================================================================================ ircd-RU! Extensions Specification -------------------------------------------------------------------------------- $Id: ircd-RU.specs.txt,v 22.214.171.124 2003/08/17 05:30:12 rzhe Exp $ ================================================================================ I. INTRODUCTION =============== A. Purpose ---------- This document describes the requirements for a set of extensions to Internet Relay Chat Daemon (IRCd). The internal name for this software is "ircd-RU Extensions" or IRE shortly. This document is not the final version of IRE specification and may vary. B. Scope -------- IRE is a set of extensions that provide more features than a server they are applied to does. IRE is designed to be a set of additional data and functions and also changes to the existing data and functions that are compiled into IRCd. It is not a program by itself. C. Definitions -------------- This document uses common, industry-standard terms, definitions and nomenclature to describe IRE. There are some document-specific terms: 1. Valid symbol - a symbol which is allowed to general use in nicknames and channel names. 2. Codepage - a set of correspondences between symbols and their numbers in a certain codepage. Regarding to IRE codepage also includes information about "validity" of each symbol. 3. Codepage atom (cpatom) - a unit substitution which means a number of a symbol in some another codepage. 4. Absolute codepage - an abstract degenerate (upwards numbering) codepage used to define all other codepages as a single array of cpatoms. 5. Translator - a pair of arrays of cpatoms used to convert a symbol from one codepage to another one and back. 6. Base codepage - a codepage which is assumed to be "native" for a certain server, i.e. all string data is stored and processed in this codepage within the server. 7. Active codepage - a codepage which is marked as allowed to assign to clients. 8. Lost codepage - a codepage which is not marked as active, but is still used by clients. Lost codepages may appear after changing codepages parts of the server configuration data and rehashing the server. D. References ------------- 1. RFCs ## 1459, 2810, 2811, 2812, 2813. II. GENERAL DESCRIPTION ======================= IRE is a set of extensions to an IRCd that implements enhanced functionality in addition to the described in . The enhancements are a) 8-bit nicknames support, b) translation schemes support, c) additional channel modes support, d) extensions to the client part of the protocol for changing clients' codepages, obtaining information about supported codepages from a server, monitoring and reconfiguring servers' codepages, e) extensions to server configuration data and the code that reads and applies configuration data, f) extensions to the server part of the protocol for passing information about base codepages between servers. 8-bit nicknames support refers to the ability for client to have a nickname containing symbols with high bit set to one. A set of 8-bit symbols that can be used in a nickname is specific for each codepage. This extension can be optionally disabled or limited to only 7-bit or only 8-bit nicknames on a certain server. Translations schemes support refers to ability for clients to exchange data with the server in a codepage that is different from the server's base codepage. The server translates incoming and outgoing data from and to the client's codepage respectively. If the client's codepage is the same as the server's base codepage, then no translation is performed. Changing codepage is not allowed if a client has a 8-bit nickname or username. Additional channel modes support refers to forbidding users with 8-bit or mixed-alphabet nicknames joining to a certain channel where 8-bit or mixed-alphabet nicknames are not allowed, or changing the 7-bit nickname to 8-bit or mixed-alphabet one while being in a such channel. Extensions to the client part of the protocol refer to ability to change the codepage by a client without reconnecting to the server, ability to determine a set of codepages supported by a specific server, ability for IRC operators to determine a list and current state of codepages on the specific server, ability for IRC operators to make the server reread it's codepages configuration data without restarting the server. Extensions to the server configuration data and related code refer to specifying a format to set a list of codepages supported by a server, assuming codepages to specific listening ports, specifying the server's base codepage, reading codepages related data from the server's configuration file and changing the server's internal structures according to the data read. Extensions to the server part of the protocol refer to allowing downlinks determine the uplink's base codepage and perform translations from their base codepages to the uplink's one and back by themselves. This could decrease an uplink CPU usage if it has many downlinks that have another base codepage. III. SPECIFIC REQUIREMENTS ========================== A. Functional Requirements -------------------------- IRE implements extensions to the protocol according the standards described in current IRC RFCs or draft RFCs (see ). B. External Interface Requirements ---------------------------------- IRE has declarations of it's specific data and functions in the same style that is used by the code it applies to. Changes to the existing code is made in the same style used by the code is being changed. Location of declarations and definitions of IRE extensions is defined according to the similar elements of the existing code everywhere it is possible. IRE must reuse the existing code as much as possible. Some parts of the existing code that is used by IRE should be optimised if needed. C. Performance Requirements --------------------------- IRE must implement efficient algorithms for translating, assuming specific codepages to ports and clients, updating codepages related internal data structures on rehash, changing base codepage. IRE must consume absolute minimum system resources. This includes memory resources and processing time per IRE-specific operation. IRE must require absolute minimum disk storage for itself. IRE must optimize memory allocation and deallocation that it is used for its own needs. D. Coding Constraints --------------------- IRE must conform to the following coding requirements: 1. IRE will be coded in ISO Standard C '90 (based on ANSI C '89). 2. GNU C compiler will be used to compiling IRCd with IRE applied. 3. IRE must not use any other libraries than the standard C library. Some addition libraries are allowed to use in IRE if it is specified in this document. IV. ADDITIONS AND CHANGES TO IRC PROTOCOL ========================================= 1. Codepage command ------------------- Command: CODEPAGE Parameters: <name> Description: CODEPAGE command is used to set a translation scheme for client or change the previous. The <name> parameter is a name or alias of the codepage supported by the server. Numeric Replies: RPL_CODEPAGE 700 ERR_NEEDMOREPARAMS 461 ERR_NOSUCHCODEPAGE 750 ERR_ALLNICKXBUSY 751 ERR_SAMECODEPAGE 752 2. Codepages message -------------------- Command: CODEPAGES Parameters: [<server>] Description: CODEPAGES message is used to get a list of a server's active codepages. An optional parameter <server> parameter is used to query the active codepages list of the server which a client is not directly connected to. Numeric Replies: RPL_CODEPAGES 701 RPL_ENDOFCODEPAGES 702 ERR_NOSUCHSERVER 402 3. Scps message --------------- Command: SCPS Parameters: <codepage>[,<codepage>[,...]] Description: SCPS message is a part of servers joining protocol. Now servers send it after CAPAB message and before SERVER message. Servers get to know about each other base codepage and capabilities to translate server-to-server traffic via this message. A server which is connecting to another server sends his base codepage name in the first item of the list. Other items are the names of codepages it accepts to be set as a translation scheme for the connection by the server it is connecting to. These codepages are set up in the class of connection's C:-line, see Y:-line description below for more information. A server which is accepting another server performs the following check: a) Compare the connecting server's base codepage with it's own base codepage and if they coincide, then set this codepage as a translation scheme for the connection and quit this algorithm. After this, there will be no translation performed on both of the servers. b) If a) failed, then compare the connecting server's base codepage with codepages specified in the second codepage list in the accepting server's Y:-line that corresponds to the connection's N:-line. See Y:-line description below for more information. If one of those codepages coincide with the connecting server's base codepage, then set this codepage as a translation scheme for the connection and quit this algorithm. After this, the accepting server will translate to and from the connecting server's base codepage for this connection. c) If b) failed, then do the b) check again with the accepting server's base codepage and the codepages passed in SCPS message by the connecting server after its base codepage. If a coincidense is found, then set this codepage as a translation scheme for the connection and quit this algorithm. After this, the connecting server will translate to and from the accepting server's base codepage for this connection. If there is no SCPS message from the connecting server, then the accepting one checks that the codepage that corresponds to the connection P:-line exists in the second codepage list in the connection class definition. If found, then the accepting server sets this codepage as a translation scheme for the connection and will perform the translation. If all of the checks above did not succeed, then the accepting server writes a gnotice that translation negotiation with the connecting server failed and disconnects this server. The accepting server sends the connection translation scheme in SCPS message back to the connecting server. When the connecting server receives SCPS message from the accepting server, it performs the following check: a) Compare the codepage passed in SCPS with it's own base codepage and if they coincide, then set this codepage as a translation scheme for the connection and quit this algorithm. b) If a) failed, then compare the codepage passed in SCPS with codepages specified in the first codepage list in the connecting server's Y:-line that corresponds to the connection's C:-line. See Y:-line description below for more information. If there a coincidense is found, then set this codepage as a translation scheme for the connection and quit this algorithm. If all of the checks above did not succeed, then connecting server writes a gnotice that translation negotiation with the accepting server failed and disconnects from this server. If there is no SCPS message from the accepting server, then the connecting server sets its base codepage as a translation scheme for the connection and will not perform any translation. 4. Forcecp message ------------------ Command: FORCECP Parameters: <nick> <codepage> Description: FORCECP message allows an operator to change a user's translation scheme. <nick> is a nickname of the user, and <codepage> is a name or alias of a codepage that must exist on the server the target user on. Local operators are allowed to change codepage for local users only. Numeric Replies: ERR_NOSUCHNICK 401 ERR_NEEDMOREPARAMS 461 ERR_NOPRIVILEGES 481 ERR_NOSUCHCODEPAGE 750 ERR_ALLNICKXBUSY 751 ERR_SAMECODEPAGE 752 5. Nick message --------------- See  for a description of the NICK message. Additional Numeric Replies: ERR_7BITNICKS 753 ERR_NOMIXEDALPHA 754 ERR_NOMIXEDALPHAWORDS 755 ERR_IDENNICKNAMEINUSE 757 6. Whois query -------------- See  for a description of the WHOIS query. Additional Numeric Replies: RPL_WHOISSCHEME 703 7. Join message --------------- See  for a description of the JOIN message. Additional Numeric Replies: ERR_7BITNICKS 753 ERR_NOMIXEDALPHA 754 ERR_NOMIXEDALPHAWORDS 755 8. Mode message --------------- See  for a description of the MODE message. Additional channel modes: 7 - no 8-bit nicknames allowed. x - only latin or national alphabet nicknames allowed. w - mixed-alphabet words in nicknames are not allowed. e - ban exception, nick!user@host mask. B - extended ban, nick!user@host:server mask. E - extended exception, nick!user@host:server mask. X - exclusion, nick!user@host:server mask. h - do not allow to view access lists from outside. Additional user modes: H - do not show codepage and idle time in local user's whois reply. Additional Numeric Replies: RPL_EXCEPTLIST 348 RPL_ENDOFEXCEPTLIST 349 RPL_EXTBANLIST 740 RPL_ENDOFEXTBANLIST 741 RPL_EXTEXCEPTLIST 742 RPL_ENDOFEXTEXCEPTLIST 743 RPL_EXCLUSLIST 744 RPL_ENDOFEXCLUSLIST 745 ERR_CHANNELHIDESBANS 756 ERR_BANEXISTS 790 ERR_EXCEPTEXISTS 791 ERR_EXCEPTLISTFULL 792 ERR_EXTBANEXISTS 793 ERR_EXTBANLISTFULL 794 ERR_EXTEXCEPTEXISTS 795 ERR_EXTEXCEPTLISTFULL 796 ERR_EXCLUSEXISTS 797 ERR_EXCLUSLISTFULL 798 ERR_CANTDEOPSERVICE 851 9. Kick command --------------- See  for a description of the KICK command. Additional Numeric Replies: ERR_CANTKICKSERVICE 850 10. Stats message ---------------- See  for a description of the STATS message. Additional queries: b - query a list of codepages with their parameters that exist on the specified server or on the server which a client is directly connected to. r - query channel restrictions statistics. L - query DNSBLs statistics. Additional Numeric Replies: RPL_STATSRLINE 228 RPL_STATSCODEPAGE 704 11. Capab message ----------------- See the sources of the server IRE is applied to for a description of the CAPAB message. Additional Parameter Keywords: 8BNCI - is sent by a server which supports 8-bit name symbols case-insensitive processing. 8BCHNCI - is sent by a server which supports 8-bit channel name symbols case-insensitive processing. 12. Server message ------------------ See  for a description of the SERVER message. Extended parameters: <servername> <hopcount> [<protocol>] <info> Description: When connecting and accepting servers pass SERVER messages about themselves to each other, the <protocol> parameter is set to the protocol version of the server which sends the SERVER message. Another one compares this value with its protocol version and if they differ, then reports the error and closes the connection to the server the wrong protocol version received from. When informing servers about other servers with <hopcount> parameter more than 1, the <protocol> parameter is not passed. V. ADDITIONS AND CHANGES TO SERVER CONFIGURATION DATA ===================================================== For more detailed description of changed items see the "ircd.conf-dist" of the standard IRCd. M: [MANDATORY] - Changed ------------------------ Fields, in order, are: M:Hostname:IP:Description Of Your Server:Default Connect Port The last parameter is used to set the port an outgoing connection will try to connect to, if the port field in a C:-line is blank. There is no more listening on the default connect port. Please check out an ATTENTION in P:-lines description below. Sample line: M:server.funkies.com:*:Some Funky Server:6660 Y: [SUGGESTED] - Changed ------------------------ Fields, in order, are: class number, ping frequency (in seconds), non-zero connect frequency (in seconds) for server class or zero for client class, maximum number of links (used for auto-connecting, and for limiting the number of clients in that class), sendq (this overrides any value set in "include/config.h" for #define MAXSENDQLENGTH), commas-separated connecting translation list for server class or flags for client class, commas-separated accepting translation list for server class or nothing for client class. Connecting translation list contains codepages (not including the base codepage) that the server is agree to translate to and from another server's base codepage when it initiates a connection to another server. Accepting translation list contains codepages (not including the base codepage) that the server is agree to translate to and from another server's base codepage when it accepts a connection from another server. The following clients flags are available for now: 7 - no 8-bit nicknames allowed for this class. x - no mixed-alphabet nicknames allowed for this class. w - no mixed-alphabet words in nicknames allowed for this class. s - dislpay short MOTD in ircd.smotd instead of ircd.motd on client register. m - do not display any MOTD to client on register. a - do external authentication. Sample lines: # Class 42 - Leaf to hub, autoconnect, leaf is agree to translate to and from # CP1251 for accepting hub Y:42:90:90:1:5000000:CP1251 # Class 32 - Hub to leaf, hub is agree to translate to and from KOI8-F and # KOI8-R for connecting leaf Y:32:90:90:0:5000000::KOI8-F,KOI8-R # Class 2 - Users not allwed to use mixed-alphabet nicknames Y:2:90:0:500:100000:x N: [NETWORKED] - Changed ------------------------ Fields, in order, are: remote hostname, password, remote servername, flags, connection class. Optionally (but not recommended), address masks can be used in remote hostname filed. The additional flags are: V - Do not use protocol version checking. Disables protocol version sending and checking for the server. It is HIGHLY recommended to NOT use this flag, especially for networks where the server software is upgraded regularly. If the protocol is changed in the next server release and protocol checking is disabled, then linking two servers with different protocol version may cause unpredictable results. N - Do not use names caseinsensitivity checking. NOT recommended for use by the same reason as the above. C - Do not use channel names caseinsensitivity checking. NOT recommended for use by the same reason as the above. P: [MANDATORY] - Changed ------------------------ Fields, in order, are: address mask to allow connections from, address to bind to, codepage name, port to listen on. Codepage name is a name of the codepage (listed in D:-lines, see below) which is to be assigned to the clients accepted using this line. ATTENTION: P:-lines become mandatory, because the last parameter in M:-line is used only for setting the default port number on which the server will connect to, if there is no port specified in a connection C:-line. There will be no listening on that port if there is no P:-line that corresponds to the port number in M:-line! Note that setting codepages for ports to listen on defines translations only for clients, not for servers. Servers that have different base codepages negotiate about their translation by themselves using translation lists from Y:-lines. Sample lines: P:*:*::6660 P:*:*:CP1251:6667 P:*:*:TRANSLIT:6668 P:*:*:KOI8-F:6669 P:*:*:KOI8-R:6670 P:*:*:CP866:6671 P:*:*:ISO8859-5:6672 B: [SUGGESTED] - Added ---------------------- Define codepages that are supported by the server. Fields, in order, are: case insensitive codepage name, filename of the codepage, commas-separated list of case insensitive aliases, flags. Sample lines: B:CP1251:cp1251.cp:win:B B:TRANSLIT:translit.cp B:KOI8-F:koi8-f.cp:koi,koi8,unix B:KOI8-R:koi8-r.cp B:CP866:cp866.cp:dos B:ISO8859-5:iso8859-5.cp:iso R: [OPTIONAL] - Added --------------------- Define channel using restrictions rules for client connection classes. Rules are checked in the straight order, so the top rule is checked first and the bottom rules is checked last. Fields, in order, are: R:Allow mask:::A:Class R:Deny mask::Deny reason:D:Class R:Redirect mask::Target:R:Class T: [DISCOURAGED] - Changed -------------------------- Override the default connection throttling settings. ATTENTION: Use these lines ONLY IF STRONGLY NEEDED, and ONLY FOR YOUR OWN KNOWN HOSTS, e.g. for your web and other known gates, your multiple bot hosts, etc. The best way is to ask your network administration for permission to place certain T:Lines. Fields, in order, are: T:IP mask::Trig Count:Trig Time L: [OPTIONAL] - Added --------------------- Defines DNSBL zone and exception address, define address list that should avoid DNSBL check (filters). DNSBL L:Line fields, in order, are: L:Exception address::DNSBL zone:Flags The first field is an optional special IP address that defines a BL exception address. A client could escape blacklisting if any of its queries (initiated by the client connection) returns the exception address. May be different for each zone. The following flags can be used: I - query the list about d.c.b.a.zone, where a.b.c.d is a connecting client IP address. H - query the list about host.zone, where host is a connecting client hostname. L - the list is not network-wide but for local server use only. ATTENTION: Using many DNSBLs may lead to significant delays in accepting clients. Using RHSBLs (H flag) adds a delay after the client hostname is found. Filter L:Line fields, in order, are: L:Filter mask:::F Known addresses (e.g. servers or clients from known networks) can avoid DNSBL or RHSBL check being defined in filters. Filters can be IP or hostname masks. VI. CODEPAGE FILE FORMAT ======================== Codepage file data consists of the following sequential blocks: 1. Length : 256 bytes Content: Translator from the absolute codepage to the codepage defined by the file. 2. Length : 256 bytes Content: Translator from the codepage defined by the file to the absolute codepage. 3. Length : 256 bytes Content: Tolower table. 4. Length : 256 bytes Content: Toupper table. 5. Length : 256 bytes Content: Flags table. The flags are: 0x01 - symbol can be used for nicknames. 0x02 - symbol can be used for channel names. 0x04 - latin alphabet symbol. 0x08 - national alphabet symbol. 0x10 - digit. 6. Length : 256 bytes Content: Identity table.
|(C) rzhe@WeNet, 2001-2003|