1 #ifndef _GPXE_DHCP_H 2 #define _GPXE_DHCP_H 3 4 /** @file 5 * 6 * Dynamic Host Configuration Protocol 7 * 8 */ 9 10 FILE_LICENCE ( GPL2_OR_LATER ); 11 12 #include <stdint.h> 13 #include <gpxe/in.h> 14 #include <gpxe/list.h> 15 #include <gpxe/refcnt.h> 16 #include <gpxe/tables.h> 17 #include <gpxe/uuid.h> 18 #include <gpxe/netdevice.h> 19 #include <gpxe/uaccess.h> 20 21 struct job_interface; 22 struct dhcp_options; 23 struct dhcp_packet; 24 25 /** BOOTP/DHCP server port */ 26 #define BOOTPS_PORT 67 27 28 /** BOOTP/DHCP client port */ 29 #define BOOTPC_PORT 68 30 31 /** PXE server port */ 32 #define PXE_PORT 4011 33 34 /** Construct a tag value for an encapsulated option 35 * 36 * This tag value can be passed to Etherboot functions when searching 37 * for DHCP options in order to search for a tag within an 38 * encapsulated options block. 39 */ 40 #define DHCP_ENCAP_OPT( encapsulator, encapsulated ) \ 41 ( ( (encapsulator) << 8 ) | (encapsulated) ) 42 /** Extract encapsulating option block tag from encapsulated tag value */ 43 #define DHCP_ENCAPSULATOR( encap_opt ) ( (encap_opt) >> 8 ) 44 /** Extract encapsulated option tag from encapsulated tag value */ 45 #define DHCP_ENCAPSULATED( encap_opt ) ( (encap_opt) & 0xff ) 46 /** Option is encapsulated */ 47 #define DHCP_IS_ENCAP_OPT( opt ) DHCP_ENCAPSULATOR( opt ) 48 49 /** 50 * @defgroup dhcpopts DHCP option tags 51 * @{ 52 */ 53 54 /** Padding 55 * 56 * This tag does not have a length field; it is always only a single 57 * byte in length. 58 */ 59 #define DHCP_PAD 0 60 61 /** Minimum normal DHCP option */ 62 #define DHCP_MIN_OPTION 1 63 64 /** Subnet mask */ 65 #define DHCP_SUBNET_MASK 1 66 67 /** Routers */ 68 #define DHCP_ROUTERS 3 69 70 /** DNS servers */ 71 #define DHCP_DNS_SERVERS 6 72 73 /** Syslog servers */ 74 #define DHCP_LOG_SERVERS 7 75 76 /** Host name */ 77 #define DHCP_HOST_NAME 12 78 79 /** Domain name */ 80 #define DHCP_DOMAIN_NAME 15 81 82 /** Root path */ 83 #define DHCP_ROOT_PATH 17 84 85 /** Vendor encapsulated options */ 86 #define DHCP_VENDOR_ENCAP 43 87 88 /** PXE boot server discovery control */ 89 #define DHCP_PXE_DISCOVERY_CONTROL DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 6 ) 90 91 /** PXE boot server discovery control bits */ 92 enum dhcp_pxe_discovery_control { 93 /** Inhibit broadcast discovery */ 94 PXEBS_NO_BROADCAST = 1, 95 /** Inhibit multicast discovery */ 96 PXEBS_NO_MULTICAST = 2, 97 /** Accept only servers in DHCP_PXE_BOOT_SERVERS list */ 98 PXEBS_NO_UNKNOWN_SERVERS = 4, 99 /** Skip discovery if filename present */ 100 PXEBS_SKIP = 8, 101 }; 102 103 /** PXE boot server multicast address */ 104 #define DHCP_PXE_BOOT_SERVER_MCAST DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 7 ) 105 106 /** PXE boot servers */ 107 #define DHCP_PXE_BOOT_SERVERS DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 8 ) 108 109 /** PXE boot server */ 110 struct dhcp_pxe_boot_server { 111 /** "Type" */ 112 uint16_t type; 113 /** Number of IPv4 addresses */ 114 uint8_t num_ip; 115 /** IPv4 addresses */ 116 struct in_addr ip[0]; 117 } __attribute__ (( packed )); 118 119 /** PXE boot menu */ 120 #define DHCP_PXE_BOOT_MENU DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 9 ) 121 122 /** PXE boot menu */ 123 struct dhcp_pxe_boot_menu { 124 /** "Type" */ 125 uint16_t type; 126 /** Description length */ 127 uint8_t desc_len; 128 /** Description */ 129 char desc[0]; 130 } __attribute__ (( packed )); 131 132 /** PXE boot menu prompt */ 133 #define DHCP_PXE_BOOT_MENU_PROMPT DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 10 ) 134 135 /** PXE boot menu prompt */ 136 struct dhcp_pxe_boot_menu_prompt { 137 /** Timeout 138 * 139 * A value of 0 means "time out immediately and select first 140 * boot item, without displaying the prompt". A value of 255 141 * means "display menu immediately with no timeout". Any 142 * other value means "display prompt, wait this many seconds 143 * for keypress, if key is F8, display menu, otherwise select 144 * first boot item". 145 */ 146 uint8_t timeout; 147 /** Prompt to press F8 */ 148 char prompt[0]; 149 } __attribute__ (( packed )); 150 151 /** PXE boot menu item */ 152 #define DHCP_PXE_BOOT_MENU_ITEM DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 71 ) 153 154 /** PXE boot menu item */ 155 struct dhcp_pxe_boot_menu_item { 156 /** "Type" 157 * 158 * This field actually identifies the specific boot server (or 159 * cluster of boot servers offering identical boot files). 160 */ 161 uint16_t type; 162 /** "Layer" 163 * 164 * Just don't ask. 165 */ 166 uint16_t layer; 167 } __attribute__ (( packed )); 168 169 /** Requested IP address */ 170 #define DHCP_REQUESTED_ADDRESS 50 171 172 /** Lease time */ 173 #define DHCP_LEASE_TIME 51 174 175 /** Option overloading 176 * 177 * The value of this option is the bitwise-OR of zero or more 178 * DHCP_OPTION_OVERLOAD_XXX constants. 179 */ 180 #define DHCP_OPTION_OVERLOAD 52 181 182 /** The "file" field is overloaded to contain extra DHCP options */ 183 #define DHCP_OPTION_OVERLOAD_FILE 1 184 185 /** The "sname" field is overloaded to contain extra DHCP options */ 186 #define DHCP_OPTION_OVERLOAD_SNAME 2 187 188 /** DHCP message type */ 189 #define DHCP_MESSAGE_TYPE 53 190 #define DHCPNONE 0 191 #define DHCPDISCOVER 1 192 #define DHCPOFFER 2 193 #define DHCPREQUEST 3 194 #define DHCPDECLINE 4 195 #define DHCPACK 5 196 #define DHCPNAK 6 197 #define DHCPRELEASE 7 198 #define DHCPINFORM 8 199 200 /** DHCP server identifier */ 201 #define DHCP_SERVER_IDENTIFIER 54 202 203 /** Parameter request list */ 204 #define DHCP_PARAMETER_REQUEST_LIST 55 205 206 /** Maximum DHCP message size */ 207 #define DHCP_MAX_MESSAGE_SIZE 57 208 209 /** Vendor class identifier */ 210 #define DHCP_VENDOR_CLASS_ID 60 211 212 /** Client identifier */ 213 #define DHCP_CLIENT_ID 61 214 215 /** Client identifier */ 216 struct dhcp_client_id { 217 /** Link-layer protocol */ 218 uint8_t ll_proto; 219 /** Link-layer address */ 220 uint8_t ll_addr[MAX_LL_ADDR_LEN]; 221 } __attribute__ (( packed )); 222 223 /** TFTP server name 224 * 225 * This option replaces the fixed "sname" field, when that field is 226 * used to contain overloaded options. 227 */ 228 #define DHCP_TFTP_SERVER_NAME 66 229 230 /** Bootfile name 231 * 232 * This option replaces the fixed "file" field, when that field is 233 * used to contain overloaded options. 234 */ 235 #define DHCP_BOOTFILE_NAME 67 236 237 /** User class identifier */ 238 #define DHCP_USER_CLASS_ID 77 239 240 /** Client system architecture */ 241 #define DHCP_CLIENT_ARCHITECTURE 93 242 243 /** Client network device interface */ 244 #define DHCP_CLIENT_NDI 94 245 246 /** UUID client identifier */ 247 #define DHCP_CLIENT_UUID 97 248 249 /** UUID client identifier */ 250 struct dhcp_client_uuid { 251 /** Identifier type */ 252 uint8_t type; 253 /** UUID */ 254 union uuid uuid; 255 } __attribute__ (( packed )); 256 257 #define DHCP_CLIENT_UUID_TYPE 0 258 259 /** Etherboot-specific encapsulated options 260 * 261 * This encapsulated options field is used to contain all options 262 * specific to Etherboot (i.e. not assigned by IANA or other standards 263 * bodies). 264 */ 265 #define DHCP_EB_ENCAP 175 266 267 /** Priority of this options block 268 * 269 * This is a signed 8-bit integer field indicating the priority of 270 * this block of options. It can be used to specify the relative 271 * priority of multiple option blocks (e.g. options from non-volatile 272 * storage versus options from a DHCP server). 273 */ 274 #define DHCP_EB_PRIORITY DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x01 ) 275 276 /** "Your" IP address 277 * 278 * This option is used internally to contain the value of the "yiaddr" 279 * field, in order to provide a consistent approach to storing and 280 * processing options. It should never be present in a DHCP packet. 281 */ 282 #define DHCP_EB_YIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x02 ) 283 284 /** "Server" IP address 285 * 286 * This option is used internally to contain the value of the "siaddr" 287 * field, in order to provide a consistent approach to storing and 288 * processing options. It should never be present in a DHCP packet. 289 */ 290 #define DHCP_EB_SIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x03 ) 291 292 /** Keep SAN drive registered 293 * 294 * If set to a non-zero value, gPXE will not detach any SAN drive 295 * after failing to boot from it. (This option is required in order 296 * to perform a Windows Server 2008 installation direct to an iSCSI 297 * target.) 298 */ 299 #define DHCP_EB_KEEP_SAN DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x08 ) 300 301 /* 302 * Tags in the range 0x10-0x7f are reserved for feature markers 303 * 304 */ 305 306 /** Skip PXE DHCP protocol extensions such as ProxyDHCP 307 * 308 * If set to a non-zero value, gPXE will not wait for ProxyDHCP offers 309 * and will ignore any PXE-specific DHCP options that it receives. 310 */ 311 #define DHCP_EB_NO_PXEDHCP DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xb0 ) 312 313 /** Network device descriptor 314 * 315 * Byte 0 is the bus type ID; remaining bytes depend on the bus type. 316 * 317 * PCI devices: 318 * Byte 0 : 1 (PCI) 319 * Byte 1 : PCI vendor ID MSB 320 * Byte 2 : PCI vendor ID LSB 321 * Byte 3 : PCI device ID MSB 322 * Byte 4 : PCI device ID LSB 323 */ 324 #define DHCP_EB_BUS_ID DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xb1 ) 325 326 /** Network device descriptor */ 327 struct dhcp_netdev_desc { 328 /** Bus type ID */ 329 uint8_t type; 330 /** Vendor ID */ 331 uint16_t vendor; 332 /** Device ID */ 333 uint16_t device; 334 } __attribute__ (( packed )); 335 336 /** Use cached network settings 337 * 338 * Cached network settings may be available from a prior DHCP request 339 * (if running as a PXE NBP), non-volatile storage on the NIC, or 340 * settings set via the command line or an embedded image. If this 341 * flag is not set, it will be assumed that those sources are 342 * insufficient and that DHCP should still be run when autobooting. 343 */ 344 #define DHCP_EB_USE_CACHED DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xb2 ) 345 346 /** BIOS drive number 347 * 348 * This is the drive number for a drive emulated via INT 13. 0x80 is 349 * the first hard disk, 0x81 is the second hard disk, etc. 350 */ 351 #define DHCP_EB_BIOS_DRIVE DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbd ) 352 353 /** Username 354 * 355 * This will be used as the username for any required authentication. 356 * It is expected that this option's value will be held in 357 * non-volatile storage, rather than transmitted as part of a DHCP 358 * packet. 359 */ 360 #define DHCP_EB_USERNAME DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbe ) 361 362 /** Password 363 * 364 * This will be used as the password for any required authentication. 365 * It is expected that this option's value will be held in 366 * non-volatile storage, rather than transmitted as part of a DHCP 367 * packet. 368 */ 369 #define DHCP_EB_PASSWORD DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbf ) 370 371 /** Reverse username 372 * 373 * This will be used as the reverse username (i.e. the username 374 * provided by the server) for any required authentication. It is 375 * expected that this option's value will be held in non-volatile 376 * storage, rather than transmitted as part of a DHCP packet. 377 */ 378 #define DHCP_EB_REVERSE_USERNAME DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xc0 ) 379 380 /** Reverse password 381 * 382 * This will be used as the reverse password (i.e. the password 383 * provided by the server) for any required authentication. It is 384 * expected that this option's value will be held in non-volatile 385 * storage, rather than transmitted as part of a DHCP packet. 386 */ 387 #define DHCP_EB_REVERSE_PASSWORD DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xc1 ) 388 389 /** gPXE version number */ 390 #define DHCP_EB_VERSION DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xeb ) 391 392 /** iSCSI primary target IQN */ 393 #define DHCP_ISCSI_PRIMARY_TARGET_IQN 201 394 395 /** iSCSI secondary target IQN */ 396 #define DHCP_ISCSI_SECONDARY_TARGET_IQN 202 397 398 /** iSCSI initiator IQN */ 399 #define DHCP_ISCSI_INITIATOR_IQN 203 400 401 /** Maximum normal DHCP option */ 402 #define DHCP_MAX_OPTION 254 403 404 /** End of options 405 * 406 * This tag does not have a length field; it is always only a single 407 * byte in length. 408 */ 409 #define DHCP_END 255 410 411 /** @} */ 412 413 /** 414 * Count number of arguments to a variadic macro 415 * 416 * This rather neat, non-iterative solution is courtesy of Laurent 417 * Deniau. 418 * 419 */ 420 #define _VA_ARG_COUNT( _1, _2, _3, _4, _5, _6, _7, _8, \ 421 _9, _10, _11, _12, _13, _14, _15, _16, \ 422 _17, _18, _19, _20, _21, _22, _23, _24, \ 423 _25, _26, _27, _28, _29, _30, _31, _32, \ 424 _33, _34, _35, _36, _37, _38, _39, _40, \ 425 _41, _42, _43, _44, _45, _46, _47, _48, \ 426 _49, _50, _51, _52, _53, _54, _55, _56, \ 427 _57, _58, _59, _60, _61, _62, _63, N, ... ) N 428 #define VA_ARG_COUNT( ... ) \ 429 _VA_ARG_COUNT ( __VA_ARGS__, \ 430 63, 62, 61, 60, 59, 58, 57, 56, \ 431 55, 54, 53, 52, 51, 50, 49, 48, \ 432 47, 46, 45, 44, 43, 42, 41, 40, \ 433 39, 38, 37, 36, 35, 34, 33, 32, \ 434 31, 30, 29, 28, 27, 26, 25, 24, \ 435 23, 22, 21, 20, 19, 18, 17, 16, \ 436 15, 14, 13, 12, 11, 10, 9, 8, \ 437 7, 6, 5, 4, 3, 2, 1, 0 ) 438 439 /** Construct a DHCP option from a list of bytes */ 440 #define DHCP_OPTION( ... ) VA_ARG_COUNT ( __VA_ARGS__ ), __VA_ARGS__ 441 442 /** Construct a DHCP option from a list of characters */ 443 #define DHCP_STRING( ... ) DHCP_OPTION ( __VA_ARGS__ ) 444 445 /** Construct a byte-valued DHCP option */ 446 #define DHCP_BYTE( value ) DHCP_OPTION ( value ) 447 448 /** Construct a word-valued DHCP option */ 449 #define DHCP_WORD( value ) DHCP_OPTION ( ( ( (value) >> 8 ) & 0xff ), \ 450 ( ( (value) >> 0 ) & 0xff ) ) 451 452 /** Construct a dword-valued DHCP option */ 453 #define DHCP_DWORD( value ) DHCP_OPTION ( ( ( (value) >> 24 ) & 0xff ), \ 454 ( ( (value) >> 16 ) & 0xff ), \ 455 ( ( (value) >> 8 ) & 0xff ), \ 456 ( ( (value) >> 0 ) & 0xff ) ) 457 458 /** Construct a DHCP encapsulated options field */ 459 #define DHCP_ENCAP( ... ) DHCP_OPTION ( __VA_ARGS__, DHCP_END ) 460 461 /** 462 * A DHCP option 463 * 464 * DHCP options consist of a mandatory tag, a length field that is 465 * mandatory for all options except @c DHCP_PAD and @c DHCP_END, and a 466 * payload. 467 */ 468 struct dhcp_option { 469 /** Tag 470 * 471 * Must be a @c DHCP_XXX value. 472 */ 473 uint8_t tag; 474 /** Length 475 * 476 * This is the length of the data field (i.e. excluding the 477 * tag and length fields). For the two tags @c DHCP_PAD and 478 * @c DHCP_END, the length field is implicitly zero and is 479 * also missing, i.e. these DHCP options are only a single 480 * byte in length. 481 */ 482 uint8_t len; 483 /** Option data */ 484 uint8_t data[0]; 485 } __attribute__ (( packed )); 486 487 /** 488 * Length of a DHCP option header 489 * 490 * The header is the portion excluding the data, i.e. the tag and the 491 * length. 492 */ 493 #define DHCP_OPTION_HEADER_LEN ( offsetof ( struct dhcp_option, data ) ) 494 495 /** Maximum length for a single DHCP option */ 496 #define DHCP_MAX_LEN 0xff 497 498 /** 499 * A DHCP header 500 * 501 */ 502 struct dhcphdr { 503 /** Operation 504 * 505 * This must be either @c BOOTP_REQUEST or @c BOOTP_REPLY. 506 */ 507 uint8_t op; 508 /** Hardware address type 509 * 510 * This is an ARPHRD_XXX constant. Note that ARPHRD_XXX 511 * constants are nominally 16 bits wide; this could be 512 * considered to be a bug in the BOOTP/DHCP specification. 513 */ 514 uint8_t htype; 515 /** Hardware address length */ 516 uint8_t hlen; 517 /** Number of hops from server */ 518 uint8_t hops; 519 /** Transaction ID */ 520 uint32_t xid; 521 /** Seconds since start of acquisition */ 522 uint16_t secs; 523 /** Flags */ 524 uint16_t flags; 525 /** "Client" IP address 526 * 527 * This is filled in if the client already has an IP address 528 * assigned and can respond to ARP requests. 529 */ 530 struct in_addr ciaddr; 531 /** "Your" IP address 532 * 533 * This is the IP address assigned by the server to the client. 534 */ 535 struct in_addr yiaddr; 536 /** "Server" IP address 537 * 538 * This is the IP address of the next server to be used in the 539 * boot process. 540 */ 541 struct in_addr siaddr; 542 /** "Gateway" IP address 543 * 544 * This is the IP address of the DHCP relay agent, if any. 545 */ 546 struct in_addr giaddr; 547 /** Client hardware address */ 548 uint8_t chaddr[16]; 549 /** Server host name (null terminated) 550 * 551 * This field may be overridden and contain DHCP options 552 */ 553 char sname[64]; 554 /** Boot file name (null terminated) 555 * 556 * This field may be overridden and contain DHCP options 557 */ 558 char file[128]; 559 /** DHCP magic cookie 560 * 561 * Must have the value @c DHCP_MAGIC_COOKIE. 562 */ 563 uint32_t magic; 564 /** DHCP options 565 * 566 * Variable length; extends to the end of the packet. Minimum 567 * length (for the sake of sanity) is 1, to allow for a single 568 * @c DHCP_END tag. 569 */ 570 uint8_t options[0]; 571 }; 572 573 /** Opcode for a request from client to server */ 574 #define BOOTP_REQUEST 1 575 576 /** Opcode for a reply from server to client */ 577 #define BOOTP_REPLY 2 578 579 /** BOOTP reply must be broadcast 580 * 581 * Clients that cannot accept unicast BOOTP replies must set this 582 * flag. 583 */ 584 #define BOOTP_FL_BROADCAST 0x8000 585 586 /** DHCP magic cookie */ 587 #define DHCP_MAGIC_COOKIE 0x63825363UL 588 589 /** DHCP minimum packet length 590 * 591 * This is the mandated minimum packet length that a DHCP participant 592 * must be prepared to receive. 593 */ 594 #define DHCP_MIN_LEN 552 595 596 /** Timeouts for sending DHCP packets */ 597 #define DHCP_MIN_TIMEOUT ( 1 * TICKS_PER_SEC ) 598 #define DHCP_MAX_TIMEOUT ( 10 * TICKS_PER_SEC ) 599 600 /** Maximum time that we will wait for ProxyDHCP responses */ 601 #define PROXYDHCP_MAX_TIMEOUT ( 2 * TICKS_PER_SEC ) 602 603 /** Maximum time that we will wait for Boot Server responses */ 604 #define PXEBS_MAX_TIMEOUT ( 3 * TICKS_PER_SEC ) 605 606 /** Settings block name used for DHCP responses */ 607 #define DHCP_SETTINGS_NAME "dhcp" 608 609 /** Settings block name used for ProxyDHCP responses */ 610 #define PROXYDHCP_SETTINGS_NAME "proxydhcp" 611 612 /** Setting block name used for BootServerDHCP responses */ 613 #define PXEBS_SETTINGS_NAME "pxebs" 614 615 extern void * dhcp_chaddr ( struct net_device *netdev, uint8_t *hlen, 616 uint16_t *flags ); 617 extern int dhcp_create_packet ( struct dhcp_packet *dhcppkt, 618 struct net_device *netdev, uint8_t msgtype, 619 const void *options, size_t options_len, 620 void *data, size_t max_len ); 621 extern int dhcp_create_request ( struct dhcp_packet *dhcppkt, 622 struct net_device *netdev, 623 unsigned int msgtype, struct in_addr ciaddr, 624 void *data, size_t max_len ); 625 extern int start_dhcp ( struct job_interface *job, struct net_device *netdev ); 626 extern int start_pxebs ( struct job_interface *job, struct net_device *netdev, 627 unsigned int pxe_type ); 628 629 /* In environments that can provide cached DHCP packets, this function 630 * should look for such a packet and call store_cached_dhcpack() with 631 * it if it exists. 632 */ 633 __weak_decl ( void, get_cached_dhcpack, ( void ), (), ); 634 635 extern void store_cached_dhcpack ( userptr_t data, size_t len ); 636 637 #endif /* _GPXE_DHCP_H */ 638