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