Update doc/Protocol.txt for IRCv3 WEBIRC extension
[ngircd-alex.git] / 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 - M: Changing client "metadata" (hostname, real name, ...) using the
85      METADATA command is supported.
86
87 - o: IRC operators are allowed to change channel- and channel-user-modes
88      even if they aren't channel-operator of the affected channel.
89
90 - S: The server supports the SERVICE command (on this link).
91
92 - X: Server supports XOP channel modes (owner, admin, halfop) and supports
93      these user prefixes in CHANINFO commands, for example.
94
95 - Z: Compressed server links are supported by the server.
96
97 Example for a complete <flags> string: "ngircd|0.7.5:CZ".
98
99 The optional parameter <options> is used to propagate server options as
100 defined in RFC 2813, section 4.1.1.
101
102
103 II.2 Enhanced Server Handshake
104
105 The "enhanced server handshake" is used when both servers support this IRC+
106 extension, which is indicated by the 'H' flag in the <serverflags> sent with
107 the PASS command, see section II.1.
108
109 It basically means, that after exchanging the PASS and SERVER commands the
110 server is not registered in the network (as usual), but that IRC numerics
111 are exchanged until the numeric 376 (ENDOFMOTD) is received. Afterwards the
112 peer is registered in the network as with the regular IRC protocol.
113
114 A server implementing the enhanced server handshake (and indicating this
115 using 'H' in the <serverflags>) MUST ignore all unknown numerics to it
116 silently.
117
118 In addition, such a server should at least send the numeric 005 (ISUPPORT)
119 to its peer, containing the following information. Syntax: <key>=<value>,
120 one token per IRC parameter. If the server has to send more than 12 token
121 it must send separate ISUPPORT numerics (this is a limitation of the IRC
122 protocol which allows at max 15 arguments per command).
123
124  - NICKLEN: Maximum nickname length. Default: 9.
125  - CASEMAPPING: Case mapping used for nick- and channel name comparing.
126    Default: "ascii", the chars [a-z] are lowercase of [A-Z].
127  - PREFIX: List of channel modes a person can get and the respective prefix
128    a channel or nickname will get in case the person has it. The order of the
129    modes goes from most powerful to least powerful. Default: "(ov)@+"
130  - CHANTYPES: Supported channel prefixes. Default: "#".
131  - CHANMODES: List of channel modes for 4 types, separated by comma (","):
132    Mode that adds or removes a nick or address to a list, mode that changes
133    a setting (both have always has a parameter), mode that changes a setting
134    and only has a parameter when set, and mode that changes a setting and
135    never has a parameter. For example "bI,k,l,imnPst".
136  - CHANLIMIT: Maximum number of channels allowed to join by channel prefix,
137    for example "#:10".
138
139 Please see <http://www.irc.org/tech_docs/005.html> for details.
140
141 The information exchanged using ISUPPORT can be used to detect configuration
142 incompatibilities (different maximum nickname length, for example) and
143 therefore to disconnect the peer prior to registering it in the network.
144
145
146 II.3 Exchange channel-modes, topics, and persistent channels
147
148      Command: CHANINFO
149   Parameters: <channel> +<modes> [[<key> <limit>] <topic>]
150      Used by: servers only
151
152 CHANINFO is used by servers to inform each other about a channel: its
153 modes, channel key, user limits and its topic. The parameter combination
154 <key> and <limit> is optional, as well as the <topic> parameter, so that
155 there are three possible forms of this command:
156
157   CHANINFO <channel> +<modes>
158   CHANINFO <channel> +<modes> <topic>
159   CHANINFO <channel> +<modes> <key> <limit> <topic>
160
161 If the channel already exists on the server receiving the CHANINFO command,
162 it only adopts the <modes> (or the <topic>) if there are no modes (or topic)
163 already set. It there are already values set the server ignores the
164 corresponding parameter.
165
166 If the channel doesn't exists at all it will be created.
167
168 The parameter <key> must be ignored if a channel has no key (the parameter
169 <modes> doesn't list the "k" channel mode). In this case <key> should
170 contain "*" because the parameter <key> is required by the CHANINFO syntax
171 and therefore can't be omitted. The parameter <limit> must be ignored when
172 a channel has no user limit (the parameter <modes> doesn't list the "l"
173 channel mode). In this case <limit> should be "0".
174
175
176 II.4 Update webchat/proxy client information
177
178      Command: WEBIRC
179   Parameters: <password> <username> <hostname> <ip-address> [<ignored>]
180      Used by: unregistered clients only
181
182 The WEBIRC command is used by some Web-to-IRC gateways to set the correct
183 user name and host name of users instead of their own. It must be the very
184 first command sent to the server, even before USER and NICK commands!
185
186 The <password> must be set in the server configuration file to prevent
187 unauthorized clients to fake their identity; it is an arbitrary string.
188
189 Optionally, a 5th parameter is accepted to comply with an IRCv3 extension,
190 see <https://github.com/ircv3/ircv3-ideas/issues/12>, but ignored.
191
192
193 II.5 Client character encoding conversion
194
195      Command: CHARCONV
196   Parameters: <client-charset>
197      Used by: registered clients
198      Replies: RPL_IP_CHARCONV, ERR_IP_CHARCONV
199
200 A client can set its character set encoding using the CHARCONV command:
201 after receiving such a command, the server translates all message data
202 received from the client using the set <client-charset> to the server
203 encoding (UTF-8), and all message data which is to be sent to the client
204 from the server encoding (UTF-8) to <client-charset>.
205
206 The list of supported client character sets is implementation dependent.
207
208 If a client sets its <client-charset> to the server encoding (UTF-8),
209 it disables all conversions; the connection behaves as if no CHARCONV
210 command has been sent at all in this session.
211
212
213 II.6 Update client "metadata"
214
215      Command: METADATA
216   Parameters: <target> <key> <value>
217      Used by: servers only
218
219 The METADATA command is used on server-links to update "metadata" information
220 of clients, like the hostname, the info text ("real name"), or the user name.
221
222 The server updates its client database according to the received <key> and
223 <value> parameters, and passes the METADATA command on to all the other
224 servers in the network that support this command (see section II.1 "Register
225 new server link", <serverflag> "M"), even if it doesn't support the given
226 <key> itself: unknown <key> names are ignored silently!
227
228 The following <key> names are defined:
229
230  - "accountname": the account name of a client (can't be empty)
231  - "certfp": the certificate fingerprint of a client (can't be empty)
232  - "cloakhost": the cloaked hostname of a client
233  - "host": the hostname of a client (can't be empty)
234  - "info": info text ("real name") of a client
235  - "user": the user name of a client (can't be empty)
236
237
238 III. Numerics used by IRC+ Protocol
239 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
240
241 The IRC+ protocol uses numerics in the range 800-899 which aren't used by
242 RFC 2812 and hopefully don't clash with other implementations ...
243
244 Numerics 800-849 are used for status and success messages, and numerics
245 850-899 are failure and error messages.
246
247
248 III.1 IRC+ status and success numerics
249
250 801 - RPL_IP_CHARCONV
251         %1 :Client encoding set"
252
253                 %1      client character set
254
255
256 III.2 IRC+ failure and error numerics
257
258 851 - ERR_IP_CHARCONV
259         :Can't initialize client encoding