AnnNet Specification
1. License
AnnNet Specification
by
Brent Saner
is licensed under:
Creative Commons Attribution-ShareAlike 4.0 International
(License in full)
Attribution-ShareAlike 4.0 International
=======================================================================
Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
Creative Commons public licenses does not create a lawyer-client or
other relationship. Creative Commons makes its licenses and related
information available on an "as-is" basis. Creative Commons gives no
warranties regarding its licenses, any material licensed under their
terms and conditions, or any related information. Creative Commons
disclaims all liability for damages resulting from their use to the
fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and
conditions that creators and other rights holders may use to share
original works of authorship and other material subject to copyright
and certain other rights specified in the public license below. The
following considerations are for informational purposes only, are not
exhaustive, and do not form part of our licenses.
Considerations for licensors: Our public licenses are
intended for use by those authorized to give the public
permission to use material in ways otherwise restricted by
copyright and certain other rights. Our licenses are
irrevocable. Licensors should read and understand the terms
and conditions of the license they choose before applying it.
Licensors should also secure all rights necessary before
applying our licenses so that the public can reuse the
material as expected. Licensors should clearly mark any
material not subject to the license. This includes other CC-
licensed material, or material used under an exception or
limitation to copyright. More considerations for licensors:
wiki.creativecommons.org/Considerations_for_licensors
Considerations for the public: By using one of our public
licenses, a licensor grants the public permission to use the
licensed material under specified terms and conditions. If
the licensor's permission is not necessary for any reason--for
example, because of any applicable exception or limitation to
copyright--then that use is not regulated by the license. Our
licenses grant only permissions under copyright and certain
other rights that a licensor has authority to grant. Use of
the licensed material may still be restricted for other
reasons, including because others have copyright or other
rights in the material. A licensor may make special requests,
such as asking that all changes be marked or described.
Although not required by our licenses, you are encouraged to
respect those requests where reasonable. More considerations
for the public:
wiki.creativecommons.org/Considerations_for_licensees
=======================================================================
Creative Commons Attribution-ShareAlike 4.0 International Public
License
By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution-ShareAlike 4.0 International Public License ("Public
License"). To the extent this Public License may be interpreted as a
contract, You are granted the Licensed Rights in consideration of Your
acceptance of these terms and conditions, and the Licensor grants You
such rights in consideration of benefits the Licensor receives from
making the Licensed Material available under these terms and
conditions.
Section 1 -- Definitions.
a. Adapted Material means material subject to Copyright and Similar
Rights that is derived from or based upon the Licensed Material
and in which the Licensed Material is translated, altered,
arranged, transformed, or otherwise modified in a manner requiring
permission under the Copyright and Similar Rights held by the
Licensor. For purposes of this Public License, where the Licensed
Material is a musical work, performance, or sound recording,
Adapted Material is always produced where the Licensed Material is
synched in timed relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright
and Similar Rights in Your contributions to Adapted Material in
accordance with the terms and conditions of this Public License.
c. BY-SA Compatible License means a license listed at
creativecommons.org/compatiblelicenses, approved by Creative
Commons as essentially the equivalent of this Public License.
d. Copyright and Similar Rights means copyright and/or similar rights
closely related to copyright including, without limitation,
performance, broadcast, sound recording, and Sui Generis Database
Rights, without regard to how the rights are labeled or
categorized. For purposes of this Public License, the rights
specified in Section 2(b)(1)-(2) are not Copyright and Similar
Rights.
e. Effective Technological Measures means those measures that, in the
absence of proper authority, may not be circumvented under laws
fulfilling obligations under Article 11 of the WIPO Copyright
Treaty adopted on December 20, 1996, and/or similar international
agreements.
f. Exceptions and Limitations means fair use, fair dealing, and/or
any other exception or limitation to Copyright and Similar Rights
that applies to Your use of the Licensed Material.
g. License Elements means the license attributes listed in the name
of a Creative Commons Public License. The License Elements of this
Public License are Attribution and ShareAlike.
h. Licensed Material means the artistic or literary work, database,
or other material to which the Licensor applied this Public
License.
i. Licensed Rights means the rights granted to You subject to the
terms and conditions of this Public License, which are limited to
all Copyright and Similar Rights that apply to Your use of the
Licensed Material and that the Licensor has authority to license.
j. Licensor means the individual(s) or entity(ies) granting rights
under this Public License.
k. Share means to provide material to the public by any means or
process that requires permission under the Licensed Rights, such
as reproduction, public display, public performance, distribution,
dissemination, communication, or importation, and to make material
available to the public including in ways that members of the
public may access the material from a place and at a time
individually chosen by them.
l. Sui Generis Database Rights means rights other than copyright
resulting from Directive 96/9/EC of the European Parliament and of
the Council of 11 March 1996 on the legal protection of databases,
as amended and/or succeeded, as well as other essentially
equivalent rights anywhere in the world.
m. You means the individual or entity exercising the Licensed Rights
under this Public License. Your has a corresponding meaning.
Section 2 -- Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License,
the Licensor hereby grants You a worldwide, royalty-free,
non-sublicensable, non-exclusive, irrevocable license to
exercise the Licensed Rights in the Licensed Material to:
a. reproduce and Share the Licensed Material, in whole or
in part; and
b. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where
Exceptions and Limitations apply to Your use, this Public
License does not apply, and You do not need to comply with
its terms and conditions.
3. Term. The term of this Public License is specified in Section
6(a).
4. Media and formats; technical modifications allowed. The
Licensor authorizes You to exercise the Licensed Rights in
all media and formats whether now known or hereafter created,
and to make technical modifications necessary to do so. The
Licensor waives and/or agrees not to assert any right or
authority to forbid You from making technical modifications
necessary to exercise the Licensed Rights, including
technical modifications necessary to circumvent Effective
Technological Measures. For purposes of this Public License,
simply making modifications authorized by this Section 2(a)
(4) never produces Adapted Material.
5. Downstream recipients.
a. Offer from the Licensor -- Licensed Material. Every
recipient of the Licensed Material automatically
receives an offer from the Licensor to exercise the
Licensed Rights under the terms and conditions of this
Public License.
b. Additional offer from the Licensor -- Adapted Material.
Every recipient of Adapted Material from You
automatically receives an offer from the Licensor to
exercise the Licensed Rights in the Adapted Material
under the conditions of the Adapter's License You apply.
c. No downstream restrictions. You may not offer or impose
any additional or different terms or conditions on, or
apply any Effective Technological Measures to, the
Licensed Material if doing so restricts exercise of the
Licensed Rights by any recipient of the Licensed
Material.
6. No endorsement. Nothing in this Public License constitutes or
may be construed as permission to assert or imply that You
are, or that Your use of the Licensed Material is, connected
with, or sponsored, endorsed, or granted official status by,
the Licensor or others designated to receive attribution as
provided in Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not
licensed under this Public License, nor are publicity,
privacy, and/or other similar personality rights; however, to
the extent possible, the Licensor waives and/or agrees not to
assert any such rights held by the Licensor to the limited
extent necessary to allow You to exercise the Licensed
Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this
Public License.
3. To the extent possible, the Licensor waives any right to
collect royalties from You for the exercise of the Licensed
Rights, whether directly or through a collecting society
under any voluntary or waivable statutory or compulsory
licensing scheme. In all other cases the Licensor expressly
reserves any right to collect such royalties.
Section 3 -- License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the
following conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified
form), You must:
a. retain the following if it is supplied by the Licensor
with the Licensed Material:
i. identification of the creator(s) of the Licensed
Material and any others designated to receive
attribution, in any reasonable manner requested by
the Licensor (including by pseudonym if
designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of
warranties;
v. a URI or hyperlink to the Licensed Material to the
extent reasonably practicable;
b. indicate if You modified the Licensed Material and
retain an indication of any previous modifications; and
c. indicate the Licensed Material is licensed under this
Public License, and include the text of, or the URI or
hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any
reasonable manner based on the medium, means, and context in
which You Share the Licensed Material. For example, it may be
reasonable to satisfy the conditions by providing a URI or
hyperlink to a resource that includes the required
information.
3. If requested by the Licensor, You must remove any of the
information required by Section 3(a)(1)(A) to the extent
reasonably practicable.
b. ShareAlike.
In addition to the conditions in Section 3(a), if You Share
Adapted Material You produce, the following conditions also apply.
1. The Adapter's License You apply must be a Creative Commons
license with the same License Elements, this version or
later, or a BY-SA Compatible License.
2. You must include the text of, or the URI or hyperlink to, the
Adapter's License You apply. You may satisfy this condition
in any reasonable manner based on the medium, means, and
context in which You Share Adapted Material.
3. You may not offer or impose any additional or different terms
or conditions on, or apply any Effective Technological
Measures to, Adapted Material that restrict exercise of the
rights granted under the Adapter's License You apply.
Section 4 -- Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right
to extract, reuse, reproduce, and Share all or a substantial
portion of the contents of the database;
b. if You include all or a substantial portion of the database
contents in a database in which You have Sui Generis Database
Rights, then the database in which You have Sui Generis Database
Rights (but not its individual contents) is Adapted Material,
including for purposes of Section 3(b); and
c. You must comply with the conditions in Section 3(a) if You Share
all or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.
Section 5 -- Disclaimer of Warranties and Limitation of Liability.
a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
c. The disclaimer of warranties and limitation of liability provided
above shall be interpreted in a manner that, to the extent
possible, most closely approximates an absolute disclaimer and
waiver of all liability.
Section 6 -- Term and Termination.
a. This Public License applies for the term of the Copyright and
Similar Rights licensed here. However, if You fail to comply with
this Public License, then Your rights under this Public License
terminate automatically.
b. Where Your right to use the Licensed Material has terminated under
Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided
it is cured within 30 days of Your discovery of the
violation; or
2. upon express reinstatement by the Licensor.
For the avoidance of doubt, this Section 6(b) does not affect any
right the Licensor may have to seek remedies for Your violations
of this Public License.
c. For the avoidance of doubt, the Licensor may also offer the
Licensed Material under separate terms or conditions or stop
distributing the Licensed Material at any time; however, doing so
will not terminate this Public License.
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
License.
Section 7 -- Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different
terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the
Licensed Material not stated herein are separate from and
independent of the terms and conditions of this Public License.
Section 8 -- Interpretation.
a. For the avoidance of doubt, this Public License does not, and
shall not be interpreted to, reduce, limit, restrict, or impose
conditions on any use of the Licensed Material that could lawfully
be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is
deemed unenforceable, it shall be automatically reformed to the
minimum extent necessary to make it enforceable. If the provision
cannot be reformed, it shall be severed from this Public License
without affecting the enforceability of the remaining terms and
conditions.
c. No term or condition of this Public License will be waived and no
failure to comply consented to unless expressly agreed to by the
Licensor.
d. Nothing in this Public License constitutes or may be interpreted
as a limitation upon, or waiver of, any privileges and immunities
that apply to the Licensor or You, including from the legal
processes of any jurisdiction or authority.
=======================================================================
Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
will be considered the “Licensor.” The text of the Creative Commons
public licenses is dedicated to the public domain under the CC0 Public
Domain Dedication. Except for the limited purpose of indicating that
material is shared under a Creative Commons public license or as
otherwise permitted by the Creative Commons policies published at
creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark "Creative Commons" or any other trademark or logo
of Creative Commons without its prior written consent including,
without limitation, in connection with any unauthorized modifications
to any of its public licenses or any other arrangements,
understandings, or agreements concerning use of licensed material. For
the avoidance of doubt, this paragraph does not form part of the
public licenses.
Creative Commons may be contacted at creativecommons.org.
In a nutshell, this means any may:
-
Use it in commercial/proprietary/internal works…
-
Expand upon/change the specification…
-
(As long as it is released under the same Creative Commons license)
-
As long as you attribute the original (this document). This can be as simple as something like:
Based on AnnNet version <protocol version> as found at https://annnet.io/.
More details certainly helps, though; you may want to mention the exact date you "forked" it, etc.
Please see the full text as collapsed above or the online version of the license for full legal copy.
|
Note
|
In the event of the embedded text in this document differing from the online version, the online version is assumed to take precedence as the valid license applicable to this work. |
3. Disclaimer
3.1. The AnnNet Protocol
This specification is provided as-is with no guarantees or obligations from this specification’s author(s).
The author(s) is/are not held liable for any damages caused by implementation/use of this protocol.
The AnnNet specification is subject to change, but changes are not considered definitive nor effective until/unless tied with/to a specific released version.
3.2. References
Many outside references are made throughout this document.
-
The author(s) is/are not sponsored by, contribute to, nor condone any of the resources mentioned unless otherwise specified.
-
The author(s) is/are not sponsored by, nor member(s),contributor(s), or sponsor of, nor condone any organizations or other entities listed or their actions unless otherwise specified.
References are suggested as-is with no guarantees or obligations from this specification’s author(s).
4. Protocol
The AnnNet (pronounced like the woman’s name "Annette") protocol is an announcement/query protocol designed for unspecified hosts on a local network. It is a shorthand for "the Announcement Network Protocol".
AnnNet is designed to operate with or without IP addressing being available, as it can operate on layer 2, layer 3, or both to unknown/unspecified destinations.
It is intended as a sort of "announcement" mechanism for sending messages to all hosts on a locally-linked (or single-organization-controlled) network (such as bootstrapping large-scale layer 3 services/clusters). It was designed with service/implementation-specific host discovery in mind, though other uses are possible.
It is recommended that it is only used sparingly for small messages (such as cluster bootstrapping for new members or initial cluster assembly). Operational messages should occur on a well-defined transport layer (e.g. TCP).
It is important to avoid the temptation of simply implementing ALL of a service’s communication via AnnNet, as this can quite easily overwhelm the physical network’s limitations as hosts participating in its communication grows. See the FAQ/FUQ entry Why Shouldn’t I Use AnnNet for Regular Traffic? for suggestions on how to manage actual service communication instead.
|
Note
|
The OSI (Open Systems Interconnection) model is going to be referenced a fair bit in this document. The linked Wikipedia article is a fantastic primer on it with a plethora of useful links, but if you’d like to read the authoritative material that’d be ISO/IEC 7498-1:1994. ISO/IEC 7498-1:1994 is one of the free-as-in-beer-for-digital-copy ISO/IEC standards available, provided you have an ISO account — which is also free to create and use. You can use the Register link at the bottom of ISO’s Webstore login to create a new purchasing account. Another fantastic reference for the OSI model (and all things networking) is the TCP/IP Guide by Charles M. Kozierok. (I am not sponsored by nor condone the material found in that re) It is available:
I (Brent) have a physical copy from No Starch Press. I find myself referencing the PDF much more often, as it has some very useful document linking within it, but moreso because the print copy is a behemoth and is very bulky for anything but a bookshelf and seated-at-a-table reading/research! The OSI model is covered in the TCP/IP Guide in Part I-2 (chapters 5 to 7 inclusive), starting on p.79. |
5. Specification
AnnNet supports two "sub-protocols":
Both make use of the Standard Prefix, though in different places of the frame/packet depending on their implementation. See each sub-protocol below for details.
5.1. AnnNet Message Format
The general format of an AnnNet message (excluding leading/surrounding/trailing frames, headers, etc.) is:
Standard Prefix (5 Bytes) |
5.1.1. Standard Prefix
AnnNet defines a specific prefix that must be added before a message. While AnnNet does not dictate the contents of the payload in any way, all AnnNet messages must contain this prefix.
In AnnNet Link, it immediately follows the EtherType value.
In AnnNet Broadcast, it immediately follows the IPv4/IPv6 header.
In its current form, this is:
5.1.1.1. Version
| Length (Octets/Bytes) | Type |
|---|---|
|
Big-Endian Unsigned 32-Bit Integer/Container |
The Version field matches the version of AnnNet being used.
Because AnnNet follows Semantic Versioning (v2.0.0) for its specification, this can either be treated as an abstract container (hereafter a "byte-slice version" in this spec) of individual bytes indicating each version sub-field or treated as a whole (hereafter a "single-value version" in this spec).
Thus for example, when determing how to parse the following fields from an AnnNet message if incompatible structuring changes are introduced, one can either:
-
Perform a version comparison sequentially (e.g. via first parsing and comparing the Major, and then moving on to the Minor, and so forth) for a byte-slice version
-
Or for a single-value version, a direct integer comparison — for example, if a single-value Version is greater than or equal to
16777216to check if it is greater than or equal to version1.0.0of AnnNet (16777216being equal to0x01,0x00,0x00,0x00, or more properly0x01000000, when big-endian decoded).
|
Tip
|
Bit-shifting can be used to extract individual version fields from a single-value version. Example in Goexamples/extractversion.go |
5.1.1.1.1. Major
| Length (Octets/Bytes) | Type |
|---|---|
|
Unsigned 8-Bit Integer |
The Major is the first byte in Version (if interpreted as a byte slice and not a big-endian unsigned 32-bit integer).
5.1.1.1.2. Minor
| Length (Octets/Bytes) | Type |
|---|---|
|
Unsigned 8-Bit Integer |
The Minor is the second byte in Version (if interpreted as a byte slice and not a big-endian unsigned 32-bit integer).
5.1.1.1.3. Patch
| Length (Octets/Bytes) | Type |
|---|---|
|
Unsigned 8-Bit Integer |
The Patch is the third byte in Version (if interpreted as a byte slice and not a big-endian unsigned 32-bit integer).
|
Note
|
The "patch" in SemVer may be more accurate to think of it as a "revision" than a "patch", but the term "revision" means something else in Semantic Version specification so "patch" is used here instead. |
5.1.1.1.4. Release Flag(s)
| Length (Octets/Bytes) | Type |
|---|---|
|
Byte/8-Bit Length Bitmask |
The Release Flag(s) field is the fourth byte in Version. It is not intended as an unsigned 8-bit integer but rather a bitmasked byte.
The collection of all flags is coalesced into a single byte on the wire — an unsigned 8-bit integer — with each flag occupying a single bit.
The following flags are currently defined:
| Integer | Flag | Name |
|---|---|---|
|
|
None; stable release. |
|
|
Pre-release |
|
|
Unstable |
|
|
Experimental |
Additionally, several "shorthand" flags are explicitly defined by the bit-wise OR'd combination of other flags:
| Integer | Flag | Expression | Name |
|---|---|---|---|
|
|
|
Beta release |
|
|
|
Alpha release |
A flag’s presence can be checked via a bit-wise AND against flag being equal to flag.
Example in Go
hasflag.gopackage main
import (
"fmt"
)
const anetNone uint8 = 0
const (
anetPreRel uint8 = 1 << iota
anetUnstable
anetExperiment
anetBeta = anetPreRel | anetUnstable
anetAlpha = anetBeta | anetExperiment
)
var (
// In Golang, a byte is exactly equivalent to a uint8.
// Use the same value extracted in the example `extractversion.go`.
// A value of 0x01 (1) indicates Pre-Release flag is set, with no other myFlags set.
myFlags byte = 0x01
)
func main() {
fmt.Printf("Flags:\t%d\t%#02x\n\n", myFlags, myFlags)
// Prints:
/*
Flags: 1 0x01
*/
for flag, flagNm := range map[uint8]string{
anetPreRel: "Pre-release",
anetUnstable: "Unstable",
anetExperiment: "Experimental",
anetBeta: "Beta release",
anetAlpha: "Alpha release",
} {
fmt.Printf(
"Has flag '%s' (%d, %#02x):\t%v\n\n",
flagNm, flag, flag, myFlags&flag == flag,
)
}
// Prints:
/*
Flags: 1 0x01
Has flag 'Pre-release' (1, 0x01): true
Has flag 'Unstable' (2, 0x02): false
Has flag 'Experimental' (4, 0x04): false
Has flag 'Beta release' (3, 0x03): false
Has flag 'Alpha release' (7, 0x07): false
*/
}5.1.1.2. Payload Length
| Length (Octets/Bytes) | Type |
|---|---|
|
Big-Endian Unsigned 32-Bit Integer |
The Payload Length indicates the length of the Payload, which is the arbitrary/implementation-specific data that follows the Standard Prefix (and thus the Payload Length is the last field in the Prefix).
It must be the length of the entirety of the payload that follows (but not including the size of the Prefix).
|
Note
|
|
5.1.2. Payload
The Payload is the arbitrary data that follows the Standard Prefix in the AnnNet Message Format.
It is an arbitrary length (specified/bounded by Payload Length) of payload data.
5.2. AnnNet Link
AnnNet Link operates on OSI layer 2 as an EtherType protocol.
|
Warning
|
For obvious reasons, this is not going to play well with other EtherTypes (e.g. VLAN/802.1Q tagging). Future versions of AnnNet may implement VLAN support. If VLAN support is added, it will be done so in a dedicated major release. |
It may send to either a directed MAC/physical address of a host or to the broadcast MAC/PHY(sical) address ff:ff:ff:ff:ff:ff.
Its source must be the MAC/PHYS address of the network interface it is sending from.
It must not traverse physical network boundaries (can’t, really, since it’s layer 2).
It currently uses the 0x88b5 EtherType by default, as AnnNet is still in experimental stages and this EtherType is reserved for prototyping per IEEE Std 802. (0x88b6 is another viable option for your implementation, as it too is reserved by IEEE Std 802 for prototyping.) See also IANA’s registration list.
If AnnNet is allocated a dedicated IEEE/IANA-registered EtherType, it will be implemented in a new major version release.
The AnnNet Message follows the EtherType value immediately:
Ethernet II Header (14 Bytes) |
|||
E:D |
E:S |
E:T |
|
Where:
- E:D
-
Destination MAC/PHY(sical) Address (6 Bytes)
- E:S
-
Source MAC/PHY(sical) Address (6 Bytes)
- E:T
-
EtherType (
0x88b5or0x88b6) (2 Bytes)
5.3. AnnNet Broadcast
AnnNet Broadcast operates on layer 3, making use of IPv4 (EtherType 0x0800) and/or IPv6 (EtherType 0x86dd).
5.3.1. IPv4
If IPv4, the AnnNet Broadcast sender may send to:
-
The IPv4 limited broadcast address
255.255.255.255/32(RFC 6890 § 2.2.2, 8190 § 2.2) -
Or a direct address of a host, IPv4 link-local (also known as Automatic Private IP Addressing/APIPA, RFC 3927) or not.
-
The target host/network must not traverse organization boundary (e.g. must not be routed directly across the Internet).
-
If using the 255.255.255.255/32 broadcast address, the source address must be a network-reachable address of the interface the message is sending from.
If using any other address, the source address must be an address reachable by the network/host the message is being sent to.
5.3.1.1. Message Format
The AnnNet Message follows the Options value immediately:
Ethernet II Header |
IP Header (20-60 Bytes) |
||||||||||||||||
V/IHL |
D/E |
Fragmentation |
|||||||||||||||
E:D |
E:S |
E:T |
VI:V |
VI:I |
DE:D |
DE:E |
IP:L |
IP:I |
IP:F |
IP:R |
IP:T |
IP:P |
IP:C |
IP:S |
IP:D |
IP:O |
|
Where:
- E:D
-
Destination MAC/PHY(sical) Address (6 Bytes)
- E:S
-
Source MAC/PHY(sical) Address (6 Bytes)
- E:T
-
EtherType (
0x86dd) (>= 2 Bytes; may be prefixed with VLAN information etc.) - VI:V
-
Version (4 Bits; see Addendum)
- VI:I
-
Internet Header Length (4 Bits; see Addendum)
- DE:D
-
DSCP (Differentiated Services Code Point; QoS/traffic class) (6 Bits; see Addendum)
- DE:E
-
ECN (Explicit Congestion Notification) (2 Bits; see Addendum)
- IP:L
-
Total size of IP header + payload (not to be confused with Payload Length) (2 Bytes)
- IP:I
-
Identification (used in fragmentation) (2 Bytes)
- IP:F
-
IP Flags (3 bits; see Addendum)
- IP:R
-
Fragmentation Offset (13 Bits; see Addendum)
- IP:T
-
TTL (1 Byte)
- IP:P
-
IP/Transport Protocol Number (1 Byte)
- IP:C
- IP:S
-
Source IPv4 Address (32 Bits/4 Bytes)
- IP:D
-
Destination IPv4 Address (32 Bits/4 Bytes)
- IP:O
-
Options (Optional) (See the IANA Registered IP Parameters for details) (Variable Length)
5.3.2. IPv6
If IPv6, the AnnNet Broadcast sender may send to:
-
The multicast addresses (
ff0x) with the following scopes (scop) (RFC 3513 § 2.7, 4291 § 2.7, 7346 § 2, see also IANA IPv6 Multicast Registry)-
except as reserved by other IANA/IETF/IESG-recognized protocols (i.e.
OSPFIGP,NDP, et. al.):-
Scope
1(0x0001), Interface-Local -
Scope
2(0x0002), Link-Local -
Scope
4(0x0004), Admin-Local -
Scope
5(0x0005), Site-Local -
Scope
8(0x0008), Organization-Local
-
-
A generally safe address would be
ff02::1(All Nodes, Link-Local) but refer to the IANA registry to select the most appropriate multicast address(es).
-
-
Or a direct IPv6 Link-Local Address (LLA) of a host (RFC 3513 § 2.5.6, 3927, 4291 § 2.5.6, 7404 (tangentially))
-
Or a direct IPv6 Unique Local Address (ULA) of a host (RFC 4193)
If using a multicast address, the source address must be a network-reachable address of the interface the message is sending from.
If using any other address, the source address must be an address reachable by the network/host the message is being sent to.
5.3.2.1. Message Format
The AnnNet Message follows the Destination Address value immediately:
Ethernet II Header |
IP Header (40 Bytes) |
||||||||||
V/TC/Flow (4 Bytes) |
|||||||||||
E:D |
E:S |
E:T |
VTF:V |
VTF:T |
VTF:F |
IP:L |
IP:N |
IP:H |
IP:S |
IP:D |
|
Where:
- E:D
-
Destination MAC/PHY(sical) Address (6 Bytes)
- E:S
-
Source MAC/PHY(sical) Address (6 Bytes)
- E:T
-
EtherType (
0x86dd) (>= 2 Bytes; may be prefixed with VLAN information etc.) - VTF:V
-
Version (4 Bits; see Addendum)
- VTF:T
-
Traffic Class (8 Bits) (not 1 Byte; see Addendum)
- VTF:F
-
Flow Label (20 bits; see Addendum)
- IP:L
-
IP Payload Length (not to be confused with Payload Length) (2 Bytes)
- IP:N
-
Next Header (transport protocol number) (1 Byte)
- IP:H
-
Hop Limit (1 Byte)
- IP:S
-
Source IPv6 Address (128 Bits/16 Bytes)
- IP:D
-
Destination IPv6 Address (128 Bits/16 Bytes)
5.3.3. Internet Protocol Number
AnnNet currently uses the IPv4 protocol/IPv6 Next Header protocol number 253 (0xfd) by default, as AnnNet is still in experimental stages and this protocol is reserved for experimentation per IANA. (254, 0xfe, is another viable option for your implementation as it too is reserved by IANA for experimentation.)
If AnnNet is allocated a dedicated IANA-registered Protocol/Next Header, it will be implemented in a new major version release.
6. Limitations
-
AnnNet messages must fit into a single frame on the network it is being sent/received on. If message continuation or longer messages are wanted/desired, then it is up to the implementer to add a mechanism for this within their implementation’s payload.
-
Likewise for checksumming; while most NICs will automatically handle the standard CRC32 Frame Check Sequence at the end of the entire frame (AnnNet Link is still Ethernet II), if you require checksumming within your application for payloads it must be accounted for by your application. If you are using hardware that doesn’t automatically append/strip the FCS, your application must also account for that as well.
-
For AnnNet Broadcast over IPv4, ensure that you are including the 16-bit "Internet checksum" of the header (see RFCs 1071, 1141, and 1624).
Most kernels can/will automatically insert this (e.g. on Linux, withIPPROTO_RAW/raw sockets with theIP_HDRINCLoption, seeraw(7)), but if your implementation doesn’t/can’t use such a mechanism then you must do so yourself.
IPv6 does not require a header checksum.
-
7. (F)AQ/FUQ (Anticipated, Frequently Asked/Anticipated/Unasked Questions)
7.1. Why do you reference the OSI model instead of the TCP/IP model? It’s old/outdated/inaccurate.
Hold onto your seat.
Several reasons:
-
The OSI model is standardized. There is only a single, canonical, authoritative "OSI model" when it comes to network models.
References are unambiguous. Boundaries between layers and their definitions are mostly clear. (And the ISO/IEC provides supplementals for any ambiguities that arise over the years.)
As for "the TCP/IP model", which one are you referring to?
There’s no less than seven different models that are referred to as "the TCP/IP model". (The linked-to article doesn’t even mention e.g. the DoD model.) And they’re all different in ways enough to make this confusing.
-
The OSI model is more nuanced and detailed.
When one is talking about IP protocols and service protocols in the same context, things get very confusing very quickly. One can say "protocol" and it can apply to either ambiguously.
If instead one says "L2 protocol" or "layer 2 protocol" it’s immediately clear that it operates without (IP) addressing, or "L3 protocol"/"layer 3 protocol" and it’s immediately clear that a protocol that DOES use (IP) addressing is being referenced.
7.2. Why Shouldn’t I Use AnnNet for Regular Traffic?
On a purely technical level, there’s nothing stopping you from doing so (aside from MTU windows, so you’d need to find some way of implementing message continuation, ordering, checksumming, etc. — at that point, just use UDP multicast or something else).
But AnnNet is designed to be a lightweight announcement protocol for a local (i.e. within the same subnet/link system) network.
It is designed to act like e.g.:
-
Lease requests for:
etc., but with (very small amounts of) arbitrary data making it "plug-and-play" with >= L3 protocols/services' configuration.
It explicitly avoids defining any formation of payloads, message format, or the like — because it is designed to be entirely agnostic of whatever use case it is implemented for.
However, AnnNet strongly encourages the use of WireProto for payload packing due to its minimal overhead, its strong hierarchical structuring, and its flexibility.
|
Warning
|
Future versions of AnnNet may require use of WireProto (but WireProto itself is a very loose and flexible format, and would not add much overhead). If this requirement is put in place, it will be in its own major revision. |
If one needs a much more robust solution for anything beyond e.g. announcement messages, NATS may be useful for actual messaging between known members. (AnnNet would then be used in this case to provide a mechanism for making members known/discovered with no explicit configuration.)
|
Note
|
NATS also does not define any sort of payload format in its encapsulated payloads; most implementations tend to use ProtoBuf/Protocol Buffers, MessagePack, JSON, or the like. |
8. Addendum/Errata/Administrivia
8.1. Bitpacked Fields
Certain fields in IP headers are less than 1 byte or don’t align to a clean byte boundary on their own, and therefore generally require bitwise operations to read/encapsulate meaningful values within them.
8.1.1. IP Version, IHL (IPv4)
The IP version and IHL combined make up a single byte, with four-byte "nibbles" each.
|
Note
|
The IHL is calculated as the number of "32-bit words" in the IP header. In other words, Or, alternatively, Since the V/IHL is a fixed size, this does not cause a recursion/chicken-egg problem. |
To create the Version/IHL value, the Version (always 4 because IPv4) is packed as a big-endian 8-bit unsigned integer, and is then bit-shifted to the left by 4 bits and bitwise-OR'd with the IHL (as a big-endian 8-bit unsigned integer bitwise-AND-masked to the lower bits via 0x0f/15).
To retrieve the Version and IHL, the value is bit-shifted to the right by 4 bits and cast as an 8-bit unsigned integer (this is the Version, 4), and the original value is also bitwise-AND'd with the lower bits via 0x0f (15) and cast as an unsigned 8-bit integer to get the IHL.
Example in Go
package main
import (
`fmt`
`log`
"strconv"
)
const (
vihlBits string = "01000101" // [0100 0101], or 69 (0x45)
ipVer uint8 = 0x04 // 4; unused in this program, but represented for completion's sake.
)
var (
vihlLowerMask uint8 = 0x0f // 15
)
func ToVIHL(ver, ihl uint8) (vihl byte) {
// In Go, a byte is exactly equal to a uint8
// so type casting/conversion is unnecessary here.
vihl = (ver << 4) | (ihl & vihlLowerMask)
return
}
func FromVIHL(vihl byte) (ver, ihl uint8) {
ver = vihl >> 4
ihl = vihl & vihlLowerMask
return
}
func main() {
var err error
var u64 uint64
var vihl byte
var ver uint8
var ihl uint8
// Given a V/IHL of vihlBits (see const at top)...
if u64, err = strconv.ParseUint(vihlBits, 2, 8); err != nil {
log.Panicln(err)
}
vihl = uint8(u64)
// Prints:
/*
V/IHL is: 69 (0x45)
*/
fmt.Printf("V/IHL is:\t\t%d (%#02x)\n", vihl, vihl)
ver, ihl = FromVIHL(vihl)
// Prints:
/*
Version: 4 (0x04)
IHL: 5 (0x05)
*/
fmt.Printf(
"Version:\t\t%d (%#02x)\n"+
"IHL:\t\t\t%d (%#02x)\n",
ver, ver,
ihl, ihl,
)
vihl = ToVIHL(ver, ihl)
// Prints:
/*
Confirmed V/IHL: 69 (0x45)
*/
fmt.Printf("Confirmed V/IHL:\t%d (%#02x)\n", vihl, vihl)
}8.1.2. DSCP, ECN (IPv4)
The DSCP and ECN fields are combined to make up a single byte with a 6-bit and 2-bit "nibble" each, respectively.
|
Note
|
The actual values for DSCP and ECN are sort of scattered about through several different RFCs. Notable DSCP mentions are: Notable ECN mentions are: |
Example in Go
package main
import (
`fmt`
`log`
"strconv"
)
const (
/*
This is a nonsensical example.
The actual values are sort of scattered around a multitude of RFCs.
*/
deBits string = "01010101" // [0101 0101], or 85 (0x55)
)
var (
deLowerMask uint8 = 0x03 // 3
)
func ToDE(dscp, ecn uint8) (de byte) {
de = (dscp << 2) | (ecn & deLowerMask)
return
}
func FromDE(de byte) (dscp, ecn uint8) {
dscp = de >> 2
ecn = de & deLowerMask
return
}
func main() {
var err error
var u64 uint64
var de byte
var dscp uint8
var ecn uint8
// Given a D/E of deBits (see const at top)...
if u64, err = strconv.ParseUint(deBits, 2, 8); err != nil {
log.Panicln(err)
}
de = uint8(u64)
// Prints:
/*
D/E is: 85 (0x55)
*/
fmt.Printf("D/E is:\t\t%d (%#02x)\n", de, de)
dscp, ecn = FromDE(de)
// Prints:
/*
DSCP: 21 (0x15)
ECN: 1 (0x01)
*/
fmt.Printf(
"DSCP:\t\t%d (%#02x)\n"+
"ECN:\t\t%d (%#02x)\n",
dscp, dscp,
ecn, ecn,
)
de = ToDE(dscp, ecn)
// Prints:
/*
Confirmed D/E: 85 (0x55)
*/
fmt.Printf("Confirmed D/E:\t%d (%#02x)\n", de, de)
}8.1.3. Flags, Fragmentation Offset (IPv4)
The (Fragmentation) Flags and Fragmentation Offset fields are combined to make up 2 bytes with a 3-bit and 13-bit "nibble"/"word" each, respectively.
The Fragmentation Flags and Offset are defined in RFC 791 § 3.1 and part of RFC 815.
Example in Go
package main
import (
`fmt`
`log`
"strconv"
)
const (
/*
This is a nonsensical example.
*/
fragBits string = "0101010101000100" // [0101 0101 0100 0100], or 21828 (0x5544)
)
var (
fragOffset uint16 = 0x000d // 13
fragFlagMask uint16 = 0x07 // 0b0000111 to mask 3 bits
fragOffsetMask uint16 = 0x1fff // 8191, a 13-bit mask
)
func ToFrag(flags, fo uint16) (frag uint16) {
frag = (flags << fragOffset) | (fo & fragOffsetMask)
return
}
func FromFrag(frag uint16) (flags, fo uint16) {
flags = (frag >> fragOffset) & fragFlagMask
fo = frag & fragOffsetMask
return
}
func main() {
var err error
var u64 uint64
var frag uint16
var flags uint16
var fo uint16
// Given a fragmentation configuration of fragBits (see const at top)...
if u64, err = strconv.ParseUint(fragBits, 2, 16); err != nil {
log.Panicln(err)
}
frag = uint16(u64)
// Prints:
/*
Frag is: 21828 (0x5544)
*/
fmt.Printf("Frag is:\t\t%d (%#04x)\n", frag, frag)
flags, fo = FromFrag(frag)
// Prints:
/*
Flags: 2 (0x0002)
Fragmentation Offset: 5444 (0x1544)
*/
fmt.Printf(
"Flags:\t\t\t%d (%#04x)\n"+
"Fragmentation Offset:\t%d (%#04x)\n",
flags, flags,
fo, fo,
)
frag = ToFrag(flags, fo)
// Prints:
/*
Confirmed Frag: 21828 (0x5544)
*/
fmt.Printf("Confirmed Frag:\t\t%d (%#02x)\n", frag, frag)
}8.1.4. IP Version, Traffic Class, Flow Label (IPv6)
IPv6 thankfully only has one bitpacking in the header. Unfortunately, it’s a triple-whammy.
These are mostly defined in:
-
RFC 8200 § 3 for the header format
-
RFC 8200 § 7 for the Traffic Class field
-
RFC 8200 § 6 for the Flow Label field
The IP Version takes up 4 bits (just as in IPv4, except it will always be 6 this time), the Traffic Class field takes up 8 bits, and Flow Labels takes up 20 bits for a total of 32 bits (4 bytes).
Example in Go
package main
import (
`fmt`
`log`
"strconv"
)
const (
/*
This is a nonsensical example.
*/
vtfBits string = "01100000000000000000000000000000" // [0110 0000 0000 0000 0000 0000 0000 0000], or 1610612736 (0x60000000)
)
var (
vtfVOffset uint32 = 0x0000001c // 28
vtfVFlagMask uint32 = 0x0000000f // Mask to 4 bits
vtfTOffset uint32 = 0x00000014 // 20
vtfTFlagMask uint32 = 0x000000ff // mask to 8 bits
vtfFlowMask uint32 = 0x0000ffff
)
func ToVTF(ver, tc, flow uint32) (vtf uint32) {
vtf = (ver << vtfVOffset) | (tc << vtfTOffset) | (flow & vtfFlowMask)
return
}
func FromVTF(vtf uint32) (ver, tc, flow uint32) {
ver = (vtf >> vtfVOffset) & vtfVFlagMask
tc = (vtf >> vtfTOffset) & vtfTFlagMask
flow = vtf & vtfFlowMask
return
}
func main() {
var err error
var u64 uint64
var vtf uint32
var ver uint32
var tc uint32
var flow uint32
// Given a fragmentation configuration of vtfBits (see const at top)...
if u64, err = strconv.ParseUint(vtfBits, 2, 32); err != nil {
log.Panicln(err)
}
vtf = uint32(u64)
// Prints:
/*
VTF is: 1610612736 (0x60000000)
*/
fmt.Printf("VTF is:\t\t\t%d (%#04x)\n", vtf, vtf)
ver, tc, flow = FromVTF(vtf)
// Prints:
/*
VTF is: 1610612736 (0x60000000)
Version: 6 (0x0006)
Traffic Class: 0 (0x0000)
Flow Label: 0 (0x0000)
*/
fmt.Printf(
"Version:\t\t%d (%#04x)\n"+
"Traffic Class:\t\t%d (%#04x)\n"+
"Flow Label:\t\t%d (%#04x)\n",
ver, ver,
tc, tc,
flow, flow,
)
vtf = ToVTF(ver, tc, flow)
// Prints:
/*
Confirmed V/T/F: 1610612736 (0x60000000)
*/
fmt.Printf("Confirmed V/T/F:\t%d (%#02x)\n", vtf, vtf)
}