src/include/gpxe/dhcp.h

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