From: Jilles Tjoelker Date: Sun, 25 Jan 2009 20:11:28 +0000 (+0100) Subject: First draft of a more complete TS6 server protocol description. X-Git-Tag: charybdis-3.1.0~25 X-Git-Url: https://jfr.im/git/irc/rqf/shadowircd.git/commitdiff_plain/03a905bd21a168678d0e563bcaeac189fb3f0145 First draft of a more complete TS6 server protocol description. --- diff --git a/doc/technical/ts6-protocol.txt b/doc/technical/ts6-protocol.txt new file mode 100644 index 0000000..6aebbd9 --- /dev/null +++ b/doc/technical/ts6-protocol.txt @@ -0,0 +1,890 @@ +TS6 protocol description +Written by Jilles Tjoelker + +General format: much like rfc1459 +Maximum parameters for a command: 15 (this does not include the prefix +and command name) + +SID: a server's unique ID. It is configured in each server and consists of +a digit and two alphanumerics. Sending SIDs with lowercase letters is +questionable. + +UID: a client's unique ID. It consists of the server's SID and six +alphanumerics (so it is nine characters long). The first of the alphanumerics +should be a letter, numbers are legal but reserved for future use. + +hunted: a parameter type used for various remote requests. From local users, +nicknames and server names are accepted, possibly with wildcards; from servers, +UIDs/SIDs (sending names or even wildcards is deprecated). This is done with +the function hunt_server(). Any rate limiting should be done locally. + +duration: a parameter type used for ban durations. It is a duration in seconds. +A value of 0 means a permanent ban. + +propagation: to which other servers the command is sent. For all commands +with a hunted parameter, the propagation is determined by that, and not +otherwise specified. Propagation broadcast means the command is sent to all +servers. Propagation one-to-one means the command is only sent to the target +or the server the target is on. Propagation none means the command is never +sent to another server if it is received. For some other commands, the +propagation depends on the parameters and is described in text. + +services server: server mentioned in a service{} block. There are no services +servers on EFnet. + +service: client with umode +S. This implies that it is on a services server. + +user modes: +(all) ++D (deaf: does not receive channel messages) ++S (network service) (only settable on burst from a services server) ++a (appears as server administrator) ++i (invisible, see rfc1459) ++o (IRC operator, see rfc1459) ++w (wallops, see rfc1459) (always propagated for historical reasons) +(charybdis TS6) ++Q/+R/+g/+l/+s/+z (only locally effective) ++Z (ssl user) (only settable on burst) +possibly more added by modules + +channel modes: +(all) +statuses ++o (prefix @) (ops) ++v (prefix +) (voice) +type A ++b (ban) ++e (ban exception) ++I (invite exception) +type B ++k (key: password required to join, <= 23 ascii chars, no : or , or whitespace) +type C ++l (limit: maximum number of members before further joins are disallowed) +type D ++m (moderated) ++n (no external messages) ++p (private: does not appear in /whois to non-members, no /knock allowed) ++r (only registered users may join) (only if a services server exists) ++s (secret) ++t (only chanops may change topic) +(charybdis TS6) +type A ++q (quiet) +type C ++f (forward: channel name <= 30 chars) ++j (join throttle: N:T with integer N and T) +type D ++F (free target for +f) ++L (large ban list) ++P (permanent: does not disappear when empty) ++Q (ignore forwards to this) ++c (strip colours) ++g (allow any member to /invite) ++z (send messages blocked by +m to chanops) + +ADMIN +source: user +parameters: hunted + +Remote ADMIN request. + +AWAY +source: user +propagation: broadcast +parameters: opt. away reason + +If the away reason is empty or not present, mark the user as not away. +Otherwise, mark the user as away. + +Changing away reason from one non-empty string to another non-empty string +may not be propagated. + +BMASK +source: server +propagation: broadcast +parameters: channelTS, channel, type, space separated masks + +If the channelTS in the message is greater (newer) than the current TS of +the channel, drop the message and do not propagate it. + +Type is the mode letter of a ban-like mode. In efnet TS6 this is 'b', 'e' or +'I'. In charybdis TS6 additionally 'q' is possible. + +Add all the masks to the given list of the channel. + +All ban-like modes must be bursted using this command, not using MODE or TMODE. + +CAPAB +source: unregistered server +propagation: none +parameters: space separated capability list + +Sends capabilities of the server. This must include QS and ENCAP. + +CHGHOST +charybdis TS6 +source: any +propagation: broadcast +parameters: client, new hostname + +Changes the visible hostname of a client. + +Opers are notified unless the source is a server or a service. + +CONNECT +source: any +parameters: server to connect to, port, hunted + +Remote connect request. A server WALLOPS should be sent by the receiving +server. + +The port can be 0 for the default port. + +DLINE +charybdis TS6 +encap only +source: user +parameters: duration, mask, reason + +Sets a D:line (IP ban checked directly after accepting connection). + +The mask must be an IP address or CIDR mask. + +ENCAP +source: any +parameters: target server mask, subcommand, opt. parameters... + +Sends a command to all servers with names matching the given mask (for example +'*', '*.example.com', 'irc.example.com'). Those servers do not have to be +directly connected. Targets cannot be SIDs. + +Propagation is independent of understanding the subcommand. + +ERROR +source: server or unregistered server +propagation: none +parameters: error message + +Reports a (usually fatal) error with the connection. + +Error messages may contain IP addresses and have a negative effect on server +IP hiding. + +ETRACE +encap only +encap target: single server +source: oper +parameters: client + +Remote ETRACE information request. + +EUID +charybdis TS6 +capab: EUID +source: server +parameters: nickname, hopcount, nickTS, umodes, username, visible hostname, IP address, UID, real hostname, account name, gecos +propagation: broadcast + +Introduces a client. The client is on the source server of this command. + +The account name is '0' if the user is not logged in with services. + +Nick TS rules apply. + +EUID is similar to UID but includes the ENCAP REALHOST and ENCAP LOGIN +information. + +GCAP +encap only +encap target: * +source: server +parameters: space separated capability list + +Capability list of remote server. + +INFO +source: user +parameters: hunted + +Remote INFO request. + +INVITE +source: user +parameters: target user, channel, opt. channelTS +propagation: one-to-one + +Invites a user to a channel. + +If the channelTS is greater (newer) than the current TS of the channel, drop +the message. + +Not sending the channelTS parameter is deprecated. + +JOIN +1. +source: user +parameters: '0' (one ASCII zero) +propagation: broadcast + +Parts the source user from all channels. + +2. +source: user +parameters: channelTS, channel, '+' (a plus sign) +propagation: broadcast + +Joins the source user to the given channel. If the channel does not exist yet, +it is created with the given channelTS and no modes. If the channel already +exists and has a greater (newer) TS, wipe all simple modes and statuses and +change the TS, notifying local users of this but not servers (note that +ban-like modes remain intact; invites may or may not be cleared). + +KICK +source: any +parameters: channel, target user, opt. reason +propagation: broadcast + +Kicks the target user from the given channel. + +Unless the channel's TS is 0, no check is done whether the source user has ops. + +Not sending the reason parameter is questionable. + +KILL +source: any +parameters: target user, path +propagation: broadcast + +Removes the user from the network. + +The format of the path parameter is some sort of description of the source of +the kill followed by a space and a parenthesized reason. To avoid overflow, +it is recommended not to add anything to the path. + +KLINE +1. +encap only +source: user +parameters: duration, user mask, host mask, reason + +Sets a K:line (ban on user@host). + +2. +capab: KLN +source: user +parameters: target server mask, duration, user mask, host mask, reason + +As form 1, deprecated. + +KNOCK +source: user +parameters: channel +propagation: broadcast + +Requests an invite to a channel that is locked somehow (+ikl). Notifies all +operators of the channel. (In charybdis, on +g channels all members are +notified.) + +This is broadcast so that each server can store when KNOCK was used last on +a channel. + +LINKS +source: user +parameters: hunted, server mask + +Remote LINKS request. The server mask limits which servers are listed. + +LOGIN +encap only +source: user +parameters: account name + +In a burst, states that the source user is logged in as the account. + +LUSERS +source: user +parameters: server mask, hunted + +Remote LUSERS request. Most servers ignore the server mask, treating it as '*'. + +MODE +1. +source: user +parameters: client, umode changes +propagation: broadcast + +Propagates a user mode change. The client parameter must refer to the same user +as the source. + +Not all umodes are propagated to other servers. + +2. +source: any +parameters: channel, cmode changes, opt. cmode parameters... + +Propagates a channel mode change. + +This is deprecated because the channelTS is not included. If it is received, +it should be propagated as TMODE. + +MOTD +source: user +parameters: hunted + +Remote MOTD request. + +NICK +1. +source: user +parameters: new nickname, new nickTS +propagation: broadcast + +Propagates a nick change. + +2. +source: server +parameters: nickname, hopcount, nickTS, umodes, username, hostname, server, gecos + +Historic TS5 user introduction. The user is on the server indicated by the +server parameter; the source server is meaningless (local link). + +NICKDELAY +charybdis TS6 +encap only +encap target: * +source: services server +parameters: duration, nickname + +If duration is greater than 0, makes the given nickname unavailable for that +time. + +If duration is 0, removes a nick delay entry for the given nickname. + +There may or may not be a client with the given nickname; this does not affect +the operation. + +NOTICE +source: any +parameters: msgtarget, message + +As PRIVMSG, except NOTICE messages are sent out, server sources are permitted +and most error messages are suppressed. + +OPERSPY +encap only +encap target: * +source: user +parameters: command name, parameters + +Reports operspy usage. + +OPERWALL +source: user +parameters: message +propagation: broadcast + +Sends a message to operators (with umode +z set). + +PART +source: user +parameters: comma separated channel list, message + +Parts the source user from the given channels. + +PASS +source: unregistered server +parameters: password, 'TS', TS version, SID + +Sends the server link password, TS version and SID. + +PING +source: any +parameters: origin, destination server + +Sends a PING to the destination server, which will reply with a PONG. + +The origin field is not used in the server protocol. + +Remote PINGs are used for end-of-burst detection, therefore all servers must +implement them. + +PONG +source: server +parameters: origin, destination + +Routes a PONG back to the destination that originally sent the PING. + +PRIVMSG +source: user +parameters: msgtarget, message + +Sends a normal message (PRIVMSG) to the given target. + +The target can be: +- a client + propagation: one-to-one +- a channel name + propagation: all servers with -D users on the channel + (cmode +m/+n should be checked everywhere, bans should not be checked + remotely) +- a status character ('@'/'+') followed by a channel name, to send to users + with that status or higher only. + propagation: all servers with -D users with appropriate status +- a user@server message, to send to users on a specific server. The exact + meaning of the part before the '@' is not prescribed, except that "opers" + allows IRC operators to send to all IRC operators on the server in an + unspecified format. + propagation: one-to-one +- a message to all users on server names matching a mask ('$$' followed by mask) + propagation: broadcast +- a message to all users with hostnames matching a mask ('$#' followed by mask). + Note that this is often implemented poorly. + propagation: broadcast + +PRIVS +charybdis TS6 +encap only +encap target: single server +source: oper +parameters: client + +Remote PRIVS information request. + +QUIT +source: user +parameters: comment + +Propagates quitting of a client. No QUIT should be sent for a client that +has been removed as result of a KILL message. + +REALHOST +charybdis TS6 +encap only +encap target: * +source: user +parameters: real hostname + +In a burst, propagates the real host of a dynamically-spoofed user. + +REHASH +charybdis TS6 +encap only +source: user +parameters: opt. rehash type + +Remote REHASH request. If the rehash type is omitted, it is equivalent to +a regular /rehash, otherwise it is equivalent to /rehash . + +RESV +1. +encap only +source: user +parameters: duration, mask, reason + +Sets a RESV, making a nickname mask or exact channel unavailable. + +2. +capab: CLUSTER +source: user +parameters: target server mask, duration, mask, reason + +As form 1, deprecated. + +RSFNC +encap only +capab: RSFNC +encap target: single server +source: services server +parameters: target user, new nickname, old nickTS, new nickTS + +Forces a nickname change and propagates it. + +The command is ignored if the nick TS of the user is not equal to the old +nickTS parameter. If the new nickname already exists (and is not the target +user), it is killed first. + +SASL +charybdis TS6 +encap only +1. +encap target: * +source: server +parameters: source uid, '*', 'S', sasl mechanism name + +Requests that a SASL agent (a service) initiate the authentication process. +The source uid is that of an unregistered client. This is why it is not sent +as the prefix. + +2. +encap target: single server +source: server +parameters: source uid, target uid, mode, data + +Part of a SASL authentication exchange. The mode is 'C' to send some data +(base64 encoded), or 'S' to end the exchange (data indicates type of +termination: 'A' for abort, 'F' for authentication failure, 'S' for +authentication success). + +SAVE +capab: SAVE +source: server +propagation: broadcast +parameters: target uid, TS + +Resolve a nick collision by changing a nickname to the UID. + +The server should verify that the UID belongs to a registered user, the user +does not already have their UID as their nick and the TS matches the user's +nickTS. If not, drop the message. + +SAVE should be propagated as a regular NICK change to links without SAVE capab. +present. + +SERVER +1. +source: unregistered server +parameters: server name, hopcount, server description + +Registers the connection as a server. PASS and CAPAB must have been sent +before, SVINFO should be sent afterwards. + +If there is no such server configured or authentication failed, the connection +should be dropped. + +This is propagated as a SID message. + +2. +source: server +propagation: broadcast +parameters: server name, hopcount, server description + +Introduces a new TS5 server, directly connected to the source of this command. +This is only used for jupes as TS5 servers may do little else than existing. + +SID +source: server +propagation: broadcast +parameters: server name, hopcount, sid, server description + +Introduces a new server, directly connected to the source of this command. + +SIGNON +source: user +propagation: broadcast +parameters: new nickname, new username, new visible hostname, new nickTS, new login name + +Broadcasts a change of several user parameters at once. + +Currently only sent after an SVSLOGIN. + +SJOIN +source: server +propagation: broadcast +parameters: channelTS, simple modes, opt. mode parameters..., nicklist + +Broadcasts a channel creation or bursts a channel. + +The nicklist consists of users joining the channel, with status prefixes for +their status ('@+', '@', '+' or ''), for example: +'@+1JJAAAAAB +2JJAAAA4C 1JJAAAADS'. All users must be behind the source server +so it is not possible to use this message to force users to join a channel. + +The interpretation depends on the channelTS and the current TS of the channel. +If either is 0, set the channel's TS to 0 and accept all modes. Otherwise, if +the incoming channelTS is greater (newer), ignore the incoming simple modes +and statuses and join and propagate just the users. If the incoming channelTS +is lower (older), wipe all modes and change the TS, notifying local users of +this but not servers (invites may be cleared). In the latter case, kick on +split riding may happen: if the key (+k) differs or the incoming simple modes +include +i, kick all local users, sending KICK messages to servers. + +SJOIN must be used to propagate channel creation and in netbursts. For regular +users joining channels, JOIN must be used. Pseudoservers may use SJOIN to join +a user with ops. + +SNOTE +charybdis TS6 +encap only +source: server +parameters: snomask letter, text + +Sends the text as a server notice from the source server to opers with the +given snomask set. + +SQUIT +parameters: target server, comment + +Removes the target server and all servers and users behind it from the network. + +If the target server is the receiving server or the local link this came from, +this is an announcement that the link is being closed. + +Otherwise, if the target server is locally connected, the server should send +a WALLOPS announcing the SQUIT. + +STATS +source: user +parameters: stats letter, hunted + +Remote STATS request. Privileges are checked on the server executing the +actual request. + +SU +encap only +encap target: * +source: services server +parameters: target user, new login name (optional) + +If the new login name is not present or empty, mark the target user as not +logged in, otherwise mark the target user as logged in as the given account. + +SVINFO +source: server +propagation: none +parameters: current TS version, minimum TS version, '0', current time + +Verifies TS protocol compatibility and clock. If anything is not in order, +the link is dropped. + +The current TS version is the highest version supported by the source server +and the minimum TS version is the lowest version supported. + +The current time is sent as a TS in the usual way. + +SVSLOGIN +charybdis TS6 +encap only +encap target: single server +source: services server +parameters: target, new nick, new username, new visible hostname, new login name + +Sent after successful SASL authentication. + +The target is a UID, typically an unregistered one. + +Any of the "new" parameters can be '*' to leave the corresponding field +unchanged. The new login name can be '0' to log the user out. + +If the UID is registered on the network, a SIGNON with the changes will be +broadcast, otherwise the changes will be stored, to be used when registration +completes. + +TB +source: server +propagation: broadcast +parameters: + +TIME +source: user +parameters: hunted + +Remote TIME request. + +TMODE +source: any +parameters: channelTS, channel, cmode changes, opt. cmode parameters... + +Propagates a channel mode change. + +If the channelTS is greater (newer) than the current TS of the channel, drop +the message. + +On input, only the limit on parameters per line restricts how many cmode +parameters can be present. Apart from this, arbitrary modes shall be +processed. Redundant modes may be dropped. For example, +n-n may be applied and +propagated as +n-n, -n or (if the channel was already -n) nothing, but not as ++n. + +The parameter for mode -k (removing a key) shall be ignored. + +On output, at most ten cmode parameters should be sent; if there are more, +multiple TMODE messages should be sent. + +TOPIC +source: user +propagation: broadcast + +Propagates a channel topic change. The server may verify that the source has +ops in the channel. + +TRACE +source: user +1. +parameters: hunted + +Performs a trace to the target, sending 200 numerics from each server passing +the message on. The target server sends a description of the target followed +by a 262 numeric. + +TRACE, STATS l and STATS L are the only commands using hunt_server that use the +hunted parameter for more than just determining which server the command +should be executed on. + +2. +parameters: target name, hunted + +Executes a trace command on the target server. No 200 numerics are sent. +The target name is a name, not a UID, and should be on the target server. + +UID +source: server +propagation: broadcast +parameters: nickname, hopcount, nickTS, umodes, username, visible hostname, IP address, UID, gecos +propagation: broadcast + +Introduces a client. The client is on the source server of this command. + +Nick TS rules apply. + +UNDLINE +charybdis TS6 +encap only +source: user +parameters: mask + +Removes a D:line (IP ban checked directly after accepting connection). + +The mask must be an IP address or CIDR mask. + +UNKLINE +1. +encap only +source: user +parameters: user mask, host mask + +Removes a K:line (ban on user@host). + +2. +capab: UNKLN +source: user +parameters: target server mask, user mask, host mask + +As form 1, deprecated. + +UNRESV +1. +encap only +source: user +parameters: mask + +Removes a RESV. + +2. +capab: CLUSTER +source: user +parameters: target server mask, mask + +As form 1, deprecated. + +UNXLINE +1. +encap only +source: user +parameters: mask + +Removes an X:line (ban on realname). + +2. +capab: CLUSTER +source: user +parameters: target server mask, mask + +As form 1, deprecated. + +USERS +source: user +parameters: hunted + +Remote USERS request. + +VERSION +source: any +parameters: hunted + +Remote VERSION request. + +WALLOPS +1. +source: user +parameters: message +propagation: broadcast + +In efnet TS6, sends a message to operators (with umode +z set). This is a +deprecated equivalent to OPERWALL. + +In charybdis TS6, sends a message to local users with umode +w set (or possibly +another indication that WALLOPS messages should be sent), including non-opers. + +2. +source: server +parameters: message +propagation: broadcast + +Sends a message to local users with umode +w set (or possibly another +indication that WALLOPS messages should be sent). + +In efnet TS6 this may include non-opers, in charybdis TS6 this may only be +sent to opers. + +WHOIS +source: user +parameters: hunted, target nick + +Remote WHOIS request. + +XLINE +1. +encap only +source: user +parameters: duration, mask, reason + +Sets an X:line (ban on realname). + +2. +capab: CLUSTER +source: user +parameters: target server mask, duration, mask, reason + +As form 1, deprecated. + +Local only commands (charybdis 3.1): + +ACCEPT +AUTHENTICATE +CAP +CHALLENGE +CHANTRACE +CLOSE +CNOTICE +CPRIVMSG +DIE +GET +HELP +ISON +LIST +LOCOPS +MAP +MASKTRACE +MODLIST +MODLOAD +MODRELOAD +MODRESTART +MODUNLOAD +MONITOR +NAMES +OPER +POST +PUT +RESTART +SCAN +SET +TESTGECOS +TESTLINE +TESTMASK +UHELP +UNREJECT +USER +USERHOST +WEBIRC +WHO +WHOWAS