Network Working Group A. Church Request For Comments: nnnn September, 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 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.7 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 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. The timestamp value is the number of seconds since 1 January 1970, 00:00 UTC (Universal Coordinated Time, or Greenwich Mean Time); this is the same as the Unix time(2) value. In augmented BNF, the server message format is as follows: server-message = flag length seqnum hop-list code source dest [time] * 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 time = longint ;seconds since 1970/1/1 0:00 UTC 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. 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. 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 (longint) 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. All servers MUST assign the same meaning to this time value; servers SHOULD use the current Unix standard (seconds since 1 January 1970 0:00 GMT), to reduce difficulties for clients in determining what timestamp system is in use. 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 (time), 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 (time) 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). * Absolute time values MUST be given as the number of seconds since 1 January 1970, 00:00 UTC. * 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). * Absolute time 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 information on message use, 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 messages 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 time (in seconds since 1 January 1970 00:00 UTC) when the connection was acknowledged by the server. The time (in seconds since 1 January 1970 00:00 UTC) 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 the number of seconds since 1 January 1970, 00:00 UTC, 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 i