Template:APHD/doc

{{APHD}} is a template for generating Augmented Packet Header Diagrams. An effort is underway 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.

Usage

The easiest way to see how it works is by giving some examples.

A diagram for TCP's header format

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:

TCP's header format

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)
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.

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

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:

Ethernet frame

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
⋮	⋮

IP Header

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

UDP Header

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

DHCP Payload

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)

DHCP Options (TLV)

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

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

Template {{APHD}} is used to create augmented packet header diagrams.

Template parameters

Parameter		Description	Type	Status
table header	1 (start)	Generates the header. Example start	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. Example 4	Number	suggested
special left header	1 (999)	This nonsensical numerical value (not a multiple of 4 octets) indicates that the octets and bits in the vertical header are specified by options 'hoctets' and 'hbits'. Example 999	String	suggested
table end	1 (end)	Generates the end of the table. Example end	String	suggested
field definition	1 (def)	Generates a field definition. Due to limitations, the starting semicolon cannot be generated automatically. It needs to be given outside the {{APHD}} template. Example ;{{APHD|def|field=Source Port|bits=16 bits|text=Identifies the sending port.}}	String	suggested
field definition	name (def)	Generates the field name heading. Example name=Source Port	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. Example short=DSCP	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. Example length=16 bits	String	suggested
field definition	constraint (def)	The value constraint of the field (if predefined). Displayed as '; <constraint>'. Pipe symbols need to be escaped with {{!}}. Example constraint=(FIN) == 0 {{!}}{{!}} (SYN) == 0	String	optional
field definition	text (def)	Generates the field description. Example text=Identifies the sending port.	String	optional
special octets	hoctets (999)	Specify a special string for 'Octets' in the left header. Defaults to vertical ellipsis (&vellip;) when omitted. Example hoctets=16 + 4n	String	optional
special bits	hbits (999)	Specify a special string for 'Bits' in the left header. Defaults to vertical ellipsis (&vellip;) when omitted. Example hbits=64 + 32n	String	optional
field length	bits1-bits12	Size of field field1 - field12 in bits. Default 1 Example bits3=16	String	optional
field name	field1-field12	Field name of field1 - field12. Example field2=Options	String	optional
vertical field name	vfield1-vfield12	Field name of field1 - field12. Displayed vertically. A 'fieldX' takes precedence over a 'vfieldX'. Example vfield7=SYN	String	optional
background color	background1-background12	Specify a different background color, instead of grey. Example background2=mistyrose	String	optional
text color	color1-color12	Text color to use instead of black. Example color6=red	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'. Example border7=bottom	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. Example hint1=Source MAC address	String	optional
field value	value1-value12	A value that is displayed in parentheses after the field name. Used for fields with a fixed value; either for all packets or as an example. Example value4={{Mono|0x00bb}}	String	optional