The P10 server-server protocol

Copyright © 1998 - 2000
Carlo Wood, Run on IRC
RSA-1024 0x624ACAD5 1997-01-26		Sign & Encrypt
Fingerprint16 = 32 EC A7 B6 AC DB 65 A6 F6 F6 55 DD 1C DC FF 61

The latest version of this document can be retrieved from http://www.xs4all.nl/~carlo17/irc/P10.html

1. General

1.1 The server-server connection

The communication between two servers is done by means of a binary stream of octets.  The stream must be connected, reliable and ordered.

A server that receives a connection must know that the corresponding stream will use the server-server protocol.  This can for instance be achieved by using a different port number for servers than for other connection types.

A complete stream of octets, from the connection till disconnection, is build up like:

<lines><junk><eof>

where

<lines>		Nothing <line><lines>
<junk>		Any string of octets that is not a <line>
<eof>		Connection termination (i.e. Calling close(), or read() returning 0)

Notes:

	The <junk> octets, if any, are ignored.
	A server is allowed to terminate a connection itself when it detects that it receives <junk> (when it receives a null character or when the message is too long).

1.2 Line

A line is build up like

<line>

<message><eol>

where

Received line

<message>		A string of octets (type char) not containing any <new-line> or null character.
<eol>		<new-line> <carriage-return><new-line>

Generated line

<message>		A string of octets (type char) not containing any <new-line> or null character, and not ending on a <carriage-return>.
<eol>		<new-line>

and

<new-line>		'\n' (ASCII 10)
<carriage-return>		'\r' (ASCII 13)

Notes:

	A <message> may not contain a  null character so that messages can be treated as null terminated strings, which in turn allows the use of library calls like strtok() and strchr().
	The reason that it is not allowed to generate lines that end on '\r\n' is for compatibility with P11, which will disregard the carriage-return as being special in any way.

1.3 Message

Each message is defined as

Before authentication

<message>

<pre_auth_error> <pre_auth_pass> <pre_auth_server>

After authentication

<message>

<prefix><space><cmd><space><tokens> <prefix><space><cmd><space><tokens><space><colon><last_token> <prefix><space><cmd><space><colon><last_token>

where

<pre_auth_error> <pre_auth_pass> <pre_auth_server>		See Authentication messages.
<prefix>		A token specifying the origin of the message.  See Prefix.
<space>		' ' (ASCII 32)
<cmd>		See Message overview.
<tokens>		<token> <token><space><tokens>
<colon>		':' (ASCII 58)
<last_token>		A string of octets (type char) not containing any <new-line> or null character.

and

<token>

A string of octets (type char) not containing any <space>, <new-line> or null character, and not starting with a <colon>.

Notes:

	Since generated messages may not end on a <carriage-return>,    <last_token> may also not end on <carriage-return>.  And if the message ends on a <token> then this last <token> may not end on a <carriage-return>.
	The minium number of the tokens depends on the actual <cmd>. However, the exact number is unknown because at a specified place it is possible that extra tokens are inserted.  These extra tokens should be ignored when received.  It makes it necessary however to refer to a token as either "token number x from the beginning" or "token number y from the end". See Message overview for the position that is reserved for insertion of extra tokens in each message respectively.
	The meaning of the tokens depends on the actual <cmd>.  But whether or not a specific message uses a <colon> in front of the last parameter is unspecified (In order words, it is possible to receive a message of the form <prefix><space><cmd><space><tokens><space><colon><token>). However, it is deprecated to use a colon in front of a token that can never contain a space or start with a colon.  It is also deprecated not to use a colon in front of the last parameter when generating messages that sometimes need the colon because the last parameter contains spaces.

1.4 Prefix

The prefix of received authenticated messages includes more possible formats than what may be generated.  This is for backwards compatibility with P09 and transition versions of "P10" like the ircu2.10.04 implementation.

Received message

<prefix>

<nicknum> <servnum> <colon><nickname> <colon><servname>

Generated message

<prefix>

<nicknum> <servnum>

where

<nickname>		See the description of the NICK message.
<servname>		See the description of the SERVER message.
<nicknum>		<servnum><base64><base64>  ; Must be network-wide unique.
<servnum>		<base64>  ; Must be network-wide unique.

and

<base64>

Any of 'A','B','C','D','E','F','G','H','I','J','K','L','M','N','O','P', 'Q','R','S','T','U','V','W','X','Y','Z','a','b','c','d','e','f', 'g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','v', 'w','x','y','z','0','1','2','3','4','5','6','7','8','9','[',']'

Notes:

	It is easy to detect if a prefix is a numeric or not: A prefix with a <nickname> or a <servname> starts with a <colon>, while <nicknum> and <servnum> do not.
	The value of <servnum> is read from the configuration file on startup of the server.  Its uniqueness is the responsibility of the administrator.
	A <base64> corresponds with a number (0..63) as follows: 'A' corresponds with 0, 'B' corresponds with 1, etc. until ']' which corresponds with 63.  See the table above. The last two <base64> characters of a <nicknum> need to be bitwise OR-ed with the corresponding bits of the <base64> of the <masknum> in order to get the real, unique identifier of the corresponding client (called the 'masked numeric'). For example, if a server with a numeric value of 43 (and thus a <servnum> of 'r') uses 'rD]' in its SERVER message then the <masknum> ('D]') corresponds to a value of 255 and a <nicknum> of '9v' (3951) would collide with a <nicknum> of 'Nv' (879) because 3951 & 255 == 879 & 255 (== 111).  However, these numerics are not considered to be equivalent in a prefix: if a local client with value 111 exist, then a <nicknum> like 'r9v' in the prefix should be ignored if appropriate.

1.5 Source

1.5.1 Definition

The NICK and SERVER messages introduce two identifiers each; a numeric handle and a humable readable name (the client-server protocol handle), for respectively a new client or server.  These two identifiers are the <nicknum> and <nickname> in the case of the NICK message,   and <servnum> and <servname> in the case of the SERVER message.  The client or server associated with the identifier in the <prefix> will be called the source of a message in the remainder of this document.  Note that the source of a message is not in all cases the real origin of the message, although it is in most cases and can always be interpreted like that for received messages.

1.5.2 Direction

The direction of a source is defined as the link over which the corresponding NICK or SERVER message was received, that originally introduced the source.  A link is the connection with another (authenticated) server.

1.5.3 Ignoring messages based on the source and direction

A message should be ignored, as if it was not received, in the following cases:

• No source is associated with the <prefix> (unknown) and <cmd> is not "SQUIT", "SQ", "KILL" or "D".

• The direction of the source associated with the <prefix> differs from the link over which the message was received.

Note:

If the source is unknown but the message should not be ignored (because <cmd> is "SQUIT", "SQ", "KILL" or "D"), then the server should pretend that the source of the message is the server directly behind the link the message was received from.

1.5.4 KILL for an unknown numeric nick as source in a NICK message

If the source is unknown and <cmd> is "NICK" or "N",  and <prefix> is a <nicknum>,  then the server must send a KILL message over the link that the message was received from with as target <nicknum>, itself as source and "Unknown numeric nick" as comment.

Note:

Even if the source is unknown one can see whether or not the <prefix> is a <nicknum> or not: It does not start with a <colon> and is longer than a <servnum>.

2. Authentication procedure

2.1 State of a link

A server may initiate a connection, or receive a connection.  In both cases a link structure is created which goes through a few different states before reaching the authenticated state after which the server starts to accept prefixed messages of type <message>.

The PASS and SERVER message in these tables are respectively the <pre_auth_pass> and <pre_auth_server> messages.  See Message syntax below.

2.2 ERROR handling

If an error occurs during the authentication procedure (for instance a wrong password) then an ERROR message must be sent and the link must be terminated immedeately (after flushing the ERROR message).

If an ERROR message is received then the reaction depends on the state of the link.

ERROR messages sent before the own PASS and SERVER combination must have the <pre_auth_error> syntax, while ERROR messages sent after the own PASS and SERVER combination must have a prefix, see the description of the ERROR message.

2.3 Message syntax

2.3.1 The pre-authentication ERROR message

<pre_auth_error>

ERROR<space><colon><error_text>

where

<error_text>

<last_token>  ; describing the cause of rejection.

2.3.2 The pre-authentication PASS message

<pre_auth_pass>

PASS<space><colon><password>

where

<password>

A plain text password to authenticate the server.

2.3.3 The pre-authentication SERVER message

<pre_auth_server>

SERVER<space><servname><space>1<space><boot_time><space><link_time><space>J<protocol><space><servnum><masknum><space>0<space><colon><description>

where

<servname>		See the SERVER message.
<boot_time>		<time_stamp>  ; See Boot Time Stamp.
<link_time>		<time_stamp>  ; See Link Time Stamp.
<protocol>		Received message  : <digit><digit> Generated message: 10
<servnum>		See the SERVER message.
<masknum>		<base64><base64>  ; See the SERVER message.
<description>		<last_token>  ; description of the server.  See also § 4.2 Jupes.

and

<time_stamp>		<digit><digit><digit><digit><digit><digit><digit><digit><digit> <digit><digit><digit><digit><digit><digit><digit><digit><digit><digit>
<digit>		One of 0 1 2 3 4 5 6 7 8 9

Notes:

	Authentication messages do not start with a prefix.  You might want to use a seperate parser routine for not yet authenticated connections.
	The protocol version <protocol> specifies the protocol version for the prefixed messages but also for this non-prefixed SERVER message.  It is possible to receive a different protocol version in which case the tokens after the <protocol> string may differ.
	The <description> should not contain the IP number of the server, the IP number of the server is namely added by its uplink to the description field before propagating the SERVER message.
	The '1' and the 'J' in the SERVER message are mandatory for received messages.  It is an error if these characters are different.
	The '0', just before the description field, is optional for received messages, but mandatory for sent messages.  In the future (P11) this will become an unsigned integer (in ascii format).

2.3.4 Boot Time Stamp

The Boot Time Stamp is a time_t variable, which is initialized to the time in UTC seconds when the server application is (re)started.  Next it is replaced by the value of a <boot_time> parameter of received SERVER messages whenever that value is smaller.

2.3.5 Link Time Stamp

The <link_time> parameter of a generated message when initiating a connection represents the current value of the TS Clock Time, possibly incremented a few seconds in order to make sure that the server never generates twice the same value for a <link_time> (The value must be at least 1 second larger than the last value used in a sent <pre_auth_server> message).

In all other cases (when not initiating the connection), the <link_time> parameter is the same string as received in the corresponding SERVER message for that link.

2.3.6 TS Clock Time

The TS Clock Time is the current time in UTC seconds plus an offset which is calculated from the <boot_time>, the <link_time> and the system clock at the moment a <pre_auth_server> message is received (which successfully authenticates) and this application did initiate the connection.  When the received <boot_time> is equal to or smaller than the current value of the Boot Time Stamp, then the new offset is set such that the resulting TS Clock Time equals the received <link_time>.

3. Net burst

3.1 Objects and relationships

A complete IRC network exists of several servers each of which keeps a copy of a database which contains information about the clients and the channels of the network.  This copy can be different on different servers due to the dynamic nature of the network.  We are only interested in one copy: The variables on this server: the application that is generating and receiving the messages described in this document.

The objects refered to in this paragraph are therefore the internal variables of this application, not the real entities they describe.  The difference between the objects in our local copy of the database and the real, current, state of the relevant entities is what makes the protocol hard to understand if one mixes the two up.

There are three classes of objects:

1. Servers
2. Clients
3. Channels

There are four different relationships between these objects:

1. A Server can be connected to another Server.
2. A Client can be connected to a Server.
3. A Client can be joined on a Channel.
4. A Client can have several channel dependent flags set (usually for channels on which they are joined).

The state of the Server object and relationship 1. is completely determined by the SERVER,  END_OF_BURST and the SQUIT messages.

Likewise, relationship 2. is completely determined by the NICK and the QUIT and KILL messages, while the state of the Client object is additionally determined by the MODE <nickname>,  AWAY and SILENCE messages.

Relationship 3. is changed by the CREATE,  JOIN,  KICK,  PART and BURST messages.

The state of a Channel object is changed by the messages MODE <channel_name> and TOPIC.

Finally, relationship 4. is determined (apart from the messages that determine relationship 3. of course) by the messages MODE <channel_name> , INVITE and BURST.

Notes:

	Commands that change the state of a remote server application are not listed of course: Those messages don't change the state of our own local objects.
	The local server, the application itself, has a lot more variables - the state of the local server can be changed by several other messages not listed here either.

3.2 Creation and destruction of the objects

The Server object is created when a new server is introduced by means of the SERVER message (provided the server is accepted and the application doesn't send an SQUIT upstream instead).  A Server object gets destructed when an SQUIT message is received causing it to be disconnected from the local Server object.

The Client object is created when introduced with a NICK message and destructed when a corresponding QUIT or KILL message is received for the client <nicknum>, or when its server Object is destructed.

A Channel object is created when the first client joins the channel (CREATE and JOIN) and destructed when the last client leaves the channel (PART,  KICK and JOIN0).  When a Client object gets destructed, the client also leaves all channels of course.

It is not really necessary to destruct the Server and Client objects when an SQUIT is received, as long as the server hides this fact from the clients.  It should appear as if clients that split off (because the side of the network they are connected to disconnects) also leave all channels, and re-join when the net is reconnected.  The only gain here would be in the size of the net-burst because only changes in the relationships should be needed to be passed to the servers behind the first server of our side.  Realizing this needs a change in the protocol however, probably P11, and this documentation describes P10.  Therefore it is reasonable to actually destruct the objects and we will assume that is the case here.

3.3 Synchronization and message queueing

The concept of synchronization in a highly dynamic network like an IRC network might be hard to grasp.  The main idea is that every change in the local state of an application (that is, the local server, one of its local clients or a channel due to a message from a local client) which is relevant for the corresponding object on the remote servers, is represented by a message, sent to these remote servers.  In order to get full synchronization, this message must reach all servers.

However, a message can be rejected somewhere half way by one of the receiving servers.  In that case a cancelling message needs to be sent to all servers that the original message did already reach - in order to cancel the change everywhere.

If there is a network congestion and there are more messages being sent over a link then the bandwidth allows at that moment, then these messages need to be queued.  This costs memory, and the application can run out of memory, or the lag caused by the size of the queue can grow unacceptable large.  Therefore it can happen that this link breaks, and all queued messages get lost.

Because of the lost messages, a special resynchronization step is needed when the two sides of the IRC network reconnect.  As said before, this is currently done by a full synchronization: All state information of the objects and their relationships are (re)sent to the connecting side.  Well, thats not entirely true: Certain information is disregarded on purpose - causing desynchronisation between the servers.  The reason for disregarding this information is to reduce the size of the so called net burst.

The changes represented by the following messages are disregarded: AWAY,  SILENCE,  TOPIC and INVITE.  SILENCE has its own resynchronisation mechanism.  An invited client that did split off before the invite reached him needs to be re-invited, the desynchronisation of the invite-flag in the objects of servers not the local server of the client, is not relevant.  Not resending the AWAY messages and the channel TOPIC results in a plain desynchronisation.  Its the only desynchronisation however that can not be abused.

Because in the current implementation all objects that split off are destructed, it is not necessary to resent destructing messages.  The messages left over are SERVER,  NICK,  MODE <nickname>,  CREATE,  JOIN and MODE <channel_name>.  During the special step of resynhronizing the network after a net.junction, sending the net burst, the last four messages are combined into a single message: BURST.

Some messages, like the chat messages itself, don't need any synchronization.  Those messages don't need to be queued because of synchronisation.  Not all messages need to be kept in the same order to garantee synchronization: Messages related to different channels could be mixed up as a function of the bandwidth use per channel for instance.  In order to be able to assign priorities to queued messages it is better to queue the messages as objects rather then to queue them as a string of characters in one huge buffer.  It is almost certain that this type of queueing will be necessary for P11.

3.4 State of an authenticated link

When two servers connect the state of the link reaches the authenticated state at one point (See chapter 2).  There are multiple authenticated states however.  Two more states follow the authenticated state:

3.5 State of a remote link

Servers introduced by local servers are remote servers.  The links via which a remote server is connected also goes through a few states during its net burst.  If a remote server is introduced with a SERVER message that has a P in its protocol field, then that link is immedeately in the state linked.  However, if the protocol field starts with a J (see <pre_auth_server>), then that link goes through the following states:

3.6 Generating the net burst

The messages that form the net burst must be generated in an order which allows the receiving server to create the objects and relationships represented by each message, at the moment the message is received.  So, first a Server objects must be created and then the Client objects connected to that Server.  Likewise, a Server that is connected closer must be created first before a Server behind it can be introduced, etc.

Because servers may be rejected as function of which servers are introduced, it makes most sense to first introduce all servers before introducing clients.  This in order to avoid processing parts of a net burst, creating client objects, which need to be destructed a second later again.

Therefore, the net burst is constructed as follows:

	All SERVER messages, one for each Server object - the closest first.
	All NICK messages, one for each Client object.
	All BURST messages, one or more for each Channel object.
	One END_OF_BURST message.

4. Special server types

4.1 Trusted Services

Some services are of a special trusted type.  Like all services they just register as a normal server but they use a <servname> that is agreed upon by all other servers and services on the network giving them the right to make any kind of changes to the state of channels.

Trusted Services are not allowed to introduce other servers except Jupes.

4.2 Jupes

A Jupe is a server whose info field <description> starts with the four characters "JUPE" (case sensitive).  Juped servers are not allowed to send any message except the the SERVER message that introduces themselfs.  Juped servers can not be SQUIT-ed by other servers (only by Opers).

5. Nick collisions

5.1 Server nick collisions

Each received SERVER message introduces a new Server object with a numeric handle <servnum> and a name <servname>.  When a Server object with the same numeric or name already exists, then we have a server nick collision.

In the case of a collision, either an SQUIT message must be generated to break the loop that is the result of this (if server tries to connect (link state pass) and the supplied name and/or numeric collides, causing it to be rejected - then an ERROR message is sent instead of an SQUIT message of course).

Collision checking for local servers is done after authentication checking.

5.1.1 Local connection

If a collision occurs with the name and/or numeric of the server application itself, then the local link over which the SERVER message was received is terminated.

When the existing server is an Trusted Service then the local connection over which the SERVER message was received must be terminated.  Trusted Services are expected to always connect to the same server so that any collision with it makes the whole side of the net that introduced the fake service suspicious.

5.1.2 Introduced server

The server that is introduced by the received SERVER message should be rejected in the following cases:

• The numeric is colliding, but the name of the servers are different.
• The name is colliding, but the numeric of the servers are different.
• When the existing server is a Jupe.

5.1.3 Existing server

The existing server is squitted in the following cases:

• When the existing Server object is a local link with state challenged or handshake (Note that it is not allowed to have more then one connect attempt at a time).
• When the existing Server object is a Ghost.  A server is a ghost when the new server that caused the collision is a direct connection.
• When the existing Server object is part of a Ghost loop: when the new server that caused the collision is introduced by a server that caused a Ghost, as part of the same (initial) burst.

5.1.4 The second youngest link

When none of the above causes the collision to be solved, then the second youngest link in the loop according to the link time must be terminated, or when the third and second youngest link in the loop have the same link time, then the link to be terminated is determined by the names of the servers: The link that is a connection of the server with the largest name (See strcmp(3)). If that still doesn't uniquely identify a link (because we have A -- C -- B), then the link with the largest of the two remaining server names must be terminated (C -- B).

5.1.5 Configuration rules

All of the above rules determine where the loop should be broken.  Independent of that it is possible that the received SERVER message causes the need for a link termination as a result of a Configuration Rule (d:, D:, H: or L: lines).

At all times only one link should be terminated (otherwise it is possible that the net ends up in two parts), therefore the following rule applies: If the two links that need to be broken (one according to § 5.1.1 through § 5.1.4 and one according to a Configuration rule) are in the same direction, then only the one that is closest is actually broken.  If the two links lay in opposite directions, then the link in the direction from which we received the SERVER message is broken.

If the link that needs to be broken according to a Configuration rule doesn't lay on the loop, then this paragraph does not apply.

5.2 Client nick collisions

Each received NICK message with a server as source, introduces a new Client object with a numeric handle <nicknum> and a name <nickname>.  Each NICK message with a client as source, changes the name of a given Client object.  When another Client object with the same masked numeric or name already exists, then we have a client nick collision.

If the collision is with a local client which did not authenticate yet (who is not yet broadcasted to the other servers), then this local client is removed.

Otherwise if it is a nick change (the source of the NICK message is a client) and if the time stamps of the nicks of the two colliding clients are equal, or when the time stamp of the incoming nick is larger and the user@hostname differs, or when the time stamp of the incoming nick is smaller and the user@hostname is equal then send a KILL message to all outgoing servers for the source client.  If the collision is with a local client, also send a KILL upstream (this for security reasons and might not really be necessary).

Otherwise, but also when the two time stamps are equal, send a KILL message for the existing client to all outgoing servers.

6. Message overview

6.1 Reserved parameter position

The syntax of the authenticated <message> is described in § 1.3.

As stated before, there is a position reserved for new parameters:

<prefix> <cmd> param₀ param₁ ... param_p-1[ reserved ...] param_n-q param_n-q+1 ... [<colon>]param_n-1

where

p		Number of defined parameters at the beginning.
q		Number of defined parameters at the end.
n		Number of received parameters.

If  n > p + q  then  param_p  till  param_n-q-1  must be ignored by P10.   P10 may or may not propagate the extra parameters, P11 will demand extra parameters to be propagated.

The maximum number of received parameters is 15, in other words n < 16.

6.2 Target types

A lot of commands behave more or less the same in the way they are propagated.  If neither a server nor one of its locally connect clients is a target of a message, it should merely route the message and not change its database state based on the message's content.  In total we can distinguish six main types:

wall    : Propagate to all servers
server  : Target is a server
client  : Target is a client
channel : Target is a channel
umode   : Target is all users with a given umode
catch   : Don't propagate

6.2.1 wall

This type of message doesn't have a target field.  It is propagated without change to all servers.  The application who receives such a message will propagate the message to all other (authenticated) server links it has.

Messages that are not essential for synchronisation can optionally be hold back for links that are still exchanging the net.burst (states authenticated and burst_sent).

Messages that are propagated as the wall type are AWAY, BURST, CREATE, END_OF_BURST, EOB_ACK, GLINE, JOIN, KICK, KILL, MODE <nickname>, MODE <channel_name>, NICK, NICK, PART, QUIT, SERVER, SETTIME, SILENCE, SQUIT and TOPIC.

6.2.2 server

This type of message has a server numeric or name as target field. It usually has no effect on the internal state of servers that are only routing it, until it reaches its destination.

Messages that are propagated as the server type are ADMIN, CONNECT, GLINE, GLINE, INFO, LINKS, LUSERS, MOTD, NAMES, PING, PONG, RPING, RPING, RPONG, SETTIME, STATS, TIME, TRACE, UPING, VERSION, WHOIS and WHOWAS.

6.2.3 client

This type of message has a client numeric or name as target field. It usually has no effect on the internal state of servers that are only routing it, until it reaches its destination: the server of the client.

Messages that are propagated as the client type are INVITE, NOTICE, PONG, PRIVMSG, RPONG, SILENCE and TRACE.

6.2.4 channel

This type of message is only routed to those servers that have clients on this channel.  It is not routed over links that are not in the linked state however, in order to prevend excessive lag build up.  These type of messages are never essential for (channel) synchronisation, which are of type wall.

Messages that are propagated as the channel type are NOTICE, PRIVMSG and WALLCHOPS.

6.2.5 umode

This type of message is essentially a wall type message, but only routed over links that have clients behind it with a certain umode set.  Like the wall type message, it does not have a target field.

Messages that are propagated as the umode type are DESYNCH and WALLOPS.

6.2.6 catch

This type of message is not routed at all.  It has no target field, but is considered to be targetted to the application itself.

The only message that are propagated as the catch type is ERROR.

6.3 Message types

A lot of commands behave the same in the way they effect the internal state of a server.  We have essentially seven main types:

server  : Change internal state of server object
client  : Change internal state of client object
channel : Change internal state related to channel
query   : Query remote server for information
remote  : Trigger a different remote action
notice  : Send a one way notice
chat    : Communication between two or more users

The first three change someting in the Server, Client or Channel objects respectively, and/or in the relationships between these objects.  These are thus (mostly) of propagation type wall because all servers need to be synchronized.  The exceptions are INVITE and SILENCE, the first because it is only needed to know at the server local to the invited client that it is invited, and the second because SILENCE has its own synchronization method.

The last four types don't change anything in the servers they pass, until they reach the point of destination.

6.3.1 server

The commands of type server are END_OF_BURST, EOB_ACK, SERVER and SQUIT.  These commands change something in one or more Server objects and control relationship 1.

6.3.2 client

The commands of type client are AWAY, KILL, MODE <nickname>, NICK, QUIT and SILENCE.  These commands change something in a Client object and control relationship 2.

6.3.3 channel

The commands of type channel are BURST, CREATE, INVITE, JOIN, KICK, KILL, MODE <channel_name>, PART and QUIT.  These commands change something in a Channel object and control relationships 3 and 4.  The PART and QUIT messages only change these relationships indirectly when the client is on a channel, the code for it being hidden behind the removal of the Client object.

6.3.4 query

The commands of type query are ADMIN, GLINE, INFO, LINKS, LUSERS, MOTD, NAMES, PING, RPING, STATS, TIME, TRACE, VERSION, WHOIS and WHOWAS.  These commands, when received by the server, send back a reply to the source (client) of the message.  The content of the reply may depend on the umode of the client.  The <prefix> of the reply message(s) must represent the server generating the reply and the target must represent the source of the query.  The TRACE command is special because every server on its path to the target server does send a reply to the source.

6.3.5 notice

The commands of type notice are DESYNCH, ERROR, NOTICE, PONG, RPONG and WALLOPS.

6.3.6 chat

The commands of type chat are PRIVMSG and WALLCHOPS.

6.3.7 remote

The commands of type remote are CONNECT, GLINE (query), GLINE (setting a gline), RPING, RPONG, SETTIME (from client), SETTIME (from server) and UPING.

6.4 Command overview

Table 3 gives an overview of the existing commands that can be used in the <cmd> position in a message line.  Command gives the unabbreviated string while Token gives the abbreviated synonym for the same command.  The Source field specifies whether the <prefix> can refer to a client, server or both as the originator of the message.  p, q and n are as defined in § 6.1.  The column Spaces in last param specifies whether the last parameter is allowed to contain spaces (and thus must be preceded by a <colon>).  Target is as described in § 6.2.  Modified before propagation specifies if the parameters are modified by servers other than the originating server.  Type spefifies the Message Type, described in § 6.3.

6.5 Parameter definitions

6.5.1 ADMIN

Parameters

Description

The target server replies to the source client with numerics 256, 257, 258 and 259. The <text> fields of these numeric replies should describe more or less the following: The text: «Administrative info about <name of the server>». A descriptive name, for instance the name of the company or university running the server. The location of the server (city / country or state). Contact information for the admin, for instance an email address. These four lines are usually specified by the admin in the configuration file of the server.

6.5.2 AWAY

Parameters

The parameter is optional.

Description

	When the parameter is present then the source client object is marked as being away.
	Without the parameter, the source client object is marked as being not away.

6.5.3 BURST

Parameters

The meaning of the following parameters depend on their first character.

If  param_i  starts with a '+' then

If  param_i  starts with a '%',  then i will equal n-1 and

If  param_i  starts with another character then

This message uses the following tokens:

<modes>		[s|p][m][t][i][n][l][k]
<burst_ban_list>		<ban mask> <ban mask><space><burst_ban_list>
<burst_nick_list>		<nicknum> <nicknum><comma><burst_nick_list> <nicknum><colon><ucmodes> <nicknum><colon><ucmodes><comma><burst_nick_list>

where

<comma>		',' (ASCII 44)
<ucmodes>		'ov' (ASCII 111 and ASCII 118) 'v' (ASCII 118) 'o' (ASCII 111)

Description

	A BURST message from a server directly behind a link in the state burst_received or linked causes the local connection over which this illegal message was received to be terminated except when this server is a Trusted Service, in which case the message is accepted (and an appropriate notification is sent to all local +s users).
	If the channel object <channel_name> does not exist then it is created and all its attributes are set appropriately.
	If the channel object <channel_name> already exists and the received <time_stamp> is larger than the existing one then all modes and bans are ignored: only the nicks are processed.
	If the channel object <channel_name> already exists and the received <time_stamp> is smaller than the existing one then all current users are deopped (and devoiced), the channel modes and bans are synchronized and the new creation time is used.
	If the channel object <channel_name> already exist and the received <time_stamp> is equal to the existing one then all incoming modes and bans are added as usual (see MODE).
	The nicks in the <burst_nick_list> are processed as follows: if the <nicknum> is valid and it is from the correct direction, it joins.  If it doesn't exist or is from another direction, we have to ignore it.
	If all nicks are ignored, we remove the channel again when it is empty and don't propagate the BURST message.

6.5.4 CONNECT

Parameters

Description

A CONNECT message is a request to the target server to initiate a connection to another server, whose name matches the given mask.  The target server uses its configuration file to find a suitable server to connect to.

Note

	The target server should broadcast the request using a WALLOPS.
	The destination server may be unable or unwilling to initiate a new connection to the specified mask.  In that case it can send a NOTICE to the source client indicating the reason of failure.  It is possible that this message is delayed, for example when the reason for a failure is a connect timeout.

6.5.5 CREATE

Parameters

Description

	A CREATE message is used for newly created channels.  In effect it is equivalent to a JOIN of the source client and granting him channel operator status.
	When a CREATE message is received for an already existing channel and the received time stamp is smaller than or equal to the creation time of that channel then the creation time of the channel is set to the received creation time and the CREATE message is processed as usual.
	When a CREATE message is received for an already existing channel and the received time stamp is larger than the creation time of that channel then the CREATE is processed as a normal JOIN and a deopping MODE (with the creation time of the local channel as time stamp) is send upstream to deop the source client.

Note

When a CREATE message is received for an already existing channel and the received time stamp is much larger than the creation time of that channel then it makes more sense to use a time stamp of zero for the deopping MODE in order to trigger a DESYNCH notice.  With "much larger" is meant that the difference can not be explained by normal lag and/or clock offsets between servers.

6.5.6 DESYNCH

Parameters

Description

DESYNCH is used to notify the network that desynchronization in clock or network state has been detected between two servers. This may happen for a variety of reasons; the text should be read by humans, but is not intended to be automatically processed by network services.

6.5.7 END_OF_BURST

Parameters

Description

END_OF_BURST is sent as the last line it a server's net.burst. If the originator of this command is a locally connected server, an EOB_ACK message should be sent to acknowledge the end of the burst.

6.5.8 EOB_ACK

Parameters

Description

EOB_ACK is sent as an acknowledgement of an END_OF_BURST message. After this message is sent, channel PRIVMSG messages may be sent in that direction.

6.5.9 ERROR

Parameters

Description

ERROR is sent to indicate that the originating server will disregard any further data sent from the receiving server. The text argument is meant for human consumption.

6.5.10 GLINE

Parameters

Description

6.5.11 GLINE

Parameters

This message uses the following tokens:

<sign>		+|-
<short_hostmask>		<usermask> @ <hostnamemask>
<duration>		<digit> +

where

<usermask>		Printable characters except for @
<hostnamemask>		Characters valid in host names, plus ? and *

Description

	GLINE sets, removes or updates a G-line. A G-line is a ban on certain clients from connecting to one or more servers.
	The target server may be any server's <servnum> or '*' (which indicates all servers). The <sign> before the hostmask indicates whether the G-line should be added/updated or removed; if it is omitted, '+' is assumed. The <duration> is the new duration for the G-line; if an existing G-line has the same <short_hostmask> as this command, its duration is updated with the new value.

Notes:

If the host part of the hostmask is a wildcarded IP mask, then the G-line should be considered valid based on a client's IP address. Otherwise, the host part should be matched against the client's resolved hostname. The method used to resolve a client's hostname is outside the scope of this document.

6.5.12 INFO

Parameters

Description

6.5.13 INVITE

Parameters

Description

6.5.14 JOIN

Parameters

Description

6.5.15 KICK

Parameters

Description

6.5.16 KILL

Parameters

Description

6.5.17 LINKS

Parameters

Optional:

Description

6.5.18 LUSERS

Parameters

Description

6.5.19 MODE

Parameters

Description

6.5.20 MODE

Parameters

The order of the following parameters is the same as the order in which their corresponding <mode> appears in the <mode_block>.

This parameter is always the last parameter, but it is only present when the source of the message is a server.

This message uses the following tokens:

<mode_list>		<mode_block> <mode_block><modelist>
<key>		A <token> not containing any <colon> and not containing any ASCII value smaller than 33.
<limit>		A series of digits (see <digit>) representing an unsigned positive number smaller than 4294967296.
<ban_mask>

Description

6.5.21 MOTD

Parameters

Description

6.5.22 NAMES

Parameters

Description

6.5.23 NICK

Parameters

Description

6.5.24 NICK

Parameters

Parameter 5 is optional.

Description

6.5.25 NOTICE

Parameters

Description

6.5.26 PART

Parameters

Optional:

Description

6.5.27 PING

Parameters

Optional:

Description

6.5.28 PONG

Parameters

Description

6.5.29 PRIVMSG

Parameters

Description

6.5.30 QUIT

Parameters

Description

6.5.31 RPING

Parameters

Description

6.5.32 RPING

Parameters

Description

6.5.33 RPONG

Parameters

Description

6.5.34 RPONG

Parameters

Description

6.5.35 SERVER

Parameters

Description

6.5.36 SETTIME

Parameters

Description

6.5.37 SETTIME

Parameters

Description

6.5.38 SILENCE

Parameters

Description

6.5.39 SQUIT

Parameters

Description

6.5.40 STATS

Parameters

Optional:

Description

6.5.41 TIME

Parameters

Description

6.5.42 TOPIC

Parameters

Optional:

Description

6.5.43 TRACE

Parameters

Description

6.5.44 UPING

Parameters

Description

6.5.45 VERSION

Parameters

Description

6.5.46 WALLCHOPS

Parameters

Description

6.5.47 WALLOPS

Parameters

Description

6.5.48 WHOIS

Parameters

Description

6.5.49 WHOWAS

Parameters

Description

6.6 Numerics

6.6.1 Type 1

<prefix><space><numeric><space><nickname><space><colon><text>

where

<numeric>		<digit><digit><digit>
<text>		<last_token>