doc/Protocol.txt

   1
   2                      ngIRCd - Next Generation IRC Server
   3                            http://ngircd.barton.de/
   4
   5                (c)2001-2019 Alexander Barton and Contributors.
   6                ngIRCd is free software and published under the
   7                    terms of the GNU General Public License.
   8
   9                               -- Protocol.txt --
  10
  11
  12 I. Compatibility
  13 ~~~~~~~~~~~~~~~~
  14
  15 The ngIRCd implements the Internet Relay Chat (IRC) protocol version 2.10
  16 as defined in RFC ("request for comment") 1459 and 2810-2813. These (and
  17 probably further relevant RFCs) are listed in doc/RFC.txt.
  18
  19 Unfortunately, even the "original" ircd doesn't follow these specifications
  20 in all details. But because the ngIRCd should be a fully compatible
  21 replacement for this server ("ircd") it tries to emulate these differences.
  22
  23 If you don't like this behavior please ./configure the ngIRCd using the
  24 "--enable-strict-rfc" command line option. But keep in mind: not all IRC
  25 clients are compatible with a server configured that way, some can't even
  26 connect at all! Therefore this option usually isn't desired for "normal
  27 server operation".
  28
  29 In addition, ngIRCd implements some "IRCv3" features. This includes:
  30  - IRCv3 Client Capability Negotiation
  31  - IRCv3.1 multi-prefix Extension
  32  - IRCv3.2 userhost-in-names Extension
  33 Please see the IRCv3 homepage for more information: <https://ircv3.net>.
  34
  35
  36 II. The IRC+ Protocol
  37 ~~~~~~~~~~~~~~~~~~~~~
  38
  39 Starting with version 0.5.0, the ngIRCd extends the original IRC protocol
  40 as defined in RFC 2810-2813. This enhanced protocol is named "IRC+". It is
  41 backwards compatible to the "plain" IRC protocol and will only be used by
  42 the ngIRCd if it detects that the peer supports it as well.
  43
  44 The "PASS" command is used to detect the protocol and peer versions see
  45 RFC 2813 (section 4.1.1) and below.
  46
  47
  48 II.1 Register new server link
  49
  50      Command: PASS
  51   Parameters: <password> <version> <flags> [<options>]
  52      Used by: servers only (with these parameters)
  53
  54 <password> is the password for this new server link as defined in the server
  55 configuration which is sent to the peer or received from it.
  56
  57 <version> consists of two parts and is at least 4, at most 14 characters
  58 long: the first four bytes contain the IRC protocol version number, whereas
  59 the first two bytes represent the major version, the last two bytes the
  60 minor version (the string "0210" indicates version 2.10, e.g.).
  61
  62 The following optional(!) 10 bytes contain an implementation-dependent
  63 version number. Servers supporting the IRC+ protocol as defined in this
  64 document provide the string "-IRC+" here.
  65
  66 Example for <version>: "0210-IRC+".
  67
  68 <flags> consists of two parts separated with the character "|" and is at
  69 most 100 bytes long. The first part contains the name of the implementation
  70 (ngIRCd sets this to "ngircd", the original ircd to "IRC", e.g.). The second
  71 part is implementation-dependent and should only be parsed if the peer
  72 supports the IRC+ protocol as well. In this case the following syntax is
  73 used: "<serverversion>[:<serverflags>]".
  74
  75 <serverversion> is an ASCII representation of the clear-text server version
  76 number, <serverflags> indicates the supported IRC+ protocol extensions (and
  77 may be empty!).
  78
  79 The following <serverflags> are defined at the moment:
  80
  81 - C: The server supports the CHANINFO command.
  82
  83 - L: INVITE- and BAN-lists should be synchronized between servers: if the
  84      peer understands this flag, it will send "MODE +I" and "MODE +b"
  85      commands after the server link has been established.
  86
  87 - H: The server supports the "enhanced server handshake", see section II.2
  88      for a detailed description.
  89
  90 - M: Changing client "metadata" (hostname, real name, ...) using the
  91      METADATA command is supported.
  92
  93 - o: IRC operators are allowed to change channel- and channel-user-modes
  94      even if they aren't channel-operator of the affected channel.
  95
  96 - S: The server supports the SERVICE command (on this link).
  97
  98 - X: Server supports XOP channel modes (owner, admin, halfop) and supports
  99      these user prefixes in CHANINFO commands, for example.
 100
 101 - Z: Compressed server links are supported by the server.
 102
 103 Example for a complete <flags> string: "ngircd|0.7.5:CZ".
 104
 105 The optional parameter <options> is used to propagate server options as
 106 defined in RFC 2813, section 4.1.1.
 107
 108
 109 II.2 Enhanced Server Handshake
 110
 111 The "enhanced server handshake" is used when both servers support this IRC+
 112 extension, which is indicated by the 'H' flag in the <serverflags> sent with
 113 the PASS command, see section II.1.
 114
 115 It basically means, that after exchanging the PASS and SERVER commands the
 116 server is not registered in the network (as usual), but that IRC numerics
 117 are exchanged until the numeric 376 (ENDOFMOTD) is received. Afterwards the
 118 peer is registered in the network as with the regular IRC protocol.
 119
 120 A server implementing the enhanced server handshake (and indicating this
 121 using 'H' in the <serverflags>) MUST ignore all unknown numerics to it
 122 silently.
 123
 124 In addition, such a server should at least send the numeric 005 (ISUPPORT)
 125 to its peer, containing the following information. Syntax: <key>=<value>,
 126 one token per IRC parameter. If the server has to send more than 12 token
 127 it must send separate ISUPPORT numerics (this is a limitation of the IRC
 128 protocol which allows at max 15 arguments per command).
 129
 130  - NICKLEN: Maximum nickname length. Default: 9.
 131  - CASEMAPPING: Case mapping used for nick- and channel name comparing.
 132    Default: "ascii", the chars [a-z] are lowercase of [A-Z].
 133  - PREFIX: List of channel modes a person can get and the respective prefix
 134    a channel or nickname will get in case the person has it. The order of the
 135    modes goes from most powerful to least powerful. Default: "(ov)@+"
 136  - CHANTYPES: Supported channel prefixes. Default: "#".
 137  - CHANMODES: List of channel modes for 4 types, separated by comma (","):
 138    Mode that adds or removes a nick or address to a list, mode that changes
 139    a setting (both have always has a parameter), mode that changes a setting
 140    and only has a parameter when set, and mode that changes a setting and
 141    never has a parameter. For example "bI,k,l,imnPst".
 142  - CHANLIMIT: Maximum number of channels allowed to join by channel prefix,
 143    for example "#:10".
 144
 145 Please see <http://www.irc.org/tech_docs/005.html> for details.
 146
 147 The information exchanged using ISUPPORT can be used to detect configuration
 148 incompatibilities (different maximum nickname length, for example) and
 149 therefore to disconnect the peer prior to registering it in the network.
 150
 151
 152 II.3 Exchange channel-modes, topics, and persistent channels
 153
 154      Command: CHANINFO
 155   Parameters: <channel> +<modes> [[<key> <limit>] <topic>]
 156      Used by: servers only
 157
 158 CHANINFO is used by servers to inform each other about a channel: its
 159 modes, channel key, user limits and its topic. The parameter combination
 160 <key> and <limit> is optional, as well as the <topic> parameter, so that
 161 there are three possible forms of this command:
 162
 163   CHANINFO <channel> +<modes>
 164   CHANINFO <channel> +<modes> <topic>
 165   CHANINFO <channel> +<modes> <key> <limit> <topic>
 166
 167 If the channel already exists on the server receiving the CHANINFO command,
 168 it only adopts the <modes> (or the <topic>) if there are no modes (or topic)
 169 already set. It there are already values set the server ignores the
 170 corresponding parameter.
 171
 172 If the channel doesn't exists at all it will be created.
 173
 174 The parameter <key> must be ignored if a channel has no key (the parameter
 175 <modes> doesn't list the "k" channel mode). In this case <key> should
 176 contain "*" because the parameter <key> is required by the CHANINFO syntax
 177 and therefore can't be omitted. The parameter <limit> must be ignored when
 178 a channel has no user limit (the parameter <modes> doesn't list the "l"
 179 channel mode). In this case <limit> should be "0".
 180
 181
 182 II.4 Update webchat/proxy client information
 183
 184      Command: WEBIRC
 185   Parameters: <password> <username> <hostname> <ip-address> [<ignored>]
 186      Used by: unregistered clients only
 187
 188 The WEBIRC command is used by some Web-to-IRC gateways to set the correct
 189 user name and host name of users instead of their own. It must be the very
 190 first command sent to the server, even before USER and NICK commands!
 191
 192 The <password> must be set in the server configuration file to prevent
 193 unauthorized clients to fake their identity; it is an arbitrary string.
 194
 195 Optionally, a 5th parameter is accepted to comply with an IRCv3 extension,
 196 see <https://github.com/ircv3/ircv3-ideas/issues/12>, but ignored.
 197
 198
 199 II.5 Client character encoding conversion
 200
 201      Command: CHARCONV
 202   Parameters: <client-charset>
 203      Used by: registered clients
 204      Replies: RPL_IP_CHARCONV, ERR_IP_CHARCONV
 205
 206 A client can set its character set encoding using the CHARCONV command:
 207 after receiving such a command, the server translates all message data
 208 received from the client using the set <client-charset> to the server
 209 encoding (UTF-8), and all message data which is to be sent to the client
 210 from the server encoding (UTF-8) to <client-charset>.
 211
 212 The list of supported client character sets is implementation dependent.
 213
 214 If a client sets its <client-charset> to the server encoding (UTF-8),
 215 it disables all conversions; the connection behaves as if no CHARCONV
 216 command has been sent at all in this session.
 217
 218
 219 II.6 Update client "metadata"
 220
 221      Command: METADATA
 222   Parameters: <target> <key> <value>
 223      Used by: servers only
 224
 225 The METADATA command is used on server-links to update "metadata" information
 226 of clients, like the hostname, the info text ("real name"), or the user name.
 227
 228 The server updates its client database according to the received <key> and
 229 <value> parameters, and passes the METADATA command on to all the other
 230 servers in the network that support this command (see section II.1 "Register
 231 new server link", <serverflag> "M"), even if it doesn't support the given
 232 <key> itself: unknown <key> names are ignored silently!
 233
 234 The following <key> names are defined:
 235
 236  - "accountname": the account name of a client (can't be empty)
 237  - "certfp": the certificate fingerprint of a client (can't be empty)
 238  - "cloakhost": the cloaked hostname of a client
 239  - "host": the hostname of a client (can't be empty)
 240  - "info": info text ("real name") of a client
 241  - "user": the user name of a client (can't be empty)
 242
 243
 244 III. Numerics used by IRC+ Protocol
 245 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 246
 247 The IRC+ protocol uses numerics in the range 800-899 which aren't used by
 248 RFC 2812 and hopefully don't clash with other implementations ...
 249
 250 Numerics 800-849 are used for status and success messages, and numerics
 251 850-899 are failure and error messages.
 252
 253
 254 III.1 IRC+ status and success numerics
 255
 256 801 - RPL_IP_CHARCONV
 257         %1 :Client encoding set"
 258
 259                 %1      client character set
 260
 261
 262 III.2 IRC+ failure and error numerics
 263
 264 851 - ERR_IP_CHARCONV
 265         :Can't initialize client encoding