emo/ndhc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation and add more configuration examples.

Browse Source
This commit is contained in:
Nicholas J. Kain 2022-03-08 12:38:27 -05:00
parent 5bca0a3d48
commit 0b53d93648
1 changed files with 51 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
README.md
View File

@ -9,11 +9,10 @@ runs with the minimal necessary privileges in order to perform its task.
Currently, ndhc consists of three subprocesses: the ndhc-master, Currently, ndhc consists of three subprocesses: the ndhc-master,
ndhc-ifch, and ndhc-sockd. ndhc-ifch, and ndhc-sockd.
ndhc-master communicates with DHCP servers and handles the vagaries of ndhc-master communicates with DHCP servers and handles the vagaries of the DHCP
the DHCP client protocol. It runs as a non-root user inside a chroot. client protocol. It runs as a non-root user inside a chroot. ndhc runs as a
ndhc runs as a normal user with no special privileges and is restricted normal user with no special privileges and is restricted to a chroot that
to a chroot that contains nothing more than a domain socket filesystem contains nothing more than a urandom device node and a null device node.
object (if using syslog), a urandom device node, and a null device node.
ndhc-ifch handles interface change requests. It listens on a unix ndhc-ifch handles interface change requests. It listens on a unix
socket for such requests. ndhc-ifch runs as a non-root user inside socket for such requests. ndhc-ifch runs as a non-root user inside
@ -137,22 +136,22 @@ Create a urandom device for ndhc to use within the jail.
# chmod a+r dev/urandom # chmod a+r dev/urandom
# chmod a+rw dev/null # chmod a+rw dev/null
``` ```
(_optional_) If you wish for logging to properly work, you will need
to properly configure your logging daemon so that it opens a domain
socket in the proper location within the jail. Since this varies
per-daemon, I cannot provide a general configuration.
At this point the jail is usable; ndhc is ready to be used. It should At this point the jail is usable; ndhc is ready to be used. It should
be invoked as the root user so that it can spawn its processes with the be invoked as the root user so that it can spawn its processes with the
proper permissions. An example of invoking ndhc: `ndhc -i wan0 -u dhcp -U dhcpifch -D dhcpsockd -C /var/lib/ndhc` proper permissions. An example of invoking ndhc: `ndhc -i wan0 -u dhcp -U dhcpifch -D dhcpsockd -C /var/lib/ndhc`
If you encounter problems, I suggest running ndhc in the foreground If a configuration file is preferred instead of command arguments, I provide an
and examining the printed output. example configuation file `examples/wan0.conf`. The associated example of
invoking ndhc with such a configuration would be `ndhc -c /etc/ndhc/wan0.conf`.
I suggest running ndhc under some sort of process If you encounter problems, I suggest running ndhc in the foreground
supervision such as [runit](http://smarden.org/runit) or and examining the printed output. ndhc logs all output to standard out
or standard error.
ndhc should be run under some sort of process supervision such as
[s6](http://www.skarnet.org/software/s6). This will allow for reliable [s6](http://www.skarnet.org/software/s6). This will allow for reliable
functioning in the case of unforseen or unrecoverable errors. functioning in the case of unforseen or unrecoverable errors. I provide
an example s6 run file `examples/s6.run`.
## Behavior Notes ## Behavior Notes
@ -160,6 +159,43 @@ ndhc does not enable updates of the local `hostname` and `resolv.conf` by
default. If you wish to enable these functions, use the `--resolve` default. If you wish to enable these functions, use the `--resolve`
(`-R`) and `--hostname` (`-H`) flags. See `ndhc --help`. (`-R`) and `--hostname` (`-H`) flags. See `ndhc --help`.
If the network interface must be up for dependent daemons to run, the `now`
configuration or `--now` command flag should be used so that ndhc will
be respawned by the process supervisor if no lease is acquired.
## Running a script when a new lease is acquired
It is common for there to be some system state that must be changed
if a network interface configuration changes; for example, on a system
providing NAT or firewalling, the NAT or firewall might need to be updated
if the associated upbound interface has a new IP address.
ndhc has the ability to run a script each time a new lease state is acquired.
The script to be run is specified either in the configuration file with
`script-file = SCRIPTFILE` or as a command argument with `--script-file
SCRIPTFILE` where SCRIPTFILE is a path to an executable file. The script will
not be run if an existing lease (acquired since the ndhc process was started)
is simply updated.
If a scriptfile is specified, ndhc will spawn a subprocess that runs as root
that has the sole job of forking off a subprocess that exec's the specified
script in a sanitized and fixed-state environment whenever a new DHCPv4 lease
is acquired.
Note that this script is provided no information about ndhc or the
DHCP state in the environment or in any argument fields; it is the
responsibility of this script to gather whatever information it needs
from either the filesystem or syscalls. This design is intended to
avoid the historical problems that are associated with dhcp clients
invoking scripts.
The path of the scriptfile cannot be changed after ndhc is initially
run; ndhc forks off the privsep script subprocess that executes scripts
after it has read the configuration file and command arguments, but
before it begins processing network data; thus, it is impossible for the
network-handling process to modify or influence the script assuming
proper OS memory protection.
## State Storage Notes ## State Storage Notes
ndhc requires a read/writable directory to store the DUID/IAID states. ndhc requires a read/writable directory to store the DUID/IAID states.