1 '\" te
2 .\" Copyright (c) 1992-1996 Competitive Automation, Inc. Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright (c) 2016-2017, Chris Fraire <cfraire@me.com>.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
5 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
6 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH DHCPAGENT 1M "Jun 30, 2017"
8 .SH NAME
9 dhcpagent \- Dynamic Host Configuration Protocol (DHCP) client daemon
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBdhcpagent\fR [\fB-a\fR] [ \fB-d\fR \fIn\fR] [\fB-f\fR] [\fB-v\fR]
14 .fi
15
16 .SH DESCRIPTION
17 .LP
18 \fBdhcpagent\fR implements the client half of the Dynamic Host Configuration
19 Protocol \fB(DHCP)\fR for machines running illumos software.
20 .sp
21 .LP
22 The \fBdhcpagent\fR daemon obtains configuration parameters for the client
23 (local) machine's network interfaces from a \fBDHCP\fR server. These parameters
24 may include a lease on an \fBIP\fR address, which gives the client machine use
25 of the address for the period of the lease, which may be infinite. If the
26 client wishes to use the \fBIP\fR address for a period longer than the lease,
27 it must negotiate an extension using \fBDHCP\fR. For this reason,
28 \fBdhcpagent\fR must run as a daemon, terminating only when the client machine
29 powers down.
30 .sp
31 .LP
32 For IPv4, the \fBdhcpagent\fR daemon is controlled through \fBipadm\fR(1M),
33 \fBnwamcfg\fR(1M), or \fBifconfig\fR(1M) in much the same way that the
34 \fBinit\fR(1M) daemon is controlled by \fBtelinit\fR(1M). \fBdhcpagent\fR can
35 be invoked as a user process, albeit one requiring root privileges, but this is
36 not necessary, as \fBipadm\fR(1M), \fBnwamcfg\fR(1M), or \fBifconfig\fR(1M)
37 will start \fBdhcpagent\fR automatically.
124
125 .sp
126 .LP
127 All DHCP packets sent by \fBdhcpagent\fR include a vendor class identifier (RFC
128 2132, option code 60; RFC 3315, option code 16). This identifier is the same as
129 the platform name returned by the \fBuname\fR \fB-i\fR command, except:
130 .RS +4
131 .TP
132 .ie t \(bu
133 .el o
134 Any commas in the platform name are changed to periods.
135 .RE
136 .RS +4
137 .TP
138 .ie t \(bu
139 .el o
140 If the name does not start with a stock symbol and a comma, it is automatically
141 prefixed with \fBSUNW\fR.
142 .RE
143 .SS "Messages"
144 .LP
145 The \fBdhcpagent\fR daemon writes information and error messages in five
146 categories:
147 .sp
148 .ne 2
149 .na
150 \fBcritical\fR
151 .ad
152 .sp .6
153 .RS 4n
154 Critical messages indicate severe conditions that prevent proper operation.
155 .RE
156
157 .sp
158 .ne 2
159 .na
160 \fBerrors\fR
161 .ad
162 .sp .6
163 .RS 4n
164 Error messages are important, sometimes unrecoverable events due to resource
194 .sp
195 .ne 2
196 .na
197 \fBdebug\fR
198 .ad
199 .sp .6
200 .RS 4n
201 Debugging messages, which may be generated at two different levels of
202 verbosity, are chiefly of benefit to persons having access to source code, but
203 may be useful as well in debugging difficult DHCP configuration problems.
204 Debugging messages are only generated when using the \fB-d\fR option.
205 .RE
206
207 .sp
208 .LP
209 When \fBdhcpagent\fR is run without the \fB-f\fR option, all messages are sent
210 to the system logger \fBsyslog\fR(3C) at the appropriate matching priority and
211 with a facility identifier \fBLOG_DAEMON\fR. When \fBdhcpagent\fR is run with
212 the \fB-f\fR option, all messages are directed to standard error.
213 .SS "DHCP Events and User-Defined Actions"
214 .LP
215 If an executable (binary or script) is placed at \fB/etc/dhcp/eventhook\fR, the
216 \fBdhcpagent\fR daemon will automatically run that program when any of the
217 following events occur:
218 .sp
219 .ne 2
220 .na
221 \fB\fBBOUND\fR and \fBBOUND6\fR\fR
222 .ad
223 .sp .6
224 .RS 4n
225 These events occur during interface configuration. The event program is invoked
226 when \fBdhcpagent\fR receives the DHCPv4 ACK or DHCPv6 Reply message from the
227 DHCP server for the lease request of an address, indicating successful initial
228 configuration of the interface. (See also the \fBINFORM\fR and \fBINFORM6\fR
229 events, which occur when configuration parameters are obtained without address
230 leases.)
231 .RE
232
233 .sp
234 .ne 2
334 event name, respectively. For DHCPv6, the interface name is the name of the
335 physical interface.
336 .sp
337 .LP
338 The event program can use the \fBdhcpinfo\fR(1) utility to fetch additional
339 information about the interface. While the event program is invoked on every
340 event defined above, it can ignore those events in which it is not interested.
341 The event program runs with the same privileges and environment as
342 \fBdhcpagent\fR itself, except that \fBstdin\fR, \fBstdout\fR, and \fBstderr\fR
343 are redirected to \fB/dev/null\fR. Note that this means that the event program
344 runs with root privileges.
345 .sp
346 .LP
347 If an invocation of the event program does not exit after 55 seconds, it is
348 sent a \fBSIGTERM\fR signal. If does not exit within the next three seconds, it
349 is terminated by a \fBSIGKILL\fR signal.
350 .sp
351 .LP
352 See EXAMPLES for an example event program.
353 .SH OPTIONS
354 .LP
355 The following options are supported:
356 .sp
357 .ne 2
358 .na
359 \fB\fB-a\fR\fR
360 .ad
361 .sp .6
362 .RS 4n
363 Adopt a configured IPv4 interface. This option is for use with diskless
364 \fBDHCP\fR clients. In the case of diskless \fBDHCP\fR, \fBDHCP\fR has already
365 been performed on the network interface providing the operating system image
366 prior to running \fBdhcpagent\fR. This option instructs the agent to take over
367 control of the interface. It is intended primarily for use in boot scripts.
368 .sp
369 The effect of this option depends on whether the interface is being adopted.
370 .sp
371 If the interface is being adopted, the following conditions apply:
372 .sp
373 \fBdhcpagent\fR uses the client id specified in
374 \fB/chosen\fR:\fI<client_id>\fR, as published by the PROM or as specified on a
409 .na
410 \fB\fB-f\fR\fR
411 .ad
412 .sp .6
413 .RS 4n
414 Run in the foreground instead of as a daemon process. When this option is used,
415 messages are sent to standard error instead of to \fBsyslog\fR(3C).
416 .RE
417
418 .sp
419 .ne 2
420 .na
421 \fB\fB-v\fR\fR
422 .ad
423 .sp .6
424 .RS 4n
425 Provide verbose output useful for debugging site configuration problems.
426 .RE
427
428 .SH EXAMPLES
429 .LP
430 \fBExample 1 \fRExample Event Program
431 .sp
432 .LP
433 The following script is stored in the file \fB/etc/dhcp/eventhook\fR, owned by
434 root with a mode of 755. It is invoked upon the occurrence of the events listed
435 in the file.
436
437 .sp
438 .in +2
439 .nf
440 #!/bin/sh
441
442 (
443 echo "Interface name: " $1
444 echo "Event: " $2
445
446 case $2 in
447 "BOUND")
448 echo "Address acquired from server "\e
449 `/sbin/dhcpinfo -i $1 ServerID`
450 ;;
451 "BOUND6")
452 echo "Addresses acquired from server " \e
453 `/sbin/dhcpinfo -v6 -i $1 ServerID`
454 ;;
455 "EXTEND")
456 echo "Lease extended for " \e
457 `sbin/dhcpinfo -i $1 LeaseTim`" seconds"
458 ;;
459 "EXTEND6")
460 echo "New lease information obtained on $i"
461 ;;
462 "EXPIRE" | "DROP" | "RELEASE")
463 ;;
464
465 esac
466 ) >/var/run/dhcp_eventhook_output 2>&1
467 .fi
468 .in -2
469 .sp
470
471 .sp
472 .LP
473 Note the redirection of stdout and stderr to a file.
474
475 .SH FILES
476 .ne 2
477 .na
806 where \fIhostname\fR is the host name requested.
807 .sp
808 This option works with DHCPv4 only.
809 .sp
810 Default value of this option is \fIyes\fR.
811 .RE
812
813 .RE
814
815 .sp
816 .ne 2
817 .na
818 \fB\fB/etc/dhcp/eventhook\fR\fR
819 .ad
820 .sp .6
821 .RS 4n
822 Location of a DHCP event program.
823 .RE
824
825 .SH ATTRIBUTES
826 .LP
827 See \fBattributes\fR(5) for descriptions of the following attributes:
828 .sp
829
830 .sp
831 .TS
832 box;
833 c | c
834 l | l .
835 ATTRIBUTE TYPE ATTRIBUTE VALUE
836 _
837 Interface Stability Committed
838 .TE
839
840 .SH SEE ALSO
841 .LP
842 \fBdhcpinfo\fR(1), \fBifconfig\fR(1M), \fBinit\fR(1M), \fBin.mpathd\fR(1M),
843 \fBin.ndpd\fR(1M), \fBipadm\fR(1M), \fBnwamcfg\fR(1M), \fBsyslog\fR(3C),
844 \fBnodename\fR(4), \fBresolv.conf\fR(4), \fBattributes\fR(5), \fBdhcp\fR(5)
845 .sp
846 .LP
847 \fI\fR
848 .sp
849 .LP
850 Croft, B. and Gilmore, J. \fIRFC 951, Bootstrap Protocol (BOOTP)\fR, Network
851 Working Group, September 1985.
852 .sp
853 .LP
854 Droms, R. \fIRFC 2131, Dynamic Host Configuration Protocol\fR, Network Working
855 Group, March 1997.
856 .sp
857 .LP
858 Lemon, T. and B. Sommerfeld. \fIRFC 4361, Node-specific Client Identifiers for
859 Dynamic Host Configuration Protocol Version Four (DHCPv4)\fR. Nominum and Sun
860 Microsystems. February 2006.
861 .sp
862 .LP
863 Droms, R. \fIRFC 3315, Dynamic Host Configuration Protocol for IPv6
864 (DHCPv6)\fR. Cisco Systems. July 2003.
865 .SH NOTES
866 .LP
867 The \fBdhcpagent\fR daemon can be used on IPv4 logical interfaces, just as with
868 physical interfaces. When used on a logical interface, the daemon automatically
869 constructs a Client ID value based on the DUID and IAID values, according to
870 RFC 4361. The \fB/etc/default/dhcpagent\fR \fBCLIENT_ID\fR value, if any,
871 overrides this automatic identifier.
872 .sp
873 .LP
874 As with physical IPv4 interfaces, the \fB/etc/hostname.hme0:1\fR and
875 \fB/etc/dhcp.hme0:1\fR files must also be created in order for \fBhme0:1\fR to
876 be automatically plumbed and configured at boot. In addition, unlike physical
877 IPv4 interfaces, \fBdhcpagent\fR does not add or remove default routes
878 associated with logical interfaces.
879 .sp
880 .LP
881 DHCP can be performed on IPMP IP interfaces to acquire and maintain IPMP data
882 addresses. Because an IPMP IP interface has no hardware address, the daemon
883 automatically constructs a Client ID using the same approach described above
884 for IPv4 logical interfaces. In addition, the lack of a hardware address means
885 the daemon must set the "broadcast" flag in all \fBDISCOVER\fR and
886 \fBREQUEST\fR messages on IPMP IP interfaces. Some DHCP servers may refuse such
|
1 '\" te
2 .\" Copyright (c) 1992-1996 Competitive Automation, Inc. Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright (c) 2016-2017, Chris Fraire <cfraire@me.com>.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
5 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
6 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH DHCPAGENT 1M "Feb 13, 2020"
8 .SH NAME
9 dhcpagent \- Dynamic Host Configuration Protocol (DHCP) client daemon
10 .SH SYNOPSIS
11 .nf
12 \fBdhcpagent\fR [\fB-a\fR] [ \fB-d\fR \fIn\fR] [\fB-f\fR] [\fB-v\fR]
13 .fi
14
15 .SH DESCRIPTION
16 \fBdhcpagent\fR implements the client half of the Dynamic Host Configuration
17 Protocol \fB(DHCP)\fR for machines running illumos software.
18 .sp
19 .LP
20 The \fBdhcpagent\fR daemon obtains configuration parameters for the client
21 (local) machine's network interfaces from a \fBDHCP\fR server. These parameters
22 may include a lease on an \fBIP\fR address, which gives the client machine use
23 of the address for the period of the lease, which may be infinite. If the
24 client wishes to use the \fBIP\fR address for a period longer than the lease,
25 it must negotiate an extension using \fBDHCP\fR. For this reason,
26 \fBdhcpagent\fR must run as a daemon, terminating only when the client machine
27 powers down.
28 .sp
29 .LP
30 For IPv4, the \fBdhcpagent\fR daemon is controlled through \fBipadm\fR(1M),
31 \fBnwamcfg\fR(1M), or \fBifconfig\fR(1M) in much the same way that the
32 \fBinit\fR(1M) daemon is controlled by \fBtelinit\fR(1M). \fBdhcpagent\fR can
33 be invoked as a user process, albeit one requiring root privileges, but this is
34 not necessary, as \fBipadm\fR(1M), \fBnwamcfg\fR(1M), or \fBifconfig\fR(1M)
35 will start \fBdhcpagent\fR automatically.
122
123 .sp
124 .LP
125 All DHCP packets sent by \fBdhcpagent\fR include a vendor class identifier (RFC
126 2132, option code 60; RFC 3315, option code 16). This identifier is the same as
127 the platform name returned by the \fBuname\fR \fB-i\fR command, except:
128 .RS +4
129 .TP
130 .ie t \(bu
131 .el o
132 Any commas in the platform name are changed to periods.
133 .RE
134 .RS +4
135 .TP
136 .ie t \(bu
137 .el o
138 If the name does not start with a stock symbol and a comma, it is automatically
139 prefixed with \fBSUNW\fR.
140 .RE
141 .SS "Messages"
142 The \fBdhcpagent\fR daemon writes information and error messages in five
143 categories:
144 .sp
145 .ne 2
146 .na
147 \fBcritical\fR
148 .ad
149 .sp .6
150 .RS 4n
151 Critical messages indicate severe conditions that prevent proper operation.
152 .RE
153
154 .sp
155 .ne 2
156 .na
157 \fBerrors\fR
158 .ad
159 .sp .6
160 .RS 4n
161 Error messages are important, sometimes unrecoverable events due to resource
191 .sp
192 .ne 2
193 .na
194 \fBdebug\fR
195 .ad
196 .sp .6
197 .RS 4n
198 Debugging messages, which may be generated at two different levels of
199 verbosity, are chiefly of benefit to persons having access to source code, but
200 may be useful as well in debugging difficult DHCP configuration problems.
201 Debugging messages are only generated when using the \fB-d\fR option.
202 .RE
203
204 .sp
205 .LP
206 When \fBdhcpagent\fR is run without the \fB-f\fR option, all messages are sent
207 to the system logger \fBsyslog\fR(3C) at the appropriate matching priority and
208 with a facility identifier \fBLOG_DAEMON\fR. When \fBdhcpagent\fR is run with
209 the \fB-f\fR option, all messages are directed to standard error.
210 .SS "DHCP Events and User-Defined Actions"
211 If an executable (binary or script) is placed at \fB/etc/dhcp/eventhook\fR, the
212 \fBdhcpagent\fR daemon will automatically run that program when any of the
213 following events occur:
214 .sp
215 .ne 2
216 .na
217 \fB\fBBOUND\fR and \fBBOUND6\fR\fR
218 .ad
219 .sp .6
220 .RS 4n
221 These events occur during interface configuration. The event program is invoked
222 when \fBdhcpagent\fR receives the DHCPv4 ACK or DHCPv6 Reply message from the
223 DHCP server for the lease request of an address, indicating successful initial
224 configuration of the interface. (See also the \fBINFORM\fR and \fBINFORM6\fR
225 events, which occur when configuration parameters are obtained without address
226 leases.)
227 .RE
228
229 .sp
230 .ne 2
330 event name, respectively. For DHCPv6, the interface name is the name of the
331 physical interface.
332 .sp
333 .LP
334 The event program can use the \fBdhcpinfo\fR(1) utility to fetch additional
335 information about the interface. While the event program is invoked on every
336 event defined above, it can ignore those events in which it is not interested.
337 The event program runs with the same privileges and environment as
338 \fBdhcpagent\fR itself, except that \fBstdin\fR, \fBstdout\fR, and \fBstderr\fR
339 are redirected to \fB/dev/null\fR. Note that this means that the event program
340 runs with root privileges.
341 .sp
342 .LP
343 If an invocation of the event program does not exit after 55 seconds, it is
344 sent a \fBSIGTERM\fR signal. If does not exit within the next three seconds, it
345 is terminated by a \fBSIGKILL\fR signal.
346 .sp
347 .LP
348 See EXAMPLES for an example event program.
349 .SH OPTIONS
350 The following options are supported:
351 .sp
352 .ne 2
353 .na
354 \fB\fB-a\fR\fR
355 .ad
356 .sp .6
357 .RS 4n
358 Adopt a configured IPv4 interface. This option is for use with diskless
359 \fBDHCP\fR clients. In the case of diskless \fBDHCP\fR, \fBDHCP\fR has already
360 been performed on the network interface providing the operating system image
361 prior to running \fBdhcpagent\fR. This option instructs the agent to take over
362 control of the interface. It is intended primarily for use in boot scripts.
363 .sp
364 The effect of this option depends on whether the interface is being adopted.
365 .sp
366 If the interface is being adopted, the following conditions apply:
367 .sp
368 \fBdhcpagent\fR uses the client id specified in
369 \fB/chosen\fR:\fI<client_id>\fR, as published by the PROM or as specified on a
404 .na
405 \fB\fB-f\fR\fR
406 .ad
407 .sp .6
408 .RS 4n
409 Run in the foreground instead of as a daemon process. When this option is used,
410 messages are sent to standard error instead of to \fBsyslog\fR(3C).
411 .RE
412
413 .sp
414 .ne 2
415 .na
416 \fB\fB-v\fR\fR
417 .ad
418 .sp .6
419 .RS 4n
420 Provide verbose output useful for debugging site configuration problems.
421 .RE
422
423 .SH EXAMPLES
424 \fBExample 1 \fRExample Event Program
425 .sp
426 .LP
427 The following script is stored in the file \fB/etc/dhcp/eventhook\fR, owned by
428 root with a mode of 755. It is invoked upon the occurrence of the events listed
429 in the file.
430
431 .sp
432 .in +2
433 .nf
434 #!/bin/sh
435
436 (
437 echo "Interface name: " $1
438 echo "Event: " $2
439
440 case $2 in
441 "BOUND")
442 echo "Address acquired from server "\e
443 `/sbin/dhcpinfo -i $1 ServerID`
444 ;;
445 "BOUND6")
446 echo "Addresses acquired from server " \e
447 `/sbin/dhcpinfo -v6 -i $1 ServerID`
448 ;;
449 "EXTEND")
450 echo "Lease extended for " \e
451 `/sbin/dhcpinfo -i $1 LeaseTim`" seconds"
452 ;;
453 "EXTEND6")
454 echo "New lease information obtained on $i"
455 ;;
456 "EXPIRE" | "DROP" | "RELEASE")
457 ;;
458
459 esac
460 ) >/var/run/dhcp_eventhook_output 2>&1
461 .fi
462 .in -2
463 .sp
464
465 .sp
466 .LP
467 Note the redirection of stdout and stderr to a file.
468
469 .SH FILES
470 .ne 2
471 .na
800 where \fIhostname\fR is the host name requested.
801 .sp
802 This option works with DHCPv4 only.
803 .sp
804 Default value of this option is \fIyes\fR.
805 .RE
806
807 .RE
808
809 .sp
810 .ne 2
811 .na
812 \fB\fB/etc/dhcp/eventhook\fR\fR
813 .ad
814 .sp .6
815 .RS 4n
816 Location of a DHCP event program.
817 .RE
818
819 .SH ATTRIBUTES
820 See \fBattributes\fR(5) for descriptions of the following attributes:
821 .sp
822
823 .sp
824 .TS
825 box;
826 c | c
827 l | l .
828 ATTRIBUTE TYPE ATTRIBUTE VALUE
829 _
830 Interface Stability Committed
831 .TE
832
833 .SH SEE ALSO
834 \fBdhcpinfo\fR(1), \fBifconfig\fR(1M), \fBinit\fR(1M), \fBin.mpathd\fR(1M),
835 \fBin.ndpd\fR(1M), \fBipadm\fR(1M), \fBnwamcfg\fR(1M), \fBsyslog\fR(3C),
836 \fBnodename\fR(4), \fBresolv.conf\fR(4), \fBattributes\fR(5), \fBdhcp\fR(5)
837 .sp
838 .LP
839 \fI\fR
840 .sp
841 .LP
842 Croft, B. and Gilmore, J. \fIRFC 951, Bootstrap Protocol (BOOTP)\fR, Network
843 Working Group, September 1985.
844 .sp
845 .LP
846 Droms, R. \fIRFC 2131, Dynamic Host Configuration Protocol\fR, Network Working
847 Group, March 1997.
848 .sp
849 .LP
850 Lemon, T. and B. Sommerfeld. \fIRFC 4361, Node-specific Client Identifiers for
851 Dynamic Host Configuration Protocol Version Four (DHCPv4)\fR. Nominum and Sun
852 Microsystems. February 2006.
853 .sp
854 .LP
855 Droms, R. \fIRFC 3315, Dynamic Host Configuration Protocol for IPv6
856 (DHCPv6)\fR. Cisco Systems. July 2003.
857 .SH NOTES
858 The \fBdhcpagent\fR daemon can be used on IPv4 logical interfaces, just as with
859 physical interfaces. When used on a logical interface, the daemon automatically
860 constructs a Client ID value based on the DUID and IAID values, according to
861 RFC 4361. The \fB/etc/default/dhcpagent\fR \fBCLIENT_ID\fR value, if any,
862 overrides this automatic identifier.
863 .sp
864 .LP
865 As with physical IPv4 interfaces, the \fB/etc/hostname.hme0:1\fR and
866 \fB/etc/dhcp.hme0:1\fR files must also be created in order for \fBhme0:1\fR to
867 be automatically plumbed and configured at boot. In addition, unlike physical
868 IPv4 interfaces, \fBdhcpagent\fR does not add or remove default routes
869 associated with logical interfaces.
870 .sp
871 .LP
872 DHCP can be performed on IPMP IP interfaces to acquire and maintain IPMP data
873 addresses. Because an IPMP IP interface has no hardware address, the daemon
874 automatically constructs a Client ID using the same approach described above
875 for IPv4 logical interfaces. In addition, the lack of a hardware address means
876 the daemon must set the "broadcast" flag in all \fBDISCOVER\fR and
877 \fBREQUEST\fR messages on IPMP IP interfaces. Some DHCP servers may refuse such
|