ndhc/src/ndhc.8

.TH NDHC 8 2012-07-20 Linux "Linux Administrator's Manual"
.SH NAME
ndhc \- secure DHCP client
.SH SYNOPSIS
.B ndhc
.RI [ OPTION ]...
.SH DESCRIPTION
The ndhc client negotiates a lease with the DHCP server and informs ifchd of
the change when it is obtained or lost.  It also 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.  It requires a cooperating
ifchd server to properly perform its duties.
.SH OPTIONS
.TP
.BI \-c\  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
.BR \-b ,\  \-\-background
Immediately fork into the background, even before obtaining a lease.
.TP
.BI \-p\  PIDFILE ,\ \-\-pidfile= PIDFILE
Write the process id number of the ndhc process into the specified file name.
The default is to not write the process id number into any file at all.
.TP
.BI \-l\  LEASEFILE ,\ \-\-leasefile= LEASEFILE
Write the IP address of the currently held DHCP lease into the specified file
name.  The default is to not write the lease IP address into any file at all.
This file can be quite useful for reacting to changes in IP address -- one
can listen for changes to it using fanotify() or inotify() on Linux.
.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
.BR \-n ,\  \-\-now
Exit with failure if a lease cannot be obtained.  Useful for some init scripts.
.TP
.BR \-q ,\  \-\-quit
Exit after obtaining a lease.  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
.BR \-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
.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.
.BR \-S ,\  \-\-seccomp\-enforce
Enforces seccomp-based syscall whitelisting.  System calls that ndhc and
ndhc-ifch are not expected to need are prohibited from being called if this
flag is set.  The lists of allowed syscalls are hardcoded, and attempts
to call a non-listed syscall will result in the ndhc process being
terminated.  As systems vary, it cannot be guaranteed that these system
call lists are accurate for your system, and thus seccomp filtering will
not be used unless this flag is set.
.TP
.BR \-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
.BR \-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
.BR \-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
.BR \-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
.BR \-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).