Network Working Group A. Church Request For Comments: nnnn October, 1999 Obsoletes: 1459 Category: Experimental The Internet Relay Chat Protocol, Version 3 Status of this Memo This memo defines an Experimental Protocol for the Internet community. This memo does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited. Abstract Internet Relay Chat (IRC) is a client/server protocol allowing Internet users to engage in realtime "conversation". It has existed for a number of years, and the use of IRC has grown rapidly during that time. IRC has classically been a purely text-based protocol allowing for simple text-based interaction, as described in RFC 1459 [1]; however, current usage and trends demand a more efficient method for allowing IRC servers to communicate with each other than defined by the original protocol, as well as more stability than that protocol allows. In addition, as bandwidth availability increases, IRC should be extensible enough to allow other forms of communication, such as audio and/or video. Finally, the wide range of incompatible changes made to the protocol suggest that a new, extensible standard be defined to alleviate these incompatibilities. This protocol was given the name "version 3" due to the reference RFC1459 implementation being known as "irc2". Table of Contents 0. Preface 0.1 Acknowledgements 0.2 Terminology 1. About IRC 1.1 Servers 1.2 Clients 1.2.1 IRC operators 1.3 Requirements for clients and servers 1.4 Channels 1.4.1 Channel operators 1.5 Unicode and names 1.6 Communication 1.6.1 The shortest-path algorithm 1.6.2 One-to-one messages 1.6.2.1 Inter-network messages 1.6.3 One-to-many messages 2. The IRC specification 2.1 Strings 2.2 Messages 2.2.1 Client messages (commands) 2.2.2 Server messages 2.2.3 Replies 2.3 Summary of message flag bits 2.4 Time values 3. Message details 3.1 Connection registration and cancellation 3.1.1 Password message 3.1.2 User message 3.1.2.1 A note on the Ident Protocol 3.1.3 Server message 3.1.4 Remote server message 3.1.5 Network message 3.1.6 Quit message 3.1.7 Server quit message 3.2 Message sending 3.2.1 Public messages 3.2.2 Private messages 3.2.3 Notices 3.2.4 Server notices 3.2.5 Operator messages 3.2.6 Global messages 3.3 Channel operations 3.3.1 Join message 3.3.2 Part message 3.3.3 Channel mode message 3.3.4 Topic message 3.3.5 Channel operator message 3.3.6 Channel voice message 3.3.7 Kick message 3.3.8 Channel ban message 3.3.9 Invite message 3.4 User control messages 3.4.1 Nick message 3.4.2 Away message 3.4.3 Silence message 3.4.4 User mode message 3.4.5 Operator message 3.4.6 Kill message 3.4.7 Server ban message 3.4.8 Network ban message 3.5 Server control messages 3.5.1 Connect message 3.5.2 Disconnect message 3.5.3 Rehash message 3.5.4 Restart message 3.5.5 Die message 3.6 Query messages 3.6.1 Who message 3.6.2 Names message 3.6.3 List message 3.6.4 Whois message 3.6.5 Whowas message 3.6.6 Ison message 3.6.7 Users message 3.6.8 Message of the Day message 3.6.9 Administrative information message 3.6.10 Server information message 3.6.11 Server version message 3.6.12 Statistics message 3.6.13 Links message 3.6.14 Trace message 3.6.15 Time message 3.7 Miscellaneous messages 3.7.1 Ping message 3.7.2 Pong message 3.8 Reserved message codes 3.9 Erroneous messages 3.10 Use of experimental message codes 4. Replies 4.1 Command responses 4.2 Error messages 4.2.1 Syntactical errors 4.2.2 Functional errors 4.3 Reserved reply codes 5. Problems and limitations 5.1 Scalability 5.2 Name collisions 5.2.1 Nickname collisions 5.2.2 Server name or ID collisions 5.2.3 Channel collisions 5.3 Timekeeping 5.4 Connection desynchronization 5.5 Cyclic networks 6. Security considerations 6.1 IP spoofing 6.2 DNS spoofing 6.3 Network sniffing 6.4 Time overflow 7. Author's address 8. References and notes 9. Copyright notice Appendix A: Dijkstra's algorithm Appendix B: Alphabetical index of message and reply elements Appendix C: List of requirements and recommendations C.1 Basic client and server requirements C.2 Names and identifiers C.3 Privilege levels C.4 Unicode support C.5 Message generation, transmission and receipt C.6 Messages C.7 Replies C.8 Collisions C.9 Other requirements Appendix D: Conversion table for the RFC 1459 protocol 0. PREFACE 0.1 Acknowledgements The author wishes to acknowledge the assistance of Ian Justman and Andrew Kempe for offering suggestions on this document and the protocol defined therein. The author also wishes to acknowledge an IRC protocol proposal by Steven Arnold [2] for providing the idea for inter-network communication. 0.2 Terminology This document describes a number of requirements for the Internet Relay Chat protocol. It also explains the reasoning behind those requirements; the author realizes that there may be reasons for or against including particular elements of the specification in a particular implementation, and the explanations will help in making those decisions. At the same time, implementors cannot have complete freedom in choosing what parts of the protocol to implement, or there would be little to no compatibility between different versions -- as has already been demonstrated by the wide variety of IRC server implementations currently available, many of which cannot communicate with each other due to changes introduced into the protocol by each particular implementation [3]; the author is personally aware of no less than six variant protocols, none of which are compatible with each other or with the original RFC 1459 [1] specification. Hence, this document uses a number of terms to indicate which elements of the protocol are required and which are merely suggested. Whenever these words are used in this sense, they are capitalized. For a more complete description of the use of these terms, see RFC 2119 [4]. MUST indicates that the capability or functionality described is an absolute requirement. An implementation that does not include this capability does not conform to the protocol. SHOULD indicates that, while the capability or functionality described is strongly recommended for inclusion in any implementation, it is not required for compliance with the protocol. However, any implementation designer should carefully weigh the potential benefits and liabilities before deciding not to include this capability or functionality. MAY indicates that the capability or functionality described is truly optional. One implementation may include it, and another may not, for any reason whatsoever. Both are compliant with the protocol. SHOULD NOT is the opposite of SHOULD; implementation designers are discouraged from including the capability or functionality described in an implementation of the protocol, though there may exist valid reasons to do so. MUST NOT is the opposite of MUST; implementations are prohibited from including the capability or functionality described. Additionally, the terms "old protocol" and "original protocol" refer to the IRC protocol described in RFC 1459 [1]. The word "iff" (as opposed to "if") has its standard logical meaning of "if and only if." 1. ABOUT IRC The Internet Relay Chat (IRC) protocol has been designed over a number of years as a text-based realtime communication protocol. This document describes a new protocol intended to replace the original IRC protocol; this protocol is designed to achieve better performance and more flexibility than the original protocol. The author recognizes the well-tested principle that extending an old protocol is better than designing a new one; however, with the many IRC implementations in existence that are not compliant--or even compatible--with the original protocol, and with the inherent limitations of the text-based communication model of that protocol, it is the author's belief that creating a new protocol, using many of the concepts from the old one but providing a different, more flexible structure, would be more beneficial than simply revising the old protocol. While this document stands on its own, it is assumed that many of the readers of this document, at least in its early days, will be familiar with the old protocol, and thus notes are made occasionally on similarities and differences between the old protocol and the protocol defined by this document. IRC uses the client-server model; it is best suited to running in a distributed environment, with individual systems acting as servers for the users' clients and for other servers. An IRC client may be any program capable of sending data through a data network to an IRC server, though due to the binary nature of this protocol, it is assumed that users will use some sort of client program to mediate between the raw protocol data and more easily human-viewable information, such as text, audio, or video. 1.1 Servers The backbone of the IRC network is the server. Servers act as central points for IRC clients to connect to, and also for other servers to connect to, forming an IRC network. If each server on the network is a vertex of a graph, then the entire network forms a graph which is fully connected; i.e. there is at least one path from any server to any other server. Note that there may be multiple paths between any two given servers, but there may be no more than one direct connection between any two servers. See Figure 1 for an example IRC network. 14 15 1 9 / \ / \______ | / \ / \|/ 3----2-----------8-----10 \ ___/| \ ,---' _| 4-----5-' /| \ / | \ 6 | _,--11----12 7---' \ \ 13 [Figure 1: Sample IRC network] Servers have the responsibility of maintaining a complete image of the IRC environment -- the sum of the information about all clients and servers connected to the IRC network -- and ensuring that it remains consistent and obeys certain rules. Under this protocol, each server is identified by a unique 16-bit integer sent in the server registration message (see section 3.1.3). This identifier is included in all server-to-server messages. Each server is also assigned a name; this name MUST be no more than 63 characters in length, and MUST NOT contain the character with value zero (ASCII NUL). All other characters are legal; however, for compatibility with older clients, servers SHOULD NOT use names with the space (" ", ASCII 0x20) and comma (",", ASCII 0x2C) characters, as those are delimiters under the old protocol, or names that begin with "#" or "&", as those are used at the beginning of channel names under the old protocol, which has no way to distinguish server names and nicknames from channel names except by the first character. This name is used by clients to refer to a particular server, but is not used in server-server communication. Note that this identification scheme only allows up to 65,536 servers to exist in a single network. While the author believes this to be more than sufficient for the foreseeable future, the server ID value 65,535 (hexadecimal FFFF) is reserved for future use should the need arise. Servers MUST NOT use this value when registering, and a which receives a server registration message with this value MUST reject it. 1.2 Clients A client (also known as a user) is essentially anything connected to the IRC network that is not a server. Each client, when it registers its connection (see section 3.1.2), is assigned a 16-bit non-zero identifier which is unique among all clients connected to the same server (zero is used to represent the server itself). Thus, any client or server on the IRC network can be uniquely identified by a combination of the client's ID (zero in the case of a server) and the ID of the server that the client is connected to (the server's own ID in the case of a server). This client ID is used only by servers, and is not seen by clients. Note that this identification scheme only allows for 65,535 clients to be connected to a single server. While the author believes this to be sufficient for the near future, the client ID 65,535 (hexadecimal FFFF) is reserved for future use should the need arise. Servers MUST NOT assign this ID to any client. (This reduces the maximum number of clients per server to 65,534.) Under this scheme, the maximum number of clients on a network is 65,535 (servers) * 65,534 (clients per server) = 4,294,780,690. As this number is currently greater than 2/3 of the world's population, it is considered sufficient for the foreseeable future. Furthermore, should it be necessary to split clients among two or more networks, those clients can still communicate with each other via inter-network messages (see section 1.6.2.1). When a client registers its connection, it gives a "nickname" by which it will be known to all other clients. This allows a particular client to be known by a single identifier regardless of the server to which the client connects or the client ID assigned by that server. The nickname MUST be no longer than 31 characters, and has the same restrictions (except for length) as server names; again, for compatibility with older clients, newer clients SHOULD NOT allow users to select nicknames with the space (" ", ASCII 0x20) and comma (",", ASCII 0x2C) characters, as those are delimiters under the old protocol, or nicknames that begin with "#" or "&", as those are used at the beginning of channel names under the old protocol, which has no way to distinguish nicknames from channel names except by the first character. Case is not relevant. (Compatibility note: The old protocol required three pairs of non-alphabetic characters to be pairwise equivalent: "[" and "{"; "]" and "}"; and "\" and "|". These six characters are all distinct in this protocol.) Each client also has an address in the form "user@host" associated with it, where "user" is the username of the client (e.g. a Unix login name) and "host" is the fully-qualified domain name or IP address of the host from which the client connected. The hostname is determined by the server; the username is sent by the client, and obeys the same restrictions as the nickname. 1.2.1 IRC operators In an ideal world, IRC would be a completely automated system; users would be able to connect, converse, and disconnect with no troubles or interruptions. However, the real world is far from ideal, and human intervention is often required to keep the IRC network in optimal condition. These users are known as "IRC operators", and have the ability to make changes which affect the IRC environment, including disconnecting and reconnecting servers (see sections 3.5.1 and 3.5.2) and forcibly removing troublesome users from the IRC network (see sections 3.4.6 and 3.4.7). Obviously, IRC operators should be chosen with care, as a malevolent IRC operator could potentially disrupt the entire IRC network. Note that, while this document only specifies two levels of client privilege -- normal client and IRC operator -- a particular server MAY define additional privilege levels. In addition, servers MAY define additional authentication methods for accessing any privilege level (see section 3.8 on command codes which are designated for experimental or local use). If a network successfully implements such a scheme and finds it useful, the author would appreciate a well-written description of that scheme for possible inclusion in a revision of this protocol. However, regardless of how many or what privilege levels exist on a server, normal (unprivileged) clients MUST NOT be able to execute any functions which require IRC operator privileges in this protocol description. 1.3 Requirements for clients and servers Both clients and servers MUST be capable of sending and receiving arbitrary data octets. Servers MUST use the current protocol (the protocol defined in this document) for transmitting data to other servers compatible with this protocol; servers SHOULD recognize both the old and current protocols, and MUST communicate with a client or server using the same protocol the client or server registered with. 1.4 Channels A channel is a named group of one or more clients which will all receive messages addressed to that channel. A channel is implicitly created when the first client joins it, and it ceases to exist when the last client leaves it. A channel name is a string which consists of up to 63 characters. Specifically, channel names MUST obey the same restrictions as server names: no NUL, space and comma are discouraged, names are case-insensitive. There are two distinct types of channels defined by this protocol: distributed channels and local channels. Distributed channels are are broadcast to all servers in the IRC network, and must therefore have names that are unique among all distributed channels on all servers. Local channels are not broadcast to any servers; only clients on the same server will be in the same local channel. Two or more servers may have local channels with exactly the same names, but clients in one server's channel will know nothing of clients in another server's channel, as the two channels are completely separate. Channels are distributed by default; they may be made local by using the channel mode command (see section 3.3.3). Compatibility note: The old protocol required channel names to begin with either "#" or "&"; the former was for distributed channels, the latter for local channels. When communicating with a client or server using the old protocol, the server MUST prepend either "#" or "&" to the name of a distributed or local channel, respectively, whenever the name appears in a message. Note that this extends the maximum length of a channel name string with respect to old-protocol clients to 64 characters (not 63); implementors should take care to avoid buffer overflow problems. In order to become part of a channel, a client sends a "join" command (see section 3.3.1). If the channel does not already exist, it is created, and the client becomes a channel operator. If the channel does exist, the client's request to join the channel may be denied depending on the channel status; the channel may be invite-only, for example, or the client may be banned from the channel. See section 3.3.3 for a full description of channel modes. 1.4.1 Channel operators As IRC operators are to the IRC network, so are channel operators to their channels. A channel operator (also called "chanop" or simply "op") has full control of his or her channel, including the ability to set channel modes, invite users into the channel, and forcibly remove ("kick") users from the channel. There may be multiple channel operators for a single channel. As with network-level privileges, individual servers or implementations MAY define additional privilege levels or authentication schemes, but MUST obey the restrictions set forth in this document as to what unprivileged users are permitted and not permitted to do. Furthermore, individual servers or implementations MAY allow users with IRC operator privileges or other locally-defined privileges to perform channel actions which are normally restricted to channel operators and/or clients in the channel, even when the privileged user is not a channel operator or is not in the channel. 1.5 Unicode and names As of the writing of this document, the most common system for encoding characters in digital form is to use an eight-bit encoding system such as ASCII or ISO 8859 (although countries such as Japan with larger character sets use 16-bit systems). However, a new, 16-bit standard known as Unicode is emerging, and may replace current 8-bit standards in the future. Obviously, this protocol should be able to support Unicode as well as traditional standards. A server or client implementation which is capable of receiving and processing Unicode strings MUST set the "Unicode support" flag (see section 2.2) in all messages, and MUST set the "Unicode" flag in any messages sent which contain Unicode-encoded strings. Servers and clients MUST NOT include both Unicode and non-Unicode strings in the same message. A server with Unicode support which has the ability to generate and send text messages (such as descriptive error messages; see section 2.2.3) SHOULD include support for sending the same text messages in the preferred non-Unicode encoding for the language used (when such an encoding exists). Note that a client implementation which is capable of understanding Unicode need not necessarily generate strings in Unicode. Implementors of clients or servers with Unicode support should take note of the distinction between "characters" and "octets". For example, the maximum length of a nickname (as given in section 1.2.1) is 31 characters; this means that a 62-octet (31-character) Unicode string is also legal. Any implementation that uses Unicode MUST translate all characters referred to in this document into their Unicode equivalents rather than using the hexadecimal octet values given (single octets make no sense as characters in Unicode anyway). 1.6 Communication Messages in the IRC protocol take one of two general forms: one-to-one (one sender, one recipient) or one-to-many (one sender, multiple recipients). All messages travel via the shortest path from the sender to each recipient. 1.6.1 The shortest-path algorithm For any message from or to a directly connected client, the shortest path is obvious; however, in order for a message between servers or from a server to a remote client) to traverse the IRC network, the servers need to know what path to send it along. Servers may use any method they choose to calculate the shortest path to other servers; a description of Dijkstra's algorithm, an algorithm for finding the shortest path from one node in a graph to all others, is presented in Appendix A. Typically, all links will be assigned equal weight. In some circumstances it may be preferable to assign a larger weight to a server on a slow link, or to assign weights based on round-trip packet times; however, every server on a network MUST use the same method for computing weights, so that all servers compute the same shortest paths. (Otherwise, some messages may be sent in cycles and ultimately discarded without reaching their destinations.) When sending a message to another server, the sender MUST append its server ID to the path field of the message (this is described in detail in section 2.2); a server MUST NOT send a message to a server which is listed in the message's path field, and a server receiving a message with its own ID in the path field MUST discard the message. Note that only the first server on the path is relevant, as that server will determine where next to pass the message (to another server or to a client on that server). When there are two or more equivalent paths, any of them may be chosen. Servers MAY precalculate the first server on the shortest path to every other server on the IRC network; however, servers that do this MUST update their tables whenever a server is added to or removed from the network. The following examples are based on the sample network in Figure 1, above. All links are assumed to have the same weight. Example: Message from server 2 to server 8. Servers 2 and 8 are directly connected, so the shortest path is simply 2->8 (server 2 sends the message to server 8). Example: Message from server 3 to server 8. There are several distinct paths from server 3 to server 8. However, the shortest one is 3->2->8. Note that server 2, when it receives the message from server 3, considers the message to now be one from itself to server 8 for the purpose of routing, and sends the message to server 8 as described in the previous example. Example: Message from server 4 to server 11. Here, there are two shortest routes: 4->5->11 and 4->7->11. Server 4 may send the message either to server 5 or to server 7; whichever it chooses will then forward the message to server 11. 1.6.2 One-to-one messages There are three types of one-to-one messages: client-to-server, server-to-client, and server-to-server. Messages travel from the sending server (or the sending client's server) to the destination server (or the destination client's server) using the shortest-path algorithm described in section 1.5.1. - Client-to-server: All mesages from clients. While some messages from clients will actually have other clients as their destinations, such messages are only ever sent to the server to which the client is connected. - Server-to-client, server-to-server: Ping messages to determine whether an inactive link is still connected. 1.6.2.1 Inter-network messages A special subset of one-to-one messages are messages sent between a server on one IRC network and a server on another IRC network. This type of communication alleviates the scalability problem with this protocol (see section 5.1) by allowing clients from different networks to communicate with each other. This inter-network communication is accomplished through "border servers" which connect to other networks and identify themselves as such. In Figure 2, below, servers A4 and B1 are border servers for networks A and B, respectively. Network C is currently isolated from the other networks. Network A Network B Network C A1----A3---A5 B2---B3 C1----C3 | / | / | | / | / | | / | / | A2----A4------------B1 C2----C4 [Figure 2: Three IRC Networks with Border Servers] To identify networks, a simple arbitrary string, obeying the same restrictions as for server names (see section 1.1), is used, since if a numeric identifier (as for servers and clients) were used, it would be difficult to ensure that every network in existence used a different identifier, while network names are generally better known. To establish an inter-network connection, a server on one network sends a "remote server" message (see section 3.1.4) to a server on another network. If the connection is permitted, both the sender and the receiver of the message send out "new network" messages to the rest of the servers on their own networks identifying themselves as border servers (see section 3.1.5). If server B3 in Figure 2 were now to make a connection as a remote server to server C1, then it would inform all servers on network B of the new connection; likewise, server C1 would inform all servers on network C of the connection to network B. However, note that server B1 would not pass the remote network message along to server A4; in order to pass messages from network A to network C, a server on network A would have to connect directly to a server on network C. See section 5.1 for a discussion of the reasoning behind this decision. If a client on network A wishes to send a message to a client on network B, the client would include the name of network B in its message and set a flag bit marking the message as for a remote network (see section 2 for information about the message format). The client's server would then forward that to the nearest border server for network B (A4), which would forward it to the server on network B to which it was connected (B1). That server would then either deliver the message to the destination client or return an error message (which would be returned via the border server on network A). Likewise, a client on network B could join a channel on network A; any messages then sent to the channel by clients on network A would be sent to server A4, which would forward them to server B1 for the client on network B. In all cases the messages would include the "remote network" flag to distinguish the client on network B from any client on network A which shared the same server and client identification numbers and might otherwise be confused with the client on network B. 1.6.3 One-to-many messages There are two types of one-to-many messages: server-to-clients and server-to-servers. The former includes all messages sent to a channel by a client, all channel state changes (which are sent to all clients on the channel), and global messages sent by IRC operators; the latter includes all state changes and all messages with targets on servers other than the one the message originated from. In the latter case, the message is sent from the source server to all servers along the shortest paths to all destination servers / destination clients' servers, using the shortest-path algorithm described in section 1.5.1. In order to prevent messages from travelling in cycles, a message from one server to another includes a hop list containing the ID numbers of the servers through which the message has passed. Also, to prevent a server from processing a message twice which reaches it through two different paths, a message sequence number method is employed similar to TCP [5] sequence numbers. See section 2.2.2 for detailed information on this component of a message. The following examples, which use Figure 3 below, should help make this more clear. Note that those examples begin from a client action which causes servers to generate this type of message. H / / A---1------5 ,--4-----F / \ ,--' / \ / \ ,--' / \ B \ ,--' / G 2-----------3----E |`--D | C #mychannel: A, C, E, F, H #otherchannel: B, D, F, G #secret: C, D [Figure 3: Small IRC Network with Clients and Channels] Example: Message from client A to channel #mychannel. In this example, there are clients in the destination channel on each of the five servers. Server 1 receives the message from client A and passes it on to server 2, the first server in the shortest path to servers 2, 3, and 4, and to server 5. When server 2 receives the message, it sends the message to servers 3 and 4, which are directly connected to it. It does NOT return the message to server 1, even though a client on server 1 is in the destination channel, because server 1 has put its ID in the hop list. Likewise, neither server 3 nor server 4 will send the message back to server 2. Servers 3 and 4 will each send the message to each other, but they will each drop the second copy because of the sequence number check (see section 2.2.2 for details). Example: Message from client D to channel #otherchannel. In this example, the message will be directed to clients on servers 1, 2, and 4. Server 2 forwards the message to servers 1 and 4, but not to server 3, since no clients on server 3 are in the destination channel. Example: Message from client C to channel #secret. The only clients on the destination channel are on server 2, so when server 2 receives the message, it does not send it to any servers, but instead simply sends it to client D. (Note that client C, the sender, does not get a copy of the message back.) This algorithm is also used when sending messages to clients on a local channel. 2. THE IRC SPECIFICATION Communication over the IRC network takes place via messages and replies. Messages can be sent over any connection in any direction, while replies are always sent from a server (to a client or server). "Augmented BNF", used below to provide formats of message and reply elements, refers to the modified Backus-Naur Form used in RFC 822 [6]. All messages and replies consist of a string of arbitrary 8-bit values (data octets). Many message and reply fields contain values with a width greater than one octet; such values are transmitted in big-endian order, i.e. with the most significant octet first. Bits in a value are always numbered starting from the right (lowest-order bit), with the lowest-order bit being bit 0. All values are unsigned unless otherwise specified. 2.1 Strings Of particular interest is the format used to transmit strings of ASCII text or other data intended for display to a user, since such strings are potentially found in nearly every message and reply sent. Since these strings can be of widely varying lengths, and transmitting all strings in a fixed-width field would be a tremendous waste of bandwidth, the length of the string in octets is transmitted first, as a 16-bit or 32-bit value, followed by the octets which comprise the string itself. A zero-length string is valid, and there is no limitation on the values of the octets in the string. If the length of a string is greater than 32,767 octets, a 32-bit length MUST be used to represent the string length; otherwise, a 16-bit length SHOULD be used. Note that since strings may contain any binary information, they can be used for any variable-length information which is sent over the IRC network. The augmented BNF representation for a string is: length16 = <16-bit count of octets in the remainder of the object which the rule describes> string16 = length16 *32767 length32 = string32 = length32 *2147483647 string = string16 / string32 2.2 Messages There are two distinct formats for messages: messages sent from a client to a server or from a server to a client (called client messages), and messages sent from a server to another server (called server messages). Both formats contain similar information, but are each optimized for their specific purpose. A separate type of message -- the server reply -- also uses the client message format. Both message formats begin with an 8-bit start-of-message indicator, followed by a 16-bit flag parameter, followed by a 32-bit value containing the length of the remaining data in the message in octets. The start-of-message indicator is an octet with decimal value 253. If the first octet of a supposed message does not have this value, the client or server MUST discard the octet as belonging to a previous message. This makes it less likely that a transmission error will cause complete desynchronization of a connection, which could otherwise be possible due to the lack of an end-of-message delimiter such as the CR/LF pair used in the old protocol; the value 253 was chosen for the start-of-message indicator because it is believed relatively unlikely to appear in an actual message. Bit 15 of the flag parameter is reserved; it MUST be set to zero when sending a message. Bit 14 of the flag parameter is cleared (zero) for client messages and set (one) for server messages. If a client or server receives a message in an inappropriate format, it MUST discard that message, though it MAY log the message or in some other way record the fact that it received such an erroneous message. Bit 13 of the flag parameter is the Unicode support flag (see section 1.5); any message sent by a client or server which supports Unicode MUST have this flag set, whether or not the message actually uses any Unicode characters. Bit 12 of the flag parameter is the Unicode flag (see section 1.5); any message which includes strings containing Unicode characters MUST have this flag set. If bit 9 of the flag parameter is set, all strings are considered to have 32-bit length fields rather than 16-bit length fields. Bits 7 and 6 of the flag parameter are reserved for experimental or local use. Bit 5 of the flag parameter is set when the message's source or destination is a remote network. The network field MUST be included wherever listed in the message grammar if bit 10 of the flag parameter is set; otherwise the network field MUST NOT be included. Additional bits are defined below, and all of the flag bits are summarized in section 2.3. All flag bits not defined by this protocol MUST be set to zero when sending a message. Both clients and servers MUST read exactly the number of octets given by the length parameter, regardless of the validity of the message, and MUST send exactly the number of octets they specify in the length parameter. However, servers MAY discard a message if it is not received completely within a certain time period (10 seconds is recommended), to prevent malicious or accidental resource starvation by sending large messages through multiple clients. Servers MAY disconnect the remote client or server in this instance, but if not, the number of octets specified by the length parameter MUST be read from the input stream before beginning to process another message from the remote server or client, even though the input will be immediately discarded, to prevent desynchronization. If the message length field is not completely received within the timeout period, the server MUST disconnect the remote client or server if they do not wish to wait for the length field to be completely received. Servers and clients MAY also limit the length of a message they will accept, and MAY terminate a connection upon receipt of a message exceeding that length, but MUST read the specified number of octets if they do not terminate the connection. 2.2.1 Client messages (commands) Client messages consist of the aforementioned flag and length, followed by a message code, possibly a sender (whether the sender is present depends on the direction the message is traveling), and a parameter list. Each parameter is a string, though for the sake of clarity parameters will only be referred to as strings when they are not integer values. The end of the parameter list is implicitly determined by the length of the message. If the length given for a parameter would exceed the length of the message, the server or client receiving the message MUST truncate the parameter when the message's length is reached and, in the case of a server, MUST send an ERR_NEED_MORE_PARAMS error reply (see section 2.2.3) and discard the message if there are fewer parameters than expected. The behavior of a client upon receiving a such a message is undefined by this protocol. The sender field is present only in messages sent from a server to a client; clients MUST NOT include a sender field, as the server would misinterpret this as the beginning of the parameter list. The sender field consists of a a string containing the sender's network's name (iff bit 5 of the flag parameter is set), followed by a string containing the sender's nickname (or the server name, if the sender is a server), possibly followed by a string containing the sender's user@host address (if the sender is a client). If the address is included, bit 11 of the flag parameter MUST be set. If the Unicode flag is set, the address MUST be in Unicode (type "addr-unistring" below); otherwise, the address MUST NOT be in Unicode (type "addr-string" below). The address MUST be sent on all client join, leave, and quit messages which are broadcast to other clients, and MAY be sent with any other client-generated message. (Obviously, the address makes no sense for server-generated messages.) Clients MUST accept any length string in the sender address field, though they MAY discard a string longer than a certain length depending on display and other requirements. The augmented BNF description of a client message is: client-message = flag length (cli-serv-msg / serv-cli-msg) length = length16 / length32 ;chosen as appropriate flag = shortint shortint = <16-bit integer> cli-serv-msg = code [network] * ;message from client to server code = shortint network = string ;destination network parameter = string octet = serv-cli-msg = code [network] sendername [senderaddr] * ;message from server to client sendername = string ;sender's nick / servername senderaddr = addr-string | addr-unistring ;sender's user@host address addr-string = length * "@" * addr-octet = addr-unistring = length * "@" * addr-unichar = 2.2.2 Server messages Server messages are similar to client messages, with the following differences: All server-to-server messages include a message sequence number, used to ensure that no message is processed twice by the same server. When a server registers itself (see section 3.1.3), it provides an initial message sequence number. Whenever that server generates a new server-to-server message, for example when a directly-connected client requests a mode change, it increments its current message sequence number and stores that number in the seqnum field of the server-to-server message (immediately after the message length). When a server receives a message from another server, it compares the sequence number in the message with the last sequence number seen from the originating server (the server in the source parameter). If the sequence number of the received message is less than or equal to the last sequence number seen from the given server, the message is a duplicate and is therefore ignored. Specifically, if the signed 32-bit difference (message sequence number) - (source's last seen sequence number) is less than or equal to zero, the server MUST discard the message. Note that, since not all messages are sent to all servers, it is theoretically possible for a server to generate 2**31 = 2,147,483,648 consecutive messages such that at least one other server sees none of them; that server would then ignore the next 2**31 messages from the sending server as being duplicates. However, the author does not believe this situation will ever occur in practice, since, among others, all state change messages (including client connections and disconnections and channel joins and parts) are transmitted to all servers. Should this situation occur, it could be resolved by breaking the connection between the two servers (if one existed) and reestablishing it. Note also that this algorithm assumes that all data is transmitted in sequence along all paths. Without this assumption, it is possible for a later message to overtake an earlier one, causing some messages to be inappropriately discarded. For this reason, IRC servers MUST use a transport protocol that guarantees in-order delivery of data, such as TCP [5], or explicitly implement such a protocol on top of an existing transport protocol. As described in detail in section 5.5, cyclic networks present additional difficulties with respect to message passing. *** FIXME: update this when section 5.5's FIXME is resolved All server-to-server messages also include a "trace" of hops (servers) the message has already passed through. When a server generates a message, it sets the length of the hop list to 1 and inserts its own server ID as the sole element in the hop list. When forwarding a message from a server to another server, the forwarding server increments the length of the hop list by 1 and inserts its server ID as the first element in the hop list. See section 1.6.3 for more discussion of the hop list and server-to-server messages. The original sender of the message is always included, and both the source and destination are encoded using the server and client ID values. The reserved client ID 0 (zero) is used to indicate that the source of a message is the server itself and not a particular client on that server; or that the message has a special destination, depending on the value of the lowest two bits of the flag parameter: 0 - indicates that a message is destined for all servers, rather than any particular client or set of clients. 1 - indicates that a message is destined for a channel; the name name of the channel is the first parameter of the message. (This mode is only used with messages which can have a channel name as the first parameter, such as public messages (see section 3.2.1).) 2 - indicates that a message is destined for only the server to which it was sent. 3 - indicates that a message is destined for all clients on the server. Furthermore, all server messages MAY include a timestamp that indicates when the original message was sent. Servers MUST include a timestamp for the user registration (section 3.1.2) and nickname change (section 3.4.1) messages. If a timestamp is included, bit 8 of the flag parameter MUST be set. See section 2.4 for information on timestamps, including the reasons for using a 64-bit integer. In augmented BNF, the server message format is as follows: server-message = flag length seqnum hop-list code source dest [timestamp] * seqnum = longint hop-list = hop-count *32767 hop-count = shortint ;number of servers in hop-list source = [network] serverid clientid serverid = shortint clientid = shortint dest = [network] serverid clientid timestamp = <64-bit integer> 2.2.3 Replies Replies are a special type of message sent by servers in response to messages from clients or other servers. Replies are used when there is no information to be sent other than a status code and possibly a descriptive string. A server is the only legal source for a reply; if a server receives a reply from a client, it MUST ignore the reply. Replies use the same format as server-to-client messages as described above, except: bit 10 of the flag parameter is set to indicate a reply as opposed to a standard message; the "code" refers to a reply code instead of a message code; and only one parameter (an optional one) is allowed: a string describing the reply. Servers SHOULD NOT include descriptive strings when sending replies to other servers, but MAY include strings when sending replies to clients. (However, if a server receives a string in a reply, it MUST pass that string along unmodified.) Interactive clients (as opposed to automated scripts or programs) SHOULD display a default description if one is not sent with the reply. The augmented BNF description of a reply: reply = flag length code sendername [string] 2.3 Summary of message flag bits Bit 15: Reserved, set to 0. 14: 1 if the message is from a server, else 0. 13: 1 if the sender of the message supports Unicode, else 0. 12: 1 if the message uses Unicode, else 0. 11: 1 if the message includes a sender address field, else 0. 10: 1 if the message is a reply, else 0. 9: 1 if the message has strings with 32-bit lengths, else 0. 8: 1 if the message includes a timestamp, else 0. 7-6: Reserved for experimental or local use; values undefined. 5: 1 if the message is to or from a remote network, else 0. 4-2: Unused, set to 0. 1-0: Identify the destination of a message with destination client ID equal to zero; see section 2.2.2. 2.4 Timestamps A number of messages require timestamps to be sent. All servers on a network MUST assign the same meaning to this time value; servers SHOULD use the current Unix standard (seconds since 1 January 1970 00:00 GMT), to reduce difficulties for clients in determining what timestamp system is in use. Since servers that use the time system described above will run into problems beginning in January 2038 if a 32-bit signed integer is used to store the time, and 32 bits is a considerable restriction on the range of times representable in many other conceivable time systems (such as systems using milliseconds as the base unit), all timestamps, when sent in binary format, MUST be sent using 64 bits. Clients and servers MUST be prepared to properly handle any timestamp value, including values outside the range of a 32-bit integer. Additionally, clients which process decimal time values (particularly in response to query messages; see section 3.6) MUST be prepared to handle values outside the range of a 32-bit integer. 3. MESSAGE DETAILS This section describes in detail each of the different messages defined for this protocol. Unless otherwise noted, all of the messages described below MUST be implemented by all servers. Note that messages are also called "commands", particularly when referring to the act of a client sending a message to a server to request a certain action on the part of the server. Parameters are listed below in the following format: tag (type) where "tag" is a text string describing the parameter and "type" is one of the types described in previous sections (string, shortint, etc.) or a new type which is defined immediately after the parameter list. Brackets ("[" and "]") around a parameter (or more than one parameter) indicate that the parameter is optional. An ellipsis ("...") following a parameter indicates that that parameter may be repeated as many times as desired. A few messages have different formats depending on whether the message is sent by a client or a server. For such messages, two parameter lists are given, one preceded by "" and the other preceded by "", for messages generated by clients and servers respectively. If a server encounters a fatal error while parsing a message, it MUST immediately stop parsing that message and return an error reply to the source of the message. Fatal errors include: an invalid command code, an insufficient number of parameters, and insufficient privileges for the given command. A full list of error conditions in messages is given in section 3.9. If a server successfully parses a message, it MUST act on all of the parameters, sending appropriate replies for each. In the descriptions below, a string is represented by characters inside double quotes (i.e. the length word is omitted). The example messages are given without the flag and length parameters, and are prefixed by one of: "CS:" for a client-to-server message, "SC:" for a server-to-client message, or "SS:" for a server-to-server message. In server-to-client examples, the sender's address is not included unless required. In general, only one example is given unless another is needed to illustrate a particular point. The list of replies indicates all of the possible replies that can be generated by that message. A particular message may cause none, one, some, or all of those replies to be sent. Note that this list only includes server-to-client messages which fall under the "replies" category (section 2.2.3); they do not include "command" messages (section 2.2.1) sent back to the client. The reply code ERR_NOT_REGISTERED is not listed; see section 3.9 for conditions under which it is to be generated. Where a description refers to "forwarding" a message received by a server and is not otherwise qualified, the term refers to the server sending, to all other servers on the network, a server-server message containing the same message code and parameters as the original message. In any message including a target, the message MUST be sent to that target as described under section 1.5 unless otherwise noted. "Wildcards" in a string refer to the characters "*" (asterisk, ASCII 0x2A) and "?" (question mark, ASCII 0x3F). The former matches any sequence of zero or more characters, and the latter matches exactly one character. These are the same meanings as used in many Unix shells, VAX/VMS, and MS-DOS, among others. Except as otherwise specified, all implementations MUST implement the messages below with exactly the behavior listed. Message codes, parameters, or bits in parameters listed as reserved for experimentation have undefined behavior for the purpose of the protocol definition. 3.1 Connection registration and cancellation These commands are concerned with establishing and breaking client-server and server-server connections. All messages in this group except the password and remote server messages MUST be forwarded; those two message types MUST NOT be forwarded. 3.1.1 Password message Code: 0x0000 Parameters: password (string) Establishes a "connection password" for a new connection. This allows greater certainty about the identity of the remote side of the connection. If a password message is sent, it MUST be sent before the connection registration message (see section 3.1.2 and 3.1.3). The password message is client-server only. Examples: CS: 0x0000 "secret" The initiator of a remote connection is sending the password "secret" to verify his identity. Replies: ERR_NEED_MORE_PARAMS ERR_ALREADY_REGISTERED 3.1.2 User message Code: 0x0001 Parameters: version-id (shortint), nickname (string), username (user-string), real-name (string) Server-only parameters: time (timestamp) longint = <32-bit value> user-string = * Registers a connection as a client. The nickname parameter indicates what name the client will be known by to other clients. The username is the login identifier used by the client on its host; typically, this will be the username portion of an E-mail address. The real-name is an arbitrary string giving the actual identity of the client; typically, this is the real name of the user running the client program. Note that the client's hostname, as appears in the source address of server-client messages generated (indirectly) by the registering client, is not given in this command; instead, it is determined from the address of the host on the remote side of the connection. (See section 6.2 for a note on this procedure.) The version-id parameter is used to identify the version of the protocol in use; the value 0x0100 is assigned to represent the protocol defined by this document. Future revisions of this protocol will be assigned version-id values in strictly increasing order and will be less than 0x8000; the range 0x8000-0xFFFF is reserved for local and experimental use, and implementors which add or modify features of this protocol MUST choose a new version-id value in that range for their revised protocol. The time parameter is added to the message by the server to which the client connected before the message is broadcast to other servers. If the nickname given by the client is already in use, the server MUST return ERR_NICKNAME_IN_USE and ignore the message. Examples: CS: 0x0001 "Alcan" "achurch" "Andrew Church" The author's client registers its connection using the nickname "Alcan". SS: 0x0001 0x00000000 0x00000000 843254181 "Alcan" "achurch" "Andrew Church" Server 0 informing the network of the connection described above; note that a timestamp is included. Replies: ERR_NEED_MORE_PARAMS RPL_WELCOME ERR_ALREADY_REGISTERED RPL_WELCOME2 ERR_BAD_PASSWORD ERR_CLIENT_DENIED ERR_NICKNAME_IN_USE ERR_NAME_TOO_LONG 3.1.2.1 A note on the Ident Protocol Earlier versions of the IRC protocol took advantage of the Ident Protocol [7] to obtain a username from a (supposedly) more reliable source than the client connection. Many implementations of the protocol included a special character at the beginning of a username when an ident reply could not be obtained, and some implementations even refused client connections when ident service was not available. However, to quote from RFC 1413, which defines the Ident Protocol: "The Identification Protocol is not intended as an authorization or access control protocol. At best, it provides some additional auditing information with respect to TCP connections. At worst, it can provide misleading, incorrect, or maliciously incorrect information. "The use of the information returned by this protocol for other than auditing is strongly discouraged. Specifically, using Identification Protocol information to make access control decisions - either as the primary method (i.e. no other checks) or as an adjunct to other methods MAY RESULT IN A WEAKENING OF NORMAL HOST SECURITY." (emphasis added) Indeed, in the author's experience, a very great majority of users use personal computers for Internet connectivity, and thus have the ability to send an arbitrary identifier in response to an ident request. Some of the multi-user systems (including the author's own) on which clients may be run do not run an ident server -- thus preventing such clients from connecting to any servers which require ident -- and in any case, the most common IRC clients used on multi-user systems will send the user's true user identifier when connecting. Moreover, the author has observed numerous occurrences of a malicious user usurping the identity or privileges of another user despite the supposed added security of the Ident Protocol. Therefore, IRC servers SHOULD NOT use the Ident Protocol for any purpose directly related to the implementation of this protocol, including but not limited to access control decisions. However, the result of an ident lookup MAY be stored as auxiliary information lookup as auxiliary information, for possible use by the server administrator in (for example) tracking malicious users. If an identification protocol with the purpose of returning _authenticated_ user identifiers is developed and gains wide acceptance, this section will be re-evaluated with respect to that protocol. Such a protocol would necessarily be completely inaccessible to the user, whether the user was on a multi-user system or his/her own personal computer. 3.1.3 Server message Code: 0x0002 Parameters: version-id (shortint), server-id (shortint), server-name (string), server-desc (string), initial-seqnum (longint) Registers a connection as a server. The server-name parameter is the name of the server, as described in section 1.1. Server-desc is an arbitrary string describing the server; it may identify the organization responsible for maintaining the server, for example. Server-id is a 16-bit integer uniquely identifying the server, as described in section 1.2. The initial-seqnum parameter gives the server's initial message sequence number (see section 2.2.2). The version-id parameter is as described for the user registration message (see section 3.1.2). A server MUST reject an attempted registration with ERR_WRONG_VERSION if it is not prepared to support the version supplied. Servers compliant with this protocol MUST accept connections which supply the value 0x0100 in that field. Upon successful registration of a server, both the registering server and the server to which it connected MUST send all state information, using server messages, network messages (section 3.1.5 below), user messages (section 3.1.2 above), join messages (section 3.3.1), and channel mode, topic, operator, voice, and ban messages (sections 3.3.3-6 and 3.3.8). The order of the messages is subject to the following constraints: - All server messages must come before all other messages. - All network messages must come immediately after all server messages. - No join message may be sent for a client for whom a user message has not yet been sent. - No channel message may be sent before at least one client has joined the channel. Unlike all other messages between servers except the remote server message (see section 3.1.4 below), this message, when used to register a server connection, is sent in client-server message format. Examples: SS: 0x0002 0x0100 0 "dragonfire.esper.net" "Dragonfire's EsperNet IRC server" Server 0 (dragonfire.esper.net) registers itself as a server after connecting to server 1, using version code 0x0100. SS: 0x0002 0x00010000 0x00020000 0x0100 0 "dragonfire.esper.net" "Dragonfire's EsperNet IRC server" Server 1 informs server 2 of the new server connection. Replies: ERR_NEED_MORE_PARAMS RPL_SERVER_WELCOME ERR_ALREADY_REGISTERED ERR_BAD_PASSWORD ERR_SERVER_DENIED ERR_NAME_TOO_LONG ERR_WRONG_VERSION 3.1.4 Remote server message Code: 0x0042 Parameters: network-name (string), server-id (shortint), server-name (string), server-desc (string) Similar to the server message (described above), this message registers a connection as a server. The difference is that a server using this message is registering itself as a border server from an outside network. Such a server will, if the connection is allowed, then be able to pass messages from its own network to the network to which it is connecting, and will receive messages from that network destined for its own network. See section 1.6.2.1 for more information on inter-network messages. The network-name parameter is a string containing the name of the network, as described in section 1.6.2.1. The other parameters are as described for the normal server registration message in section 3.1.3. Note that servers MUST NOT send state information to remote networks. Unlike all other messages between servers except the server message, this message is sent in client-server message format. Examples: SS: 0x0042 "EsperNet" 0 "dragonfire.esper.net" "Dragonfire's EsperNet IRC server" Server 0 from the network "EsperNet" connects to a server on another network and announces itself as a remote server. Replies: ERR_NEED_MORE_PARAMS RPL_BSERVER_WELCOME ERR_ALREADY_REGISTERED ERR_BAD_PASSWORD ERR_SERVER_DENIED ERR_NETWORK_DENIED ERR_NAME_TOO_LONG 3.1.5 Network message Code: 0x0043 (add), 0x00C3 (remove) Parameters: network (string) Indicates that the server has become (0x0043) or is no longer (0x00C3) a border server for the specified network. Examples: SS: 0x0043 0x00010000 0x00020000 "EFNet" Server 1 sends a message to server 2 indicating that it is now a border router for the network "EFNet". Replies: ERR_NEED_MORE_PARAMS ERR_NOT_SERVER ERR_NAME_TOO_LONG 3.1.6 Quit message Code: 0x0004 Parameters: [reason (string)] Terminates a client connection. The "reason" is an arbitrary text string sent by the client which, as the name implies, is intended to reflect the reason for the quit. Normally, a quit message will be sent to the server by the client just before it closes the connection. However, certain circumstances may cause a server to forcibly close a client's connection. Such circumstances SHOULD be limited to a "ping timeout", as described in section 3.6.2; a kill message, as described in section 3.4.5; a nickname collision, as described in section 5.2.1; and an operating system error which prevents the server from reading data from the client's connection. When a server forcibly closes a connection, it MUST generate a quit message on the client's behalf, it MUST include a "reason" describing why the connection was closed, and it MUST send that quit message to the client whose connection is being closed (if possible). Any server receiving a quit message, whether from a directly-connected client or from another server, MUST send that message to all clients connected to it who are on any channel the quitting client was on. Examples: CS: 0x0004 "Off to work" A client closes its connection with the message "off to work". SC: 0x0004 "Alcan" "Connection reset by peer" The server has closed Alcan's client connection due to the operating system error "Connection reset by peer". Replies: None. 3.1.7 Server quit message Code: 0x0005 Parameters: server-id (shortint), [reason (string)] Terminates a server connection. The server-id is the ID number of the server which is disconnecting; the reason is, as with the quit message, intended to describe why the server is quitting. Upon receipt of a server quit message, the server removes the quitting server from its internal server list, and if the quitting server is connected directly to the receiving server, the connection is closed. In addition, the server also removes from its internal lists any server which can no longer be reached because of the broken connection. If any now-unreachable clients were on channels that any clients local to the server are also on, then the server MUST generate and send quit messages on their behalf as described in the previous section; the reason in those quit messages SHOULD be of the form "server1 server2", where server1 and server2 are the servers at either end of the severed connection: server1 is the server which is still on the IRC network, and server2 is the server which is no longer on the network. As with the quit message, connections may be closed either voluntarily or forcibly. In the former case, the server which is disconnecting sends its own ID in the server-id parameter. In the latter case, the server closing the connection sends a server quit message to the server whose connection is being closed, which MUST include an explanation of why the connection is being closed. Examples: SS: 0x0005 0x00000000 0x00010000 0 "Terminated" Server 0 closes its connection to server 1 for the reason "Terminated". Replies: ERR_NEED_MORE_PARAMS 3.2 Message sending These messages, which send strings to a client or a set of clients (such strings are also called "messages"), form the core of the IRC protocol. Note that these strings need not be only readable text; they may contain any arbitrary series of octets, and could be used, for example, to send special client-oriented commands between clients, such as the "CTCP" protocol ("Client To Client Protocol") in use on current IRC networks, or to send multimedia data on high-speed local area networks. However, such protocols are beyond the scope of this document. 3.2.1 Public messages Code: 0x0100 Parameters: target (string), message (string) Sends a string (message) to a target channel. Whether the message is actually delivered depends on the channel modes (see section 3.3.3) and whether the sender is in the channel. This message is forwarded to any servers on which there is a client in the channel, and to any clients in the channel on that server, including the sender. Examples: CS: 0x0100 "#dragonweyr" "Hi, all." A client sends a message to channel #dragonweyr. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_CHANNEL ERR_CANNOT_SEND 3.2.2 Private messages Code: 0x0101 Parameters: nickname (string), message (string) Sends a string (message) to a target client (nickname). Whether the message is delivered depends on the target client's "silence" list (see section 3.4.3). Examples: CS: 0x0101 "Alcan" "How are you?" A client sends a private message to client Alcan. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_USER ERR_CANNOT_SEND 3.2.3 Notices Code: 0x0102 (channel), 0x0103 (private) Parameters: target (string), message (string) These two commands are similar to the public and private message commands, with one difference: A client or server which receives a notice MUST NOT generate any other messages (including server error messages) in response to the notice. This makes notices ideal for responses from automated clients, to prevent possible message loops. Examples: CS: 0x0103 "Alcan" "Your nickname has been registered." A client sends a notice to client Alcan. The sending client is automated, and therefore sends only notices to prevent another automated client from replying to it. Replies: None. 3.2.4 Server notices Code: 0x0104 Parameters: message (string) Sends a string to all clients on the server with the user mode UMODE_SERVER_NOTICES set (see section 3.4.4). This is typically used to broadcast server-specific status messages; status messages relevant to the entire network SHOULD be sent as operator messages (section 3.2.5). This message is only sent by servers, and MUST be ignored when received from a client. Examples: SC: 0x0104 "Client exiting: Alcan (Leaving)" The server reports a client's disconnecting. Replies: None. 3.2.5 Operator messages Code: 0x0105 Parameters: message (string) Sends a string to all IRC operators who are currently online (and who have not disabled their ability to receive such messages; see section 3.4.4). Only IRC operators may send this message. This message is not sent directly from the receiving server to all target clients; instead, it is forwarded to all servers, and each server sends the message to any target clients directly connected to it. Servers MAY generate operator messages to inform IRC operators of network events, such as the establishing or breaking of a server-to- server connection. For events local to a single server, servers SHOULD use server notices (see section 3.2.4). Examples: CS: 0x0105 "Watch out for clones from lame.org." An IRC operator sends a message to all other online operators. Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED 3.2.6 Global messages Code: 0x0106 Parameters: message (string), [target-server (string)] Sends a string to all clients on a given server. If the target-server parameter is omitted, the string is sent to all users on the IRC network. Only IRC operators may send this message. This message is not sent directly from the receiving server to all target clients; instead, it is forwarded to all servers, and each server sends the message to any target clients directly connected to it. Examples: CS: 0x0106 "This server will be shutting down in 2 minutes." "dragonfire.esper.net" An IRC operator sends a message to all clients on server dragonfire.esper.net. Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.3 Channel operations These messages affect channels and the access privileges of clients in channels. All messages in this group MUST be forwarded except as noted, and MUST be sent by each server to all clients connected to that server on the channel sent in the message. 3.3.1 Join message Code: 0x0200, 0x0280 Parameters: (0x0200) channel-name (string) [...] (0x0280) channel-name (string), key (string) Adds the sender to the list of clients in the given channel(s), assuming the sender is allowed to join those channels. If any of the channels specified do not exist, they are created and the sender is given channel-operator status in those channels (see section 3.3.5). New channels do not have any modes active (see section 3.3.3). If a client is not allowed to join a channel, the reply ERR_CANNOT_JOIN is sent for each such channel. Failed join messages MUST NOT be forwarded. The second form of the join message is used when a channel has a key associated with it (see section 3.3.3); only one channel may be joined with a single message in this form. When broadcasting join messages to clients in the joined channel(s), the server MUST send a separate join message for each channel using message code 0x0200, and MUST NOT include any key used in the original join message. Upon joining, the server SHOULD send to the client the channel topic, current channel modes, and a list of all clients on the channel, as if the user had sent a topic message (section 3.3.4), mode message (section 3.3.3), and names message (section 3.6.2) for the channel. Examples: CS: 0x0200 "#dragonweyr" "#help" A client joins channel #dragonweyr and #help. CS: 0x0280 "#mychannel" "mykey" A client joins channel #mychannel, sending the key "mykey" to be allowed to join. SC: 0x0200 "Alcan" "achurch@achurch.org" "#mychannel" The server broadcasts the previous join message to the channel. Note that code 0x0200 is always used, and the key is not sent. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_CANNOT_JOIN 3.3.2 Part message Code: 0x0201, 0x0281 Parameters: (0x0201) channel (string) ... (0x0281) channel (string), reason (string) Removes the sender from the list of clients in the given channel(s). If no clients are left in any of the channels specified, those channels are deleted. In the second form, the client may send a reason with the part message. Only one channel at a time may be left with this form of the message. When broadcasting the part message to clients in the parted channel(s), the server MUST use message code 0x0281, and MUST send an empty string for the "reason" parameter if one was not given in the original message. Examples: CS: 0x0281 "#dragonweyr" "Be back later" A client leaves channel #dragonweyr for the reason "Be back later". CS: 0x0201 "#dragonweyr" "#help" A client leaves channels #dragonweyr and #help. SC: 0x0281 "#help" "" The server informs clients in #help of the previous message. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NOT_IN_CHANNEL 3.3.3 Channel mode message Code: 0x0202 Parameters: channel (string), [new-modes (bits-32), new-modes-mask (bits-32), [mode-parameter ...]] bits-32 = longint This command sets binary modes for the channel or returns the current channel modes. If only a channel name is given, the current modes of the channel are returned, using the same message code with server-client format (assuming the channel is not secret, see below). Otherwise, the new-modes parameter lists the new values for the channel modes, and the new-modes-mask parameter indicates which modes are actually to be changed. This allows changing channel modes one at a time without having to specify the entire set of channel modes each time. Channel modes may only be set by a channel operator. When this message is used to change channel modes, the server's reply includes only those modes which were changed in the new-modes-mask parameter; to obtain a full list of channel modes, a query message must be sent. A query message is simply a channel mode message with no mode parameters. Some modes require parameters when they are set active; these are given in increasing bit order -- i.e. the parameter for the lowest bit set in new-modes is given first, and so on. See the second example below. If a client which does not have channel operator privileges attempts to change channel modes, the server MUST reply with ERR_PERMISSION_DENIED and discard the message without processing it. Compatibility note: some operations which were considered "mode changes" in the original IRC protocol, setting channel operators for example, have been separated into distinct commands in this protocol. The channel mode message is only for changing channel flags. The following channel modes are currently defined: 0x00000001 CMODE_PRIVATE A channel marked PRIVATE can only be queried by clients outside the channel if they know the exact name of the channel. "Querying" a channel includes sending any messages which would return information about the channel, i.e. the channel mode message, who message (section 3.6.1), names message (section 3.6.2), and list message (section 3.6.3). 0x00000002 CMODE_SECRET A channel marked SECRET cannot be queried by clients outside the channel at all. A superset of CMODE_PRIVATE -- i.e., setting CMODE_PRIVATE in addition to this flag will have no effect. 0x00000004 CMODE_EXTERN_MSGS If a channel has this mode active, clients do not need to be in the channel in order to send messages to it. 0x00000008 CMODE_TOPIC_OPS This mode limits the ability to change the channel's topic (see section 3.3.4) to channel operators. 0x00000010 CMODE_INVITE_ONLY If this mode is set, clients can only enter the channel if they have been invited (see section 3.3.9). 0x00000020 CMODE_MODERATED If this mode is set, clients in the channel can only send messages to the channel if they are channel operators or have been "given a voice" (see section 3.3.6). Note that this does not affect the operation of CMODE_EXTERN_MSGS. 0x00000040 CMODE_USER_LIMIT (parameter: limit (shortint)) If this mode is set, the number of clients which can be in the channel is limited to the given value. 0x00000080 CMODE_KEY (parameter: key (string)) If this mode is set, the channel may only be entered by clients sending a join message with a key parameter identical to the key given with the mode message. Note that the key is never sent to any client in a mode status or change message. 0x00000100 CMODE_LOCAL If this mode is set, the channel is local; if this mode is not set, the channel is distributed. This mode may only be changed when there is exactly one client in the channel; otherwise, the server MUST return ERR_CANNOT_CHANGE_DIST_LOCAL and discard the entire message. 0x00800000 CMODE_LOCKED If this mode is set, the channel mode is "locked", i.e. may not be changed. Specifically, if a client without IRC operator privileges attempts to change channel modes on a channel which has the CMODE_LOCKED flag set, the server MUST return ERR_CANNOT_CHANGE_LOCKED and discard the entire message. A server MAY allow IRC operators, or a certain subset of IRC operators, to change modes when the CMODE_LOCKED mode is active. The upper eight bits of the mode parameter are reserved for experimental and/or local use. All other bits are reserved for future expansion of the protocol and MUST NOT be used by any client or server. If any mode change in a mode change request is disallowed, the entire mode change request MUST be discarded. For example, if a client with channel operator privileges tries to set both CMODE_LOCAL and CMODE_MODERATED in the same message, the server MUST discard the message without changing any modes, even though the CMODE_MODERATED flag by itself would have been permitted. Examples: CS: 0x0202 "#dragonweyr" 0x00000008 0x00000008 Channel #dragonweyr is given the CMODE_TOPIC_OPS mode. CS: 0x0202 "#mychannel" 0x000000C0 0x000000D0 30 "mykey" For channel #mychannel, the CMODE_INVITE_ONLY flag is removed, and the CMODE_USER_LIMIT and CMODE_KEY flags are set. The client limit is set to 30, and the channel key is set to "mykey". SC: 0x0202 "#mychannel" 0x000000C0 0x000000D0 30 The server sends this message back to all clients in the channel. Note that the key has been removed from the mode parameter list. CS: 0x0202 "#mychannel" A client queries the modes in channel #mychannel. SC: 0x0202 "#mychannel" 0x000000C9 0xFFFFFFFF 30 A response to the above mode query, indicating the modes CMODE_PRIVATE, CMODE_TOPIC_OPS, CMODE_USER_LIMIT, and CMODE_KEY are set, with a limit of 30 clients in the channel. Again, the key is not included. The new-mode-mask will always have all bits set in this type of response. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED ERR_CANNOT_CHANGE_DIST_LOCAL ERR_CANNOT_CHANGE_LOCKED 3.3.4 Topic message Code: 0x0203 Parameters: channel-name (string), [topic (string)] Sets (or retrieves) the "topic" for the given channel; this is a string displayed to clients when they join the channel, and typically indicates the nature of discussion in the channel. A server MUST NOT permit topic changes by unprivileged clients not in the channel, and MUST NOT permit topic changes by unprivileged clients in the channel iff the CMODE_TOPIC_OPS flag is set. Examples: CS: 0x0203 "#help" "General help channel" The topic for #help is set to "General help channel". CS: 0x0203 "#help" SC: 0x0203 "#help" "General help channel" A client requests the topic for #help, and the server returns it. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED 3.3.5 Channel operator message Code: 0x0204 (add), 0x0284 (remove) Parameters: channel-name (string), nickname (string) ... Gives (takes away) channel operator privileges to (from) the given nickname(s) on the given channel. The sender MUST be a channel operator. Code 0x0204 is used to give privileges, and code 0x0284 is used to take them away. Examples: CS: 0x0204 "#dragonweyr" "Alcan" Gives channel operator privileges to Alcan on channel #dragonweyr. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED ERR_NO_SUCH_USER 3.3.6 Channel voice message Code: 0x0205 (add), 0x0285 (remove) Parameters: channel-name (string), nickname (string) ... Gives (takes away) "voice" (permission to send messages on a moderated channel; see section 3.3.3) to (from) the given nickname(s) on the given channel. The sender MUST be a channel operator. Code 0x0205 is used to give privileges, and code 0x0285 is used to take them away. Examples: CS: 0x0205 "#dragonweyr" "Alcan" Gives a voice to Alcan on channel #dragonweyr. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED ERR_NO_SUCH_USER 3.3.7 Kick message Code: 0x0206 Parameters: channel-name (string), reason (string), nickname (string) ... Forcibly removes one or more clients from a channel. The sender MUST be a channel operator. Examples: CS: 0x0206 "#dragonweyr" "Flooding is not permitted." "LaMeR" Forcibly removes the client with the nickname "LaMeR" from channel #dragonweyr with the reason "Flooding is not permitted." Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED ERR_NO_SUCH_USER 3.3.8 Channel ban message Code: 0x0207 (add), 0x0247 (list), 0x0287 (remove) Parameters: channel-name (string), [userhost-mask (string) ...] Adds or removes bans on clients joining channels. If a client attempts to join a channel, and its address matches any of the ban strings for that channel, the client's join request is denied. The ban strings may contain wildcards. For the list message (0x0247), if one or more ban strings are sent, then only those bans matching at least one string are returned, otherwise all bans on the given channel are returned. The server MUST send exactly one ban per response message. For the add (0x0207) and remove (0x0287) messages, at least one string MUST be given, and the sender MUST be a channel operator. Examples: CS: 0x0207 "#dragonweyr" "*@*.lame.org" Bans any client from any system in the lame.org domain from joining channel #dragonweyr. CS: 0x0247 "#dragonweyr" A request for the list of bans for channel "#dragonweyr". SC: 0x0247 "#dragonweyr" "*@*.lame.org" A response to the request for the list of bans. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED 3.3.9 Invite message Code: 0x0208 Parameters: channel-name (string), nickname (string)... Invites the given client(s) to the given channel. If the channel is invite-only (see section 3.3.3), this allows the client(s) to join the channel. The sender MUST be a channel operator. Examples: CS: 0x0208 "#dragonweyr" "Alcan" Invites client Alcan to channel #dragonweyr. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_CHANNEL ERR_NO_SUCH_USER ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED 3.4 Client control messages These messages allow a client to set information about itself, and allow privileged clients to control other clients' access to the IRC network. These messages MUST be forwarded except as specified. 3.4.1 Nick message Code: 0x0300 Parameters: nickname (string) Allows a client to change its nickname. If the nickname is already in use, the server MUST return ERR_NICK_IN_USE and MUST NOT forward the message. This message may also be generated by a server to cause a client to change its nickname. A client receiving a nick message for itself MUST change its nickname to that specified in the message. The server generating the message MUST also forward the message to all other servers. Examples: CS: 0x0300 "NewNick" A client requests a change of nickname to "NewNick". Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NICK_IN_USE 3.4.2 Away message Code: 0x0301 Parameters: [reason (string)] Marks a client as "away" (if the reason parameter is included) or not away (if the parameter is omitted). Any client which sends a private message to a client marked away MUST be sent an away message with the sender field set to the nickname of the client to which the message was sent. (Note that servers MUST NOT discard any messages sent to a client marked away.) Examples: CS: 0x0301 "Getting food" A client marks itself away because of "Getting food". SC: 0x0301 "Alcan" "Getting food" A client tried to send a private message to Alcan, who was marked away, and the server responded with Alcan's current away message. CS: 0x0301 A client marks itself as no longer away. Replies: RPL_MARKED_AWAY RPL_MARKED_UNAWAY 3.4.3 Silence message Code: 0x0302,0x0342 (add), 0x0382,0x03C2 (remove) Parameters: (0x0302,0x0382) nickname (string) (0x0342,0x03C2) mask (string) Adds a nickname or "user@host" mask to or removes a nickname or mask from a client's "silence list". If the client would normally receive a message from a client on the silence list, such messages will be discarded. Specifically, if client B matches an entry on client A's silence list, then: - Any private messages or notices from client B to client A MUST be discarded by both client B's server and (if it receives any) client A's server. - Any other type of message or notice sent by client B which client A would normally receive MUST NOT be sent to client A. Examples: CS: 0x0302 "lamer" Adds the nickname "lamer" to the client's silence list. CS: 0x0342 "*@*.lame.com" Adds the mask "*@*.lame.com" to the client's silence list. Any client matching this mask, regardless of nickname, will be silenced. Replies: ERR_NEED_MORE_PARAMS RPL_SILENCE_ADD RPL_SILENCE_DEL 3.4.4 Client mode message Code: 0x0303 Parameters: [new-modes (bits-32), new-modes-mask (bits-32), [mode-parameter ...]] Similar to the channel mode message (section 3.3.3), this sets various binary modes for a client. "new-modes" and "new-modes-mask" operate as with the channel mode message. Server responses to this command are also as defined for the channel mode message, except where noted below. The following client modes are currently defined: 0x00000001 UMODE_OPERATOR Indicates that the client is an IRC operator. Note that the client may not set this mode directly; if a client attempts to do so, the server MUST return ERR_PERMISSION_DENIED and discard the entire client mode message. Clients may clear (unset) this mode, however. 0x00000002 UMODE_INVISIBLE If this mode is set, the client will not appear in any channel name lists (unless the querying client and this client are both in the same channel, and that channel is the target of the query) or "who" command results unless the querying client is an IRC operator. 0x00000004 UMODE_OPER_MESSAGES If this mode is set and the client is an IRC operator, the client will receive operator messages (see section 3.2.5). Normal clients MUST NOT receive operator messages regardless of the setting of this mode. 0x00800000 UMODE_SERVER_NOTICES (parameter: types (bits-32)) If this mode is set, the server should send to the client informational messages (see section 3.2.4) regarding network and server activity. The parameter indicates which types of messages the client wishes to receive. The meaning of the particular bits in the "types" parameter are not specified here and are left to the implementors, except that a "1" bit MUST indicate a request that messages of a particular type be sent, and a "0" bit MUST indicate that messages of that type should not be sent. Clients SHOULD default to sending a parameter containing all bits set, to allow for a consistent meaning across servers for this mode's default function. Servers MAY limit this mode to IRC operators only. Servers that do so MUST return ERR_PERMISSION_DENIED and discard the entire mode message if sent from a non-privileged client, and MUST unset the UMODE_SERVER_NOTICES mode whenever the UMODE_OPERATOR mode is unset. This mode is also special in that it is server-specific; a client can never receive server notices from any server except that to which it is directly connected. Servers MUST NOT send this mode when reporting client modes to other servers. The upper eight bits of the mode parameter are reserved for experimental and/or local use. All other bits are reserved for future expansion of the protocol and MUST NOT be used by any client or server. If any mode change in a mode change request is disallowed, the entire mode change request MUST be discarded. For example, if a (non-operator, non-invisible) client tries to set both UMODE_OPERATOR and UMODE_INVISIBLE in the same message, the server MUST discard the message without changing any modes, even though the UMODE_INVISIBLE flag by itself would have been permitted. Note that this message may be generated by the server in response to other types of messages as well (in particular, it is generated in response to an operator message; see section 3.4.5 below). Examples: CS: 0x0303 0x00800004 0x00800006 0xFFFFFFFF A client requests that it receive all types of server notices as well as operator messages, and disables the UMODE_INVISIBLE mode. SC: 0x0303 0x00800004 0x00800006 0xFFFFFFFF The server replies, showing the client's new modes. CS: 0x0303 The client requests its current modes. SC: 0x0303 0x00800005 0xFFFFFFFF 0xFFFFFFFF The server informs the client of its current modes. Note that the UMODE_OPERATOR flag is set here, while it was not set in the previous message from the server (because it was not changed by the client's client mode message). CS: 0x0303 0x00000000 0x00000001 The client gives up IRC operator status. SC: 0x0303 0x00000000 0x00800001 The server replies. Note that the server has unset the UMODE_SERVER_NOTICES mode as well as the UMODE_OPERATOR mode. Replies: ERR_PERMISSION_DENIED 3.4.5 Operator message Code: 0x0304 Parameters: password (string), [nickname (string)] Requests that the client be given IRC operator status. Depending on the value of the password parameter and other site-dependent parameters, the client's request may be accepted (in which case RPL_NOW_OPERATOR is sent) or denied (in which case ERR_PERMISSION_DENIED is sent). If the "nickname" parameter is given, the server MUST treat the request as if it had come from the given nickname (though the actual sender, not the named client, will receive operator privileges), and SHOULD allow the request even if another client has gained operator privileges under that nickname. (Consider the not-uncommon scenario in which an IRC operator's connection fails, and the operator reconnects to the server before the server recognizes that the earlier connection has been severed.) This message MUST NOT be forwarded; instead, a client mode message MUST be generated which sets the UMODE_OPERATOR flag and forwarded. The client mode message MUST also be sent to the client (in addition to RPL_NOW_OPERATOR). A server MAY set or unset additional client modes after a successful operator message; for example, a server might set the UMODE_OPER_MESSAGES and UMODE_SERVER_NOTICES flags. Examples: CS: 0x0304 "mypassword" A client requests IRC operator privileges with the password "mypassword". Replies: ERR_NEED_MORE_PARAMS RPL_NOW_OPERATOR ERR_NAME_TOO_LONG ERR_PERMISSION_DENIED 3.4.6 Kill message Code: 0x0305 Parameters: nickname (string), reason (string) Forcibly terminates a client's connection to the IRC network. The server to which the named client is connected MUST send the kill message to the client and then immediately terminate the connection upon receipt of the message. Non-operator clients MUST NOT be permitted to use this command. Examples: CS: 0x0305 "lamer" "Flooding is not permitted" Removes the client with nickname "lamer" from the network with the reason "Flooding is not permitted". Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG ERR_NO_SUCH_USER 3.4.7 Server ban message Code: 0x0306 (add), 0x0386 (remove) Parameters: username (string), hostname (string) Adds or removes a ban on clients connecting to the server which receives the message. The username and hostname given may contain wildcards. If a client connects and sends a user message with a username and hostname which match those of any ban, the client is rejected by the server. In the special case where the username is "*", which matches any string, the server MAY immediately close a connection whose source address matches the hostname mask without waiting for a registration message. Non-operator clients MUST NOT be permitted to use this command. This message MUST NOT be forwarded. Examples: CS: 0x0306 "lamer" "*.lame.com" Add a ban on any client connecting with the username "lamer" and a hostname ending in ".lame.com". Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED 3.4.8 Network ban message Code: 0x0307 (add), 0x0387 (remove) Parameters: username (string), hostname (string) Adds or removes a ban on clients connectiong to any server on the network. The username and hostname are interpreted as described for the server ban message in section 3.4.7 above. As with the server ban, a client who tries to register with a banned username and hostname will be rejected. If a server receives a user message from another server for a client whose username and hostname match such a ban, it MUST issue a kill message for that client, generate a network ban message from the banned username and hostname masks which the client matched, and forward that message to all servers. If the client matches multiple username/hostname masks, the server may choose any of the matching pairs. Non-operator clients MUST NOT be permitted to use this command. Examples: CS: 0x0306 "lamer" "*.lame.com" Add a ban on any client connecting to any server with the username "lamer" and a hostname ending in ".lame.com". Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED 3.5 Server control messages These messages allow IRC operators to control servers on the IRC network. Each of these messages can take an optional "dest-server" parameter; this is the name of a server on the IRC network to which the message is to be forwarded (if present and if the sender is an IRC operator, the server receiving the message from the client MUST forward it to the specified server and MUST NOT act on it). Other than the above, these messages MUST NOT be forwarded. The dest-server parameter for these messages, if supplied, MUST be a server name. Non-operator clients MUST NOT be permitted to use any of these functions. 3.5.1 Connect message Code: 0x0400 Parameters: server-to-connect (string), [dest-server (string)] This message is sent by an IRC operator to cause a server to attempt to establish a connection to the given "server-to-connect". If the dest-server parameter is given, the messages is forwarded to that server, which acts on it; otherwise, the server receiving the message from the client attempts to make the connection. The server-to-connect parameter SHOULD be a server name as given in the server registration message (section 3.1.3), but may be any arbitrary string which a server can use to identify another server and how to connect to it. The error ERR_ALREADY_CONNECTED is returned only when a direct connection exists between the server executing the command and the server named in the server-to-connect parameter. A server without such a connection MUST attempt to establish one even if the server-to-connect is already present on the network (i.e. by being connected to a different server). Examples: CS: 0x0400 "weyr.esper.net" A client instructs its server to connect to the server "weyr.esper.net". CS: 0x0400 "weyr.esper.net" "dragonfire.esper.net" A client instructs the server "dragonfire.esper.net" to connect to the server "weyr.esper.net". Replies: ERR_NEED_MORE_PARAMS ERR_ALREADY_CONNECTED ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.5.2 Disconnect message Code: 0x0401 Parameters: server-to-disconnect (string), [dest-server (string)] This message instructs a server to terminate the connection to another server. The dest-server parameter functions as with the connect message, described above. The server-to-disconnect parameter MUST be the name of a server; if the server is not on the network or is not directly connected to the server receiving and acting on the message, the error ERR_NO_SUCH_SERVER is returned. Examples: CS: 0x0401 "weyr.esper.net" A client instructs its server to disconnect the server named "weyr.esper.net". Replies: ERR_NEED_MORE_PARAMS ERR_NO_SUCH_SERVER ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.5.3 Rehash message Code: 0x0402 Parameters: [dest-server (string)] Instructs the dest-server or the server receiving the message to reread any configuration information. The implementation of this message is server-dependent; this message may not be applicable to all servers. This command MAY be unimplemented, or MAY be implemented for use by directly connected clients only. Replies: ERR_NOT_IMPLEMENTED ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.5.4 Restart message Code: 0x0403 Parameters: [dest-server (string)] Instructs the dest-server or the server receiving the message to restart itself. If implemented, the use of this command MUST terminate all connections to the server, clear all state information, and re-read any configuration information. This command MAY be unimplemented, or MAY be implemented for use by directly connected clients only. Replies: ERR_NOT_IMPLEMENTED ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.5.5 Die message Code: 0x0404 Parameters: [dest-server (string)] Instructs the dest-server or the server receiving the message to terminate. If implemented, receipt of this message MUST cause the server to terminate all connections and free all system resources it owns. This command MAY be unimplemented, or MAY be implemented for use by directly connected clients only. Replies: ERR_NOT_IMPLEMENTED ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.6 Query messages These messages return information about the state of a client, a server, or the IRC network as a whole. These messages MUST not be forwarded, except to the target server (where appropriate). 3.6.1 Who message Code: 0x0500 Parameters: who (string), [target-server (string)] nickname (string), status (bits-16), userhost (addr-string), name (string) bits-16 = shortint Requests information about the given "who". The string may contain wildcards. The string is matched against the nicknames, usernames, hostnames, server names, and currently joined channels for each client on the network, and any matches are returned in a message (one for each match) with the same message code and the following parameters: nickname: The nickname of the client. status: A 16-bit word with bits set as follows: Bit 3: 1 if the client has UMODE_INVISIBLE set (see section 3.4.4). Bit 2: 1 if the client is marked away (see section 3.4.2). Bit 1: 1 if the client is a channel operator on at least one channel. Bit 0: 1 if the client is an IRC operator. userhost: The address of the client in "user@host" format. name: The name provided by the client. The upper four bits of the status parameter are reserved for experimental and/or local use. All other bits are reserved for future expansion of the protocol and MUST NOT be used by any client or server. If there are no matches, nothing is returned by the server. Clients with UMODE_INVISIBLE set do not match any string (even one without wildcards) unless the sender is an IRC operator. Examples: CS: 0x0500 "achurch" A client requests information on any clients matching the string "achurch". SC: 0x0500 "Alcan" 0x0005 "achurch@achurch.org" "Andrew Church" The server replies with the author's client information. Replies: ERR_NEED_MORE_PARAMS 3.6.2 Names message Code: 0x0501 Parameters: channel (string), [target-server (string)] channel (string), nickname (string) ... Requests a list of clients in channels matching the given channel string, which may contain wildcards. For each channel matching the given string, a message is returned, with the first parameter set to the channel name and subsequent parameters set to the nicknames of the clients in the channel. If a particular client is a channel operator in the channel, the character "@" (ASCII 0x40) is prefixed to the nickname; if the client is not a channel operator but has been "given a voice" (see section 3.3.6), the character "+" (ASCII 0x2B) is prefixed. If the sending client is not in the channel, clients with UMODE_INVISIBLE set (see section 3.4.4) are not printed. Private channels (channels with CMODE_PRIVATE set; see section 3.3.3) are not returned unless the given string is an exact (case-insensitive) match for the channel name; secret channels are not returned unless the preceding condition is satisfied and the client is in the channel. Examples: CS: 0x0501 "#dragon*" A client requests a list of the clients in any channels matching the string "#dragon*". SC: 0x0501 "#dragonweyr" "@Alcan" The server returns a list of nicknames in channel "#dragonweyr", showing that Alcan is a channel operator in that channel. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG 3.6.3 List message Code: 0x0502 Parameters: channel (string), [target-server (string)] channel (string), clients (longint), topic (string) Requests information on any channels matching the given channel string, which may contain wildcards. The clients parameter is set to the total number of clients (including clients with UMODE_INVISIBLE set; see section 3.4.4) in the channel, and the topic parameter is set to the channel's current topic. Private channels (channels with CMODE_PRIVATE set; see section 3.3.3) are not listed unless the given string is an exact (case-insensitive) match for the channel name; secret channels are not listed unless the preceding condition is satisfied and the client is in the channel. Examples: SC: "#dragonweyr" 1 "Channel #dragonweyr's topic" A server replies to a list request for channel "#dragonweyr". Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG 3.6.4 Whois message Code: 0x0503 Parameters: nickname (string), [target-server (string)] nickname (string), userhost (string), name (string), servername (string), serverdesc (string), signon (timestamp), idle (longint), status (bits-16), [away (string)] Requests information on a particular client. The fields in the reply are as follows: nickname: Nickname of the client, as sent in the query. userhost: Address of the client, in "user@host" format. name: Name given by the client at registration time. servername: The name of the server the client is connected to. serverdesc: The description of the server the client is connected to. signon: Time in seconds since 1 January 1970 00:00 UTC when the client connected to its server. idle: Time in seconds since the client last send a public or private message (see sections 3.2.1 and 3.2.2). status: A 16-bit word with bits set as follows: Bit 1: 1 iff the client is marked away. Bit 0: 1 iff the client is an IRC operator. away: The client's away message (see section 3.4.2). Sent iff the client is marked away. The upper four bits of the status parameter are reserved for experimental and/or local use. All other bits are reserved for future expansion of the protocol and MUST NOT be used by any client or server. Examples: SC: 0x0503 "Alcan" "achurch@achurch.org" "Andrew Church" "dragonfire.esper.net" "Dragonfire's IRC server" 879185792 1234 0x0003 "not here" Replies: ERR_NEED_MORE_PARAMS ERR_NO_SUCH_USER ERR_NAME_TOO_LONG 3.6.5 Whowas message Code: 0x0504 Parameters: nickname, [target-server (string)] nickname (string), userhost (string), name (string), servername (string), signoff (timestamp) Requests information on previous users of a nickname. One reply is returned for each user, starting from the most recent. The number of replies returned is implementation-dependent; however, if a server does not return any information, it MUST send ERR_WAS_NO_SUCH_USER. The values of the parameters in the reply are: nickname: Nickname of the client, as sent in the query. userhost: Address of the client, in "user@host" format. name: Name given by the client at registration time. servername: The name of the server the client was connected to. signoff: Time in seconds since 1 January 1970 00:00 UTC when the client disconnected from its server. This command MAY be unimplemented. Examples: SC: 0x0504 "Alcan" "achurch@achurch.org" "Andrew Church" "dragonfire.esper.net" 879085832 The server sends information about a previous instance of the author's client. Replies: ERR_NOT_IMPLEMENTED ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_WAS_NO_SUCH_USER 3.6.6 Ison message Code: 0x0505 Parameters: [nickname (string) ...] This message, when sent by the client, requests a reply from the server indicating which of the nicknames given is currently connected to the IRC network. The server sends back the a message with the same message code and a parameter list containing only those nicknames originally specified which are currently connected to the network (which may be an empty list). This message MUST be parsed by the client's server and MUST NOT be forwarded to any other server. Note that an ERR_NAME_TOO_LONG reply MUST NOT be generated by this message even if a nickname given in the list is longer than the allowable length. Examples: CS: 0x0505 "xhdslas" "Alcan" A client asks whether any of the nicknames "xhdslas" and "Alcan" are currently online. SC: 0x0505 "Alcan" The server replies that the nickname "Alcan" is currently online (and it can thus be deduced that the nickname "xhdslas" is not currently online). Replies: None. 3.6.7 Users message Code: 0x0506 Parameters: [server (string)] clients (longint), channels (shortint), servers (shortint), my-clients (shortint), my-servers (shortint) Requests information on the number of clients connected to the IRC network and the client's server. If the server parameter is given, the message is forwarded to that server, which replies from its point of view. The server MUST send a users message back to the client with the following numeric information: clients : Number of clients connected to the network. channels : Number of channels existing on the network. servers : Number of servers connected to the network. my-clients: Number of clients connected to the responding server. my-servers: Number of servers connected to the responding server. In addition, the server MUST send one or more RPL_USERS replies to the client. A server MAY send a single RPL_USERS with no descriptive string, or MAY send one or more RPL_USERS replies with descriptive strings included; in the latter case, the server SHOULD include in the reply strings all information included in the numeric response, and MAY include any other information considered relevant. If an interactive client receives a reply without a descriptive string, it SHOULD display the information received from the server in an appropriate format; otherwise, it SHOULD display only the text included in the RPL_USERS replies and use the numeric responses for updating internal information only. This command MAY be unimplemented. Examples: CS: 0x0506 A client requests information on the number of clients connected to the network. Replies: ERR_NOT_IMPLEMENTED RPL_USERS ERR_NAME_TOO_LONG 3.6.8 Message of the Day message Code: 0x0507 Parameters: [server (string)] Requests the "Message of the Day" from the client's server or the specified server. The text of this message is server-dependent; the server MAY either send a single RPL_MOTD reply with the entire text or split the text into multiple RPL_MOTD replies. In either case, the server MUST send an RPL_MOTD_END reply after the last RPL_MOTD reply. All RPL_MOTD replies to this message MUST include strings. Examples: CS: 0x0507 A client requests the Message of the Day from the server to which it is connected. CS: 0x0507 "dragonfire.esper.net" A client requests the Message of the Day from the server "dragonfire.esper.net". Replies: ERR_NAME_TOO_LONG RPL_MOTD RPL_MOTD_END 3.6.9 Administrative information message Code: 0x0508 Parameters: [server (string)] Requests administrative information from the client's server or the specified server. The server MUST respond with at least one RPL_ADMININFO reply, though it MAY send more. All replies to this message MUST include appropriate descriptive strings. The format of the reply is implementation- and server-dependent. Examples: See section 3.6.8. Replies: ERR_NAME_TOO_LONG RPL_ADMININFO 3.6.10 Server information message Code: 0x0509 Parameters: [server (string)] Requests information about the client's server or the specified server. The server MUST respond with at least one RPL_SERVERINFO reply, though it MAY send more. All replies to this message MUST include appropriate descriptive strings. The format of the reply is implementation- and server-dependent. Examples: See section 3.6.8. Replies: ERR_NAME_TOO_LONG RPL_SERVERINFO 3.6.11 Server version message Code: 0x050A Parameters: [server (string)] Requests version information for the client's server or the specified server. The server MUST respond with exactly one RPL_SERVERVERSION reply, which MUST include an appropriate descriptive string. The reply string MUST begin with a version number or identifier followed by a space character (ASCII 0x20); the format of the version number and the remainder of the reply string is implementation- and server-dependent, with the exception that the version number or identifier MUST NOT include the space character. Examples: See section 3.6.8. Replies: ERR_NAME_TOO_LONG RPL_SERVERVERSION 3.6.12 Statistics message Code: 0x050B Parameters: type (byte), [server (string)] byte = octet Requests server statistics of the given type from the client's server or the named server. The low 8 bits of the reply code sent MUST be equal to the type value. All replies to this message MUST include appropriate descriptive strings, with the exception that servers MUST send a reply with no string after processing a request to signal the end of information. A server MUST generate ERR_BAD_STATS_TYPE_* (with the low 8 bits of the reply code equal to the type value) if it is not prepared to handle a given type request. Servers MAY limit all or some type requests to operators only. Servers MAY generate ERR_BAD_STATS_TYPE_* instead of ERR_PERMISSION_DENIED when denying a particular request type, but SHOULD generate ERR_PERMISSION_DENIED if all requests are denied to unprivileged users. For the purpose of this protocol, the meaning of the type parameter and the format of the replies are implementation- and server-dependent. However, the following values of "type" are recommended by this document; all implementations SHOULD support these types when possible, to provide a common set of statistics requests. For implementations supporting these requests as described, replies are defined to have the following format: * All items listed MUST be sent in the order listed, MUST separated by a single space character (ASCII 0x20), and MUST NOT contain the space character except as described. * Any reply MAY contain additional information after the required information, but such additional information MUST be preceded by the space character. * The format of remote addresses in statistics information is implementation- and server-dependent, but addresses MUST NOT contain the comma character (ASCII 0x2C). * All numeric values MUST be represented as decimal values using the characters "0" through "9" (ASCII 0x30 through 0x39), except where otherwise specified; hexadecimal values MUST be represented using the characters "0" through "9" and "A" through "F" (ASCII 0x30 through 0x39 and 0x41 through 0x46). * For requests on connection restrictions and bans, rules MUST be listed in the order in which they are applied. 0x61: Network ban information Requests a list of active network bans, including: * Remote address to which the ban applies. * Username to which the ban applies (possibly including wildcards). * Nickname to which the ban applies (possibly including wildcards). * Timestamp at which the ban expires, or "0" if the ban does not expire. 0x63: Server connection information Requests a list of what servers the server will attempt to connect to or allow to connect, including: * The character "B" for a border server or "S" for a regular server. * Server name. * Comma-separated list of remote addresses to which this server will attempt to connect upon receiving a connect message for the given server. * Comma-separated list of remote addresses from which this server will allow the given server to register itself. * The character "*" if a password is required for connection, "-" otherwise. 0x69: Client connection restrictions Requests a list of restrictions upon client connections, including: * Comma-separated list of remote addresses to which this rule applies. * The character "*" if a client matching the rule is required to enter a password, "-" otherwise. 0x6B: Server ban information Requests a list of active server bans, including: * Remote address to which the ban applies. * Username to which the ban applies (possibly including wildcards). * Nickname to which the ban applies (possibly including wildcards). * Absolute time at which the ban expires, or "0" if the ban does not expire. 0x6C: Active connection statistics Requests information on all active connections, including: * The character "B" if the connection is a border server, "S" if it is a regular server, "C" if it is a client. * Remote address. * Total number of octets sent. * Total number of messages sent. * Total number of octets received. * Total number of messages received. * Absolute time at which the connection was established. 0x6D: Message statistics Requests usage information for each message code supported by the server, including: * Message code, represented as a 4-digit hexadecimal number. * Number of times the message has been received. * Total number of octets included in all received instances of the message. Servers MAY omit message codes which have never been received. 0x6F: Operator restrictions Requests information on restrictions on clients becoming IRC operators, including: * Remote addresses from which the client may become an operator. * Username under which the client may become an operator (possibly including wildcards). * Nickname under which the client may become an operator (possibly including wildcards). 0x75: Server uptime Requests information on how long the server has been active, as well as the maximum number of connections reached, including: * Number of seconds since the server was started. * Maximum number of connections. * Number of clients connected when the maximum number of connectoins was first reached. Examples: CS: 0x050B 0x75 A client requests statistics of type 0x75 from the server to which it is connected. Replies: ERR_NEED_MORE_PARAMS RPL_STATS_* ERR_NAME_TOO_LONG ERR_PERMISSION_DENIED ERR_BAD_STATS_TYPE_* 3.6.13 Links message Code: 0x050C (servers only), 0x058C (all connections) Parameters: [server (string)] Requests information on active connections for the client's server or the specified server. If the sender is an IRC operator or another server and the message code is 0x058C, information on all connections is sent; otherwise, only information on server connections is sent. The server MUST send one RPL_LINKS reply for each active connection, and MAY send zero or more RPL_LINKS_EXTRA replies for additional information; any RPL_LINKS_EXTRA replies for a connection MUST be sent immediately after the RPL_LINKS reply for that connection and before any other replies are sent. All replies to this message MUST include appropriate descriptive strings. RPL_LINKS replies MUST contain the following information in the order given, with all items separated by a single space character (ASCII 0x20). Numeric items MUST be sent using the characters "0" through "9" (ASCII 0x30 through 0x39). Items MUST NOT contain the space character unless explicitly permitted in the description of the item. One character representing the connection type: "S" for a server on the same network, "B" for a border server of another network, "O" for an IRC operator, "C" for a non-IRC-operator client, or "?" for a connection which has not yet registered. Servers MAY send other characters to indicate special types of connections, and MAY use the space character. The timestamp when the connection was established. The timestamp when data was most recently received from the remote end of the connection. The number of octets of data which have been scheduled to be sent to the remote host but have not yet been passed to the transport layer (i.e. write buffer length). The number of octets of data which have been received from the remote host but not yet processed by the server (i.e. read buffer length). The raw address of the remote host (dotted-quad format, e.g. 123.45.67.89, for IPv4). The hostname as determined by the server (which may be the same as the raw address; see section 6.2). The username iff the connection is a client. Any other information considered relevant. This item MAY include the space character. The format of the RPL_LINKS_EXTRA replies are implementation- and server-dependent. Servers MAY limit the use of this command to IRC operators, or MAY limit the information returned to non-operator clients. Examples: See section 3.6.8. Replies: ERR_NAME_TOO_LONG RPL_LINKS ERR_PERMISSION_DENIED RPL_LINKS_EXTRA 3.6.14 Trace message Code: 0x050D (server), 0x058D (client) Parameters: target (string) Requests information on the route through the IRC network to a particular target (which may be a client nickname or a server name). Any server receiving this message MUST send a RPL_TRACE reply with an appropriate descriptive string back to the source. Furthermore, a server receiving a trace message with a target of a client connected to that server MUST send a RPL_TRACE reply on that client's behalf. Servers MUST NOT send trace messages to clients. The format of the replies are implementation- and server-dependent. Servers MAY limit the use of this command to IRC operators. Examples: CS: 0x058D "dragonfire.esper.net" A client requests information on the route to the server "dragonfire.esper.net". Replies: ERR_NEED_MORE_PARAMS RPL_TRACE ERR_NAME_TOO_LONG ERR_PERMISSION_DENIED 3.6.15 Time message Code: 0x050E Parameters: [server (string)] Requests the server's current time. The server MUST send a RPL_TIME reply with a descriptive string containing only the server's idea of the current time expressed as a timestamp, represented in decimal using the characters "0" through "9" (ASCII 0x30 through 0x39). Examples: See section 3.6.8. Replies: RPL_TIME 3.7 Miscellaneous messages These messages do not fit easily into any other category. 3.7.1 Ping message Code: 0x7FFE Parameters: [text (string), [target-server (string)]] The ping message is designed to test the integrity of a client or server connection. A client or server which receives a ping message MUST reply by sending a pong message (see section 3.7.2) to the sender as soon as possible. If the optional text parameter is included in the ping message, an identical text parameter MUST be sent with the corresponding pong message. The ping message can be sent by clients as well as servers. If sent by a client, the optional target-server parameter specifies that the message should not be interpreted by the client's server itself, but should be sent to the named server. Only servers can be pinged by clients in this fashion; servers MUST NOT send (or forward) ping messages to clients which are not directly connected to them. Clients may implement a protocol on top of the IRC protocol, using the standard message and notice commands (section 3.2), to allow a client to ping another client (CTCP [8] is an example of such a protocol). Examples: SC: 0x7FFE A server tests whether a client's link is active. CS: 0x7FFE "879150517" "dragonfire.esper.net" A client sends a ping message with the text "879150517" to the server "dragonfire.esper.net". A message such as this one, with a timestamp in the text parameter (the timestamp could just as easily be in binary), can be used to test the round-trip delay between a client and a server. Replies: ERR_NO_SUCH_SERVER 3.7.2 Pong message Code: 0x7FFF Parameters: [text (string)] Sent in reply to a ping message (see section 3.7.1). Servers and clients MUST NOT generate any messages or replies upon receiving a pong message, with the exception that a server MAY generate server notices (see section 3.2.4) indicating the status of a particular link. Examples: CS: 0x7FFF A client responds to a ping message sent by its server. Replies: None. 3.8 Reserved message codes To allow for testing and implementation of features specific to a single IRC network or potential additions to the IRC protocol, one-half of the message code space is allocated for custom use. Specifically, all message codes in the range 0x8000-0xFFFF (i.e. those with bit 15 set) are reserved for this purpose. All other command codes not listed in this section are reserved for future expansion of the IRC protocol. Clients and servers MUST NOT generate any such messages, and MUST discard any such message received. 3.9 Erroneous messages There are two types of erroneous messages: syntactically invalid messages and functionally invalid messages. Syntactically invalid messages are those which do not conform to the definitions in this protocol; these include messages with undefined message codes, messages with insufficient numbers of parameters, and messages containing names (for clients, channels, servers, or networks) with either invalid characters or too many characters. Error messages corresponding to these conditions are listed in section 4.2.1. Of the syntactic errors, the only one whose generation is not mandatory is ERR_NAME_TOO_LONG. In the case of a name which is longer than the maximum allowable length, a server MAY send this reply, or MAY continue processing the message normally (with or without truncation of the offending name). All other syntactic errors MUST be generated as soon as the corresponding condition occurs, and the server generating the error MUST discard the message. Functional errors are much more numerous, and which messages can generate which errors varies from message to message. There is, however, one functional error which can be generated by nearly all messages: ERR_NOT_REGISTERED. If a client sends any message other than the password message before sending a registration message, the server receiving the message MUST discard it and generate an ERR_NOT_REGISTERED reply. 3.10 Use of experimental message codes In an effort to preserve compatibility between clients and servers which utilize experimental message codes, the following guidelines are provided regarding the use of such message codes. If an implementor wishes to modify or enhance a message described in this document, s/he has two options: 1) Add functionality to the processing of the message to support the modification or enhancement. 2) Utilize an experimental message code (see section 3.8) to support the modification or enhancement, and leave the original message processing as is. In case 1, the implementor may add, remove, or rearrange parameters for the experimental version of the message; the server can then determine, based either on the number of parameters provided or on some earlier agreement with the remote client or server to use the experimental format, whether to process the message using the implementor's new method or the method defined in this document. For example, an implementor may add a parameter to the user registration messages specifying a homepage URL for the client; a client aware of the new functionality can provide the extra parameter, while an unaware client which does not provide the parameter will have its message processed according to this document. In case 2, the implementor defines a new message code for each modified message, and alters its behavior depending on whether the original or new message code is used. When possible, implementors SHOULD select new message code numbers by adding 8000 hexadecimal (i.e. by setting bit 15) to an existing message number; for example, a modified user message (section 3.1.2) would have code 8001 hexadecimal. In this case, a client which sends an experimental message code and receives an ERR_UNKNOWN_COMMAND response MUST resend the message according to the protocol defined in this document when possible. Since there are no message ID numbers associated with messages to or from clients, the client needs to make a "best guess" as to which message caused a particular error response. Implementors MUST ensure that, regardless of any modifications or enhancements made to this protocol, the messages specified in this section function exactly as described when used in the manner described. For example, a server with a modified user registration message as described in the example for case 1 above MUST ensure that a client which sends a user registration message according to the specification given in this document has that message processed as specified in this document. 4. REPLIES This section lists all reply codes and their names and meanings. (The names are intended merely as mnemonics, and do not necessarily need to be included in an IRC implementation.) 4.1 Command responses These replies are sent when a command completes successfully. All responses have bit 15 clear. Note that in many cases, the successful completion of a command will generate one or more new messages, and thus no reply is needed for those cases. 0x0000 RPL_WELCOME Sent to acknowledge a successful client registration request. 0x0001 RPL_WELCOME2 This reply may be sent zero, one, or multiple times to (for example) provide the client with information about the server. 0x0080 RPL_SERVER_WELCOME Sent to acknowledge a successful server registration request. 0x00C0 RPL_BSERVER_WELCOME Sent to acknowledge a successful remote (border) server registration request. 0x0100 RPL_NOW_OPERATOR Sent to acknowledge a successful client request to be given IRC operator status. 0x0110 RPL_MARKED_AWAY Sent to acknowledge that a client has been marked away. 0x0111 RPL_MARKED_UNAWAY Sent to acknowledge that a client is no longer marked away. 0x0120 RPL_SILENCE_ADD Sent to confirm addition of a mask to the client's silence list. 0x0121 RPL_SILENCE_DEL Sent to confirm deletion of a mask ÷½ the client's silence list. 0x0200 RPL_USERS Sent in response to a users message (see section 3.6.7). 0x0210 RPL_MOTD 0x0211 RPL_MOTD_END Sent in response to a Message of the Day request (see section 3.6.8). 0x0220 RPL_ADMININFO Sent in response to an administrative information request (see section 3.6.9). 0x0230 RPL_SERVERINFO Sent in response to a server information request (see section 3.6.10). 0x0240 RPL_SERVERVERSION Sent in response to a server version request (see section 3.6.11). 0x0250 RPL_LINKS 0x0251 RPL_LINKS_EXTRA Sent in response to a links request (see section 3.6.13). 0x0260 RPL_TRACE Sent in response to a trace request (see section 3.6.14). 0x0300 RPL_STATS_00 through 0x03FF RPL_STATS_FF Sent in response to statistics requests (see section 3.6.12). 4.2 Error messages Error messages can be divided into two categories: syntactical errors and functional errors. The former indicate errors in the format of the message; the latter indicate failure to carry out an otherwise valid command. All error codes have bit 15 set; all functional error codes also have bit 14 set, while syntactical error codes have bit 14 clear. 4.2.1 Syntactical errors 0x8000 ERR_UNKNOWN_COMMAND A command was received that was not understood. 0x8001 ERR_NEED_MORE_PARAMS Required parameters for the given command were missing. 0x8002 ERR_TOO_MANY_PARAMS More parameters were provided for the given command than were expected. 0x8100 ERR_INVALID_NAME A name (nickname, channel name, server name) that included invalid characters was given in a message. 0x8101 ERR_NAME_TOO_LONG A name (nickname, channel name, server name, or network name) given in a message was longer than the maximum allowed length. 4.2.2 Functional errors 0xC000 ERR_ALREADY_REGISTERED A connection may only be registered once; if a second registration command is sent over an already-registered connection, this error is returned. 0xC001 ERR_NOT_REGISTERED Other than the password message (see section 3.1.1), the first message sent across a connection must be a registration message. Any other message causes this error. 0xC002 ERR_BAD_PASSWORD An entity attempted to register a connection but failed to supply the correct password. 0xC003 ERR_NICKNAME_IN_USE A client tried to register with or change to a nickname which was already being used by another client. 0xC040 ERR_WRONG_VERSION The version number sent in a registration message was not accepted. 0xC080 ERR_ALREADY_CONNECTED A connect message was issued for a server-server link which already exists. 0xC081 ERR_NOT_SERVER A client tried to issue a message that is limited to servers. 0xC100 ERR_NO_SUCH_CHANNEL The target channel given for a channel-based command does not exist. 0xC101 ERR_NO_SUCH_USER The target nickname given for a command does not exist. 0xC102 ERR_NOT_IN_CHANNEL A client tried to send a part message for a channel or make changes (mode, etc.) to a channel without being in that channel. 0xC103 ERR_WAS_NO_SUCH_USER A client requested "whowas" information for a nickname (see section 3.6.5), but the server did not have any information on previous users of the nickname. 0xC103 ERR_ALREADY_IN_CHANNEL A client in a channel tried to join that channel again. 0xC180 ERR_NO_SUCH_SERVER A named server does not exist. 0xC200 ERR_PERMISSION_DENIED A client without sufficient privileges tried to execute a privileged command. (For example, a non-privileged client tried to send a kill message, or a non-channel operator tried to send an invite message.) 0xC201 ERR_CLIENT_DENIED A client sent a user message (see section 3.1.2) which was rejected by the server. 0xC210 ERR_CANNOT_SEND A message cannot be sent to its target. 0xC211 ERR_CANNOT_JOIN A join message was disallowed. 0xC212 ERR_CANNOT_CHANGE_DIST_LOCAL A client tried to change the distributed/local channel mode (see section 3.3.3) when there were other clients in the channel. 0xC213 ERR_CANNOT_CHANGE_LOCKED A client tried to change channel modes while the CMODE_LOCKED mode (see section 3.3.3) was set. 0xC280 ERR_SERVER_DENIED A server registration message (see section 3.1.3) was sent which was rejected by the receiving server. 0xC281 ERR_NETWORK_DENIED A remote server registration message (see section 3.1.4) was sent which was rejected by the receiving server. 0xC300 ERR_BAD_STATS_TYPE_00 through 0xC3FF ERR_BAD_STATS_TYPE_FF Sent in response to statistics requests (see section 3.6.12) when the server cannot handle the requested type. 0xDFFE ERR_INTERNAL_ERROR An internal error prevented the server from carrying out a function. 0xDFFF ERR_NOT_IMPLEMENTED A message was received which was understood but was not implemented. 4.3 Reserved reply codes To allow for testing and implementation of features specific to a single IRC network or potential additions to the IRC protocol, one-half of the reply code space is allocated for custom use. Specifically, all reply codes with bit 13 set, i.e. 0x2000-0x3FFF, 0x6000-0x7FFF, 0xA000-0xBFFF, and 0xE000-0xFFFF, are reserved for this purpose. All other reply codes not listed in this section are reserved for future expansion of the IRC protocol, and servers MUST NOT generate any such replies. 5. PROBLEMS AND LIMITATIONS There are a number of recognized problems and limitations of this protocol, some carrying over from the earlier IRC protocol. 5.1 Scalability Within the network context, this protocol, like the old protocol, scales poorly due to the requirement that all servers maintain state information for the entire network. As more clients and servers join a network, the load on every server will increase, degrading communications between servers and ultimately between clients. While the use of a single "state server" was considered as an alternative to the current approach, it was deemed unacceptable, since a failure of either the state server itself or its connection to the rest of the network would render the entire network nonfunctional. Instead, a set of commands was added to the protocol to allow a server from one network to communicate with a server from another network while keeping the two networks distinct. In this model, servers are only required to maintain information about the network of which they are a part, and networks can remain relatively small while allowing communication with other entities outside of the network. The inter-network communications protocol introduces a scalability problem of its own: namely, the fact that to allow N networks to communicate with each other, there must be O(N^2) connections between the networks. While a "relay" approach similar to the server relay method of sending messages within networks was considered, it was deemed not worth the additional effort required to implement such a second-level relay given the current sizes and numbers of networks. This may be re-evaluated in the future. 5.2 Name collisions Like the earlier IRC protocol, there exists the possibility of name collisions. These are caused by race conditions which are unavoidable due to the nature of IRC; for example, two clients may connect to two different servers at exactly the same time, and choose the same nickname, resulting in a nickname collision when the two messages' paths intersect. The following sections detail the procedures for resolving collisions of the different categories of names. 5.2.1 Nickname collisions If a server receives a client registration or nickname change message from another server, and the nickname for the new client matches the nickname of a client already present on the IRC network, the server receiving the colliding message MUST remove from its internal list of nicknames whichever has the more recent nickname change time (which is the time of connection registration if the client has not changed nicknames since then). If that client is directly connected to the server, then the server MUST terminate the connection with an appropriate quit message (see section 3.1.6). 5.2.2 Server name or ID collisions If a server receives a server registration message from another (already-connected) server, and either the name or the ID number (but not both) match those of another server present on the network, the server receiving the message MUST issue a server-quit message for the ID number(s) of both servers, thus removing both colliding servers from the network. However, servers SHOULD NOT issue a server-quit message for the forwarder of a colliding server message; doing so could easily cause more havoc than necessary. In the case of a malicious server intentionally issuing colliding server messages or a misconfigured server being abused for the same purpose, IRC operators can intervene and disconnect that server. 5.2.3 Channel collisions Channel collisions present something of a greater problem than do nickname and server collisions. Unlike those, a channel is not a single concrete entity; rather, it is an alias for a list of clients. There is no way to determine, in fact, whether a channel on a new server has collided with a channel on the network or whether clients on the new server just happened to join the channel immediately after the server connected to the network. Thus, channel collisions are treated inclusively. When a server receives a channel mode message or join message from another server, it MUST act on that message regardless of any other state information; for example, if a server sends a join message for a client which is banned from the channel on another server, the second server must allow the client to join despite the ban. One possible consequence of this collision resolution method is that a malicious user could take advantage of data transmission delay between servers to set a channel's modes such that the channel's ordinary users would be unable to use the channel. To avoid this situation, server implementors may want to consider allowing users with IRC operator privileges (or some other local privilege level) to circumvent channel mode and ban restrictions, or including support for a special "network service" server which would have the ability to change channel modes on request by sufficiently privileged users (Services for IRC Networks [9], originally developed by the author of this document, is an example of such a "network service" server). 5.3 Timekeeping Because parts of this protocol -- in particular, the collision resolution methods described above -- depend on knowing the time at which an event happened, and because timestamps may be generated by different servers, it is important that the servers' clocks be as closely synchronized as possible. A server with a clock which differs significantly from those of other servers may cause unexpected results if collisions occur. Therefore, servers SHOULD use a method such as the Network Time Protocol [10] to keep their clocks synchronized. 5.4 Connection desynchronization Since there is no specific marker for the end of a message, a communication error can cause complete desynchronization of a connection. If, for example, noise on a network link resulted in a series of "1" bits being sent in the length field of a client's message, the server would then attempt to read 4,294,967,295 bytes of data, which in all likelihood would not be sent before the server dropped the connection due to a ping timeout (see section 3.7.1). For this reason, servers SHOULD use a reliable transport protocol (such as TCP [5]) to minimize the possibility of desynchronization. (Also, see section 5.5 below for additional reasons for the use of a reliable transport protocol.) 5.5 Cyclic networks While the introduction of cycles into IRC networks increases their reliability, it also adds some complexity to the process of message passing. In the non-cyclic tree structure of networks under the old IRC protocol, it was sufficient for a server forwarding a message to simply send the message to all directly-connected servers other than the one from which it received the message; the non-cyclic nature of the network guaranteed that each server would receive the message exactly once. However, in a cyclic network, this approach would result in a message being sent endlessly in circles. To avoid this problem, two methods are used, as described in section 2.2.2: sequence numbers and a hop list. While sequence numbers are sufficient to prevent messages from being processed more than once by any given server, a hop list is also used to reduce network traffic at the expense of additional computation, since the former is seen as the more severe bottleneck. (This may be reevaluated in the future.) When a server generates a server-to-server message, it inserts its next sequence number in the message. Servers receiving a message check that the received sequence number is greater than the last sequence number seen from the originating server (modulo 2**32), and discard messages that do not meet this test as duplicates. Note that the sequence numbers generated by one server as seen from the viewpoint of another server are guaranteed only to be strictly increasing, not to be monotonically increasing. Some messages (in particular, messages to channels or clients on other servers) will not be sent to all servers, so some servers will see "gaps" in sequence numbers between messages. As described in section 2.2.2, this algorithm will only function properly in an environment where data is guaranteed to be received in the same order it was sent. For this reason, servers MUST use a reliable transport protocol which preserves order, such as TCP [5], or explicitly implement such a protocol on top of an existing transport protocol. *** FIXME: This breaks when servers create redundant connections. Take the following simple network: A----B----C Suppose both the A<->B and B<->C links are very slow, but that a direct connection between A and C would be much faster. If A sends a message with ID 1 destined for server C, it will first go to B and from there to C. But suppose that right after sending that message, A connects to C and sends another message to it, with ID 2. C could receive message 2 first, and when it later receives message 1 from B, it will inappropriately discard it. This problem could be mitigated by inserting a "delay" before making use of any new routes, but this is only a kludge, not a solution. One solution might be to have the server actually sending the message (i.e. forwarders too, not just originators) set the message sequence number field to its own next sequence number. This would appear to solve the problem, but could still result in desynchs from one message overtaking another. To resolve this would seem to require sending a copy of the entire state over the new connection, despite the fact that the remote server already has that information. Another possibility is to have a server P, when connecting to another server Q, to check whether Q is already in the network, and to send Q's last seen sequence number in the server registration message if so. Q will then send to P any messages it has not yet seen. The sequence number processing will filter out the duplicates. However, this breaks when many servers are involved. Suppose a server D is connected to C in the network above; how do we ensure that D's messages arrive in order? Does solving this problem require sending information on _every_ server's last seen sequence number? Note that we can't just rely on waiting for the last sequence number plus one (or some other calculable number), like we do with TCP sequence numbers, because not all messages go to all servers. We could supposedly have individual sequence numbers for every connection to every server, but then we still have the problem where C sees message 2 before message 1, and C can't know that B still has something to send it. Maybe this needs a completely different tack? When a server sends a message (whether generated or forwarded) to another server, it inserts itself at the head of the server hop list in the message. Servers never forward messages to servers already on the hop list. This prevents the sending of duplicate messages to servers which have already seen it and would just discard the duplicate anyway. 6. SECURITY CONSIDERATIONS 6.1 IP spoofing A fairly well-known method of network attack, called spoofing, involves sending data from one host and making it appear to be from another, usually more trusted, host. In order to decrease the likelihood of success of a spoofing attack on IRC, which could be used (for example) to gain increased channel access from automated clients or to attack the reputation of another user, servers SHOULD send a ping message (see section 3.7.1) immediately upon registration of a connection, including in the message one parameter containing a randomly generated series of octets. A server implementing this procedure MUST discard all messages from the remote end of the connection without processing them until either the remote end replies with a pong message containing the same string or the ping timeout period expires. A server MAY reduce the timeout period for this ping message. An example client/server dialog using this procedure: (commands are given by their names in angle brackets) Client: "secretpass" Client: "Alcan" "achurch" "Andrew Church" Server: 0x419FC82D834960017D2A9AB540FF1683E7 Client: 0x419FC82D834960017D2A9AB540FF1683E7 (regular commands and replies follow) 6.2 DNS spoofing Another way in which malicious users may try to exploit trust systems is DNS spoofing, i.e. altering DNS records to make one host appear to have the name of another host. While spoofers may be able to just as easily modify both the forward and reverse lookup records, thus hiding any trace of their activity, the following procedure will catch at least those who can only alter one of the records; all servers SHOULD follow this procedure when determining the hostname of a remote connection. Upon receiving a connection, the server looks up the name assigned to the remote address. Assuming that lookup succeeds, the server then looks up the address associated with the name it found. If the second lookup fails or its result does not contain the actual address of the remote host, the server MUST use the remote host's raw address (dotted-quad format for IPv4, e.g. 123.45.67.89) for the remote hostname. Servers SHOULD NOT close the connection on a lookup failure or mismatch, because there are some legitimate hosts which have a mismatched IP address and DNS name (likely due to errors on the part of the administrators for those IP ranges or domains). However, servers SHOULD generate some sort of warning for such an occurrance (for example, via a server message (section 3.2.4)). 6.3 Network sniffing Since this protocol does not include any capability for encrypting data in transit, all data sent and received by servers and clients-- including connection passwords--is vulnerable to network sniffing. For this reason, networks may wish to investigate external encryption methods, such as encrypted IP tunnels. 6.4 Timekeeping and timestamp overflows Section 5.3 discusses the necessity of maintaining synchronized clocks among all servers on a network; a server with an incorrect clock may, among other things, allow users to deliberately disconnect other users or improperly take over control of channels. Furthermore, it is important that implementors be aware of the possibility of timestamp overflows; no matter what time system is used, there are only a finite number of instants of time representable by a timestamp, and if that range is exceeded, unpredictable results similar to the case of a server with an incorrect clock will result. Therefore, implementors SHOULD take appropriate steps to reduce the likelihood of an overflow and/or handle the case of an overflow specially. As a concrete example, implementors using the C language and the "time_t" type defined on Unix (and other) systems should be aware that in many cases the "time_t" type is a 32-bit signed integer, and will overflow in January 2038; such implementors SHOULD explicitly use a 64-bit integer type (or, when such a type is not available, two 32-bit integers) rather than the predefined "time_t" type for handling timestamps. 7. AUTHOR'S ADDRESS Andrew Church 3716 Hayes Manor Lane Olney, MD 20832 USA E-mail: achurch@achurch.org 8. REFERENCES AND NOTES [1] Oikarinen, J. and Reed, D., "Internet Relay Chat Protocol", RFC 1459, May, 1993. [2] Arnold, S., "IRCII 1/2 proposal", http://www.the-project.org/proposals/stevenpaper.html [3] See, for example, the timestamp protocol implemented in many current servers, such as that used on the DALnet (http://www.dal.net/) and UnderNet (http://www.undernet.org/) networks, but not present in the reference implementation or in the protocol definition--note that the exact timestamp protocol also varies (incompatibly) between servers. [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March, 1997. [5] Postel, J., "Transmission Control Protocol", RFC 793, September, 1981. [6] Crocker, D., "Standard for the Format of ARPA Internet Text Messages", RFC 822, August, 1982. [7] St. Johns, M., "Identification Protocol", RFC 1413, February, 1993. [8] *** FIXME: Does anyone know of a good CTCP reference? [9] http://achurch.org/services/ [10] Mills, David L., "Network Time Protocol (Version 3)", RFC 1305, March, 1992. 9. Copyright notice This document is copyright (c) 1999 Andrew Church. This document may be freely distributed as-is, and may be excerpted as-is provided that the excerpt includes an attribution to the author. This document may be modified, but modified versions may not be distributed unless this notice remains intact and an additional notice is included stating that the document has been modified and where the original document may be obtained. Appendix A. Dijkstra's algorithm Dijkstra's algorithm is an algorithm for finding the shortest path from one node in a graph to one or all others. It involves keeping a table of parents (the "parent" of a node is defined to be the previous node on the shortest path to the node from the starting node), path lengths (the length of a path is simply the sum of the weights of all edges on the path), and "finished" flags, indicating whether the shortest path to the node has been definitively determined. Initially, the path length to all nodes is set to positive infinity (or as close as the chosen numeric format will allow), except for the starting node, which has a path length of 0. The "finished" flag for all nodes, including the starting node, is set to false. While there is at least one node whose "finished" flag is false, choose the unfinished node N with the smallest cost (if there are multiple such nodes, choose any one of them). Set N's "finished" flag to true; then, for all unfinished nodes Q adjacent to N, set Q's path length to the path length of N plus the weight of the edge (N,Q) iff that length is shorter than the current path length for Q. If the goal is to find the shortest path to a single node, the algorithm stops when that node's "finished" flag becomes true. Appendix B. Alphabetical list of message and reply elements addr-octet = addr-string = length * "@" * addr-unichar = addr-unistring = length * "@" * bits-16 = shortint bits-32 = longint byte = octet cli-serv-msg = code [network] * ;message from client to server client-message = flag length32 (cli-serv-msg / serv-cli-msg) clientid = shortint code = shortint dest = [network] serverid clientid flag = shortint hop-count = shortint ;number of servers in hop-list hop-list = hop-count *32767 length = length16 / length32 ;chosen as appropriate length16 = <16-bit count of octets in the remainder of the object which the rule describes> length32 = longint = <32-bit integer> network = string ;destination network octet = parameter = string reply = flag length code sendername [string] sendername = string ;sender's nick / servername senderaddr = addr-string | addr-unistring ;sender's user@host address serv-cli-msg = code [network] sendername [senderaddr] * ;message from server to client seqnum = longint server-message = flag length32 seqnum hop-list code source dest [time] * serverid = shortint shortint = <16-bit integer> source = [network] serverid clientid string = string16 / string32 string16 = length16 *32767 string32 = length32 *2147483647 timestamp = <64-bit integer> user-string = length * Appendix C. List of requirements and recommendations Requirements (MUST, MUST NOT) are prefixed with "REQ:"; recommendations (SHOULD, SHOULD NOT) are prefixed with "REC:". Additionally, the section number in which each requirement or recommendation is stated is given in parentheses after the requirement or recommendation itself. C.1 Basic client and server requirements REQ: Both clients and servers MUST be capable of sending and receiving arbitrary data octets. (1.3) REQ: Servers MUST use the protocol defined in this document for transmitting data to other servers compatible with this protocol. (1.3) REQ: Servers MUST communicate with a remote client or server using the same protocol it registered with. (1.3) REC: Servers SHOULD recognize both the old and current protocols. (1.3) REQ: Servers MUST use a transport protocol that guarantees in-order delivery of data, or explicitly implement such a protocol on top of an existing transport protocol. (2.2.2, 5.5) REC: Servers SHOULD use some method to keep their clocks synchronized. (5.3) REC: Servers SHOULD use a reliable transport protocol to minimize the possibility of desynchronization. (5.4) C.2 Names and identifiers REQ: Server names MUST be no more than 63 characters in length. (1.1) REQ: Server names MUST NOT contain the character with value zero (ASCII NUL). (1.1) REC: Server names SHOULD NOT contain the space (" ", ASCII 0x20) or comma (",", ASCII 0x2C) characters, or begin with the "#" or "&" characters. (1.1) REQ: Servers MUST NOT use the identifier 65,535 (hexadecimal FFFF) when registering. (1.1) REQ: Servers MUST reject a server registration message which uses the identifier 65,535 (hexadecimal FFFF). (1.1) REQ: Client names MUST be no more than 31 characters in length. (1.2) REQ: Client names MUST NOT contain the character with value zero (ASCII NUL). (1.2) REC: Client names SHOULD NOT contain the space (" ", ASCII 0x20) or comma (",", ASCII 0x2C) characters, or begin with the "#" or "&" characters. (1.2) REQ: Servers MUST NOT assign the ID 65,535 (hexadecimal FFFF) to any client. (1.2) REQ: Channel names MUST be no more than 63 characters in length. (1.4) REQ: Channel names MUST NOT contain the character with value zero (ASCII NUL). (1.4) REC: Channel names SHOULD NOT contain the space (" ", ASCII 0x20) or comma (",", ASCII 0x2C) characters, or begin with the "#" or "&" characters. (1.2) REQ: When communicating with a client or server using the old protocol, servers MUST prepend either "#" or "&" to the name of a distributed or local channel, respectively, whenever the name appears in a message. (1.4) C.3 Privilege levels REQ: Normal (unprivileged) users MUST NOT be able to execute any functions which require IRC operator privileges in this protocol description. (1.2) REQ: Normal (unprivileged) users MUST NOT be able to execute any functions which require channel operator privileges in this protocol description. C.4 Unicode support REQ: A server or client which is capable of receiving and processing Unicode strings MUST set the "Unicode support" flag in all messages. (1.5) REQ: A server or client which includes Unicode strings in a message MUST set the "Unicode" flag in that message. (1.5) REQ: Servers and clients MUST NOT include both Unicode and non-Unicode strings in the same message. (!.5) REC: A server with Unicode support which has the ability to generate and send text messages SHOULD include support for sending the same text messages in the preferred non-Unicode encoding for the language used. (1.5) REQ: Any implementation that uses Unicode MUST translate all characters referred to in this document into their Unicode equivalents rather than using the hexadecimal octet values given. (1.5) C.5 Message generation, transmission and receipt REQ: If the length of a string is greater than 32,767 octets, a 32-bit length MUST be used to represent the string length. (2.1) REC: If the length of a string is less than 32,768 octets, a 16-bit length SHOULD be used to represent the string length. (2.1) REQ: Bit 15 of the flag parameter MUST be set to zero when sending a message. (2.2) REQ: The Unicode support flag (bit 13 of the flag parameter) MUST be set in any message sent by a client or server which supports Unicode. (2.2) REQ: The Unicode flag (bit 12 of the flag parameter) MUST be set in any message which contains Unicode strings. (2.2) REQ: The network field MUST be included wherever allowed if and only if bit 5 of the flag parameter is set for a message. (2.2) REQ: All flag bits not defined by this protocol MUST be set to zero when sending a message. (2.2) REQ: Clients MUST NOT include a sender field when generating a message. (2.2.1) REQ: If the address is included in a sender field, bit 11 of the flag parameter MUST be set. (2.2.1) REQ: The address part of a sender field MUST be in Unicode iff the Unicode flag is set. (2.2.1) REQ: The address part of a sender field MUST be sent on all client join, leave, and quit messages which are broadcast to other clients. (2.2.1) REQ: Servers MUST include a timestamp for the user registration and nickname change messages. (2.2.2, 3.1.2) REQ: Bit 8 of the flag parameter MUST be set if a timestamp is included in the message. (2.2.2) REC: Servers SHOULD NOT include descriptive strings when sending replies to other servers. (2.2.3) REQ: Every server on a network MUST use the same method for computing link weights for shortest-path determination. (1.6.1) REQ: When sending a message to another server, the sender MUST append its server ID to the path field of the message. (1.6.1) REQ: A server MUST NOT send a message to a server which is listed in the message's path field. (1.6.1) REQ: Servers which precalculate the shortest path to every other server on the network MUST update their tables whenever a server is added to or removed from the network. (1.6.1) REQ: Both clients and servers MUST send exactly the number of octets they specify in the length parameter. REQ: A server receiving a message with its own ID in the path field MUST discard the message. (1.6.1) REQ: If the first octet of a supposed message does not have the decimal value 253, the client or server MUST discard the octet as belonging to a previous message. (2.2) REQ: If a client receives a server message or a server receives a server message from a client or a client message from a server, it MUST discard that message. (2.2) REQ: Both clients and servers MUST read exactly the number of octets given by the length parameter, regardless of the validity of the message. (2.2) REQ: When discarding a message, if the remote client or server is not immediately disconnected, the receiver MUST read the number of bytes specified in the length parameter from the input stream before beginning to process the next message. (2.2) REQ: When discarding a message, if the length parameter has not been completely received, the remote client or server MUST be disconnected. (2.2) REQ: If the length given for a parameter would exceed the length of the message, the server or client receiving the message MUST truncate the parameter when the message's length is reached and, in the case of a server, MUST send an ERR_NEED_MORE_PARAMS reply and discard the message if there are fewer parameters than expected. (2.2.1) REQ: Clients MUST accept any length string in the sender address field. (2.2.1) REQ: For server messages, if the signed 32-bit difference (message sequence number) - (source's last seen sequence number) is less than or equal to zero, the server MUST discard the message. (2.2.2) REQ: If a server receives a reply from a client, it MUST ignore the reply. (2.2.3) REQ: If a server receives a string in a reply, it MUST pass that string along unmodified. (2.2.3) REC: Clients SHOULD display a default description if one is not sent with the reply. (2.2.3) REQ: All servers on a network MUST assign the same meaning to the value of a timestamp. (2.4) REQ: Timestamps, when sent in binary format, MUST be sent using 64 bits. (2.4) REQ: Clients and servers MUST be prepared to properly handle any timestamp value, including values outside the range of a 32-bit integer. (2.4) REQ: Clients which process decimal time values MUST be prepared to handle values outside the range of a 32-bit integer. (2.4) C.6 Messages REQ: All of the messages listed in section 3 MUST be implemented by all servers with exactly the behavior listed. (3) REQ: If a server encounters a fatal error while parsing a message, it MUST immediately stop parsing that message and return an error reply to the source of the message. (3) REQ: If a server successfully parses a message, it MUST act on all of the parameters, sending appropriate replies for each. REQ: In any message including a target, the message MUST be sent to that target as described under section 1.5 unless otherwise noted. (3) REQ: All connection registration/cancellation messages MUST be forwarded, except for password and remote server messages, which MUST NOT be forwarded. (3.1) REQ: If a password message is sent, it MUST be sent before the connection registration message. (3.1.1) REQ: Implementors which add or modify features of this protocol MUST choose a new version-id value in the range 0x8000-0xFFFF for their revised protocol. (3.1.2) REQ: If the nickname given by a client in a user registration message or nick message is already in use, the server MUST return ERR_NICKNAME_IN_USE and ignore (not forward) the message. (3.1.2, 3.4.1) REQ: A server MUST reject an attempted registration with ERR_WRONG_VERSION if it is not prepared to support the version supplied. (3.1.3) REQ: Servers compliant with this protocol MUST accept connections which supply the value 0x0100 in the version-id field. REQ: Upon successful registration of a server, both the registering server and the server to which it connected MUST send all state information. (3.1.3) REQ: Servers MUST NOT send state information to remote networks. (3.1.4) REC: Servers SHOULD forcibly close a client connection in only the following cases: a ping timeout, a kill message, a nickname collision, and an operating system error which prevents the server from reading data from the client's connection. (3.1.6) REQ: A server which forcibly closes a client's connection MUST generate a quit message on the client's behalf, it MUST include a "reason" describing why the connection was closed, and it MUST send that quit message to the client whose connection is being closed (if possible). (3.1.6) REQ: Any server receiving a quit message, whether from a directly-connected client or from another server, MUST send that message to all clients connected to it who are on any channel the quitting client was on. (3.1.6) REQ: Upon receipt of a server quit message, if any now-unreachable clients were on channels that any clients local to the receiving server are also on, then the server MUST generate and send quit messages on their behalf. REC: The "reason" in quit messages resulting from a server quit message SHOULD be of the form "server1 server2", where server1 and server2 are the servers at either end of the severed connection: server1 is the server which is still on the IRC network, and server2 is the server which is no longer on the network. (3.1.7) REQ: When a server forcibly disconnects a remote server, it MUST generate and send a server quit message to the server whose connection is being closed, and MUST include an explanation of why the connection is being closed. REQ: A client or server which receives a notice MUST NOT generate any other messages (including server error messages) in response to the notice. (3.2.3) REC: Status messages relevant to the entire network SHOULD be sent as operator messages. (3.2.4) REQ: Server notices MUST be ignored when received from a client. (3.2.4) REC: For events local to a single server, servers SHOULD use server notices for reporting. (3.2.5) REQ: All channel messages MUST be forwarded except as noted, and MUST be sent by each server to all clients connected to that server on the channel sent in the message. (3.3) REQ: Failed join messages MUST NOT be forwarded. (3.3.1) REQ: When broadcasting join messages to clients in joined channel(s), the server MUST send a separate join message for each channel using message code 0x0200, and MUST NOT include any key used in the original join message. (3.3.1) REC: Upon joining, the server SHOULD send to the client the channel topic, current channel modes, and a list of all clients on the channel. (3.3.1) REQ: When broadcasting a part message to clients in the parted channel(s), the server MUST use message code 0x0281, and MUST send an empty string for the "reason" parameter if one was not given in the original message. (3.3.2) REQ: If a client which does not have channel operator privileges attempts to change channel modes, the server MUST reply with ERR_PERMISSION_DENIED and discard the message without processing it. (3.3.3) REQ: A server receiving an otherwise valid channel mode message requesting a change of the CMODE_LOCAL flag when more than one client is in the channel MUST return ERR_CANNOT_CHANGE_DIST_LOCAL and discard the message. (3.3.3) REQ: If a client without IRC operator privileges attempts to change channel modes on a channel which has the CMODE_LOCKED flag set, the server MUST return ERR_CANNOT_CHANGE_LOCKED and discard the entire message. (3.3.3) REQ: All channel mode bits not defined in this protocol are reserved for future expansion and MUST NOT be used by any client or server. (3.3.3) REQ: If any mode change in a mode change request is disallowed, the entire mode change request MUST be discarded. (3.3.3) REQ: A server MUST NOT permit topic changes by unprivileged clients not in the channel, and MUST NOT permit topic changes by unprivileged clients in the channel iff the CMODE_TOPIC_OPS flag is set. (3.3.4) REQ: The sender of a channel operator, channel voice, kick, channel ban add, channel ban remove, or invite message MUST be a channel operator. (3.3.5, 3.3.6, 3.3.7, 3.3.8) REQ: For the channel ban list message, the server MUST send exactly one ban per response message. (3.3.8) REQ: For the channel ban add and remove messages, at least one string MUST be given. (3.3.8) REQ: Client control messages MUST be forwarded except as specified. (3.4) REQ: A client receiving a nick message for itself MUST change its nickname to that specified in the message. (3.4.1) REQ: A server generating a nick message for a client MUST forward the message to all other servers. (3.4.1) REQ: Any client which sends a private message to a client marked away MUST be sent an away message with the sender field set to the nickname of the client to which the message was sent. (3.4.2) REQ: Servers MUST NOT discard any messages sent to a client marked away. (3.4.2) REQ: If client B matches an entry on client A's silence list, then any private messages or notices from client B to client A MUST be discarded by both client B's server and client A's server, and any other type of message or notice sent by client B which client A would normally receive MUST NOT be sent to client A. (3.4.3) REQ: If a client attempts to set the UMODE_OPERATOR flag directly, the server MUST return ERR_PERMISSION_DENIED and discard the entire client mode message. (3.4.4) REQ: Normal clients MUST NOT receive operator messages regardless of the setting of the UMODE_OPER_MESSAGES mode. (3.4.4) REQ: In the parameter for the UMODE_SERVER_NOTICES mode, a "1" bit MUST indicate a request that messages of a particular type be sent, and a "0" bit MUST indicate that messages of that type should not be sent. (3.4.4) REC: Clients SHOULD default to sending a parameter for the UMODE_SERVER_NOTICES mode containing all bits set. (3.4.4) REQ: Servers which limit the UMODE_SREVER_NOTICES mode to IRC operators only MUST return ERR_PERMISSION_DENIED and discard the entire mode message if sent from a non-privileged client, and MUST unset the UMODE_SERVER_NOTICES mode whenever the UMODE_OPERATOR mode is unset. (3.4.4) REQ: Servers MUST NOT send the UMODE_SERVER_NOTICES mode when reporting client modes to other servers. (3.4.4) REQ: All user mode bits not defined in this protocol are reserved for future expansion and MUST NOT be used by any client or server. REQ: If any mode change in a mode change request is disallowed, the entire mode change request MUST be discarded. REQ: If the nickname parameter is included in an operator message, the server MUST treat the request as if it had come from the given nickname. (3.4.5) REC: Servers SHOULD allow operator messages with nickname parameters even if another client has gained operator privileges under the same nickname. (3.4.5) REQ: The operator message MUST NOT be forwarded; instead, a client mode message MUST be generated which sets the UMODE_OPERATOR flag and forwarded. The client mode message MUST also be sent to the client. (3.4.5) REQ: The server to which a client which is the target of a kill message is connected MUST send the kill message to the client and then immediately terminate the connection upon receipt of this message. REQ: Non-operator clients MUST NOT be permitted to use the kill, server ban, or network ban messages. (3.4.6, 3.4.7, 3.4.8) REQ: The server ban message MUST NOT be forwarded. REQ: If a server receives a user message from another server for a client whose username and hostname match a network ban, it MUST issue a kill message for that client, generate a network ban message from the banned username and hostname masks which the client matched, and forward that message to all servers. REQ: For server control messages, if a destination server is supplied and the sender is an IRC operator, the message MUST be forwarded to the destination server; otherwise, the message MUST NOT be forwarded. (3.5) REQ: The dest-server parameter for server control messages, if supplied, MUST be a server name. (3.5) REQ: Non-operator clients MUST NOT be permitted to use server control commands. (3.5) REC: The server-to-connect parameter for the connect message SHOULD be a server name as given in the server registration message. (3.5.1) REQ: Upon receiving a connect message, a server MUST attempt to establish a direct connection to the specified server if one does not already exist. (3.5.1) REQ: The server-to-disconnect parameter for the disconnect message MUST be the name of a server. (3.5.2) REQ: Upon receipt of a restart message, the server MUST terminate all connections to it, clear all state information, and re-read any configuration information. (3.5.4) REQ: Upon receipt of a die message, the server MUST terminate all connections to it and free all system resources it owns. (3.5.5) REQ: Query messages MUST NOT be forwarded, except to the target server (where appropriate). (3.6) REQ: All bits in the who message reply status not specified are reserved for future expansion and MUST NOT be used. (3.6.1) REQ: All bits in the whois message reply status not specified are reserved for future expansion and MUST NOT be used. (3.6.4) REQ: If a server does not return any information for a whowas message, it MUST send ERR_WAS_NO_SUCH_USER. (3.6.5) REQ: The ison message MUST be parsed by the client's server and MUST NOT be forwarded to any other server. (3.6.6) REQ: An ERR_NAME_TOO_LONG reply MUST NOT be generated by the ison message even if a nickname given in the list is longer than the allowable length. (3.6.6) REQ: The reply to the users message MUST include an appropriate descriptive string. (3.6.7) REQ: Servers MUST send an RPL_MOTD_END message after the last RPL_MOTD message sent in reply to a Message of the Day message. (3.6.8) REQ: All RPL_MOTD replies to a Message of the Day message MUST include strings. (3.6.8) REQ: Servers MUST respond to an administrative information message with at least one RPL_ADMININFO reply. (3.6.9) REQ: All replies to the administrative information message MUST include appropriate descriptive strings. (3.6.9) REQ: Servers MUST respond to a server information message with at least one RPL_SERVERINFO reply. (3.6.10) REQ: All replies to the server information message MUST include appropriate descriptive strings. (3.6.10) REQ: Servers MUST respond to the server version message with exactly one RPL_SERVERINFO reply, which MUST include an appropriate descriptive string. (3.6.11) REQ: The low 8 bits of the reply code sent for a statistics message MUST be equal to the type value. (3.6.12) REQ: All replies to the statistics message MUST include appropriate descriptive strings. (3.6.12) REQ: Servers MUST send one RPL_LINKS reply for each active connection in response to a links message. (3.6.13) REQ: All replies to the links message MUST include appropriate descriptive strings. (3.6.13) REQ: Any server receiving a trace message MUST send a RPL_TRACE reply with an appropriate descriptive string back to the source. (3.6.14) REQ: A server receiving a trace message with a target of a client connected to that server MUST send a RPL_TRACE reply on that client's behalf. (3.6.14) REQ: Servers MUST NOT send trace messages to clients. (3.6.14) REQ: A client or server which receives a ping message MUST reply by sending a pong message to the sender as soon as possible. (3.7.1) REQ: If the optional text parameter is included in the ping message, an identical text parameter MUST be sent with the corresponding pong message. (3.7.1) REQ: Servers MUST NOT send (or forward) ping messages to clients which are not directly connected to them. (3.7.1) REQ: Servers and clients MUST NOT generate any messages or replies upon receiving a pong message, with the exception that a server MAY geneate server noticecs indicating the status of a particular link. (3.7.2) REQ: Clients and servers MUST NOT generate messages with reserved command codes, and MUST discard any such message received. (3.8) REQ: All syntactic errors other than ERR_NAME_TOO_LONG MUST be generated as soon as the corresponding condition occurs, and the server generating the error MUST discard the message. REQ: If a client sends any message other than the password message before sending a registration message, the server receiving the message MUST discard it and generate an ERR_NOT_REGISTERED reply. (3.9) REQ: Implementors who create new messages SHOULD select new message numbers by adding 8000 hexadecimal to an existing message number. (3.10) REQ: A client which sends an experimental message code and receives an ERR_UNKNOWN_COMMAND response MUST resend the message according to the protocol defined in this document when possible. (3.10) REQ: Implementors MUST ensure that, regardless of any modifications or enhancements made to this protocol, the messages specified in section 3 function exactly as described when used in the manner described. C.7 Replies REQ: All reply codes not listed in section 4 are reserved for future expansion of the IRC protocol, and servers MUST NOT generate any such replies. (4.3) C.8 Collisions REQ: If a server receives a client registration or nickname change message from another server, and the nickname for the new client matches the nickname of a client already present on the IRC network, the server receiving the colliding message MUST remove from its internal list of nicknames whichever has the more recent nickname change time. If that client is directly connected to the server, then the server MUST terminate the connection with an appropriate quit message. (5.2.1) REQ: If a server receives a server registration message from another (already-connected) server, and either the name or the ID number (but not both) match those of another server present on the network, the server receiving the message MUST issue a server-quit message for the ID number(s) of both servers. (5.2.2) REC: Servers SHOULD NOT issue a server-quit message for the forwarder of a colliding server message. (5.2.2) REQ: When a server receives a channel mode message or join message from another server, it MUST act on that message regardless of any other state information. C.9 Other requirements REC: Servers SHOULD NOT use the Ident Protocol for any purpose directly related to the implementation of this protocol, including but not limited to access control decisions. (3.1.2.1) REC: Servers SHOULD send a ping message immediately upon registration of a connection, including in the message one parameter containing a randomly generated series of octets. (6.1) REQ: Servers which implement the anti-IP-spoofing method described in section 6.1 MUST discard all messages from the remote end of the connection without processing them until either the remote end replies with a pong message containing the same string or the ping timeout period expires. (6.1) REC: Servers SHOULD follow the procedure described in section 6.2 for determining the hostname of a remote connection. (6.2) REQ: Servers using the procedure described in section 6.2 MUST use the remote host's raw address for the remote hostname. (6.2) REC: Servers SHOULD NOT close the connection on a lookup failure or mismatch, but SHOULD generate some sort of warning for such an occurrance. (6.2) Appendix D. Conversion table for the RFC 1459 protocol This table lists the commands defined in RFC 1459 and their equivalent message codes in the protocol defined by this document, and is intended as a guide to implementors who wish to include support for RFC 1459 clients. Commands are listed in alphabetical order. Note that there is not a one-to-one correspondence between commands; some commands from RFC 1459 have different message codes depending on the circumstances of use, and others have no equivalent. Also note that even for commands which have a direct equivalent, the semantics of the command in the new protocol may be different from the semantics defined for the command in RFC 1459, and that many IRC servers have defined their own semantics for some of these commands. See the notes at the bottom of the table and the message definitions in this document for details on how to translate messages. | RFC 1459 | | | | Command | New Command | Notes | +----------+----------------+-------+ | ADMIN | 0x0508 | | | AWAY | 0x0301 | | | CONNECT | 0x0400 | | | DIE | 0x0404 | | | ERROR | (none) | | | INFO | 0x0509 | | | INVITE | 0x0208 | | | ISON | 0x0505 | | | JOIN | 0x0200,0x0280 | E | | KICK | 0x0206 | | | KILL | 0x0305 | | | LINKS | 0x050C,0x058C | | | LIST | 0x0502 | | | LUSERS | 0x0506 | | | MODE | 0x0303,0x0202, | C | | | 0x0204,0x0284, | | | | 0x0205,0x0285, | | | | 0x0207,0x0247, | | | | 0x0287 | | | MOTD | 0x0507 | | | NAMES | 0x0501 | | | NICK | 0x0300 | A | | NOTICE | 0x0102,0x0103, | D | | | 0x0104,0x0106 | | | OPER | 0x0304 | | | PART | 0x0201 | | | PASS | 0x0000 | | | PING | 0x7FFE | | | PONG | 0x7FFF | | | PRIVMSG | 0x0100,0x0101, | D | | | 0x0104,0x0106 | | | QUIT | 0x0004 | | | REHASH | 0x0402 | | | RESTART | 0x0403 | | | SERVER | 0x0002 | | | SQUIT | 0x0005,0x0401 | | | STATS | 0x050B | | | SUMMON | (none) | | | TIME | 0x050E | | | TOPIC | 0x0203 | | | TRACE | 0x050D | | | USER | 0x0001 | B | | USERS | (none) | | | VERSION | 0x050A | | | WALLOPS | 0x0105 | | | WHO | 0x0500 | | | WHOIS | 0x0503 | | | WHOWAS | 0x0504 | | *E: JOIN 0 (leave all channels) is not supported. *C: MODE command summary: 0x0303 = MODE for a client 0x0202 = MODE for a channel (except o/v/b) 0x0204,0x0284 = MODE +o/-o for a channel 0x0205,0x0285 = MODE +v/-v for a channel 0x0207,0x0247,0x0287 = MODE +b/-b for a channel (0x0247=list) *A: For the NICK command used to change a client's nickname. When used at registration time, there is no equivalent; see the USER command. *D: Keep in mind that the new protocol distinguishes between messages/notices to a channel (public) and messages/notices to a client (private). *B: When registering, the nickname (formerly from the NICK command) is included in the user registration message.