2fb16567f1
This can be enabled via the s6-notify configure option; see http://www.skarnet.org/software/s6/notifywhenup.html for details. ndhc will signal that it is ready when the first valid lease is obtained. Programs dependent on a working network interface can then simply use s6-wait on the associated ndhc service dir. A typical command line option assuming the s6 service directory notification-fd contains '3' would be '--s6-notify 3', and a typical configure file option would be 's6-notify 3'.
164 lines
7.5 KiB
Groff
164 lines
7.5 KiB
Groff
.TH NDHC 8 2022-02-12 Linux "Linux Administrator's Manual"
|
|
.SH NAME
|
|
ndhc \- secure DHCPv4 client
|
|
.SH SYNOPSIS
|
|
.B ndhc
|
|
.RI [ OPTION ]...
|
|
.SH DESCRIPTION
|
|
The ndhc client negotiates a lease with the DHCPv4 server. Once a lease is
|
|
obtained, it then defends the assigned IP address against hostile imposters and
|
|
requests a new lease if it detects that the interface has been connected to a
|
|
new network.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BI \-c\ CONFIGFILE ,\ \-\-config= CONFIGFILE
|
|
Read configuration information from the specified file. The format of
|
|
configuration options is a simple 'option = value' for each line. The
|
|
names of the options are exactly the same as for command line options.
|
|
.TP
|
|
.BI \-I\ CLIENTID ,\ \-\-clientid= CLIENTID
|
|
Specifies the client identifier that will be sent to the remote server. This
|
|
can be any (reasonably sized, <64byte or so) text string, or an ethernet
|
|
MAC address in a form similar to 'aa:bb:cc:dd:ee:ff'. ndhc is smart enough
|
|
to recognize MAC addresses. ISP DHCP servers commonly check the value of this
|
|
field before providing a lease. The default value is the MAC address of
|
|
the network interface to which ndhc is bound.
|
|
.TP
|
|
.BI \-h\ HOSTNAME ,\ \-\-hostname= HOSTNAME
|
|
Send the specified client hostname to the remote DHCP server. This option
|
|
should not be necessary in most instances, but may perhaps be useful for odd
|
|
DHCP servers that perform some kind of authentication against the hostname
|
|
option field. The default is to send no hostname option at all.
|
|
.TP
|
|
.BI \-v\ VENDORID ,\ \-\-vendorid= VENDORID
|
|
Send the specified vendor identification string to the remote DHCP server.
|
|
This option should not be necessary in most instances, but may perhaps be
|
|
useful for odd DHCP servers that perform some kind of authentication against
|
|
the vendor id option field. The default is to send the string 'ndhc'.
|
|
.TP
|
|
.BI \-s\ STATEDIR ,\ \-\-state\-dir= STATEDIR
|
|
Specifies the directory where the DHCP state associated with the given
|
|
interface will be stored. Such state will include the leased IP, the
|
|
IAID, and the DUID. The file representing the leased IP can be quite
|
|
useful for reacting to changes in IP address -- one can listen for changes
|
|
to it using fanotify() or inotify() on Linux. The 'fcactus' program
|
|
written by the ndhc author is designed to perform this task.
|
|
.TP
|
|
.BI \-i\ INTERFACE ,\ \-\-interface= INTERFACE
|
|
Act as a DHCP client for the specified interface. A single ndhc daemon can
|
|
only act as a DHCP client for a single interface. Specify the interface it
|
|
should use by name. The default is to listen on 'eth0'.
|
|
.TP
|
|
.BI \-n ,\ \-\-now
|
|
Exit with failure if a lease cannot be obtained. Useful for some init scripts.
|
|
.TP
|
|
.BI \-r\ IP ,\ \-\-request= IP
|
|
Request the specified IP address from the remote DHCP server. The DHCP server
|
|
has no obligation to provide us with this IP, but it may acquiesce to the
|
|
request if it would not conflict with another host.
|
|
.TP
|
|
.BI \-u\ USER ,\ \-\-user= USER
|
|
This option specifies the user name or user id that ndhc will change to after
|
|
startup. ndhc will also change its group to match the default group of this
|
|
user.
|
|
.TP
|
|
.BI \-U\ USER ,\ \-\-ifch\-user= USER
|
|
This option specifies the user name or user id that ndhc-ifch will change to
|
|
after startup. ndhc-ifch will also change its group to match the default group
|
|
of this user.
|
|
.TP
|
|
.BI \-C\ CHROOTDIR ,\ \-\-chroot= CHROOTDIR
|
|
This option specifies the directory to which ndhc should confine itself via
|
|
chroot() after startup. This directory should have access to dev/urandom and
|
|
dev/null. For logging to work, a dev/log socket or device should also exist.
|
|
.TP
|
|
.BI \-d ,\ \-\-relentless\-defense
|
|
If specified, ndhc will never back down in defending the IP address that it
|
|
has been assigned by the remote DHCP server. This behavior should not be
|
|
specified for average machines, but is useful for servers or routers where
|
|
the IP address of the machine must remain fixed for proper operation.
|
|
.TP
|
|
.BI \-R\ RESOLVCONF ,\ \-\-resolv\-conf= RESOLVCONF
|
|
Specifies the path to the system resolv.conf. This file will typically be in
|
|
/etc/resolv.conf. If this option is specified, ndhc will update the contents
|
|
of this file to match the DNS servers specified by the remote DHCP server. If
|
|
this option is not specified, ifchd will never change the system DNS resolution
|
|
configuration.
|
|
.TP
|
|
.BI \-H ,\ \-\-dhcp\-set\-hostname
|
|
If specified, ndhc will update the system host name in response to any
|
|
hostname option field provided by a remote DHCP server on the request of
|
|
a ndhc client. If this option is not specified, ndhc will never change
|
|
the system hostname.
|
|
.TP
|
|
.BI \-w\ TIMEMS ,\ \-\-arp\-probe\-wait= TIMEMS
|
|
Adjusts the time that we wait for an ARP response when checking to see if
|
|
our lease assignment is already taken by an existing host. Default is
|
|
1000ms.
|
|
.TP
|
|
.BI \-W\ NUMPROBES ,\ \-\-arp\-probe\-num= NUMPROBES
|
|
Adjusts the number of ARP packets that we send when probing for collisions
|
|
with an existing host that is using our assigned IP. Once we have sent
|
|
the specified number of probe packets with no response, ndhc is willing
|
|
to believe that there is no colliding host. Default number is 3 probes.
|
|
.TP
|
|
.BI \-m\ TIMEMS ,\ \-\-arp\-probe\-min= TIMEMS
|
|
Adjusts the minimum time that we wait between sending probe packets. The
|
|
default is 1000ms. The precise inter-probe wait time is randomized.
|
|
.TP
|
|
.BI \-M\ TIMEMS ,\ \-\-arp\-probe\-max= TIMEMS
|
|
Adjusts the maximum time that we wait between sending probe packets. The
|
|
default is 2000ms. The precise inter-probe wait time is randomized.
|
|
.TP
|
|
.BI \-t\ GWMETRIC ,\ \-\-gw\-metric= GWMETRIC
|
|
Specifies the routing metric for the default gateway entry. Defaults to
|
|
0 if not specified. Higher values will de-prioritize the route entry.
|
|
.TP
|
|
.BI \-K\ RFKILLIDX ,\ \-\-rfkill\-idx= RFKILLIDX
|
|
If set, specifies the rfkill device index that corresponds to this interface.
|
|
ndhc will then listen for matching radio frequency kill switch events
|
|
and will bring the interface up and down in reaction to the events.
|
|
The rfkill devices can be found in /sys/class/rfkill/rfkill<RFKILLIDX>.
|
|
It may be useful to check the contents of the 'name' file within this
|
|
directory to determine the correct device index. In any event, if
|
|
an rfkill-idx parameter is specified, ndhc will print messages for any
|
|
rfkill events that it sees, so it should not be too difficult to locate
|
|
the proper rfkill device by checking the logs after hitting the switch.
|
|
.TP
|
|
.BI \-N\ NOTIFY_FDNUM ,\ \-\-s6\-notify= NOTIFY_FDNUM
|
|
If set, specifies the file descriptor number that will have a '\n' written to
|
|
and closed when the first DHCP lease is bound. This option should be used when
|
|
ndhc is run under a s6 supervisor that implements service startup
|
|
notifications.
|
|
.TP
|
|
.BI \-v ,\ \-\-version
|
|
Display the ndhc version number.
|
|
.SH SIGNALS
|
|
It is not necessary to sleep between sending signals, as signals received are
|
|
processed sequentially in the order they are received.
|
|
.B ndhc
|
|
responds to the following signals:
|
|
.TP
|
|
.B SIGUSR1
|
|
This signal causes
|
|
.B ndhc
|
|
to renew the current lease or, if it does not have one, obtain a
|
|
new lease.
|
|
.TP
|
|
.B SIGUSR2
|
|
This signal causes
|
|
.B ndhc
|
|
to release the current lease and go to sleep until it receives a SIGUSR1.
|
|
.SH NOTES
|
|
ndhc will seed its random number generator (used for generating xids)
|
|
by reading /dev/urandom. If you have a lot of embedded systems on the same
|
|
network, with no entropy, you can either seed /dev/urandom by a method of
|
|
your own, or doing the following on startup:
|
|
|
|
ifconfig eth0 > /dev/urandom
|
|
|
|
in order to seed /dev/urandom with some data (mac address) unique to your
|
|
system. If reading /dev/urandom fails, ndhc will fall back to seeding with
|
|
time(0).
|
|
|