[BACK]Return to Protocol.txt CVS log [TXT][DIR] Up to [local] / ircnowd / doc

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