From: Roy Marples Date: Thu, 17 Jan 2008 14:16:13 +0000 (+0000) Subject: Re-write the man page using the mdoc format. X-Git-Tag: v3.2.3~83 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1c4ba5d89abcd587b0bd5da524632ae5987cd092;p=thirdparty%2Fdhcpcd.git Re-write the man page using the mdoc format. --- diff --git a/Makefile b/Makefile index 33024d41..22901a36 100644 --- a/Makefile +++ b/Makefile @@ -12,9 +12,6 @@ CLEANFILES= version.h dhcpcd.8 BINDIR= ${PREFIX}/sbin -# Needed for crappy Linux headers :/ -CSTD= gnu99 - MK= mk include ${MK}/os.mk include ${MK}/cc.mk @@ -32,4 +29,4 @@ version.h: echo "#define VERSION \"${VERSION}\""> version.h dhcpcd.8: dhcpcd.8.in - sed 's:%%INFODIR%%:${INFOD}:g' dhcpcd.8.in > dhcpcd.8 + sed 's:@PREFIX@:${PREFIX}:g; s:@INFODIR@:${INFOD}:g' $< > $@ diff --git a/dhcpcd.8.in b/dhcpcd.8.in index 48983664..37167ec5 100644 --- a/dhcpcd.8.in +++ b/dhcpcd.8.in @@ -1,399 +1,356 @@ -.TH DHCPCD 8 "18 Jul 2007" "dhcpcd 3.1" -.SH NAME -dhcpcd \- DHCP client daemon -.SH SYNOPSIS -dhcpcd -\%[\-dknpAEGHMLNRSTY] -\%[\-c\ script] -\%[\-h\ hostname] -\%[\-i\ vendorClassID] -\%[\-l\ leasetime] -\%[\-m\ metric] -\%[\-r\ ipaddr] -\%[\-s\ ipaddr[/cidr]] -\%[\-t\ timeout] -\%[\-u\ userClass] -\%[\-F\ none | ptr | both ] -\%[\-I\ clientID ] -\%[interface] -.SH DESCRIPTION -.B dhcpcd +.\" Copyright 2006-2008 Roy Marples +.\" All rights reserved +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd Jan 17, 2008 +.Dt DHCPCD 8 SMM +.Sh NAME +.Nm dhcpcd +.Nd an RFC2131 compliant DHCP client +.Sh SYNOPSIS +.Nm +.Op Fl dknpAEGHMLNRSTY +.Op Fl c , -script Ar script +.Op Fl h , -hostname Ar hostname +.Op Fl i , -classid Ar classid +.Op Fl l , -leasetime Ar seconds +.Op Fl m , -metric Ar metric +.Op Fl r , -request Ar address +.Op Fl t , -timeout Ar seconds +.Op Fl u , -userclass Ar class +.Op Fl F , -fqdn Ar FQDN +.Op Fl I , -clientid Ar clientid +.Ar interface +.Nm +.Fl k , -release +.Ar interface +.Nm +.Fl x , -exit +.Ar interface +.Sh DESCRIPTION +.Nm is an implementation of the DHCP client specified in -.B RFC 2131. - -It gets the host information (IP address, netmask, broadcast address, -etc.) from a DHCP server and configures the network interface of the -machine on which it is running. It also tries to renew the lease time -according to -.B RFC 2131. - -If -.B dhcpcd -fails to get a lease then we attempt Dynamic Configuration of IPv4 -Link-Local Addresses unless the -.B \-L -option is given. - -.SH OPTIONS -.TP -.BI interface -Specifies the network interface name (eth0, eth1, etc.). -.TP -.BI \-c \ script -.B dhcpcd -will try to execute -.I script -instead of the default script -.I /etc/dhcpcd.sh -every time it configures or brings down the interface. See the -description of -.I dhcpcd.sh -script in -.B FILES -section below. -.TP -.BI \-d -Echos debugging and information messages to the console. -Subsequent debug options stop \fBdhcpcd\fR from daemonising. -.TP -.BI \-h \ hostname -specifies a string used for the hostname option field when -.B dhcpcd -sends DHCP messages. Some DHCP servers, notably those used by -@Home Networks, require the hostname option -field containing a specific string in the DHCP messages from clients. -When combined with the -F switch, specifies the string used for the -FQDN option field instead of the hostname option field. -We send the current hostname by default. To send no hostname, use -h ''. -.TP -.BI \-i \ vendorClassID -Specifies the vendor class identifier string. The default is dhcpcd-. -.TP -.BI \-k -Sends -.B SIGHUP -signal to the -.B dhcpcd -process associated with the specified interface if one is currently running. If -.B dhcpcd -receives -.B SIGHUP -it will send -.B DHCP_RELEASE -message to the server and destroy dhcpcd cache. In a case -.B dhcpcd -receives -.B SIGTERM -which is normally used by -.B shutdown(8) -when rebooting the system -.B dhcpcd -will not send -.B DHCP_RELEASE -and will not destroy cache. When system boots -.B dhcpcd -will use cache to request the same IP address -from DHCP server which was assigned before the -system went down. (see also -.B -p -) -.TP -.BI \-l \ leasetime -Specifies (in seconds) the recommended lease time to the server. (Note -that the server can override this value if it sees fit). This value is -used in the -.B DHCP_DISCOVER -message. Use -1 for an infinite lease time. We don't request a specific -lease time by default. If we do not receive a lease time in the -.B DHCP_OFFER -message then we default to 1 hour. -.TP -.BI \-m \ metric -Routes will be added with the given metric. The default is 0. -On some systems such as FreeBSD the interface is given the metric. -.TP -.BI \-n -Sends -.B SIGALRM -signal to the -.B dhcpcd -process that is currently running which -forces -.B dhcpcd -to try to renew the lease. If dhcpcd is not running, the flag -is ignored and -.B dhcpcd -follows the normal startup procedure. -.TP -.BI \-p -Stops -.B dhcpcd -from removing the interface configuration when it is terminated with the -.B SIGTERM -signal. This is useful when a host is running with an NFS-mounted root -filesystem over an interface controlled by DHCP. It should not be used -except in those circumstances, since if -.B dhcp -is stopped it can no longer down an interface at the end of its -lease period when the lease is not renewed. -.TP -.BI \-r \ ipaddr -Sends -.B DHCP_REQUEST -message requesting to lease IP address ipaddr. -The ipaddr parameter must be in the form xxx.xxx.xxx.xxx. -If we are not given an ipaddr then we try to use the first one assigned -to the interface if present, otherwise the last address we leased for the -interface, otherwise we return an error. -This effectively doubles the timeout period, as if we fail to get -this IP address then we enter the INIT state and try to get any -IP address. -.TP -.BI \-s \ ipaddr[/cidr] -Exactly like \fB-r\fR, but sends DHCP_INFORM instead. This requires the -interface to be configured with the ipaddr/cidr first. -When we DHCP_INFORM, we don't request or respect any lease times. -However, we do re-inform by the lease time specified by -.BI \-l -if given. -.TP -.BI \-t \ timeout -Specifies (in seconds ) for how long -.B dhcpcd -will try to get an IP address. The default is 20 seconds. -.B dhcpcd -will not fork into background until it gets a valid IP address -in which case dhcpcd will return 0 to the parent process. -In a case -.B dhcpcd -times out before receiving a valid IP address from DHCP server -.B dhcpcd -will return exit code 1 to the parent process. Setting the timeout to -zero disables it: dhcp will keep trying forever to get a lease, and if -the lease is lost, it will try forever to get another. -.TP -.BI \-u \ userClass -Tags the DHCP message with the specified user class. DHCP servers can use -these fields to send back different information instead of grouping by -fixed hardware addresses. You can specify more than one user class, but the -total length must be less than 255 characters, -1 character for each user -class. -.TP -.BI \-x -Sends -.B SIGTERM -signal to the -.B dhcpcd -process associated with the specified interface if one is currently running. If -.B dhcpcd -receives -.B SIGTERM -it will stop running, de-configure the interface and exit. -(see also -.B -k +.Rs +.%T "RFC 2131" +.Re +.Nm +gets the host information +.Po +IP address, routes, etc +.Pc +from a DHCP server and configures the network +.Ar interface +of the +machine on which it is running. +.Nm +will then write DNS information to +.Xr resolvconf 8 , +if available, otherwise directly to +.Pa /etc/resolv.conf . +.Nm +will also configure +.Pa /etc/yp.conf and -.B -p -) -.TP -.BI \-A -Don't do an -.B ARP -check on the IP address. -.TP -.BI \-E -Will read -.I %%INFODIR%%/dhcpcd-.info -file and use last known good lease if -.B dhcpcd -is unable to reach the DHCP server and the lease has not expired. -This puts \fBdhcpcd\fR into the BOUND or REBINDING state depending on -how long the lease has until expiry. -.TP -.BI \-F \ none | ptr | both -Forces -.B dhcpcd -to request the DHCP server update the DNS using the FQDN option -instead of the Hostname option. The name used by this option -is specified with the \fB-h\fP switch, which must be present. If -the \fB-h\fP switch is not present, the FQDN option is ignored. -The name should be fully qualified, although servers usually -accept a simple name. -.I both -requests that the DHCP server update both the A and PTR -records in the DNS. -.I ptr -requests that the DHCP server updates only the PTR record in -the DNS. -.I none -requests that the DHCP server perform no updates. -.B dhcpcd -does not perform any DNS update, even when the server is -requested to perform no updates. This can be easily -implemented outside the client; all the necessary -information is recorded in the -.I %%INFODIR%%/dhcpcd-.info -file. -.TP -.BI \-G -Prevents -.B dhcpcd -from installing default routes provided by DHCP server. -.TP -.BI \-H -Forces -.B dhcpcd -to set hostname of the host to the hostname option supplied by DHCP server. -By default -.B dhcpcd -will NOT set hostname of the host to the hostname option -received from DHCP server unless the current hostname is blank, (none) or -localhost. If no hostname is returned by the DHCP server then we attempt -to lookup the hostname via DNS. -More -H's control what we do with the FQDN returned by DNS. -.IP -.BI \-H -set hostname to the full FQDN -.br -.BI \-HH -strip the domain if it matches a given domain in our DHCP message -.br -.BI \-HHH -strip the domain regardless -.br -.BI \-HHHH -force hostname lookup even if given a hostname in our DHCP message -.br -.BI \-HHHHH -same as above, but strip the domain if it matches -.br -.BI \-HHHHHH -same as above, but strip the domain regardless -.TP -.BI \-I \ clientID -Specifies the client identifier string. If not specified then -.B dhcpcd -will attempt to create a client identifier according to \fBRFC 4361\fR -and store the DUID part in -.I %%INFODIR%%/dhcpcd.duid\fR, otherwise -.B dhcpcd -uses the MAC address of the network interface. If \fB-I\fR is not given -an option then we use the MAC address of the network interface. -.TP -.BI \-L -Prevents dhcpcd from probing for IPV4LL addresses. IPV4LL is otherwise -known as ZeroConf or APIPA and is \fBRFC 3927\fR. -.TP -.BI \-M -Prevents -.B dhcpcd -from setting the \fIMTU\fR provided by the DHCP server. -.TP -.BI \-N -Prevents -.B dhcpcd -from replacing -.I /etc/ntp.conf -.TP -.BI \-R -Prevents -.B dhcpcd -from replacing -.I /etc/resolv.conf -or using resolvconf. -.TP -.BI \-S -Makes -.B dhcpcd -request Microsoft CSR option 249 as well as the normal CSR option 121. -Subsquent -.BI \-S -options disable the requesting of the normal CSR if the dhcp message returned -is too big. -Ideally, DHCP servers should start responding to option 121 so -that users don't have to deal with this mess. -.TP -.BI \-T -dhcpcd sends out a DHCP_DISCOVER message and then prints the values returned to -stdout. It does not configure the interface or touch the .info files. -.TP -.BI \-Y -Prevents -.B dhcpcd -from replacing -.I /etc/yp.conf - -.SH FILES -.TP -.BI /etc/dhcpcd.sh -script file, which -.B dhcpcd -will try to execute whenever it configures or brings down the interface. The -path to this executable script can be changed with -.I \-c \ script +.Pa /etc/ntpd.conf +with NIS and NTP information if the DHCP server provided them. +If those file contents changed, then +.Nm +will also attempt to restart the respective services to notify them of the +change. +If the hostname is currenly blank, (null) or localhost then +.Nm +will set the hostname to the one supplied by the DHCP server, or look it up +in DNS if none supplied. +.Nm +then daemonises and waits for the lease renewal time to lapse. +Then it attempts to renew its lease and reconfigure if the new lease changes. +.Ss Local Link configuration +If +.Nm +failed to obtain a lease, it will probe for a valid IPv4LL address +.Po +aka Zerconf, aka APIPA +.Pc . +Once obtained it will probe every 10 seconds or so for a DHCP server to get a +proper address. +.Pp +Even when +.Nm +obtains a proper lease, it will still add a Local Link route +.Po +165.254.0.0/16 +.Pc +so that the host can communicate with clients using these addresses. +.Pp +When using IPv4LL, +.Nm +will always succeed and return a 0 exit code. To disable this behaviour, you +can use the +.Fl L , -noipv4ll option. -.B dhcpcd -passes 3 parameters to -.I dhcpcd.sh -script: -.TP -.I dhcpcd.sh infofile [up | down | new] -The first parameter infofile is the path to a file containing all DHCP -information we have. The second parameter value -.I up | down | new -mean the interface has been brought up with the same IP address as before ("up"), or -with the new IP address ("new"), or the interface has been brought down ("down"). -.TP -.BI /etc/resolv.conf -file created by -.B dhcpcd -when the client receives DNS and domain name options. -If resolvconf is present on the system then we send the data to it instead -of overwriting resolv.conf -.TP -.BI /etc/yp.conf -file created by -.B dhcpcd -when the client receives NIS options. -.TP -.BI /etc/ntp.conf -file created by -.B dhcpcd -when the client receives NTP options. -.TP -.BI /var/run/dhcpcd-.pid -file containing the process id of -.B dhcpcd. -The word -.I -is actually replaced with the network interface name like -.I eth0 -to which -.B dhcpcd -is attached. -.TP -.BI %%INFODIR%%/dhcpcd.duid -file containing the generated DUID for dhcpcd to use. -.TP -.BI %%INFODIR%%/dhcpcd-.info -file containing information provided by the DHCP server than can be used in -shell scripts. -.SH SEE ALSO -.LP -.I Dynamic Host Configuration Protocol, -RFC 2131 -.LP -.I DHCP Options and BOOTP Vendor Extensions, -RFC 2132 -.LP -.I Dynamic Configuration of IPv4 Link-Local Addresses, -RFC 3927 -.LP -.I DHCP FQDN Option specification, -RFC 4702 - -.SH BUGS -Please report them to http://bugs.marples.name -.PD 0 - -.SH AUTHORS -Roy Marples +.Ss Hooking into DHCP events +.Nm +will run @PREFIX@/etc/dhcpcd.sh, or the script specified by the +.Fl c , -script +option. It will set $1 to a shell compatible file that holds various +configuration settings obtained from the DHCP server and $2 to either +up, down or new depending on the state of +.Nm . +.Nm +ignores the exist code of the script. +.Ss Fine tuning +You can fine tune the behaviour of +.Nm +with the following options :- +.Bl -tag -width indent +.It Fl d , -debug +Echos debug and informational messages to the console. +Subsequent debug options stop +.Nm +from daemonising. +.It Fl h , -hostname Ar hostname +By default, +.Nm +will send the current hostname to the DHCP server so it can register in DNS. +You can use this option to specify the +.Ar hostname +sent, or an empty string to +stop any +.Ar hostname +from being sent. +.It Fl i , -classid Ar classid +Override the DHCP vendor +.Ar classid +field we send. The default is +dhcpcd-. +.It Fl k , -release +This causes an existing +.Nm +process running on the +.Ar interface +to release it's lease, deconfigure the +.Ar interface +and then exit. +.It Fl l , -leasetime Ar seconds +Request a specific lease time in +.Ar seconds . +By default +.Nm +does not request any lease time and leaves the it in the hands of the +DHCP server. +.It Fl m , -metric Ar metric +Added routes will use the +.Ar metric +on systems where this is supported +.Po +presently only Linux +.Pc . +Route metrics allow the addition of routes to the same destination across +different interfaces, the lower the metric the more it is preferred. +.It Fl n , -renew +Notifies an existing +.Nm +process running on the +.Ar interface +to renew it's lease. If +.Nm +is not running, then it starts up as normal. +.It Fl p , -persistent +.Nm +normally deconfigures the +.Ar interface +and configuration when it exits. +Sometimes, this isn't desirable if for example you have root mounted over NFS. +You can use this option to stop this from happening. +.It Fl r , -request Op Ar address +.Nm +normally sends a DHCP Broadcast to find servers to offer an address. +.Nm +will then request the address used. You can use this option to skip the +broadcast step and just request an +.Ar address . +The downside is if you request +an +.Ar address +the DHCP server does not know about or the DHCP server is not +authorative, it will remain silent. In this situation, we go back to the init +state and broadcast again. +If no +.Ar address +is given then we use the first address currently assigned to the +.Ar interface . +.It Fl s , -inform Op Ar address Op / Ar cidr +Behaves exactly like +.Fl r , -request +as above, but sends a DHCP inform instead of a request. This requires the +interface to be configured first. This does not get a lease as such, just +notifies the DHCP server of the +.Ar address +we are using. +.It Fl t , -timeout Ar seconds +Timeout after +.Ar seconds , +instead of the default 20. +A setting of 0 +.Ar seconds +causes +.Nm +to wait forever to get a lease. +.It Fl u , -userclass Ar class +Tags the DHCP message with the userclass +.Ar class . +DHCP servers use this give memebers of the class DHCP options other than the +default, without having to know things like hardware address or hostname. +.If Fl F , -fqdn Ar fqdn +Requests that the DHCP server updates DNS using FQDN instead of just a +hostname. Valid values for +.Ar fqdn +are none, ptr and both. +.Nm +dhcpcd itself never does any DNS updates. +.It Fl H , --sethostname +Forces +.Nm +to set the hostname as supplied by the DHCP server. Because some OS's and users +prefer to have just the hostname, or the full FQDN more +.Fl H , --sethostname +options change the behaviour. Below is the list of possible combinations:- +.Bl -tag -width indent +.It Fl H +set the hostname to the full FQDN. +.It Fl HH +strip the domain if it matches the dns domain. +.It Fl HHH +strip the domain regardless. +.It Fl HHHH +same as +.Fl H +but force hostname lookup via DNS. +.It Fl HHHHH +same as above, but strip the domain if it matches the dns domain. +.It Fl HHHHHH +same as above, but strip the domain regardless. +.El +.It Fl I , -clientid Ar clientid +Send a +.Ar clientid +as a client identifier string. +.It Fl S, -mscsr +Microsoft have their own code for Classless Static Routes +.Po +RFC 3442 +.Pc . +You can use this option to request this as well as the normal CSR. Another +instace of this option only requests the Microsoft CSR to prevent DHCP message +over-running its maximum size. DHCP server administrators should update their +CSR code from the Microsoft specific one to the RFC compliant one as the +content is fully compatible. +.El +.Ss Restriciting behaviour +.Nm +will try to do as much as it can by default. However, there are sometimes +situations where you don't want the things to be configured exactly how the +the DHCP server wants. Here are some option that deal with turning these bits +off. +.Bl -tag -width indent +.It Fl A , -noarp +Don't request and claim the address by ARP. +.It Fl G , -nogateway +Don't set any default routes. +.It Fl L , -noipv4ll +Don't use IPv4LL at all. +.It Fl M , -nomtu +Don't set the MTU of the +.Ar interface . +.It Fl N , -nontp +Don't touch +.Pa /etc/ntp.d.conf +or restart the ntp service. +.It Fl R , -nodns +Don't send DNS information to resolvconf or touch +.Pa /etc/resolv.conf . +.It Fl T , -test +On receipt of discover messages, simply print the contents of the DHCP +message to the console. +.Nm +will not configure the +.Ar interface , +touch any files or restart any services. +.It Fl Y , -nonis +Don't touch +.Pa /etc/yp.conf +or restart the ypbind service. +.El +.Sh NOTES +Because +.Nm +supports InfiniBand, we put a Node-specific Client Identifier or DUID in the +ClientID field. This is required by RFC 4390. It's also required for DHCP IPv6 +which +.Nm +should support one day. However, some DHCP servers have no idea what a DUID is +and reject the message. Of course, RFC 2131 allowed for future use of the +ClientID field and this is a future use. Also, some DHCP server configurations +require an ethernet hardware address of 6 hexacdecimal numbers in the ClientID +which is the default behaviour of most other DHCP clients. If your DHCP server +is as desribed above, you should fix the server, or if that is not an option +you can compile DUID support out of +.Nm +or use the +.Fl I , -clientid Ar clientid +option and set +.Ar clientid +to ''. +.Pp +ISC dhcpd, dnsmasq, udhcpd and Microsoft DHCP server 2003 default configurations +work just fine with the default +.Nm +configuration. +.Pp +.Nm +requires a Berkley Packet Filter, or BPF device on BSD based systems and a +Packet Socket on Linux based systems. +.Sh FILES +.Bl -ohang +.It Pa @PREFIX@/etc/dhcpcd.sh +Bourne shell script that is run when we configure or deconfigure an interface. +.It Pa @INFODIR@/dhcpcd.duid +Text file that holds the DUID used to identify the host. +.It Pa @INFODIR@/dhcpcd- Ns Ar interface Ns .info +Bourne shell file that holds the DHCP values used in configuring the interface. +This path is passed as the first argument to +.Pa @PREFIX@/etc/dhcpcd.sh . +.El +.Sh SEE ALSO +.Xr ntp 1 , +.Xr resolv.conf 5 , +.Xr resolvconf 8 , +.Xr yp.conf 5 , +.Xr ypbind 8 +.Sh STANDARDS +RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3397, RFC 3442, RFC 3927, +RFC 4361, RFC 4390, RFC 4702. +.Sh AUTHORS +.An "Roy Marples" Aq roy@marples.name +.Sh BUGS +Please report them to http://bugs.marples.name