Template:APHD
{{APHD}}
is a template for generating Augmented Packet Header Diagrams. An effort is underway[1] to standardize diagrams in RFCs and to make them machine readable. This macro, however, is solely intended for generating diagrams for human consumption. As such, and building on Wikipedia's history, they will differ somewhat.
The generated diagram (a wikitable) has been designed and improved by many earlier editors on many wiki pages. This template merely standardizes this work and simplifies its use.
The diagram includes a header that numbers bits from 0 to 31, with 0 being the most significant bit. These bits are numbered in network byte order, since they are, with very few exceptions, transmitted over the line in this order.[2]
Usage
[edit]The easiest way to see how it works is by giving some examples.
A diagram for TCP's header format
[edit]We start with the header, and we add a title, embellished with a reference.
{{APHD|start|title=TCP's header format{{Ref RFC|9293}}}}
Next we define two 16-bit fields, starting at octet 0:
{{APHD|0|bits1=16|bits2=16|field1=Source Port|field2=Destination Port}}
We follow with two 32-bit fields, starting at octet 4 and 8. Suppose some emphasis is required on the name of a field, you can give it a different colour:
{{APHD|4|bits1=32|field1=Sequence Number|color1=saddlebrown}}
{{APHD|8|bits1=32|field1=Acknowledgement Number (meaningful when ACK bit set)}}
Now, things get interesting. Let's define 11 fields of various sizes and display some of them vertically. Note that we do not have to specify the widths of fields of only one bit.
{{APHD|12|bits1=4|bits2=4|bits11=16|field1=Data Offset|field2=Reserved|vfield3=CWR|vfield4=ECE| vfield5=URG|vfield6=ACK|vfield7=PSH|vfield8=RST|vfield9=SYN|vfield10=FIN|field11=Window}}
Then we repeat a line with two 16-bit fields. You can include wikilinks in the fields' text, as well as references:
{{APHD|16|bits1=16|bits2=16|field1=[[Internet checksum|Checksum]]|field2=Urgent Pointer (meaningful when URG bit set){{Ref RFC|9293|rsection=3.8.5}}}}
We end the fields with a large, 320-bit field, which would span ten lines but is summarized on just 3 lines. We give it a very light salmon colour ('misty rose') to indicate it is optional:
{{APHD|20|bits1=320|background1=linen|field1=[Options] If present, Data Offset will be greater than 5.{{break}}Padded with zeroes to a multiple of 32 bits, since Data Offset counts words of 4 octets.}}
Background colours can be specified using a standard HTML colour name, or a hexadecimal colour code with 3 or 6 digits.
{{APHD|60|bits1=0|background1=mistyrose|field1=Data}}
Finally, we end the wikitable with:
{{APHD|end}}
It does not generate output, but ends the table in a proper manner. It should always be included at the end of the table.
As an example, we give a description of some of the fields.
Due to template restrictions, the semicolon (to generate a HTML description list) need to be placed before the call to this {{APHD}} template.
;{{APHD|def|name=Source Port|length=16 bits|text=Identifies the sending port.}}
;{{APHD|def|name=Reserved|length=4 bits|text=For future use and should be set to zero.
:From 2003–2017, the last bit (bit 103 of the header) was defined as the NS (Nonce Sum) flag by the experimental RFC 3540, ECN-nonce. ECN-nonce never gained widespread use and the RFC was moved to Historic status.{{Ref RFC|3540}}}}
(Notice the line break after 'zero.' and the start of the next line with a colon to indent it properly.)
;{{APHD|def|name=Options|length=Variable 0–320 bits, in units of 32 bits|text=The length of this field is determined by the ''data offset'' field. Options have up to three fields: Option-Kind (1 byte), Option-Length (1 byte), Option-Data (variable). The Option-Kind field indicates the type of option and is the only field that is not optional. Depending on Option-Kind value, the next two fields may be set. Option-Length indicates the total length of the option, and Option-Data contains data associated with the option, if applicable. For example...}}
- Or you could just use extra text outside the start of the field definitions.
This is the result:
Offset | Octet | 0 | 1 | 2 | 3 | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Octet | Bit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 |
0 | 0 | Source Port | Destination Port | ||||||||||||||||||||||||||||||
4 | 32 | Sequence Number | |||||||||||||||||||||||||||||||
8 | 64 | Acknowledgement Number (meaningful when ACK bit set) | |||||||||||||||||||||||||||||||
12 | 96 | Data Offset | Reserved | CWR | ECE | URG | ACK | PSH | RST | SYN | FIN | Window | |||||||||||||||||||||
16 | 128 | Checksum | Urgent Pointer (meaningful when URG bit set)[3]: §3.8.5 | ||||||||||||||||||||||||||||||
20 | 160 | [Options] If present, Data Offset will be greater than 5. Padded with zeroes to a multiple of 32 bits, since Data Offset counts words of 4 octets. | |||||||||||||||||||||||||||||||
⋮ | ⋮ | ||||||||||||||||||||||||||||||||
56 | 448 | ||||||||||||||||||||||||||||||||
60 | 480 | Data | |||||||||||||||||||||||||||||||
64 | 512 | ||||||||||||||||||||||||||||||||
⋮ | ⋮ |
- Source Port: 16 bits
- Identifies the sending port.
- Reserved: 4 bits
- For future use and should be set to zero.
- From 2003–2017, the last bit (bit 103 of the header) was defined as the NS (Nonce Sum) flag by the experimental RFC 3540, ECN-nonce. ECN-nonce never gained widespread use and the RFC was moved to Historic status.[4]
- Options: Variable 0–320 bits, in units of 32 bits
- The length of this field is determined by the data offset field. Options have up to three fields: Option-Kind (1 byte), Option-Length (1 byte), Option-Data (variable). The Option-Kind field indicates the type of option and is the only field that is not optional. Depending on Option-Kind value, the next two fields may be set. Option-Length indicates the total length of the option, and Option-Data contains data associated with the option, if applicable. For example...
A diagram for a DHCP Request packet
[edit]Some packet diagrams are best displayed in more than one logical part. You can place these diagrams directly below each other, without repeating the header. Some fields are too small to display both name and value. In that case you can use the 'hint' option. Large fields can start somewhere in 'the middle' and continue on the next line. With proper use of the 'border' option, you can create the illusion that the field is continuous. Below is an example of a DHCP Request packet.
The field containing the IPv4 packet has bitlength of 0, indicating unknown length. It starts as field4 on the previous line, which has no bottom border, and an empty text. To complete the illusion that the two are contiguous, the IPv4 field has no top border. Fields 1 and 2 are too small to include the field name, so it is included in the hint.
{{APHD|start|title=Ethernet frame}}
{{APHD|0|bits1=6|bits2=6|bits3=2|bits4=18|border4=bottom|field1={{MACaddr|00:ce:83:24:bb:e4}}|hint1=Source MAC|field2={{MACaddr|ff:ff:ff:ff:ff:ff}}|hint2=Destination MAC (the broadcast address)|field3={{Mono|0x8000}}|hint3=EtherType (indicating IPv4)|field4= |background4=mistyrose}}
{{APHD|4|bits1=0|border1=top|background1=mistyrose|field1=IPv4 packet, containing a UDP PDU with DHCP payload...}}
{{APHD|end}}
Next is the containing IPv4 packet. We include a header once more, because we start counting bits from zero again.
{{APHD|start|title=IP Header}}
{{APHD|0|bits1=64|field1=IP header start}}
{{APHD|8|bits1=8|bits2=16|bits3=8|field1=TTL|field2=Protocol ({{Mono|17}} UDP)|field3=Header Checksum}}
{{APHD|end}}
Then follows the UDP header, which continues the IPv4 packet.
{{APHD|start|header=no|title=UDP Header}}
{{APHD|12|bits1=32|field1=Source Address ({{IPaddr|0.0.0.0}})}}
{{APHD|16|bits1=32|field1=Destination Address ({{IPaddr|255.255.255.255}})}}
{{APHD|20|bits1=16|bits2=16|field1=Source Port (68)|field2=Destination Port (67)}}
{{APHD|24|bits1=16|bits2=16|field1=Length|field2=Checksum}}
{{APHD|end}}
Then the DHCP Payload, again without a header.
{{APHD|start|header=no|title=DHCP Payload}}
{{APHD|28|bits1=8|bits2=8|bits3=8|bits4=8|field1=OP ({{Mono|0x01}})|field2=HTYPE ({{Mono|0x01}})|field3=HLEN ({{Mono|0x06}})|field4=HOPS ({{Mono|0x00}})}}
{{APHD|32|bits1=32|field1=XID ({{Mono|0x3903F326}})}}
{{APHD|36|bits1=16|bits2=16|field1=SECS ({{Mono|0x0000}})|field2=FLAGS ({{Mono|0x0000}})}}
{{APHD|40|bits1=32|field1=CIADDR (Client IP address: {{Mono|0x00000000}})}}
{{APHD|44|bits1=32|field1=YIADDR (Your IP address: {{Mono|0x00000000}})}}
{{APHD|48|bits1=32|field1=SIADDR (Server IP address: {{Mono|0x00000000}})}}
{{APHD|52|bits1=32|field1=GIADDR (Gateway IP address: {{Mono|0x00000000}})}}
{{APHD|56|bits1=128|field1=CHADDR (Client Hardware address: {{Mono|0x00053C04<br>0x8D590000<br>0x00000000<br>0x00000000}})}}
{{APHD|72|bits1=1536|field1=192 octets of 0s, or overflow space for additional options; BOOTP legacy.}}
{{APHD|264|bits1=32|field1=[[Magic cookie|Magic Cookie]] ({{Mono|0x63825363}})}}
{{APHD|end}}
The last part describes DHCP options in a TLV structure, where fields cross the 32 octet boundary.
{{APHD|start|header=no|title=DHCP Options ([[Type-length-value|TLV]])}}
{{APHD|292|bits1=24|background1=linen|field1=First option: {{Mono|0x350101}}: Option 53 (DHCP Discover) 1 octet|bits2=8|background2=linen|border2=right|field2=Second option:}}
{{APHD|324|bits1=32|background1=linen|border1=left|field1={{Mono|0x3204c0a80164}}: Option 50 (Request IP address) 4 octets (containing {{IPaddr|192.168.1.100}})}}
{{APHD|356|bits1=32|background1=linen|field1=Third option: {{Mono|0x370401030f06}}: Option: 55 (Parameter Request List) 4 octets|hint1=0x01: Request Subnet Mask; 0x03: Router; 0x0f: Domain Name|border1=right}}
{{APHD|388|bits1=8|background1=linen|border1=left|field1=PRL cont...|hint1=0x06: Domain Name Server|bits2=1|field2=<small>{{Mono|ff}}</small>|hint2=0xff Option end mark}}
{{APHD|end}}
This is the result:
Offset | Octet | 0 | 1 | 2 | 3 | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Octet | Bit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 |
0 | 0 | 00:CE:83:24:BB:E4 | FF:FF:FF:FF:FF:FF | 0x8000 | |||||||||||||||||||||||||||||
4 | 32 | IPv4 packet, containing a UDP PDU with DHCP payload... | |||||||||||||||||||||||||||||||
8 | 64 | ||||||||||||||||||||||||||||||||
⋮ | ⋮ |
Offset | Octet | 0 | 1 | 2 | 3 | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Octet | Bit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 |
0 | 0 | IP header start | |||||||||||||||||||||||||||||||
4 | 32 | ||||||||||||||||||||||||||||||||
8 | 64 | TTL | Protocol (17 UDP) | Header Checksum |
12 | 96 | Source Address (0.0.0.0) | |||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
16 | 128 | Destination Address (255.255.255.255) | |||||||||||||||||||||||||||||||
20 | 160 | Source Port (68) | Destination Port (67) | ||||||||||||||||||||||||||||||
24 | 192 | Length | Checksum |
28 | 224 | OP (0x01) | HTYPE (0x01) | HLEN (0x06) | HOPS (0x00) | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
32 | 256 | XID (0x3903F326) | |||||||||||||||||||||||||||||||
36 | 288 | SECS (0x0000) | FLAGS (0x0000) | ||||||||||||||||||||||||||||||
40 | 320 | CIADDR (Client IP address: 0x00000000) | |||||||||||||||||||||||||||||||
44 | 352 | YIADDR (Your IP address: 0x00000000) | |||||||||||||||||||||||||||||||
48 | 384 | SIADDR (Server IP address: 0x00000000) | |||||||||||||||||||||||||||||||
52 | 416 | GIADDR (Gateway IP address: 0x00000000) | |||||||||||||||||||||||||||||||
56 | 448 | CHADDR (Client Hardware address: 0x00053C04 0x8D590000 0x00000000 0x00000000) | |||||||||||||||||||||||||||||||
60 | 480 | ||||||||||||||||||||||||||||||||
64 | 512 | ||||||||||||||||||||||||||||||||
68 | 544 | ||||||||||||||||||||||||||||||||
72 | 576 | 192 octets of 0s, or overflow space for additional options; BOOTP legacy. | |||||||||||||||||||||||||||||||
⋮ | ⋮ | ||||||||||||||||||||||||||||||||
260 | 2080 | ||||||||||||||||||||||||||||||||
264 | 2112 | Magic Cookie (0x63825363) |
292 | 2336 | First option: 0x350101: Option 53 (DHCP Discover) 1 octet | Second option:↴ | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
324 | 2592 | ↪0x3204c0a80164: Option 50 (Request IP address) 4 octets (containing 192.168.1.100) | |||||||||||||||||||||||||||||||
356 | 2848 | Third option: 0x370401030f06: Option: 55 (Parameter Request List) 4 octets↴ | |||||||||||||||||||||||||||||||
388 | 3104 | ↪PRL cont... | ff |
Suggestions for the use of color
[edit]If in doubt, don't use color and leave the table and its fields in its default color scheme.
Background color may be used to signify a notable field. You could use 'mistyrose' as background color for fields that you want to stand out. Use a background of 'linen' for any field that is optional.
Only in special cases use a text color other than the default black. Use sparingly.
Template data
[edit]Template {{APHD}} is used to create augmented packet header diagrams.
Parameter | Description | Type | Status | |
---|---|---|---|---|
table header | 1 (start) | Generates the header.
| String | suggested |
offset | 1 (numerical) | If this parameter is numerical then it is interpreted as the octet offset of this 4 octet-sized table row, which is displayed in the left header. The bit offset is calculated automatically.
| Number | suggested |
table end | 1 (end) | Generates the end of the table.
| String | suggested |
field definition | 1 (def) | Generates a field definition.
| String | suggested |
field definition | name (def) | Generates the field name heading.
| String | suggested |
field definition | short (def) | Generates the short field name heading in parentheses. Used to indicate how the field is represented in the header diagram.
| String | optional |
field definition | length (def) | Generates the length of the field in bits (or bytes if clearly defined as such). Use 'variable' if the field is of variable length.
| String | suggested |
field definition | constraint (def) | The value constraint of the field (if predefined). Displayed as '; <constraint>'. Pipe symbols need to be escaped with {{!}}.
| String | optional |
field definition | text (def) | Generates the field description.
| String | optional |
field length | bits1-bits12 | Size of field field1 - field12 in bits.
| String | optional |
field name | field1-field12 | Field name of field1 - field12.
| String | optional |
vertical field name | vfield1-vfield12 | Field name of field1 - field12. Displayed vertically. A 'fieldX' takes precedence over a 'vfieldX'.
| String | optional |
background color | background1-background12 | Specify a different background color, instead of grey.
| String | optional |
text color | color1-color12 | Text color to use instead of black.
| String | optional |
border option | border1-border12 | Indicate which border NOT to display. Possible values: 'top', 'right', 'left', 'bottom', 'top-bottom'. Value 'right' should be used on the last field, which also displays a continuation arrow. Value 'left' should be used on the first field, which also displays a continuation arrow. Use 'top-bottom' for a field of 32 octets or more, that has started as the last field (say: 'field7') of the previous line, and continues afterwards as the first field on the line below it. The last field on the previous line should use 'border7=bottom'; the first field on the next line should use 'border1=top'.
| String | optional |
field hint | hint1-hint12 | A hint that is displayed as a tool-tip (using the HTML <abbr> tag). Useful to give more information about a field, or to be able to display a value in a small field and tell the viewer the name of the field as a hint.
| String | optional |
References
[edit]- ^ S. McQuistin; V. Band; D. Jacob; C. S. Perkins (23 October 2023). Describing Protocol Data Units with Augmented Packet Header Diagrams. Network Working Group.Internet Draft
- ^ J. Reynolds; J. Postel (October 1994). ASSIGNED NUMBERS. Network Working Group. doi:10.17487/RFC1700. STD 2. RFC 1700. Obsolete. Obsoleted by RFC 3232. Obsoletes RFC 1340, 1060, 1010, 990, 960, 943, 923, 900, 870, 820, 790, 776, 770, 762, 758, 755, 750, 739 604, 503, 433 and 349. Obsoletes IENs: 127, 117, 93.
- ^ a b W. Eddy, ed. (August 2022). Transmission Control Protocol (TCP). Internet Engineering Task Force. doi:10.17487/RFC9293. ISSN 2070-1721. STD 7. RFC 9293. Internet Standard 7. Obsoletes RFC 793, 879, 2873, 6093, 6429, 6528 and 6691. Updates RFC 1011, 1122 and 5961.
- ^ N. Spring; D. Wetherall; D. Ely (June 2003). Robust Explicit Congestion Notification (ECN) Signaling with Nonces. Network Working Group. doi:10.17487/RFC3540. RFC 3540. Historic.