First draft of a more complete TS6 server protocol description.

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 <rehash type>.
+
+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