X-Git-Url: https://jfr.im/git/irc/rqf/shadowircd.git/blobdiff_plain/03a905bd21a168678d0e563bcaeac189fb3f0145..c554add299fb870b44957e3c7f7a8e743abceb1c:/doc/technical/ts6-protocol.txt diff --git a/doc/technical/ts6-protocol.txt b/doc/technical/ts6-protocol.txt index 6aebbd9..64beadb 100644 --- a/doc/technical/ts6-protocol.txt +++ b/doc/technical/ts6-protocol.txt @@ -21,19 +21,45 @@ 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. +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. + +For all commands with a target server mask parameter, the propagation is +determined by that, and not otherwise specified. The command is sent 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 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. +connection setup: +The initiator sends the PASS, CAPAB and SERVER messages. Upon receiving the +SERVER, the listener will check the information, and if it is valid, it will +send its own PASS, CAPAB and SERVER messages, followed by SVINFO and the burst. +Upon receiving the SERVER, the initiator will send SVINFO and the burst. If +ziplinks are used, SVINFO is the first compressed message. + +The burst consists of SID and SERVER messages for all known servers, BAN +messages for all propagated bans, UID or EUID messages for all known users +(possibly followed by ENCAP REALHOST, ENCAP LOGIN and/or AWAY) and SJOIN +messages for all known channels (possibly followed by BMASK and/or TB). + user modes: (all) +D (deaf: does not receive channel messages) @@ -54,8 +80,8 @@ statuses +v (prefix +) (voice) type A +b (ban) -+e (ban exception) -+I (invite exception) ++e (ban exception) (capab: EX) ++I (invite exception) (capab: IE) type B +k (key: password required to join, <= 23 ascii chars, no : or , or whitespace) type C @@ -64,7 +90,7 @@ 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) ++r (only registered users may join) (only if a services server exists) (capab: SERVICES) +s (secret) +t (only chanops may change topic) (charybdis TS6) @@ -82,6 +108,29 @@ type D +g (allow any member to /invite) +z (send messages blocked by +m to chanops) + +source: server +parameters: target, any... + +The command name should be three decimal ASCII digits. + +Propagates a "numeric" command reply, such as from a remote WHOIS request. + +If the first digit is 0 (indicating a reply about the local connection), it +should be changed to 1 before propagation or sending to a user. + +Numerics to the local server may be sent to opers. + +To avoid infinite loops, servers should not send any replies to numerics. + +The target can be: +- a client + propagation: one-to-one +- a channel name + propagation: all servers with -D users on the channel + +Numerics to channels are broken in some older servers. + ADMIN source: user parameters: hunted @@ -99,6 +148,45 @@ Otherwise, mark the user as away. Changing away reason from one non-empty string to another non-empty string may not be propagated. +BAN +charybdis TS6 +capab: BAN +source: any +propagation: broadcast (restricted) +parameters: type, user mask, host mask, creation TS, duration, lifetime, oper, reason + +Propagates a network wide ban. + +The type is K for K:lines, R for resvs and X for X:lines; other types are +reserved. The user mask field is only used for K:lines; for resvs and X:lines +the field is ignored in input and sent as an asterisk. + +The creation TS indicates when this ban was last modified. An incoming ban MUST +be ignored and not propagated if the creation TS is older than the creation TS +of the current ban. If the ban is identical, it SHOULD NOT be propagated to +avoid unnecessary network traffic. (Two changes to bans that set the TS to the +same value may cause desynchronization.) + +The duration is 0 for an unban and relative to the creation TS for a ban. +When the duration has passed, the ban is no longer active but it may still +be necessary to remember it. + +The lifetime is relative to the creation TS and indicates for how long this +ban needs to be remembered and propagated. This MUST be at least the duration. +Initially, it is usually set the same as the duration but when the ban is +modified later, it SHOULD be set such that the modified ban is remembered at +least as long as the original ban. This ensures that the original ban does not +revive via split servers. This requirement is only a SHOULD to allow for +implementations that only inject bans and do not remember any; implementations +that remember and propagate bans MUST set the lifetime appropriately. + +The oper field indicates the oper that originally set the ban. If this message +is the initial propagation of a change, it SHOULD be sent as * (an asterisk). + +The reason field indicates the reason for the ban. Any part after a | (vertical +bar) MUST NOT be shown to normal users. The rest of the field and the creation +TS and duration MAY be shown to normal users. + BMASK source: server propagation: broadcast @@ -119,7 +207,13 @@ source: unregistered server propagation: none parameters: space separated capability list -Sends capabilities of the server. This must include QS and ENCAP. +Sends capabilities of the server. This must include QS and ENCAP. It is also +strongly recommended to include EX, CHW, IE and KNOCK, and for charybdis TS6 +also SAVE and EUID. For use with services, SERVICES and RSFNC are strongly +recommended. + +The capabilities may depend on the configuration for the server they are sent +to. CHGHOST charybdis TS6 @@ -154,11 +248,10 @@ 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. +Sends a command to matching servers. Propagation is independent of +understanding the subcommand. -Propagation is independent of understanding the subcommand. +Subcommands are listed elsewhere with "encap only". ERROR source: server or unregistered server @@ -202,6 +295,41 @@ parameters: space separated capability list Capability list of remote server. +GLINE +efnet TS6 +capab: GLN +source: user +parameters: user mask, host mask, reason +propagation: broadcast + +Propagates a G:line vote. Once votes from three different opers (based on +user@host mask) on three different servers have arrived, trigger the G:line. +Pending G:lines expire after some time, usually ten minutes. Triggered G:lines +expire after a configured time which may differ across servers. + +Requests from server connections must be propagated, unless they are found to +be syntactically invalid (e.g. '!' in user mask). Therefore, disabling glines +must not affect propagation, and too wide glines, double votes and glines that +already exist locally must still be propagated. + +Of course, servers are free to reject gline requests from their own operators. + +GUNGLINE +efnet TS6 +encap only +encap target: * +source: user +parameters: user mask, host mask, reason +propagation: broadcast + +Propagates a G:line removal vote. Once three votes have arrived (as with +G:lines), remove the G:line. Pending G:lines removals expire after some time, +usually ten minutes. + +Pending G:line removals do not interact with pending G:lines. Triggering a +G:line does not affect a pending G:line removal. Triggering a G:line removal +does not affect a pending G:line. + INFO source: user parameters: hunted @@ -239,6 +367,8 @@ 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). +A JOIN is propagated with the new TS of the channel. + KICK source: any parameters: channel, target user, opt. reason @@ -277,6 +407,7 @@ parameters: target server mask, duration, user mask, host mask, reason As form 1, deprecated. KNOCK +capab: KNOCK source: user parameters: channel propagation: broadcast @@ -294,6 +425,22 @@ parameters: hunted, server mask Remote LINKS request. The server mask limits which servers are listed. +LOCOPS +1. +encap only +source: user +parameters: text + +Sends a message to operators (with umode +l set). This is intended to be +used for strict subsets of the network. + +2. +capab: CLUSTER +source: user +parameters: target server mask, text + +As form 1, deprecated. + LOGIN encap only source: user @@ -307,6 +454,28 @@ parameters: server mask, hunted Remote LUSERS request. Most servers ignore the server mask, treating it as '*'. +MLOCK +charybdis TS6 +source: services server +parameters: channelTS, channel, cmode changes, opt. cmode parameters... +propagation: broadcast (restricted) + +Propagates a channel mode lock 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. + +An MLOCK message with no modes disables the MLOCK, therefore the MLOCK message +always contains the literal MLOCK for simplicity. + MODE 1. source: user @@ -370,6 +539,9 @@ parameters: msgtarget, message As PRIVMSG, except NOTICE messages are sent out, server sources are permitted and most error messages are suppressed. +Servers may not send '$$', '$#' and opers@server notices. Older servers may +not allow servers to send to specific statuses on a channel. + OPERSPY encap only encap target: * @@ -399,11 +571,14 @@ Sends the server link password, TS version and SID. PING source: any -parameters: origin, destination server +parameters: origin, opt. destination server -Sends a PING to the destination server, which will reply with a PONG. +Sends a PING to the destination server, which will reply with a PONG. If the +destination server parameter is not present, the server receiving the message +must reply. -The origin field is not used in the server protocol. +The origin field is not used in the server protocol. It is sent as the name +(not UID/SID) of the source. Remote PINGs are used for end-of-burst detection, therefore all servers must implement them. @@ -429,7 +604,11 @@ The target can be: remotely) - a status character ('@'/'+') followed by a channel name, to send to users with that status or higher only. + capab: CHW propagation: all servers with -D users with appropriate status +- '=' followed by a channel name, to send to chanops only, for cmode +z. + capab: CHW and EOPMOD + propagation: all servers with -D chanops - 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 @@ -437,9 +616,14 @@ The target can be: propagation: one-to-one - a message to all users on server names matching a mask ('$$' followed by mask) propagation: broadcast + Only allowed to IRC operators. - a message to all users with hostnames matching a mask ('$#' followed by mask). Note that this is often implemented poorly. propagation: broadcast + Only allowed to IRC operators. + +In charybdis TS6, services may send to any channel and to statuses on any +channel. PRIVS charybdis TS6 @@ -598,6 +782,9 @@ 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. +An SJOIN is propagated with the new TS and modes of the channel. The statuses +are propagated if and only if they were accepted. + 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. @@ -670,9 +857,19 @@ broadcast, otherwise the changes will be stored, to be used when registration completes. TB +capab: TB source: server propagation: broadcast -parameters: +parameters: channel, topicTS, opt. topic setter, topic + +Propagates a channel topic as part of a burst. + +If the channel had no topic yet or the topicTS in the message is older than +the topicTS of the current topic on the channel and the topics differ, set +the topic with topicTS and topic setter, and propagate the message. Otherwise +ignore the message and do not propagate it. + +If the topic setter is not present, use a server name instead. TIME source: user @@ -703,10 +900,15 @@ multiple TMODE messages should be sent. TOPIC source: user propagation: broadcast +parameters: channel, topic Propagates a channel topic change. The server may verify that the source has ops in the channel. +The topicTS shall be set to the current time and the topic setter shall be +set indicating the source user. Note that this means that the topicTS of a +topic set with TOPIC is not necessarily consistent across the network. + TRACE source: user 1. @@ -862,7 +1064,6 @@ GET HELP ISON LIST -LOCOPS MAP MASKTRACE MODLIST