IRCv3 Core May 2015
Pitcock, et al. Standards Track [Page]
Workgroup:
Network Working Group
Published:
Authors:
W. Pitcock, Ed.
mammon.io
J. Allnutt
Kiwi IRC
L. Maganti
FusionX

Internet Relay Chat Core Protocol version 3

Abstract

The IRC protocol has been developed by the greater IRC user and administrator community since the first version formalized in [RFC1459]. It has adapted over the years to be the primary collaboration tool for many groups because of it's simplicity and robustness.

The IRC Core Protocol version 3 updates [RFC1459] and [RFC2812] with a base protocol and framework for extensions which has been developed over the past decade, as well as standardizes current known best practices in the greater IRC community. The IRC Core Protocol version 3 framework mechanisms also provide some level of compatibility with legacy IRC clients.

▲

Table of Contents

1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

2. Introduction

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.

2.1. Servers

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.

2.2. Clients

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.

2.2.1. IRC Operators

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.

2.3. Channels

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.

2.3.1. Channel Statuses

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.

2.4. Services, Accounts and Authentication

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.

3. The IRC Client Protocol

3.1. Overview

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

3.2. Character Encoding

While [RFC1459] does not specify any specific character set, servers implementing the IRCv3 core protocol SHOULD use UTF-8 as defined by [RFC3629]. 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 equivalents of []\. This is specified using the CASEMAPPING configuration attribute, and an IRC network MUST use the same CASEMAPPING attribute in the entire network.

3.3. Messages

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 1024 octets in length (512 bytes for tags, 512 for the rest) unless otherwise indicated by the server (see Section 3.8.2.1.17). If the limit is exceeded, the line MAY be silently truncated.

3.3.1. Message Format in Augmented BNF

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:

message      =  [ "@" tags SPACE ] [ ":" prefix SPACE ] command [ params ] crlf
prefix       =  servername / ( nickname [ [ "!" user ] "@" host ] )
command      =  1*letter / 3digit
params       =  *14( SPACE middle ) [ SPACE ":" trailing ]
             =/ 14( SPACE middle ) [ SPACE [ ":" ] trailing ]

nospcrlfcl   =  %x01-09 / %x0B-0C / %x0E-1F / %x21-39 / %x3B-FF
                    ; any octet except NUL, CR, LF, " " and ":"
middle       =  nospcrlfcl *( ":" / nospcrlfcl )
trailing     =  *( ":" / " " / nospcrlfcl )

tags         =  tag [';' tag]*
tag          =  key ['=' value]
nospcrlfscl  =  %x01-09 / %x0B-0C / %x0E-1F / %x21-39 / %x3C-FF
key          =  [ vendor '/' ] *( nospcrflscl )
value        =  nospcrflscl *( nospcrflscl )

SPACE        =  %x20        ; space character
crlf         =  %x0D %x0A   ; "carriage return" "linefeed"

Notes:

  1. SPACE explicitly is only the octet 0x20. Other forms of whitespace, such as tabs, are not considered part of SPACE.

  2. 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.

  3. 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.

  4. The trailing parameter may be an empty string.

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.

3.4. Numeric replies

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 Section 3.8.

3.5. Wildcard expressions

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:

    mask       =  *( nowild / noesc wildone / noesc wildmany )
    wildone    =  %x3F
    wildmany   =  %x2A
    nowild     =  %x01-29 / %x2B-3E / %x40-FF
                    ; any octet except NUL, "*", "?"
    noesc      =  %x01-5B / %x5D-FF
                    ; any octet except NUL and "\"
    matchone   =  %x01-FF
                    ; matches wildone
    matchmany  =  *matchone
                    ; matches wildmany

3.6. Connection registration

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:

  1. STARTTLS

  2. PASS

  3. CAP

  4. NICK

  5. 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 Section 3.7.5) command before sending any other messages.

The PASS command (see Section 3.7.4) 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 Section 3.7.1) suspends the registration process and immediately starts the capability negotiation process. See Section 3.6.1 for more information.

The NICK and USER commands (see Section 3.7.2 and Section 3.7.3, respectively) are used to identify the user's nickname, username and "real name". Once both commands have been submitted, the registration process will end, unless it is still suspended by a STARTTLS or CAP negotiation.

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 Section 3.8.2.

3.6.1. Capability negotiation

IRC is an asynchronous protocol, which means that IRC clients may issue additional IRC commands while previous commands are being processed. 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 Section 3.7.1 for more information.

Once capability negotiation has ended, the registration process SHALL resume.

3.7. Commands

3.7.2. NICK

Syntax: "NICK <new nickname>"

The NICK message serves a dual purpose: it can be used to give the user a nickname or it can be used by an existing user to change their nickname.

Numeric Replies:

3.7.3. USER

Syntax: "USER <username> <ignored> <ignored> <realname>"

The USER message is used at registration time to inform the server of the username and realname of the user.

The realname parameter may contain a space and if so MUST be preceeded by the colon (:) delimiter.

NOTE: parameters 2 and 3 are ignored and are simply included for backward compatibility with [RFC1459]

Numeric Replies:

3.7.4. PASS

Syntax: "PASS <password>"

The PASS message is used at registration time to provide a password to fully open a connection with the server. It SHOULD NOT be used to authenticate the user and is instead intended to be a way of limiting access to the server to only those with access to the password.

The PASS command can be sent multiple times but only the last attempt is utilized and the command SHOULD NOT be used after registration.

Numeric Replies:

3.8. Replies

3.8.1. RPL_WELCOME (001)

Syntax: "001 <nickname> :Welcome to the <network name> Internet Relay Chat Network <nick>!<username>@<hostname>"

Once client registration is complete, the server MUST send the RPL_WELCOME (001) numeric to the client. The numeric SHOULD be sent before any other numerics.

The numeric is only intended to acknowledge that the registration is finished, but it is RECOMMENDED that the descriptive text adhere to the specified format.

3.8.2. RPL_ISUPPORT (005)

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.

3.8.2.1. List of standard RPL_ISUPPORT tokens
3.8.2.1.1. CASEMAPPING

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 equivalency is defined.

  • "rfc1459": The ASCII characters 0x61 through 0x7e are defined as the lower-case characters of ASCII characters 0x41 through 0x5e. No other equivalency 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 equivalency is defined.

  • "rfc3454": Strings are compared using the stringprep method described in [RFC3454].

New implementations SHOULD default to using the "rfc3454" method in the event that this token is not available.

3.8.2.1.2. PREFIX

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 [RFC1459]. 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.

3.8.2.1.3. CHANTYPES

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 [RFC1459]. 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.

3.8.2.1.4. CHANMODES

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".

3.8.2.1.5. NETWORK

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.

3.8.2.1.6. MODES

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 [RFC1459].

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.

3.8.2.1.7. CHANLIMIT

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.

3.8.2.1.8. MAXLIST

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.

3.8.2.1.9. SAFELIST

Syntax: SAFELIST

The SAFELIST parameter indicates that the client may request a "LIST" command from the server, without risking a disconnection 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.

3.8.2.1.10. STATUSMSG

Syntax: STATUSMSG=string

The STATUSMSG token indicates that the server supports 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 (e.g. @#channel).

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.

3.8.2.1.11. CALLERID

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.

3.8.2.1.12. NICKLEN

Syntax: NICKLEN=integer

An integer value which describes the maximum allowed length of a nickname in octets. The default value is 9.

3.8.2.1.13. CHANNELLEN

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.

3.8.2.1.14. TOPICLEN

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. If the token is not specified at all, the default value is 390.

3.8.2.1.15. AWAYLEN

Syntax: AWAYLEN=integer

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

The AWAYLEN token does not require a value; if none is given, the length of away messages is not limited.

3.8.2.1.16. USERLEN

Syntax: USERLEN=integer

An integer value which describes the maximum allowed length of an username in octets.

The USERLEN token does not require a value; if none is given, the length of usernames is not limited.

3.8.2.1.17. LINELEN

Syntax: LINELEN=integer

An integer value which describes the maximum allowed length of a single IRC message (line) in octets.

The LINELEN token defaults to a value of 512 for compatibility with legacy IRC implementations. There is no specified upper bound for LINELEN.

3.8.3. RPL_TOPICWHOTIME (333)

Syntax: "333 <nickname> <channel> <topic-setter-nick>!<username>@<hostname> <timestamp>"

After a channel is joined, and RPL_TOPIC (332) is sent, the server SHOULD send the RPL_TOPICWHOTIME (333) numeric to the client.

The numeric provides information about who set the channel topic and when. <timestamp> is an epoch time in seconds

3.9. Errors

3.9.1. ERR_ERRONEOUSNICKNAME (432)

Syntax: "432 <nickname> :Erroneous nickname"

Returned when a NICK command is sent with a nickname argument which does not comply with the format of a nickname set out in Section 3.3.1

3.9.2. ERR_NICKNAMEINUSE (433)

Syntax: "433 <nickname> :Nickname is already in use"

Returned when a NICK command is sent with a nickname argument which currently exists (i.e. is currently the nickname of another user)

3.9.3. ERR_NICKCOLLISION (436)

Syntax: "433 <nickname> :Nickname collision"

Returned when the server detects a nickname collision (e.g. when a heal of a netsplit occurs and both sides have a different user with the same nickname). This error may be followed by a possible termination of the connection through a KILL command or a forcible changing of nick through a NICK command or the use of some other server specific system.

3.9.4. ERR_NEEDMOREPARAMS (461)

Syntax: "433 <command> :Not enough parameters"

Returned when a command was sent by the client with not enough parameters.

3.9.5. ERR_NEEDMOREPARAMS (462)

Syntax: "462 <command> :You may not reregister"

Returned when the client tries to send a command which may be only used at registration time (e.g. PASS, USER) after registration has completed.

4. Normative References

[RFC1459]
Oikarinen, J. and D. Reed, "Internet Relay Chat Protocol", RFC 1459, DOI 10.17487/RFC1459, , <https://www.rfc-editor.org/info/rfc1459>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC2812]
Kalt, C., "Internet Relay Chat: Client Protocol", RFC 2812, DOI 10.17487/RFC2812, , <https://www.rfc-editor.org/info/rfc2812>.
[RFC3454]
Hoffman, P. and M. Blanchet, "Preparation of Internationalized Strings ("stringprep")", RFC 3454, DOI 10.17487/RFC3454, , <https://www.rfc-editor.org/info/rfc3454>.
[RFC3629]
Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, , <https://www.rfc-editor.org/info/rfc3629>.

Authors' Addresses

William Pitcock (editor)
mammon.io
URI: http://kaniini.dereferenced.org/
Jack Allnutt
Kiwi IRC
URI: http://allnutt.eu/
Lalit Maganti
FusionX
URI: https://github.com/tilal6991/