Server protocol:Introduction

Below we explain the server to server protocol. It is often used by people who want to write their own Services.

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 highly recommend to use 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. See the PROTOCOL command to see which tokens are supported.

UnrealIRCd 3.4.x uses the following (feel free to copy-paste): PROTOCTL NOQUIT NICKv2 SJOIN SJOIN2 UMODE2 VL SJ3 TKLEXT TKLEXT2 NICKIP ESVID PROTOCTL SID=999 MLOCK EXTSWHOIS

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

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

NETINFO - Network information
The NETINFO command is used to share your configuration settings with other servers. This way some things can be verified, for example that the cloak keys match on both ends.

Syntax: NETINFO maxglobal currenttime protocolversion cloakhash 0 0 0 :networkname

Where:
 * maxglobal: the maximum number of clients ever seen (global), used for statistics.
 * currenttime: current unix time stamp.
 * protocolversion: see Server protocol:protocol version.
 * cloakhash: a hash of the cloak keys used to verify that both servers have the same set of cloak keys. Most services coders use * here instead.
 * networkname: the network name, as set in set::network-name.

Example: NETINFO 0 12345678 2400 * 0 0 0 :SomeNet

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

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.