Tip of the day: Check out Special users on how to give trusted users/bots more rights without making them IRCOp.

Server protocol:Introduction

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

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 are in the wrong place. For the client protocol have a look at https://modern.ircdocs.horse/ and RFC1459 instead.

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.

TIP: People often use anope services in debug mode (bin/services -debug -nofork) on a test network to learn about server traffic. It can be useful to combine this document + anope in debug mode together, to get a better learning experience.

A word about time

Unreal is very time-dependant. Users and channels, for example, are timestamped. If server clocks are not synchronized properly, things can go very wrong very fast. If you want to know why, then 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.


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. For example:

link services.test.net {
        incoming {
        password "test";
        class servers;

This would accept connections from only, with the password test.

If your server is going to be a services server then you should also list it in the ULines block:

ulines {

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.


:source PING [:target]


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. If the server uses a certificate fingerprint as an authentication mechanism then send a * as the 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 

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

See the PROTOCTL 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.

If you wonder why this is important: this is used to see the difference between synching activity and normal activity. As an example, joins during synching are not counted as flooding for channel mode +f.


NETINFO - Network information

Server protocol:NETINFO Command

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

:source SERVER new.server hopcount :description

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


: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


: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.

User operations

UID - User introduction (new)


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


:nick QUIT :reason

This command indicates that a user has disconnected.

KILL - Force user disconnect


: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.


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 upon other commands such as /VHOST or /OPER.

Other user property changes

Channel operations

TODO. Server protocol:SJOIN command etc...

Services operations

UnrealIRCd has over 10 commands that are meant to be used by Services only. They all start with the letters SVS. They are not documented in this wiki at the moment, but as a normal user you can use the command HELPOP SVSCMDS on IRC to view the documentation for these commands.