path: root/docs/server_tokens.txt

This is a list of all tokens used by InspIRCd at the time of writing for server to server communication. Module coders may find this information 
useful when syncronising module data between different servers on the mesh. All tokens are case sensitive. Token names are given, however these are 
just a way of identifying the token, so if you hear developers talking of the 'CHGNAME token' you can be sure they are talking about the 'a' symbol.

Modules should try to avoid low ascii values. The only illegal token characters are ASCII 0, ASCII 13, and ASCII 10.

--------------------------------------------------------------------------------
Compatibility Translations

InspIRCd will translate some RFC-style commands into mesh tokens, to maintain compatibility with some services packages. This only occurs if the 
server is a U-type link (see the tokens below for an explaination). The translated commands are:

    * 433 - Translated to *
    * 432 - Translated to *
    * PING - Translated to *
    * NOTICE - Translated to V
    * PRIVMSG - Translatd to P
    * QUIT - Translated to Q
    * SQUIT - Translated to &
    * SVSMODE - Translated to m
    * SVS2MODE - Translated to m
    * MODE - Translated to m
    * KICK - Translated to k
    * KILL - Translated to K
    * SVSJOIN - Translated to J 

IMPORTANT NOTE: Where the prefix on these commands is confused with a uniqueness sum (see below) the uniqueness sum for the command is set to '*' 
which is a wildcard sum and is always accepted by all servers.

--------------------------------------------------------------------------------
Uniqueness Sums

Each command on the mesh is prefixed by a 'uniqueness sum' which is a random sequence (usually of 7 or 8 characters) which identifies that command. 
Each server should keep a queue of the most recent commands sums, and should store up to 128 of the sums. When there are 128 sums in the list the 
oldest should be removed from the list and the newest put into the list in its place, keeping constant 'rotation' of sums. The current implementation 
simply generates the sums via the rand() function, there is no documented system for creating these uniqueness values, it is up to the person 
implementing the system how these fields are generated, so long as there is minimal chance of a collision with other active sums on the network.

If any server receives a command with a sum which is already in its list (no matter what the source of the command within the mesh is, to compensate 
for redirect tokens, see below in the command specification) then the entire command is to be silently dropped without any attempt at processing.

The sum value '*' should not be used, and is a special value which should cause all connected servers to always allow the command. Services servers 
which do not directly support the mesh protocol, and must have their commands rewritten, may generate commands which have this sum.

To avoid confusing parsers which are designed to process 'standard' irc server to server communication, each uniqueness sum is prefixed with a : 
symbol. For example:

:uniqueness-sum TOKEN param param :final param

This makes it a simple matter to fetch the uniqueness sum from the 'source' field in the software's API, and process the rest of the data within the 
parameters array, or however your software passes its data. 

--------------------------------------------------------------------------------
Mesh Tokens
--------------------------------------------------------------------------------
AuthCookie: - Token

Syntax: - <authcookie> <servername> :<serverdesc>

When a server links into the mesh, it passes an Auth Cookie with its link request (in an S token). All other servers on the mesh respond by connecting 
back to the initiating server and issuing this token with a valid auth cookie. If the auth cookie is valid, the server accepts their mesh link, 
otherwise it rejects it.
--------------------------------------------------------------------------------
Inbound Server: S Token

Syntax: S <servername> <password> <port> :<description>

To initiate a mesh link, a server must connect to the port given in its <connect> tag, and issue this command. The port number is the port number the 
initiator is listening on for incoming server connections, it must be provided so that other servers in the mesh can link back and issue auth cookies. 
This is known as an 'active' connect, e.g. the initiator always uses the uppercase S token.
--------------------------------------------------------------------------------
Set version reply: v Token

Syntax: v <servername> <arbitary version string>

This token indicates the version string of a server on the mesh. Rather than send it each time it is requested, inspircd simply updates the mesh with 
its details either on bursting or if/when the data changes.
--------------------------------------------------------------------------------
Outbound Server: s Token

Syntax: s <servername> <password> <port> :<description>

Upon receiving a valid S token, if the password and servername are accepted, the receiving server replies with this token. It is a different token to 
S to avoid loops, and diffrentiate between initiator and receiver in the linking process. Once the initiator accepts the s token, the link is 
established and the burst begins.
--------------------------------------------------------------------------------
Non-Mesh Server: U Token

Syntax: U <servername> <password> :<description>

The U token is similar to the S token in that it initiates a server to server link, but it is designed primarily to link systems which are not able to 
become a fully meshed node, for example IRC Services packages. Upon a successful "U type" (as this is known) authentication, the other servers are 
informed of the introduction of the server via means of a H token, but will never connect back to it, they will route all messages via its uplink 
(messier than meshing it, but if the application is physically incapapable of joining the mesh, this is what must be done).
--------------------------------------------------------------------------------
Error: E Token

Syntax: E :<error message>

The E token indicates a protocol error, or invalid credentials etc, and immediately after an E token the connection is dropped. Failure to 
authenticate during a link is usually the cause of such tokens being sent.
--------------------------------------------------------------------------------
Begin Netburst: Y Token

Syntax: Y <time>

The Y token indicates the start of the netburst. The time value is used simply to correctly calculate the length of the burst (a similar token is sent 
at the end of the netburst which also contains a time, allowing the delta to match up correctly without clock syncronization)
--------------------------------------------------------------------------------
Set Auth Cookie: ~ Token

Syntax: ~ <new auth cookie>

The ~ token adds a new auth cookie to the servers allowed list. A server may permit multiple auth cookies at any one time to cope with resyncs.
--------------------------------------------------------------------------------
Begin Mesh: + Token

Syntax: + <servername> <portnumber> <authcookie>

When a server successfully initiates a connection, it sends this token out to all servers it already has in its mesh, which inform all the servers to 
connect back upon the servername given, on the port provided, using the given auth cookie. When this occurs all servers will send the "-" token to it 
upon connection.
--------------------------------------------------------------------------------
Send Routing Table: $ Token

Syntax: $ <source server> <reachable server> [<reachable server>...]

The $ token is a means of transmitting routing tables around the mesh. A server sends a list of servers it can reach directly. These tables are 
updated periodically. If a server cannot be reached directly, the ircd will scan the routing tables it has looking for an ircd which can reach it 
directly, and inform that server to route the message for it.
--------------------------------------------------------------------------------
SQUIT: & Token

Syntax: & <servername>

The & symbol is sent by a server when it leaves the mesh, or by servers which detect that other servers are completely unroutable. Upon receipt of an 
& symbol, the local server will instantly and recursively (according to its routing table) remove all users along that route.
--------------------------------------------------------------------------------
Reroute: R Token

Syntax: R <target-server> <anything>

This is the R or 'reroute' token, which indicates the <anything> provided should be instantly routed to <target-server> and only to <target-server> 
without processing it any further. Usually the server will receive these if it is the only available and direct route to <target-server>.
--------------------------------------------------------------------------------
PONG: ? Token

Syntax: ?

This token is used as a PONG, and has no parameters or responses. Only locally connected servers send pings (! token) to their peers, so no source is 
required.
--------------------------------------------------------------------------------
NOP: * or : Token

Syntax: *|:

This token is a NOP (No-Operation) message.
--------------------------------------------------------------------------------
USER: N Token

Syntax: N <time> <nick> <host> <displayed-host> <ident> <modes> <ipaddress> <server> :<GECOS>

This token introduces a new user into the network. The server specified by <server> is responsible for all local checking of that user's actions, such 
as channel joins, PINGs, QUITs etc. The <time> value is a unix epoch time, and the <ipaddress> field is the user's ip address in dotted decimal 
(1.2.3.4) form.
--------------------------------------------------------------------------------
CHGNAME: a Token

Syntax: a <nick> :<GECOS>

Change realname (GECOS) of a connected user.
--------------------------------------------------------------------------------
CHGHOST: b Token

Syntax: b <nick> :<displayed-host>

Change the displayed hostname of a connected user (vhost) to the one provided. No checking of this value is done, it is up to the local server to 
check this value before sending it out onto the mesh.
--------------------------------------------------------------------------------
TOPIC: t Token

Syntax: t <nick> <channel> :<topic>

This token indicates a user set or changed a channel topic. This token should not be used in netjoins, the T token (with a timestamp) should be used 
instead to check which topic 'wins'.
--------------------------------------------------------------------------------
INVITE: i Token

Syntax: i <nick> <source> <channel>

Invite a user to a channel. The user specified by <nick> is invited to channel <channel> by <source>.
--------------------------------------------------------------------------------
KICK: k Token

Syntax: k <source> <dest> <channel> :<reason>

This token indicates a user was kicked from a channel.
--------------------------------------------------------------------------------
NICK: n Token

Syntax: n <old nick> <new nick>

Indicates a nickchange.
--------------------------------------------------------------------------------
JOIN: J Token

Syntax: J <nick> [permissions]<channel> [[permissions]<channel>...]

This token indicates that a user is joining one or more channels, and indicates their privilages upon said channel. For example: "J MrFoo @#bar +#qux 
#baz".
--------------------------------------------------------------------------------
SERVERTOPIC: T Token

Syntax: T <settime> <nick> <channel> :<topic>

This token indicates the server set or changed a channel topic. This token should be used in netjoins to check which topic 'wins'.
--------------------------------------------------------------------------------
SERVERMODE: M Token

Syntax: M <target> <modes> [mode-parameters]

This token sets channel or user modes (depending upon the target given). The server sets the modes with this token as opposed to the 'm' token (lower 
case 'm') in which a user sets the modes.
--------------------------------------------------------------------------------
MODE: m Token

Syntax: m <source> <target> <modes> [mode-parameters]

This token sets channel or user modes (depending upon the target given). The user given as <source> sets the modes with this token. You cannot specify 
<source> as a server, for this you must use the M token instead.
--------------------------------------------------------------------------------
PRIVMSG: P Token

Syntax: P <source> <target> :<text>

The P token indicates a PRIVMSG between a user and a channel or other user. Target may be either a channel, or a user, source may only be a user.
--------------------------------------------------------------------------------
NOTICE: V Token

Syntax: V <source> <target> :<text>

The V token indicates a NOTICE between a user and a channel or other user. Target may be either a channel, or a user, source may only be a user.

As of 1.0 Beta 4, there are two special cases for the V token, in which the target may be one of:

    * "*" - Specify a target of * to send the notice to all users upon that server.
    * "@*" - Specify this target to send to all opers upon that server and place the nickname of the originator within the body of the notice. 

--------------------------------------------------------------------------------
PART: L Token

Syntax: L <nick> <channel> :<reason>

This token indicates a user is leaving a channel with the given reason. The reason field is not optional, if there is no reason the field is just a 
colon (":").
--------------------------------------------------------------------------------
QUIT: Q Token

Syntax: Q <nick> :<reason>

The Q token indicates a user is quitting. The reason given is not optional, if none is specified the field contains just a colon symbol (":").
--------------------------------------------------------------------------------
Non-Mesh-Add: H Token

Syntax: H <servername>

Adds a U-Type server to the map without any other information. This is used to maintain links to services.
--------------------------------------------------------------------------------
KILL: K Token

Syntax: K <source> <nick> :<reason>

This token is the KILL token, which indicates a user is to be KILLed. Its use generates a QUIT token from the local server. Source may only be a user, 
not a server, as server kills are always handled locally.
--------------------------------------------------------------------------------
WALLOPS: @ Token

Syntax: @ <source> :<text>

This token sends a global WALLOPS. Source may only be a user, not a server.
--------------------------------------------------------------------------------
GLINE: # Token

Syntax: # <mask> <who-set-it> <time-set> <duration> :<reason>

Adds a permenant or timed G-Line to all servers on the mesh. The mask contains both the ident and hostname in ident@host form. <who-set-it> is 
arbitary text, and can be a user or a server.
--------------------------------------------------------------------------------
UNGLINE: . Token

Syntax: . <mask> <who>

Removes a G-Line from all servers on the mesh.
--------------------------------------------------------------------------------
QLINE: { Token

Syntax: { <mask> <who-set-it> <time-set> <duration> :<reason>

Adds a permenant or timed Q-Line to all servers on the mesh. The mask contains a nickname pattern. <who-set-it> is arbitary text, and can be a user or 
a server.
--------------------------------------------------------------------------------
UNQLINE: [ Token

Syntax: [ <nickmask> <who>

Removes a Q-Line from all servers on the mesh.
--------------------------------------------------------------------------------
ZLINE: } Token

Syntax: } <mask> <who-set-it> <time-set> <duration> :<reason>

Adds a permenant or timed Z-Line to all servers on the mesh. The mask contains an ip address mask. <who-set-it> is arbitary text, and can be a user or 
a server. If duration is 0, the ban is permenant.
--------------------------------------------------------------------------------
UNZLINE: ] Token

Syntax: ] <mask> <who>

Deletes a Z-Line from all servers on the mesh.
--------------------------------------------------------------------------------
OPERTYPE: | Token

Syntax: | <nick> <opertype>

Sets the opertype of an oper to the given string. This is done so that all ircds are aware of what the oper types of each oper is globally. 
Configuration of oper types and classes should match network wide.
--------------------------------------------------------------------------------
End-Netburst: F Token

Syntax: F <time>

This token indicates the end of the netburst, for more information see the 'Y' token.
--------------------------------------------------------------------------------
SERVICE1: / Token

Syntax: / <nickserv nick>

This token is used to indicate the name of a nickname service and is reserved for future use.
--------------------------------------------------------------------------------
End-Netburst-NM: f Token

Syntax: f <time>

This is identical in syntax and operation to the F token, except its use does not cause mesh links, as in the server is added in a disconnected state 
to force routing through its uplink. Used by services servers.
--------------------------------------------------------------------------------
Begin-Burst: X Token

Syntax: X <time>

This token when sent indicates that the server is ready to receive the other servers (recipient of this token) netburst data.
--------------------------------------------------------------------------------
Example Server Conversation

This is an example of a services server linking to an InspIRd server. During the 'conversation' two users connect, one of which is an oper, one of 
which is a normal user.

>> U services-dev.chatspike.net xxxxxxxx :Developer Services
>> / NickServ
>> N 1111691007 OperServ chatspike.net chatspike.net services-dev +oio 0.0.0.0 services-dev.chatspike.net :Operator Server
>> N 1111691007 Global chatspike.net chatspike.net services-dev +oio 0.0.0.0 services-dev.chatspike.net :Global Noticer
>> N 1111691007 NickServ chatspike.net chatspike.net services-dev +oo 0.0.0.0 services-dev.chatspike.net :Nickname Server
>> N 1111691007 ChanServ chatspike.net chatspike.net services-dev +oo 0.0.0.0 services-dev.chatspike.net :Channel Server
>> N 1111691007 MemoServ chatspike.net chatspike.net services-dev +oo 0.0.0.0 services-dev.chatspike.net :Memo Server
<< Y 1111691007
<< X 0
<< N 1111690997 [Brain] synapse.brainbox.winbot.co.uk netadmin.chatspike.net ~brain +xiwsogh 10.0.0.2 test.chatspike.net :Brain
>> V NickServ [Brain] :This nickname is registered and protected.  If it is your nickname, type msg NickServ...
>> V NickServ [Brain] :If you do not change within one minute, I will change your nickname.
<< | [Brain] NetAdmin
<< J [Brain] @#chatspike
<< M #chatspike +nt
<< H services-dev.chatspike.net
<< $ test.chatspike.net services-dev.chatspike.net
<< F 1111691007
<< $ test.chatspike.net services-dev.chatspike.net
>> m ChanServ #chatspike +ntrl 99
<< P [Brain] NickServ :identify xxxxxxxx
>> m NickServ [Brain] :+r
>> V NickServ [Brain] :Password accepted -- you are now recognized.
>> m ChanServ #chatspike +q [Brain]
<< n [Brain] [Brain
>> m NickServ [Brain :-r
<< n [Brain [Brain]
>> m NickServ [Brain] :+r
<< P [Brain] NickServ : identify xxxxxxx
>> m NickServ [Brain] :+r
>> V NickServ [Brain] :Password accepted -- you are now recognized.
<< N 1111691073 Om xxxxxx.gotadsl.co.uk ChatSpike-7A15BE0A.gotadsl.co.uk ~om +x 81.6.252.165 test.chatspike.net :Om
<< b Om ChatSpike-7A15BE0A.gotadsl.co.uk
<< m Om Om +x
>> V NickServ Om :This nickname is registered and protected.  If it is your nickname, type...
<< m Om Om +wsi
<< J Om #chatspike
<< P Om NickServ :identify xxxx
>> V NickServ Om :Password incorrect.