doc/Protocol.txt

   1
   2                      ngIRCd - Next Generation IRC Server
   3                            http://ngircd.barton.de/
   4
   5                (c)2001-2012 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
  30 II. The IRC+ Protocol
  31 ~~~~~~~~~~~~~~~~~~~~~
  32
  33 Starting with version 0.5.0, the ngIRCd extends the original IRC protocol
  34 as defined in RFC 2810-2813. This enhanced protocol is named "IRC+". It is
  35 backwards compatible to the "plain" IRC protocol and will only be used by
  36 the ngIRCd if it detects that the peer supports it as well.
  37
  38 The "PASS" command is used to detect the protocol and peer versions see
  39 RFC 2813 (section 4.1.1) and below.
  40
  41
  42 II.1 Register new server link
  43
  44      Command: PASS
  45   Parameters: <password> <version> <flags> [<options>]
  46      Used by: servers only (with these parameters)
  47
  48 <password> is the password for this new server link as defined in the server
  49 configuration which is sent to the peer or received from it.
  50
  51 <version> consists of two parts and is at least 4, at most 14 characters
  52 long: the first four bytes contain the IRC protocol version number, whereas
  53 the first two bytes represent the major version, the last two bytes the
  54 minor version (the string "0210" indicates version 2.10, e.g.).
  55
  56 The following optional(!) 10 bytes contain an implementation-dependent
  57 version number. Servers supporting the IRC+ protocol as defined in this
  58 document provide the string "-IRC+" here.
  59
  60 Example for <version>: "0210-IRC+".
  61
  62 <flags> consists of two parts separated with the character "|" and is at
  63 most 100 bytes long. The first part contains the name of the implementation
  64 (ngIRCd sets this to "ngircd", the original ircd to "IRC", e.g.). The second
  65 part is implementation-dependent and should only be parsed if the peer
  66 supports the IRC+ protocol as well. In this case the following syntax is
  67 used: "<serverversion>[:<serverflags>]".
  68
  69 <serverversion> is an ASCII representation of the clear-text server version
  70 number, <serverflags> indicates the supported IRC+ protocol extensions (and
  71 may be empty!).
  72
  73 The following <serverflags> are defined at the moment:
  74
  75 - C: The server supports the CHANINFO command.
  76
  77 - L: INVITE- and BAN-lists should be synchronized between servers: if the
  78      peer understands this flag, it will send "MODE +I" and "MODE +b"
  79      commands after the server link has been established.
  80
  81 - H: The server supports the "enhanced server handshake", see section II.2
  82      for a detailed description.
  83
  84 - o: IRC operators are allowed to change channel- and channel-user-modes
  85      even if they aren't channel-operator of the affected channel.
  86
  87 - S: The server supports the SERVICE command (on this link).
  88
  89 - Z: Compressed server links are supported by the server.
  90
  91 Example for a complete <flags> string: "ngircd|0.7.5:CZ".
  92
  93 The optional parameter <options> is used to propagate server options as
  94 defined in RFC 2813, section 4.1.1.
  95
  96
  97 II.2 Enhanced Server Handshake
  98
  99 The "enhanced server handshake" is used when both servers support this IRC+
 100 extension, which is indicated by the 'H' flag in the <serverflags> sent with
 101 the PASS command, see section II.1.
 102
 103 It basically means, that after exchanging the PASS and SERVER commands the
 104 server is not registered in the network (as usual), but that IRC numerics
 105 are exchanged until the numeric 376 (ENDOFMOTD) is received. Afterwards the
 106 peer is registered in the network as with the regular IRC protocol.
 107
 108 A server implementing the enhanced server handshake (and indicating this
 109 using 'H' in the <serverflags>) MUST ignore all unknown numerics to it
 110 silently.
 111
 112 In addition, such a server should at least send the numeric 005 (ISUPPORT)
 113 to its peer, containing the following information. Syntax: <key>=<value>,
 114 one token per IRC parameter. If the server has to send more than 12 token
 115 it must send separate ISUPPORT numerics (this is a limitation of the IRC
 116 protocol which allows at max 15 arguments per command).
 117
 118  - NICKLEN: Maximum nickname length. Default: 9.
 119  - CASEMAPPING: Case mapping used for nick- and channel name comparing.
 120    Default: "ascii", the chars [a-z] are lowercase of [A-Z].
 121  - PREFIX: List of channel modes a person can get and the respective prefix
 122    a channel or nickname will get in case the person has it. The order of the
 123    modes goes from most powerful to least powerful. Default: "(ov)@+"
 124  - CHANTYPES: Supported channel prefixes. Default: "#".
 125  - CHANMODES: List of channel modes for 4 types, separated by comma (","):
 126    Mode that adds or removes a nick or address to a list, mode that changes
 127    a setting (both have always has a parameter), mode that changes a setting
 128    and only has a parameter when set, and mode that changes a setting and
 129    never has a parameter. For example "bI,k,l,imnPst".
 130  - CHANLIMIT: Maximum number of channels allowed to join by channel prefix,
 131    for example "#:10".
 132
 133 Please see <http://www.irc.org/tech_docs/005.html> for details.
 134
 135 The information exchanged using ISUPPORT can be used to detect configuration
 136 incompatibilities (different maximum nick name length, for example) and
 137 therefore to disconnect the peer prior to registering it in the network.
 138
 139
 140 II.3 Exchange channel-modes, topics, and persistent channels
 141
 142      Command: CHANINFO
 143   Parameters: <channel> +<modes> [[<key> <limit>] <topic>]
 144      Used by: servers only
 145
 146 CHANINFO is used by servers to inform each other about a channel: its
 147 modes, channel key, user limits and its topic. The parameter combination
 148 <key> and <limit> is optional, as well as the <topic> parameter, so that
 149 there are three possible forms of this command:
 150
 151   CHANINFO <channel> +<modes>
 152   CHANINFO <channel> +<modes> <topic>
 153   CHANINFO <channel> +<modes> <key> <limit> <topic>
 154
 155 If the channel already exists on the server receiving the CHANINFO command,
 156 it only adopts the <modes> (or the <topic>) if there are no modes (or topic)
 157 already set. It there are already values set the server ignores the
 158 corresponding parameter.
 159
 160 If the channel doesn't exists at all it will be created.
 161
 162 The parameter <key> must be ignored if a channel has no key (the parameter
 163 <modes> doesn't list the "k" channel mode). In this case <key> should
 164 contain "*" because the parameter <key> is required by the CHANINFO syntax
 165 and therefore can't be omitted. The parameter <limit> must be ignored when
 166 a channel has no user limit (the parameter <modes> doesn't list the "l"
 167 channel mode). In this case <limit> should be "0".
 168
 169
 170 II.4 Update webchat/proxy client information
 171
 172      Command: WEBIRC
 173   Parameters: <password> <username> <hostname> <ip-address>
 174      Used by: unregistered clients only
 175
 176 The WEBIRC command is used by some Web-to-IRC gateways to set the correct
 177 user name and host name of users instead of their own. It must be the very
 178 first command sent to the server, even before USER and NICK commands!
 179
 180 The <password> must be set in the server configuration file to prevent
 181 unauthorized clients to fake their identity; it is an arbitrary string.
 182
 183
 184 II.5 Client character encoding conversion
 185
 186      Command: CHARCONV
 187   Parameters: <client-charset>
 188      Used by: registered clients
 189      Replies: RPL_IP_CHARCONV_MSG, ERR_IP_CHARCONV_MSG
 190
 191
 192 III. Numerics used by IRC+ Protocol
 193 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 194
 195 The IRC+ protocol uses numerics in the range 800-899 which aren't used by
 196 RFC 2812 and hopefully don't clash with other implementations ...
 197
 198 Numerics 800-849 are used for status and success messages, and numerics
 199 850-899 are failure and error messages.
 200
 201
 202 III.1 IRC+ status and success numerics
 203
 204 800 - RPL_IP_CHARCONV_MSG
 205         %1 :Client encoding set"
 206
 207                 %1      client character set
 208
 209
 210 III.2 IRC+ failure and error numerics
 211
 212 850 - ERR_IP_CHARCONV_MSG
 213         :Can't initialize client encoding