6 * Dynamic Host Configuration Protocol
10 FILE_LICENCE ( GPL2_OR_LATER );
15 #include <ipxe/list.h>
16 #include <ipxe/refcnt.h>
17 #include <ipxe/tables.h>
18 #include <ipxe/uuid.h>
19 #include <ipxe/netdevice.h>
20 #include <ipxe/uaccess.h>
26 /** BOOTP/DHCP server port */
27 #define BOOTPS_PORT 67
29 /** BOOTP/DHCP client port */
30 #define BOOTPC_PORT 68
32 /** PXE server port */
35 /** Construct a tag value for an encapsulated option
37 * This tag value can be passed to Etherboot functions when searching
38 * for DHCP options in order to search for a tag within an
39 * encapsulated options block.
41 #define DHCP_ENCAP_OPT( encapsulator, encapsulated ) \
42 ( ( (encapsulator) << 8 ) | (encapsulated) )
43 /** Extract encapsulating option block tag from encapsulated tag value */
44 #define DHCP_ENCAPSULATOR( encap_opt ) ( (encap_opt) >> 8 )
45 /** Extract encapsulated option tag from encapsulated tag value */
46 #define DHCP_ENCAPSULATED( encap_opt ) ( (encap_opt) & 0xff )
47 /** Option is encapsulated */
48 #define DHCP_IS_ENCAP_OPT( opt ) DHCP_ENCAPSULATOR( opt )
51 * @defgroup dhcpopts DHCP option tags
57 * This tag does not have a length field; it is always only a single
62 /** Minimum normal DHCP option */
63 #define DHCP_MIN_OPTION 1
66 #define DHCP_SUBNET_MASK 1
69 #define DHCP_ROUTERS 3
72 #define DHCP_DNS_SERVERS 6
75 #define DHCP_LOG_SERVERS 7
78 #define DHCP_HOST_NAME 12
81 #define DHCP_DOMAIN_NAME 15
84 #define DHCP_ROOT_PATH 17
86 /** Vendor encapsulated options */
87 #define DHCP_VENDOR_ENCAP 43
89 /** PXE boot server discovery control */
90 #define DHCP_PXE_DISCOVERY_CONTROL DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 6 )
92 /** PXE boot server discovery control bits */
93 enum dhcp_pxe_discovery_control {
94 /** Inhibit broadcast discovery */
95 PXEBS_NO_BROADCAST = 1,
96 /** Inhibit multicast discovery */
97 PXEBS_NO_MULTICAST = 2,
98 /** Accept only servers in DHCP_PXE_BOOT_SERVERS list */
99 PXEBS_NO_UNKNOWN_SERVERS = 4,
100 /** Skip discovery if filename present */
104 /** PXE boot server multicast address */
105 #define DHCP_PXE_BOOT_SERVER_MCAST DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 7 )
107 /** PXE boot servers */
108 #define DHCP_PXE_BOOT_SERVERS DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 8 )
110 /** PXE boot server */
111 struct dhcp_pxe_boot_server {
114 /** Number of IPv4 addresses */
116 /** IPv4 addresses */
117 struct in_addr ip[0];
118 } __attribute__ (( packed ));
121 #define DHCP_PXE_BOOT_MENU DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 9 )
124 struct dhcp_pxe_boot_menu {
127 /** Description length */
131 } __attribute__ (( packed ));
133 /** PXE boot menu prompt */
134 #define DHCP_PXE_BOOT_MENU_PROMPT DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 10 )
136 /** PXE boot menu prompt */
137 struct dhcp_pxe_boot_menu_prompt {
140 * A value of 0 means "time out immediately and select first
141 * boot item, without displaying the prompt". A value of 255
142 * means "display menu immediately with no timeout". Any
143 * other value means "display prompt, wait this many seconds
144 * for keypress, if key is F8, display menu, otherwise select
148 /** Prompt to press F8 */
150 } __attribute__ (( packed ));
152 /** PXE boot menu item */
153 #define DHCP_PXE_BOOT_MENU_ITEM DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 71 )
155 /** PXE boot menu item */
156 struct dhcp_pxe_boot_menu_item {
159 * This field actually identifies the specific boot server (or
160 * cluster of boot servers offering identical boot files).
168 } __attribute__ (( packed ));
170 /** Requested IP address */
171 #define DHCP_REQUESTED_ADDRESS 50
174 #define DHCP_LEASE_TIME 51
176 /** Option overloading
178 * The value of this option is the bitwise-OR of zero or more
179 * DHCP_OPTION_OVERLOAD_XXX constants.
181 #define DHCP_OPTION_OVERLOAD 52
183 /** The "file" field is overloaded to contain extra DHCP options */
184 #define DHCP_OPTION_OVERLOAD_FILE 1
186 /** The "sname" field is overloaded to contain extra DHCP options */
187 #define DHCP_OPTION_OVERLOAD_SNAME 2
189 /** DHCP message type */
190 #define DHCP_MESSAGE_TYPE 53
192 #define DHCPDISCOVER 1
194 #define DHCPREQUEST 3
195 #define DHCPDECLINE 4
198 #define DHCPRELEASE 7
201 /** DHCP server identifier */
202 #define DHCP_SERVER_IDENTIFIER 54
204 /** Parameter request list */
205 #define DHCP_PARAMETER_REQUEST_LIST 55
207 /** Maximum DHCP message size */
208 #define DHCP_MAX_MESSAGE_SIZE 57
210 /** Vendor class identifier */
211 #define DHCP_VENDOR_CLASS_ID 60
213 /** Client identifier */
214 #define DHCP_CLIENT_ID 61
216 /** Client identifier */
217 struct dhcp_client_id {
218 /** Link-layer protocol */
220 /** Link-layer address */
221 uint8_t ll_addr[MAX_LL_ADDR_LEN];
222 } __attribute__ (( packed ));
226 * This option replaces the fixed "sname" field, when that field is
227 * used to contain overloaded options.
229 #define DHCP_TFTP_SERVER_NAME 66
233 * This option replaces the fixed "file" field, when that field is
234 * used to contain overloaded options.
236 #define DHCP_BOOTFILE_NAME 67
238 /** User class identifier */
239 #define DHCP_USER_CLASS_ID 77
241 /** Client system architecture */
242 #define DHCP_CLIENT_ARCHITECTURE 93
244 /** DHCP client architecture */
245 struct dhcp_client_architecture {
247 } __attribute__ (( packed ));
249 /** DHCP client architecture values
251 * These are defined by the PXE specification and redefined by
254 enum dhcp_client_architecture_values {
256 DHCP_CLIENT_ARCHITECTURE_X86 = 0x0000,
258 DHCP_CLIENT_ARCHITECTURE_PC98 = 0x0001,
260 DHCP_CLIENT_ARCHITECTURE_IA64 = 0x0002,
262 DHCP_CLIENT_ARCHITECTURE_ALPHA = 0x0003,
264 DHCP_CLIENT_ARCHITECTURE_ARCX86 = 0x0004,
265 /** Intel Lean Client */
266 DHCP_CLIENT_ARCHITECTURE_LC = 0x0005,
268 DHCP_CLIENT_ARCHITECTURE_IA32 = 0x0006,
270 DHCP_CLIENT_ARCHITECTURE_EFI = 0x0007,
272 DHCP_CLIENT_ARCHITECTURE_XSCALE = 0x0008,
274 DHCP_CLIENT_ARCHITECTURE_X86_64 = 0x0009,
277 /** Client network device interface */
278 #define DHCP_CLIENT_NDI 94
280 /** UUID client identifier */
281 #define DHCP_CLIENT_UUID 97
283 /** UUID client identifier */
284 struct dhcp_client_uuid {
285 /** Identifier type */
289 } __attribute__ (( packed ));
291 #define DHCP_CLIENT_UUID_TYPE 0
293 /** DNS domain search list */
294 #define DHCP_DOMAIN_SEARCH 119
296 /** Etherboot-specific encapsulated options
298 * This encapsulated options field is used to contain all options
299 * specific to Etherboot (i.e. not assigned by IANA or other standards
302 #define DHCP_EB_ENCAP 175
304 /** Priority of this options block
306 * This is a signed 8-bit integer field indicating the priority of
307 * this block of options. It can be used to specify the relative
308 * priority of multiple option blocks (e.g. options from non-volatile
309 * storage versus options from a DHCP server).
311 #define DHCP_EB_PRIORITY DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x01 )
313 /** "Your" IP address
315 * This option is used internally to contain the value of the "yiaddr"
316 * field, in order to provide a consistent approach to storing and
317 * processing options. It should never be present in a DHCP packet.
319 #define DHCP_EB_YIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x02 )
321 /** "Server" IP address
323 * This option is used internally to contain the value of the "siaddr"
324 * field, in order to provide a consistent approach to storing and
325 * processing options. It should never be present in a DHCP packet.
327 #define DHCP_EB_SIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x03 )
329 /** Keep SAN drive registered
331 * If set to a non-zero value, iPXE will not detach any SAN drive
332 * after failing to boot from it. (This option is required in order
333 * to perform an installation direct to an iSCSI target.)
335 #define DHCP_EB_KEEP_SAN DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x08 )
337 /** Skip booting from SAN drive
339 * If set to a non-zero value, iPXE will skip booting from any SAN
340 * drive. (This option is sometimes required in conjunction with @c
341 * DHCP_EB_KEEP_SAN in order to perform an installation direct to an
344 #define DHCP_EB_SKIP_SAN_BOOT DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x09 )
347 * Tags in the range 0x10-0x4f are reserved for feature markers
353 * If a scriptlet exists, it will be executed in place of the usual
356 #define DHCP_EB_SCRIPTLET DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x51 )
358 /** Encrypted syslog server */
359 #define DHCP_EB_SYSLOGS_SERVER DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x55 )
361 /** Trusted root certficate fingerprints */
362 #define DHCP_EB_TRUST DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x5a )
364 /** Client certficate */
365 #define DHCP_EB_CERT DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x5b )
367 /** Client private key */
368 #define DHCP_EB_KEY DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x5c )
370 /** Cross-signed certificate source */
371 #define DHCP_EB_CROSS_CERT DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x5d )
373 /** Skip PXE DHCP protocol extensions such as ProxyDHCP
375 * If set to a non-zero value, iPXE will not wait for ProxyDHCP offers
376 * and will ignore any PXE-specific DHCP options that it receives.
378 #define DHCP_EB_NO_PXEDHCP DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xb0 )
380 /** Network device descriptor
382 * Byte 0 is the bus type ID; remaining bytes depend on the bus type.
386 * Byte 1 : PCI vendor ID MSB
387 * Byte 2 : PCI vendor ID LSB
388 * Byte 3 : PCI device ID MSB
389 * Byte 4 : PCI device ID LSB
391 #define DHCP_EB_BUS_ID DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xb1 )
393 /** Network device descriptor */
394 struct dhcp_netdev_desc {
401 } __attribute__ (( packed ));
403 /** Use cached network settings (obsolete; do not reuse this value) */
404 #define DHCP_EB_USE_CACHED DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xb2 )
406 /** BIOS drive number
408 * This is the drive number for a drive emulated via INT 13. 0x80 is
409 * the first hard disk, 0x81 is the second hard disk, etc.
411 #define DHCP_EB_BIOS_DRIVE DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbd )
415 * This will be used as the username for any required authentication.
416 * It is expected that this option's value will be held in
417 * non-volatile storage, rather than transmitted as part of a DHCP
420 #define DHCP_EB_USERNAME DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbe )
424 * This will be used as the password for any required authentication.
425 * It is expected that this option's value will be held in
426 * non-volatile storage, rather than transmitted as part of a DHCP
429 #define DHCP_EB_PASSWORD DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbf )
433 * This will be used as the reverse username (i.e. the username
434 * provided by the server) for any required authentication. It is
435 * expected that this option's value will be held in non-volatile
436 * storage, rather than transmitted as part of a DHCP packet.
438 #define DHCP_EB_REVERSE_USERNAME DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xc0 )
442 * This will be used as the reverse password (i.e. the password
443 * provided by the server) for any required authentication. It is
444 * expected that this option's value will be held in non-volatile
445 * storage, rather than transmitted as part of a DHCP packet.
447 #define DHCP_EB_REVERSE_PASSWORD DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xc1 )
451 * This will be used as the user id for AUTH_SYS based authentication in NFS.
453 #define DHCP_EB_UID DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xc2 )
457 * This will be used as the group id for AUTH_SYS based authentication in NFS.
459 #define DHCP_EB_GID DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xc3 )
461 /** iPXE version number */
462 #define DHCP_EB_VERSION DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xeb )
464 /** iSCSI primary target IQN */
465 #define DHCP_ISCSI_PRIMARY_TARGET_IQN 201
467 /** iSCSI secondary target IQN */
468 #define DHCP_ISCSI_SECONDARY_TARGET_IQN 202
470 /** iSCSI initiator IQN */
471 #define DHCP_ISCSI_INITIATOR_IQN 203
473 /** Maximum normal DHCP option */
474 #define DHCP_MAX_OPTION 254
478 * This tag does not have a length field; it is always only a single
485 /** Construct a DHCP option from a list of bytes */
486 #define DHCP_OPTION( ... ) VA_ARG_COUNT ( __VA_ARGS__ ), __VA_ARGS__
488 /** Construct a DHCP option from a list of characters */
489 #define DHCP_STRING( ... ) DHCP_OPTION ( __VA_ARGS__ )
491 /** Construct a byte-valued DHCP option */
492 #define DHCP_BYTE( value ) DHCP_OPTION ( value )
494 /** Construct a word-valued DHCP option */
495 #define DHCP_WORD( value ) DHCP_OPTION ( ( ( (value) >> 8 ) & 0xff ), \
496 ( ( (value) >> 0 ) & 0xff ) )
498 /** Construct a dword-valued DHCP option */
499 #define DHCP_DWORD( value ) DHCP_OPTION ( ( ( (value) >> 24 ) & 0xff ), \
500 ( ( (value) >> 16 ) & 0xff ), \
501 ( ( (value) >> 8 ) & 0xff ), \
502 ( ( (value) >> 0 ) & 0xff ) )
504 /** Construct a DHCP encapsulated options field */
505 #define DHCP_ENCAP( ... ) DHCP_OPTION ( __VA_ARGS__, DHCP_END )
510 * DHCP options consist of a mandatory tag, a length field that is
511 * mandatory for all options except @c DHCP_PAD and @c DHCP_END, and a
517 * Must be a @c DHCP_XXX value.
522 * This is the length of the data field (i.e. excluding the
523 * tag and length fields). For the two tags @c DHCP_PAD and
524 * @c DHCP_END, the length field is implicitly zero and is
525 * also missing, i.e. these DHCP options are only a single
531 } __attribute__ (( packed ));
534 * Length of a DHCP option header
536 * The header is the portion excluding the data, i.e. the tag and the
539 #define DHCP_OPTION_HEADER_LEN ( offsetof ( struct dhcp_option, data ) )
541 /** Maximum length for a single DHCP option */
542 #define DHCP_MAX_LEN 0xff
551 * This must be either @c BOOTP_REQUEST or @c BOOTP_REPLY.
554 /** Hardware address type
556 * This is an ARPHRD_XXX constant. Note that ARPHRD_XXX
557 * constants are nominally 16 bits wide; this could be
558 * considered to be a bug in the BOOTP/DHCP specification.
561 /** Hardware address length */
563 /** Number of hops from server */
565 /** Transaction ID */
567 /** Seconds since start of acquisition */
571 /** "Client" IP address
573 * This is filled in if the client already has an IP address
574 * assigned and can respond to ARP requests.
576 struct in_addr ciaddr;
577 /** "Your" IP address
579 * This is the IP address assigned by the server to the client.
581 struct in_addr yiaddr;
582 /** "Server" IP address
584 * This is the IP address of the next server to be used in the
587 struct in_addr siaddr;
588 /** "Gateway" IP address
590 * This is the IP address of the DHCP relay agent, if any.
592 struct in_addr giaddr;
593 /** Client hardware address */
595 /** Server host name (null terminated)
597 * This field may be overridden and contain DHCP options
600 /** Boot file name (null terminated)
602 * This field may be overridden and contain DHCP options
605 /** DHCP magic cookie
607 * Must have the value @c DHCP_MAGIC_COOKIE.
612 * Variable length; extends to the end of the packet. Minimum
613 * length (for the sake of sanity) is 1, to allow for a single
619 /** Opcode for a request from client to server */
620 #define BOOTP_REQUEST 1
622 /** Opcode for a reply from server to client */
623 #define BOOTP_REPLY 2
625 /** BOOTP reply must be broadcast
627 * Clients that cannot accept unicast BOOTP replies must set this
630 #define BOOTP_FL_BROADCAST 0x8000
632 /** DHCP magic cookie */
633 #define DHCP_MAGIC_COOKIE 0x63825363UL
635 /** DHCP minimum packet length
637 * This is the mandated minimum packet length that a DHCP participant
638 * must be prepared to receive.
640 #define DHCP_MIN_LEN 552
642 /** Timeouts for sending DHCP packets */
643 #define DHCP_MIN_TIMEOUT ( 1 * TICKS_PER_SEC )
644 #define DHCP_MAX_TIMEOUT ( 10 * TICKS_PER_SEC )
646 /** Maximum time that we will wait for ProxyDHCP responses */
647 #define PROXYDHCP_MAX_TIMEOUT ( 2 * TICKS_PER_SEC )
649 /** Maximum time that we will wait for Boot Server responses */
650 #define PXEBS_MAX_TIMEOUT ( 3 * TICKS_PER_SEC )
652 /** Settings block name used for DHCP responses */
653 #define DHCP_SETTINGS_NAME "dhcp"
655 /** Settings block name used for ProxyDHCP responses */
656 #define PROXYDHCP_SETTINGS_NAME "proxydhcp"
658 /** Setting block name used for BootServerDHCP responses */
659 #define PXEBS_SETTINGS_NAME "pxebs"
661 extern uint32_t dhcp_last_xid;
662 extern int dhcp_create_packet ( struct dhcp_packet *dhcppkt,
663 struct net_device *netdev, uint8_t msgtype,
664 uint32_t xid, const void *options,
665 size_t options_len, void *data,
667 extern int dhcp_create_request ( struct dhcp_packet *dhcppkt,
668 struct net_device *netdev,
669 unsigned int msgtype, uint32_t xid,
670 struct in_addr ciaddr,
671 void *data, size_t max_len );
672 extern int start_dhcp ( struct interface *job, struct net_device *netdev );
673 extern int start_pxebs ( struct interface *job, struct net_device *netdev,
674 unsigned int pxe_type );
676 #endif /* _IPXE_DHCP_H */