Create/improve netcore initial setup documentation

[guilhem]

Hi,

I have some difficulties bootstrapping service :/

netcore doesn't seems to create etcd directories if not present.
Even If I'm creating this (with etcdctl) and even if I set with flags setZone etc, I always have problem:

Configuration failed: This host has not been assigned to a zone.

I really don't know how to initialize etcd...
I may have missed something :)

[emmaly]

With regard to that specific error, the way netcore knows which zone to place a running instance of netcore is by its hostname. For example for a machine running netcore with a FQDN of netcore.seattle.example.com, a set of values need to exist for these keys:

/config/netcore.seattle.example.com/dhcpip
/config/netcore.seattle.example.com/dhcpnic
/config/netcore.seattle.example.com/zone

You can see here that the instance is therefore defined at /config/$FQDNHOSTNAME.

The dhcpip value would be the IP address that the DHCP service will use (such as 192.168.1.1, without a netmask/CIDR). It needs to be an IP that properly routes to the server hosting netcore.

The dhcpnic value would be the name of the network device (such as eth0) that DHCP will listen on for DHCP lease requests. If you don't want this instance to run DHCP service, just omit this key altogether.

The zone value would be the name of the zone that the netcore instance is in, such as seattle. You can have many instances within a single zone, though right now netcore doesn't automatically handle multiple instances running concurrently within a single zone. That means that DHCP might issue multiple IP addresses per inbound lease request, for example. It is intended to support this use in the future for failover, load balancing, or otherwise. For DNS service, it doesn't matter how many instances you have running.

A zone is an area that is defined by the DHCP subnet it serves. For example, for the seattle zone, it might be serving addresses out of the 192.168.0.0/22 subnet (which is 192.168.0.1 through 192.168.3.254), but restricted to a pool of 192.168.2.0/23 (which is 192.168.2.1 through 192.168.3.254). One would configure it with these keys:

/config/seattle/dhcpleaseduration
/config/seattle/dhcpsubnet
/config/seattle/domain
/config/seattle/gateway
/config/seattle/ntp
/config/seattle/subnet

You can see here that the zone is therefore defined at /config/$ZONE.

dhcpleaseduration is the lease duration value, in seconds. 600 would be 10 minutes, for example. The default is 12 hours if this is unset.

dhcpsubnet is the address pool. This does not need to match the local network's subnet. In the example above, this value would be set to 192.168.2.0/23 to issue addresses between 192.168.2.1 through 192.168.3.254.

domain is the search domain and domain suffix to register in within netcore DNS. I think it can be empty. You might want to set it to something like seattle.example.com. A machine that claims to be acme would then get an FQDN (via DHCP) of acme.seattle.example.com and that name would be automatically registered in netcore DNS as expected.

gateway is the default gateway to advertise. If this is missing, DHCP users won't be able to get out of your subnet. This is just an IP address, no CIDR/netmask. Something like 192.168.0.1.

ntp is the NTP server you want to advertise. If you don't have one, just omit it. We put an IP address in this value. I don't recall if this can be an FQDN instead.

subnet is the network subnet. This doesn't need to match the DHCP address pool (dhcpsubnet) above. In the above example, this would be set to 192.168.0.0/22 which is a range of 192.168.0.1 through 192.168.3.254.

Right now we're in the middle of some pretty serious refactoring to clean up the way the system works as well as how/where values are stored within etcd.

Obviously one of the things we need to deal with is the documentation, or the lack thereof.

[emmaly]

I've renamed the issue to be more correct. I want to leave this issue open until we've improved the state of our documentation. If the above is insufficient to get you going, please let me know so I can help.