Mesh Protocol (Pre beta6)
From the makers of InspIRCd.
 |
Historical Material - Information posted here may be inaccurate as a result of being obsolete. This information is kept for historical reference purposes. |
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.
Connection States
The server connection engine in InspIRCd is a finate state machine with a predetermined set of states. A socket may be inbound or outbound, and depending upon which it is, may be in any of the following states:
- STATE_DISCONNECTED - This state indicates a connection is completely down. Usually, these are removed at the earliest opportunity unless they are due to be retried.
- STATE_CONNECTED - This state indicates a connection is completely up, and has been initiated by a direct /CONNECT from another server, for example an 'S' or 's' token.
- STATE_SYNC - This state indicates a connection is currently synching. A server may only enter this sate from STATE_NOAUTH_INBOUND or STATE_NOAUTH_OUTBOUND - This state indicates a connection is in progress using connect() to a remote server. The connection was initiated by a direct /CONNECT to another machine, e.g. an 'S' token, and from this state we may only move to STATE_SYNC or STATE_DISCONNECTED (upon failure) in which case the socket is closed. Please note that during this state, the socket may not yet be connected and should be polled to check if it is writeable yet. The ircd_connector class (see the programmer documentation) does this for you and will not send buffered data to a socket which is not yet connected.
- STATE_NOAUTH_INBOUND - This state indicates an inbound connection is in progress using accept() from a remote server, which initiated the connection with an 'S' token.
- STATE_SERVICES - This state is identical to STATE_CONNECTED except it indicates the server which is linked to this socket is incapable of a proper meshed link, e.g. it is a services server which predates InspIRCd's protocol. A server on this type of link has several behavioural characteristics different to a normal connection:
|
- STATE_COOKIE_OUTBOUND - This state is identical to STATE_NOAUTH_OUTBOUND except that it occurs in a 'cookie' connection, e.g. where an outbound connect() is due to send a '-' token and not an 'S' token, to mesh itself into an already-established partial link. Upon connection and successful sending of a '-' token, a socket in this state becomes STATE_CONNECTED if the remote side accepts it.
Mesh Tokens
The following token types are supported by the current release of InspIRCd. Please note that a working implementation of the protocol need not handle all of these token types (for example a services server may choose not to handle meshing and link as a 'U' token server instead (see below)) but, to be deemed 100% compliant with the protocol spec, all tokens should be supported where possible.
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.
Change-Server-Description: = Token
Syntax: = <servername> :<new description>
This token is intended to keep the server descriptions of meshed servers in step with each other. Only fully meshed servers should see this token, if it is sent to a non-meshed ('U' linked) server, it can be safely ignored.
Example Server Conversation
This is an example of an anope services server linking to an InspIRd server. During the 'conversation' two users connect, one of which becomes an oper, one of which remains a normal user.
>> :jDUKSWL U services-dev.chatspike.net password :Anope Test Services >> :yghKKno N 1116091781 NickServ chatspike.net chatspike.net services-dev +o 0.0.0.0 services-dev.chatspike.net :Nickname Server >> :YNUhWpt N 1116091781 ChanServ chatspike.net chatspike.net services-dev +o 0.0.0.0 services-dev.chatspike.net :Channel Server >> :epLBorX N 1116091781 HostServ chatspike.net chatspike.net services-dev +o 0.0.0.0 services-dev.chatspike.net :vHost Server >> :lYPvTCp N 1116091781 MemoServ chatspike.net chatspike.net services-dev +o 0.0.0.0 services-dev.chatspike.net :Memo Server >> :RutxGyE N 1116091781 BotServ chatspike.net chatspike.net services-dev +o 0.0.0.0 services-dev.chatspike.net :Bot Server >> :UVRHTvU N 1116091781 HelpServ chatspike.net chatspike.net services-dev +o 0.0.0.0 services-dev.chatspike.net :Help Server >> :lQfVXct N 1116091781 OperServ chatspike.net chatspike.net services-dev +io 0.0.0.0 services-dev.chatspike.net :Operator Server >> :upBVFsw N 1116091781 Global chatspike.net chatspike.net services-dev +io 0.0.0.0 services-dev.chatspike.net :Global Noticer >> :tjlswPb N 1116091781 ThisIsABot botbotbot.bot botbotbot.bot botbot +i 0.0.0.0 services-dev.chatspike.net :realhost.bot << :UKSWLyg X 0 << :hKKnoYN s test.chatspike.net password 7123 :ChatSpike InspIRCd test server << :UhWptep Y 1116091781 >> :RRUfLjR / NickServ >> :McTdpNK v services-dev.chatspike.net Anope-1.7.8 (730) services-dev.chatspike.net :InspIRCd 1.0 Beta - TM -- build #1, compiled May 5 2005 23:50:37 << :LBorXlY $ test.chatspike.net services-dev.chatspike.net << :PvTCpRu H services-dev.chatspike.net << :txGyEUV v test.chatspike.net InspIRCd-1.0(Beta5)+CVS Rev. 1.423 test.chatspike.net :FreeBSD neuron 5.2.1-RELEASE (O=0) [SE=kqueue] << :RHTvUlQ N 1116091671 [Brain] synapse.brainbox.winbot.co.uk InspIRCd-Testnet-5110D559577D63B7.brainbox.winbot.co.uk ~brain +xiws 10.0.0.2 test.chatspike.net :There are no secrets except those that keep themselves >> :mnwLNch V NickServ [Brain] :This nickname is registered and protected. If it is your >> :DcoRuHL V NickServ [Brain] :nick, type /msg NickServ IDENTIFY password. Otherwise, >> :qWWgEKV V NickServ [Brain] :please choose a different nick. << :fVXctup J [Brain] @#chatspike >> :XnirhDG m ChanServ #chatspike +nrt >> :NKPqmyq m ChanServ #chatspike -o [Brain] << :BVFswtj N 1116091689 PinkFreud xxxxxxxx.ewndsr01.nj.comcast.net InspIRCd-Testnet-7C5E55656F40C50D.ewndsr01.nj.comcast.net ~WhyNot +x 1.2.3.4 test.chatspike.net :stranded in the real world << :lswPbRR J PinkFreud @#PinkFreud #chatspike << :fdsfewQ M #PinkFreud +nt << :bdfxvbD M #chatspike +nt << :UfLjRMc F 1116091781 << :wLNchDc $ test.chatspike.net services-dev.chatspike.net << :oRuHLqW P [Brain] NickServ : identify xxxxxxxx >> :EoFJsoD M [Brain] +r >> :mpFWfjw V NickServ [Brain] :Password accepted - you are now recognized. >> :fktrWVm m ChanServ #chatspike +qo [Brain] [Brain] << :WgEKVXn P [Brain] OperServ :help >> :RzWnrzH V OperServ [Brain] :Access denied. << :irhDGNK | [Brain] NetAdmin << :PqmyqEo b [Brain] netadmin.chatspike.net << :FJsoDmp M [Brain] +o >> :vPNhLzp V OperServ * :[Brain] is now an IRC operator. << :FWfjwfk m [Brain] [Brain] +g << :trWVmRz P [Brain] OperServ :help
Bold text
