emo/ndhc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
9338aa37c2
ndhc/ndhc.8

172 lines
7.9 KiB
Groff
Raw Normal View History

Update the manpage a bit.
2022-02-12 23:27:10 +05:30
.TH NDHC 8 2022-02-12 Linux "Linux Administrator's Manual"
Initial commit.
2010-11-12 14:32:18 +05:30
.SH NAME
Update the manpage a bit.
2022-02-12 23:27:10 +05:30
ndhc \- secure DHCPv4 client
Initial commit.
2010-11-12 14:32:18 +05:30
.SH SYNOPSIS
.B ndhc
.RI [ OPTION ]...
.SH DESCRIPTION
Update the manpage a bit.
2022-02-12 23:27:10 +05:30
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.
Initial commit.
2010-11-12 14:32:18 +05:30
.SH OPTIONS
.TP
Update the manual page.
2014-04-15 01:22:39 +05:30
.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
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
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.
Initial commit.
2010-11-12 14:32:18 +05:30
.TP
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
.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.
Initial commit.
2010-11-12 14:32:18 +05:30
.TP
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
.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'.
Initial commit.
2010-11-12 14:32:18 +05:30
.TP
Update the man page and correct some formatting errors.
2015-02-13 05:33:09 +05:30
.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
Support running an executable file when a new lease is acquired. If no 'script-file = SCRIPTFILE' is specified in the configuration file and if no '-X SCRIPTFILE' or '--script-file SCRIPTFILE' command argument is provided, then this functionality is entirely inactive and no associated subprocess is spawned. Otherwise, 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. The privsep channel communicates that the script should be run by simply writing a newline; anything else will result in ndhc terminating itself. Before the recommended way to update system state after a change in lease information was to run the fcactus program and watch the associated leasefile for the interface for modification; now no external program is needed for this job.
2022-02-24 11:22:26 +05:30
to it using fanotify() or inotify() on Linux.
Initial commit.
2010-11-12 14:32:18 +05:30
.TP
.BI \-i\ INTERFACE ,\ \-\-interface= INTERFACE
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
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'.
Initial commit.
2010-11-12 14:32:18 +05:30
.TP
Update the man page and correct some formatting errors.
2015-02-13 05:33:09 +05:30
.BI \-n ,\ \-\-now
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
Exit with failure if a lease cannot be obtained. Useful for some init scripts.
Initial commit.
2010-11-12 14:32:18 +05:30
.TP
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
.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.
Initial commit.
2010-11-12 14:32:18 +05:30
.TP
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
.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
Merge ifchd into ndhc. Rather than function as entirely separate daemons, ndhc will fork off an ifchd child that it will communicate with via pipes rather than by connecting to a SO_PEERCRED AF_UNIX socket. The advantages include: 1. Simpler configuration. Much easier for users and packagers to set up. 2. Drastically less complex code for the ifch functionality. More code is removed than added, and the result is a lot less complex. 3. Potentially better security. The ifch can only service the parent ndhc process, and it is restricted to issuing modifications to the single interface that ndhc manages. 4. Less memory used on systems that allow overcommit. The downsides: 1. Possibly more memory used on systems that run multiple ndhcs and use strict commit limits. At the same time, use netlink rather than ioctls so that the interface ip, subnet, and broadcast address can be set simultaneously. This change reduces the netlink notification spam greatly. The current code builds but isn't yet complete. Subsequent commits will flesh things out and polish out some remaining issues.
2014-03-10 10:22:56 +05:30
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.
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
.TP
.BI \-C\ CHROOTDIR ,\ \-\-chroot= CHROOTDIR
This option specifies the directory to which ndhc should confine itself via
Merge ifchd into ndhc. Rather than function as entirely separate daemons, ndhc will fork off an ifchd child that it will communicate with via pipes rather than by connecting to a SO_PEERCRED AF_UNIX socket. The advantages include: 1. Simpler configuration. Much easier for users and packagers to set up. 2. Drastically less complex code for the ifch functionality. More code is removed than added, and the result is a lot less complex. 3. Potentially better security. The ifch can only service the parent ndhc process, and it is restricted to issuing modifications to the single interface that ndhc manages. 4. Less memory used on systems that allow overcommit. The downsides: 1. Possibly more memory used on systems that run multiple ndhcs and use strict commit limits. At the same time, use netlink rather than ioctls so that the interface ip, subnet, and broadcast address can be set simultaneously. This change reduces the netlink notification spam greatly. The current code builds but isn't yet complete. Subsequent commits will flesh things out and polish out some remaining issues.
2014-03-10 10:22:56 +05:30
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.
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
.TP
Update the man page and correct some formatting errors.
2015-02-13 05:33:09 +05:30
.BI \-d ,\ \-\-relentless\-defense
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
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
Merge ifchd into ndhc. Rather than function as entirely separate daemons, ndhc will fork off an ifchd child that it will communicate with via pipes rather than by connecting to a SO_PEERCRED AF_UNIX socket. The advantages include: 1. Simpler configuration. Much easier for users and packagers to set up. 2. Drastically less complex code for the ifch functionality. More code is removed than added, and the result is a lot less complex. 3. Potentially better security. The ifch can only service the parent ndhc process, and it is restricted to issuing modifications to the single interface that ndhc manages. 4. Less memory used on systems that allow overcommit. The downsides: 1. Possibly more memory used on systems that run multiple ndhcs and use strict commit limits. At the same time, use netlink rather than ioctls so that the interface ip, subnet, and broadcast address can be set simultaneously. This change reduces the netlink notification spam greatly. The current code builds but isn't yet complete. Subsequent commits will flesh things out and polish out some remaining issues.
2014-03-10 10:22:56 +05:30
.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.
Update the man page and correct some formatting errors.
2015-02-13 05:33:09 +05:30
.TP
.BI \-w\ TIMEMS ,\ \-\-arp\-probe\-wait= TIMEMS
Merge ifchd into ndhc. Rather than function as entirely separate daemons, ndhc will fork off an ifchd child that it will communicate with via pipes rather than by connecting to a SO_PEERCRED AF_UNIX socket. The advantages include: 1. Simpler configuration. Much easier for users and packagers to set up. 2. Drastically less complex code for the ifch functionality. More code is removed than added, and the result is a lot less complex. 3. Potentially better security. The ifch can only service the parent ndhc process, and it is restricted to issuing modifications to the single interface that ndhc manages. 4. Less memory used on systems that allow overcommit. The downsides: 1. Possibly more memory used on systems that run multiple ndhcs and use strict commit limits. At the same time, use netlink rather than ioctls so that the interface ip, subnet, and broadcast address can be set simultaneously. This change reduces the netlink notification spam greatly. The current code builds but isn't yet complete. Subsequent commits will flesh things out and polish out some remaining issues.
2014-03-10 10:22:56 +05:30
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
Update the man page and correct some formatting errors.
2015-02-13 05:33:09 +05:30
.BI \-W\ NUMPROBES ,\ \-\-arp\-probe\-num= NUMPROBES
Merge ifchd into ndhc. Rather than function as entirely separate daemons, ndhc will fork off an ifchd child that it will communicate with via pipes rather than by connecting to a SO_PEERCRED AF_UNIX socket. The advantages include: 1. Simpler configuration. Much easier for users and packagers to set up. 2. Drastically less complex code for the ifch functionality. More code is removed than added, and the result is a lot less complex. 3. Potentially better security. The ifch can only service the parent ndhc process, and it is restricted to issuing modifications to the single interface that ndhc manages. 4. Less memory used on systems that allow overcommit. The downsides: 1. Possibly more memory used on systems that run multiple ndhcs and use strict commit limits. At the same time, use netlink rather than ioctls so that the interface ip, subnet, and broadcast address can be set simultaneously. This change reduces the netlink notification spam greatly. The current code builds but isn't yet complete. Subsequent commits will flesh things out and polish out some remaining issues.
2014-03-10 10:22:56 +05:30
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
Update the man page and correct some formatting errors.
2015-02-13 05:33:09 +05:30
.BI \-m\ TIMEMS ,\ \-\-arp\-probe\-min= TIMEMS
Merge ifchd into ndhc. Rather than function as entirely separate daemons, ndhc will fork off an ifchd child that it will communicate with via pipes rather than by connecting to a SO_PEERCRED AF_UNIX socket. The advantages include: 1. Simpler configuration. Much easier for users and packagers to set up. 2. Drastically less complex code for the ifch functionality. More code is removed than added, and the result is a lot less complex. 3. Potentially better security. The ifch can only service the parent ndhc process, and it is restricted to issuing modifications to the single interface that ndhc manages. 4. Less memory used on systems that allow overcommit. The downsides: 1. Possibly more memory used on systems that run multiple ndhcs and use strict commit limits. At the same time, use netlink rather than ioctls so that the interface ip, subnet, and broadcast address can be set simultaneously. This change reduces the netlink notification spam greatly. The current code builds but isn't yet complete. Subsequent commits will flesh things out and polish out some remaining issues.
2014-03-10 10:22:56 +05:30
Adjusts the minimum time that we wait between sending probe packets. The
default is 1000ms. The precise inter-probe wait time is randomized.
.TP
Update the man page and correct some formatting errors.
2015-02-13 05:33:09 +05:30
.BI \-M\ TIMEMS ,\ \-\-arp\-probe\-max= TIMEMS
Merge ifchd into ndhc. Rather than function as entirely separate daemons, ndhc will fork off an ifchd child that it will communicate with via pipes rather than by connecting to a SO_PEERCRED AF_UNIX socket. The advantages include: 1. Simpler configuration. Much easier for users and packagers to set up. 2. Drastically less complex code for the ifch functionality. More code is removed than added, and the result is a lot less complex. 3. Potentially better security. The ifch can only service the parent ndhc process, and it is restricted to issuing modifications to the single interface that ndhc manages. 4. Less memory used on systems that allow overcommit. The downsides: 1. Possibly more memory used on systems that run multiple ndhcs and use strict commit limits. At the same time, use netlink rather than ioctls so that the interface ip, subnet, and broadcast address can be set simultaneously. This change reduces the netlink notification spam greatly. The current code builds but isn't yet complete. Subsequent commits will flesh things out and polish out some remaining issues.
2014-03-10 10:22:56 +05:30
Adjusts the maximum time that we wait between sending probe packets. The
default is 2000ms. The precise inter-probe wait time is randomized.
.TP
Update the man page and correct some formatting errors.
2015-02-13 05:33:09 +05:30
.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
rfkill: Add support for reacting to radio kill switch events. In order for this to work, the correct rfkill index must be specified with the rfkill-idx option. It might be possible to auto-detect the corresponding rfkill-idx option, but I'm not sure if there's a guaranteed mapping between rfkill name and interface name, as it seems that rfkills should represent phy devices and not wlan devices. The rfkill indexes can be found by checking /sys/class/rfkill/rfkill<IDX>.
2015-02-14 02:55:36 +05:30
.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
Support s6 service startup notification 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'.
2022-02-13 03:01:39 +05:30
.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
Support running an executable file when a new lease is acquired. If no 'script-file = SCRIPTFILE' is specified in the configuration file and if no '-X SCRIPTFILE' or '--script-file SCRIPTFILE' command argument is provided, then this functionality is entirely inactive and no associated subprocess is spawned. Otherwise, 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. The privsep channel communicates that the script should be run by simply writing a newline; anything else will result in ndhc terminating itself. Before the recommended way to update system state after a change in lease information was to run the fcactus program and watch the associated leasefile for the interface for modification; now no external program is needed for this job.
2022-02-24 11:22:26 +05:30
.BI \-X\ SCRIPTFILE ,\ \-\-script\-file= SCRIPTFILE
If set, ndhc will spawn a subprocess that has the exclusive job of executing
the specified executable file immediately after a new lease is acquired. This
script file will run as root and will not be chrooted. It will be provided a
sanitized environment that has no inputs from the dhcp state. If this
parameter is not provided, then the ndhc-scriptd subprocess will not exist.
This facility is intended to be used for updating firewall/nat rules or similar
tasks.
.TP
Update the man page and correct some formatting errors.
2015-02-13 05:33:09 +05:30
.BI \-v ,\ \-\-version
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
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.
Initial commit.
2010-11-12 14:32:18 +05:30
.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
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
This signal causes
Initial commit.
2010-11-12 14:32:18 +05:30
.B ndhc
Write man pages and do some misc cleanup on old files. Add more documentation to the README.
2011-07-13 12:00:10 +05:30
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).
Reference in New Issue Copy Permalink