Internet Relay Chat Core Protocol version 3

IRC networks have been maintained over several decades for use with text-based conferencing. This document describes the core IRC client protocol and a framework for extending the protocol. IRC itself is a distributed teleconferencing and signalling system which is well-suited for running on many machines in a distributed manner. A typical setup involves many clients connecting to an IRC server which is connected to other servers in the network. The IRC server handles all of the necessary message routing and broadcast tasks.

In a typical IRC network, the servers are linked to each other in a topology which resembles an acyclic graph, however, some experimental networks have developed alternative topologies such as mesh-like topologies. Other IRC server software implements support for hot failover connections, however this is usually dependent on a specialized server-to-server protocol.

A client is anything connected to a server which is using the IRC client protocol. Each client is distinguished from other clients by having a unique nickname. In addition to the nickname, every server on the network maintains other information on the client, such as the real hostname of the client, the username that the client has selected and other information about the client such as the name of the user.

To facilitate maintenance of the network, IRC features a type of privileged user known as an "IRC operator". IRC operators are granted special privilege to perform maintenance-related tasks such as rerouting servers as needed to mitigate bad network routing. Operators also typically have the ability to enforce network policy by removing users from the network who do not comply with the network's policies.

A channel is a named group of zero or more clients which will all receive messages that are addressed to that channel. The channel is typically created when the first client joins it, and typically ceases to exist when the last client leaves it, however some IRC server software support keeping the channel open when no clients are presently using it in order to maintain the channel's settings. Channel names are strings which begin with a configured CHANPREFIX of length up to a configured CHANNELLEN length. Apart from the requirement that the channel name begin with a recognized CHANPREFIX, the only other restriction is that may not contain any spaces, control codes or commas (",") which is used as a list-item separator by the protocol.

A channel may have zero or more channel operators which provide for the maintenance and moderation of the channel. Depending on the server software in use, the channel operators may have special sigils as designated by the PREFIX configuration value. In a channel which is moderated, users which are allowed to bypass the moderation are given "voice" status. Users who have "voice" status MAY be given the "+" sigil to designate that they have the ability to bypass moderation.

A common feature of the present-day IRC networks are the usage of services servers. These servers provide specialized bots which provide an authentication layer on the network, allowing for ownership of nicknames and channels. Services usually provide facilities for account management and authentication, and map ownership of objects such as nicknames and channels to those accounts.

This protocol is a superset of , and is intended to be backwards compatible with where possible. It describes only the client side of the protocol unlike , as the server protocols have diverged over the years and are no longer compatible.

While does not specify any specific character set, servers implementing the IRCv3 core protocol SHOULD use UTF-8 as defined by . Clients SHOULD send UTF-8 unless explicitly configured not to do so. Because of IRC's scandinavian origin, some IRC servers specify that the characters {}| be mapped to be the lower-case equivilants of []\. This is specified using the CASEMAPPING configuration attribute, and an IRC network MUST use the same CASEMAPPING attribute in the entire network.

Servers and clients send messages between each other which may or may not generate a reply. If the message contains a valid command, as described in later sections, the client SHOULD expect a reply as specified, but it is not advised to wait for the reply. Client to server communications should be treated as asynchronous in nature. IRC messages consist of up to four parts: the tags section (optional), the prefix (optional), the command and it's parameters. All components of the message are separated using the UTF-8 space character (0x20). The presence of a tags section is designated with a single leading "@" symbol (0x40). The tags section consists of a set of key-value pairs delimited by an equals sign (0x3D). Each key-value pair is delimited by a semi-colon (";") (0x3B), which may be escaped using a backslash ("\") (0x5C). There MUST NOT be any whitespace between the "@" symbol and the key-value pairs. The presence of a prefix is designated with a single leading colon (":") (0x3A). There MUST NOT be any whitespace between the ":" symbol and the prefix itself. The prefix is used by servers to designate the origin of the message. If the prefix is missing, then clients SHOULD assume it came from the server the client is connected to. Clients SHOULD NOT use the prefix when they are sending a message to a server, but MAY send relevant tags. The command must be either a valid IRC command or a three-digit number represented in UTF-8 text. IRC messages are always lines of characters delimited with a CR-LF (Carriage Return - Line Feed) pair, and these messages SHOULD NOT exceed 512 characters in length unless otherwise negotiated with the server as a capability.

The protocol messages must be extracted from the contiguous stream of octets. The current solution is to designate two characters, CR and LF, as separators. Empty messages are silently ignored, which permits the use of the sequence CR-LF between messages without extra problems. The extracted message is parsed into the components <tags>, <prefix>, <command> and list of parameters (<params>). The Augmented BNF representation for this is:

Notes: SPACE explicitly is only the octet 0x20. Other forms of whitespace such as tabulation, are not considered part of SPACE. After extracting the parameter list, all parameters are equal, whether matched by "middle" or "trailing". "trailing" is just a syntactic trick to allow SPACE within parameter. The NUL character is not special in message framing but as it would cause extra complexities in normal C string handling it is not allowed within messages. The last parameter may be an empty string. Use of the extended prefix (['!' <user> ] ['@' <host> ]) must not be used in server to server communications and is only intended for server to client messages in order to provide clients with more useful information about who a message is from without the need for additional queries. Most protocol messages specify additional semantics and syntax for the extracted parameter strings dictated by their position in the list. For example, many server commands will assume that the first parameter after the command is the list of targets.

Most of the messages sent to the server generate a reply of some sort. The most common type of reply is a numeric reply, used for both errors and normal replies. The numeric reply MUST be sent as one message consisting of the sender prefix, the three-digit numeric and the target of the reply. A numeric reply MUST NOT originate from the client. In all other respects, a numeric reply SHOULD be treated as any other message, with the exception that the command keyword is made up of 3 numeric digits rather than a string of letters. A list of different replies is included in .

When wildcards are allowed in a string, it is referred as a "mask". For string matching purposes, the protocol allows the use of two special characters: "?" (0x3F) to match one and only one character, and "*" (0x2A) to match any number of any characters. These two characters can be escaped using the character "\" (0x5C). The Augmented BNF syntax for this is:

Immediately upon establishing a connection the client must attempt registration without waiting for any banner message from the server. Until registration is complete, only a small subset of commands may be accepted by the server. The recommended order of commands during registration is: STARTTLS PASS CAP NICK USER If the transport layer is not secured by TLS it is RECOMMENDED that the client attempt to opportunistically enable encryption by sending the STARTTLS (see ) command before sending any other messages. The PASS command (see ) is not required for the connection to be registered, but if included it MUST precede the latter of the NICK and USER commands. If the server supports capability negotiation the CAP command (see ) suspends the registration process and immediately starts the capability negotiation process. See for more information. The NICK and USER commands (see and , respectively) are used to identify the user's nickname, username and "real name". Unless the registration process is suspended by a STARTTLS or CAP negotiation, these commands will end the registration process. Upon successful completion of the registration process, the server MUST send the RPL_WELCOME (001) and RPL_ISUPPORT (005) numerics. The server SHOULD also send the MOTD (Message of the Day), if one exists, and MAY send other numerics. The RPL_ISUPPORT (005) numeric contains significant information for clients and is covered in more detail in .

IRC is an asynchronous protocol, which means that IRC clients may issue additional IRC commands while previous commands are being processed. Additionally, there is no guarantee of a specific kind of banner being issued upon connection. Some servers also do not complain about unknown commands during registration, which means that a client cannot reliably do passive implementation discovery at registration time. The solution to these problems is to extend the registration process with actual capability negotiation. If the server supports capability negotiation, the registration process will be suspended until negotiation is completed. If the server does not support capability negotiation, then registration will complete immediately, and the client will not use any IRCv3 capabilities. Capability negotiation is started by the client issuing a CAP LS command. Negotiation is then performed with the CAP REQ, CAP ACK, and CAP NAK commands, and ended with the CAP END command. See for more information. Once capability negotiation has ended, the registration process SHALL resume.

Syntax: "005 [nickname] [tokens...] :are provided by this server" Once client registration is complete, the server MUST send at least one RPL_ISUPPORT (005) numeric to the client. The server MAY send more than one RPL_ISUPPORT numeric and it is RECOMMENDED that consecutive RPL_ISUPPORT numerics are sent adjacent to each other. Each parameter of this numeric is a token and optional value in the form of TOKEN[=VALUE]. The tokens MUST be sent in upper-case but, unless otherwise specified, the value MUST be treated as case-sensitive.

Syntax: CLIENTVER=float A value which describes the specific version of the IRCv3 protocol being used on the server. This token is mainly meant to be informative for clients so that they can voluntarily disable some legacy support for performance reasons.

Syntax: CASEMAPPING=string The CASEMAPPING parameter allows the server to specify which method it uses to compare equality of case-insensitive strings. Possible values are: "ascii": The ASCII characters 0x61 through 0x7a are defined as the lower-case characters of ASCII characters 0x41 through 0x5a. No other equivilancy is defined. "rfc1459": The ASCII characters 0x61 through 0x7e are defined as the lower-case characters of ASCII characters 0x41 through 0x5e. No other equivilancy is defined. "strict-rfc1459": The ASCII characters 0x61 through 0x7d are defined as the lower-case characters of ASCII characters 0x41 through 0x5d. No other equivilancy is defined. "rfc3454": Strings are compared using the stringprep method described in . New implementations SHOULD default to using the "rfc3454" method in the event that this token is not available.

Syntax: PREFIX=[(modes)prefixes] The PREFIX parameter specifies a list of channel status flags (the "modes" section) that clients may have on channels, followed by a mapping to the equivalent channel status flags ("prefixes"), which are used in NAMES and WHO replies. There is a one to one mapping between each mode and prefix. The order of the modes is from that which gives most privileges on the channel, to that which gives the least. The default value for PREFIX is "PREFIX=(ov)@+", which corresponds to . It SHOULD NOT be specified if the server provides only these modes. If a server provides ANY additional status flags, it MUST also provide (ov)@+ (assuming they are applicable to the server). The PREFIX parameter may be advertised with a null value specifier; this indicates that no prefixes are supported by the IRC server. Note that PREFIX does NOT specify whether or not the server sends multiple prefix characters for a user in NAMES replies.

Syntax: CHANTYPES=chars The CHANTYPES parameter specifies the valid characters to begin a channel name. The default value for CHANTYPES is "CHANTYPES=#&", which corresponds to . It SHOULD NOT be specified if the server supports exactly these channel types. The CHANMODES parameter does not require a value; if none is given, the server does not support any channel types.

Syntax: CHANMODES=A,B,C,D The CHANMODES token specifies the modes that may be set on a channel. These modes are split into four categories, as follows: Type A: Modes that add or remove an address to or from a list. These modes always take a parameter when sent by the server to a client; when sent by a client, they may be specified without a parameter, which requests the server to display the current contents of the corresponding list on the channel to the client. Type B: Modes that change a setting on the channel. These modes always take a parameter. Type C: Modes that change a setting on the channel. These modes take a parameter only when set; the parameter is absent when the mode is removed both in the client's and server's MODE command. Type D: Modes that change a setting on the channel. These modes never take a parameter. If the server sends any additional types after these 4, the client MUST ignore them. The IRC server MUST NOT list modes in CHANMODES which are also present in the PREFIX parameter; however, for completeness, modes described in PREFIX may be treated as type B modes. If the server does not support any modes corresponding to a particular type, it should advertise that type as the empty string. The default value for the CHANMODES token is: "beI,k,l,imnpst".

Syntax: NETWORK=name The NETWORK parameter defines the name of the IRC network that the client is connected to. Note that this parameter is intended only for user display purposes; the client SHOULD NOT assume further capabilities or features of the IRC server based on the value of the NETWORK parameter. The default value of the NETWORK token is no value; that is, the network does not have a name specified.

Syntax: MODES=number This parameter specifies the maximum number of "variable" modes which may by set on a channel by a single MODE command from a client. A "variable" mode is defined as being type A, B and C modes as defined for CHANMODES, and channel modes specified in the PREFIX parameter. The value of MODES does not limit the number of modes in a MODE command which is sent from the server to the client; the client MUST NOT rely on this being the case. The default value for the MODES parameter is 3, which corresponds to . The MODES token does not require a value; if none is given, the number of modes which may be set in one command is not limited.

Syntax: CHANLIMIT=pfx:num[,pfx:num,...] This parameter specifies the maximum number of channels that a client may join. The value is a series of "pfx:num" pairs, where 'pfx' refers to one or more channel prefix characters (as specified in CHANTYPES), and 'num' indicates how many of these types of channel the client may join in total. If there is no limit to the number of certain channel type(s) a client may join, the limit should be specified as the empty string, for example "#:". Clients on either this server or a remote server may be on more than this number of channels; this parameter is only intended for information on how many channels the client it is advertised to may join. There is no default value for the CHANLIMIT token.

Syntax: MAXLIST=mode:num[,mode:num,...] This parameter specifies the maximum numbers of 'list modes' (type A modes in CHANMODES) that a client may set on a channel at one time. Note that this MUST only be interpreted as applying to new modes which are set by clients -- it should not be used to infer the maximum length of any mode lists returned by the server. The parameter is a series of mode-number pairs, each of which specifies one or more type A modes, along with the maximum size of the associated list for those modes. Modes which are specified in the same pair share the same maximum size. The MAXLIST token MUST have a value. There is no default value for the MAXLIST token.

Syntax: SAFELIST The SAFELIST parameter indicates that the client may request a "LIST" command from the server, without being disconnected due to the large amount of data generated by the command. The SAFELIST token MUST NOT be specified with a value. The default value for the SAFELIST token is none; that is, the client may not safely request a LIST command.

STATUSMSG=string The server supports a method of sending a NOTICE message to only those people on a channel with the specified status. This is done via a NOTICE command, with the channel prefixed by the desired status flag as the target. The server should deliver the message to all users on the specified channel with equal or higher status on the channel as the status flag indicates. The required value argument to STATUSMSG indicates which prefixes (from the PREFIX parameter) are valid status values for use in NOTICE commands. The server MUST NOT advertise a character in STATUSMSG which is also present in CHANTYPES. The STATUSMSG token MUST have a value if present. The default value of the STATUSMSG token is none; that is, the server does not support this form of messaging.

Syntax: CALLERID=char The CALLERID parameter indicates that the server supports so-called "caller id" mode, which rejects PRIVMSG messages from unauthorized users. The CALLERID value if set indicates the mode-letter to enable this feature. The CALLERID value MUST be set. There is no default value for the CALLERID token.

Syntax: NICKLEN=integer An integer value which describes the maximum allowed length of a nickname in octets.

Syntax: CHANNELLEN=integer An integer value which describes the maximum allowed length of a channel name in octets. The default value for CHANNELLEN is 200. The CHANNELLEN token does not require a value, if none is given, channel names are not limited in length.

Syntax: TOPICLEN=integer An integer value which describes the maximum allowed length of a channel's topic in octets. The TOPICLEN token does not require a value; if none is given, the length of channel topics is not limited.

Syntax: AWAYLEN=integer An integer value which describes the maximum allowed length of an away message in octets.