Server protocol:Introduction

This article gives an introduction to UnrealIRCd's server to server protocol. It is often used by people who want to write their own Services.

If you are writing your own IRC client or IRC bot then you should use the IRC client protocol instead. This is not documented here on this page. RFC1459 may be of help.

Before you get started
If you are completely new to the IRC protocol then you probably want to read RFC1459 which explains basic message parsing and the client protocol.

Below we will explain the server protocol, which is used to 'link' servers. This protocol has a lot more requirements and is more complex than to implement a basic IRC client. Basic rules about IRC message parsing are the same for both client and server, however.

As said earlier, if you are just writing an IRC client or IRC bot then you should not read this article. Instead connect as a regular client and follow RFC1459.

A word about time
Unreal is very time-dependant. Users and channels, for example, are timestamped, and if server clocks are not synchronized properly, things can go very wrong very fast. See FAQ: Why correct time is important.

UnrealIRCd uses UNIX time, which is the number of seconds since since Midnight January 1, 1970 GMT. This means that time zones are no problem, nor is daylight savings time. For more information you could read the wikipedia article.

Connecting
The first step to establish a server-to-server communication is open a TCP/IP connection to the target host and port. You should connect to one of the ports that UnrealIRCd is listening on. If your program connects to UnrealIRCd on the same machine (so, localhost) then you can use a regular connection, otherwise we require SSL/TLS.

To configure UnrealIRCd to accept your incoming server link, you must configure a Link block.

Basic operations
The PING command MUST be implemented, otherwise your server will keep disconnecting or may not get connected at all.

PING - Check connection query
On IRC a PING is used to check if a connection is still alive. Whenever you recieve a PING you must reply with a PONG. Failure to reply in time will cause your connection to be closed by the server.

Syntax: :source PING [:target]

Example: PING :maintest.test.net

Suggested reply: PONG :maintest.test.net

PONG - Check connection reply
A pong will be used to reply to a ping. See previous item for more information. Syntax: PONG :xxx

If you never send a PING yourself, then you won't receive a PONG either so you can skip implementing this.

Server negotiation
These commands are used when you are connecting your server to UnrealIRCd. They should be sent as soon as the TCP/IP connection is established.

PASS - Connection password
This should be the first command you will be sending. The PASS command is used to transmit the password required for a server link. It must match the password specified in UnrealIRCd's link::password. PASS :xyz

PROTOCTL - Server protocol negotiation
The PROTOCTL command is used to enable certain server protocol features. In almost all cases you are expected to send one or more PROTOCTL lines after having sent PASS.

You can use: PROTOCTL EAUTH=my.server.name SID=999 PROTOCTL NOQUIT NICKv2 SJOIN SJ3 CLK TKLEXT TKLEXT2 NICKIP ESVID MLOCK EXTSWHOIS

Replace the 999 in the SID=999 with your Server ID.

See the PROTOCOL command for a full list of tokens which are supported and what they do.

SERVER - Introducing yourself
The SERVER command is used to tell the other side your server name, at the same time some version information is shared too.

You can use the following syntax: SERVER server.name 1 :server description

For more details see SERVER command.

EOS - End Of Synch
By sending this you mark the end of the synching process.

EOS

Server operations
To keep track of servers on a network you need to implement the commands explained below. Servers may connect (SERVER & SID), disconnect (SQUIT) or have their description changed (SDESC).

SERVER - Server introduction
The command indicates that the server named new.server is being introduced by the source (the source is the server which new.server is directly linked to). The hopcount will be the number of links the receiving server would have to cross to reach new.server. In other words, new.server introduced itself with a hopcount of 1, and as the SERVER message is passed along, hopcount is incremented.

As an example, a services server faking a SERVER message for JUPE functionality would use a hopcount of 2.

TODO: this documents the old server command, should (also) document the new SID.

SQUIT - Server removal
Syntax: :source SQUIT server.name :reason When you receive this the server named server.name has disconnected from the IRC network (de-linked). This can be forcefully due to an IRCOp issuing /SQUIT, but it can also be because of network issues or other reasons.

SDESC - Update server description
Syntax: :source SDESC :new description This changes the server description of the source. The server description is normally set in the config as me::info and is actually little used. It is shown in /LINKS.

UID - User introduction (new)
Syntax: UID nickname hopcount timestamp username hostname uid servicestamp usermodes virtualhost cloakedhost ip :gecos

See the Server protocol:UID command for more information.

NICK - Nick change
The following syntax is used when a user changes his/her nickname: :oldnick NICK newnick :timestamp The timestamp is the UNIX timestamp of when the nick change happened.

NICK - User introduction (old)
Syntax with NICKv2+NICKIP+CLK: NICK nickname hopcount timestamp username hostname server servicestamp usermodes virtualhost cloakedhost ip :realname

This command is identical to the Server protocol:UID command from above, except the uid field is the name of the server instead.

QUIT - User disconnect
Syntax: :nick QUIT :reason

This command indicates that a user has disconnected.

KILL - Force user disconnect
Syntax: :source KILL target :killpath!source (reason)

A kill is used when an IRC Operator did /KILL nick reason or when the server removed a user from IRC, for example due to triggering flood controls, a Spamfilter, a Nick collision, etc.

Other
There are many other client commands.

Tracking user@host changes
If you need to keep track of user/host changes (and you probably do) then you need to implement these commands. They are actually very easy to implement. These commands are used either directly by an end-user (eg: user doing /SETNAME xyz), or broadcasted sent by commands such as /VHOST (which will broadcast a SETHOST command to all servers).
 * SETIDENT, CHGIDENT, SETHOST, CHGHOST, SETNAME, CHGNAME

Other user property changes
A user can have special /WHOIS lines added and removed:
 * Server protocol:SWHOIS