docs/server_tokens.txt

   1 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
   2 useful when syncronising module data between different servers on the mesh. All tokens are case sensitive. Token names are given, however these are
   3 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.
   4
   5 Modules should try to avoid low ascii values. The only illegal token characters are ASCII 0, ASCII 13, and ASCII 10.
   6
   7 --------------------------------------------------------------------------------
   8 Compatibility Translations
   9
  10 InspIRCd will translate some RFC-style commands into mesh tokens, to maintain compatibility with some services packages. This only occurs if the
  11 server is a U-type link (see the tokens below for an explaination). The translated commands are:
  12
  13     * 433 - Translated to *
  14     * 432 - Translated to *
  15     * PING - Translated to *
  16     * NOTICE - Translated to V
  17     * PRIVMSG - Translatd to P
  18     * QUIT - Translated to Q
  19     * SQUIT - Translated to &
  20     * SVSMODE - Translated to m
  21     * SVS2MODE - Translated to m
  22     * MODE - Translated to m
  23     * KICK - Translated to k
  24     * KILL - Translated to K
  25     * SVSJOIN - Translated to J
  26
  27 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 '*'
  28 which is a wildcard sum and is always accepted by all servers.
  29
  30 --------------------------------------------------------------------------------
  31 Uniqueness Sums
  32
  33 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.
  34 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
  35 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
  36 simply generates the sums via the rand() function, there is no documented system for creating these uniqueness values, it is up to the person
  37 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.
  38
  39 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
  40 for redirect tokens, see below in the command specification) then the entire command is to be silently dropped without any attempt at processing.
  41
  42 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
  43 which do not directly support the mesh protocol, and must have their commands rewritten, may generate commands which have this sum.
  44
  45 To avoid confusing parsers which are designed to process 'standard' irc server to server communication, each uniqueness sum is prefixed with a :
  46 symbol. For example:
  47
  48 :uniqueness-sum TOKEN param param :final param
  49
  50 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
  51 parameters array, or however your software passes its data.
  52
  53 --------------------------------------------------------------------------------
  54 Mesh Tokens
  55 --------------------------------------------------------------------------------
  56 AuthCookie: - Token
  57
  58 Syntax: - <authcookie> <servername> :<serverdesc>
  59
  60 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
  61 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,
  62 otherwise it rejects it.
  63 --------------------------------------------------------------------------------
  64 Inbound Server: S Token
  65
  66 Syntax: S <servername> <password> <port> :<description>
  67
  68 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
  69 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.
  70 This is known as an 'active' connect, e.g. the initiator always uses the uppercase S token.
  71 --------------------------------------------------------------------------------
  72 Set version reply: v Token
  73
  74 Syntax: v <servername> <arbitary version string>
  75
  76 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
  77 its details either on bursting or if/when the data changes.
  78 --------------------------------------------------------------------------------
  79 Outbound Server: s Token
  80
  81 Syntax: s <servername> <password> <port> :<description>
  82
  83 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
  84 S to avoid loops, and diffrentiate between initiator and receiver in the linking process. Once the initiator accepts the s token, the link is
  85 established and the burst begins.
  86 --------------------------------------------------------------------------------
  87 Non-Mesh Server: U Token
  88
  89 Syntax: U <servername> <password> :<description>
  90
  91 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
  92 become a fully meshed node, for example IRC Services packages. Upon a successful "U type" (as this is known) authentication, the other servers are
  93 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
  94 (messier than meshing it, but if the application is physically incapapable of joining the mesh, this is what must be done).
  95 --------------------------------------------------------------------------------
  96 Error: E Token
  97
  98 Syntax: E :<error message>
  99
 100 The E token indicates a protocol error, or invalid credentials etc, and immediately after an E token the connection is dropped. Failure to
 101 authenticate during a link is usually the cause of such tokens being sent.
 102 --------------------------------------------------------------------------------
 103 Begin Netburst: Y Token
 104
 105 Syntax: Y <time>
 106
 107 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
 108 at the end of the netburst which also contains a time, allowing the delta to match up correctly without clock syncronization)
 109 --------------------------------------------------------------------------------
 110 Set Auth Cookie: ~ Token
 111
 112 Syntax: ~ <new auth cookie>
 113
 114 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.
 115 --------------------------------------------------------------------------------
 116 Begin Mesh: + Token
 117
 118 Syntax: + <servername> <portnumber> <authcookie>
 119
 120 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
 121 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
 122 upon connection.
 123 --------------------------------------------------------------------------------
 124 Send Routing Table: $ Token
 125
 126 Syntax: $ <source server> <reachable server> [<reachable server>...]
 127
 128 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
 129 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
 130 directly, and inform that server to route the message for it.
 131 --------------------------------------------------------------------------------
 132 SQUIT: & Token
 133
 134 Syntax: & <servername>
 135
 136 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
 137 & symbol, the local server will instantly and recursively (according to its routing table) remove all users along that route.
 138 --------------------------------------------------------------------------------
 139 Reroute: R Token
 140
 141 Syntax: R <target-server> <anything>
 142
 143 This is the R or 'reroute' token, which indicates the <anything> provided should be instantly routed to <target-server> and only to <target-server>
 144 without processing it any further. Usually the server will receive these if it is the only available and direct route to <target-server>.
 145 --------------------------------------------------------------------------------
 146 PONG: ? Token
 147
 148 Syntax: ?
 149
 150 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
 151 required.
 152 --------------------------------------------------------------------------------
 153 NOP: * or : Token
 154
 155 Syntax: *|:
 156
 157 This token is a NOP (No-Operation) message.
 158 --------------------------------------------------------------------------------
 159 USER: N Token
 160
 161 Syntax: N <time> <nick> <host> <displayed-host> <ident> <modes> <ipaddress> <server> :<GECOS>
 162
 163 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
 164 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
 165 (1.2.3.4) form.
 166 --------------------------------------------------------------------------------
 167 CHGNAME: a Token
 168
 169 Syntax: a <nick> :<GECOS>
 170
 171 Change realname (GECOS) of a connected user.
 172 --------------------------------------------------------------------------------
 173 CHGHOST: b Token
 174
 175 Syntax: b <nick> :<displayed-host>
 176
 177 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
 178 check this value before sending it out onto the mesh.
 179 --------------------------------------------------------------------------------
 180 TOPIC: t Token
 181
 182 Syntax: t <nick> <channel> :<topic>
 183
 184 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
 185 instead to check which topic 'wins'.
 186 --------------------------------------------------------------------------------
 187 INVITE: i Token
 188
 189 Syntax: i <nick> <source> <channel>
 190
 191 Invite a user to a channel. The user specified by <nick> is invited to channel <channel> by <source>.
 192 --------------------------------------------------------------------------------
 193 KICK: k Token
 194
 195 Syntax: k <source> <dest> <channel> :<reason>
 196
 197 This token indicates a user was kicked from a channel.
 198 --------------------------------------------------------------------------------
 199 NICK: n Token
 200
 201 Syntax: n <old nick> <new nick>
 202
 203 Indicates a nickchange.
 204 --------------------------------------------------------------------------------
 205 JOIN: J Token
 206
 207 Syntax: J <nick> [permissions]<channel> [[permissions]<channel>...]
 208
 209 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
 210 #baz".
 211 --------------------------------------------------------------------------------
 212 SERVERTOPIC: T Token
 213
 214 Syntax: T <settime> <nick> <channel> :<topic>
 215
 216 This token indicates the server set or changed a channel topic. This token should be used in netjoins to check which topic 'wins'.
 217 --------------------------------------------------------------------------------
 218 SERVERMODE: M Token
 219
 220 Syntax: M <target> <modes> [mode-parameters]
 221
 222 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
 223 case 'm') in which a user sets the modes.
 224 --------------------------------------------------------------------------------
 225 MODE: m Token
 226
 227 Syntax: m <source> <target> <modes> [mode-parameters]
 228
 229 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
 230 <source> as a server, for this you must use the M token instead.
 231 --------------------------------------------------------------------------------
 232 PRIVMSG: P Token
 233
 234 Syntax: P <source> <target> :<text>
 235
 236 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.
 237 --------------------------------------------------------------------------------
 238 NOTICE: V Token
 239
 240 Syntax: V <source> <target> :<text>
 241
 242 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.
 243
 244 As of 1.0 Beta 4, there are two special cases for the V token, in which the target may be one of:
 245
 246     * "*" - Specify a target of * to send the notice to all users upon that server.
 247     * "@*" - Specify this target to send to all opers upon that server and place the nickname of the originator within the body of the notice.
 248
 249 --------------------------------------------------------------------------------
 250 PART: L Token
 251
 252 Syntax: L <nick> <channel> :<reason>
 253
 254 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
 255 colon (":").
 256 --------------------------------------------------------------------------------
 257 QUIT: Q Token
 258
 259 Syntax: Q <nick> :<reason>
 260
 261 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 (":").
 262 --------------------------------------------------------------------------------
 263 Non-Mesh-Add: H Token
 264
 265 Syntax: H <servername>
 266
 267 Adds a U-Type server to the map without any other information. This is used to maintain links to services.
 268 --------------------------------------------------------------------------------
 269 KILL: K Token
 270
 271 Syntax: K <source> <nick> :<reason>
 272
 273 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,
 274 not a server, as server kills are always handled locally.
 275 --------------------------------------------------------------------------------
 276 WALLOPS: @ Token
 277
 278 Syntax: @ <source> :<text>
 279
 280 This token sends a global WALLOPS. Source may only be a user, not a server.
 281 --------------------------------------------------------------------------------
 282 GLINE: # Token
 283
 284 Syntax: # <mask> <who-set-it> <time-set> <duration> :<reason>
 285
 286 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
 287 arbitary text, and can be a user or a server.
 288 --------------------------------------------------------------------------------
 289 UNGLINE: . Token
 290
 291 Syntax: . <mask> <who>
 292
 293 Removes a G-Line from all servers on the mesh.
 294 --------------------------------------------------------------------------------
 295 QLINE: { Token
 296
 297 Syntax: { <mask> <who-set-it> <time-set> <duration> :<reason>
 298
 299 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
 300 a server.
 301 --------------------------------------------------------------------------------
 302 UNQLINE: [ Token
 303
 304 Syntax: [ <nickmask> <who>
 305
 306 Removes a Q-Line from all servers on the mesh.
 307 --------------------------------------------------------------------------------
 308 ZLINE: } Token
 309
 310 Syntax: } <mask> <who-set-it> <time-set> <duration> :<reason>
 311
 312 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
 313 a server. If duration is 0, the ban is permenant.
 314 --------------------------------------------------------------------------------
 315 UNZLINE: ] Token
 316
 317 Syntax: ] <mask> <who>
 318
 319 Deletes a Z-Line from all servers on the mesh.
 320 --------------------------------------------------------------------------------
 321 OPERTYPE: | Token
 322
 323 Syntax: | <nick> <opertype>
 324
 325 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.
 326 Configuration of oper types and classes should match network wide.
 327 --------------------------------------------------------------------------------
 328 End-Netburst: F Token
 329
 330 Syntax: F <time>
 331
 332 This token indicates the end of the netburst, for more information see the 'Y' token.
 333 --------------------------------------------------------------------------------
 334 SERVICE1: / Token
 335
 336 Syntax: / <nickserv nick>
 337
 338 This token is used to indicate the name of a nickname service and is reserved for future use.
 339 --------------------------------------------------------------------------------
 340 End-Netburst-NM: f Token
 341
 342 Syntax: f <time>
 343
 344 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
 345 to force routing through its uplink. Used by services servers.
 346 --------------------------------------------------------------------------------
 347 Begin-Burst: X Token
 348
 349 Syntax: X <time>
 350
 351 This token when sent indicates that the server is ready to receive the other servers (recipient of this token) netburst data.
 352 --------------------------------------------------------------------------------
 353 Example Server Conversation
 354
 355 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
 356 which is a normal user.
 357
 358 >> U services-dev.chatspike.net xxxxxxxx :Developer Services
 359 >> / NickServ
 360 >> N 1111691007 OperServ chatspike.net chatspike.net services-dev +oio 0.0.0.0 services-dev.chatspike.net :Operator Server
 361 >> N 1111691007 Global chatspike.net chatspike.net services-dev +oio 0.0.0.0 services-dev.chatspike.net :Global Noticer
 362 >> N 1111691007 NickServ chatspike.net chatspike.net services-dev +oo 0.0.0.0 services-dev.chatspike.net :Nickname Server
 363 >> N 1111691007 ChanServ chatspike.net chatspike.net services-dev +oo 0.0.0.0 services-dev.chatspike.net :Channel Server
 364 >> N 1111691007 MemoServ chatspike.net chatspike.net services-dev +oo 0.0.0.0 services-dev.chatspike.net :Memo Server
 365 << Y 1111691007
 366 << X 0
 367 << N 1111690997 [Brain] synapse.brainbox.winbot.co.uk netadmin.chatspike.net ~brain +xiwsogh 10.0.0.2 test.chatspike.net :Brain
 368 >> V NickServ [Brain] :This nickname is registered and protected.  If it is your nickname, type msg NickServ...
 369 >> V NickServ [Brain] :If you do not change within one minute, I will change your nickname.
 370 << | [Brain] NetAdmin
 371 << J [Brain] @#chatspike
 372 << M #chatspike +nt
 373 << H services-dev.chatspike.net
 374 << $ test.chatspike.net services-dev.chatspike.net
 375 << F 1111691007
 376 << $ test.chatspike.net services-dev.chatspike.net
 377 >> m ChanServ #chatspike +ntrl 99
 378 << P [Brain] NickServ :identify xxxxxxxx
 379 >> m NickServ [Brain] :+r
 380 >> V NickServ [Brain] :Password accepted -- you are now recognized.
 381 >> m ChanServ #chatspike +q [Brain]
 382 << n [Brain] [Brain
 383 >> m NickServ [Brain :-r
 384 << n [Brain [Brain]
 385 >> m NickServ [Brain] :+r
 386 << P [Brain] NickServ : identify xxxxxxx
 387 >> m NickServ [Brain] :+r
 388 >> V NickServ [Brain] :Password accepted -- you are now recognized.
 389 << N 1111691073 Om xxxxxx.gotadsl.co.uk ChatSpike-7A15BE0A.gotadsl.co.uk ~om +x 81.6.252.165 test.chatspike.net :Om
 390 << b Om ChatSpike-7A15BE0A.gotadsl.co.uk
 391 << m Om Om +x
 392 >> V NickServ Om :This nickname is registered and protected.  If it is your nickname, type...
 393 << m Om Om +wsi
 394 << J Om #chatspike
 395 << P Om NickServ :identify xxxx
 396 >> V NickServ Om :Password incorrect.
 397