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