dhcpcd: Update to Version 5.2.10

Change-Id: I949331c7aad91b125decd51da4041983d3a352bc
Signed-off-by: Dmitry Shmidt <dimitrysh@google.com>

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