================================================================================
ircd-RU! Extensions Specification
--------------------------------------------------------------------------------
$Id: ircd-RU.specs.txt,v 1.1.8.14 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 [1]. 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 [1]).
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 [1] 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 [1] for a description of the WHOIS query.
Additional Numeric Replies:
RPL_WHOISSCHEME 703
7. Join message
---------------
See [1] for a description of the JOIN message.
Additional Numeric Replies:
ERR_7BITNICKS 753
ERR_NOMIXEDALPHA 754
ERR_NOMIXEDALPHAWORDS 755
8. Mode message
---------------
See [1] 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 [1] for a description of the KICK command.
Additional Numeric Replies:
ERR_CANTKICKSERVICE 850
10. Stats message
----------------
See [1] 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 [1] 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
|