The Primnet protocol suite is a set of protocols for negotiating and performing reliable, highly-flexible transfers of text and inventory items (including scripts) between two primitives ("prims") within a Second Life region and, with the use of Primnet routers, between different regions, without the use of external servers. Primnet Network Interface Controllers (NICs) and routers can be configured to use your own external HTTP server for more resilient and flexible cross-region communications with private dynamic DNS and nameserver support.
Primnet communicates via chat, which only supports strings up to 1024 characters and has no ability to reach beyond 100 meters or the region border, depending on which function is used. Primnet uses a structured datagram format to provide encapsulation and headers so that Primnet routers can act as a mesh network.
Each Primnet script, or NIC, can be controlled via llMessageLinked to listen to up to 65 simultaneous channels via llListen and transmit over any channel.
Communiating over Primnet requires only an instance UUID of a prim. Primnet networks are region-scope by default, primarily using llRegionSayTo, but setting per-request flags allows the NIC to use less secure communication methods or even over Primnet routers that are owned by other users.
The layered network specifications allow Primnet to intrinsically provide reliable chat transmission of strings longer than 1024 characters and automatic nameserver lookups across multiple regions without using external servers (although Primnet is designed to support external HTTP servers for flexibility and reliability). Primnet also negotiates and performs secure transfers of prim inventory using llGiveInventory and llRemoteLoadScriptPin.
The network level is a series of layers that implement the actual communication network of Primnet. These layers are based off the Open Systems Interconnection (OSI) model.
Each layer includes a header that is defined as the length of the payload in two hexadecimal bytes cast as a two-character string, followed by a four-character protocol identifier. This allows Primnet to immediately identify Primnet traffic and recursively define payloads within it, as well as process up to four packets in a single frame by concatenating them, since the payload length cannot exceed 0xFA (250), resulting in a combined length for the packet of up to 256 characters, or one quarter of the maximum length of a string sent via chat (1024).
- Layer 1 (physical):
- The physical layer consists of llRegionSay, llRegionSayTo, llShout (for SDTP bridges), llHTTPRequest (for HDTP bridges), llGiveInventory (for ITP), and llRemoteLoadScriptPin (for STP), as well as a variety of other functions to perform higher-level operations such as same-owner checks, DNNS lookups, et cetera. The header for this layer is "00!PN!", which is used to identify traffic compliant with the Primnet protocol suite for processing, and the "00"-length payload is an empty string.
- Layer 2 (data link):
- HTTP Data Tunneling Protocol (HDTP): The protocol used to transfer Primnet packets between arbitrary locations on the grid. HDTP bridges do not rely on a path of regions between two points, but require manual setup and possible repair. Using an external OARS server can avoid these issues, making HDTP extremely reliable but reliant on an external server, which costs money and time to maintain. HDTP tunnels are rate-limited to prevent network flooding. Functionally similar to tunneling protocols.
- Shout Data Tunneling Protocol (SDTP): The protocol used to transfer Primnet packets across region crossings. SDTP bridges require no maintenance because they automatically communicate with other SDTP bridges within 100 meters, but using SDTP may cause network stability issues if there is no path through the network between two regions due to weekly region restarts or other downtime. SDTP tunnels are rate limited to prevent flooding and store a configurable log of packet UUIDs to identify and avoid network loops. SDTP bridges can be owned by different agents, but if so, owner-only traffic will be blocked. Functionally similar to tunneling protocols.
- Layer 3 (network):
- Layer 3 is functionally served by prim instance UUIDs, which act as addresses in the Primnet network. Since it is computationally inefficient to compress these addresses in a lossless way, Primnet uses UUIDs directly, except that the standard protocol suite strips dashes out to save characters.
- Layer 4 (transport):
- Ordered Packet Protocol (OPP): The protocol used to transfer packets in sequence via Primnet. Functionally similar to the Transmission Control Protocol (TCP). The
[service]
parameter is functionally similar to a port number.
- Layer 5 (session):
- Data Transfer Protocol (DTP): Transfers a text string, including strings beyond the 1024 characters permitted by llRegionSay, over OPP.
- Inventory Transfer Protocol (ITP): Transfers an inventory item using llGiveInventory over OPP. Cannot be used through HDTP or SDTP.
- Script Transfer Protocol (STP): Transfers a script using llRemoteLoadScriptPin over OPP. Cannot be used through HDTP or SDTP.
- Layer 6 (presentation):
- Primnet NIC Control Interface (PNCI): A standard for controlling Primnet NICs that implement layers 5 and lower using llMessageLinked from scripts in the same object.
- Layer 7 (application):
- Prim Nameserver System (PNS): A standard that resolves registered hostnames into prim UUIDs. NICs that incorporate PNS can look up hostnames via Primnet to an in-world PNS nameserver or an external HTTP-based PNS nameserver, both configurable at runtime.
- Prim Domain Name System (PDNS): A specification for hierarchical and distributed PNS name service. Since Primnet networks are not designeed to be reliant on external HTTP services, and local network scales likely do not call for distributed PNS name service, PDNS is left as a specification to be implemented optionally by private PDNS registrars.
- NBS PDNS Service: An HTTP service that provides a hierarchical and distributed PNS name service hosted externally by Northbridge Business Systems (NBS). NICs that incorporate the NBS PDNS as their PNS resolver can look up hostnames in the NBS PDNS system.
- Dynamic PNS Update Protocol (DPUP): A standard API for issuing RSA-signed updates to PNS servers to update prim UUIDs as needed. DPUP allows end-users to keep PNS hostnames updated via Primnet NICs themselves instead of needing to rely on PNS registrars for manual hostname record updates.
The Primnet Protocol Suite includes additional miscellaneous specifications:
- Display Name Nameserver Specification (DNNS): A method of storing arbitrary types of records in a specific Second Life agent's display name. It is used to identify authoritative Primnet prims without relying on a known PNS server by prim UUID or HTTP URL. However, display name changes have very long cooldowns (7 days) and cannot be automated without the use of an externally-hosted bot.
- Prim Attribute Nameserver Specification (PANS): A method of storing arbitrary types of records in a specific Second Life prim's name, description, hovertext, and other values readable via llGetObjectDetails. PANS servers must be specified by key and must be in the same region to be read.
- Chat Local Area Network (CLAN) Channel Band: A standard channel allocation of 802110000 (the default public RLAN channel) through 802119999, allocated as CLAN channels 0 through 9999. CLAN channels are designated for use as public, general-purpose channels for Primnet end-users. Functionally similar to Wi-Fi.
- Grid Wide Web (GWW): A web server standard that uses Primnet. Functionally similar to the World Wide Web (WWW).
¶ Channel Bands
The below channel ranges are suggested. Primnet has no enforcement mechanism for controlling channels, nor does it assign channels exclusively for specific uses.
These channels are chat channels, so conflicts may still occur. Primnet itself is a channel-agnostic message protocol by design, so scripts are designed to quickly reject any messages that are missing an Primnet Protocol header. Chat channel separation is encouraged only to reduce server load, since Primnet scripts must process the incoming message to determine if it is relevant to them, even if it is not.
- 0: prohibited (PUBLIC_CHANNEL)
- 1 through 80210999: unassigned, allowed for private preshared use
- 802110000: reserved, default channel for LPNR
- 802110001 through 802119999: reserved, alternate channels for LPNR
- 802120000 through 2147483646: unassigned, allowed for private pre-shared use
- 2147483647: prohibited (DEBUG_CHANNEL)
- -1 through -2147483647: unassigned, allowed for private pre-shared use
- -2147483648: reserved, used by SDTP
- This channel is used for cross-region shouts. SDTP bridges repeat any Primnet traffic received on the channels they listen to that can't be routed in the same region. Therefore, while safe, it's not recommended to use this channel for other purposes because of the possibility of flooding and packet loss.