| Tip of the day: Exempt your IP address from bans, just in case you or a fellow IRCOp accidentally GLINES you. |
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 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.
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. For example:
link services.test.net {
incoming {
mask 127.0.0.1;
}
password "test";
class servers;
}
This would accept connections from 127.0.0.1 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 {
services.test.net;
}
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. 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 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 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.
EOS
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
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.
User operations
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 upon other commands such as /VHOST or /OPER.
Other user property changes
- A user can have special /WHOIS lines added and removed, see Server protocol:SWHOIS
- A user can have MODDATA attached to it, see Server protocol:MD
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.