Annotation of ircnowd/doc/Protocol.txt, Revision 1.1.1.1
1.1 tomglok 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
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to Protocol.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [local] / ircnowd / doc