"Fossies" - the Fresh Open Source Software Archive

Member "ircd-hybrid-8.2.26/doc/technical/rfc2813.txt" (31 May 2019, 52695 Bytes) of package /linux/privat/ircd-hybrid-8.2.26.tgz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Network Working Group                                           C. Kalt
    2 Request for Comments: 2813                                   April 2000
    3 Updates: 1459
    4 Category: Informational
    6                   Internet Relay Chat: Server Protocol
    8 Status of this Memo
   10    This memo provides information for the Internet community.  It does
   11    not specify an Internet standard of any kind.  Distribution of this
   12    memo is unlimited.
   14 Copyright Notice
   16    Copyright (C) The Internet Society (2000).  All Rights Reserved.
   18 Abstract
   20    While based on the client-server model, the IRC (Internet Relay Chat)
   21    protocol allows servers to connect to each other effectively forming
   22    a network.
   24    This document defines the protocol used by servers to talk to each
   25    other.  It was originally a superset of the client protocol but has
   26    evolved differently.
   28    First formally documented in May 1993 as part of RFC 1459 [IRC], most
   29    of the changes brought since then can be found in this document as
   30    development was focused on making the protocol scale better.  Better
   31    scalability has allowed existing world-wide networks to keep growing
   32    and reach sizes which defy the old specification.
   34 Table of Contents
   36    1.  Introduction ...............................................   3
   37    2.  Global database ............................................   3
   38       2.1  Servers ................................................   3
   39       2.2  Clients ................................................   4
   40          2.2.1  Users .............................................   4
   41          2.2.2  Services ..........................................   4
   42       2.3  Channels ...............................................   4
   43    3.  The IRC Server Specification ...............................   5
   44       3.1  Overview ...............................................   5
   45       3.2  Character codes ........................................   5
   46       3.3  Messages ...............................................   5
   47          3.3.1  Message format in Augmented BNF ...................   6
   48       3.4  Numeric replies ........................................   7
   49    4.  Message Details ............................................   7
   50       4.1  Connection Registration ................................   8
   51          4.1.1  Password message ..................................   8
   52          4.1.2  Server message ....................................   9
   53          4.1.3  Nick ..............................................  10
   54          4.1.4  Service message ...................................  11
   55          4.1.5  Quit ..............................................  12
   56          4.1.6  Server quit message ...............................  13
   57       4.2  Channel operations .....................................  14
   58          4.2.1  Join message ......................................  14
   59          4.2.2  Njoin message .....................................  15
   60          4.2.3  Mode message ......................................  16
   61    5.  Implementation details  ....................................  16
   62       5.1  Connection 'Liveness' ..................................  16
   63       5.2  Accepting a client to server connection ................  16
   64          5.2.1  Users .............................................  16
   65          5.2.2  Services ..........................................  17
   66       5.3  Establishing a server-server connection. ...............  17
   67          5.3.1  Link options ......................................  17
   68     Compressed server to server links ............  18
   69     Anti abuse protections .......................  18
   70          5.3.2  State information exchange when connecting ........  18
   71       5.4  Terminating server-client connections ..................  19
   72       5.5  Terminating server-server connections ..................  19
   73       5.6  Tracking nickname changes ..............................  19
   74       5.7  Tracking recently used nicknames .......................  20
   75       5.8  Flood control of clients ...............................  20
   76       5.9  Non-blocking lookups ...................................  21
   77          5.9.1  Hostname (DNS) lookups ............................  21
   78          5.9.2  Username (Ident) lookups ..........................  21
   79    6.  Current problems ...........................................  21
   80       6.1  Scalability ............................................  21
   81       6.2  Labels .................................................  22
   83          6.2.1  Nicknames .........................................  22
   84          6.2.2  Channels ..........................................  22
   85          6.2.3  Servers ...........................................  22
   86       6.3  Algorithms .............................................  22
   87    7.  Security Considerations ....................................  23
   88       7.1  Authentication .........................................  23
   89       7.2  Integrity ..............................................  23
   90    8.  Current support and availability ...........................  24
   91    9.  Acknowledgements ...........................................  24
   92    10.  References ................................................  24
   93    11.  Author's Address ..........................................  25
   94    12. Full Copyright Statement ...................................  26
   96 1. Introduction
   98    This document is intended for people working on implementing an IRC
   99    server but will also be useful to anyone implementing an IRC service.
  101    Servers provide the three basic services required for realtime
  102    conferencing defined by the "Internet Relay Chat: Architecture"
  103    [IRC-ARCH]: client locator (via the client protocol [IRC-CLIENT]),
  104    message relaying (via the server protocol defined in this document)
  105    and channel hosting and management (following specific rules [IRC-
  106    CHAN]).
  108 2. Global database
  110    Although the IRC Protocol defines a fairly distributed model, each
  111    server maintains a "global state database" about the whole IRC
  112    network.  This database is, in theory, identical on all servers.
  114 2.1 Servers
  116    Servers are uniquely identified by their name which has a maximum
  117    length of sixty three (63) characters.  See the protocol grammar
  118    rules (section 3.3.1) for what may and may not be used in a server
  119    name.
  121    Each server is typically known by all other servers, however it is
  122    possible to define a "hostmask" to group servers together according
  123    to their name.  Inside the hostmasked area, all the servers have a
  124    name which matches the hostmask, and any other server with a name
  125    matching the hostmask SHALL NOT be connected to the IRC network
  126    outside the hostmasked area.  Servers which are outside the area have
  127    no knowledge of the individual servers present inside the area,
  128    instead they are presented with a virtual server which has the
  129    hostmask for name.
  131 2.2 Clients
  133    For each client, all servers MUST have the following information: a
  134    netwide unique identifier (whose format depends on the type of
  135    client) and the server to which the client is connected.
  137 2.2.1 Users
  139    Each user is distinguished from other users by a unique nickname
  140    having a maximum length of nine (9) characters.  See the protocol
  141    grammar rules (section 3.3.1) for what may and may not be used in a
  142    nickname.  In addition to the nickname, all servers MUST have the
  143    following information about all users: the name of the host that the
  144    user is running on, the username of the user on that host, and the
  145    server to which the client is connected.
  147 2.2.2 Services
  149    Each service is distinguished from other services by a service name
  150    composed of a nickname and a server name.  The nickname has a maximum
  151    length of nine (9) characters.  See the protocol grammar rules
  152    (section 3.3.1) for what may and may not be used in a nickname.  The
  153    server name used to compose the service name is the name of the
  154    server to which the service is connected.  In addition to this
  155    service name all servers MUST know the service type.
  157    Services differ from users by the format of their identifier, but
  158    more importantly services and users don't have the same type of
  159    access to the server: services can request part or all of the global
  160    state information that a server maintains, but have a more restricted
  161    set of commands available to them (See "IRC Client Protocol" [IRC-
  162    CLIENT] for details on which) and are not allowed to join channels.
  163    Finally services are not usually subject to the "Flood control"
  164    mechanism described in section 5.8.
  166 2.3 Channels
  168    Alike services, channels have a scope [IRC-CHAN] and are not
  169    necessarily known to all servers.  When a channel existence is known
  170    to a server, the server MUST keep track of the channel members, as
  171    well as the channel modes.
  173 3. The IRC Server Specification
  175 3.1 Overview
  177    The protocol as described herein is for use with server to server
  178    connections.  For client to server connections, see the IRC Client
  179    Protocol specification.
  181    There are, however, more restrictions on client connections (which
  182    are considered to be untrustworthy) than on server connections.
  184 3.2 Character codes
  186    No specific character set is specified. The protocol is based on a a
  187    set of codes which are composed of eight (8) bits, making up an
  188    octet.  Each message may be composed of any number of these octets;
  189    however, some octet values are used for control codes which act as
  190    message delimiters.
  192    Regardless of being an 8-bit protocol, the delimiters and keywords
  193    are such that protocol is mostly usable from US-ASCII terminal and a
  194    telnet connection.
  196    Because of IRC's Scandinavian origin, the characters {}|^ are
  197    considered to be the lower case equivalents of the characters []\~,
  198    respectively. This is a critical issue when determining the
  199    equivalence of two nicknames, or channel names.
  201 3.3 Messages
  203    Servers and clients send each other messages which may or may not
  204    generate a reply.  Most communication between servers do not generate
  205    any reply, as servers mostly perform routing tasks for the clients.
  207    Each IRC message may consist of up to three main parts: the prefix
  208    (OPTIONAL), the command, and the command parameters (maximum of
  209    fifteen (15)).  The prefix, command, and all parameters are separated
  210    by one ASCII space character (0x20) each.
  212    The presence of a prefix is indicated with a single leading ASCII
  213    colon character (':', 0x3b), which MUST be the first character of the
  214    message itself.  There MUST be NO gap (whitespace) between the colon
  215    and the prefix.  The prefix is used by servers to indicate the true
  216    origin of the message.  If the prefix is missing from the message, it
  217    is assumed to have originated from the connection from which it was
  218    received.  Clients SHOULD not use a prefix when sending a message
  219    from themselves; if they use one, the only valid prefix is the
  220    registered nickname associated with the client.
  222    When a server receives a message, it MUST identify its source using
  223    the (eventually assumed) prefix.  If the prefix cannot be found in
  224    the server's internal database, it MUST be discarded, and if the
  225    prefix indicates the message comes from an (unknown) server, the link
  226    from which the message was received MUST be dropped.  Dropping a link
  227    in such circumstances is a little excessive but necessary to maintain
  228    the integrity of the network and to prevent future problems.  Another
  229    common error condition is that the prefix found in the server's
  230    internal database identifies a different source (typically a source
  231    registered from a different link than from which the message
  232    arrived).  If the message was received from a server link and the
  233    prefix identifies a client, a KILL message MUST be issued for the
  234    client and sent to all servers.  In other cases, the link from which
  235    the message arrived SHOULD be dropped for clients, and MUST be
  236    dropped for servers.  In all cases, the message MUST be discarded.
  238    The command MUST either be a valid IRC command or a three (3) digit
  239    number represented in ASCII text.
  241    IRC messages are always lines of characters terminated with a CR-LF
  242    (Carriage Return - Line Feed) pair, and these messages SHALL NOT
  243    exceed 512 characters in length, counting all characters including
  244    the trailing CR-LF. Thus, there are 510 characters maximum allowed
  245    for the command and its parameters.  There is no provision for
  246    continuation message lines.  See section 5 for more details about
  247    current implementations.
  249 3.3.1 Message format in Augmented BNF
  251    The protocol messages must be extracted from the contiguous stream of
  252    octets.  The current solution is to designate two characters, CR and
  253    LF, as message separators.  Empty messages are silently ignored,
  254    which permits use of the sequence CR-LF between messages without
  255    extra problems.
  257    The extracted message is parsed into the components <prefix>,
  258    <command> and list of parameters (<params>).
  260    The Augmented BNF representation for this is found in "IRC Client
  261    Protocol" [IRC-CLIENT].
  263    The extended prefix (["!" user "@" host ]) MUST NOT be used in server
  264    to server communications and is only intended for server to client
  265    messages in order to provide clients with more useful information
  266    about who a message is from without the need for additional queries.
  268 3.4 Numeric replies
  270    Most of the messages sent to the server generate a reply of some
  271    sort.  The most common reply is the numeric reply, used for both
  272    errors and normal replies.  The numeric reply MUST be sent as one
  273    message consisting of the sender prefix, the three digit numeric, and
  274    the target of the reply.  A numeric reply is not allowed to originate
  275    from a client; any such messages received by a server are silently
  276    dropped. In all other respects, a numeric reply is just like a normal
  277    message, except that the keyword is made up of 3 numeric digits
  278    rather than a string of letters.  A list of different replies is
  279    supplied in "IRC Client Protocol" [IRC-CLIENT].
  281 4. Message Details
  283    All the messages recognized by the IRC server and client are
  284    described in the IRC Client Protocol specification.
  286    Where the reply ERR_NOSUCHSERVER is returned, it means that the
  287    target of the message could not be found.  The server MUST NOT send
  288    any other replies after this error for that command.
  290    The server to which a client is connected is required to parse the
  291    complete message, returning any appropriate errors.  If the server
  292    encounters a fatal error while parsing a message, an error MUST be
  293    sent back to the client and the parsing terminated.  A fatal error
  294    may follow from incorrect command, a destination which is otherwise
  295    unknown to the server (server, client or channel names fit this
  296    category), not enough parameters or incorrect privileges.
  298    If a full set of parameters is presented, then each MUST be checked
  299    for validity and appropriate responses sent back to the client.  In
  300    the case of messages which use parameter lists using the comma as an
  301    item separator, a reply MUST be sent for each item.
  303    In the examples below, some messages appear using the full format:
  305    :Name COMMAND parameter list
  307    Such examples represent a message from "Name" in transit between
  308    servers, where it is essential to include the name of the original
  309    sender of the message so remote servers may send back a reply along
  310    the correct path.
  312    The message details for client to server communication are described
  313    in the "IRC Client Protocol" [IRC-CLIENT].  Some sections in the
  314    following pages apply to some of these messages, they are additions
  315    to the message specifications which are only relevant to server to
  317    server communication, or to the server implementation.  The messages
  318    which are introduced here are only used for server to server
  319    communication.
  321 4.1 Connection Registration
  323    The commands described here are used to register a connection with
  324    another IRC server.
  326 4.1.1 Password message
  328       Command: PASS
  329    Parameters: <password> <version> <flags> [<options>]
  331    The PASS command is used to set a 'connection password'.  The
  332    password MUST be set before any attempt to register the connection is
  333    made.  Currently this means that servers MUST send a PASS command
  334    before any SERVER command.  Only one (1) PASS command SHALL be
  335    accepted from a connection.
  337    The last three (3) parameters MUST be ignored if received from a
  338    client (e.g. a user or a service).  They are only relevant when
  339    received from a server.
  341    The <version> parameter is a string of at least four (4) characters,
  342    and up to fourteen (14) characters.  The first four (4) characters
  343    MUST be digits and indicate the protocol version known by the server
  344    issuing the message.  The protocol described by this document is
  345    version 2.10 which is encoded as "0210".  The remaining OPTIONAL
  346    characters are implementation dependent and should describe the
  347    software version number.
  349    The <flags> parameter is a string of up to one hundred (100)
  350    characters.  It is composed of two substrings separated by the
  351    character "|" (%x7C).  If present, the first substring MUST be the
  352    name of the implementation.  The reference implementation (See
  353    Section 8, "Current support and availability") uses the string "IRC".
  354    If a different implementation is written, which needs an identifier,
  355    then that identifier should be registered through publication of an
  356    RFC. The second substring is implementation dependent.  Both
  357    substrings are OPTIONAL, but the character "|" is REQUIRED.  The
  358    character "|" MUST NOT appear in either substring.
  360    Finally, the last parameter, <options>, is used for link options.
  361    The only options defined by the protocol are link compression (using
  362    the character "Z"), and an abuse protection flag (using the character
  364    "P").  See sections (Compressed server to server links) and
  365 (Anti abuse protections) respectively for more information on
  366    these options.
  368    Numeric Replies:
  372    Example:
  374         PASS moresecretpassword 0210010000 IRC|aBgH$ Z
  376 4.1.2 Server message
  378       Command: SERVER
  379    Parameters: <servername> <hopcount> <token> <info>
  381    The SERVER command is used to register a new server. A new connection
  382    introduces itself as a server to its peer.  This message is also used
  383    to pass server data over whole net.  When a new server is connected
  384    to net, information about it MUST be broadcasted to the whole
  385    network.
  387    The <info> parameter may contain space characters.
  389    <hopcount> is used to give all servers some internal information on
  390    how far away each server is.  Local peers have a value of 0, and each
  391    passed server increments the value.  With a full server list, it
  392    would be possible to construct a map of the entire server tree, but
  393    hostmasks prevent this from being done.
  395    The <token> parameter is an unsigned number used by servers as an
  396    identifier.  This identifier is subsequently used to reference a
  397    server in the NICK and SERVICE messages sent between servers.  Server
  398    tokens only have a meaning for the point-to-point peering they are
  399    used and MUST be unique for that connection.  They are not global.
  401    The SERVER message MUST only be accepted from either (a) a connection
  402    which is yet to be registered and is attempting to register as a
  403    server, or (b) an existing connection to another server, in which
  404    case the SERVER message is introducing a new server behind that
  405    server.
  407    Most errors that occur with the receipt of a SERVER command result in
  408    the connection being terminated by the destination host (target
  409    SERVER).  Because of the severity of such event, error replies are
  410    usually sent using the "ERROR" command rather than a numeric.
  412    If a SERVER message is parsed and it attempts to introduce a server
  413    which is already known to the receiving server, the connection, from
  414    which that message arrived, MUST be closed (following the correct
  415    procedures), since a duplicate route to a server has been formed and
  416    the acyclic nature of the IRC tree breaks.  In some conditions, the
  417    connection from which the already known server has registered MAY be
  418    closed instead.  It should be noted that this kind of error can also
  419    be the result of a second running server, problem which cannot be
  420    fixed within the protocol and typically requires human intervention.
  421    This type of problem is particularly insidious, as it can quite
  422    easily result in part of the IRC network to be isolated, with one of
  423    the two servers connected to each partition therefore making it
  424    impossible for the two parts to unite.
  426    Numeric Replies:
  430    Example:
  432    SERVER test.oulu.fi 1 1 :Experimental server ; New server
  433                                    test.oulu.fi introducing itself and
  434                                    attempting to register.
  436    :tolsun.oulu.fi SERVER csd.bu.edu 5 34 :BU Central Server ; Server
  437                                    tolsun.oulu.fi is our uplink for
  438                                    csd.bu.edu which is 5 hops away.  The
  439                                    token "34" will be used by
  440                                    tolsun.oulu.fi when introducing new
  441                                    users or services connected to
  442                                    csd.bu.edu.
  444 4.1.3 Nick
  446       Command: NICK
  447    Parameters: <nickname> <hopcount> <username> <host> <servertoken>
  448                <umode> <realname>
  450    This form of the NICK message MUST NOT be allowed from user
  451    connections. However, it MUST be used instead of the NICK/USER pair
  452    to notify other servers of new users joining the IRC network.
  454    This message is really the combination of three distinct messages:
  455    NICK, USER and MODE [IRC-CLIENT].
  457    The <hopcount> parameter is used by servers to indicate how far away
  458    a user is from its home server.  A local connection has a hopcount of
  459    0.  The hopcount value is incremented by each passed server.
  461    The <servertoken> parameter replaces the <servername> parameter of
  462    the USER (See section 4.1.2 for more information on server tokens).
  464    Examples:
  466    NICK syrk 5 kalt millennium.stealth.net 34 +i :Christophe Kalt ; New
  467                                    user with nickname "syrk", username
  468                                    "kalt", connected from host
  469                                    "millennium.stealth.net" to server
  470                                    "34" ("csd.bu.edu" according to the
  471                                    previous example).
  473    :krys NICK syrk                 ; The other form of the NICK message,
  474                                    as defined in "IRC Client Protocol"
  475                                    [IRC-CLIENT] and used between
  476                                    servers: krys changed his nickname to
  477                                    syrk
  479 4.1.4 Service message
  481       Command: SERVICE
  482    Parameters: <servicename> <servertoken> <distribution> <type>
  483                 <hopcount> <info>
  485    The SERVICE command is used to introduce a new service.  This form of
  486    the SERVICE message SHOULD NOT be allowed from client (unregistered,
  487    or registered) connections.  However, it MUST be used between servers
  488    to notify other servers of new services joining the IRC network.
  490    The <servertoken> is used to identify the server to which the service
  491    is connected.  (See section 4.1.2 for more information on server
  492    tokens).
  494    The <hopcount> parameter is used by servers to indicate how far away
  495    a service is from its home server.  A local connection has a hopcount
  496    of 0.  The hopcount value is incremented by each passed server.
  498    The <distribution> parameter is used to specify the visibility of a
  499    service.  The service may only be known to servers which have a name
  500    matching the distribution.  For a matching server to have knowledge
  501    of the service, the network path between that server and the server
  502    to which the service is connected MUST be composed of servers whose
  503    names all match the mask.  Plain "*" is used when no restriction is
  504    wished.
  506    The <type> parameter is currently reserved for future usage.
  508    Numeric Replies:
  512            RPL_YOURESERVICE                RPL_YOURHOST
  513            RPL_MYINFO
  515    Example:
  517 SERVICE dict@irc.fr 9 *.fr 0 1 :French Dictionary r" registered on
  518                                    server "9" is being announced to
  519                                    another server.  This service will
  520                                    only be available on servers whose
  521                                    name matches "*.fr".
  523 4.1.5 Quit
  525       Command: QUIT
  526    Parameters: [<Quit Message>]
  528    A client session ends with a quit message.  The server MUST close the
  529    connection to a client which sends a QUIT message. If a "Quit
  530    Message" is given, this will be sent instead of the default message,
  531    the nickname or service name.
  533    When "netsplit" (See Section 4.1.6) occur, the "Quit Message" is
  534    composed of the names of two servers involved, separated by a space.
  535    The first name is that of the server which is still connected and the
  536    second name is either that of the server which has become
  537    disconnected or that of the server to which the leaving client was
  538    connected:
  540       <Quit Message> =  ":" servername SPACE servername
  542    Because the "Quit Message" has a special meaning for "netsplits",
  543    servers SHOULD NOT allow a client to use a <Quit Message> in the
  544    format described above.
  546    If, for some other reason, a client connection is closed without the
  547    client issuing a QUIT command (e.g. client dies and EOF occurs on
  548    socket), the server is REQUIRED to fill in the quit message with some
  549    sort of message reflecting the nature of the event which caused it to
  550    happen.  Typically, this is done by reporting a system specific
  551    error.
  553    Numeric Replies:
  555            None.
  557    Examples:
  559    :WiZ QUIT :Gone to have lunch   ; Preferred message format.
  561 4.1.6 Server quit message
  563       Command: SQUIT
  564    Parameters: <server> <comment>
  566    The SQUIT message has two distinct uses.
  568    The first one (described in "Internet Relay Chat: Client Protocol"
  569    [IRC-CLIENT]) allows operators to break a local or remote server
  570    link.  This form of the message is also eventually used by servers to
  571    break a remote server link.
  573    The second use of this message is needed to inform other servers when
  574    a "network split" (also known as "netsplit") occurs, in other words
  575    to inform other servers about quitting or dead servers.  If a server
  576    wishes to break the connection to another server it MUST send a SQUIT
  577    message to the other server, using the name of the other server as
  578    the server parameter, which then closes its connection to the
  579    quitting server.
  581    The <comment> is filled in by servers which SHOULD place an error or
  582    similar message here.
  584    Both of the servers which are on either side of the connection being
  585    closed are REQUIRED to send out a SQUIT message (to all its other
  586    server connections) for all other servers which are considered to be
  587    behind that link.
  589    Similarly, a QUIT message MAY be sent to the other still connected
  590    servers on behalf of all clients behind that quitting link.  In
  591    addition to this, all channel members of a channel which lost a
  592    member due to the "split" MUST be sent a QUIT message.  Messages to
  593    channel members are generated by each client's local server.
  595    If a server connection is terminated prematurely (e.g., the server on
  596    the other end of the link died), the server which detects this
  597    disconnection is REQUIRED to inform the rest of the network that the
  598    connection has closed and fill in the comment field with something
  599    appropriate.
  601    When a client is removed as the result of a SQUIT message, the server
  602    SHOULD add the nickname to the list of temporarily unavailable
  603    nicknames in an attempt to prevent future nickname collisions. See
  605    section 5.7 (Tracking recently used nicknames) for more information
  606    on this procedure.
  608    Numeric replies:
  610            ERR_NOPRIVILEGES                ERR_NOSUCHSERVER
  611            ERR_NEEDMOREPARAMS
  613    Example:
  615    SQUIT tolsun.oulu.fi :Bad Link ?  ; the server link tolson.oulu.fi
  616                                    has been terminated because of "Bad
  617                                    Link".
  619    :Trillian SQUIT cm22.eng.umd.edu :Server out of control ; message
  620                                    from Trillian to disconnect
  621                                    "cm22.eng.umd.edu" from the net
  622                                    because "Server out of control".
  624 4.2 Channel operations
  626    This group of messages is concerned with manipulating channels, their
  627    properties (channel modes), and their contents (typically users).  In
  628    implementing these, a number of race conditions are inevitable when
  629    users at opposing ends of a network send commands which will
  630    ultimately clash.  It is also REQUIRED that servers keep a nickname
  631    history to ensure that wherever a <nick> parameter is given, the
  632    server check its history in case it has recently been changed.
  634 4.2.1 Join message
  636       Command: JOIN
  637    Parameters: <channel>[ %x7 <modes> ]
  638                *( "," <channel>[ %x7 <modes> ] )
  640    The JOIN command is used by client to start listening a specific
  641    channel. Whether or not a client is allowed to join a channel is
  642    checked only by the local server the client is connected to; all
  643    other servers automatically add the user to the channel when the
  644    command is received from other servers.
  646    Optionally, the user status (channel modes 'O', 'o', and 'v') on the
  647    channel may be appended to the channel name using a control G (^G or
  648    ASCII 7) as separator.  Such data MUST be ignored if the message
  649    wasn't received from a server.  This format MUST NOT be sent to
  650    clients, it can only be used between servers and SHOULD be avoided.
  652    The JOIN command MUST be broadcast to all servers so that each server
  653    knows where to find the users who are on the channel.  This allows
  654    optimal delivery of PRIVMSG and NOTICE messages to the channel.
  656    Numeric Replies:
  659            ERR_INVITEONLYCHAN              ERR_BADCHANNELKEY
  660            ERR_CHANNELISFULL               ERR_BADCHANMASK
  661            ERR_NOSUCHCHANNEL               ERR_TOOMANYCHANNELS
  663            RPL_TOPIC
  665    Examples:
  667    :WiZ JOIN #Twilight_zone        ; JOIN message from WiZ
  669 4.2.2 Njoin message
  671       Command: NJOIN
  672    Parameters: <channel> [ "@@" / "@" ] [ "+" ] <nickname>
  673                          *( "," [ "@@" / "@" ] [ "+" ] <nickname> )
  675    The NJOIN message is used between servers only.  If such a message is
  676    received from a client, it MUST be ignored.  It is used when two
  677    servers connect to each other to exchange the list of channel members
  678    for each channel.
  680    Even though the same function can be performed by using a succession
  681    of JOIN, this message SHOULD be used instead as it is more efficient.
  682    The prefix "@@" indicates that the user is the "channel creator", the
  683    character "@" alone indicates a "channel operator", and the character
  684    '+' indicates that the user has the voice privilege.
  686    Numeric Replies:
  688            ERR_NEEDMOREPARAMS              ERR_NOSUCHCHANNEL
  691    Examples:
  693    :ircd.stealth.net NJOIN #Twilight_zone :@WiZ,+syrk,avalon ; NJOIN
  694                                    message from ircd.stealth.net
  695                                    announcing users joining the
  696                                    #Twilight_zone channel: WiZ with
  697                                    channel operator status, syrk with
  698                                    voice privilege and avalon with no
  699                                    privilege.
  701 4.2.3 Mode message
  703    The MODE message is a dual-purpose command in IRC.  It allows both
  704    usernames and channels to have their mode changed.
  706    When parsing MODE messages, it is RECOMMENDED that the entire message
  707    be parsed first, and then the changes which resulted passed on.
  709    It is REQUIRED that servers are able to change channel modes so that
  710    "channel creator" and "channel operators" may be created.
  712 5. Implementation details
  714    A the time of writing, the only current implementation of this
  715    protocol is the IRC server, version 2.10. Earlier versions may
  716    implement some or all of the commands described by this document with
  717    NOTICE messages replacing many of the numeric replies. Unfortunately,
  718    due to backward compatibility requirements, the implementation of
  719    some parts of this document varies with what is laid out.  One
  720    notable difference is:
  722         * recognition that any LF or CR anywhere in a message marks
  723           the end of that message (instead of requiring CR-LF);
  725    The rest of this section deals with issues that are mostly of
  726    importance to those who wish to implement a server but some parts
  727    also apply directly to clients as well.
  729 5.1 Connection 'Liveness'
  731    To detect when a connection has died or become unresponsive, the
  732    server MUST poll each of its connections.  The PING command (See "IRC
  733    Client Protocol" [IRC-CLIENT]) is used if the server doesn't get a
  734    response from its peer in a given amount of time.
  736    If a connection doesn't respond in time, its connection is closed
  737    using the appropriate procedures.
  739 5.2 Accepting a client to server connection
  741 5.2.1 Users
  743    When a server successfully registers a new user connection, it is
  744    REQUIRED to send to the user unambiguous messages stating: the user
  745    identifiers upon which it was registered (RPL_WELCOME), the server
  746    name and version (RPL_YOURHOST), the server birth information
  747    (RPL_CREATED), available user and channel modes (RPL_MYINFO), and it
  748    MAY send any introductory messages which may be deemed appropriate.
  750    In particular the server SHALL send the current user/service/server
  751    count (as per the LUSER reply) and finally the MOTD (if any, as per
  752    the MOTD reply).
  754    After dealing with registration, the server MUST then send out to
  755    other servers the new user's nickname (NICK message), other
  756    information as supplied by itself (USER message) and as the server
  757    could discover (from DNS servers).  The server MUST NOT send this
  758    information out with a pair of NICK and USER messages as defined in
  759    "IRC Client Protocol" [IRC-CLIENT], but MUST instead take advantage
  760    of the extended NICK message defined in section 4.1.3.
  762 5.2.2 Services
  764    Upon successfully registering a new service connection, the server is
  765    subject to the same kind of REQUIREMENTS as for a user.  Services
  766    being somewhat different, only the following replies are sent:
  769    After dealing with this, the server MUST then send out to other
  770    servers (SERVICE message) the new service's nickname and other
  771    information as supplied by the service (SERVICE message) and as the
  772    server could discover (from DNS servers).
  774 5.3 Establishing a server-server connection.
  776    The process of establishing a server-to-server connection is fraught
  777    with danger since there are many possible areas where problems can
  778    occur - the least of which are race conditions.
  780    After a server has received a connection following by a PASS/SERVER
  781    pair which were recognized as being valid, the server SHOULD then
  782    reply with its own PASS/SERVER information for that connection as
  783    well as all of the other state information it knows about as
  784    described below.
  786    When the initiating server receives a PASS/SERVER pair, it too then
  787    checks that the server responding is authenticated properly before
  788    accepting the connection to be that server.
  790 5.3.1 Link options
  792    Server links are based on a common protocol (defined by this
  793    document) but a particular link MAY set specific options using the
  794    PASS message (See Section 4.1.1).
  796 Compressed server to server links
  798    If a server wishes to establish a compressed link with its peer, it
  799    MUST set the 'Z' flag in the options parameter to the PASS message.
  800    If both servers request compression and both servers are able to
  801    initialize the two compressed streams, then the remainder of the
  802    communication is to be compressed.  If any server fails to initialize
  803    the stream, it will send an uncompressed ERROR message to its peer
  804    and close the connection.
  806    The data format used for the compression is described by RFC 1950
  807    [ZLIB], RFC 1951 [DEFLATE] and RFC 1952 [GZIP].
  809 Anti abuse protections
  811    Most servers implement various kinds of protections against possible
  812    abusive behaviours from non trusted parties (typically users).  On
  813    some networks, such protections are indispensable, on others they are
  814    superfluous.  To require that all servers implement and enable such
  815    features on a particular network, the 'P' flag is used when two
  816    servers connect.  If this flag is present, it means that the server
  817    protections are enabled, and that the server REQUIRES all its server
  818    links to enable them as well.
  820    Commonly found protections are described in sections 5.7 (Tracking
  821    recently used nicknames) and 5.8 (Flood control of clients).
  823 5.3.2 State information exchange when connecting
  825    The order of state information being exchanged between servers is
  826    essential.  The REQUIRED order is as follows:
  828            * all known servers;
  830            * all known client information;
  832            * all known channel information.
  834    Information regarding servers is sent via extra SERVER messages,
  835    client information with NICK and SERVICE messages and channels with
  836    NJOIN/MODE messages.
  838    NOTE: channel topics SHOULD NOT be exchanged here because the TOPIC
  839    command overwrites any old topic information, so at best, the two
  840    sides of the connection would exchange topics.
  842    By passing the state information about servers first, any collisions
  843    with servers that already exist occur before nickname collisions
  844    caused by a second server introducing a particular nickname.  Due to
  845    the IRC network only being able to exist as an acyclic graph, it may
  846    be possible that the network has already reconnected in another
  847    location.  In this event, the place where the server collision occurs
  848    indicates where the net needs to split.
  850 5.4 Terminating server-client connections
  852    When a client connection unexpectedly closes, a QUIT message is
  853    generated on behalf of the client by the server to which the client
  854    was connected.  No other message is to be generated or used.
  856 5.5 Terminating server-server connections
  858    If a server-server connection is closed, either via a SQUIT command
  859    or "natural" causes, the rest of the connected IRC network MUST have
  860    its information updated by the server which detected the closure.
  861    The terminating server then sends a list of SQUITs (one for each
  862    server behind that connection).  (See Section 4.1.6 (SQUIT)).
  864 5.6 Tracking nickname changes
  866    All IRC servers are REQUIRED to keep a history of recent nickname
  867    changes.  This is important to allow the server to have a chance of
  868    keeping in touch of things when nick-change race conditions occur
  869    with commands manipulating them.  Messages which MUST trace nick
  870    changes are:
  872            * KILL (the nick being disconnected)
  874            * MODE (+/- o,v on channels)
  876            * KICK (the nick being removed from channel)
  878       No other commands need to check nick changes.
  880    In the above cases, the server is required to first check for the
  881    existence of the nickname, then check its history to see who that
  882    nick now belongs to (if anyone!).  This reduces the chances of race
  883    conditions but they can still occur with the server ending up
  884    affecting the wrong client.  When performing a change trace for an
  885    above command it is RECOMMENDED that a time range be given and
  886    entries which are too old ignored.
  888    For a reasonable history, a server SHOULD be able to keep previous
  889    nickname for every client it knows about if they all decided to
  890    change.  This size is limited by other factors (such as memory, etc).
  892 5.7 Tracking recently used nicknames
  894    This mechanism is commonly known as "Nickname Delay", it has been
  895    proven to significantly reduce the number of nickname collisions
  896    resulting from "network splits"/reconnections as well as abuse.
  898    In addition of keeping track of nickname changes, servers SHOULD keep
  899    track of nicknames which were recently used and were released as the
  900    result of a "network split" or a KILL message.  These nicknames are
  901    then unavailable to the server local clients and cannot be re-used
  902    (even though they are not currently in use) for a certain period of
  903    time.
  905    The duration for which a nickname remains unavailable SHOULD be set
  906    considering many factors among which are the size (user wise) of the
  907    IRC network, and the usual duration of "network splits".  It SHOULD
  908    be uniform on all servers for a given IRC network.
  910 5.8 Flood control of clients
  912    With a large network of interconnected IRC servers, it is quite easy
  913    for any single client attached to the network to supply a continuous
  914    stream of messages that result in not only flooding the network, but
  915    also degrading the level of service provided to others.  Rather than
  916    require every 'victim' to provide their own protection, flood
  917    protection was written into the server and is applied to all clients
  918    except services.  The current algorithm is as follows:
  920    * check to see if client's `message timer' is less than current time
  921      (set to be equal if it is);
  923    * read any data present from the client;
  925    * while the timer is less than ten (10) seconds ahead of the current
  926      time, parse any present messages and penalize the client by two (2)
  927      seconds for each message;
  929    * additional penalties MAY be used for specific commands which
  930      generate a lot of traffic across the network.
  932    This in essence means that the client may send one (1) message every
  933    two (2) seconds without being adversely affected.  Services MAY also
  934    be subject to this mechanism.
  936 5.9 Non-blocking lookups
  938    In a real-time environment, it is essential that a server process
  939    does as little waiting as possible so that all the clients are
  940    serviced fairly.  Obviously this requires non-blocking IO on all
  941    network read/write operations.  For normal server connections, this
  942    was not difficult, but there are other support operations that may
  943    cause the server to block (such as disk reads).  Where possible, such
  944    activity SHOULD be performed with a short timeout.
  946 5.9.1 Hostname (DNS) lookups
  948    Using the standard resolver libraries from Berkeley and others has
  949    meant large delays in some cases where replies have timed out.  To
  950    avoid this, a separate set of DNS routines were written for the
  951    current implementation.  Routines were setup for non-blocking IO
  952    operations with local cache, and then polled from within the main
  953    server IO loop.
  955 5.9.2 Username (Ident) lookups
  957    Although there are numerous ident libraries (implementing the
  958    "Identification Protocol" [IDENT]) for use and inclusion into other
  959    programs, these caused problems since they operated in a synchronous
  960    manner and resulted in frequent delays.  Again the solution was to
  961    write a set of routines which would cooperate with the rest of the
  962    server and work using non-blocking IO.
  964 6. Current problems
  966    There are a number of recognized problems with this protocol, all of
  967    which are hoped to be solved sometime in the near future during its
  968    rewrite.  Currently, work is underway to find working solutions to
  969    these problems.
  971 6.1 Scalability
  973    It is widely recognized that this protocol does not scale
  974    sufficiently well when used in a large arena.  The main problem comes
  975    from the requirement that all servers know about all other servers
  976    and clients and that information regarding them be updated as soon as
  977    it changes.  It is also desirable to keep the number of servers low
  978    so that the path length between any two points is kept minimal and
  979    the spanning tree as strongly branched as possible.
  981 6.2 Labels
  983    The current IRC protocol has 4 types of labels: the nickname, the
  984    channel name, the server name and the service name.  Each of the four
  985    types has its own domain and no duplicates are allowed inside that
  986    domain.  Currently, it is possible for users to pick the label for
  987    any of the first three, resulting in collisions.  It is widely
  988    recognized that this needs reworking, with a plan for unique names
  989    for nicks that don't collide being desirable as well as a solution
  990    allowing a cyclic tree.
  992 6.2.1 Nicknames
  994    The idea of the nickname on IRC is very convenient for users to use
  995    when talking to each other outside of a channel, but there is only a
  996    finite nickname space and being what they are, it's not uncommon for
  997    several people to want to use the same nick.  If a nickname is chosen
  998    by two people using this protocol, either one will not succeed or
  999    both will be removed by use of KILL (See Section 3.7.1 of "IRC Client
 1000    Protocol" [IRC-CLIENT]).
 1002 6.2.2 Channels
 1004    The current channel layout requires that all servers know about all
 1005    channels, their inhabitants and properties.  Besides not scaling
 1006    well, the issue of privacy is also a concern.  A collision of
 1007    channels is treated as an inclusive event (people from both nets on
 1008    channel with common name are considered to be members of it) rather
 1009    than an exclusive one such as used to solve nickname collisions.
 1011    This protocol defines "Safe Channels" which are very unlikely to be
 1012    the subject of a channel collision.  Other channel types are kept for
 1013    backward compatibility.
 1015 6.2.3 Servers
 1017    Although the number of servers is usually small relative to the
 1018    number of users and channels, they too are currently REQUIRED to be
 1019    known globally, either each one separately or hidden behind a mask.
 1021 6.3 Algorithms
 1023    In some places within the server code, it has not been possible to
 1024    avoid N^2 algorithms such as checking the channel list of a set of
 1025    clients.
 1027    In current server versions, there are only few database consistency
 1028    checks, most of the time each server assumes that a neighbouring
 1029    server is correct.  This opens the door to large problems if a
 1030    connecting server is buggy or otherwise tries to introduce
 1031    contradictions to the existing net.
 1033    Currently, because of the lack of unique internal and global labels,
 1034    there are a multitude of race conditions that exist.  These race
 1035    conditions generally arise from the problem of it taking time for
 1036    messages to traverse and effect the IRC network.  Even by changing to
 1037    unique labels, there are problems with channel-related commands being
 1038    disrupted.
 1040 7. Security Considerations
 1042 7.1 Authentication
 1044    Servers only have two means of authenticating incoming connections:
 1045    plain text password, and DNS lookups.  While these methods are weak
 1046    and widely recognized as unsafe, their combination has proven to be
 1047    sufficient in the past:
 1049     * public networks typically allow user connections with only few
 1050       restrictions, without requiring accurate authentication.
 1052     * private networks which operate in a controlled environment often
 1053       use home-grown authentication mechanisms not available on the
 1054       internet: reliable ident servers [IDENT], or other proprietary
 1055       mechanisms.
 1057    The same comments apply to the authentication of IRC Operators.
 1059    It should also be noted that while there has been no real demand over
 1060    the years for stronger authentication, and no real effort to provide
 1061    better means to safely authenticate users, the current protocol
 1062    offers enough to be able to easily plug-in external authentication
 1063    methods based on the information that a client can submit to the
 1064    server upon connection: nickname, username, password.
 1066 7.2 Integrity
 1068    Since the PASS and OPER messages of the IRC protocol are sent in
 1069    clear text, a stream layer encryption mechanism (like "The TLS
 1070    Protocol" [TLS]) could be used to protect these transactions.
 1072 8. Current support and availability
 1074       Mailing lists for IRC related discussion:
 1075         General discussion: ircd-users@irc.org
 1076         Protocol development: ircd-dev@irc.org
 1078       Software implementations:
 1079         ftp://ftp.irc.org/irc/server
 1080         ftp://ftp.funet.fi/pub/unix/irc
 1081         ftp://coombs.anu.edu.au/pub/irc
 1083       Newsgroup: alt.irc
 1085 9. Acknowledgements
 1087    Parts of this document were copied from the RFC 1459 [IRC] which
 1088    first formally documented the IRC Protocol.  It has also benefited
 1089    from many rounds of review and comments.  In particular, the
 1090    following people have made significant contributions to this
 1091    document:
 1093    Matthew Green, Michael Neumayer, Volker Paulsen, Kurt Roeckx, Vesa
 1094    Ruokonen, Magnus Tjernstrom, Stefan Zehl.
 1096 10. References
 1098    [KEYWORDS]   Bradner, S., "Key words for use in RFCs to Indicate
 1099                 Requirement Levels", BCP 14, RFC 2119, March 1997.
 1101    [ABNF]       Crocker, D. and P. Overell, "Augmented BNF for Syntax
 1102                 Specifications: ABNF", RFC 2234, November 1997.
 1104    [IRC]        Oikarinen, J. and D. Reed, "Internet Relay Chat
 1105                 Protocol", RFC 1459, May 1993.
 1107    [IRC-ARCH]   Kalt, C., "Internet Relay Chat: Architecture", RFC 2810,
 1108                 April 2000.
 1110    [IRC-CLIENT] Kalt, C., "Internet Relay Chat: Client Protocol", RFC
 1111                 2812, April 2000.
 1113    [IRC-CHAN]   Kalt, C., "Internet Relay Chat: Channel Management", RFC
 1114                 2811, April 2000.
 1116    [ZLIB]       Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data
 1117                 Format Specification version 3.3", RFC 1950, May 1996.
 1119    [DEFLATE]    Deutsch, P., "DEFLATE Compressed Data Format
 1120                 Specification version 1.3", RFC 1951, May 1996.
 1122    [GZIP]       Deutsch, P., "GZIP file format specification version
 1123                 4.3", RFC 1952, May 1996.
 1125    [IDENT]      St. Johns, M., "The Identification Protocol", RFC 1413,
 1126                 February 1993.
 1128    [TLS]        Dierks, T. and C. Allen, "The TLS Protocol", RFC 2246,
 1129                 January 1999.
 1131 11. Author's Address
 1133    Christophe Kalt
 1134    99 Teaneck Rd, Apt #117
 1135    Ridgefield Park, NJ 07660
 1136    USA
 1138    EMail: kalt@stealth.net
 1140 12.  Full Copyright Statement
 1142    Copyright (C) The Internet Society (2000).  All Rights Reserved.
 1144    This document and translations of it may be copied and furnished to
 1145    others, and derivative works that comment on or otherwise explain it
 1146    or assist in its implementation may be prepared, copied, published
 1147    and distributed, in whole or in part, without restriction of any
 1148    kind, provided that the above copyright notice and this paragraph are
 1149    included on all such copies and derivative works.  However, this
 1150    document itself may not be modified in any way, such as by removing
 1151    the copyright notice or references to the Internet Society or other
 1152    Internet organizations, except as needed for the purpose of
 1153    developing Internet standards in which case the procedures for
 1154    copyrights defined in the Internet Standards process must be
 1155    followed, or as required to translate it into languages other than
 1156    English.
 1158    The limited permissions granted above are perpetual and will not be
 1159    revoked by the Internet Society or its successors or assigns.
 1161    This document and the information contained herein is provided on an
 1168 Acknowledgement
 1170    Funding for the RFC Editor function is currently provided by the
 1171    Internet Society.