From 70f1558a2eca8295e30bb1e381d948056333634d Mon Sep 17 00:00:00 2001 From: michael Date: Sat, 27 Oct 2012 21:02:32 +0000 Subject: - Second time's the charm? Moving svnroot/ircd-hybrid-8 to svnroot/ircd-hybrid/trunk git-svn-id: svn://svn.ircd-hybrid.org/svnroot/ircd-hybrid/trunk@1592 82007160-df01-0410-b94d-b575c5fd34c7 --- .../draft-mitchell-irc-capabilities-01.txt | 1298 ++++++++ doc/technical/event.txt | 82 + doc/technical/fd-management.txt | 47 + doc/technical/hostmask.txt | 136 + doc/technical/index.txt | 16 + doc/technical/network.txt | 99 + doc/technical/rfc1459.txt | 3110 ++++++++++++++++++++ doc/technical/rfc2812.txt | 2916 ++++++++++++++++++ doc/technical/rfc2813.txt | 1173 ++++++++ doc/technical/send.txt | 262 ++ doc/technical/ts3.txt | 321 ++ doc/technical/ts5.txt | 147 + doc/technical/ts6.txt | 267 ++ 13 files changed, 9874 insertions(+) create mode 100644 doc/technical/draft-mitchell-irc-capabilities-01.txt create mode 100644 doc/technical/event.txt create mode 100644 doc/technical/fd-management.txt create mode 100644 doc/technical/hostmask.txt create mode 100644 doc/technical/index.txt create mode 100644 doc/technical/network.txt create mode 100644 doc/technical/rfc1459.txt create mode 100644 doc/technical/rfc2812.txt create mode 100644 doc/technical/rfc2813.txt create mode 100644 doc/technical/send.txt create mode 100644 doc/technical/ts3.txt create mode 100644 doc/technical/ts5.txt create mode 100644 doc/technical/ts6.txt (limited to 'doc/technical') diff --git a/doc/technical/draft-mitchell-irc-capabilities-01.txt b/doc/technical/draft-mitchell-irc-capabilities-01.txt new file mode 100644 index 0000000..f0c6736 --- /dev/null +++ b/doc/technical/draft-mitchell-irc-capabilities-01.txt @@ -0,0 +1,1298 @@ + +Network Working Group K. Mitchell +Internet-Draft P. Lorier +Expires: September 5, 2005 Undernet IRC Network + L. Hardy + ircd-ratbox + P. Kucharski + IRCnet + March 7, 2005 + + IRC Client Capabilities Extension + draft-mitchell-irc-capabilities-01 + +Status of this Memo + + This document is an Internet-Draft and is subject to all provisions + of section 3 of RFC 3667. By submitting this Internet-Draft, each + author represents that any applicable patent or other IPR claims of + which he or she is aware have been or will be disclosed, and any of + which he or she become aware will be disclosed, in accordance with + RFC 3668. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as + Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft will expire on September 5, 2005. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + IRC (Internet Relay Chat) is a long-standing protocol for real-time + chatting. The basic client-server protocol is a very simple + text-based protocol with no explicit mechanism for introducing or + + +Mitchell, et al. Expires September 5, 2005 [Page 1] +Internet-Draft IRC CAP March 2005 + + negotiating backwards-incompatible extensions. This memo presents a + mechanism for negotiation of such extensions. + +Requirements Language + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in RFC + 2119 [1]. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + + 2. Problems to be Solved . . . . . . . . . . . . . . . . . . . . 4 + + 3. The CAP Command . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.1 CAP LS . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.2 CAP LIST . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.3 CAP REQ . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 3.4 CAP ACK . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 3.5 CAP NAK . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 3.6 CAP CLEAR . . . . . . . . . . . . . . . . . . . . . . . . 8 + 3.7 CAP END . . . . . . . . . . . . . . . . . . . . . . . . . 8 + + 4. Capability Negotiation . . . . . . . . . . . . . . . . . . . . 10 + + 5. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.1 Capability Modifiers . . . . . . . . . . . . . . . . . . . 11 + + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 + + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 + + 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 + + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 + + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 15 + + A. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 + + B. ABNF Description of Capabilities . . . . . . . . . . . . . . . 19 + + C. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + + Intellectual Property and Copyright Statements . . . . . . . . 28 + + +Mitchell, et al. Expires September 5, 2005 [Page 2] +Internet-Draft IRC CAP March 2005 + +1. Introduction + + The IRC protocol, as originally documented by RFC 1459 [2] and + updated by RFC 2812 [3], is a simple, text-based conferencing + protocol, involving a number of users spread across a number of + interconnected servers. These users may chat with other individual + users, or may chat with groups of users on "channels"--what other + chat systems refer to as "rooms" or "chat rooms". + + Over the years, various extensions to the basic IRC protocol have + been made by IRC server programmers. Often, these extensions are + intended to conserve bandwidth, close loopholes left by the original + protocol specification, or add features for users or for the server + administrators. Most of these changes are backwards-compatible with + the original protocol specification: A command may be added, a reply + may be extended to contain more parameters, etc. Recently, however, + there has been a desire to introduce changes that would not be + backwards-compatible with existing IRC clients. Ideally, these + protocol changes would only be used with clients and servers that can + understand the revised protocol. Unfortunately, the IRC protocol + does not provide any form of extension or protocol negotiation, + making it impossible to determine support for such extensions. + + This memo introduces a standardized mechanism for negotiation of + protocol extensions, known as *capabilities*, that will be + backwards-compatible with all existing IRC clients and servers. Any + server not implementing this extension will still interoperate with + clients that do implement it; similarly, clients that do not + implement the capabilities extension may successfully communicate + with a server that does implement the extension. + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 3] +Internet-Draft IRC CAP March 2005 + +2. Problems to be Solved + + The IRC protocol is not a lockstep protocol. This means that a + client may issue additional commands before the server has finished + responding to the first one. Additionally, unlike other protocols, + the server does not necessarily issue a banner response upon initial + connection. This, combined with the fact that some servers do not + complain about unknown commands prior to completion of the client + registration phase, means that a client cannot know for certain + whether a server implements the extension. If a client had to wait + for a banner message, it would fail to interoperate with a server not + implementing the capabilities extension. If the client must issue a + command and then wait for a response, a similar problem results. As + some potential protocol extensions must be set up prior to completion + of the client registration phase, there is no reliable way a server + may indicate implementation of the capabilities extension to a + client. + + The solution to these problems turns out to be to extend the client + registration procedure. The client sends a request to begin + capability negotiation, as well as the other information necessary + for client registration (user name, nick name, optional password, + etc.). If the server understands the capabilities extension, it will + suspend completion of the registration phase until the negotiation is + complete; negotiation may then proceed in a lockstep fashion. If the + server does not understand capabilities, then the registration will + complete immediately, and the client will receive the 001 numeric. + This will signal to the client that the server does not implement the + capabilities extension. + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 4] +Internet-Draft IRC CAP March 2005 + +3. The CAP Command + + The capabilities extension is implemented by addition of one command + with several subcommands. The command added is *CAP*. CAP takes a + single, required subcommand, optionally followed by a single + parameter consisting of a space-separated list of capabilities. Each + capability within the list MAY be preceded by a capability modifier. + (Section 5.1) + + The subcommands defined for CAP are: + + 1. LS (Section 3.1) + 2. LIST (Section 3.2) + 3. REQ (Section 3.3) + 4. ACK (Section 3.4) + 5. NAK (Section 3.5) + 6. CLEAR (Section 3.6) + 7. END (Section 3.7) + + The LS (Section 3.1), LIST (Section 3.2), REQ (Section 3.3), ACK + (Section 3.4), and NAK (Section 3.5) subcommands may be followed by a + single parameter consisting of a space-separated list of capability + names. If more than one capability is named, this argument MUST be + preceded by the IRC protocol colon (':') sentinel to signal that the + remainder of the line is a single argument. + + If a client sends a subcommand not listed above or issues an invalid + command, the server SHOULD reply with the ERR_INVALIDCAPCMD numeric + response, 410. The first parameter after the client nickname SHALL + be the subcommand the client sent; the second parameter SHOULD be a + textual description of the error. + + In ABNF [4] notation: + + capcmd = [ ":" servername SP ] "CAP" SP subcmd + + subcmd = lscmd / listcmd / reqcmd / ackcmd / + nakcmd / clearcmd / endcmd + + capcmderr = ":" servername SP "410" SP nick SP badcmd + SP ":Invalid CAP subcommand" + ; badcmd is the unrecognized subcommand + + caplist = [ ":" ] *( capmod ) capab + caplist =/ ":" *( capmod ) capab 1*( SP *( capmod ) capab ) + + where SP is as designated in Appendix A of RFC 2234 [4], and + servername and nick are as designated in section 2.3.1 of RFC 1459 + + +Mitchell, et al. Expires September 5, 2005 [Page 5] +Internet-Draft IRC CAP March 2005 + + [2]. + + The discussion in the following sections applies only to clients and + servers implementing the capabilities extension. Servers (and + clients) not implementing the capabilities extension are exempted + from the requirements of this section. + +3.1 CAP LS + + The LS subcommand is used to list the capabilities supported by the + server. The client SHALL send an LS subcommand with no arguments to + solicit a list of supported capabilities from the server. Servers + MUST respond to such LS subcommands with one or more LS subcommands + containing the list of recognized capabilities. All but the last + subcommand MUST have a parameter containing only an asterisk ('*') + preceding the capability list. + + If a client issues an LS subcommand during the client registration + phase, client registration MUST be suspended until an END (Section + 3.7) subcommand is received. + + ABNF [4] description of the LS subcommand: + + lscmd = "LS" + lscmd =/ "LS" SP [ "*" SP ] caplist + +3.2 CAP LIST + + The LIST subcommand is provided to permit the client to request a + list of the capabilities currently active for the connection. It is + similar to the LS (Section 3.1) subcommand--if a client issues a LIST + subcommand with no arguments, the server MUST respond with a sequence + of LIST subcommands, all but the last of which MUST have a single + parameter consisting solely of an asterisk ('*') preceding the list + of capabilities. If no capabilities have been enabled, the server + MUST send a LIST command with an empty capability list; the parameter + MUST NOT be omitted. The active capabilities MAY be listed in any + order. + + ABNF [4] description of the LIST subcommand: + + listcmd = "LIST" + listcmd =/ "LIST" SP ":" + listcmd =/ "LIST" SP [ "*" SP ] caplist + + + +Mitchell, et al. Expires September 5, 2005 [Page 6] +Internet-Draft IRC CAP March 2005 + +3.3 CAP REQ + + The REQ subcommand is sent by the client to request that a capability + or set of capabilities be enabled or disabled. Its sole parameter + MUST be a space-separated list of capabilities. Each capability name + MAY be preceded by a dash ('-') to indicate that the capability + should be disabled. Additionally, receipt of this subcommand during + the client registration MUST suspend client registration until an END + (Section 3.7) subcommand is received. + + Servers MUST respond to a REQ command with either the ACK (Section + 3.4) or NAK (Section 3.5) subcommands to indicate acceptance or + rejection of the capability set requested by the client. A server + MUST accept the entire capability set or reject it whole; servers + MUST NOT accept some capabilities in the set while rejecting others. + If a client requests that a "sticky" capability be disabled, the + server MUST reject the capability set. + + ABNF [4] description of the REQ subcommand: + + reqcmd = "REQ" SP caplist + +3.4 CAP ACK + + The ACK subcommand has three uses. It is used by the server to + acknowledge a REQ (Section 3.3) subcommand; by the server to + acknowledge a CLEAR (Section 3.6) subcommand and list the removed + capabilities; and by the client to acknowledge certain capabilities + designated as requiring acknowledgment. If more than one ACK is + required due to the IRC line length limitation of 512 characters, all + but the last SHALL contain a parameter consisting of a single + asterisk ('*') immediately preceding the list of capabilities, as for + LS (Section 3.1) and LIST (Section 3.2). + + If an ACK reply originating from the server is spread across multiple + lines, a client MUST NOT change capabilities until the last ACK of + the set is received. Equally, a server MUST NOT change the + capabilities of the client until the last ACK of the set has been + sent. + + In the first usage, acknowledging a REQ (Section 3.3) subcommand, the + ACK subcommand has a single parameter consisting of a space separated + list of capability names, which may optionally be preceded with one + or more modifiers (Section 5.1). + + The second usage, acknowledging a CLEAR (Section 3.6) subcommand, is + similar to the first usage. When a CLEAR (Section 3.6) subcommand is + + +Mitchell, et al. Expires September 5, 2005 [Page 7] +Internet-Draft IRC CAP March 2005 + + issued, all non-"sticky" capabilities are disabled, and a set of ACK + subcommands will be generated by the server with the disable modifier + preceding each capability. + + The third usage is when, in the preceding two cases, some capability + names have been preceded with the ack modifier. ACK in this case is + used to fully enable or disable the capability. Clients MUST NOT + issue an ACK subcommand for any capability not marked with the ack + modifier in a server-generated ACK subcommand. + + ABNF [4] description of the ACK subcommand: + + ackcmd = "ACK" SP [ "*" SP ] caplist + +3.5 CAP NAK + + The NAK subcommand MUST be sent by the server in response to a REQ + (Section 3.3) subcommand when any capability change requested cannot + be performed for any reason. The server MUST NOT make any change to + the set of capabilities for the client if it responds with a NAK + subcommand. The argument of the NAK subcommand MUST consist of at + least the first one hundred characters of the capability list in the + REQ (Section 3.3) subcommand which triggered the NAK. + + ABNF [4] description of the NAK subcommand: + + nakcmd = "NAK" SP ":" acklist + ; acklist is at least 100 characters of the + ; capability list from the REQ + +3.6 CAP CLEAR + + The CLEAR subcommand requests that the server clear the capability + set for the client. The server MUST respond with a set of ACK + (Section 3.4) subcommands indicating the capabilities being + deactivated. + + ABNF [4] description of the CLEAR subcommand: + + clearcmd = "CLEAR" + +3.7 CAP END + + The END subcommand signals to the server that capability negotiation + is complete and requests that the server continue with client + + +Mitchell, et al. Expires September 5, 2005 [Page 8] +Internet-Draft IRC CAP March 2005 + + registration. If the client is already registered, this command MUST + be ignored by the server. + + Clients that support capabilities but do not wish to enter + negotiation SHOULD send CAP END upon connection to the server. + + ABNF [4] description of the END subcommand: + + endcmd = "END" + + + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 9] +Internet-Draft IRC CAP March 2005 + +4. Capability Negotiation + + Clients implementing this extension SHOULD take one of the following + three actions upon initial connection to a server: + + o Issue an LS (Section 3.1) subcommand (with an empty capability + list) to solicit a list of supported capabilities from the server; + + o Issue the REQ (Section 3.3) subcommand to request a particular set + of capabilities without knowing what capabilities the server + supports or if it supports the capabilities extension; or + + o Issue the END (Section 3.7) subcommand to signal implementation of + the capabilities extension without entering into capability + negotiation. + + Although a client is permitted to not issue any CAP commands upon + connection, this is NOT RECOMMENDED. Servers MAY assume a client + does not implement the capabilities extension if it does not issue + any CAP commands upon initial connection. + + Clients SHOULD follow CAP commands issued upon connection with the + standard IRC client registration commands without waiting for any + responses from the server. See RFC 1459 [2] for more details about + the client registration procedure. + + If a client issues the LS (Section 3.1) or REQ (Section 3.3) + subcommands during the client registration procedure, a server + implementing the capabilities extension MUST NOT complete the client + registration until the client issues the END (Section 3.7) + subcommand. A client that sees a RPL_WELCOME (001) numeric response + before it sends CAP END (Section 3.7) SHOULD assume that the server + does not support the capabilities extension. + + Once the client is registered, CAP commands SHALL have no effect on + other connection operations, except that a client MAY change the + capabilities it has set. In particular, CAP commands and their + responses MAY be interspersed with other protocol messages. The END + (Section 3.7) subcommand SHALL have no effect once client + registration has been completed. + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 10] +Internet-Draft IRC CAP March 2005 + +5. Capabilities + + Capabilities are designated by a name composed of one or more + elements. Name elements are not case-sensitive. They must begin + with a letter and may contain any number of letters, numbers, and the + dash character ('-'). Names containing more than one name element + MUST also contain a period character ('.') in the first name element. + Name elements are separated from each other via the slash character + ('/'). + + There are two capability name spaces: + + Network Specific: Names whose first element contains a period + character ('.') designate a delegated capability name space. The + first element MUST be a valid, existing DNS domain name. These + names MUST contain at least two elements. + + Standardized: All other names MUST correspond to capabilities + documented by an RFC. Further, these names MUST contain only one + element. + + These rules are summarized by the following ABNF [4] representation: + + elem = ALPHA *( ALPHA / DIGIT / "-" ) + + netname = elem 1*( "." elem ) + + netDeleg = netname 1*( "/" elem ) + + standardized = elem + + capab = netDeleg / standardized + + where ALPHA and DIGIT are as designated in Appendix A of RFC 2234 + [4]. + +5.1 Capability Modifiers + + There are various capability modifiers available. If a capability + modifier is to be used, it MUST directly precede the capability name. + The following are the modifiers defined for capabilities. Certain + modifiers MAY be combined. + + The disable modifier is used by both the server and the client to + indicate that a capability should be disabled. The disable modifier + is defined as the dash character ('-'). A client MUST only use the + disable modifier in the REQ (Section 3.3) and ACK (Section 3.4) + subcommands. A server MUST use the disable modifier in the ACK + + +Mitchell, et al. Expires September 5, 2005 [Page 11] +Internet-Draft IRC CAP March 2005 + + (Section 3.4) subcommand when disabling a capability, or in + conjunction with a ack modifier in the LIST (Section 3.2) subcommand. + The server MUST NOT use the disable modifier in any other command + response. + + The sticky modifier is used by the server to indicate a capability + that, once enabled, cannot be disabled. The sticky modifier is + defined as the equals character ('='). A client MUST NOT use the + sticky modifier. A server MUST only use the sticky modifier in the + ACK (Section 3.4), LIST (Section 3.2) and LS (Section 3.1) + subcommands and MUST use the modifier for all such capabilities. + + The ack modifier is used by the server to indicate that the client + must issue an ACK (Section 3.4) subcommand to fully enable or disable + the capability. The ack modifier is defined as the tilde character + ('~'). The ack modifier indicates that traffic originating from the + server SHALL make use of the capability, but the server SHALL NOT + expect traffic originating from the client to make use of the + capability. When combined with the disable modifier, it indicates + traffic originating from the server SHALL NOT make use of the + capability, but the server expects traffic originating from the + client SHALL make use of the capability. The ack modifier MAY be + combined with the sticky modifier. + + A server MUST use the ack modifier in the ACK (Section 3.4) and LIST + (Section 3.2) subcommands to indicate capabilities that require an + ACK (Section 3.4) subcommand from the client to be fully enabled or + disabled. Servers MUST also use the ack modifier in the response to + an LS (Section 3.1) subcommand to indicate capabilities which will + require ACK (Section 3.4) subcommands from the client. Clients MUST + NOT use the ack modifier, but SHOULD issue the ACK (Section 3.4) + subcommand as soon as possible after receiving an ACK (Section 3.4) + or REQ (Section 3.3) subcommand from the server that contains a + capability marked with the ack modifier. + + In ABNF [4] notation: + + dismod = "-" + stickymod = "=" + ackmod = "~" + + capmod = dismod / stickymod / ackmod + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 12] +Internet-Draft IRC CAP March 2005 + +6. IANA Considerations + + The standardized capability name space shall be managed by IANA in + accordance with the description of capability names in Section 5. In + particular, any name not containing the period character ('.') must + be specified by an RFC. + + + + + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 13] +Internet-Draft IRC CAP March 2005 + +7. Security Considerations + + Capabilities are an extension to a preexisting, insecure chat + protocol. This extension does not add and does not purport to add + any security to the IRC protocol. Capability negotiation occurs + after client registration has already begun. Moreover, no mechanism + is defined that allows parameters to be passed for specific + capabilities. Although such a mechanism could be added, + cryptographic security systems frequently require several exchanges + to establish a secure context, particularly if authentication must + also be negotiated. Thus, the capabilities extension is unsuited to + the implementation of those protocols, and other mechanisms, such as + SSL-encapsulated IRC, should be used. + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 14] +Internet-Draft IRC CAP March 2005 + +8. Acknowledgments + + The authors wish to gratefully acknowledge the participation of Aaron + Wiebe and the members of the proto-desc@dal.net email list in the + design of this protocol extension. + +9 References + + [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [2] Oikarinen, J. and D. Reed, "Internet Relay Chat Protocol", RFC + 1459, May 1993. + + [3] Kalt, C., "Internet Relay Chat: Client Protocol", RFC 2812, + April 2000. + + [4] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [5] Bradner, S., "IETF Rights in Contributions", BCP 78, RFC 3667, + February 2004. + +Authors' Addresses + + Kevin L. Mitchell + Undernet IRC Network + 38 Eighth St., Apt. 7 + Cambridge, Massachusetts 02141 + US + + Phone: +1-617-230-1021 + EMail: klmitch@mit.edu + URI: http://www.mit.edu/~klmitch/ + + Perry Lorier + Undernet IRC Network + 3 Liston Cres + Hamilton, Waikato 2001 + NZ + + Phone: +64-7-859-1109 + EMail: isomer@undernet.org + + + +Mitchell, et al. Expires September 5, 2005 [Page 15] +Internet-Draft IRC CAP March 2005 + + Lee Hardy + ircd-ratbox Development Team + + EMail: lee@leeh.co.uk + URI: http://www.leeh.co.uk + + Piotr Kucharski + IRCnet + + EMail: Beeth@irc.pl + URI: http://42.pl/ + + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 16] +Internet-Draft IRC CAP March 2005 + +Appendix A. Examples + + In the following examples, lines preceded by "CLIENT:" indicate + protocol messages sent by the client, and lines preceded by "SERVER:" + indicate protocol messages sent by the server. For clarity, the + origin field for server-originated protocol messages has been + omitted. This field would consist of a colon (':') followed by the + full server name, and would be the first field in the command. + + A client communicating with a server not supporting CAP. + + CLIENT: CAP LS + CLIENT: NICK nickname + CLIENT: USER username ignored ignored :real name + SERVER: 001 [...] + + A client which does not wish to enter capability negotiation. + + CLIENT: CAP END + CLIENT: NICK nickname + CLIENT: USER username ignored ignored :real name + SERVER: 001 [...] + + A client entering into capability negotiation during registration, + and requesting a set of capabilities that the server does not + support. + + CLIENT: CAP LS + CLIENT: NICK nickname + CLIENT: USER username ignored ignored :real name + SERVER: CAP LS * :A B C D E F G H + SERVER: CAP LS :I J + CLIENT: CAP REQ :A B C D E F + SERVER: CAP NAK :A B C D E F + CLIENT: CAP REQ :A C E F + SERVER: CAP ACK :A C E F + CLIENT: CAP REQ :B + SERVER: CAP ACK :B + CLIENT: CAP REQ :D + SERVER: CAP NAK :D + CLIENT: CAP END + SERVER: 001 [...] + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 17] +Internet-Draft IRC CAP March 2005 + + A client requesting a capability that requires an ACK (Section 3.4) + subcommand from the client to be enabled. + + CLIENT: CAP LS + SERVER: CAP LS :~I ~J K + CLIENT: CAP REQ :I J K + SERVER: CAP ACK :~I ~J K + CLIENT: CAP ACK :I J + + A client requesting a capability that requires an ACK (Section 3.4) + subcommand from the client to be enabled and disabled, using the LIST + (Section 3.2) subcommand in between. + + CLIENT: CAP LS + SERVER: CAP LS :~A ~B + CLIENT: CAP REQ :A B + SERVER: CAP ACK :~A ~B + CLIENT: CAP LIST + SERVER: CAP LIST :~A ~B + CLIENT: CAP ACK :A B + CLIENT: CAP LIST + SERVER: CAP LIST :A B + CLIENT: CAP REQ :-B + SERVER: CAP ACK :-~B + CLIENT: CAP LIST + SERVER: CAP LIST :A -~B + CLIENT: CAP ACK :-B + CLIENT: CAP LIST + SERVER: CAP LIST :A + + A client requesting a capability that is sticky. + + CLIENT: CAP LS + SERVER: CAP LS :=I J + CLIENT: CAP REQ :I J + SERVER: CAP ACK :=I J + + A client requesting a capability be disabled. + + CLIENT: CAP LIST + SERVER: CAP LIST :=A B C D + CLIENT: CAP REQ :-B -C + SERVER: CAP ACK :-B -C + + + + +Mitchell, et al. Expires September 5, 2005 [Page 18] +Internet-Draft IRC CAP March 2005 + +Appendix B. ABNF Description of Capabilities + + This section summarizes the ABNF [4] description of the capabilities + extension. + + capcmd = [ ":" servername SP ] "CAP" SP subcmd + + subcmd = lscmd / listcmd / reqcmd / ackcmd / + nakcmd / clearcmd / endcmd + + capcmderr = ":" servername SP "410" SP nick SP badcmd + SP ":Invalid CAP subcommand" + ; badcmd is the unrecognized subcommand + + caplist = [ ":" ] *( capmod ) capab + caplist =/ ":" *( capmod ) capab 1*( SP *( capmod ) capab ) + + lscmd = "LS" + lscmd =/ "LS" SP [ "*" SP ] caplist + + listcmd = "LIST" + listcmd =/ "LIST" SP ":" + listcmd =/ "LIST" SP [ "*" SP ] caplist + + reqcmd = "REQ" SP caplist + + ackcmd = "ACK" SP [ "*" SP ] caplist + + nakcmd = "NAK" SP ":" acklist + ; acklist is at least 100 characters of the + ; capability list from the REQ + + clearcmd = "CLEAR" + + endcmd = "END" + + elem = ALPHA *( ALPHA / DIGIT / "-" ) + + netname = elem 1*( "." elem ) + + netDeleg = netname 1*( "/" elem ) + + standardized = elem + + capab = netDeleg / standardized + + dismod = "-" + stickymod = "=" + + +Mitchell, et al. Expires September 5, 2005 [Page 19] +Internet-Draft IRC CAP March 2005 + + ackmod = "~" + + capmod = dismod / stickymod / ackmod + + + + + + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 20] +Internet-Draft IRC CAP March 2005 + +Appendix C. ChangeLog + + Note to RFC Editor: This section may be removed on publication as an + RFC. + + Here is a log of changes to this document: + + 2004-12-15 KLM Initial draft written. + + 2004-12-16 KLM + + * Added description of the argument to some CAP commands in + Section 3. + + * Clarified that requirements of Section 3 only apply to clients + and servers implementing capabilities. + + * Substitution of "performed" for "done" in Section 3.5 + + * Added LIST (Section 3.2) subcommand to provide a mechanism to + query active capabilities. + + * Added reference to RFC 2812 [3]. + + * Moved Examples (Appendix A) section into the back matter. + + * Corrected Perry Lorier's email address. + + * Added this ChangeLog section. + + * Corrected typo in Section 3.7: "sent" for "send". + + * Added elements to enhance readability. + + * Changed to non-compact form. + + * Changed anchor for Section 5 to "capabilities" from "caps" to + reduce possible confusion. + + * Revise last sentence of first paragraph of Section 2 to remove + redundancy. + + * Revise last sentence of second paragraph of Section 2 + + * Added email addresses for Lee H and Beeth; updated contact + information for Isomer. + + + +Mitchell, et al. Expires September 5, 2005 [Page 21] +Internet-Draft IRC CAP March 2005 + + 2004-12-17 KLM + + * Augmented description of CAP command and subcommands with ABNF + description. + + * Revised Section 5 to remove "net." name space and replace it + with a delegated name space beginning with a DNS domain name + (suggested by Isomer). + + * Augmented ABNF description of capability names. + + * Revised Section 6 to reflect change in capability name space. + + * Added Appendix B to bring together the entire ABNF description + of capabilities. + + 2004-12-18 KLM + + * Added explanation of what should happen if an unrecognized + subcommand is given. + + * Clarified what to do if a client sends a subcommand that + shouldn't come from a client. + + * Add references to LIST (Section 3.2) to LSL and Section 3.1. + + * Section 3.3 omitted the caplist argument for the REQ command; + corrected. + + * Relax the prohibition against a client acknowledging a + capability that doesn't modify the protocol stream in Section + 3.4 + + * Relax the requirement for a client that understands + capabilities to send CAP END in Section 3.7 + + 2004-12-19 KLM + + * Converted a number of common xrefs into internal entities to + simplify the text. + + * Inserted some white space to make the section a bit + more readable. + + * Added the keyword "Protocol". + + +Mitchell, et al. Expires September 5, 2005 [Page 22] +Internet-Draft IRC CAP March 2005 + + * Added the term "NOT RECOMMENDED" to the note on "Requirements + Language". + + * Moved LIST (Section 3.2) up in the list of CAP subcommands. + + * Minor formatting change to the ABNF representation of subcmd. + + * Capitalized "MAY" in "empty" subcommand. + + * Added text about capability list order and what to do if no + capabilities are implemented to "empty" subcommand. + + * Mention LIST (Section 3.2) also in LSL when talking about + sending more than one LSL subcommand. + + * Clarify language in Section 3.1 a little bit. + + * Substitute "set of capabilities" for "list of capabilities" in + Section 3.3. + + * Fix minor typo in preamble to ABNF description of NAK (Section + 3.5) subcommand: substitution of "ACK" for "NAK". + + * Add note about servers ignoring END (Section 3.7) after client + registration. + + * Fix minor typo in preamble to ABNF description of LIST (Section + 3.2) subcommand: substitution of "END" for "LIST". + + * Added Section 4 discussing capability negotiation. + + * Add ".xml" extension to include files in references section. + + * Simplification of preamble of first example (Appendix A). + + * Add 'type="ABNF"' to sections so that they can be + extracted and used to create the abnf.xml now included in + Appendix B. + + * It's now RFC 3667 [5], not RFC 2026... + + 2004-12-27 KLM + + * Minor wording changes to second paragraph of Section 1 + + * Minor wording change to first paragraph of Section 2 + + +Mitchell, et al. Expires September 5, 2005 [Page 23] +Internet-Draft IRC CAP March 2005 + + * Minor wording changes to first paragraph of Section 3; remove + redundant note about the IRC colon sentinel. + + * Change a "must" to a "MUST" in Section 3.4; note that + capability list may be truncated if it would otherwise exceed + the 512 character limit. + + * In Section 3.5, note that capability list may be truncated if + it would otherwise exceed the 512 character limit. + + * Remove redundant line about ignoring END (Section 3.7) commands + after registration. + + * Correct spelling of "acknowledgments". + + * Empty elements for Lee H and Beeth; put Beeth's + real name, Piotr Kucharski, in the right place. + + * Switch to using a new preprocessor that consolidates all the + ABNF artwork and inserts it with the processing instruction + . + + * Remove deliberate page break after section. + + * Reorder authors section to consolidate elements + for everyone. + + * Drop abbreviation for Undernet. + + * Expand Section 7 a bit to try to explain why capabilities are + not suited to securing IRC. + + 2005-01-04 KLM + + * Add Lee Hardy's information to the list of authors. + + 2005-01-05 KLM + + * Replace UNKNOWNCAPCMD with INVALIDCAPCMD. + + * Begin rewriting LS (Section 3.1) documentation + + + + +Mitchell, et al. Expires September 5, 2005 [Page 24] +Internet-Draft IRC CAP March 2005 + + 2005-01-19 KLM + + * Redesign the protocol substantially to simplify it. + + 2005-01-20 KLM + + * Update Piotr's contact information. + + * Drop the "x-" namespace... + + 2005-01-20 LH + + * Some servers do issue banner responses, now. + + * The CAP subcommand is now a requirement. + + * Minor grammatical fix-up in documentation of REQ (Section 3.3) + ("acceptance of or rejection of"--strike first "of"). + + * Clarify that sticky capabilities cause a REQ (Section 3.3) to + be NAK (Section 3.5)ed. + + * Mark the third case of an ACK (Section 3.4) with an explicit + indicator that it's the third case... + + * Strike redundant mention of not suspending client registration + in documentation for END (Section 3.7). + + 2005-01-21 LH + + * Move all references on capability modifiers to its own section + + * Clarify instructions on the ack ('~') modifier, indicating it + can be used with sticky capabilities. + + * Add a note into CAP section about capability modifiers + + 2005-01-21 KLM + + * Subcommands are not optional anymore; updated the description + of CAP and the ABNF to reflect this. + + * More than one modifier may precede a capability name. + + +Mitchell, et al. Expires September 5, 2005 [Page 25] +Internet-Draft IRC CAP March 2005 + + * Move ABNF for capmod into the "Capability Modifiers" section. + + * Fix a few minor grammatical errors (I think). + + * Note that capability names may be preceded by modifiers in the + first form of ACK. + + * Remove an unnecessary "MAY" in documentation for the third + usage of ACK. + + * Explicitly note in the ABNF for NAK that the parameter is an + opaque repeat of at least the first 100 characters of the + argument to REQ. + + * CLEAR may result in more than one ACK. + + * Clarify the language of what composes a capability name. + + * Add missing . + + * ACK subcommand should be sent in response to ACK with ack + modifier as soon as possible... + + * Allow disable modifier in LIST, but only in conjunction with an + ack modifier. + + * The ack modifier may also show up in an LS response; rewrote + the final paragraph to indicate that and clarify the language. + + * Add "Client" to the title in the appropriate place... + + * The "capability" rule in the ABNF got changed to "capab" for + brevity. + + * Update "date" to be current. + + 2005-01-22 LH + + * Clarify a client must not act upon an ACK spread across + multiple lines until it receives the final ACK of the set. + + 2005-01-23 KLM + + * Bump version number in preparation for any suggested edits... + + + +Mitchell, et al. Expires September 5, 2005 [Page 26] +Internet-Draft IRC CAP March 2005 + + 2005-01-26 LH + + * Clarify a server also must not change capabilities until its + finished sending its ACKs. + + 2005-01-27 KLM + + * Acknowledge Aaron Wiebe as participating. + + 2005-03-01 LH + + * Add examples on sticky modifiers, the removal modifier and the + sticky modifier. + + 2005-03-07 KLM + + * Submit second draft... + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 27] +Internet-Draft IRC CAP March 2005 + +Intellectual Property Statement + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Disclaimer of Validity + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Copyright Statement + + Copyright (C) The Internet Society (2005). This document is subject + to the rights, licenses and restrictions contained in BCP 78, and + except as set forth therein, the authors retain all their rights. + +Acknowledgment + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + +Mitchell, et al. Expires September 5, 2005 [Page 28] diff --git a/doc/technical/event.txt b/doc/technical/event.txt new file mode 100644 index 0000000..b09b0b7 --- /dev/null +++ b/doc/technical/event.txt @@ -0,0 +1,82 @@ +Overview of the event subsystem +Adrian Chadd + +$Id$ + +One of the things that immediately struck me whilst first looking at the +code was that the ircd periodically scheduled things in io_loop() but +it did them manually. This is very wasteful and very tedious. + +Therefore, an event system was added to hybrid. src/event.c contains an +event system ported from the squid web cache. It is pretty self contained, +and only a few things (debugging, time resolution) needed changing. + +An event is scheduled through eventAdd() or eventAddIsh() : + +eventAdd(const char *name, EVH * func, void *arg, time_t when, int weight) +eventAddIsh(const char *name, EVH * func, void *arg, time_t delta_ish, + int weight) + +after 'when' (or delta_ish) seconds has elapsed from the time the above +functions are called, the 'func' is called with the given data 'arg'. The +event is then deleted. + +To delete an event, use eventDelete() : + +eventDelete(EVH * func, void *arg) + +An event is identified by its callback function and data pair. + +Events are run through eventRun(). This is designed to be called *BEFORE* +your IO handlers, to let events scheduled immediately (ie a time of 0) +to initiate IO before the IO handlers are called. + +(Believe me, its useful.) + + + +Example: + +Say you have something which must be called every 15 seconds. + +* You would first define the callback in your module: + +static EVH foo_periodic_event; +static int initialised = 0; + +* You would then add the event in your initialization function: + +void foo_init(void) +{ + if (!initialised) { + eventAdd("foo_periodic_event", foo_periodic_event, NULL, 0, 0); + initialised = 1; + } +} + + This will force the event to be called the next time eventRun() is called, + rather than waiting 15 seconds. + +* You then define your event callback: + +static void +foo_periodic_event(void *data) +{ + /* We'd do our work here */ + + /* Then we'd finish */ + eventAdd("foo_periodic_event", foo_periodic_event, NULL, 15, 0); +} + + +Notes: + +* I really should change the timeout value to be in milliseconds. Squid used + a double, but Dianora had something against floating point code in the main + loop (which is understandable). If someone wants a fun task .. :-) + +* Note that the 'name' parameter to eventAdd() / eventAddIsh() is a const + char *, and is *not copied* but *referenced*. Therefore, it is in your + best interest to use string constants. + +* /stats E for an oper shows pending events. Thanks Diane! diff --git a/doc/technical/fd-management.txt b/doc/technical/fd-management.txt new file mode 100644 index 0000000..cb98e3f --- /dev/null +++ b/doc/technical/fd-management.txt @@ -0,0 +1,47 @@ +Overview of the filedescriptor subsystem +Adrian Chadd + +$Id$ + + +Filedescriptor lists +-------------------- + +The filedescriptor list is managed through the routines in fdlist.c . +These include: + +fd_open() - tag an FD as "open" and active +fd_close() - tag an FD as "closed" and close() the filedescriptor +fd_note() - update the filedescriptor tag + +You can get the current list of open filedescriptors through /stats F as +an oper. + + + +FD lists +-------- + +The FD list support is very alpha. There are a few lists defined: + +typedef enum fdlist_t { + FDLIST_NONE, + FDLIST_SERVICE, + FDLIST_SERVER, + FDLIST_IDLECLIENT, + FDLIST_BUSYCLIENT, + FDLIST_MAX +} fdlist_t; + +FDLIST_NONE Not on any list (ie close()d) +FDLIST_SERVICE A service - listen() sockets, resolver, etc +FDLIST_SERVER Server connections +FDLIST_IDLECLIENT An idle client +FDLIST_BUSYCLIENT A busy client +FDLIST_MAX Used for bounds checking + +The idea is that the SERVICE sockets need polling frequently, the SERVER +sockets also need polling frequently, BUSYCLIENT is for busy clients +which need frequent polling (eg we're trying to write to them), and +IDLECLIENT is for clients which we don't need to poll frequently. +THIS hasn't been decided upon yet. diff --git a/doc/technical/hostmask.txt b/doc/technical/hostmask.txt new file mode 100644 index 0000000..892bc93 --- /dev/null +++ b/doc/technical/hostmask.txt @@ -0,0 +1,136 @@ +The Hostmask and Netmask System +Copyright(c) 2001 by Andrew Miller(A1kmm) + +$Id$ +------------------------------------------------------------------------ + +Contents :: +============ +* Section 1: Motivation +* Section 2: Underlying Mechanism + - 2.1: General Overview + - 2.2: IPv4 Netmasks + - 2.3: IPv6 Netmasks + - 2.4: Hostmasks +* Section 3: Exposed Abstraction Layer + - 3.1: Parsing Masks + - 3.2: Adding Configuration Items + - 3.3: Initialising or Rehashing + - 3.4: Finding IP/Hostname Confs + - 3.5: Deleting Entries + - 3.6: Reporting Entries + +Section 1: Motivation +===================== + +Looking up configuration hostnames and IP addresses (such as for I-Lines +and K-Lines) needs to be implemented efficiently. It turns out a hash +based algorithm like that employed here performs very will on the average +case, which is what we should be the most concerned about. A profiling +comparison with the mtre code using data from a real network confirmed +that this algorithm performs much better. + + +Section 2: Underlying Mechanism +=============================== + +2.1: General Overview +--------------------- + +In short, a hash-table with linked lists for buckets is used to locate +the correct hostname/netmask entries. In order to support CIDR IPs and +wildcard masks, the entire key cannot be hashed, and there is a need to +rehash. The means for deciding how much to hash differs between the +hostmasks and IPv4/6 netmasks. + +2.2: IPv4 Netmasks +------------------ + +In order to hash IPv4 netmasks for addition to the hash, the mask is first +processed into a 32-bit address and a number of bits is used. All unused +bits are set to 0. The mask could be in these forms: + +1.2.3.4 => 1.2.3.4 : 32 +1.2.3.* => 1.2.3.0 : 24 +1.2.*.* => 1.2.0.0 : 16 +1.2.3.64/26 => 1.2.3.64 : 26 + +The number of whole bytes is then calculated, and only those bytes are +hashed (e.g. 1.2.3.64/26 and 1.2.3.0/24 hash the same). When a complete +IPv4 address is given so that an IPv4 match can be found the entire IP +address is first hashed, and then looked up in the table. Then the most +significant three bytes are hashed, followed by the most significant two, +the most significant one, and finally the "identity hash" bucket is +searched (to match masks like 192/7). + +2.3: IPv6 Netmasks +------------------ + +As per the IPv4 netmasks, except that instead of rehashing with one byte +granularity, a 16-bit (two byte) granularity is used, as 16 rehashes is +considered too great a fixed offset to be justified for a (possible) +slight reduction in hash collisions. + +2.4: Hostmasks +-------------- + +On adding a hostmask to the hash, all of the hostmask right of the next +dot after the last wildcard character in the string is hashed, or in the +case that there are no wildcards in the hostmask, the entire string is +hashed. + +On searching for a hostmask match, the entire hostname is hashed, followed +by the entire hostmask after the first dot, followed by the entire hostmask +after the second dot, and so on. Finally the "identity hash" bucket is checked +to catch hostnames like *test*. + +Section 3: Exposed Abstraction Layer +==================================== + +Section 3.1: Parsing Masks +-------------------------- + +Call "parse_netmask()" with the netmask and a pointer to an irc_inaddr +structure to be filled in, as well as a pointer to an integer where the +number of bits will be placed. + +Always check the return value, if it returns HM_MOST, it means that the +mask is probably a hostmask. If it returns HM_IPV4, it means it was an +IPv4 address. If it returns HM_IPV6, it means it was an IPv6 address. +If parse_netmask() returns HM_MOST however, no change is made to the +irc_inaddr structure or the number of bits. + +Section 3.2: Adding Configuration Items +--------------------------------------- + +Call "add_conf_by_address()" with the hostname or IP mask, the username, +and the ConfItem* to associate with this mask. + +Section 3.3: Initialising and Rehashing +--------------------------------------- + +To initialise, call "init_host_hash()". This only needs to be done once +on start-up. On rehash, to wipe out the old unwanted configuration, and +free them if there are no references to them, call +"clear_out_address_conf()". + +Section 3.4: Finding IP/Hostname Confs +--------------------------------------- + +Call "find_address_conf()" with the hostname, the username, the address, +the address family and the client-supplied password. To find a D-Line, +call "find_dline()" with the address and address family. + +Section 3.5: Deleted Entries +---------------------------- + +Call "delete_one_address_conf()" with the hostname and the ConfItem*. + +Section 3.6: Reporting Entries +------------------------------ + +Call "report_dlines()", "report_exemptlines()", "report_Klines()", or +"report_Ilines()" with the client pointer to report to. Note these walk +the hash, which is inefficient, but these are not called often enough +to justify the memory and maintenance clockcycles to for more efficient +data structuring. diff --git a/doc/technical/index.txt b/doc/technical/index.txt new file mode 100644 index 0000000..32577e9 --- /dev/null +++ b/doc/technical/index.txt @@ -0,0 +1,16 @@ +$Id$ +----------------------------------------------- + +Technical Documentation for ircd-hybrid-8 + +event.txt - Outline of the event system +fd-management.txt - Outline of the file descriptor management system +hostmask.txt - Outline of hostmask handling +network.txt - Outline of the network traffic subsystem +rfc1459.txt - The IRC RFC +rfc2812.txt - The IRC Client RFC +rfc2813.txt - The IRC Server RFC +send.txt - Document on all of the send_to functions +ts3.txt - TSora Version 3 Protocol +ts5.txt - TSora Version 5 Protocol +ts6.txt - TSora Version 6 Protocol diff --git a/doc/technical/network.txt b/doc/technical/network.txt new file mode 100644 index 0000000..520adc0 --- /dev/null +++ b/doc/technical/network.txt @@ -0,0 +1,99 @@ +Overview of the network subsystem +Adrian Chadd + +$Id$ + +This document is an overview of the new and hopefully improved network +subsystem. + +The code is based loosely upon the network core found in the Squid web cache +server, with some optimizations for ircd-specific IO patterns. + +Filedescriptor IO +----------------- + +Filedescriptor IO is initiated using comm_setselect(). comm_setselect() +registers interest in reading from or writing to a file descriptor. +When a filedescriptor is ready for the required IO a callback is called +from the IO loop. + +The comm_setselect() usage is: + +void +comm_setselect(int fd, fdlist_t list, int type, PF *callback, void *cbdata, + int timeout) + +where: + fd filedescriptor + list Which list the FD should be put on + type IO type. Can currently include: + COMM_SELECT_READ - register for read + COMM_SELECT_WRITE - register for write + callback Function to call when the FD is ready + cbdata Data to be passed to above function + timeout Update the timeout value. 0 is "don't update". + + +A typical use is: + +.. + +/* Register interest in the FD for a read event */ +comm_setselect(fd, FDLIST_SERVICE, COMM_SELECT_READ, read_callback, read_data, + 0); + +.. + +(FD becomes ready for read in the IO loop) + +void +read_callback(int fd, void *data) +{ + /* called when the FD becomes ready for read */ + retval = read(fd, buf, len); + + .. + /* Ok, we need to read some more when its ready */ + comm_setselect(fd, FDLIST_SERVICE, COMM_SELECT_READ, read_callback, data, + 0); +} + +Socket timeouts +--------------- + +A "socket timeout" is a callback registered to be called when a certain +amount of time has elapsed. Think of it as an event, but against a FD. + +A good example of socket timeouts is in the comm_connect_tcp() code. +When the connect() begins, comm_settimeout() is called to call +comm_connect_timeout() if the timeout occurs. Once the connect() completes, +comm_settimeout() is called with a timeout of 0 and callback of NULL +to deregister the timeout. If the timeout occurs, comm_connect_timeout() +is called and the connection attempt is aborted. + + + + +Functions +--------- + +comm_open() - a socket() wrapper, enforcing fd limitations and tagging the + file descriptor with a note + +comm_accept() - an accept() wrapper, enforcing fd limitations and tagging + the file descriptor with a note + +comm_connect_tcp() - attempt an async connect(). Handles DNS lookups if + required, and will call the given callback at completion or error + +comm_settimeout() - set a callback to be called after a given time period. + This is good to implement things like PING checks and connect() timeouts. + +Notes: + +* All socket creation should go through comm_open() / comm_accept(). +* All socket closing should go through fd_close(). comm_close() isn't + implemented yet. +* comm_connect_tcp() is your best friend. :-) +* *ALL* network sockets should be non-blocking. If your OS doesn't support + non-blocking sockets, you shouldn't be here. diff --git a/doc/technical/rfc1459.txt b/doc/technical/rfc1459.txt new file mode 100644 index 0000000..768e176 --- /dev/null +++ b/doc/technical/rfc1459.txt @@ -0,0 +1,3110 @@ +$Id$ + +Network Working Group J. Oikarinen +Request for Comments: 1459 D. Reed + May 1993 + + Internet Relay Chat Protocol + +Status of This Memo + + This memo defines an Experimental Protocol for the Internet + community. Discussion and suggestions for improvement are requested. + Please refer to the current edition of the "IAB Official Protocol + Standards" for the standardization state and status of this protocol. + Distribution of this memo is unlimited. + +Abstract + + The IRC protocol was developed over the last 4 years since it was + first implemented as a means for users on a BBS to chat amongst + themselves. Now it supports a world-wide network of servers and + clients, and is stringing to cope with growth. Over the past 2 years, + the average number of users connected to the main IRC network has + grown by a factor of 10. + + The IRC protocol is a text-based protocol, with the simplest client + being any socket program capable of connecting to the server. + +Table of Contents + + 1. INTRODUCTION ............................................... 4 + 1.1 Servers ................................................ 4 + 1.2 Clients ................................................ 5 + 1.2.1 Operators .......................................... 5 + 1.3 Channels ................................................ 5 + 1.3.1 Channel Operators .................................... 6 + 2. THE IRC SPECIFICATION ....................................... 7 + 2.1 Overview ................................................ 7 + 2.2 Character codes ......................................... 7 + 2.3 Messages ................................................ 7 + 2.3.1 Message format in 'pseudo' BNF .................... 8 + 2.4 Numeric replies ......................................... 10 + 3. IRC Concepts ................................................ 10 + 3.1 One-to-one communication ................................ 10 + 3.2 One-to-many ............................................. 11 + 3.2.1 To a list .......................................... 11 + 3.2.2 To a group (channel) ............................... 11 + 3.2.3 To a host/server mask .............................. 12 + 3.3 One to all .............................................. 12 + + 3.3.1 Client to Client ................................... 12 + 3.3.2 Clients to Server .................................. 12 + 3.3.3 Server to Server ................................... 12 + 4. MESSAGE DETAILS ............................................. 13 + 4.1 Connection Registration ................................. 13 + 4.1.1 Password message ................................... 14 + 4.1.2 Nickname message ................................... 14 + 4.1.3 User message ....................................... 15 + 4.1.4 Server message ..................................... 16 + 4.1.5 Operator message ................................... 17 + 4.1.6 Quit message ....................................... 17 + 4.1.7 Server Quit message ................................ 18 + 4.2 Channel operations ...................................... 19 + 4.2.1 Join message ....................................... 19 + 4.2.2 Part message ....................................... 20 + 4.2.3 Mode message ....................................... 21 + 4.2.3.1 Channel modes ................................. 21 + 4.2.3.2 User modes .................................... 22 + 4.2.4 Topic message ...................................... 23 + 4.2.5 Names message ...................................... 24 + 4.2.6 List message ....................................... 24 + 4.2.7 Invite message ..................................... 25 + 4.2.8 Kick message ....................................... 25 + 4.3 Server queries and commands ............................. 26 + 4.3.1 Version message .................................... 26 + 4.3.2 Stats message ...................................... 27 + 4.3.3 Links message ...................................... 28 + 4.3.4 Time message ....................................... 29 + 4.3.5 Connect message .................................... 29 + 4.3.6 Trace message ...................................... 30 + 4.3.7 Admin message ...................................... 31 + 4.3.8 Info message ....................................... 31 + 4.4 Sending messages ........................................ 32 + 4.4.1 Private messages ................................... 32 + 4.4.2 Notice messages .................................... 33 + 4.5 User-based queries ...................................... 33 + 4.5.1 Who query .......................................... 33 + 4.5.2 Whois query ........................................ 34 + 4.5.3 Whowas message ..................................... 35 + 4.6 Miscellaneous messages .................................. 35 + 4.6.1 Kill message ....................................... 36 + 4.6.2 Ping message ....................................... 37 + 4.6.3 Pong message ....................................... 37 + 4.6.4 Error message ...................................... 38 + 5. OPTIONAL MESSAGES ........................................... 38 + 5.1 Away message ............................................ 38 + 5.2 Rehash command .......................................... 39 + 5.3 Restart command ......................................... 39 + + 5.4 Summon message .......................................... 40 + 5.5 Users message ........................................... 40 + 5.6 Operwall command ........................................ 41 + 5.7 Userhost message ........................................ 42 + 5.8 Ison message ............................................ 42 + 6. REPLIES ..................................................... 43 + 6.1 Error Replies ........................................... 43 + 6.2 Command responses ....................................... 48 + 6.3 Reserved numerics ....................................... 56 + 7. Client and server authentication ............................ 56 + 8. Current Implementations Details ............................. 56 + 8.1 Network protocol: TCP ................................... 57 + 8.1.1 Support of Unix sockets ............................ 57 + 8.2 Command Parsing ......................................... 57 + 8.3 Message delivery ........................................ 57 + 8.4 Connection 'Liveness' ................................... 58 + 8.5 Establishing a server-client connection ................. 58 + 8.6 Establishing a server-server connection ................. 58 + 8.6.1 State information exchange when connecting ......... 59 + 8.7 Terminating server-client connections ................... 59 + 8.8 Terminating server-server connections ................... 59 + 8.9 Tracking nickname changes ............................... 60 + 8.10 Flood control of clients ............................... 60 + 8.11 Non-blocking lookups ................................... 61 + 8.11.1 Hostname (DNS) lookups ............................ 61 + 8.11.2 Username (Ident) lookups .......................... 61 + 8.12 Configuration file ..................................... 61 + 8.12.1 Allowing clients to connect ....................... 62 + 8.12.2 Operators ......................................... 62 + 8.12.3 Allowing servers to connect ....................... 62 + 8.12.4 Administrivia ..................................... 63 + 8.13 Channel membership ..................................... 63 + 9. Current problems ............................................ 63 + 9.1 Scalability ............................................. 63 + 9.2 Labels .................................................. 63 + 9.2.1 Nicknames .......................................... 63 + 9.2.2 Channels ........................................... 64 + 9.2.3 Servers ............................................ 64 + 9.3 Algorithms .............................................. 64 + 10. Support and availability ................................... 64 + 11. Security Considerations .................................... 65 + 12. Authors' Addresses ......................................... 65 + +1. INTRODUCTION + + The IRC (Internet Relay Chat) protocol has been designed over a + number of years for use with text based conferencing. This document + describes the current IRC protocol. + + The IRC protocol has been developed on systems using the TCP/IP + network protocol, although there is no requirement that this remain + the only sphere in which it operates. + + IRC itself is a teleconferencing system, which (through the use of + the client-server model) is well-suited to running on many machines + in a distributed fashion. A typical setup involves a single process + (the server) forming a central point for clients (or other servers) + to connect to, performing the required message delivery/multiplexing + and other functions. + +1.1 Servers + + The server forms the backbone of IRC, providing a point to which + clients may connect to to talk to each other, and a point for other + servers to connect to, forming an IRC network. The only network + configuration allowed for IRC servers is that of a spanning tree [see + Fig. 1] where each server acts as a central node for the rest of the + net it sees. + + [ Server 15 ] [ Server 13 ] [ Server 14] + / \ / + / \ / + [ Server 11 ] ------ [ Server 1 ] [ Server 12] + / \ / + / \ / + [ Server 2 ] [ Server 3 ] + / \ \ + / \ \ + [ Server 4 ] [ Server 5 ] [ Server 6 ] + / | \ / + / | \ / + / | \____ / + / | \ / + [ Server 7 ] [ Server 8 ] [ Server 9 ] [ Server 10 ] + + : + [ etc. ] + : + + [ Fig. 1. Format of IRC server network ] + +1.2 Clients + + A client is anything connecting to a server that is not another + server. Each client is distinguished from other clients by a unique + nickname having a maximum length of nine (9) characters. See the + protocol grammar rules for what may and may not be used in a + nickname. In addition to the nickname, all servers must have the + following information about all clients: the real name of the host + that the client is running on, the username of the client on that + host, and the server to which the client is connected. + +1.2.1 Operators + + To allow a reasonable amount of order to be kept within the IRC + network, a special class of clients (operators) is allowed to perform + general maintenance functions on the network. Although the powers + granted to an operator can be considered as 'dangerous', they are + nonetheless required. Operators should be able to perform basic + network tasks such as disconnecting and reconnecting servers as + needed to prevent long-term use of bad network routing. In + recognition of this need, the protocol discussed herein provides for + operators only to be able to perform such functions. See sections + 4.1.7 (SQUIT) and 4.3.5 (CONNECT). + + A more controversial power of operators is the ability to remove a + user from the connected network by 'force', i.e. operators are able + to close the connection between any client and server. The + justification for this is delicate since its abuse is both + destructive and annoying. For further details on this type of + action, see section 4.6.1 (KILL). + +1.3 Channels + + A channel is a named group of one or more clients which will all + receive messages addressed to that channel. The channel is created + implicitly when the first client joins it, and the channel ceases to + exist when the last client leaves it. While channel exists, any + client can reference the channel using the name of the channel. + + Channels names are strings (beginning with a '&' or '#' character) of + length up to 200 characters. Apart from the the requirement that the + first character being either '&' or '#'; the only restriction on a + channel name is that it may not contain any spaces (' '), a control G + (^G or ASCII 7), or a comma (',' which is used as a list item + separator by the protocol). + + There are two types of channels allowed by this protocol. One is a + distributed channel which is known to all the servers that are + + connected to the network. These channels are marked by the first + character being a only clients on the server where it exists may join + it. These are distinguished by a leading '&' character. On top of + these two types, there are the various channel modes available to + alter the characteristics of individual channels. See section 4.2.3 + (MODE command) for more details on this. + + To create a new channel or become part of an existing channel, a user + is required to JOIN the channel. If the channel doesn't exist prior + to joining, the channel is created and the creating user becomes a + channel operator. If the channel already exists, whether or not your + request to JOIN that channel is honoured depends on the current modes + of the channel. For example, if the channel is invite-only, (+i), + then you may only join if invited. As part of the protocol, a user + may be a part of several channels at once, but a limit of ten (10) + channels is recommended as being ample for both experienced and + novice users. See section 8.13 for more information on this. + + If the IRC network becomes disjoint because of a split between two + servers, the channel on each side is only composed of those clients + which are connected to servers on the respective sides of the split, + possibly ceasing to exist on one side of the split. When the split + is healed, the connecting servers announce to each other who they + think is in each channel and the mode of that channel. If the + channel exists on both sides, the JOINs and MODEs are interpreted in + an inclusive manner so that both sides of the new connection will + agree about which clients are in the channel and what modes the + channel has. + +1.3.1 Channel Operators + + The channel operator (also referred to as a "chop" or "chanop") on a + given channel is considered to 'own' that channel. In recognition of + this status, channel operators are endowed with certain powers which + enable them to keep control and some sort of sanity in their channel. + As an owner of a channel, a channel operator is not required to have + reasons for their actions, although if their actions are generally + antisocial or otherwise abusive, it might be reasonable to ask an IRC + operator to intervene, or for the usersjust leave and go elsewhere + and form their own channel. + + The commands which may only be used by channel operators are: + + KICK - Eject a client from the channel + MODE - Change the channel's mode + INVITE - Invite a client to an invite-only channel (mode +i) + TOPIC - Change the channel topic in a mode +t channel + + A channel operator is identified by the '@' symbol next to their + nickname whenever it is associated with a channel (ie replies to the + NAMES, WHO and WHOIS commands). + +2. The IRC Specification + +2.1 Overview + + The protocol as described herein is for use both with server to + server and client to server connections. There are, however, more + restrictions on client connections (which are considered to be + untrustworthy) than on server connections. + +2.2 Character codes + + No specific character set is specified. The protocol is based on a a + set of codes which are composed of eight (8) bits, making up an + octet. Each message may be composed of any number of these octets; + however, some octet values are used for control codes which act as + message delimiters. + + Regardless of being an 8-bit protocol, the delimiters and keywords + are such that protocol is mostly usable from USASCII terminal and a + telnet connection. + + Because of IRC's scandanavian origin, the characters {}| are + considered to be the lower case equivalents of the characters []\, + respectively. This is a critical issue when determining the + equivalence of two nicknames. + +2.3 Messages + + Servers and clients send eachother messages which may or may not + generate a reply. If the message contains a valid command, as + described in later sections, the client should expect a reply as + specified but it is not advised to wait forever for the reply; client + to server and server to server communication is essentially + asynchronous in nature. + + Each IRC message may consist of up to three main parts: the prefix + (optional), the command, and the command parameters (of which there + may be up to 15). The prefix, command, and all parameters are + separated by one (or more) ASCII space character(s) (0x20). + + The presence of a prefix is indicated with a single leading ASCII + colon character (':', 0x3b), which must be the first character of the + message itself. There must be no gap (whitespace) between the colon + and the prefix. The prefix is used by servers to indicate the true + + origin of the message. If the prefix is missing from the message, it + is assumed to have originated from the connection from which it was + received. Clients should not use prefix when sending a message from + themselves; if they use a prefix, the only valid prefix is the + registered nickname associated with the client. If the source + identified by the prefix cannot be found from the server's internal + database, or if the source is registered from a different link than + from which the message arrived, the server must ignore the message + silently. + + The command must either be a valid IRC command or a three (3) digit + number represented in ASCII text. + + IRC messages are always lines of characters terminated with a CR-LF + (Carriage Return - Line Feed) pair, and these messages shall not + exceed 512 characters in length, counting all characters including + the trailing CR-LF. Thus, there are 510 characters maximum allowed + for the command and its parameters. There is no provision for + continuation message lines. See section 7 for more details about + current implementations. + +2.3.1 Message format in 'pseudo' BNF + + The protocol messages must be extracted from the contiguous stream of + octets. The current solution is to designate two characters, CR and + LF, as message separators. Empty messages are silently ignored, + which permits use of the sequence CR-LF between messages + without extra problems. + + The extracted message is parsed into the components , + and list of parameters matched either by or + components. + + The BNF representation for this is: + + ::= [':' ] + ::= | [ '!' ] [ '@' ] + ::= { } | + ::= ' ' { ' ' } + ::= [ ':' | ] + + ::= + ::= + + ::= CR LF + +NOTES: + + 1) is consists only of SPACE character(s) (0x20). + Specially notice that TABULATION, and all other control + characters are considered NON-WHITE-SPACE. + + 2) After extracting the parameter list, all parameters are equal, + whether matched by or . is just + a syntactic trick to allow SPACE within parameter. + + 3) The fact that CR and LF cannot appear in parameter strings is + just artifact of the message framing. This might change later. + + 4) The NUL character is not special in message framing, and + basically could end up inside a parameter, but as it would + cause extra complexities in normal C string handling. Therefore + NUL is not allowed within messages. + + 5) The last parameter may be an empty string. + + 6) Use of the extended prefix (['!' ] ['@' ]) must + not be used in server to server communications and is only + intended for server to client messages in order to provide + clients with more useful information about who a message is + from without the need for additional queries. + + Most protocol messages specify additional semantics and syntax for + the extracted parameter strings dictated by their position in the + list. For example, many server commands will assume that the first + parameter after the command is the list of targets, which can be + described with: + + ::= [ "," ] + ::= | '@' | | + ::= ('#' | '&') + ::= + ::= see RFC 952 [DNS:4] for details on allowed hostnames + ::= { | | } + ::= ('#' | '$') + ::= + + Other parameter syntaxes are: + + ::= { } + ::= 'a' ... 'z' | 'A' ... 'Z' + ::= '0' ... '9' + ::= '-' | '[' | ']' | '\' | '`' | '^' | '{' | '}' + + ::= + +2.4 Numeric replies + + Most of the messages sent to the server generate a reply of some + sort. The most common reply is the numeric reply, used for both + errors and normal replies. The numeric reply must be sent as one + message consisting of the sender prefix, the three digit numeric, and + the target of the reply. A numeric reply is not allowed to originate + from a client; any such messages received by a server are silently + dropped. In all other respects, a numeric reply is just like a normal + message, except that the keyword is made up of 3 numeric digits + rather than a string of letters. A list of different replies is + supplied in section 6. + +3. IRC Concepts. + + This section is devoted to describing the actual concepts behind the + organization of the IRC protocol and how the current + implementations deliver different classes of messages. + + 1--\ + A D---4 + 2--/ \ / + B----C + / \ + 3 E + + Servers: A, B, C, D, E Clients: 1, 2, 3, 4 + + [ Fig. 2. Sample small IRC network ] + +3.1 One-to-one communication + + Communication on a one-to-one basis is usually only performed by + clients, since most server-server traffic is not a result of servers + talking only to each other. To provide a secure means for clients to + talk to each other, it is required that all servers be able to send a + message in exactly one direction along the spanning tree in order to + reach any client. The path of a message being delivered is the + shortest path between any two points on the spanning tree. + + The following examples all refer to Figure 2 above. + +Example 1: + A message between clients 1 and 2 is only seen by server A, which + sends it straight to client 2. + +Example 2: + A message between clients 1 and 3 is seen by servers A & B, and + client 3. No other clients or servers are allowed see the message. + +Example 3: + A message between clients 2 and 4 is seen by servers A, B, C & D + and client 4 only. + +3.2 One-to-many + + The main goal of IRC is to provide a forum which allows easy and + efficient conferencing (one to many conversations). IRC offers + several means to achieve this, each serving its own purpose. + +3.2.1 To a list + + The least efficient style of one-to-many conversation is through + clients talking to a 'list' of users. How this is done is almost + self explanatory: the client gives a list of destinations to which + the message is to be delivered and the server breaks it up and + dispatches a separate copy of the message to each given destination. + This isn't as efficient as using a group since the destination list + is broken up and the dispatch sent without checking to make sure + duplicates aren't sent down each path. + +3.2.2 To a group (channel) + + In IRC the channel has a role equivalent to that of the multicast + group; their existence is dynamic (coming and going as people join + and leave channels) and the actual conversation carried out on a + channel is only sent to servers which are supporting users on a given + channel. If there are multiple users on a server in the same + channel, the message text is sent only once to that server and then + sent to each client on the channel. This action is then repeated for + each client-server combination until the original message has fanned + out and reached each member of the channel. + + The following examples all refer to Figure 2. + +Example 4: + Any channel with 1 client in it. Messages to the channel go to the + server and then nowhere else. + +Example 5: + 2 clients in a channel. All messages traverse a path as if they + were private messages between the two clients outside a channel. + +Example 6: + Clients 1, 2 and 3 in a channel. All messages to the channel are + sent to all clients and only those servers which must be traversed + by the message if it were a private message to a single client. If + client 1 sends a message, it goes back to client 2 and then via + server B to client 3. + +3.2.3 To a host/server mask + + To provide IRC operators with some mechanism to send messages to a + large body of related users, host and server mask messages are + provided. These messages are sent to users whose host or server + information match that of the mask. The messages are only sent to + locations where users are, in a fashion similar to that of channels. + +3.3 One-to-all + + The one-to-all type of message is better described as a broadcast + message, sent to all clients or servers or both. On a large network + of users and servers, a single message can result in a lot of traffic + being sent over the network in an effort to reach all of the desired + destinations. + + For some messages, there is no option but to broadcast it to all + servers so that the state information held by each server is + reasonably consistent between servers. + +3.3.1 Client-to-Client + + There is no class of message which, from a single message, results in + a message being sent to every other client. + +3.3.2 Client-to-Server + + Most of the commands which result in a change of state information + (such as channel membership, channel mode, user status, etc) must be + sent to all servers by default, and this distribution may not be + changed by the client. + +3.3.3 Server-to-Server. + + While most messages between servers are distributed to all 'other' + servers, this is only required for any message that affects either a + user, channel or server. Since these are the basic items found in + + IRC, nearly all messages originating from a server are broadcast to + all other connected servers. + +4. Message details + + On the following pages are descriptions of each message recognized by + the IRC server and client. All commands described in this section + must be implemented by any server for this protocol. + + Where the reply ERR_NOSUCHSERVER is listed, it means that the + parameter could not be found. The server must not send any + other replies after this for that command. + + The server to which a client is connected is required to parse the + complete message, returning any appropriate errors. If the server + encounters a fatal error while parsing a message, an error must be + sent back to the client and the parsing terminated. A fatal error + may be considered to be incorrect command, a destination which is + otherwise unknown to the server (server, nick or channel names fit + this category), not enough parameters or incorrect privileges. + + If a full set of parameters is presented, then each must be checked + for validity and appropriate responses sent back to the client. In + the case of messages which use parameter lists using the comma as an + item separator, a reply must be sent for each item. + + In the examples below, some messages appear using the full format: + + :Name COMMAND parameter list + + Such examples represent a message from "Name" in transit between + servers, where it is essential to include the name of the original + sender of the message so remote servers may send back a reply along + the correct path. + +4.1 Connection Registration + + The commands described here are used to register a connection with an + IRC server as either a user or a server as well as correctly + disconnect. + + A "PASS" command is not required for either client or server + connection to be registered, but it must precede the server message + or the latter of the NICK/USER combination. It is strongly + recommended that all server connections have a password in order to + give some level of security to the actual connections. The + recommended order for a client to register is as follows: + + 1. Pass message + 2. Nick message + 3. User message + +4.1.1 Password message + + Command: PASS + Parameters: + + The PASS command is used to set a 'connection password'. The + password can and must be set before any attempt to register the + connection is made. Currently this requires that clients send a PASS + command before sending the NICK/USER combination and servers *must* + send a PASS command before any SERVER command. The password supplied + must match the one contained in the C/N lines (for servers) or I + lines (for clients). It is possible to send multiple PASS commands + before registering but only the last one sent is used for + verification and it may not be changed once registered. Numeric + Replies: + + ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED + + Example: + + PASS secretpasswordhere + +4.1.2 Nick message + + Command: NICK + Parameters: [ ] + + NICK message is used to give user a nickname or change the previous + one. The parameter is only used by servers to indicate + how far away a nick is from its home server. A local connection has + a hopcount of 0. If supplied by a client, it must be ignored. + + If a NICK message arrives at a server which already knows about an + identical nickname for another client, a nickname collision occurs. + As a result of a nickname collision, all instances of the nickname + are removed from the server's database, and a KILL command is issued + to remove the nickname from all other server's database. If the NICK + message causing the collision was a nickname change, then the + original (old) nick must be removed as well. + + If the server recieves an identical NICK from a client which is + directly connected, it may issue an ERR_NICKCOLLISION to the local + client, drop the NICK command, and not generate any kills. + + Numeric Replies: + + ERR_NONICKNAMEGIVEN ERR_ERRONEUSNICKNAME + ERR_NICKNAMEINUSE ERR_NICKCOLLISION + + Example: + + NICK Wiz ; Introducing new nick "Wiz". + + :WiZ NICK Kilroy ; WiZ changed his nickname to Kilroy. + +4.1.3 User message + + Command: USER + Parameters: + + The USER message is used at the beginning of connection to specify + the username, hostname, servername and realname of s new user. It is + also used in communication between servers to indicate new user + arriving on IRC, since only after both USER and NICK have been + received from a client does a user become registered. + + Between servers USER must to be prefixed with client's NICKname. + Note that hostname and servername are normally ignored by the IRC + server when the USER command comes from a directly connected client + (for security reasons), but they are used in server to server + communication. This means that a NICK must always be sent to a + remote server when a new user is being introduced to the rest of the + network before the accompanying USER is sent. + + It must be noted that realname parameter must be the last parameter, + because it may contain space characters and must be prefixed with a + colon (':') to make sure this is recognised as such. + + Since it is easy for a client to lie about its username by relying + solely on the USER message, the use of an "Identity Server" is + recommended. If the host which a user connects from has such a + server enabled the username is set to that as in the reply from the + "Identity Server". + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED + + Examples: + + USER guest tolmoon tolsun :Ronnie Reagan + + ; User registering themselves with a + username of "guest" and real name + "Ronnie Reagan". + + :testnick USER guest tolmoon tolsun :Ronnie Reagan + ; message between servers with the + nickname for which the USER command + belongs to + +4.1.4 Server message + + Command: SERVER + Parameters: + + The server message is used to tell a server that the other end of a + new connection is a server. This message is also used to pass server + data over whole net. When a new server is connected to net, + information about it be broadcast to the whole network. + is used to give all servers some internal information on how far away + all servers are. With a full server list, it would be possible to + construct a map of the entire server tree, but hostmasks prevent this + from being done. + + The SERVER message must only be accepted from either (a) a connection + which is yet to be registered and is attempting to register as a + server, or (b) an existing connection to another server, in which + case the SERVER message is introducing a new server behind that + server. + + Most errors that occur with the receipt of a SERVER command result in + the connection being terminated by the destination host (target + SERVER). Error replies are usually sent using the "ERROR" command + rather than the numeric since the ERROR command has several useful + properties which make it useful here. + + If a SERVER message is parsed and attempts to introduce a server + which is already known to the receiving server, the connection from + which that message must be closed (following the correct procedures), + since a duplicate route to a server has formed and the acyclic nature + of the IRC tree broken. + + Numeric Replies: + + ERR_ALREADYREGISTRED + + Example: + +SERVER test.oulu.fi 1 :[tolsun.oulu.fi] Experimental server + ; New server test.oulu.fi introducing + itself and attempting to register. The + name in []'s is the hostname for the + host running test.oulu.fi. + +:tolsun.oulu.fi SERVER csd.bu.edu 5 :BU Central Server + ; Server tolsun.oulu.fi is our uplink + for csd.bu.edu which is 5 hops away. + +4.1.5 Oper + + Command: OPER + Parameters: + + OPER message is used by a normal user to obtain operator privileges. + The combination of and are required to gain + Operator privileges. + + If the client sending the OPER command supplies the correct password + for the given user, the server then informs the rest of the network + of the new operator by issuing a "MODE +o" for the clients nickname. + + The OPER message is client-server only. + + Numeric Replies: + + ERR_NEEDMOREPARAMS RPL_YOUREOPER + ERR_NOOPERHOST ERR_PASSWDMISMATCH + + Example: + + OPER foo bar ; Attempt to register as an operator + using a username of "foo" and "bar" as + the password. + +4.1.6 Quit + + Command: QUIT + Parameters: [] + + A client session is ended with a quit message. The server must close + the connection to a client which sends a QUIT message. If a "Quit + Message" is given, this will be sent instead of the default message, + the nickname. + + When netsplits (disconnecting of two servers) occur, the quit message + + is composed of the names of two servers involved, separated by a + space. The first name is that of the server which is still connected + and the second name is that of the server that has become + disconnected. + + If, for some other reason, a client connection is closed without the + client issuing a QUIT command (e.g. client dies and EOF occurs + on socket), the server is required to fill in the quit message with + some sort of message reflecting the nature of the event which + caused it to happen. + + Numeric Replies: + + None. + + Examples: + + QUIT :Gone to have lunch ; Preferred message format. + +4.1.7 Server quit message + + Command: SQUIT + Parameters: + + The SQUIT message is needed to tell about quitting or dead servers. + If a server wishes to break the connection to another server it must + send a SQUIT message to the other server, using the the name of the + other server as the server parameter, which then closes its + connection to the quitting server. + + This command is also available operators to help keep a network of + IRC servers connected in an orderly fashion. Operators may also + issue an SQUIT message for a remote server connection. In this case, + the SQUIT must be parsed by each server inbetween the operator and + the remote server, updating the view of the network held by each + server as explained below. + + The should be supplied by all operators who execute a SQUIT + for a remote server (that is not connected to the server they are + currently on) so that other operators are aware for the reason of + this action. The is also filled in by servers which may + place an error or similar message here. + + Both of the servers which are on either side of the connection being + closed are required to to send out a SQUIT message (to all its other + server connections) for all other servers which are considered to be + behind that link. + + Similarly, a QUIT message must be sent to the other connected servers + rest of the network on behalf of all clients behind that link. In + addition to this, all channel members of a channel which lost a + member due to the split must be sent a QUIT message. + + If a server connection is terminated prematurely (e.g. the server on + the other end of the link died), the server which detects + this disconnection is required to inform the rest of the network + that the connection has closed and fill in the comment field + with something appropriate. + + Numeric replies: + + ERR_NOPRIVILEGES ERR_NOSUCHSERVER + + Example: + + SQUIT tolsun.oulu.fi :Bad Link ? ; the server link tolson.oulu.fi has + been terminated because of "Bad Link". + + :Trillian SQUIT cm22.eng.umd.edu :Server out of control + ; message from Trillian to disconnect + "cm22.eng.umd.edu" from the net + because "Server out of control". + +4.2 Channel operations + + This group of messages is concerned with manipulating channels, their + properties (channel modes), and their contents (typically clients). + In implementing these, a number of race conditions are inevitable + when clients at opposing ends of a network send commands which will + ultimately clash. It is also required that servers keep a nickname + history to ensure that wherever a parameter is given, the + server check its history in case it has recently been changed. + +4.2.1 Join message + + Command: JOIN + Parameters: {,} [{,}] + + The JOIN command is used by client to start listening a specific + channel. Whether or not a client is allowed to join a channel is + checked only by the server the client is connected to; all other + servers automatically add the user to the channel when it is received + from other servers. The conditions which affect this are as follows: + + 1. the user must be invited if the channel is invite-only; + + 2. the user's nick/username/hostname must not match any + active bans; + + 3. the correct key (password) must be given if it is set. + + These are discussed in more detail under the MODE command (see + section 4.2.3 for more details). + + Once a user has joined a channel, they receive notice about all + commands their server receives which affect the channel. This + includes MODE, KICK, PART, QUIT and of course PRIVMSG/NOTICE. The + JOIN command needs to be broadcast to all servers so that each server + knows where to find the users who are on the channel. This allows + optimal delivery of PRIVMSG/NOTICE messages to the channel. + + If a JOIN is successful, the user is then sent the channel's topic + (using RPL_TOPIC) and the list of users who are on the channel (using + RPL_NAMREPLY), which must include the user joining. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_BANNEDFROMCHAN + ERR_INVITEONLYCHAN ERR_BADCHANNELKEY + ERR_CHANNELISFULL ERR_BADCHANMASK + ERR_NOSUCHCHANNEL ERR_TOOMANYCHANNELS + RPL_TOPIC + + Examples: + + JOIN #foobar ; join channel #foobar. + + JOIN &foo fubar ; join channel &foo using key "fubar". + + JOIN #foo,&bar fubar ; join channel #foo using key "fubar" + and &bar using no key. + + JOIN #foo,#bar fubar,foobar ; join channel #foo using key "fubar". + and channel #bar using key "foobar". + + JOIN #foo,#bar ; join channels #foo and #bar. + + :WiZ JOIN #Twilight_zone ; JOIN message from WiZ + +4.2.2 Part message + + Command: PART + Parameters: {,} + + The PART message causes the client sending the message to be removed + from the list of active users for all given channels listed in the + parameter string. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL + ERR_NOTONCHANNEL + + Examples: + + PART #twilight_zone ; leave channel "#twilight_zone" + + PART #oz-ops,&group5 ; leave both channels "&group5" and + "#oz-ops". + +4.2.3 Mode message + + Command: MODE + + The MODE command is a dual-purpose command in IRC. It allows both + usernames and channels to have their mode changed. The rationale for + this choice is that one day nicknames will be obsolete and the + equivalent property will be the channel. + + When parsing MODE messages, it is recommended that the entire message + be parsed first and then the changes which resulted then passed on. + +4.2.3.1 Channel modes + + Parameters: {[+|-]|o|p|s|i|t|n|b|v} [] [] + [] + + The MODE command is provided so that channel operators may change the + characteristics of `their' channel. It is also required that servers + be able to change channel modes so that channel operators may be + created. + + The various modes available for channels are as follows: + + o - give/take channel operator privileges; + p - private channel flag; + s - secret channel flag; + i - invite-only channel flag; + t - topic settable by channel operator only flag; + n - no messages to channel from clients on the outside; + m - moderated channel; + l - set the user limit to channel; + + b - set a ban mask to keep users out; + v - give/take the ability to speak on a moderated channel; + k - set a channel key (password). + + When using the 'o' and 'b' options, a restriction on a total of three + per mode command has been imposed. That is, any combination of 'o' + and + +4.2.3.2 User modes + + Parameters: {[+|-]|i|w|s|o} + + The user MODEs are typically changes which affect either how the + client is seen by others or what 'extra' messages the client is sent. + A user MODE command may only be accepted if both the sender of the + message and the nickname given as a parameter are both the same. + + The available modes are as follows: + + i - marks a users as invisible; + s - marks a user for receipt of server notices; + w - user receives wallops; + o - operator flag. + + Additional modes may be available later on. + + If a user attempts to make themselves an operator using the "+o" + flag, the attempt should be ignored. There is no restriction, + however, on anyone `deopping' themselves (using "-o"). Numeric + Replies: + + ERR_NEEDMOREPARAMS RPL_CHANNELMODEIS + ERR_CHANOPRIVSNEEDED ERR_NOSUCHNICK + ERR_NOTONCHANNEL ERR_KEYSET + RPL_BANLIST RPL_ENDOFBANLIST + ERR_UNKNOWNMODE ERR_NOSUCHCHANNEL + + ERR_USERSDONTMATCH RPL_UMODEIS + ERR_UMODEUNKNOWNFLAG + + Examples: + + Use of Channel Modes: + +MODE #Finnish +im ; Makes #Finnish channel moderated and + 'invite-only'. + +MODE #Finnish +o Kilroy ; Gives 'chanop' privileges to Kilroy on + + channel #Finnish. + +MODE #Finnish +v Wiz ; Allow WiZ to speak on #Finnish. + +MODE #Fins -s ; Removes 'secret' flag from channel + #Fins. + +MODE #42 +k oulu ; Set the channel key to "oulu". + +MODE #eu-opers +l 10 ; Set the limit for the number of users + on channel to 10. + +MODE &oulu +b ; list ban masks set for channel. + +MODE &oulu +b *!*@* ; prevent all users from joining. + +MODE &oulu +b *!*@*.edu ; prevent any user from a hostname + matching *.edu from joining. + + Use of user Modes: + +:MODE WiZ -w ; turns reception of WALLOPS messages + off for WiZ. + +:Angel MODE Angel +i ; Message from Angel to make themselves + invisible. + +MODE WiZ -o ; WiZ 'deopping' (removing operator + status). The plain reverse of this + command ("MODE WiZ +o") must not be + allowed from users since would bypass + the OPER command. + +4.2.4 Topic message + + Command: TOPIC + Parameters: [] + + The TOPIC message is used to change or view the topic of a channel. + The topic for channel is returned if there is no + given. If the parameter is present, the topic for that + channel will be changed, if the channel modes permit this action. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOTONCHANNEL + RPL_NOTOPIC RPL_TOPIC + ERR_CHANOPRIVSNEEDED + + Examples: + + :Wiz TOPIC #test :New topic ;User Wiz setting the topic. + + TOPIC #test :another topic ;set the topic on #test to "another + topic". + + TOPIC #test ; check the topic for #test. + +4.2.5 Names message + + Command: NAMES + Parameters: [{,}] + + By using the NAMES command, a user can list all nicknames that are + visible to them on any channel that they can see. Channel names + which they can see are those which aren't private (+p) or secret (+s) + or those which they are actually on. The parameter + specifies which channel(s) to return information about if valid. + There is no error reply for bad channel names. + + If no parameter is given, a list of all channels and their + occupants is returned. At the end of this list, a list of users who + are visible but either not on any channel or not on a visible channel + are listed as being on `channel' "*". + + Numerics: + + RPL_NAMREPLY RPL_ENDOFNAMES + + Examples: + + NAMES #twilight_zone,#42 ; list visible users on #twilight_zone + and #42 if the channels are visible to + you. + + NAMES ; list all visible channels and users + +4.2.6 List message + + Command: LIST + Parameters: [{,} []] + + The list message is used to list channels and their topics. If the + parameter is used, only the status of that channel + is displayed. Private channels are listed (without their + topics) as channel "Prv" unless the client generating the query is + actually on that channel. Likewise, secret channels are not listed + + at all unless the client is a member of the channel in question. + + Numeric Replies: + + ERR_NOSUCHSERVER RPL_LISTSTART + RPL_LIST RPL_LISTEND + + Examples: + + LIST ; List all channels. + + LIST #twilight_zone,#42 ; List channels #twilight_zone and #42 + +4.2.7 Invite message + + Command: INVITE + Parameters: + + The INVITE message is used to invite users to a channel. The + parameter is the nickname of the person to be invited to + the target channel . There is no requirement that the + channel the target user is being invited to must exist or be a valid + channel. To invite a user to a channel which is invite only (MODE + +i), the client sending the invite must be recognised as being a + channel operator on the given channel. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHNICK + ERR_NOTONCHANNEL ERR_USERONCHANNEL + ERR_CHANOPRIVSNEEDED + RPL_INVITING RPL_AWAY + + Examples: + + :Angel INVITE Wiz #Dust ; User Angel inviting WiZ to channel + #Dust + + INVITE Wiz #Twilight_Zone ; Command to invite WiZ to + #Twilight_zone + +4.2.8 Kick command + + Command: KICK + Parameters: [] + + The KICK command can be used to forcibly remove a user from a + channel. It 'kicks them out' of the channel (forced PART). + + Only a channel operator may kick another user out of a channel. + Each server that receives a KICK message checks that it is valid + (ie the sender is actually a channel operator) before removing + the victim from the channel. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL + ERR_BADCHANMASK ERR_CHANOPRIVSNEEDED + ERR_NOTONCHANNEL + + Examples: + +KICK &Melbourne Matthew ; Kick Matthew from &Melbourne + +KICK #Finnish John :Speaking English + ; Kick John from #Finnish using + "Speaking English" as the reason + (comment). + +:WiZ KICK #Finnish John ; KICK message from WiZ to remove John + from channel #Finnish + +NOTE: + It is possible to extend the KICK command parameters to the +following: + +{,} {,} [] + +4.3 Server queries and commands + + The server query group of commands has been designed to return + information about any server which is connected to the network. All + servers connected must respond to these queries and respond + correctly. Any invalid response (or lack thereof) must be considered + a sign of a broken server and it must be disconnected/disabled as + soon as possible until the situation is remedied. + + In these queries, where a parameter appears as "", it will + usually mean it can be a nickname or a server or a wildcard name of + some sort. For each parameter, however, only one query and set of + replies is to be generated. + +4.3.1 Version message + + Command: VERSION + Parameters: [] + + The VERSION message is used to query the version of the server + program. An optional parameter is used to query the version + of the server program which a client is not directly connected to. + + Numeric Replies: + + ERR_NOSUCHSERVER RPL_VERSION + + Examples: + + :Wiz VERSION *.se ; message from Wiz to check the version + of a server matching "*.se" + + VERSION tolsun.oulu.fi ; check the version of server + "tolsun.oulu.fi". + +4.3.2 Stats message + + Command: STATS + Parameters: [ []] + + The stats message is used to query statistics of certain server. If + parameter is omitted, only the end of stats reply is sent + back. The implementation of this command is highly dependent on the + server which replies, although the server must be able to supply + information as described by the queries below (or similar). + + A query may be given by any single letter which is only checked by + the destination server (if given as the parameter) and is + otherwise passed on by intermediate servers, ignored and unaltered. + The following queries are those found in the current IRC + implementation and provide a large portion of the setup information + for that server. Although these may not be supported in the same way + by other versions, all servers should be able to supply a valid reply + to a STATS query which is consistent with the reply formats currently + used and the purpose of the query. + + The currently supported queries are: + + c - returns a list of servers which the server may connect + to or allow connections from; + h - returns a list of servers which are either forced to be + treated as leaves or allowed to act as hubs; + i - returns a list of hosts which the server allows a client + to connect from; + k - returns a list of banned username/hostname combinations + for that server; + l - returns a list of the server's connections, showing how + + long each connection has been established and the traffic + over that connection in bytes and messages for each + direction; + m - returns a list of commands supported by the server and + the usage count for each if the usage count is non zero; + o - returns a list of hosts from which normal clients may + become operators; + y - show Y (Class) lines from server's configuration file; + u - returns a string showing how long the server has been up. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_STATSCLINE RPL_STATSNLINE + RPL_STATSILINE RPL_STATSKLINE + RPL_STATSQLINE RPL_STATSLLINE + RPL_STATSLINKINFO RPL_STATSUPTIME + RPL_STATSCOMMANDS RPL_STATSOLINE + RPL_STATSHLINE RPL_ENDOFSTATS + + Examples: + +STATS m ; check the command usage for the server + you are connected to + +:Wiz STATS c eff.org ; request by WiZ for C/N line + information from server eff.org + +4.3.3 Links message + + Command: LINKS + Parameters: [[] ] + + With LINKS, a user can list all servers which are known by the server + answering the query. The returned list of servers must match the + mask, or if no mask is given, the full list is returned. + + If is given in addition to , the LINKS + command is forwarded to the first server found that matches that name + (if any), and that server is then required to answer the query. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_LINKS RPL_ENDOFLINKS + + Examples: + +LINKS *.au ; list all servers which have a name + that matches *.au; + +:WiZ LINKS *.bu.edu *.edu ; LINKS message from WiZ to the first + server matching *.edu for a list of + servers matching *.bu.edu. + +4.3.4 Time message + + Command: TIME + Parameters: [] + + The time message is used to query local time from the specified + server. If the server parameter is not given, the server handling the + command must reply to the query. + + Numeric Replies: + + ERR_NOSUCHSERVER RPL_TIME + + Examples: + + TIME tolsun.oulu.fi ; check the time on the server + "tolson.oulu.fi" + + Angel TIME *.au ; user angel checking the time on a + server matching "*.au" + +4.3.5 Connect message + + Command: CONNECT + Parameters: [ []] + + The CONNECT command can be used to force a server to try to establish + a new connection to another server immediately. CONNECT is a + privileged command and is to be available only to IRC Operators. If + a remote server is given then the CONNECT attempt is made by that + server to and . + + Numeric Replies: + + ERR_NOSUCHSERVER ERR_NOPRIVILEGES + ERR_NEEDMOREPARAMS + + Examples: + +CONNECT tolsun.oulu.fi ; Attempt to connect a server to + tolsun.oulu.fi + +:WiZ CONNECT eff.org 6667 csd.bu.edu + ; CONNECT attempt by WiZ to get servers + eff.org and csd.bu.edu connected on port + 6667. + +4.3.6 Trace message + + Command: TRACE + Parameters: [] + + TRACE command is used to find the route to specific server. Each + server that processes this message must tell the sender about it by + sending a reply indicating it is a pass-through link, forming a chain + of replies similar to that gained from using "traceroute". After + sending this reply back, it must then send the TRACE message to the + next server until given server is reached. If the parameter + is omitted, it is recommended that TRACE command send a message to + the sender telling which servers the current server has direct + connection to. + + If the destination given by "" is an actual server, then the + destination server is required to report all servers and users which + are connected to it, although only operators are permitted to see + users present. If the destination given by is a nickname, + they only a reply for that nickname is given. + + Numeric Replies: + + ERR_NOSUCHSERVER + + If the TRACE message is destined for another server, all intermediate + servers must return a RPL_TRACELINK reply to indicate that the TRACE + passed through it and where its going next. + + RPL_TRACELINK + A TRACE reply may be composed of any number of the following numeric + replies. + + RPL_TRACECONNECTING RPL_TRACEHANDSHAKE + RPL_TRACEUNKNOWN RPL_TRACEOPERATOR + RPL_TRACEUSER RPL_TRACESERVER + RPL_TRACESERVICE RPL_TRACENEWTYPE + RPL_TRACECLASS + + Examples: + +TRACE *.oulu.fi ; TRACE to a server matching *.oulu.fi + +:WiZ TRACE AngelDust ; TRACE issued by WiZ to nick AngelDust + +4.3.7 Admin command + + Command: ADMIN + Parameters: [] + + The admin message is used to find the name of the administrator of + the given server, or current server if parameter is omitted. + Each server must have the ability to forward ADMIN messages to other + servers. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_ADMINME RPL_ADMINLOC1 + RPL_ADMINLOC2 RPL_ADMINEMAIL + + Examples: + + ADMIN tolsun.oulu.fi ; request an ADMIN reply from + tolsun.oulu.fi + + :WiZ ADMIN *.edu ; ADMIN request from WiZ for first + server found to match *.edu. + +4.3.8 Info command + + Command: INFO + Parameters: [] + + The INFO command is required to return information which describes + the server: its version, when it was compiled, the patchlevel, when + it was started, and any other miscellaneous information which may be + considered to be relevant. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_INFO RPL_ENDOFINFO + + Examples: + + INFO csd.bu.edu ; request an INFO reply from + csd.bu.edu + + :Avalon INFO *.fi ; INFO request from Avalon for first + server found to match *.fi. + + INFO Angel ; request info from the server that + Angel is connected to. + +4.4 Sending messages + + The main purpose of the IRC protocol is to provide a base for clients + to communicate with each other. PRIVMSG and NOTICE are the only + messages available which actually perform delivery of a text message + from one client to another - the rest just make it possible and try + to ensure it happens in a reliable and structured manner. + +4.4.1 Private messages + + Command: PRIVMSG + Parameters: {,} + + PRIVMSG is used to send private messages between users. + is the nickname of the receiver of the message. can also + be a list of names or channels separated with commas. + + The parameter may also me a host mask (#mask) or server + mask ($mask). In both cases the server will only send the PRIVMSG + to those who have a server or host matching the mask. The mask must + have at least 1 (one) "." in it and no wildcards following the + last ".". This requirement exists to prevent people sending messages + to "#*" or "$*", which would broadcast to all users; from + experience, this is abused more than used responsibly and properly. + Wildcards are the '*' and '?' characters. This extension to + the PRIVMSG command is only available to Operators. + + Numeric Replies: + + ERR_NORECIPIENT ERR_NOTEXTTOSEND + ERR_CANNOTSENDTOCHAN ERR_NOTOPLEVEL + ERR_WILDTOPLEVEL ERR_TOOMANYTARGETS + ERR_NOSUCHNICK + RPL_AWAY + + Examples: + +:Angel PRIVMSG Wiz :Hello are you receiving this message ? + ; Message from Angel to Wiz. + +PRIVMSG Angel :yes I'm receiving it !receiving it !'u>(768u+1n) .br ; + Message to Angel. + +PRIVMSG jto@tolsun.oulu.fi :Hello ! + ; Message to a client on server + + tolsun.oulu.fi with username of "jto". + +PRIVMSG $*.fi :Server tolsun.oulu.fi rebooting. + ; Message to everyone on a server which + has a name matching *.fi. + +PRIVMSG #*.edu :NSFNet is undergoing work, expect interruptions + ; Message to all users who come from a + host which has a name matching *.edu. + +4.4.2 Notice + + Command: NOTICE + Parameters: + + The NOTICE message is used similarly to PRIVMSG. The difference + between NOTICE and PRIVMSG is that automatic replies must never be + sent in response to a NOTICE message. This rule applies to servers + too - they must not send any error reply back to the client on + receipt of a notice. The object of this rule is to avoid loops + between a client automatically sending something in response to + something it received. This is typically used by automatons (clients + with either an AI or other interactive program controlling their + actions) which are always seen to be replying lest they end up in a + loop with another automaton. + + See PRIVMSG for more details on replies and examples. + +4.5 User based queries + + User queries are a group of commands which are primarily concerned + with finding details on a particular user or group users. When using + wildcards with any of these commands, if they match, they will only + return information on users who are 'visible' to you. The visibility + of a user is determined as a combination of the user's mode and the + common set of channels you are both on. + +4.5.1 Who query + + Command: WHO + Parameters: [ []] + + The WHO message is used by a client to generate a query which returns + a list of information which 'matches' the parameter given by + the client. In the absence of the parameter, all visible + (users who aren't invisible (user mode +i) and who don't have a + common channel with the requesting client) are listed. The same + result can be achieved by using a of "0" or any wildcard which + + will end up matching every entry possible. + + The passed to WHO is matched against users' host, server, real + name and nickname if the channel cannot be found. + + If the "o" parameter is passed only operators are returned according + to the name mask supplied. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_WHOREPLY RPL_ENDOFWHO + + Examples: + + WHO *.fi ; List all users who match against + "*.fi". + + WHO jto* o ; List all users with a match against + "jto*" if they are an operator. + +4.5.2 Whois query + + Command: WHOIS + Parameters: [] [,[,...]] + + This message is used to query information about particular user. The + server will answer this message with several numeric messages + indicating different statuses of each user which matches the nickmask + (if you are entitled to see them). If no wildcard is present in the + , any information about that nick which you are allowed to + see is presented. A comma (',') separated list of nicknames may be + given. + + The latter version sends the query to a specific server. It is + useful if you want to know how long the user in question has been + idle as only local server (ie. the server the user is directly + connected to) knows that information, while everything else is + globally known. + + Numeric Replies: + + ERR_NOSUCHSERVER ERR_NONICKNAMEGIVEN + RPL_WHOISUSER RPL_WHOISCHANNELS + RPL_WHOISCHANNELS RPL_WHOISSERVER + RPL_AWAY RPL_WHOISOPERATOR + RPL_WHOISIDLE ERR_NOSUCHNICK + RPL_ENDOFWHOIS + + Examples: + + WHOIS wiz ; return available user information + about nick WiZ + + WHOIS eff.org trillian ; ask server eff.org for user + information about trillian + +4.5.3 Whowas + + Command: WHOWAS + Parameters: [ []] + + Whowas asks for information about a nickname which no longer exists. + This may either be due to a nickname change or the user leaving IRC. + In response to this query, the server searches through its nickname + history, looking for any nicks which are lexically the same (no wild + card matching here). The history is searched backward, returning the + most recent entry first. If there are multiple entries, up to + replies will be returned (or all of them if no + parameter is given). If a non-positive number is passed as being + , then a full search is done. + + Numeric Replies: + + ERR_NONICKNAMEGIVEN ERR_WASNOSUCHNICK + RPL_WHOWASUSER RPL_WHOISSERVER + RPL_ENDOFWHOWAS + + Examples: + + WHOWAS Wiz ; return all information in the nick + history about nick "WiZ"; + + WHOWAS Mermaid 9 ; return at most, the 9 most recent + entries in the nick history for + "Mermaid"; + + WHOWAS Trillian 1 *.edu ; return the most recent history for + "Trillian" from the first server found + to match "*.edu". + +4.6 Miscellaneous messages + + Messages in this category do not fit into any of the above categories + but are nonetheless still a part of and required by the protocol. + +4.6.1 Kill message + + Command: KILL + Parameters: + + The KILL message is used to cause a client-server connection to be + closed by the server which has the actual connection. KILL is used + by servers when they encounter a duplicate entry in the list of valid + nicknames and is used to remove both entries. It is also available + to operators. + + Clients which have automatic reconnect algorithms effectively make + this command useless since the disconnection is only brief. It does + however break the flow of data and can be used to stop large amounts + of being abused, any user may elect to receive KILL messages + generated for others to keep an 'eye' on would be trouble spots. + + In an arena where nicknames are required to be globally unique at all + times, KILL messages are sent whenever 'duplicates' are detected + (that is an attempt to register two users with the same nickname) in + the hope that both of them will disappear and only 1 reappear. + + The comment given must reflect the actual reason for the KILL. For + server-generated KILLs it usually is made up of details concerning + the origins of the two conflicting nicknames. For users it is left + up to them to provide an adequate reason to satisfy others who see + it. To prevent/discourage fake KILLs from being generated to hide + the identify of the KILLer, the comment also shows a 'kill-path' + which is updated by each server it passes through, each prepending + its name to the path. + + Numeric Replies: + + ERR_NOPRIVILEGES ERR_NEEDMOREPARAMS + ERR_NOSUCHNICK ERR_CANTKILLSERVER + + KILL David (csd.bu.edu <- tolsun.oulu.fi) + ; Nickname collision between csd.bu.edu + and tolson.oulu.fi + + NOTE: + It is recommended that only Operators be allowed to kill other users + with KILL message. In an ideal world not even operators would need + to do this and it would be left to servers to deal with. + +4.6.2 Ping message + + Command: PING + Parameters: [] + + The PING message is used to test the presence of an active client at + the other end of the connection. A PING message is sent at regular + intervals if no other activity detected coming from a connection. If + a connection fails to respond to a PING command within a set amount + of time, that connection is closed. + + Any client which receives a PING message must respond to + (server which sent the PING message out) as quickly as possible with + an appropriate PONG message to indicate it is still there and alive. + Servers should not respond to PING commands but rely on PINGs from + the other end of the connection to indicate the connection is alive. + If the parameter is specified, the PING message gets + forwarded there. + + Numeric Replies: + + ERR_NOORIGIN ERR_NOSUCHSERVER + + Examples: + + PING tolsun.oulu.fi ; server sending a PING message to + another server to indicate it is still + alive. + + PING WiZ ; PING message being sent to nick WiZ + +4.6.3 Pong message + + Command: PONG + Parameters: [] + + PONG message is a reply to ping message. If parameter is + given this message must be forwarded to given daemon. The + parameter is the name of the daemon who has responded to PING message + and generated this message. + + Numeric Replies: + + ERR_NOORIGIN ERR_NOSUCHSERVER + + Examples: + + PONG csd.bu.edu tolsun.oulu.fi ; PONG message from csd.bu.edu to + + tolsun.oulu.fi + +4.6.4 Error + + Command: ERROR + Parameters: + + The ERROR command is for use by servers when reporting a serious or + fatal error to its operators. It may also be sent from one server to + another but must not be accepted from any normal unknown clients. + + An ERROR message is for use for reporting errors which occur with a + server-to-server link only. An ERROR message is sent to the server + at the other end (which sends it to all of its connected operators) + and to all operators currently connected. It is not to be passed + onto any other servers by a server if it is received from a server. + + When a server sends a received ERROR message to its operators, the + message should be encapsulated inside a NOTICE message, indicating + that the client was not responsible for the error. + + Numerics: + + None. + + Examples: + + ERROR :Server *.fi already exists; ERROR message to the other server + which caused this error. + + NOTICE WiZ :ERROR from csd.bu.edu -- Server *.fi already exists + ; Same ERROR message as above but sent + to user WiZ on the other server. + +5. OPTIONALS + + This section describes OPTIONAL messages. They are not required in a + working server implementation of the protocol described herein. In + the absence of the option, an error reply message must be generated + or an unknown command error. If the message is destined for another + server to answer then it must be passed on (elementary parsing + required) The allocated numerics for this are listed with the + messages below. + +5.1 Away + + Command: AWAY + Parameters: [message] + + With the AWAY message, clients can set an automatic reply string for + any PRIVMSG commands directed at them (not to a channel they are on). + The automatic reply is sent by the server to client sending the + PRIVMSG command. The only replying server is the one to which the + sending client is connected to. + + The AWAY message is used either with one parameter (to set an AWAY + message) or with no parameters (to remove the AWAY message). + + Numeric Replies: + + RPL_UNAWAY RPL_NOWAWAY + + Examples: + + AWAY :Gone to lunch. Back in 5 ; set away message to "Gone to lunch. + Back in 5". + + :WiZ AWAY ; unmark WiZ as being away. + +5.2 Rehash message + + Command: REHASH + Parameters: None + + The rehash message can be used by the operator to force the server to + re-read and process its configuration file. + + Numeric Replies: + + RPL_REHASHING ERR_NOPRIVILEGES + +Examples: + +REHASH ; message from client with operator + status to server asking it to reread its + configuration file. + +5.3 Restart message + + Command: RESTART + Parameters: None + + The restart message can only be used by an operator to force a server + restart itself. This message is optional since it may be viewed as a + risk to allow arbitrary people to connect to a server as an operator + and execute this command, causing (at least) a disruption to service. + + The RESTART command must always be fully processed by the server to + which the sending client is connected and not be passed onto other + connected servers. + + Numeric Replies: + + ERR_NOPRIVILEGES + + Examples: + + RESTART ; no parameters required. + +5.4 Summon message + + Command: SUMMON + Parameters: [] + + The SUMMON command can be used to give users who are on a host + running an IRC server a message asking them to please join IRC. This + message is only sent if the target server (a) has SUMMON enabled, (b) + the user is logged in and (c) the server process can write to the + user's tty (or similar). + + If no parameter is given it tries to summon from the + server the client is connected to is assumed as the target. + + If summon is not enabled in a server, it must return the + ERR_SUMMONDISABLED numeric and pass the summon message onwards. + + Numeric Replies: + + ERR_NORECIPIENT ERR_FILEERROR + ERR_NOLOGIN ERR_NOSUCHSERVER + RPL_SUMMONING + + Examples: + + SUMMON jto ; summon user jto on the server's host + + SUMMON jto tolsun.oulu.fi ; summon user jto on the host which a + server named "tolsun.oulu.fi" is + running. + +5.5 Users + + Command: USERS + Parameters: [] + + The USERS command returns a list of users logged into the server in a + similar format to who(1), rusers(1) and finger(1). Some people + may disable this command on their server for security related + reasons. If disabled, the correct numeric must be returned to + indicate this. + + Numeric Replies: + + ERR_NOSUCHSERVER ERR_FILEERROR + RPL_USERSSTART RPL_USERS + RPL_NOUSERS RPL_ENDOFUSERS + ERR_USERSDISABLED + + Disabled Reply: + + ERR_USERSDISABLED + + Examples: + +USERS eff.org ; request a list of users logged in on + server eff.org + +:John USERS tolsun.oulu.fi ; request from John for a list of users + logged in on server tolsun.oulu.fi + +5.6 Operwall message + + Command: WALLOPS + Parameters: Text to be sent to all operators currently online + + Sends a message to all operators currently online. After + implementing WALLOPS as a user command it was found that it was + often and commonly abused as a means of sending a message to a lot + of people (much similar to WALL). Due to this it is recommended + that the current implementation of WALLOPS be used as an + example by allowing and recognising only servers as the senders of + WALLOPS. + + Numeric Replies: + + ERR_NEEDMOREPARAMS + + Examples: + + :csd.bu.edu WALLOPS :Connect '*.uiuc.edu 6667' from Joshua; WALLOPS + message from csd.bu.edu announcing a + CONNECT message it received and acted + upon from Joshua. + +5.7 Userhost message + + Command: USERHOST + Parameters: {} + + The USERHOST command takes a list of up to 5 nicknames, each + separated by a space character and returns a list of information + about each nickname that it found. The returned list has each reply + separated by a space. + + Numeric Replies: + + RPL_USERHOST ERR_NEEDMOREPARAMS + + Examples: + + USERHOST Wiz Michael Marty p ;USERHOST request for information on + nicks "Wiz", "Michael", "Marty" and "p" + +5.8 Ison message + + Command: ISON + Parameters: {} + + The ISON command was implemented to provide a quick and efficient + means to get a response about whether a given nickname was currently + on IRC. ISON only takes one (1) parameter: a space-separated list of + nicks. For each nickname in the list that is present, the server + adds that to its reply string. Thus the reply string may return + empty (none of the given nicks are present), an exact copy of the + parameter string (all of them present) or as any other subset of the + set of nicks given in the parameter. The only limit on the number + of nicks that may be checked is that the combined length must not be + too large as to cause the server to chop it off so it fits in 512 + characters. + + ISON is only be processed by the server local to the client sending + the command and thus not passed onto other servers for further + processing. + + Numeric Replies: + + RPL_ISON ERR_NEEDMOREPARAMS + + Examples: + + ISON phone trillian WiZ jarlek Avalon Angel Monstah + ; Sample ISON request for 7 nicks. + +6. REPLIES + + The following is a list of numeric replies which are generated in + response to the commands given above. Each numeric is given with its + number, name and reply string. + +6.1 Error Replies. + + 401 ERR_NOSUCHNICK + " :No such nick/channel" + + - Used to indicate the nickname parameter supplied to a + command is currently unused. + + 402 ERR_NOSUCHSERVER + " :No such server" + + - Used to indicate the server name given currently + doesn't exist. + + 403 ERR_NOSUCHCHANNEL + " :No such channel" + + - Used to indicate the given channel name is invalid. + + 404 ERR_CANNOTSENDTOCHAN + " :Cannot send to channel" + + - Sent to a user who is either (a) not on a channel + which is mode +n or (b) not a chanop (or mode +v) on + a channel which has mode +m set and is trying to send + a PRIVMSG message to that channel. + + 405 ERR_TOOMANYCHANNELS + " :You have joined too many \ + channels" + - Sent to a user when they have joined the maximum + number of allowed channels and they try to join + another channel. + + 406 ERR_WASNOSUCHNICK + " :There was no such nickname" + + - Returned by WHOWAS to indicate there is no history + information for that nickname. + + 407 ERR_TOOMANYTARGETS + " :Duplicate recipients. No message \ + + delivered" + + - Returned to a client which is attempting to send a + PRIVMSG/NOTICE using the user@host destination format + and for a user@host which has several occurrences. + + 409 ERR_NOORIGIN + ":No origin specified" + + - PING or PONG message missing the originator parameter + which is required since these commands must work + without valid prefixes. + + 411 ERR_NORECIPIENT + ":No recipient given ()" + 412 ERR_NOTEXTTOSEND + ":No text to send" + 413 ERR_NOTOPLEVEL + " :No toplevel domain specified" + 414 ERR_WILDTOPLEVEL + " :Wildcard in toplevel domain" + + - 412 - 414 are returned by PRIVMSG to indicate that + the message wasn't delivered for some reason. + ERR_NOTOPLEVEL and ERR_WILDTOPLEVEL are errors that + are returned when an invalid use of + "PRIVMSG $" or "PRIVMSG #" is attempted. + + 421 ERR_UNKNOWNCOMMAND + " :Unknown command" + + - Returned to a registered client to indicate that the + command sent is unknown by the server. + + 422 ERR_NOMOTD + ":MOTD File is missing" + + - Server's MOTD file could not be opened by the server. + + 423 ERR_NOADMININFO + " :No administrative info available" + + - Returned by a server in response to an ADMIN message + when there is an error in finding the appropriate + information. + + 424 ERR_FILEERROR + ":File error doing on " + + - Generic error message used to report a failed file + operation during the processing of a message. + + 431 ERR_NONICKNAMEGIVEN + ":No nickname given" + + - Returned when a nickname parameter expected for a + command and isn't found. + + 432 ERR_ERRONEUSNICKNAME + " :Erroneus nickname" + + - Returned after receiving a NICK message which contains + characters which do not fall in the defined set. See + section x.x.x for details on valid nicknames. + + 433 ERR_NICKNAMEINUSE + " :Nickname is already in use" + + - Returned when a NICK message is processed that results + in an attempt to change to a currently existing + nickname. + + 436 ERR_NICKCOLLISION + " :Nickname collision KILL" + + - Returned by a server to a client when it detects a + nickname collision (registered of a NICK that + already exists by another server). + + 441 ERR_USERNOTINCHANNEL + " :They aren't on that channel" + + - Returned by the server to indicate that the target + user of the command is not on the given channel. + + 442 ERR_NOTONCHANNEL + " :You're not on that channel" + + - Returned by the server whenever a client tries to + perform a channel effecting command for which the + client isn't a member. + + 443 ERR_USERONCHANNEL + " :is already on channel" + + - Returned when a client tries to invite a user to a + channel they are already on. + + 444 ERR_NOLOGIN + " :User not logged in" + + - Returned by the summon after a SUMMON command for a + user was unable to be performed since they were not + logged in. + + 445 ERR_SUMMONDISABLED + ":SUMMON has been disabled" + + - Returned as a response to the SUMMON command. Must be + returned by any server which does not implement it. + + 446 ERR_USERSDISABLED + ":USERS has been disabled" + + - Returned as a response to the USERS command. Must be + returned by any server which does not implement it. + + 451 ERR_NOTREGISTERED + ":You have not registered" + + - Returned by the server to indicate that the client + must be registered before the server will allow it + to be parsed in detail. + + 461 ERR_NEEDMOREPARAMS + " :Not enough parameters" + + - Returned by the server by numerous commands to + indicate to the client that it didn't supply enough + parameters. + + 462 ERR_ALREADYREGISTRED + ":You may not reregister" + + - Returned by the server to any link which tries to + change part of the registered details (such as + password or user details from second USER message). + + 463 ERR_NOPERMFORHOST + ":Your host isn't among the privileged" + + - Returned to a client which attempts to register with + a server which does not been setup to allow + connections from the host the attempted connection + is tried. + + 464 ERR_PASSWDMISMATCH + ":Password incorrect" + + - Returned to indicate a failed attempt at registering + a connection for which a password was required and + was either not given or incorrect. + + 465 ERR_YOUREBANNEDCREEP + ":You are banned from this server" + + - Returned after an attempt to connect and register + yourself with a server which has been setup to + explicitly deny connections to you. + + 467 ERR_KEYSET + " :Channel key already set" + 471 ERR_CHANNELISFULL + " :Cannot join channel (+l)" + 472 ERR_UNKNOWNMODE + " :is unknown mode char to me" + 473 ERR_INVITEONLYCHAN + " :Cannot join channel (+i)" + 474 ERR_BANNEDFROMCHAN + " :Cannot join channel (+b)" + 475 ERR_BADCHANNELKEY + " :Cannot join channel (+k)" + 481 ERR_NOPRIVILEGES + ":Permission Denied- You're not an IRC operator" + + - Any command requiring operator privileges to operate + must return this error to indicate the attempt was + unsuccessful. + + 482 ERR_CHANOPRIVSNEEDED + " :You're not channel operator" + + - Any command requiring 'chanop' privileges (such as + MODE messages) must return this error if the client + making the attempt is not a chanop on the specified + channel. + + 483 ERR_CANTKILLSERVER + ":You cant kill a server!" + + - Any attempts to use the KILL command on a server + are to be refused and this error returned directly + to the client. + + 491 ERR_NOOPERHOST + ":No O-lines for your host" + + - If a client sends an OPER message and the server has + not been configured to allow connections from the + client's host as an operator, this error must be + returned. + + 501 ERR_UMODEUNKNOWNFLAG + ":Unknown MODE flag" + + - Returned by the server to indicate that a MODE + message was sent with a nickname parameter and that + the a mode flag sent was not recognized. + + 502 ERR_USERSDONTMATCH + ":Cant change mode for other users" + + - Error sent to any user trying to view or change the + user mode for a user other than themselves. + +6.2 Command responses. + + 300 RPL_NONE + Dummy reply number. Not used. + + 302 RPL_USERHOST + ":[{}]" + + - Reply format used by USERHOST to list replies to + the query list. The reply string is composed as + follows: + + ::= ['*'] '=' <'+'|'-'> + + The '*' indicates whether the client has registered + as an Operator. The '-' or '+' characters represent + whether the client has set an AWAY message or not + respectively. + + 303 RPL_ISON + ":[ {}]" + + - Reply format used by ISON to list replies to the + query list. + + 301 RPL_AWAY + " :" + + 305 RPL_UNAWAY + ":You are no longer marked as being away" + 306 RPL_NOWAWAY + ":You have been marked as being away" + + - These replies are used with the AWAY command (if + allowed). RPL_AWAY is sent to any client sending a + PRIVMSG to a client which is away. RPL_AWAY is only + sent by the server to which the client is connected. + Replies RPL_UNAWAY and RPL_NOWAWAY are sent when the + client removes and sets an AWAY message. + + 311 RPL_WHOISUSER + " * :" + 312 RPL_WHOISSERVER + " :" + 313 RPL_WHOISOPERATOR + " :is an IRC operator" + 317 RPL_WHOISIDLE + " :seconds idle" + 318 RPL_ENDOFWHOIS + " :End of /WHOIS list" + 319 RPL_WHOISCHANNELS + " :{[@|+]}" + + - Replies 311 - 313, 317 - 319 are all replies + generated in response to a WHOIS message. Given that + there are enough parameters present, the answering + server must either formulate a reply out of the above + numerics (if the query nick is found) or return an + error reply. The '*' in RPL_WHOISUSER is there as + the literal character and not as a wild card. For + each reply set, only RPL_WHOISCHANNELS may appear + more than once (for long lists of channel names). + The '@' and '+' characters next to the channel name + indicate whether a client is a channel operator or + has been granted permission to speak on a moderated + channel. The RPL_ENDOFWHOIS reply is used to mark + the end of processing a WHOIS message. + + 314 RPL_WHOWASUSER + " * :" + 369 RPL_ENDOFWHOWAS + " :End of WHOWAS" + + - When replying to a WHOWAS message, a server must use + the replies RPL_WHOWASUSER, RPL_WHOISSERVER or + ERR_WASNOSUCHNICK for each nickname in the presented + + list. At the end of all reply batches, there must + be RPL_ENDOFWHOWAS (even if there was only one reply + and it was an error). + + 321 RPL_LISTSTART + "Channel :Users Name" + 322 RPL_LIST + " <# visible> :" + 323 RPL_LISTEND + ":End of /LIST" + + - Replies RPL_LISTSTART, RPL_LIST, RPL_LISTEND mark + the start, actual replies with data and end of the + server's response to a LIST command. If there are + no channels available to return, only the start + and end reply must be sent. + + 324 RPL_CHANNELMODEIS + " " + + 331 RPL_NOTOPIC + " :No topic is set" + 332 RPL_TOPIC + " :" + + - When sending a TOPIC message to determine the + channel topic, one of two replies is sent. If + the topic is set, RPL_TOPIC is sent back else + RPL_NOTOPIC. + + 341 RPL_INVITING + " " + + - Returned by the server to indicate that the + attempted INVITE message was successful and is + being passed onto the end client. + + 342 RPL_SUMMONING + " :Summoning user to IRC" + + - Returned by a server answering a SUMMON message to + indicate that it is summoning that user. + + 351 RPL_VERSION + ". :" + + - Reply by the server showing its version details. + The is the version of the software being + + used (including any patchlevel revisions) and the + is used to indicate if the server is + running in "debug mode". + + The "comments" field may contain any comments about + the version or further version details. + + 352 RPL_WHOREPLY + " \ + [*][@|+] : " + 315 RPL_ENDOFWHO + " :End of /WHO list" + + - The RPL_WHOREPLY and RPL_ENDOFWHO pair are used + to answer a WHO message. The RPL_WHOREPLY is only + sent if there is an appropriate match to the WHO + query. If there is a list of parameters supplied + with a WHO message, a RPL_ENDOFWHO must be sent + after processing each list item with being + the item. + + 353 RPL_NAMREPLY + " :[[@|+] [[@|+] [...]]]" + 366 RPL_ENDOFNAMES + " :End of /NAMES list" + + - To reply to a NAMES message, a reply pair consisting + of RPL_NAMREPLY and RPL_ENDOFNAMES is sent by the + server back to the client. If there is no channel + found as in the query, then only RPL_ENDOFNAMES is + returned. The exception to this is when a NAMES + message is sent with no parameters and all visible + channels and contents are sent back in a series of + RPL_NAMEREPLY messages with a RPL_ENDOFNAMES to mark + the end. + + 364 RPL_LINKS + " : " + 365 RPL_ENDOFLINKS + " :End of /LINKS list" + + - In replying to the LINKS message, a server must send + replies back using the RPL_LINKS numeric and mark the + end of the list using an RPL_ENDOFLINKS reply. + + 367 RPL_BANLIST + " " + 368 RPL_ENDOFBANLIST + + " :End of channel ban list" + + - When listing the active 'bans' for a given channel, + a server is required to send the list back using the + RPL_BANLIST and RPL_ENDOFBANLIST messages. A separate + RPL_BANLIST is sent for each active banid. After the + banids have been listed (or if none present) a + RPL_ENDOFBANLIST must be sent. + + 371 RPL_INFO + ":" + 374 RPL_ENDOFINFO + ":End of /INFO list" + + - A server responding to an INFO message is required to + send all its 'info' in a series of RPL_INFO messages + with a RPL_ENDOFINFO reply to indicate the end of the + replies. + + 375 RPL_MOTDSTART + ":- Message of the day - " + 372 RPL_MOTD + ":- " + 376 RPL_ENDOFMOTD + ":End of /MOTD command" + + - When responding to the MOTD message and the MOTD file + is found, the file is displayed line by line, with + each line no longer than 80 characters, using + RPL_MOTD format replies. These should be surrounded + by a RPL_MOTDSTART (before the RPL_MOTDs) and an + RPL_ENDOFMOTD (after). + + 381 RPL_YOUREOPER + ":You are now an IRC operator" + + - RPL_YOUREOPER is sent back to a client which has + just successfully issued an OPER message and gained + operator status. + + 382 RPL_REHASHING + " :Rehashing" + + - If the REHASH option is used and an operator sends + a REHASH message, an RPL_REHASHING is sent back to + the operator. + + 391 RPL_TIME + + " :" + + - When replying to the TIME message, a server must send + the reply using the RPL_TIME format above. The string + showing the time need only contain the correct day and + time there. There is no further requirement for the + time string. + + 392 RPL_USERSSTART + ":UserID Terminal Host" + 393 RPL_USERS + ":%-8s %-9s %-8s" + 394 RPL_ENDOFUSERS + ":End of users" + 395 RPL_NOUSERS + ":Nobody logged in" + + - If the USERS message is handled by a server, the + replies RPL_USERSTART, RPL_USERS, RPL_ENDOFUSERS and + RPL_NOUSERS are used. RPL_USERSSTART must be sent + first, following by either a sequence of RPL_USERS + or a single RPL_NOUSER. Following this is + RPL_ENDOFUSERS. + + 200 RPL_TRACELINK + "Link \ + " + 201 RPL_TRACECONNECTING + "Try. " + 202 RPL_TRACEHANDSHAKE + "H.S. " + 203 RPL_TRACEUNKNOWN + "???? []" + 204 RPL_TRACEOPERATOR + "Oper " + 205 RPL_TRACEUSER + "User " + 206 RPL_TRACESERVER + "Serv S C \ + @" + 208 RPL_TRACENEWTYPE + " 0 " + 261 RPL_TRACELOG + "File " + + - The RPL_TRACE* are all returned by the server in + response to the TRACE message. How many are + returned is dependent on the the TRACE message and + + whether it was sent by an operator or not. There + is no predefined order for which occurs first. + Replies RPL_TRACEUNKNOWN, RPL_TRACECONNECTING and + RPL_TRACEHANDSHAKE are all used for connections + which have not been fully established and are either + unknown, still attempting to connect or in the + process of completing the 'server handshake'. + RPL_TRACELINK is sent by any server which handles + a TRACE message and has to pass it on to another + server. The list of RPL_TRACELINKs sent in + response to a TRACE command traversing the IRC + network should reflect the actual connectivity of + the servers themselves along that path. + RPL_TRACENEWTYPE is to be used for any connection + which does not fit in the other categories but is + being displayed anyway. + + 211 RPL_STATSLINKINFO + " \ + \ +