diff options
Diffstat (limited to 'dhcpcd.8.in')
| -rw-r--r-- | dhcpcd.8.in | 305 |
1 files changed, 226 insertions, 79 deletions
diff --git a/dhcpcd.8.in b/dhcpcd.8.in index d3fbebf..5993878 100644 --- a/dhcpcd.8.in +++ b/dhcpcd.8.in @@ -1,4 +1,4 @@ -.\" Copyright 2006-2008 Roy Marples +.\" Copyright (c) 2006-2010 Roy Marples .\" All rights reserved .\" .\" Redistribution and use in source and binary forms, with or without @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd November 18, 2008 +.Dd August 31, 2010 .Dt DHCPCD 8 SMM .Os .Sh NAME @@ -30,8 +30,9 @@ .Nd an RFC 2131 compliant DHCP client .Sh SYNOPSIS .Nm -.Op Fl bdknpqABDEGKLTV +.Op Fl bdgknpqwABDEGHJKLTV .Op Fl c , -script Ar script +.Op Fl e , -env Ar value .Op Fl f , -config Ar file .Op Fl h , -hostname Ar hostname .Op Fl i , -vendorclassid Ar vendorclassid @@ -43,43 +44,61 @@ .Op Fl t , -timeout Ar seconds .Op Fl u , -userclass Ar class .Op Fl v , -vendor Ar code , Ar value +.Op Fl y , -reboot Ar seconds +.Op Fl z , -allowinterfaces Ar pattern .Op Fl C , -nohook Ar hook .Op Fl F , -fqdn Ar FQDN .Op Fl I , -clientid Ar clientid .Op Fl O , -nooption Ar option .Op Fl Q , -require Ar option -.Op Fl X , -blacklist Ar address -.Ar interface +.Op Fl S , -static Ar value +.Op Fl W , -whitelist Ar address Ns Op Ar /cidr +.Op Fl X , -blacklist Ar address Ns Op Ar /cidr +.Op Fl Z , -denyinterfaces Ar pattern +.Op interface +.Op ... .Nm .Fl k , -release +.Op interface +.Nm +.Fl U, -dumplease .Ar interface .Nm .Fl x , -exit -.Ar interface +.Op interface +.Nm +.Fl v , -version .Sh DESCRIPTION .Nm is an implementation of the DHCP client specified in .Li RFC 2131 . .Nm gets the host information -.Po +.Po IP address, routes, etc .Pc from a DHCP server and configures the network .Ar interface of the -machine on which it is running. +machine on which it is running. .Nm then runs the configuration script which writes DNS information to .Xr resolvconf 8 , if available, otherwise directly to .Pa /etc/resolv.conf . -If the hostname is currenly blank, (null) or localhost then +If the hostname is currently blank, (null) or localhost, or +.Va force_hostname +is YES or TRUE or 1 then .Nm sets the hostname to the one supplied by the DHCP server. .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. +It will then attempt to renew its lease and reconfigure if the new lease +changes. +.Pp +.Nm +is also an implementation of the BOOTP client specified in +.Li RFC 951 . .Ss Local Link configuration If .Nm @@ -98,6 +117,38 @@ installed which always defeats IPv4LL probing. To disable this behaviour, you can use the .Fl L , -noipv4ll option. +.Ss Multiple interfaces +If a list of interfaces are given on the command line, then +.Nm +only works with those interfaces, otherwise +.Nm +discovers available Ethernet interfaces. +If any interface reports a working carrier then +.Nm +will try and obtain a lease before forking to the background, +otherwise it will fork right away. +This behaviour can be modified with the +.Fl b , -background +and +.Fl w , -waitip +options. +.Pp +If a single interface is given then +.Nm +only works for that interface and runs as a separate instance. +The +.Fl w , -waitip +option is enabled in this instance to maintain compatibility with older +versions. +.Pp +Interfaces are preferred by carrier, DHCP lease/IPv4LL and then lowest metric. +For systems that support route metrics, each route will be tagged with the +metric, otherwise +.Nm +changes the routes to use the interface with the same route and the lowest +metric. +See options below for controlling which interfaces we allow and deny through +the use of patterns. .Ss Hooking into DHCP events .Nm runs @@ -123,7 +174,7 @@ for details on how these scripts work. .Nm currently ignores the exit code of the script. .Ss Fine tuning -You can fine tune the behaviour of +You can fine-tune the behaviour of .Nm with the following options: .Bl -tag -width indent @@ -137,25 +188,42 @@ Use this instead of the default .Pa @SCRIPT@ . .It Fl d , -debug -Echo debug and informational messages to the console. -Subsequent debug options stop +Echo debug messages to the stderr and syslog. +.It Fl e , -env Ar value +Push +.Ar value +to the environment for use in +.Xr dhcpcd-run-hooks 8 . +For example, you can force the hostname hook to always set the hostname with +.Fl e +.Va force_hostname=YES . +.It Fl g , -reconfigure +.Nm +will re-apply IP address, routing and run +.Xr dhcpcd-run-hooks 8 +for each interface. +This is useful so that a 3rd party such as PPP or VPN can change the routing +table and / or DNS, etc and then instruct +.Nm +to put things back afterwards. .Nm -from daemonising. +does not read a new configuration when this happens - you should rebind if you +need that functionality. .It Fl f , -config Ar file Specify a config to load instead of .Pa @SYSCONFDIR@/dhcpcd.conf . .Nm always processes the config file before any command line options. .It Fl h , -hostname Ar hostname -By default, -.Nm -sends the current hostname to the DHCP server so it can register in DNS. -You can use this option to specify the +Sends +.Ar hostname +to the DHCP server so it can be registered in DNS. +If .Ar hostname -sent, or an empty string to -stop any +is an empty string then the current system hostname is sent. +If .Ar hostname -from being sent. +is a FQDN (ie, contains a .) then it will be encoded as such. .It Fl i , -vendorclassid Ar vendorclassid Override the .Ar vendorclassid @@ -167,7 +235,7 @@ This causes an existing .Nm process running on the .Ar interface -to release its lease, deconfigure the +to release its lease, de-configure the .Ar interface and then exit. .Nm @@ -177,61 +245,45 @@ 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 +does not request any lease time and leaves 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. +Metrics are used to prefer an interface over another one, lowest wins. +.Nm +will supply a default metic of 200 + +.Xr if_nametoindex 3 . +An extra 100 will be added for wireless interfaces. .It Fl o , -option Ar option Request the DHCP .Ar option variable for use in .Pa @SCRIPT@ . .It Fl n , -rebind -Notifies an existing +Notifies .Nm -process running on the -.Ar interface -to rebind it's lease. -.Nm -will not re-configure itself or use any other command line arguments. -.Nm -will timeout the rebind after 30 seconds at which point the lease will be -expired and -.Nm -will enter the discovery state to obtain a new lease. -Use the -.Fl t , -timeout -option to change this. +to reload its configuration and rebind its interfaces. If .Nm is not running, then it starts up as normal. -This option used to be renew, but rebind is more accurate as we need to -broadcast the request instead of unicasting. .It Fl p , -persistent .Nm -normally deconfigures the +normally de-configures the .Ar interface and configuration when it exits. -Sometimes, this isn't desirable if for example you have root mounted over NFS. +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 DISCOVER to find servers to offer an address. .Nm then requests the address used. -You can use this option to skip the BROADCAST step and just request the +You can use this option to skip the DISCOVER phase and just request the .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. +authoritative, it will remain silent. In this situation, we go back to the init state and DISCOVER again. If no .Ar address @@ -247,7 +299,7 @@ This does not get a lease as such, just notifies the DHCP server of the in use. You should also include the optional .Ar cidr -network number in-case the address is not already configured on the interface. +network number in case the address is not already configured on the interface. .Nm remains running and pretends it has an infinite lease. .Nm @@ -268,39 +320,58 @@ 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 members of the class DHCP options other than the +DHCP servers use this to give members of the class DHCP options other than the default, without having to know things like hardware address or hostname. .It Fl v , -vendor Ar code , Ns Ar value -Add an enscapulated vendor option. +Add an encapsulated vendor option. .Ar code should be between 1 and 254 inclusive. +To add a raw vendor string, omit +.Ar code +but keep the comma. Examples. .Pp Set the vendor option 01 with an IP address. .D1 dhcpcd \-v 01,192.168.0.2 eth0 Set the vendor option 02 with a hex code. .D1 dhcpcd \-v 02,01:02:03:04:05 eth0 -Do the above and set a third option with a string and not an IP address. -.D1 dhcpcd \-v 01,192.168.0.2 \-v 02,01:02:03:04:05 \-v 03,\e"192.168.0.2\e" eth0 +Set the vendor option 03 with an IP address as a string. +.D1 dhcpcd \-v 03,\e"192.168.0.2\e" eth0 +Set un-encapsulated vendor option to hello world. +.D1 dhcpcd \-v ,"hello world" eth0 +.It Fl v , -version +Display both program version and copyright information. +.Nm +then exits before doing any configuration. +.It Fl w , -waitip +Wait for an address to be assigned before forking to the background. .It Fl x , -exit This will signal an existing .Nm process running on the .Ar interface -to deconfigure the +to de-configure the .Ar interface and exit. .Nm then waits until this process has exited. -.It Fl D , -duid +.It Fl y , -reboot Ar seconds +Allow +.Ar reboot +seconds before moving to the discover phase if we have an old lease to use. +The default is 10 seconds. +A setting of 0 seconds causes +.Nm +to skip the reboot phase and go straight into discover. +.It Fl D , -duid Generate an .Li RFC 4361 compliant clientid. -This requires persistent storage and not all DHCP servers work with it so it's -not enabled by default. +This requires persistent storage and not all DHCP servers work with it so it +is not enabled by default. .Nm -generates the DUID and stores in it -.Pa @SYSCONFDIR@/dhcpcd.duid +generates the DUID and stores it in +.Pa @SYSCONFDIR@/dhcpcd.duid . This file should not be copied to other hosts. .It Fl E , -lastlease If @@ -316,9 +387,6 @@ hostname. Valid values for .Ar fqdn are disable, none, ptr and both. -The current hostname or the hostname specified using the -.Fl h , -hostname -option must be a FQDN. .Nm itself never does any DNS updates. .Nm @@ -348,6 +416,14 @@ Quiet .Nm on the command line, only warnings and errors will be displayed. The messages are still logged though. +.It Fl z , -allowinterfaces Ar pattern +When discovering interfaces, the interface name must match +.Ar pattern +which is a space or comma separated list of patterns passed to +.Xr fnmatch 3 . +If the same interface is matched in +.Fl Z , -denyinterfaces +then it is still denied. .It Fl A , -noarp Don't request or claim the address by ARP. This also disables IPv4LL. @@ -360,10 +436,22 @@ Don't run this hook script. Matches full name, or prefixed with 2 numbers optionally ending with .Pa .sh . .Pp -So to stop dhcpcd from touching your DNS or MTU settings you would do:- +So to stop +.Nm +from touching your DNS or MTU settings you would do:- .D1 dhcpcd -C resolv.conf -C mtu eth0 .It Fl G , -nogateway Don't set any default routes. +.It Fl H , -xidhwaddr +Use the last four bytes of the hardware address as the DHCP xid instead +of a randomly generated number. +.It Fl J , -broadcast +Instructs the DHCP server to broadcast replies back to the client. +Normally this is only set for non Ethernet interfaces, +such as FireWire and InfiniBand. +In most instances, +.Nm +will set this automatically. .It Fl K , -nolink Don't receive link messages for carrier status. You should only have to use this with buggy device drivers or running @@ -379,24 +467,77 @@ configure the interface and routing. Requires the .Ar option to be present in all DHCP messages, otherwise the message is ignored. +To enforce that +.Nm +only responds to DHCP servers and not BOOTP servers, you can +.Fl Q +.Ar dhcp_message_type . +.It Fl S, -static Ar value +Configures a static +.Ar value . +If you set +.Ic ip_address +then +.Nm +will not attempt to obtain a lease and just use the value for the address with +an infinite lease time. +.Pp +Here is an example which configures a static address, routes and dns. +.D1 dhcpcd -S ip_address=192.168.0.10/24 \e +.D1 -S routers=192.168.0.1 \e +.D1 -S domain_name_servers=192.168.0.1 \e +.D1 eth0 .It Fl T, -test -On receipt of OFFER messages just call +On receipt of DHCP messages just call .Pa @SCRIPT@ -with the reason of TEST which echo's the DHCP variables found in the message +with the reason of TEST which echos the DHCP variables found in the message to the console. The interface configuration isn't touched and neither are any configuration files. +To test INFORM the interface needs to be configured with the desired address +before starting +.Nm . +.It Fl U, -dumplease Ar interface +Dumps the last lease for the +.Ar interface +to stdout. +.Ar interface +could also be a path to a DHCP wire formatted file. .It Fl V, -variables Display a list of option codes and the associated variable for use in .Xr dhcpcd-run-hooks 8 . -.It Fl X, -blacklist Ar address -Ignores all DHCP messages which have this -.Ar address -as the server ID. -This may be expanded in future releases to ignore all packets -matching either the IP or hardware -.Ar address . +Variables are prefixed with new_ and old_ unless the option number is -. +Variables without an option are part of the DHCP message and cannot be +directly requested. +.It Fl W, -whitelist Ar address Ns Op /cidr +Only accept packets from +.Ar address Ns Op /cidr . +.Fl X, -blacklist +is ignored if +.Fl W, -whitelist +is set. +.It Fl X, -blacklist Ar address Ns Op Ar /cidr +Ignore all packets from +.Ar address Ns Op Ar /cidr . +.It Fl Z , -denyinterfaces Ar pattern +When discovering interfaces, the interface name must not match +.Ar pattern +which is a space or comma separated list of patterns passed to +.Xr fnmatch 3 . .El +.Sh 3RDPARTY LINK MANAGEMENT +Some interfaces require configuration by 3rd parties, such as PPP or VPN. +When an interface configuration in +.Nm +is marked as STATIC or INFORM without an address then +.Nm +will monitor the interface until an address is added or removed from it and +act accordingly. +For point to point interfaces (like PPP), a default route to its +destination is automatically added to the configuration. +If the point to point interface if configured for INFORM, then +.Nm +unicasts INFORM to the destination, otherwise it defaults to STATIC. .Sh NOTES .Nm requires a Berkley Packet Filter, or BPF device on BSD based systems and a @@ -409,7 +550,7 @@ If you always use the same options, put them here. .It Pa @SYSCONFDIR@/dhcpcd.duid Text file that holds the DUID used to identify the host. .It Pa @SCRIPT@ -Bourne shell script that is run to configure or deconfigure an interface. +Bourne shell script that is run to configure or de-configure an interface. .It Pa @HOOKDIR@ A directory containing bourne shell scripts that are run by the above script. Each script can be disabled by using the @@ -418,6 +559,10 @@ option described above. .It Pa @DBDIR@/dhcpcd\- Ns Ar interface Ns .lease The actual DHCP message send by the server. We use this when reading the last lease and use the files mtime as when it was issued. +.It Pa /var/run/dhcpcd.pid +Stores the PID of +.Nm +running on all interfaces. .It Pa /var/run/dhcpcd\- Ns Ar interface Ns .pid Stores the PID of .Nm @@ -429,10 +574,12 @@ running on the .Xr dhcpcd-run-hooks 8 , .Xr resolv.conf 5 , .Xr resolvconf 8 , +.Xr if_nametoindex 3 , +.Xr fnmatch 3 .Sh STANDARDS -RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3396, RFC 3397, -RFC 3442, RFC 3927, RFC 4361, RFC 4390, RFC 4702. +RFC 951, RFC 1534, RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3396, +RFC 3397, RFC 3442, RFC 3927, RFC 4361, RFC 4390, RFC 4702. .Sh AUTHORS -.An Roy Marples <roy@marples.name> +.An Roy Marples Aq roy@marples.name .Sh BUGS Please report them to http://roy.marples.name/projects/dhcpcd |