diff options
| author | michael <michael@82007160-df01-0410-b94d-b575c5fd34c7> | 2012-10-27 21:02:32 +0000 |
|---|---|---|
| committer | michael <michael@82007160-df01-0410-b94d-b575c5fd34c7> | 2012-10-27 21:02:32 +0000 |
| commit | 70f1558a2eca8295e30bb1e381d948056333634d (patch) | |
| tree | 3051cb6afbc7d5ebae4381e54c70d9cbe54005a4 /doc | |
| parent | 4f1edcf052857117fd51e878c362f878961c4dc9 (diff) | |
- Second time's the charm? Moving svnroot/ircd-hybrid-8 to
svnroot/ircd-hybrid/trunk
git-svn-id: svn://svn.ircd-hybrid.org/svnroot/ircd-hybrid/trunk@1592 82007160-df01-0410-b94d-b575c5fd34c7
Diffstat (limited to 'doc')
31 files changed, 16246 insertions, 0 deletions
diff --git a/doc/CIDR.txt b/doc/CIDR.txt new file mode 100644 index 0000000..e17098a --- /dev/null +++ b/doc/CIDR.txt @@ -0,0 +1,316 @@ +$Id$ + +CIDR Information +---------------- + Presently, we all use IPv4. The format of IPv4 is the following: + +A.B.C.D + + Where letters 'A' through 'D' are 8-bit values. In English, this + means each digit can have a value of 0 to 255. Example: + +129.56.4.234 + + Digits are called octets. Oct meaning 8, hence 8-bit values. An + octet cannot be greater than 255, and cannot be less than 0 (eg. a + negative number). + + CIDR stands for "classless inter domain routing", details covered + in RFC's 1518 and 1519. It was introduced mainly due to waste within + A and B classes space. The goal was to make it possible to use + smaller nets than it would seem from (above) IP classes, for instance + by dividing one B class into 256 "C like" classes. The other goal was + to allow aggregation of routing information, so that routers could use + one aggregated route (like 194.145.96.0/20) instead of + advertising 16 C classes. + + Class A are all these addresses which first bit is "0", + bitmap: 0nnnnnnn.hhhhhhhh.hhhhhhhh.hhhhhhhh (n=net, h=host) + IP range is 0.0.0.0 - 127.255.255.255 + + Class B are all these addresses which first two bits are "10", + bitmap: 10nnnnnn.nnnnnnnn.hhhhhhhh.hhhhhhhh (n=net, h=host) + IP range is 128.0.0.0 - 191.255.255.255 + + Class C are all these addresses which first three bits are "110", + bitmap: 110nnnnn.nnnnnnnn.nnnnnnnn.hhhhhhhh (n=net, h=host) + IP range is 192.0.0.0 - 223.255.255.255 + + Class D are all these addresses which first four bits are "1110", + this is multicast class and net/host bitmap doesn't apply here + IP range is 224.0.0.0 - 239.255.255.255 + I bet they will never IRC, unless someone creates multicast IRC :) + + Class E are all these addresses which first five bits are "11110", + this class is reserved for future use + IP range is 240.0.0.0 - 247.255.255.255 + + So, here is how CIDR notation comes into play. + + For those of you who have real basic exposure to how networks are + set up, you should be aware of the term "netmask." Basically, this + is a IPv4 value which specifies the "size" of a network. You can + assume the word "size" means "range" if you want. + + A chart describing the different classes in CIDR format and their + wildcard equivalents would probably help at this point: + +CIDR version dot notation (netmask) Wildcard equivalent +----------------------------------------------------------------- +A.0.0.0/8 A.0.0.0/255.0.0.0 A.*.*.* or A.* +A.B.0.0/16 A.B.0.0/255.255.0.0 A.B.*.* or A.B.* +A.B.C.0/24 A.B.C.0/255.255.255.0 A.B.C.* or A.B.C.* +A.B.C.D/32 A.B.C.D/255.255.255.255 A.B.C.D + + + The question on any newbies mind at this point is "So what do all + of those values & numbers actually mean?" + + Everything relating to computers is based on binary values (1s and + zeros). Binary plays a *tremendous* role in CIDR notation. Let's + break it down to the following table: + + A B C D + -------- -------- -------- -------- +/8 == 11111111 . 00000000 . 00000000 . 00000000 == 255.0.0.0 +/16 == 11111111 . 11111111 . 00000000 . 00000000 == 255.255.0.0 +/24 == 11111111 . 11111111 . 11111111 . 00000000 == 255.255.255.0 +/32 == 11111111 . 11111111 . 11111111 . 11111111 == 255.255.255.255 + + The above is basically a binary table for the most common netblock + sizes. The "1"s you see above are the 8-bit values for each octet. + If you split an 8-bit value into each of it's bits, you find the + following: + +00000000 +^^^^^^^^_ 1sts place (1) +|||||||__ 2nds place (2) +||||||___ 3rds place (4) +|||||____ 4ths place (8) +||||_____ 5ths place (16) +|||______ 6ths place (32) +||_______ 7ths place (64) +|________ 8ths place (128) + + Now, since computers consider zero a number, you pretty much have + to subtract one (so-to-speak; this is not really how its done, but + just assume it's -1 :-) ) from all the values possible. Some + examples of decimal values in binary: + +15 == 00001111 (from left to right: 8+4+2+1) +16 == 00010000 (from left to right: 16) +53 == 00110101 (from left to right: 32+16+4+1) +79 == 01001111 (from left to right: 64+8+4+1) +254 == 11111110 (from left to right: 128+64+32+16+8+4+2) + + So, with 8 bits, the range (as I said before) is zero to 255. + + If none of this is making sense to you at this point, you should + back up and re-read all of the above. I realize it's a lot, but + it'll do you some good to re-read it until you understand :-). + + So, let's modify the original table a bit by providing CIDR info + for /1 through /8: + + A B C D + -------- -------- -------- -------- +/1 == 10000000 . 00000000 . 00000000 . 00000000 == 128.0.0.0 +/2 == 11000000 . 00000000 . 00000000 . 00000000 == 192.0.0.0 +/3 == 11100000 . 00000000 . 00000000 . 00000000 == 224.0.0.0 +/4 == 11110000 . 00000000 . 00000000 . 00000000 == 240.0.0.0 +/5 == 11111000 . 00000000 . 00000000 . 00000000 == 248.0.0.0 +/6 == 11111100 . 00000000 . 00000000 . 00000000 == 252.0.0.0 +/7 == 11111110 . 00000000 . 00000000 . 00000000 == 254.0.0.0 +/8 == 11111111 . 00000000 . 00000000 . 00000000 == 255.0.0.0 + + At this point, all of this should making a lot of sense, and you + should be able to see the precision that you can get by using CIDR + at this point. If not, well, I guess the best way to put it would + be that wildcards always assume /8, /16, or /24 (yes hello Piotr, + we can argue this later: I am referring to IPs *ONLY*, not domains + or FQDNs :-) ). + + This table will provide a reference to all of the IPv4 CIDR values + +cidr|netmask (dot notation) +----+--------------------- +/1 | 128.0.0.0 +/2 | 192.0.0.0 +/3 | 224.0.0.0 +/4 | 240.0.0.0 +/5 | 248.0.0.0 +/6 | 252.0.0.0 +/7 | 254.0.0.0 +/8 | 255.0.0.0 +/9 | 255.128.0.0 +/10 | 255.192.0.0 +/11 | 255.224.0.0 +/12 | 255.240.0.0 +/13 | 255.248.0.0 +/14 | 255.252.0.0 +/15 | 255.254.0.0 +/16 | 255.255.0.0 +/17 | 255.255.128.0 +/18 | 255.255.192.0 +/19 | 255.255.224.0 +/20 | 255.255.240.0 +/21 | 255.255.248.0 +/22 | 255.255.252.0 +/23 | 255.255.254.0 +/24 | 255.255.255.0 +/25 | 255.255.255.128 +/26 | 255.255.255.192 +/27 | 255.255.255.224 +/28 | 255.255.255.240 +/29 | 255.255.255.248 +/30 | 255.255.255.252 +/31 | 255.255.255.254 +/32 | 255.255.255.255 + + So, let's take all of the information above, and apply it to a + present-day situation on IRC. + + Let's say you have a set of flooding clients who all show up from + the following hosts. For lack-of a better example, I'll use a + subnet here at Best: + +nick1 (xyz@shell9.ba.best.com) [206.184.139.140] +nick2 (abc@shell8.ba.best.com) [206.184.139.139] +nick3 (foo@shell12.ba.best.com) [206.184.139.143] + + Most people will assume the they were all in the same class C + (206.184.139.0/24 or 206.184.139.*). + + This, as a matter of fact, is not true. Now, the reason *I* know + this is solely because I work on the network here; those IPs are + not delegated to a class C, but two portions of a class C (128 IPs + each). That means the class C is actually split into these two + portions: + +Netblock IP range +-------- -------- +206.184.139.0/25 206.184.139.0 to 206.184.139.127 +206.184.139.128/25 206.184.139.128 to 206.184.139.255 + + For the record, 206.184.139.0 and 206.184.139.128 are both known as + "network addresses" (not to be confused with "netblocks" or "Ethernet + hardware addresses" or "MAC addresses"). Network addresses are + *ALWAYS EVEN*. + + 206.184.139.127 and 206.184.139.255 are what are known as broadcast + addresses. Broadcast addresses are *ALWAYS ODD*. + + Now, the aforementioned list of clients are in the 2nd subnet shown + above, not the first. The reason for this should be obvious. + + The remaining question is, "Well that's nice, you know what the netblock + is for Best. What about us? We don't know that!" + + Believe it or not, you can find out the network block size by using + whois -h WHOIS.ARIN.NET on the IP in question. ARIN keeps a list of + all network blocks and who owns them -- quite useful, trust me. I + think I use ARIN 5 or 6 times a day, especially when dealing with + D-lines. Example: + +$ whois -h whois.arin.net 206.184.139.140 +Best Internet Communications, Inc. (NETBLK-NBN-206-184-BEST) +345 East Middlefield Road +Mountain View, CA 94043 + +Netname: NBN-206-184-BEST +Netblock: 206.184.0.0 - 206.184.255.255 +Maintainer: BEST + + Does this mean you should D-line 206.184.0.0/16? Probably not. + That's an entire class B-sized block, while you're only trying + to deny access to a subnetted class C. + + So then how do you get the *real* info? Well, truth is, you don't. + You have to pretty much take a guess at what it is, if ARIN reports + something that's overly vague. Best, for example, was assigned the + above class B-sized block. We can subnet it however we want without + reporting back to ARIN how we have it subnetted. We own the block, + and that's all that matters (to ARIN). + + Not all subnets are like this, however. Smaller subnets you may + find partitioned and listed on ARIN; I've seen /29 blocks for DSL + customers show up in ARIN before. + + So, use ARIN any chance you get. The more precision the better! + + Now, there is a small issue I want to address regarding use of CIDR + notation. Let's say you D-line the following in CIDR format (hi + sion ;-) ): + +205.100.132.18/24 + + Entries like this really makes my blood boil, solely because it adds + excessive confusion and is just basically pointless. If you + examine the above, you'll see the /24 is specifying an entire + class C -- so then what's the purpose of using .18 versus .0? + + There IS no purpose. The netmask itself will mask out the .18 and + continue to successfully use 205.100.132.0/24. + + Doing things this way just adds confusion, especially on non-octet- + aligned subnets (such as /8, /16, /24, or /32). Seeing that on a + /27 or a /19 might make people go "wtf?" + + I know for a fact this doc lacks a lot of necessary information, + like how the actual netmask/CIDR value play a role in "masking out" + the correct size, and what to do is WHOIS.ARIN.NET returns no + netblock information but instead a few different company names with + NIC handles. I'm sure you can figure this stuff out on your own, + or just ask an administrator friend of yours who DOES know. A lot + of us admins are BOFH types, but if you ask us the right questions, + you'll benefit from the answer quite thoroughly. + + Oh, I almost forgot. Most Linux systems use a different version of + "whois" than FreeBSD does. The syntax for whois on Linux is + "whois <INFO>@whois.arin.net", while under FreeBSD it is + "whois -h whois.arin.net <INFO>" Debian uses yet another version + of whois that is incompatible with the above syntax options. + + Note that the FreeBSD whois client has shortcuts for the most commonly + used whois servers. "whois -a <INFO>" is the shortcut for ARIN. + + Also note that ARIN is not authoritative for all IP blocks on the + Internet. Take for example 212.158.123.66. A whois query to ARIN + will return the following information: + +$ whois -h whois.arin.net 212.158.123.66 +European Regional Internet Registry/RIPE NCC (NET-RIPE-NCC-) + These addresses have been further assigned to European users. + Contact information can be found in the RIPE database, via the + WHOIS and TELNET servers at whois.ripe.net, and at + http://www.ripe.net/db/whois.html + + Netname: RIPE-NCC-212 + Netblock: 212.0.0.0 - 212.255.255.255 + Maintainer: RIPE + + This query tells us that it is a European IP block, and is further + handled by RIPE's whois server. We must then query whois.ripe.net + to get more information. + +$ whois -h whois.ripe.net 212.158.123.66 + +% Rights restricted by copyright. See + http://www.ripe.net/ripencc/pub-services/db/copyright.html + +inetnum: 212.158.120.0 - 212.158.123.255 +netname: INSNET-P2P +descr: Point to Point Links for for London Nodes +country: GB +--snip-- + + This tells us the actual IP block that the query was a part of. + + Other whois servers that you may see blocks referred to are: + whois.ripn.net for Russia, whois.apnic.net for Asia, Australia, and + the Pacific, and whois.6bone.net for IPv6 blocks. + +Contributed by Jeremy Chadwick <jdc@best.net> +Piotr Kucharski <chopin@sgh.waw.pl> +W. Campbell <wcampbel@botbay.net> and +Ariel Biener <ariel@fireball.tau.ac.il> diff --git a/doc/Doxyfile b/doc/Doxyfile new file mode 100644 index 0000000..bffa83e --- /dev/null +++ b/doc/Doxyfile @@ -0,0 +1,1635 @@ +# Doxyfile 1.7.1 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# http://www.gnu.org/software/libiconv for the list of possible encodings. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = ircd-hybrid-8 + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = doc/doxygen + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, +# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English +# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, +# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, +# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = NO + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like regular Qt-style comments +# (thus requiring an explicit @brief command for a brief description.) + +JAVADOC_AUTOBRIEF = NO + +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will +# interpret the first line (until the first dot) of a Qt-style +# comment as the brief description. If set to NO, the comments +# will behave just like regular Qt-style comments (thus requiring +# an explicit \brief command for a brief description.) + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 8 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for +# Java. For instance, namespaces will be presented as packages, qualified +# scopes will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources only. Doxygen will then generate output that is more tailored for +# Fortran. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for +# VHDL. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given extension. +# Doxygen has a built-in mapping, but you can override or extend it using this +# tag. The format is ext=language, where ext is a file extension, and language +# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, +# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make +# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C +# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions +# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. +# Doxygen will parse them like normal C++ but will assume all classes use public +# instead of private inheritance when no explicit protection keyword is present. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate getter +# and setter methods for a property. Setting this option to YES (the default) +# will make doxygen to replace the get and set methods by a property in the +# documentation. This will only work if the methods are indeed getting or +# setting a simple type. If this is not the case, or you want to show the +# methods anyway, you should set this option to NO. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum +# is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically +# be useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. + +TYPEDEF_HIDES_STRUCT = NO + +# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to +# determine which symbols to keep in memory and which to flush to disk. +# When the cache is full, less often used symbols will be written to disk. +# For small to medium size projects (<1000 input files) the default value is +# probably good enough. For larger projects a too small cache size can cause +# doxygen to be busy swapping symbols to and from disk most of the time +# causing a significant performance penality. +# If the system has enough physical memory increasing the cache will improve the +# performance by keeping more symbols in memory. Note that the value works on +# a logarithmic scale so increasing the size by one will rougly double the +# memory usage. The cache size is given by this formula: +# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, +# corresponding to a cache size of 2^16 = 65536 symbols + +SYMBOL_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = YES + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default +# anonymous namespace are hidden. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen +# will list include files with double quotes in the documentation +# rather than with sharp brackets. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen +# will sort the (brief and detailed) documentation of class members so that +# constructors and destructors are listed first. If set to NO (the default) +# the constructors will appear in the respective orders defined by +# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. +# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO +# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the +# hierarchy of group names into alphabetical order. If set to NO (the default) +# the group names will appear in their defined order. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is NO. + +SHOW_DIRECTORIES = NO + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. +# This will remove the Files entry from the Quick Index and from the +# Folder Tree View (if specified). The default is YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the +# Namespaces page. +# This will remove the Namespaces entry from the Quick Index +# and from the Folder Tree View (if specified). The default is YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command <command> <input-file>, where <command> is the value of +# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. The create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. +# You can optionally specify a file name after the option, if omitted +# DoxygenLayout.xml will be used as the name of the layout file. + +LAYOUT_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be abled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = include \ + modules \ + src + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is +# also the default input encoding. Doxygen uses libiconv (or the iconv built +# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for +# the list of possible encodings. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 + +FILE_PATTERNS = *.c \ + *.h + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = src/conf_parser.c \ + src/conf_parser.h \ + src/conf_lexer.c + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command <filter> <input-file>, where <filter> +# is the value of the INPUT_FILTER tag, and <input-file> is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. +# If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. +# Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. +# The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER +# is applied to all files. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = NO + +# If the REFERENCED_BY_RELATION tag is set to YES +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = YES + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. +# Otherwise they will link to the documentation. + +REFERENCES_LINK_SOURCE = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = NO + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. +# Doxygen will adjust the colors in the stylesheet and background images +# according to this color. Hue is specified as an angle on a colorwheel, +# see http://en.wikipedia.org/wiki/Hue for more information. +# For instance the value 0 represents red, 60 is yellow, 120 is green, +# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. +# The allowed range is 0 to 359. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of +# the colors in the HTML output. For a value of 0 the output will use +# grayscales only. A value of 255 will produce the most vivid colors. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to +# the luminance component of the colors in the HTML output. Values below +# 100 gradually make the output lighter, whereas values above 100 make +# the output darker. The value divided by 100 is the actual gamma applied, +# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, +# and 100 does not change the gamma. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting +# this to NO can help when comparing the output of multiple runs. + +HTML_TIMESTAMP = YES + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. For this to work a browser that supports +# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox +# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). + +HTML_DYNAMIC_SECTIONS = YES + +# If the GENERATE_DOCSET tag is set to YES, additional index files +# will be generated that can be used as input for Apple's Xcode 3 +# integrated development environment, introduced with OSX 10.5 (Leopard). +# To create a documentation set, doxygen will generate a Makefile in the +# HTML output directory. Running make will produce the docset in that +# directory and running "make install" will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find +# it at startup. +# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. + +GENERATE_DOCSET = NO + +# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the +# feed. A documentation feed provides an umbrella under which multiple +# documentation sets from a single provider (such as a company or product suite) +# can be grouped. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that +# should uniquely identify the documentation set bundle. This should be a +# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen +# will append .docset to the name. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING +# is used to encode HtmlHelp index (hhk), content (hhc) and project file +# content. + +CHM_INDEX_ENCODING = + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated +# that can be used as input for Qt's qhelpgenerator to generate a +# Qt Compressed Help (.qch) of the generated HTML documentation. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can +# be used to specify the file name of the resulting .qch file. +# The path specified is relative to the HTML output folder. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#namespace + +QHP_NAMESPACE = + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#virtual-folders + +QHP_VIRTUAL_FOLDER = doc + +# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to +# add. For more information please see +# http://doc.trolltech.com/qthelpproject.html#custom-filters + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see +# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters"> +# Qt Help Project / Custom Filters</a>. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's +# filter section matches. +# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes"> +# Qt Help Project / Filter Attributes</a>. + +QHP_SECT_FILTER_ATTRS = + +# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can +# be used to specify the location of Qt's qhelpgenerator. +# If non-empty doxygen will try to run qhelpgenerator on the generated +# .qhp file. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files +# will be generated, which together with the HTML files, form an Eclipse help +# plugin. To install this plugin and make it available under the help contents +# menu in Eclipse, the contents of the directory containing the HTML and XML +# files needs to be copied into the plugins directory of eclipse. The name of +# the directory within the plugins directory should be the same as +# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before +# the help appears. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have +# this name. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. +# If the tag value is set to YES, a side panel will be generated +# containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). +# Windows users are probably better off using the HTML help feature. + +GENERATE_TREEVIEW = NO + +# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, +# and Class Hierarchy pages using a tree view instead of an ordered list. + +USE_INLINE_TREES = YES + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open +# links to external symbols imported via tag files in a separate window. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of Latex formulas included +# as images in the HTML documentation. The default is 10. Note that +# when you change the font size after a successful doxygen run you need +# to manually remove any form_*.png images from the HTML output directory +# to force them to be regenerated. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are +# not supported properly for IE 6.0, but are supported on all modern browsers. +# Note that when changing this option you need to delete any form_*.png files +# in the HTML output before the changes have effect. + +FORMULA_TRANSPARENT = YES + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box +# for the HTML output. The underlying search engine uses javascript +# and DHTML and should work on any modern browser. Note that when using +# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets +# (GENERATE_DOCSET) there is already a search function so this one should +# typically be disabled. For large projects the javascript based search engine +# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. + +SEARCHENGINE = YES + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a PHP enabled web server instead of at the web client +# using Javascript. Doxygen will generate the search PHP script and index +# file to put on the web server. The advantage of the server +# based approach is that it scales better to large projects and allows +# full text search. The disadvances is that it is more difficult to setup +# and does not have live searching capabilities. + +SERVER_BASED_SEARCH = NO + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. +# Note that when enabling USE_PDFLATEX this option is only used for +# generating bitmaps for formulas in the HTML output, but not in the +# Makefile that is written to the output directory. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = YES + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +# If LATEX_SOURCE_CODE is set to YES then doxygen will include +# source code with syntax highlighting in the LaTeX output. +# Note that which sources are shown also depends on other settings +# such as SOURCE_BROWSER. + +LATEX_SOURCE_CODE = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. +# This is useful +# if you want to understand what is going on. +# On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse +# the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option is superseded by the HAVE_DOT option below. This is only a +# fallback. It is recommended to install and use dot, since it yields more +# powerful graphs. + +CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see +# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = YES + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is +# allowed to run in parallel. When set to 0 (the default) doxygen will +# base this on the number of processors available in the system. You can set it +# explicitly to a value larger than 0 to get control over the balance +# between CPU load and processing speed. + +DOT_NUM_THREADS = 0 + +# By default doxygen will write a font called FreeSans.ttf to the output +# directory and reference it in all dot files that doxygen generates. This +# font does not include all possible unicode characters however, so when you need +# these (or just want a differently looking font) you can specify the font name +# using DOT_FONTNAME. You need need to make sure dot is able to find the font, +# which can be done by putting it in a standard location or by setting the +# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory +# containing the font. + +DOT_FONTNAME = FreeSans + +# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. +# The default size is 10pt. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the output directory to look for the +# FreeSans.ttf font (which doxygen will put there itself). If you specify a +# different font using DOT_FONTNAME you can set the path where dot +# can find it using this tag. + +DOT_FONTPATH = + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = NO + +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs +# for selected functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then +# doxygen will generate a caller dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable caller +# graphs for selected functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of +# nodes that will be shown in the graph. If the number of nodes in a graph +# becomes larger than this value, doxygen will truncate the graph, which is +# visualized by representing a node as a red box. Note that doxygen if the +# number of direct children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note +# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not +# seem to support this out of the box. Warning: Depending on the platform used, +# enabling this option may lead to badly anti-aliased labels on the edges of +# a graph (i.e. they become hard to read). + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..775eb45 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,3 @@ +AUTOMAKE_OPTIONS = foreign +man_MANS = ircd.8 +dist_sysconf_DATA = example.conf example.efnet.conf diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..3002666 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,526 @@ +# Makefile.in generated by automake 1.12.4 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2012 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +VPATH = @srcdir@ +am__make_dryrun = \ + { \ + am__dry=no; \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + echo 'am--echo: ; @echo "AM" OK' | $(MAKE) -f - 2>/dev/null \ + | grep '^AM OK$$' >/dev/null || am__dry=yes;; \ + *) \ + for am__flg in $$MAKEFLAGS; do \ + case $$am__flg in \ + *=*|--*) ;; \ + *n*) am__dry=yes; break;; \ + esac; \ + done;; \ + esac; \ + test $$am__dry = yes; \ + } +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +DIST_COMMON = $(dist_sysconf_DATA) $(srcdir)/Makefile.am \ + $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +SOURCES = +DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } +man8dir = $(mandir)/man8 +am__installdirs = "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(sysconfdir)" +NROFF = nroff +MANS = $(man_MANS) +DATA = $(dist_sysconf_DATA) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AR = @AR@ +ARGZ_H = @ARGZ_H@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DATADIR = @DATADIR@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +GREP = @GREP@ +INCLTDL = @INCLTDL@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LEX = @LEX@ +LEXLIB = @LEXLIB@ +LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@ +LIBADD_DL = @LIBADD_DL@ +LIBADD_DLD_LINK = @LIBADD_DLD_LINK@ +LIBADD_DLOPEN = @LIBADD_DLOPEN@ +LIBADD_SHL_LOAD = @LIBADD_SHL_LOAD@ +LIBDIR = @LIBDIR@ +LIBLTDL = @LIBLTDL@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LOCALSTATEDIR = @LOCALSTATEDIR@ +LTDLDEPS = @LTDLDEPS@ +LTDLINCL = @LTDLINCL@ +LTDLOPEN = @LTDLOPEN@ +LTLIBOBJS = @LTLIBOBJS@ +LT_CONFIG_H = @LT_CONFIG_H@ +LT_DLLOADERS = @LT_DLLOADERS@ +LT_DLPREOPEN = @LT_DLPREOPEN@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PREFIX = @PREFIX@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +SYSCONFDIR = @SYSCONFDIR@ +VERSION = @VERSION@ +YACC = @YACC@ +YFLAGS = @YFLAGS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +ltdl_LIBOBJS = @ltdl_LIBOBJS@ +ltdl_LTLIBOBJS = @ltdl_LTLIBOBJS@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sys_symbol_underscore = @sys_symbol_underscore@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +AUTOMAKE_OPTIONS = foreign +man_MANS = ircd.8 +dist_sysconf_DATA = example.conf example.efnet.conf +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-man8: $(man_MANS) + @$(NORMAL_INSTALL) + @list1=''; \ + list2='$(man_MANS)'; \ + test -n "$(man8dir)" \ + && test -n "`echo $$list1$$list2`" \ + || exit 0; \ + echo " $(MKDIR_P) '$(DESTDIR)$(man8dir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(man8dir)" || exit 1; \ + { for i in $$list1; do echo "$$i"; done; \ + if test -n "$$list2"; then \ + for i in $$list2; do echo "$$i"; done \ + | sed -n '/\.8[a-z]*$$/p'; \ + fi; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^8][0-9a-z]*$$,8,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man8dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man8dir)/$$inst" || exit $$?; \ + fi; \ + done; \ + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man8dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man8dir)" || exit $$?; }; \ + done; } + +uninstall-man8: + @$(NORMAL_UNINSTALL) + @list=''; test -n "$(man8dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.8[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^8][0-9a-z]*$$,8,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + dir='$(DESTDIR)$(man8dir)'; $(am__uninstall_files_from_dir) +install-dist_sysconfDATA: $(dist_sysconf_DATA) + @$(NORMAL_INSTALL) + @list='$(dist_sysconf_DATA)'; test -n "$(sysconfdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(sysconfdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(sysconfdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(sysconfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(sysconfdir)" || exit $$?; \ + done + +uninstall-dist_sysconfDATA: + @$(NORMAL_UNINSTALL) + @list='$(dist_sysconf_DATA)'; test -n "$(sysconfdir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + dir='$(DESTDIR)$(sysconfdir)'; $(am__uninstall_files_from_dir) +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + +cscope cscopelist: + + +distdir: $(DISTFILES) + @list='$(MANS)'; if test -n "$$list"; then \ + list=`for p in $$list; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + if test -f "$$d$$p"; then echo "$$d$$p"; else :; fi; done`; \ + if test -n "$$list" && \ + grep 'ab help2man is required to generate this page' $$list >/dev/null; then \ + echo "error: found man pages containing the 'missing help2man' replacement text:" >&2; \ + grep -l 'ab help2man is required to generate this page' $$list | sed 's/^/ /' >&2; \ + echo " to fix them, install help2man, remove and regenerate the man pages;" >&2; \ + echo " typically 'make maintainer-clean' will remove them" >&2; \ + exit 1; \ + else :; fi; \ + else :; fi + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(MANS) $(DATA) +installdirs: + for dir in "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(sysconfdir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-man + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: install-dist_sysconfDATA + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: install-man8 + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-dist_sysconfDATA uninstall-man + +uninstall-man: uninstall-man8 + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + distclean distclean-generic distclean-libtool distdir dvi \ + dvi-am html html-am info info-am install install-am \ + install-data install-data-am install-dist_sysconfDATA \ + install-dvi install-dvi-am install-exec install-exec-am \ + install-html install-html-am install-info install-info-am \ + install-man install-man8 install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-generic \ + mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \ + ps ps-am uninstall uninstall-am uninstall-dist_sysconfDATA \ + uninstall-man uninstall-man8 + + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/challenge.txt b/doc/challenge.txt new file mode 100644 index 0000000..c50ebb2 --- /dev/null +++ b/doc/challenge.txt @@ -0,0 +1,208 @@ + Oper Challenge and Response System + + $Id$ + + Copyright (c) 2001-2012 by ircd-hybrid team + + ---------------------------------------------------------------------- + + ircd-hybrid + + In an effort to reduce the damage caused to a network by a hacked O-line, + Hybrid supports an OpenSSL based challenge-response system. This new + system allows the admin to remove all oper block passwords from the conf + file. Authentication is done through a public/private key. + + ---------------------------------------------------------------------- + + Requirements + + The ircd must be compiled with the --enable-openssl option to configure. + If configure detects a working openssl library, --enable-openssl is + implicitly enabled. + + oper {} blocks should not have normal passwords, but should contain the + the name of the private key file. However it is possible for the user to + use both challenge and normal passwords, but this would defeat the purpose + of the challenge system. + + m_challenge.la must be loaded. + + The oper has their private key file and an implementation of the RSA + Respond tool available to be run. + + ---------------------------------------------------------------------- + + Process + + Each oper should have a private key file and a public key file. The keys + can be generated with the mkkeypair utility provided in tools/. + + The oper keeps their private key file in a safe place, and gives their + public key file to their admin(s). + + The admin will place an entry for the public key file into a field called + rsa_public_key_file of each oper's oper {} block in the conf file. + + The oper wishes to obtain their operator status, and issues the CHALLENGE + command. + + The server will print out a long hexadecimal string, that needs to be fed + to the respond utility provided in tools/rsa_respond. + + The respond program will generate an answer that is fed back to the + CHALLENGE command. + + ---------------------------------------------------------------------- + + Generating the Key Files + + The keys can be generated with the openssl command as follows: + + openssl genrsa -des3(1) -out rsa.key 1024(2) + openssl rsa -in rsa.key -pubout -out rsa.pub + + + (1) + The -des3 must be included in order to create a key with a + passphrase. Omitting this option will create a non protected key. + (2) + The key size must be 1024 or below. The challenge sent for a + longer keysize will be too long to fit into the ircd's 512 byte + line constraint. + + It is highly recommended that you set a password on your private key. + + The tools/mkkeypair utility cannot be used to create a key suitable for + use in CHALLENGE. + + ---------------------------------------------------------------------- + + Using CHALLENGE and respond + + Note: All examples assume the use of the stock respond client included + with the ircd-hybrid-8 source, run on a UNIX(c) platform. + + The administrator of the server you oper on should remove the password in + your oper {} block and replace it with an entry for your public key, so + that /oper will be disabled. + + Note: The public key is a VERY long string. + + The oper will issue /challenge oper_nick, and see something like below: + + *** 56F1FDAE4C590C524CF758917E62C2A2A1376CB9C4C2E7D411BB0AD9C4A + 605A2D05A94E7254197E9D71438B5FB565B6FD35465E462305F35F4A2D45311 + F983B3E062F635912FA155B4B1E18EAA782CC107F4C9DA83092658D16A2E88A + 6BCF9820F5A044A29CDD4C062F05BF509CA3B561375CBC4179BD1CF6026BDE9 + 60E52C6B + + Note: The challenge is all on one line. + + Note: With some clients, the oper will have to issue /quote CHALLENGE + instead of /challenge. + + The oper will then have to feed that challenge to the respond program. + + +------------------------------------------------------------------+ + | The respond utility's syntax is: | + | | + |$ ./respond private_key_file challenge_from_server | + | | + | | + | Example: | + | | + |wcampbel@botbay (rsa_respond): ./respond hwy.key \ | + |56F1FDAE4C590C524CF758917E62C2A2A1376CB9C4C2E7D411BB0AD9C4A605A2D0| + |5A94E7254197E9D71438B5FB565B6FD35465E462305F35F4A2D45311F983B3E062| + |F635912FA155B4B1E18EAA782CC107F4C9DA83092658D16A2E88A6BCF9820F5A04| + |4A29CDD4C062F05BF509CA3B561375CBC4179BD1CF6026BDE960E52C6B | + |Keyphrase: | + |6B882932DD00F86123869E401F7334B9B0D0018A60F1DE244E90E47246AA87C7 | + | | + | Note: The challenge parameter must be on one line. | + +------------------------------------------------------------------+ + + The keyphrase must be entered properly to get the response. The bottom + line is the response that must be sent back to the server. + + The oper will issue the following command in order to obtain operator + status: + + /challenge + +6B882932DD00F86123869E401F7334B9B0D0018A60F1DE244E90E47246AA87C7 + + Note: The '+' is needed + + If successful, the oper will obtain operator status on the server. + + +------------------------------------------------------------------------+ + | Warning | + |------------------------------------------------------------------------| + | If the CHALLENGE fails, and you use ircII, EPIC, or BX, you may get | + | disconnected with the client asking for the server password. This is a | + | client bug, not an ircd bug. | + +------------------------------------------------------------------------+ + + ---------------------------------------------------------------------- + + RSA Respond Tool + + The RSA Respond tool is a vital part of challenge/response system. In + order to function, the operator must have must have a way to quickly issue + the respond command, and to copy and paste data to and from the IRC + client. + + The respond source code is included with the ircd-hybrid source, in the + tools/rsa_respond directory. + + A copy of the source tar file is available on + http://www.wohmart.com/ircd/pub/irc_tools/rsa/rsa_respond-src-hyb7.tar.gz + + For Windows platforms, there are two available RSA Respond tools. One is a + text only port of the stock tool. The binary is available from + http://www.wohmart.com/ircd/pub/irc_tools/rsa/rsa_respond-bin.tar.gz. + The other tool is a GUI enabled version[3]. The source tree[4] is available + from http://www.wohmart.com/ircd/pub/irc_tools/rsa/winrespond-src.tar.gz. + A binary distribution is available from + http://www.wohmart.com/ircd/pub/irc_tools/rsa/winrespond-bin.tar.gz. + + With the appropriate version of the RSA Respond tool, any operator can + protect their privileged access to the server, with little additional + effort over using standard operator passwords. + + ---------------------------------------------------------------------- + + Benefits + + The greatest benefit of using the challenge/response system is that there + are no passwords sent over the network in plaintext. There are also no + credentials left on the server side, as only public keys are kept in the + conf. The use of public/private key encryption provides far greater + security over having a single password, and may (if the key is kept + secure, and has a good passphrase) virtually eliminate hacked O-lines. + + ---------------------------------------------------------------------- + + A. Numerics + + :server 381 user :You have entered... the Twilight Zone!. + :server 386 user :challenge-text + :server 464 user :Password Incorrect + :server 491 user :Only few of mere mortals may try to enter the twilight zone + + + Note: The text used can be changed by the server administrator. + + ---------------------------------------------------------------------- + + Notes + + [1] Some platforms may require Makefile changes in order to link in the + OpenSSL library. This may change in the future. + [2] Platforms known to function include: Linux, FreeBSD, Solaris, and + Cygwin. + [3] A screenshot of the program is available on + http://www.wohmart.com/ircd/pub/irc_tools/rsa/winrespond.png . + [4] The winrespond source depends on a working, up to date, Cygwin + installation. diff --git a/doc/example.conf b/doc/example.conf new file mode 100644 index 0000000..e260214 --- /dev/null +++ b/doc/example.conf @@ -0,0 +1,1232 @@ +/* doc/example.conf - ircd-hybrid-8 Example configuration file + * Copyright (C) 2000-2012 Hybrid Development Team + * + * Written by ejb, wcampbel, db, leeh and others + * Other example configurations can be found in the source dir under + * doc/. + * + * $Id$ + */ + +/* IMPORTANT NOTES: + * + * auth {} blocks MUST be specified in order of precedence. The first one + * that matches a user will be used. So place spoofs first, then specials, + * then general access. + * + * Shell style (#), C++ style (//) and C style comments are supported. + * + * Files may be included by either: + * .include "filename" + * .include <filename> + * + * Times/durations are written as: + * 12 hours 30 minutes 1 second + * + * Valid units of time: + * month, week, day, hour, minute, second + * + * Valid units of size: + * megabyte/mbyte/mb, kilobyte/kbyte/kb, byte + * + * Sizes and times may be singular or plural. + */ + +/* EFNET NOTE: + * + * This config file is NOT suitable for EFNet. EFNet admins should use + * example.efnet.conf + */ + +/* + * serverinfo {}: contains information about the server + */ +serverinfo { + /* + * name: the name of this server. This cannot be changed at runtime. + */ + name = "hades.arpa"; + + /* + * sid: a server's unique ID. This is three characters long and must + * be in the form [0-9][A-Z0-9][A-Z0-9]. The first character must be + * a digit, followed by 2 alpha-numerical letters. + * NOTE: The letters must be capitalized. This cannot be changed at runtime. + */ + sid = "_CHANGE_ME_"; + + /* + * description: the description of the server. + */ + description = "ircd-hybrid test server"; + + /* + * network info: the name and description of the network this server + * is on. Shown in the 005 reply and used with serverhiding. + */ + network_name = "MyNet"; + network_desc = "This is My Network"; + + /* + * hub: allow this server to act as a hub and have multiple servers + * connected to it. + */ + hub = no; + + /* + * vhost: the IP to bind to when we connect outward to ipv4 servers. + * This should be an ipv4 IP only, or "*" for INADDR_ANY. + */ + #vhost = "192.169.0.1"; + + /* + * vhost6: the IP to bind to when we connect outward to ipv6 servers. + * This should be an ipv6 IP only, or "*" for INADDR_ANY. + */ + #vhost6 = "3ffe:80e8:546::2"; + + /* max_clients: the maximum number of clients allowed to connect */ + max_clients = 512; + + /* + * rsa_private_key_file: the path to the file containing our + * rsa key for cryptlink. + * + * Example command to store a 2048 bit RSA keypair in + * rsa.key, and the public key in rsa.pub: + * + * openssl genrsa -out rsa.key 2048 + * openssl rsa -in rsa.key -pubout -out rsa.pub + * chown <ircd-user>.<ircd.group> rsa.key rsa.pub + * chmod 0600 rsa.key + * chmod 0644 rsa.pub + */ + #rsa_private_key_file = "/usr/local/ircd/etc/rsa.key"; + + /* + * ssl_certificate_file: the path to the file containing our + * ssl certificate for encrypted client connection. + * + * This assumes your private RSA key is stored in rsa.key. You + * MUST have an RSA key in order to generate the certificate + * + * openssl req -new -days 365 -x509 -key rsa.key -out cert.pem + * + * See http://www.openssl.org/docs/HOWTO/certificates.txt + * + * Please use the following values when generating the cert + * + * Organization Name: Network Name + * Organization Unit Name: changme.someirc.net + * Common Name: irc.someirc.net + * E-mail: you@domain.com + */ + #ssl_certificate_file = "/usr/local/ircd/etc/cert.pem"; + + /* + * ssl_dh_param_file: + * + * Path to the PEM encoded Diffie-Hellman parameter file. + * DH parameters are strictly required when using ciphers + * with EDH (ephemeral Diffie-Hellman) key exchange. + * + * A DH parameter file can be created by running: + * + * openssl dhparam -out dhparam.pem 1024 + * + * Prime size must be at least 1024 bits. Further information + * regarding specific OpenSSL dhparam command-line options + * can be found in the OpenSSL manual. + */ + #ssl_dh_param_file = "/usr/local/ircd/etc/dhparam.pem"; + + /* + * ssl_cipher_list: + * + * List of ciphers that are supported by _this_ server. Can be used to + * enforce specific ciphers for incoming SSL/TLS connections. + * If a client (which also includes incoming server connections) isn't + * capable of any cipher listed below, the connection will simply be + * rejected. + * + * A list of supported ciphers can be obtained by running: + * + * openssl ciphers -ssl3 -tls1 -v + * + * Multiple ciphers are separated by colons. The order of preference is + * from left to right. + */ + #ssl_cipher_list = "DHE-RSA-AES256-SHA:AES256-SHA"; + + /* + * ssl_server_method: + * ssl_client_method: + * + * SSL/TLS methods we provide for incoming (server method) and + * outgoing (client method) SSL/TLS connections. + * This can be either sslv3 for SSLv3, and/or tlsv1 for TLSv1. + */ + #ssl_server_method = tlsv1, sslv3; + #ssl_client_method = tlsv1; +}; + +/* + * admin {}: contains admin information about the server + */ +admin { + name = "Smurf target"; + description = "Main Server Administrator"; + email = "<syn@packets.r.us>"; +}; + +/* + * class {}: contains information about classes for users + */ +class { + /* name: the name of the class */ + name = "users"; + + /* + * ping_time: how often a client must reply to a PING from the + * server before they are dropped. + */ + ping_time = 90 seconds; + + /* + * number_per_ip: how many local users are allowed to connect + * from one IP (optional) + */ + number_per_ip = 2; + + /* + * max_local: how many local users are allowed to connect + * from one ident@host (optional) + */ + max_local = 2; + + /* + * max_global: network-wide limit of users per ident@host (optional) + */ + max_global = 10; + + /* + * max_number: the maximum number of users allowed in this class (optional) + */ + max_number = 100; + + /* + * the following lines are optional and allow you to define + * how many users can connect from one /NN subnet + */ + cidr_bitlen_ipv4 = 24; + cidr_bitlen_ipv6 = 120; + number_per_cidr = 16; + + /* + * sendq: the amount of data allowed in a clients send queue before + * they are dropped. + */ + sendq = 100 kbytes; + + /* + * recvq: maximum amount of data in a clients receive queue before + * they are dropped for flooding. Defaults to 2560 if the chosen + * value isn't within the range of 512 to 8000. + */ + recvq = 2560 bytes; +}; + +class { + name = "opers"; + ping_time = 90 seconds; + number_per_ip = 10; + max_number = 100; + sendq = 100 kbytes; +}; + +class { + name = "server"; + ping_time = 90 seconds; + + /* + * ping_warning: how fast a server must reply to a PING before + * a warning to opers is generated. + */ + ping_warning = 15 seconds; + + /* + * connectfreq: only used in server classes. Specifies the delay + * between autoconnecting to servers. + */ + connectfreq = 5 minutes; + + /* max number: the amount of servers to autoconnect to */ + max_number = 1; + + /* sendq: servers need a higher sendq as they send more data */ + sendq = 2 megabytes; +}; + +/* + * listen {}: contains information about the ports ircd listens on + */ +listen { + /* + * port: the specific port to listen on. If no host is specified + * before, it will listen on all available IPs. + * + * Ports are separated via a comma, a range may be specified using ".." + */ + + /* port: listen on all available IPs, ports 6665 to 6669 */ + port = 6665 .. 6669; + + /* + * Listen on 192.168.0.1/6697 with ssl enabled and hidden from STATS P + * unless you are an administrator. + * + * NOTE: The "flags" directive has to come before "port". Always! + * + * Currently available flags are: + * + * ssl - Port is for SSL client connections only + * server - Only server connections are permitted + * hidden - Port is hidden from /stats P, unless you're an admin + */ + flags = hidden, ssl; + host = "192.168.0.1"; + port = 6697; + + /* + * host: set a specific IP/host the ports after the line will listen + * on. This may be ipv4 or ipv6. + */ + host = "1.2.3.4"; + port = 7000, 7001; + + host = "3ffe:1234:a:b:c::d"; + port = 7002; +}; + +/* + * auth {}: allow users to connect to the ircd + */ +auth { + /* + * user: the user@host allowed to connect. Multiple user + * lines are permitted per auth block. + */ + user = "*@172.16.0.0/12"; + user = "*test@123D:B567:*"; + + /* password: an optional password that is required to use this block */ + password = "letmein"; + + /* + * encrypted: controls whether the auth password above has been + * encrypted. + */ + encrypted = yes; + + /* + * spoof: fake the users host to this. This is free-form, + * just do everyone a favor and don't abuse it. ('=' prefix on /stats I) + */ + spoof = "I.still.hate.packets"; + + /* class: the class the user is placed in */ + class = "opers"; + + /* + * need_password - don't allow users who haven't supplied the correct + * password to connect using another auth{} block + * ('&' prefix on /stats I if disabled) + * need_ident - require the user to have identd to connect ('+' prefix on /stats I) + * spoof_notice - enable spoofing notification to admins + * exceed_limit - allow a user to exceed class limits ('>' prefix on /stats I) + * kline_exempt - exempt this user from k/glines ('^' prefix on /stats I) + * gline_exempt - exempt this user from glines ('_' prefix on /stats I) + * resv_exempt - exempt this user from resvs ('$' prefix on /stats I) + * no_tilde - remove ~ from a user with no ident ('-' prefix on /stats I) + * can_flood - allow this user to exceed flood limits ('|' prefix on /stats I) + */ + flags = need_password, spoof_notice, exceed_limit, kline_exempt, + gline_exempt, resv_exempt, no_tilde, can_flood; +}; + +auth { + /* + * redirect: the server and port to redirect a user to. A user does + * not have to obey the redirection, the ircd just suggests an alternative + * server for them. + */ + redirserv = "this.is.not.a.real.server"; + redirport = 6667; + + user = "*.server"; + + /* class: a class is required even though it is not used */ + class = "users"; +}; + +auth { + user = "*@*"; + class = "users"; + flags = need_ident; +}; + +/* + * operator {}: defines ircd operators + * + * ircd-hybrid no longer supports local operators, privileges are + * controlled via flags. + */ +operator { + /* name: the name of the oper */ + name = "sheep"; + + /* + * user: the user@host required for this operator. Multiple + * user="" lines are supported. + */ + user = "*sheep@192.168.0.0/16"; + user = "*@127.0.0.0/8"; + + /* + * password: the password required to oper. By default this will + * need to be encrypted by using the provided mkpasswd tool. + * Several password hash algorithms are available depending + * on your system's crypt() implementation. For example, a modern + * glibc already has support for SHA-256/512, and MD5 encryption + * algorithms. + */ + password = "$5$x5zof8qe.Yc7/bPp$5zIg1Le2Lsgd4CvOjaD20pr5PmcfD7ha/9b2.TaUyG4"; + + /* + * encrypted: controls whether the oper password above has been + * encrypted. + */ + encrypted = yes; + + /* + * rsa_public_key_file: the public key for this oper when using Challenge. + * A password should not be defined when this is used, see + * doc/challenge.txt for more information. + */ +# rsa_public_key_file = "/usr/local/ircd/etc/oper.pub"; + + /* class: the class the oper joins when they successfully /oper */ + class = "opers"; + + /* + * umodes: default usermodes opers get when they /oper. If defined, + * it will override oper_umodes settings in general {}. + * Available usermodes: + * + * +b - bots - See bot and drone flooding notices + * +c - cconn - Client connection/quit notices + * +C - cconn_full - Client connection/quit notices full + * +D - deaf - Don't receive channel messages + * +d - debug - See debugging notices + * +f - full - See auth{} block full notices + * +G - softcallerid - Server Side Ignore for users not on your channels + * +g - callerid - Server Side Ignore (for privmsgs etc) + * +H - hidden - Hides operator status to other users + * +i - invisible - Not shown in NAMES or WHO unless you share a + * a channel + * +j - rej - See rejected client notices + * +k - skill - See server generated KILL messages + * +l - locops - See LOCOPS messages + * +n - nchange - See client nick changes + * +s - servnotice - See general server notices + * +u - unauth - See unauthorized client notices + * +w - wallop - See server generated WALLOPS + * +x - external - See remote server connection and split notices + * +y - spy - See LINKS, STATS, TRACE notices etc. + * +z - operwall - See oper generated WALLOPS + */ +# umodes = locops, servnotice, operwall, wallop; + + /* + * privileges: controls the activities and commands an oper is + * allowed to do on the server. All options default to no. + * Available options: + * + * module - allows MODULE + * global_kill - allows remote users to be /KILL'd + * remote - allows remote SQUIT and CONNECT + * remoteban - allows remote KLINE/UNKLINE + * dline - allows DLINE + * undline - allows UNDLINE + * kline - allows KILL and KLINE + * unkline - allows UNKLINE + * gline - allows GLINE + * xline - allows XLINE + * globops - allows GLOBOPS + * operwall - allows OPERWALL + * nick_changes - allows oper to see nickchanges via usermode +n + * rehash - allows oper to REHASH config + * die - allows DIE + * restart - allows RESTART + * set - allows SET + * admin - gives admin privileges. admins for example, + * may see the real IP addresses of servers. + */ + flags = global_kill, remote, kline, unkline, xline, globops, restart, + die, rehash, nick_changes, admin, operwall, module; +}; + +/* + * service {}: specifies what server may act as a network service + * + * NOTE: it is absolutely important that every single server on the network + * has the same service{} block. + */ +service { + name = "service.someserver"; + name = "stats.someserver"; +}; + +/* + * connect {}: controls servers we connect to + */ +connect { + /* name: the name of the server */ + name = "irc.uplink.com"; + + /* + * host: the host or IP to connect to. If a hostname is used it + * must match the reverse dns of the server. + */ + host = "192.168.0.1"; + + /* + * vhost: the IP to bind to when we connect outward to servers. + * serverinfo::vhost and serverinfo::vhost6 will be overridden + * by this directive. + */ + vhost = "192.168.0.2"; + + /* + * passwords: the passwords we send (OLD C:) and accept (OLD N:). + * The remote server will have these passwords reversed. + */ + send_password = "password"; + accept_password = "anotherpassword"; + + /* + * encrypted: controls whether the accept_password above has been + * encrypted. + */ + encrypted = no; + + /* port: the port to connect to this server on */ + port = 6666; + + /* + * hub_mask: the mask of servers that this server may hub. Multiple + * entries are permitted + */ + hub_mask = "*"; + + /* + * leaf_mask: the mask of servers this server may not hub. Multiple + * entries are permitted. Useful for forbidding EU -> US -> EU routes. + */ +# leaf_mask = "*.uk"; + + /* class: the class this server is in */ + class = "server"; + + /* + * ssl_cipher_list: + * + * List of ciphers that the server we are connecting to must support. + * If the server isn't capable of any cipher listed below, the + * connection will simply be rejected. + * Can be used to enforce stronger ciphers, even though this option + * is not necessarily required to establish a SSL/TLS connection. + * + * Multiple ciphers are separated by colons. The order of preference + * is from left to right. + */ + #ssl_cipher_list = "DHE-RSA-AES256-SHA:AES256-SHA"; + + /* + * autoconn - controls whether we autoconnect to this server or not, + * dependent on class limits. By default, this is disabled. + * ssl - Initiates a TLS/SSL connection. + */ +# flags = autoconn, ssl; +}; + +connect { + name = "ipv6.some.server"; + host = "3ffd:dead:beef::1"; + send_password = "password"; + accept_password = "password"; + port = 6666; + + /* + * aftype: controls whether the connection uses "ipv4" or "ipv6". + * Default is ipv4. + */ + aftype = ipv6; + class = "server"; +}; + +/* + * cluster {}: servers that share klines/unkline/xline/unxline/resv/unresv/locops + * automatically + */ +cluster { + /* + * name: the server to share with, this can take wildcards + * + * NOTE: only local actions will be clustered, meaning if + * the server receives a shared kline/unkline/etc, it + * will not be propagated to clustered servers. + * + * Remote servers are not necessarily required to accept + * clustered lines, they need a shared{} for *THIS* server + * in order to accept them. + */ + name = "*.arpa"; + + /* + * type: list of what to share, options are as follows: + * dline - share dlines + * undline - share undlines + * kline - share klines + * unkline - share unklines + * xline - share xlines + * unxline - share unxlines + * resv - share resvs + * unresv - share unresvs + * locops - share locops + * all - share all of the above (default) + */ + type = kline, unkline, locops, xline, resv; +}; + +/* + * shared {}: users that are allowed to remote kline + * + * NOTE: This can be effectively used for remote klines. + * Please note that there is no password authentication + * for users setting remote klines. You must also be + * /oper'd in order to issue a remote kline. + */ +shared { + /* + * name: the server the user must be on to set klines. If this is not + * specified, the user will be allowed to kline from all servers. + */ + name = "irc2.some.server"; + + /* + * user: the user@host mask that is allowed to set klines. If this is + * not specified, all users on the server above will be allowed to set + * a remote kline. + */ + user = "oper@my.host.is.spoofed"; + + /* + * type: list of what to share, options are as follows: + * dline - allow oper/server to dline + * undline - allow oper/server to undline + * kline - allow oper/server to kline + * unkline - allow oper/server to unkline + * xline - allow oper/server to xline + * unxline - allow oper/server to unxline + * resv - allow oper/server to resv + * unresv - allow oper/server to unresv + * locops - allow oper/server to locops - only used for servers that cluster + * all - allow oper/server to do all of the above (default) + */ + type = kline, unkline, resv; +}; + +/* + * kill {}: users that are not allowed to connect + * Oper issued klines will be added to the specified kline config + */ +kill { + user = "bad@*.hacked.edu"; + reason = "Obviously hacked account"; +}; + +kill { + user = "^O[[:alpha:]]?[[:digit:]]+(x\.o|\.xo)$@^[[:alnum:]]{4}\.evilnet.tld$"; + + /* + * NOTE: You have to set type=regex; when using a regular expression + * based user entry + */ + type = regex; +}; + +/* + * deny {}: IPs that are not allowed to connect (before DNS/ident lookup) + * Oper issued dlines will be added to the specified dline config + */ +deny { + ip = "10.0.1.0/24"; + reason = "Reconnecting vhosted bots"; +}; + +/* + * exempt {}: IPs that are exempt from deny {} and Dlines + */ +exempt { + ip = "192.168.0.0/16"; +}; + +/* + * resv {}: nicks and channels users may not use/join + */ +resv { + /* reason: the reason for the proceeding resv's */ + reason = "Reserved for services"; + + /* resv: the nicks and channels users may not join/use */ + nick = "Global"; + nick = "DevNull"; + nick = "BotServ"; + nick = "Services"; + nick = "StatServ"; + nick = "HelpServ"; + nick = "HostServ"; + nick = "NickServ"; + nick = "ChanServ"; + nick = "MemoServ"; + nick = "OperServ"; + channel = "#services"; + + /* resv: wildcard masks are also supported in nicks only */ + reason = "Clone bots"; + nick = "clone*"; +}; + +/* + * gecos {}: The X: replacement, used for banning users based on + * their "realname". + */ +gecos { + name = "*sex*"; + reason = "Possible spambot"; +}; + +gecos { + name = "sub7server"; + reason = "Trojan drone"; +}; + +gecos { + name = "*http*"; + reason = "Spambot"; +}; + +gecos { + name = "^\[J[0o]hn Do[3e]\]-[0-9]{2,5}$"; + + /* + * NOTE: You have to set type=regex; when using a regular expression + * based name entry + */ + type = regex; +}; + +/* + * channel {}: The channel block contains options pertaining to channels + */ +channel { + /* + * disable_fake_channels: this option, if set to 'yes', will + * disallow clients to create or join channels that have one + * of the following ASCII characters in their name: + * + * 2 | bold + * 3 | mirc color + * 15 | plain text + * 22 | reverse + * 29 | italic + * 31 | underline + * 160 | non-breaking space + */ + disable_fake_channels = yes; + + /* + * restrict_channels: reverse channel RESVs logic, only reserved + * channels are allowed + */ + restrict_channels = no; + + /* + * knock_delay: The amount of time a user must wait between issuing + * the knock command. + */ + knock_delay = 5 minutes; + + /* + * knock_delay_channel: How often a knock to any specific channel + * is permitted, regardless of the user sending the knock. + */ + knock_delay_channel = 1 minute; + + /* + * max_chans_per_user: The maximum number of channels a user can + * join/be on. + */ + max_chans_per_user = 25; + + /* + * max_chans_per_oper: The maximum number of channels an oper can + * join/be on. + */ + max_chans_per_oper = 50; + + /* quiet_on_ban: stop banned people talking in channels. */ + quiet_on_ban = yes; + + /* max_bans: maximum number of +b/e/I modes in a channel */ + max_bans = 100; + + /* + * how many joins in how many seconds constitute a flood, use 0 to + * disable. +b opers will be notified (changeable via /set) + */ + join_flood_count = 16; + join_flood_time = 8 seconds; + + /* + * splitcode: The ircd will now check splitmode every few seconds. + * + * Either split users or split servers can activate splitmode, but + * both conditions must be met for the ircd to deactivate splitmode. + * + * You may force splitmode to be permanent by /quote set splitmode on + */ + + /* + * default_split_user_count: when the usercount is lower than this level, + * consider ourselves split. This must be set for automatic splitmode. + */ + default_split_user_count = 0; + + /* + * default_split_server_count: when the servercount is lower than this, + * consider ourselves split. This must be set for automatic splitmode. + */ + default_split_server_count = 0; + + /* no_create_on_split: disallow users creating channels on split. */ + no_create_on_split = yes; + + /* no_join_on_split: disallow users joining channels at all on a split. */ + no_join_on_split = no; +}; + +/* + * serverhide {}: The serverhide block contains the options regarding + * serverhiding + */ +serverhide { + /* + * flatten_links: this option will show all servers in /links appear + * that they are linked to this current server + */ + flatten_links = no; + + /* + * links_delay: how often to update the links file when it is + * flattened. + */ + links_delay = 5 minutes; + + /* + * hidden: hide this server from a /links output on servers that + * support it. This allows hub servers to be hidden etc. + */ + hidden = no; + + /* + * hide_servers: hide remote servernames everywhere and instead use + * hidden_name and network_desc. + */ + hide_servers = no; + + /* + * Use this as the servername users see if hide_servers = yes. + */ + hidden_name = "*.hidden.com"; + + /* + * hide_server_ips: If this is disabled, opers will be unable to see + * servers ips and will be shown a masked ip, admins will be shown the + * real ip. + * + * If this is enabled, nobody can see a servers ip. *This is a kludge*, + * it has the side effect of hiding the ips everywhere, including + * logfiles. + * + * We recommend you leave this disabled, and just take care with who you + * give admin=yes; to. + */ + hide_server_ips = no; +}; + +/* + * general {}: The general block contains many of the options that were once + * compiled in options in config.h. The general block is read at start time. + */ +general { + /* services_name: servername of nick/channel services */ + services_name = "service.someserver"; + + /* max_watch: maximum WATCH entries a client can have. */ + max_watch = 60; + + /* gline_enable: enable glines, network wide temp klines */ + gline_enable = yes; + + /* + * gline_duration: the amount of time a gline will remain on your + * server before expiring + */ + gline_duration = 1 day; + + /* + * gline_request_duration: how long a pending G-line can be around. + * 10 minutes should be plenty + */ + gline_request_duration = 10 minutes; + + /* + * gline_min_cidr: the minimum required length of a CIDR bitmask + * for IPv4 based glines + */ + gline_min_cidr = 16; + + /* + * gline_min_cidr6: the minimum required length of a CIDR bitmask + * for IPv6 based glines + */ + gline_min_cidr6 = 48; + + /* + * Whether to automatically set mode +i on connecting users. + */ + invisible_on_connect = yes; + + /* + * Max time from the nickname change that still causes KILL + * automatically to switch for the current nick of that user. + */ + kill_chase_time_limit = 90 seconds; + + /* + * If hide_spoof_ips is disabled, opers will be allowed to see the real + * IP of spoofed users in /trace etc. If this is defined they will be + * shown a masked IP. + */ + hide_spoof_ips = yes; + + /* + * Ignore bogus timestamps from other servers. Yes, this will desync + * the network, but it will allow chanops to resync with a valid non TS 0 + * + * This should be enabled network wide, or not at all. + */ + ignore_bogus_ts = no; + + /* + * disable_auth: completely disable ident lookups; if you enable this, + * be careful of what you set need_ident to in your auth {} blocks + */ + disable_auth = no; + + /* disable_remote_commands: disable users doing commands on remote servers */ + disable_remote_commands = no; + + /* + * tkline_expire_notices: enables or disables temporary kline/xline + * expire notices. + */ + tkline_expire_notices = no; + + /* + * default_floodcount: the default value of floodcount that is configurable + * via /quote set floodcount. This is the amount of lines a user + * may send to any other user/channel in one second. + */ + default_floodcount = 10; + + /* + * failed_oper_notice: send a notice to all opers on the server when + * someone tries to OPER and uses the wrong password, host or ident. + */ + failed_oper_notice = yes; + + /* + * dots_in_ident: the amount of '.' characters permitted in an ident + * reply before the user is rejected. + */ + dots_in_ident = 2; + + /* + * min_nonwildcard: the minimum non wildcard characters in k/d/g lines + * placed via the server. klines hand placed are exempt from limits. + * wildcard chars: '.' ':' '*' '?' '@' '!' '#' + */ + min_nonwildcard = 4; + + /* + * min_nonwildcard_simple: the minimum non wildcard characters in + * gecos bans. wildcard chars: '*' '?' '#' + */ + min_nonwildcard_simple = 3; + + /* max_accept: maximum allowed /accept's for +g usermode */ + max_accept = 20; + + /* anti_nick_flood: enable the nickflood control code */ + anti_nick_flood = yes; + + /* nick flood: the nick changes allowed in the specified period */ + max_nick_time = 20 seconds; + max_nick_changes = 5; + + /* + * anti_spam_exit_message_time: the minimum time a user must be connected + * before custom quit messages are allowed. + */ + anti_spam_exit_message_time = 5 minutes; + + /* + * ts delta: the time delta allowed between server clocks before + * a warning is given, or before the link is dropped. all servers + * should run ntpdate/rdate to keep clocks in sync + */ + ts_warn_delta = 30 seconds; + ts_max_delta = 5 minutes; + + /* + * warn_no_nline: warn opers about servers that try to connect but + * we don't have a connect {} block for. Twits with misconfigured + * servers can get really annoying with this enabled. + */ + warn_no_nline = yes; + + /* + * stats_e_disabled: set this to 'yes' to disable "STATS e" for both + * operators and administrators. Doing so is a good idea in case + * there are any exempted (exempt{}) server IPs you don't want to + * see leaked. + */ + stats_e_disabled = no; + + /* stats_o_oper only: make stats o (opers) oper only */ + stats_o_oper_only = yes; + + /* stats_P_oper_only: make stats P (ports) oper only */ + stats_P_oper_only = yes; + + /* + * stats i oper only: make stats i (auth {}) oper only. set to: + * yes: show users no auth blocks, made oper only. + * masked: show users first matching auth block + * no: show users all auth blocks. + */ + stats_i_oper_only = yes; + + /* + * stats_k_oper_only: make stats k/K (klines) oper only. set to: + * yes: show users no auth blocks, made oper only + * masked: show users first matching auth block + * no: show users all auth blocks. + */ + stats_k_oper_only = yes; + + /* + * caller_id_wait: time between notifying a +g user that somebody + * is messaging them. + */ + caller_id_wait = 1 minute; + + /* + * opers_bypass_callerid: allows operators to bypass +g and message + * anyone who has it set (useful if you use services). + */ + opers_bypass_callerid = no; + + /* + * pace_wait_simple: time between use of less intensive commands + * (ADMIN, HELP, (L)USERS, VERSION, remote WHOIS) + */ + pace_wait_simple = 1 second; + + /* + * pace_wait: time between more intensive commands + * (AWAY, INFO, LINKS, MAP, MOTD, STATS, WHO, wildcard WHOIS, WHOWAS) + */ + pace_wait = 10 seconds; + + /* + * short_motd: send clients a notice telling them to read the motd + * instead of forcing a motd to clients who may simply ignore it. + */ + short_motd = no; + + /* + * ping_cookie: require clients to respond exactly to a ping command, + * can help block certain types of drones and FTP PASV mode spoofing. + */ + ping_cookie = no; + + /* no_oper_flood: increase flood limits for opers. */ + no_oper_flood = yes; + + /* + * true_no_oper_flood: completely eliminate flood limits for opers + * and for clients with can_flood = yes in their auth {} blocks + */ + true_no_oper_flood = yes; + + /* oper_pass_resv: allow opers to over-ride RESVs on nicks/channels */ + oper_pass_resv = yes; + + /* REMOVE ME. The following line checks you've been reading. */ + havent_read_conf = 1; + + /* + * max_targets: the maximum amount of targets in a single + * PRIVMSG/NOTICE. Set to 999 NOT 0 for unlimited. + */ + max_targets = 4; + + /* + * message_locale: the default message locale + * Use "standard" for the compiled in defaults. + * To install the translated messages, go into messages/ in the + * source directory and run `make install'. + */ + message_locale = "standard"; + + /* + * usermodes configurable: a list of usermodes for the options below + * + * +b - bots - See bot and drone flooding notices + * +c - cconn - Client connection/quit notices + * +C - cconn_full - Client connection/quit notices full + * +D - deaf - Don't receive channel messages + * +d - debug - See debugging notices + * +f - full - See auth{} block full notices + * +G - softcallerid - Server Side Ignore for users not on your channels + * +g - callerid - Server Side Ignore (for privmsgs etc) + * +H - hidden - Hides operator status to other users + * +i - invisible - Not shown in NAMES or WHO unless you share a + * a channel + * +j - rej - See rejected client notices + * +k - skill - See server generated KILL messages + * +l - locops - See LOCOPS messages + * +n - nchange - See client nick changes + * +s - servnotice - See general server notices + * +u - unauth - See unauthorized client notices + * +w - wallop - See server generated WALLOPS + * +x - external - See remote server connection and split notices + * +y - spy - See LINKS, STATS, TRACE notices etc. + * +z - operwall - See oper generated WALLOPS + */ + + /* oper_only_umodes: usermodes only opers may set */ + oper_only_umodes = bots, cconn, cconn_full, debug, full, hidden, skill, + nchange, rej, spy, external, operwall, + locops, unauth; + + /* oper_umodes: default usermodes opers get when they /oper */ + oper_umodes = bots, locops, servnotice, operwall, wallop; + + /* + * use_egd: if your system does not have *random devices yet you + * want to use OpenSSL and encrypted links, enable this. Beware - + * EGD is *very* CPU intensive when gathering data for its pool + */ +# use_egd = yes; + + /* + * egdpool_path: path to EGD pool. Not necessary for OpenSSL >= 0.9.7 + * which automatically finds the path. + */ +# egdpool_path = "/var/run/egd-pool"; + + /* + * throttle_time: the minimum amount of time between connections from + * the same ip. exempt {} blocks are excluded from this throttling. + * Offers protection against flooders who reconnect quickly. + * Set to 0 to disable. + */ + throttle_time = 10; +}; + +modules { + /* + * path: other paths to search for modules specified below + * and in "/module load". + */ + path = "/usr/local/ircd/lib/ircd-hybrid/modules"; + path = "/usr/local/ircd/lib/ircd-hybrid/modules/autoload"; + + /* module: the name of a module to load on startup/rehash */ + #module = "some_module.la"; +}; + +/* + * log {}: contains information about logfiles. + */ +log { + /* Do you want to enable logging to ircd.log? */ + use_logging = yes; + + file { + type = oper; + name = "/home/ircd/var/log/oper.log"; + size = unlimited; + }; + + file { + type = user; + name = "/home/ircd/var/log/user.log"; + size = 50 megabytes; + }; + + file { + type = kill; + name = "/home/ircd/var/log/kill.log"; + size = 50 megabytes; + }; + + file { + type = kline; + name = "/home/ircd/var/log/kline.log"; + size = 50 megabytes; + }; + + file { + type = dline; + name = "/home/ircd/var/log/dline.log"; + size = 50 megabytes; + }; + + file { + type = gline; + name = "/home/ircd/var/log/gline.log"; + size = 50 megabytes; + }; + + file { + type = debug; + name = "/home/ircd/var/log/debug.log"; + size = 50 megabytes; + }; +}; diff --git a/doc/example.efnet.conf b/doc/example.efnet.conf new file mode 100644 index 0000000..2af4d03 --- /dev/null +++ b/doc/example.efnet.conf @@ -0,0 +1,1260 @@ +/* doc/example.efnet.conf - ircd-hybrid-8 EFnet Example configuration file + * Copyright (C) 2000-2012 Hybrid Development Team + * + * Written by ejb, wcampbel, db, leeh and others + * Other example configurations can be found in the source dir under + * doc/. + * + * $Id$ + */ + +/* IMPORTANT NOTES: + * + * auth {} blocks MUST be specified in order of precedence. The first one + * that matches a user will be used. So place spoofs first, then specials, + * then general access. + * + * Shell style (#), C++ style (//) and C style comments are supported. + * + * Files may be included by either: + * .include "filename" + * .include <filename> + * + * Times/durations are written as: + * 12 hours 30 minutes 1 second + * + * Valid units of time: + * month, week, day, hour, minute, second + * + * Valid units of size: + * megabyte/mbyte/mb, kilobyte/kbyte/kb, byte + * + * Sizes and times may be singular or plural. + */ + +/* EFNET NOTE: + * + * This configuration file is a BASIC configuration file for use + * on EFnet. You MUST still take the time to set this file up + * properly. + * + * DISCLAIMER: This file was submitted by Disciple@EFnet and has + * since been modified by the Hybrid team. + */ + +/* + * serverinfo {}: contains information about the server + */ +serverinfo { + /* + * name: the name of this server. This cannot be changed at runtime. + */ + name = "efnet.irc"; + + /* + * sid: a server's unique ID. This is three characters long and must + * be in the form [0-9][A-Z0-9][A-Z0-9]. The first character must be + * a digit, followed by 2 alpha-numerical letters. + * NOTE: The letters must be capitalized. This cannot be changed at runtime. + */ + sid = "_CHANGE_ME_"; + + /* + * description: the description of the server. + */ + description = "ircd-hybrid test server"; + + /* + * network info: the name and description of the network this server + * is on. Shown in the 005 reply and used with serverhiding. + */ + network_name = "EFnet"; + network_desc = "Eris Free Network"; + + /* + * hub: allow this server to act as a hub and have multiple servers + * connected to it. + */ + hub = no; + + /* + * vhost: the IP to bind to when we connect outward to ipv4 servers. + * This should be an ipv4 IP only, or "*" for INADDR_ANY. + */ + #vhost = "192.169.0.1"; + + /* + * vhost6: the IP to bind to when we connect outward to ipv6 servers. + * This should be an ipv6 IP only, or "*" for INADDR_ANY. + */ + #vhost6 = "3ffe:80e8:546::2"; + + /* max_clients: the maximum number of clients allowed to connect */ + max_clients = 512; + + /* + * rsa_private_key_file: the path to the file containing our + * rsa key for cryptlink. + * + * Example command to store a 2048 bit RSA keypair in + * rsa.key, and the public key in rsa.pub: + * + * openssl genrsa -out rsa.key 2048 + * openssl rsa -in rsa.key -pubout -out rsa.pub + * chown <ircd-user>.<ircd.group> rsa.key rsa.pub + * chmod 0600 rsa.key + * chmod 0644 rsa.pub + */ + #rsa_private_key_file = "/usr/local/ircd/etc/rsa.key"; + + /* + * ssl_certificate_file: the path to the file containing our + * ssl certificate for encrypted client connection. + * + * This assumes your private RSA key is stored in rsa.key. You + * MUST have an RSA key in order to generate the certificate + * + * openssl req -new -days 365 -x509 -key rsa.key -out cert.pem + * + * See http://www.openssl.org/docs/HOWTO/certificates.txt + * + * Please use the following values when generating the cert + * + * Organization Name: Network Name + * Organization Unit Name: changme.someirc.net + * Common Name: irc.someirc.net + * E-mail: you@domain.com + */ + #ssl_certificate_file = "/usr/local/ircd/etc/cert.pem"; + + /* + * ssl_dh_param_file: + * + * Path to the PEM encoded Diffie-Hellman parameter file. + * DH parameters are strictly required when using ciphers + * with EDH (ephemeral Diffie-Hellman) key exchange. + * + * A DH parameter file can be created by running: + * + * openssl dhparam -out dhparam.pem 1024 + * + * Prime size must be at least 1024 bits. Further information + * regarding specific OpenSSL dhparam command-line options + * can be found in the OpenSSL manual. + */ + #ssl_dh_param_file = "/usr/local/ircd/etc/dhparam.pem"; + + /* + * ssl_cipher_list: + * + * List of ciphers that are supported by _this_ server. Can be used to + * enforce specific ciphers for incoming SSL/TLS connections. + * If a client (which also includes incoming server connections) isn't + * capable of any cipher listed below, the connection will simply be + * rejected. + * + * A list of supported ciphers can be obtained by running: + * + * openssl ciphers -ssl3 -tls1 -v + * + * Multiple ciphers are separated by colons. The order of preference is + * from left to right. + */ + #ssl_cipher_list = "DHE-RSA-AES256-SHA:AES256-SHA"; + + /* + * ssl_server_method: + * ssl_client_method: + * + * SSL/TLS methods we provide for incoming (server method) and + * outgoing (client method) SSL/TLS connections. + * This can be either sslv3 for SSLv3, and/or tlsv1 for TLSv1. + */ + #ssl_server_method = tlsv1, sslv3; + #ssl_client_method = tlsv1; +}; + +/* + * admin {}: contains admin information about the server + */ +admin { + name = "EFnet Admin"; + description = "Main Server Administrator"; + email = "<irc-admin@efnet.irc>"; +}; + +/* + * class {}: contains information about classes for users + */ +class { + /* name: the name of the class */ + name = "users"; + + /* + * ping_time: how often a client must reply to a PING from the + * server before they are dropped. + */ + ping_time = 90 seconds; + + /* + * number_per_ip: how many local users are allowed to connect + * from one IP (optional) + */ + number_per_ip = 2; + + /* + * max_local: how many local users are allowed to connect + * from one ident@host (optional) + */ + max_local = 2; + + /* + * max_global: network-wide limit of users per ident@host (optional) + */ + max_global = 10; + + /* + * max_number: the maximum number of users allowed in this class (optional) + */ + max_number = 100; + + /* + * the following lines are optional and allow you to define + * how many users can connect from one /NN subnet + */ + cidr_bitlen_ipv4 = 24; + cidr_bitlen_ipv6 = 120; + number_per_cidr = 16; + + /* + * sendq: the amount of data allowed in a clients send queue before + * they are dropped. + */ + sendq = 100 kbytes; + + /* + * recvq: maximum amount of data in a clients receive queue before + * they are dropped for flooding. Defaults to 2560 if the chosen + * value isn't within the range of 512 to 8000. + */ + recvq = 2560 bytes; +}; + +class { + name = "opers"; + + /* + * contrary to seeming popular belief, setting ping time + * higher for an oper is NOT doing them a favor. + * Since if a link is dead its dead and it means + * you have to use another nick long enough to kill the old one :-) + * Its much better to use a fairly standard 90 second ping time + */ + ping_time = 90 seconds; + number_per_ip = 10; + max_number = 100; + sendq = 1 mbyte; +}; + +class { + name = "server"; + + /* + * Same thing here. It's a fallacy to think increasing + * ping time for servers is a "good idea." All it leads to + * is "ghosting" on one end. Not a good idea. + */ + ping_time = 90 seconds; + + /* + * ping_warning: how fast a server must reply to a PING before + * a warning to opers is generated. + */ + ping_warning = 15 seconds; + + /* + * connectfreq: only used in server classes. Specifies the delay + * between autoconnecting to servers. + * + * Both comstud and I recommend 10 minutes a few years ago. + * 15 minutes might be right now. The reason you don't want it too + * low is, you make the servers reconnect too quickly with + * a large sendq, and they _will_ nick collide. badly. 5 minutes + * IS way too short. + */ + connectfreq = 15 minutes; + + /* max number: the amount of servers to autoconnect to */ + max_number = 1; + + /* sendq: servers need a higher sendq as they send more data */ + sendq = 15 megabytes; +}; + +/* + * listen {}: contains information about the ports ircd listens on + */ +listen { + /* + * port: the specific port to listen on. If no host is specified + * before, it will listen on all available IPs. + * + * Ports are separated via a comma, a range may be specified using ".." + */ + + /* port: listen on all available IPs, ports 6665 to 6669 */ + port = 6665 .. 6669; + + /* + * Listen on 192.168.0.1/6697 with ssl enabled and hidden from STATS P + * unless you are an administrator. + * + * NOTE: The "flags" directive has to come before "port". Always! + * + * Currently available flags are: + * + * ssl - Port is for SSL client connections only + * server - Only server connections are permitted + * hidden - Port is hidden from /stats P, unless you're an admin + */ + flags = hidden, ssl; + host = "192.168.0.1"; + port = 6697; + + /* + * host: set a specific IP/host the ports after the line will listen + * on. This may be ipv4 or ipv6. + */ + host = "1.2.3.4"; + port = 7000, 7001; + + host = "3ffe:1234:a:b:c::d"; + port = 7002; +}; + +/* + * auth {}: allow users to connect to the ircd + */ +auth { + /* + * user: the user@host allowed to connect. Multiple user + * lines are permitted per auth block. + */ + user = "*@172.16.0.0/12"; + user = "*test@123D:B567:*"; + + /* password: an optional password that is required to use this block */ + password = "letmein"; + + /* + * encrypted: controls whether the auth password above has been + * encrypted. + */ + encrypted = yes; + + /* + * spoof: fake the users host to this. This is free-form, + * just do everyone a favor and don't abuse it. ('=' prefix on /stats I) + */ + spoof = "I.still.hate.packets"; + + /* class: the class the user is placed in */ + class = "opers"; + + /* + * need_password - don't allow users who haven't supplied the correct + * password to connect using another auth{} block + * ('&' prefix on /stats I if disabled) + * need_ident - require the user to have identd to connect ('+' prefix on /stats I) + * spoof_notice - enable spoofing notification to admins + * exceed_limit - allow a user to exceed class limits ('>' prefix on /stats I) + * kline_exempt - exempt this user from k/glines ('^' prefix on /stats I) + * gline_exempt - exempt this user from glines ('_' prefix on /stats I) + * resv_exempt - exempt this user from resvs ('$' prefix on /stats I) + * no_tilde - remove ~ from a user with no ident ('-' prefix on /stats I) + * can_flood - allow this user to exceed flood limits ('|' prefix on /stats I) + */ + flags = need_password, spoof_notice, exceed_limit, kline_exempt, + gline_exempt, resv_exempt, no_tilde, can_flood; +}; + +auth { + /* + * redirect: the server and port to redirect a user to. A user does + * not have to obey the redirection, the ircd just suggests an alternative + * server for them. + */ + redirserv = "this.is.not.a.real.server"; + redirport = 6667; + + user = "*.server"; + + /* class: a class is required even though it is not used */ + class = "users"; +}; + +auth { + user = "*@*"; + class = "users"; + flags = need_ident; +}; + +/* + * operator {}: defines ircd operators + * + * ircd-hybrid no longer supports local operators, privileges are + * controlled via flags. + */ +operator { + /* name: the name of the oper */ + name = "sheep"; + + /* + * user: the user@host required for this operator. Multiple + * user="" lines are supported. + */ + user = "*sheep@192.168.0.0/16"; + user = "*@127.0.0.0/8"; + + /* + * password: the password required to oper. By default this will + * need to be encrypted by using the provided mkpasswd tool. + * Several password hash algorithms are available depending + * on your system's crypt() implementation. For example, a modern + * glibc already has support for SHA-256/512, and MD5 encryption + * algorithms. + */ + password = "$5$x5zof8qe.Yc7/bPp$5zIg1Le2Lsgd4CvOjaD20pr5PmcfD7ha/9b2.TaUyG4"; + + /* + * encrypted: controls whether the oper password above has been + * encrypted. + */ + encrypted = yes; + + /* + * rsa_public_key_file: the public key for this oper when using Challenge. + * A password should not be defined when this is used, see + * doc/challenge.txt for more information. + */ +# rsa_public_key_file = "/usr/local/ircd/etc/oper.pub"; + + /* class: the class the oper joins when they successfully /oper */ + class = "opers"; + + /* + * umodes: default usermodes opers get when they /oper. If defined, + * it will override oper_umodes settings in general {}. + * Available usermodes: + * + * +b - bots - See bot and drone flooding notices + * +c - cconn - Client connection/quit notices + * +C - cconn_full - Client connection/quit notices full + * +D - deaf - Don't receive channel messages + * +d - debug - See debugging notices + * +f - full - See auth{} block full notices + * +G - softcallerid - Server Side Ignore for users not on your channels + * +g - callerid - Server Side Ignore (for privmsgs etc) + * +H - hidden - Hides operator status to other users + * +i - invisible - Not shown in NAMES or WHO unless you share a + * a channel + * +j - rej - See rejected client notices + * +k - skill - See server generated KILL messages + * +l - locops - See LOCOPS messages + * +n - nchange - See client nick changes + * +s - servnotice - See general server notices + * +u - unauth - See unauthorized client notices + * +w - wallop - See server generated WALLOPS + * +x - external - See remote server connection and split notices + * +y - spy - See LINKS, STATS, TRACE notices etc. + * +z - operwall - See oper generated WALLOPS + */ +# umodes = locops, servnotice, operwall, wallop; + + /* + * privileges: controls the activities and commands an oper is + * allowed to do on the server. All options default to no. + * Available options: + * + * module - allows MODULE + * global_kill - allows remote users to be /KILL'd + * remote - allows remote SQUIT and CONNECT + * remoteban - allows remote KLINE/UNKLINE + * dline - allows DLINE + * undline - allows UNDLINE + * kline - allows KILL and KLINE + * unkline - allows UNKLINE + * gline - allows GLINE + * xline - allows XLINE + * globops - allows GLOBOPS + * operwall - allows OPERWALL + * nick_changes - allows oper to see nickchanges via usermode +n + * rehash - allows oper to REHASH config + * die - allows DIE + * restart - allows RESTART + * set - allows SET + * admin - gives admin privileges. admins for example, + * may see the real IP addresses of servers. + */ + flags = global_kill, remote, kline, unkline, xline, globops, restart, + die, rehash, nick_changes, admin, operwall, module; +}; + +/* + * connect {}: controls servers we connect to + */ +connect { + /* name: the name of the server */ + name = "irc.uplink.com"; + + /* + * host: the host or IP to connect to. If a hostname is used it + * must match the reverse dns of the server. + */ + host = "192.168.0.1"; + + /* + * vhost: the IP to bind to when we connect outward to servers. + * serverinfo::vhost and serverinfo::vhost6 will be overridden + * by this directive. + */ + vhost = "192.168.0.2"; + + /* + * passwords: the passwords we send (OLD C:) and accept (OLD N:). + * The remote server will have these passwords reversed. + */ + send_password = "password"; + accept_password = "anotherpassword"; + + /* + * encrypted: controls whether the accept_password above has been + * encrypted. + */ + encrypted = no; + + /* port: the port to connect to this server on */ + port = 6666; + + /* + * hub_mask: the mask of servers that this server may hub. Multiple + * entries are permitted + */ + hub_mask = "*"; + + /* + * leaf_mask: the mask of servers this server may not hub. Multiple + * entries are permitted. Useful for forbidding EU -> US -> EU routes. + */ +# leaf_mask = "*.uk"; + + /* class: the class this server is in */ + class = "server"; + + /* + * ssl_cipher_list: + * + * List of ciphers that the server we are connecting to must support. + * If the server isn't capable of any cipher listed below, the + * connection will simply be rejected. + * Can be used to enforce stronger ciphers, even though this option + * is not necessarily required to establish a SSL/TLS connection. + * + * Multiple ciphers are separated by colons. The order of preference + * is from left to right. + */ + #ssl_cipher_list = "DHE-RSA-AES256-SHA:AES256-SHA"; + + /* + * autoconn - controls whether we autoconnect to this server or not, + * dependent on class limits. By default, this is disabled. + * ssl - Initiates a TLS/SSL connection. + */ +# flags = autoconn, ssl; +}; + +connect { + name = "ipv6.some.server"; + host = "3ffd:dead:beef::1"; + send_password = "password"; + accept_password = "password"; + port = 6666; + + /* + * aftype: controls whether the connection uses "ipv4" or "ipv6". + * Default is ipv4. + */ + aftype = ipv6; + class = "server"; +}; + +/* + * cluster {}: servers that share klines/unkline/xline/unxline/resv/unresv/locops + * automatically + */ +cluster { + /* + * name: the server to share with, this can take wildcards + * + * NOTE: only local actions will be clustered, meaning if + * the server receives a shared kline/unkline/etc, it + * will not be propagated to clustered servers. + * + * Remote servers are not necessarily required to accept + * clustered lines, they need a shared{} for *THIS* server + * in order to accept them. + */ + name = "*.arpa"; + + /* + * type: list of what to share, options are as follows: + * dline - share dlines + * undline - share undlines + * kline - share klines + * unkline - share unklines + * xline - share xlines + * unxline - share unxlines + * resv - share resvs + * unresv - share unresvs + * locops - share locops + * all - share all of the above (default) + */ + type = kline, unkline, locops, xline, resv; +}; + +/* + * shared {}: users that are allowed to remote kline + * + * NOTE: This can be effectively used for remote klines. + * Please note that there is no password authentication + * for users setting remote klines. You must also be + * /oper'd in order to issue a remote kline. + */ +shared { + /* + * name: the server the user must be on to set klines. If this is not + * specified, the user will be allowed to kline from all servers. + */ + name = "irc2.some.server"; + + /* + * user: the user@host mask that is allowed to set klines. If this is + * not specified, all users on the server above will be allowed to set + * a remote kline. + */ + user = "oper@my.host.is.spoofed"; + + /* + * type: list of what to share, options are as follows: + * dline - allow oper/server to dline + * undline - allow oper/server to undline + * kline - allow oper/server to kline + * unkline - allow oper/server to unkline + * xline - allow oper/server to xline + * unxline - allow oper/server to unxline + * resv - allow oper/server to resv + * unresv - allow oper/server to unresv + * locops - allow oper/server to locops - only used for servers that cluster + * all - allow oper/server to do all of the above (default) + */ + type = kline, unkline, resv; +}; + +/* + * kill {}: users that are not allowed to connect + * Oper issued klines will be added to the specified kline config + */ +kill { + user = "bad@*.hacked.edu"; + reason = "Obviously hacked account"; +}; + +kill { + user = "^O[[:alpha:]]?[[:digit:]]+(x\.o|\.xo)$@^[[:alnum:]]{4}\.evilnet.tld$"; + + /* + * NOTE: You have to set type=regex; when using a regular expression + * based user entry + */ + type = regex; +}; + +/* + * deny {}: IPs that are not allowed to connect (before DNS/ident lookup) + * Oper issued dlines will be added to the specified dline config + */ +deny { + ip = "10.0.1.0/24"; + reason = "Reconnecting vhosted bots"; +}; + +/* + * exempt {}: IPs that are exempt from deny {} and Dlines + * + * EFnet Note: We really suggest to enable general::stats_e_disabled + * if you plan to exempt EFnet server IPs you don't want to show to + * other operators and/or administrators through "STATS e". + */ +exempt { + ip = "192.168.0.0/16"; +}; + +/* + * resv {}: nicks and channels users may not use/join + */ +resv { + /* reason: the reason for the proceeding resv's */ + reason = "There are no services on this network"; + + /* resv: the nicks and channels users may not join/use */ + nick = "nickserv"; + nick = "chanserv"; + nick = "operserv"; + nick = "JUPES"; + nick = "JUPE"; + nick = "CH?NF?X"; # CHANFIX (services.int) + + /* These are totally optional, but may be a good idea */ + nick = "oper"; + nick = "ircop"; + nick = "op"; + nick = "ident"; + nick = "pass"; + channel = "#jupedchan"; + + /* resv: wildcard masks are also supported in nicks only */ + reason = "Clone bots"; + nick = "clone*"; +}; + +/* + * gecos {}: The X: replacement, used for banning users based on + * their "realname". + */ +gecos { + name = "*sex*"; + reason = "Possible spambot"; +}; + +gecos { + name = "sub7server"; + reason = "Trojan drone"; +}; + +gecos { + name = "*http*"; + reason = "Spambot"; +}; + +gecos { + name = "^\[J[0o]hn Do[3e]\]-[0-9]{2,5}$"; + + /* + * NOTE: You have to set type=regex; when using a regular expression + * based name entry + */ + type = regex; +}; + +/* + * channel {}: The channel block contains options pertaining to channels + */ +channel { + /* + * disable_fake_channels: this option, if set to 'yes', will + * disallow clients to create or join channels that have one + * of the following ASCII characters in their name: + * + * 2 | bold + * 3 | mirc color + * 15 | plain text + * 22 | reverse + * 29 | italic + * 31 | underline + * 160 | non-breaking space + */ + disable_fake_channels = yes; + + /* + * restrict_channels: reverse channel RESVs logic, only reserved + * channels are allowed + */ + restrict_channels = no; + + /* + * knock_delay: The amount of time a user must wait between issuing + * the knock command. + */ + knock_delay = 5 minutes; + + /* + * knock_delay_channel: How often a knock to any specific channel + * is permitted, regardless of the user sending the knock. + */ + knock_delay_channel = 1 minute; + + /* + * max_chans_per_user: The maximum number of channels a user can + * join/be on. + */ + max_chans_per_user = 25; + + /* + * max_chans_per_oper: The maximum number of channels an oper can + * join/be on. + */ + max_chans_per_oper = 50; + + /* quiet_on_ban: stop banned people talking in channels. */ + quiet_on_ban = yes; + + /* max_bans: maximum number of +b/e/I modes in a channel */ + max_bans = 100; + + /* + * how many joins in how many seconds constitute a flood, use 0 to + * disable. +b opers will be notified (changeable via /set) + */ + join_flood_count = 16; + join_flood_time = 8 seconds; + + /* + * splitcode: The ircd will now check splitmode every few seconds. + * + * Either split users or split servers can activate splitmode, but + * both conditions must be met for the ircd to deactivate splitmode. + * + * You may force splitmode to be permanent by /quote set splitmode on + */ + + /* + * default_split_user_count: when the usercount is lower than this level, + * consider ourselves split. This must be set for automatic splitmode. + */ + default_split_user_count = 20000; + + /* + * default_split_server_count: when the servercount is lower than this, + * consider ourselves split. This must be set for automatic splitmode. + */ + default_split_server_count = 10; + + /* no_create_on_split: disallow users creating channels on split. */ + no_create_on_split = yes; + + /* no_join_on_split: disallow users joining channels at all on a split. */ + no_join_on_split = no; +}; + +/* + * serverhide {}: The serverhide block contains the options regarding + * serverhiding + */ +serverhide { + /* + * flatten_links: this option will show all servers in /links appear + * that they are linked to this current server + * + * EFnet Note: While this is not a requirement on EFnet, it + * may be a good idea. Except, it's useless + * unless the entire net runs it. + */ + flatten_links = no; + + /* + * links_delay: how often to update the links file when it is + * flattened. + */ + links_delay = 5 minutes; + + /* + * hidden: hide this server from a /links output on servers that + * support it. This allows hub servers to be hidden etc. + */ + hidden = no; + + /* + * hide_servers: hide remote servernames everywhere and instead use + * hidden_name and network_desc. + */ + hide_servers = no; + + /* + * Use this as the servername users see if hide_servers = yes. + */ + hidden_name = "*.hidden.com"; + + /* + * hide_server_ips: If this is disabled, opers will be unable to see + * servers ips and will be shown a masked ip, admins will be shown the + * real ip. + * + * If this is enabled, nobody can see a servers ip. *This is a kludge*, + * it has the side effect of hiding the ips everywhere, including + * logfiles. + * + * We recommend you leave this disabled, and just take care with who you + * give admin=yes; to. + */ + hide_server_ips = yes; +}; + +/* + * general {}: The general block contains many of the options that were once + * compiled in options in config.h. The general block is read at start time. + */ +general { + /* max_watch: maximum WATCH entries a client can have. */ + max_watch = 60; + + /* + * EFnet Note: This feature is required for European EFnet servers + * and is used by several North American servers. As + * such, it has been left on by default. If you + * do not want your server to participate in G:Lines + * you should disable this. + */ + + /* gline_enable: enable glines, network wide temp klines */ + gline_enable = yes; + + /* + * gline_duration: the amount of time a gline will remain on your + * server before expiring + */ + gline_duration = 1 day; + + /* + * gline_request_duration: how long a pending G-line can be around. + * 10 minutes should be plenty + */ + gline_request_duration = 10 minutes; + + /* + * gline_min_cidr: the minimum required length of a CIDR bitmask + * for IPv4 based glines + */ + gline_min_cidr = 16; + + /* + * gline_min_cidr6: the minimum required length of a CIDR bitmask + * for IPv6 based glines + */ + gline_min_cidr6 = 48; + + /* + * Whether to automatically set mode +i on connecting users. + */ + invisible_on_connect = yes; + + /* + * Max time from the nickname change that still causes KILL + * automatically to switch for the current nick of that user. + */ + kill_chase_time_limit = 90 seconds; + + /* + * If hide_spoof_ips is disabled, opers will be allowed to see the real + * IP of spoofed users in /trace etc. If this is defined they will be + * shown a masked IP. + */ + hide_spoof_ips = yes; + + /* + * Ignore bogus timestamps from other servers. Yes, this will desync + * the network, but it will allow chanops to resync with a valid non TS 0 + * + * This should be enabled network wide, or not at all. + */ + ignore_bogus_ts = no; + + /* + * disable_auth: completely disable ident lookups; if you enable this, + * be careful of what you set need_ident to in your auth {} blocks + */ + disable_auth = no; + + /* disable_remote_commands: disable users doing commands on remote servers */ + disable_remote_commands = no; + + /* + * tkline_expire_notices: enables or disables temporary kline/xline + * expire notices. + */ + tkline_expire_notices = no; + + /* + * default_floodcount: the default value of floodcount that is configurable + * via /quote set floodcount. This is the amount of lines a user + * may send to any other user/channel in one second. + */ + default_floodcount = 10; + + /* + * failed_oper_notice: send a notice to all opers on the server when + * someone tries to OPER and uses the wrong password, host or ident. + */ + failed_oper_notice = yes; + + /* + * dots_in_ident: the amount of '.' characters permitted in an ident + * reply before the user is rejected. + */ + dots_in_ident = 2; + + /* + * min_nonwildcard: the minimum non wildcard characters in k/d/g lines + * placed via the server. klines hand placed are exempt from limits. + * wildcard chars: '.' ':' '*' '?' '@' '!' '#' + */ + min_nonwildcard = 3; + + /* + * min_nonwildcard_simple: the minimum non wildcard characters in + * gecos bans. wildcard chars: '*' '?' '#' + */ + min_nonwildcard_simple = 3; + + /* max_accept: maximum allowed /accept's for +g usermode */ + max_accept = 20; + + /* anti_nick_flood: enable the nickflood control code */ + anti_nick_flood = yes; + + /* nick flood: the nick changes allowed in the specified period */ + max_nick_time = 20 seconds; + max_nick_changes = 5; + + /* + * anti_spam_exit_message_time: the minimum time a user must be connected + * before custom quit messages are allowed. + */ + anti_spam_exit_message_time = 5 minutes; + + /* + * ts delta: the time delta allowed between server clocks before + * a warning is given, or before the link is dropped. all servers + * should run ntpdate/rdate to keep clocks in sync + */ + ts_warn_delta = 30 seconds; + ts_max_delta = 5 minutes; + + /* + * warn_no_nline: warn opers about servers that try to connect but + * we don't have a connect {} block for. Twits with misconfigured + * servers can get really annoying with this enabled. + */ + warn_no_nline = yes; + + /* + * stats_e_disabled: set this to 'yes' to disable "STATS e" for both + * operators and administrators. Doing so is a good idea in case + * there are any exempted (exempt{}) server IPs you don't want to + * see leaked. + */ + stats_e_disabled = no; + + /* stats_o_oper only: make stats o (opers) oper only */ + stats_o_oper_only = yes; + + /* stats_P_oper_only: make stats P (ports) oper only */ + stats_P_oper_only = yes; + + /* + * stats i oper only: make stats i (auth {}) oper only. set to: + * yes: show users no auth blocks, made oper only. + * masked: show users first matching auth block + * no: show users all auth blocks. + */ + stats_i_oper_only = yes; + + /* + * stats_k_oper_only: make stats k/K (klines) oper only. set to: + * yes: show users no auth blocks, made oper only + * masked: show users first matching auth block + * no: show users all auth blocks. + */ + stats_k_oper_only = yes; + + /* + * caller_id_wait: time between notifying a +g user that somebody + * is messaging them. + */ + caller_id_wait = 1 minute; + + /* + * opers_bypass_callerid: allows operators to bypass +g and message + * anyone who has it set (useful if you use services). + */ + opers_bypass_callerid = no; + + /* + * pace_wait_simple: time between use of less intensive commands + * (ADMIN, HELP, (L)USERS, VERSION, remote WHOIS) + */ + pace_wait_simple = 1 second; + + /* + * pace_wait: time between more intensive commands + * (AWAY, INFO, LINKS, MAP, MOTD, STATS, WHO, wildcard WHOIS, WHOWAS) + */ + pace_wait = 10 seconds; + + /* + * short_motd: send clients a notice telling them to read the motd + * instead of forcing a motd to clients who may simply ignore it. + */ + short_motd = no; + + /* + * ping_cookie: require clients to respond exactly to a ping command, + * can help block certain types of drones and FTP PASV mode spoofing. + */ + ping_cookie = no; + + /* no_oper_flood: increase flood limits for opers. */ + no_oper_flood = yes; + + /* + * true_no_oper_flood: completely eliminate flood limits for opers + * and for clients with can_flood = yes in their auth {} blocks + */ + true_no_oper_flood = yes; + + /* oper_pass_resv: allow opers to over-ride RESVs on nicks/channels */ + oper_pass_resv = yes; + + /* REMOVE ME. The following line checks you've been reading. */ + havent_read_conf = 1; + + /* + * max_targets: the maximum amount of targets in a single + * PRIVMSG/NOTICE. Set to 999 NOT 0 for unlimited. + */ + max_targets = 4; + + /* + * message_locale: the default message locale + * Use "standard" for the compiled in defaults. + * To install the translated messages, go into messages/ in the + * source directory and run `make install'. + */ + message_locale = "standard"; + + /* + * usermodes configurable: a list of usermodes for the options below + * + * +b - bots - See bot and drone flooding notices + * +c - cconn - Client connection/quit notices + * +C - cconn_full - Client connection/quit notices full + * +D - deaf - Don't receive channel messages + * +d - debug - See debugging notices + * +f - full - See auth{} block full notices + * +G - softcallerid - Server Side Ignore for users not on your channels + * +g - callerid - Server Side Ignore (for privmsgs etc) + * +H - hidden - Hides operator status to other users + * +i - invisible - Not shown in NAMES or WHO unless you share a + * a channel + * +j - rej - See rejected client notices + * +k - skill - See server generated KILL messages + * +l - locops - See LOCOPS messages + * +n - nchange - See client nick changes + * +s - servnotice - See general server notices + * +u - unauth - See unauthorized client notices + * +w - wallop - See server generated WALLOPS + * +x - external - See remote server connection and split notices + * +y - spy - See LINKS, STATS, TRACE notices etc. + * +z - operwall - See oper generated WALLOPS + */ + + /* oper_only_umodes: usermodes only opers may set */ + oper_only_umodes = bots, cconn, cconn_full, debug, full, hidden, skill, + nchange, rej, spy, external, operwall, + locops, unauth; + + /* oper_umodes: default usermodes opers get when they /oper */ + oper_umodes = bots, locops, servnotice, operwall, wallop; + + /* + * use_egd: if your system does not have *random devices yet you + * want to use OpenSSL and encrypted links, enable this. Beware - + * EGD is *very* CPU intensive when gathering data for its pool + */ +# use_egd = yes; + + /* + * egdpool_path: path to EGD pool. Not necessary for OpenSSL >= 0.9.7 + * which automatically finds the path. + */ +# egdpool_path = "/var/run/egd-pool"; + + /* + * throttle_time: the minimum amount of time between connections from + * the same ip. exempt {} blocks are excluded from this throttling. + * Offers protection against flooders who reconnect quickly. + * Set to 0 to disable. + */ + throttle_time = 0; +}; + +modules { + /* + * path: other paths to search for modules specified below + * and in "/module load". + */ + path = "/usr/local/ircd/lib/ircd-hybrid/modules"; + path = "/usr/local/ircd/lib/ircd-hybrid/modules/autoload"; + + /* module: the name of a module to load on startup/rehash */ + #module = "some_module.la"; +}; + +/* + * log {}: contains information about logfiles. + */ +log { + /* Do you want to enable logging to ircd.log? */ + use_logging = yes; + + file { + type = oper; + name = "/home/ircd/var/log/oper.log"; + size = unlimited; + }; + + file { + type = user; + name = "/home/ircd/var/log/user.log"; + size = 50 megabytes; + }; + + file { + type = kill; + name = "/home/ircd/var/log/kill.log"; + size = 50 megabytes; + }; + + file { + type = kline; + name = "/home/ircd/var/log/kline.log"; + size = 50 megabytes; + }; + + file { + type = dline; + name = "/home/ircd/var/log/dline.log"; + size = 50 megabytes; + }; + + file { + type = gline; + name = "/home/ircd/var/log/gline.log"; + size = 50 megabytes; + }; + + file { + type = debug; + name = "/home/ircd/var/log/debug.log"; + size = 50 megabytes; + }; +}; diff --git a/doc/example.quick.conf b/doc/example.quick.conf new file mode 100644 index 0000000..65f0859 --- /dev/null +++ b/doc/example.quick.conf @@ -0,0 +1,369 @@ +/* doc/example.conf.quick - ircd-hybrid-8 Example configuration file + * Copyright (C) 2000-2012 Hybrid Development Team + * + * Written by ejb, wcampbel, db, leeh and others + * + * $Id$ + */ + +/* IMPORTANT NOTES: + * + * auth {} blocks MUST be specified in order of precedence. The first one + * that matches a user will be used. So place spoofs first, then specials, + * then general access, then restricted. + * + * Both shell style (#) and C style comments are supported. + * + * Files may be included by either: + * .include "filename" + * .include <filename> + * + * Times/durations are written as: + * 12 hours 30 minutes 1 second + * + * Valid units of time: + * month, week, day, hour, minute, second + * + * Valid units of size: + * megabyte/mbyte/mb, kilobyte/kbyte/kb, byte + * + * Sizes and times may be singular or plural. + */ + +/* EFNET NOTE: + * + * This config file is NOT suitable for EFNet. EFNet admins should use + * example.efnet.conf + */ + +serverinfo { + name = "hades.arpa"; + sid = "_CHANGE_ME_"; + description = "ircd-hybrid test server"; + network_name = "MyNet"; + network_desc = "This is My Network"; + hub = no; + #vhost = "192.169.0.1"; + #vhost6 = "3ffe:80e8:546::2"; + max_clients = 512; + #rsa_private_key_file = "/usr/local/ircd/etc/rsa.key"; + #ssl_certificate_file = "/usr/local/ircd/etc/cert.pem"; + #ssl_server_method = tlsv1, sslv3; + #ssl_client_method = tlsv1; +}; + +/* admin {}: contains admin information about the server. (OLD A:) */ +admin { + name = "Smurf target"; + description = "Main Server Administrator"; + email = "<syn@packets.r.us>"; +}; + +/* class {}: contain information about classes for users (OLD Y:) */ +class { + name = "users"; + ping_time = 2 minutes; + number_per_ip = 2; + max_number = 100; + sendq = 100 kbytes; + recvq = 2560 bytes; +}; + +class { + name = "restricted"; + ping_time = 1 minute 30 seconds; + number_per_ip = 1; + max_number = 100; + sendq = 60kb; + recvq = 2560 bytes; +}; + +class { + name = "opers"; + ping_time = 5 minutes; + number_per_ip = 10; + max_number = 100; + sendq = 100kbytes; +}; + +class { + name = "server"; + ping_time = 5 minutes; + ping_warning = 15 seconds; + connectfreq = 5 minutes; + max_number = 1; + sendq=2 megabytes; +}; + +/* listen {}: contain information about the ports ircd listens on (OLD P:) */ +listen { + port = 6665 .. 6669; + + flags = ssl; + port = 6697; + + host = "1.2.3.4"; + port = 7000, 7001; + + host = "3ffe:1234:a:b:c::d"; + port = 7002; +}; + +/* auth {}: allow users to connect to the ircd (OLD I:) */ +auth { + user = "*@172.16.0.0/12"; + user = "*test@123D:B567:*"; + password = "letmein"; + flags = need_password, spoof_notice, exceed_limit, kline_exempt, + gline_exempt, no_tilde; + spoof = "I.still.hate.packets"; + class = "opers"; +}; + +auth { + redirserv = "irc.fi"; + redirport = 6667; + user = "*.fi"; + class = "users"; +}; + +auth { + user = "*@*"; + class = "users"; + flags = need_ident; +}; + +/* operator {}: defines ircd operators. (OLD O:) + * ircd-hybrid no longer supports local operators, privileges are + * controlled via flags. + */ +operator { + name = "sheep"; + user = "*sheep@*"; + user = "*@127.0.0.1"; + password = "etcnjl8juSU1E"; + encrypted = yes; + #rsa_public_key_file = "/usr/local/ircd/etc/oper.pub"; + class = "opers"; + flags = global_kill, remote, kline, unkline, gline, module, + xline, die, rehash, nick_changes, admin, set; +}; + +/* connect {}: controls servers we connect to (OLD C:, N:, H:, L:) */ +connect { + name = "irc.uplink.com"; + host = "192.168.0.1"; + send_password = "password"; + accept_password = "anotherpassword"; + encrypted = no; + port = 6666; + hub_mask = "*"; + #leaf_mask = "*.uk"; + class = "server"; + flags = autoconn; +}; + +connect { + name = "ipv6.some.server"; + host = "3ffd:dead:beef::1"; + send_password = "password"; + accept_password = "password"; + port = 6666; + + aftype = ipv6; + class = "server"; +}; + +/* cluster{}: servers that share klines/unkline/xline/unxline/resv/unresv/locops + * automatically (OLD hyb6 SLAVE_SERVERS) + */ +cluster { + name = "*.arpa"; + type = kline, unkline, locops, xline, resv; +}; + +/* shared {}: users that are allowed to remote kline (OLD U:) */ +shared { + name = "irc2.some.server"; + user = "oper@my.host.is.spoofed"; + type = all; +}; + +/* kill {}: users that are not allowed to connect (OLD K:) + * Oper issued klines will be added to the specified kline config + */ +kill { + user = "bad@*.hacked.edu"; + reason = "Obviously hacked account"; +}; + +/* deny {}: IPs that are not allowed to connect (before DNS/ident lookup) + * Oper issued dlines will be added to the specified dline config + */ +deny { + ip = "10.0.1.0/24"; + reason = "Reconnecting vhosted bots"; +}; + +/* exempt {}: IPs that are exempt from deny {} and Dlines. (OLD d:) */ +exempt { + ip = "192.168.0.0/16"; +}; + +/* resv {}: nicks and channels users may not use/join (OLD Q:) */ +resv { + nick = "nickserv"; + nick = "chanserv"; + channel = "#services"; + reason = "Clone bots"; + nick = "clone*"; +}; + +gecos { + name = "*sex*"; + reason = "Possible spambot"; +}; + +gecos { + name = "sub7server"; + reason = "Trojan drone"; +}; + +gecos { + name = "*http*"; + reason = "Spambot"; +}; + +channel { + restrict_channels = no; + knock_delay = 5 minutes; + knock_delay_channel = 1 minute; + max_chans_per_user = 25; + max_chans_per_oper = 50; + quiet_on_ban = yes; + max_bans = 25; + join_flood_count = 16; + join_flood_time = 8 seconds; + default_split_user_count = 0; + default_split_server_count = 0; + no_create_on_split = yes; + no_join_on_split = no; +}; + +serverhide { + flatten_links = no; + links_delay = 5 minutes; + hidden = no; + hide_servers = no; + hidden_name = "*.hidden.com"; + hide_server_ips = no; +}; + +general { + kill_chase_time_limit = 90 seconds; + hide_spoof_ips = yes; + ignore_bogus_ts = no; + + disable_auth = no; + disable_remote_commands = no; + default_floodcount = 10; + failed_oper_notice = yes; + dots_in_ident=2; + min_nonwildcard = 4; + min_nonwildcard_simple = 3; + max_accept = 20; + anti_nick_flood = yes; + + max_nick_time = 20 seconds; + max_nick_changes = 5; + + anti_spam_exit_message_time = 5 minutes; + ts_warn_delta = 30 seconds; + ts_max_delta = 5 minutes; + + invisible_on_connect = yes; + warn_no_nline = yes; + stats_o_oper_only=yes; + stats_P_oper_only=no; + stats_i_oper_only=masked; + stats_k_oper_only=masked; + caller_id_wait = 1 minute; + pace_wait_simple = 1 second; + pace_wait = 10 seconds; + short_motd = no; + ping_cookie = no; + no_oper_flood = yes; + true_no_oper_flood = yes; + oper_pass_resv = yes; + + /* REMOVE ME. The following line checks you've been reading. */ + havent_read_conf = 1; + + max_targets = 4; + message_locale = "standard"; + oper_only_umodes = bots, cconn, debug, full, skill, nchange, + rej, spy, external, operwall, locops, unauth; + + oper_umodes = bots, locops, servnotice, operwall, wallop; + + + #use_egd = yes; + #egdpool_path = "/var/run/egd-pool"; + throttle_time = 10; +}; + +modules { + path = "/usr/local/ircd/lib/ircd-hybrid/modules"; + path = "/usr/local/ircd/lib/ircd-hybrid/modules/autoload"; + #module = "some_module.so"; +}; + +/* + * log {}: contains information about logfiles. + */ +log { + /* Do you want to enable logging to ircd.log? */ + use_logging = yes; + + file { + type = oper; + name = "/home/ircd/var/log/oper.log"; + size = unlimited; + }; + + file { + type = user; + name = "/home/ircd/var/log/user.log"; + size = 50 megabytes; + }; + + file { + type = kill; + name = "/home/ircd/var/log/kill.log"; + size = 50 megabytes; + }; + + file { + type = kline; + name = "/home/ircd/var/log/kline.log"; + size = 50 megabytes; + }; + + file { + type = dline; + name = "/home/ircd/var/log/dline.log"; + size = 50 megabytes; + }; + + file { + type = gline; + name = "/home/ircd/var/log/gline.log"; + size = 50 megabytes; + }; + + file { + type = debug; + name = "/home/ircd/var/log/debug.log"; + size = 50 megabytes; + }; +}; diff --git a/doc/guidelines.txt b/doc/guidelines.txt new file mode 100644 index 0000000..a3d13f8 --- /dev/null +++ b/doc/guidelines.txt @@ -0,0 +1,36 @@ +ircd-hybrid documentation guidelines + +1. When a major change in the code affects users, it MUST be documented +in whats-new and all other appropriate locations. + +2. When something affects the configuration file, and it's compatibility +with previous versions, it MUST be documented in example.conf and in a +proposed new document README.NOW. This is VERY important during the beta +phase to help anyone who mans the "help desk". + +3. All documentation must properly fit in an 80 character wide terminal. +SGML and other "professional" documentation systems are good for some +projects, but hybrid is intended to be used on minimal UNIX installations +where any extra binary is a security risk. Text only docs, sized to fit +properly in an 80 character wide console, are what admins expect, and that's +what they should get. + +4. All documentation must be spell checked before a release or a beta. +'ispell' (using either the US or British dictionary) is probably the +easiest way to spell check the documentation. 'ispell -a' at the command +line will allow you to check individual words as you are editing. + +5. When a document is over approximately 5 pages long, it should be split +into sections to facilitate users reading them. + +6. All docs (except docs specifically describing code) should be written +in a way that all users of the software (not just programmers) will be able +to easily understand. + +7. Don't make documentation a chore. If it's done while coding, or shortly +after, it usually is more accurate and the documentation tasks don't get +pushed back and pile up. + +8. Don't forget to include a CVS Id. + +# $Id$ diff --git a/doc/index.txt b/doc/index.txt new file mode 100644 index 0000000..d43a112 --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,23 @@ +$Id$ +----------------------------------------------- + +Documentation for ircd-hybrid + +CIDR.txt - Description of CIDR in IPv4 +challenge.txt - Overview of the challenge/response system for + obtaining operator status +guidelines.txt - Documentation guidelines +index.txt - This file +ircd.8 - The new revised manpage, read with the following + commands in the prefix directory: + man -M . ircd +kline.txt - Outline of the remote K-line protocol for both + opers and servers +messages.txt - A general help file for users and admins to + customize ircd's messages. +modeg.txt - An in depth description of the server side silence + user mode (+g) +modes.txt - A list of all user and channel modes +resv.txt - Outline of the RESV command. +server-version-info - Overview of the flags shown in /version +serverhide.txt - Information about the server hide options diff --git a/doc/ircd.8 b/doc/ircd.8 new file mode 100644 index 0000000..25f03f4 --- /dev/null +++ b/doc/ircd.8 @@ -0,0 +1,110 @@ +.\" @(#)ircd.8 7b10 25 Oct 2001 +.\" $Id$ +.TH IRCD 8 "1 April 2012" "ircd-hybrid-8" +.SH NAME +ircd \- The IRCD-Hybrid Internet Relay Chat server +.SH SYNOPSIS +.hy 0 +.IP \fBircd\fP +[-configfile filename] [-dlinefile filename] [-klinefile filename] +[-xlinefile filename] [-logfile filename] [-pidfile filename] [-foreground] +[-version] +.SH DESCRIPTION +.LP +\fIircd\fP is the server (daemon) program for the Internet Relay Chat +Program. The \fIircd\fP is a server in that its function is to "serve" +the client program \fIirc(1)\fP and other compatible programs with +messages and commands. All commands and user messages are passed +directly to the \fIircd\fP for processing and relaying to other IRC +servers. + +This is \fIircd-hybrid\fP, the highly modified (and hopefully improved) +variant of the original ircd program by Jarkko Oikarinen. +.SH OPTIONS +.TP +.B \-configfile filename +Specifies the ircd.conf file to be used for this \fIircd\fP. The option +is used to override the default ircd.conf given at compile time. By default, +this is "etc/ircd.conf" within the prefix you installed the \fIircd\fP in. +.TP +.B \-dlinefile filename +.TP +.B \-klinefile filename +.TP +.B \-xlinefile filename +Specifies the files to be used for D-lines (host bans), K-lines (hostmask bans), +and X-lines (gecos bans), which by default are within the etc/ directory of your +installation prefix as dline.conf, kline.conf, and xline.conf. +.TP +.B \-logfile filename +Specifies an alternative logfile to be used than that specified in defaults.h +.TP +.B \-pidfile filename +Specifies the file used by the \fIircd\fP to store its process ID. The option is +used to override the default ircd.pid given at compile time. +.TP +.B \-foreground +Makes \fIircd\fP run in the foreground +.TP +.B \-version +Makes \fIircd\fP print its version, and exit. +.SH USAGE +If you plan to connect your \fIircd\fP server to an existing IRC network, +you will need to alter your local IRC configuration file (typically named +"ircd.conf") so that it will accept and make connections to other \fIIRC\fP +servers. This file contains the hostnames, IP addresses, and sometimes +passwords for connections to other ircds around the world. + +The example ircd.conf in the etc/ directory documents itself. Read it +carefully or you may expose a risk on your network simply by having your +ircd running! +.LP +.SH BOOTING THE SERVER +It is sufficient to type \fBircd\fP at the command line to start +ircd-hybrid into the background. If you wish to run ircd in the +foreground (perhaps for debugging purposes), use the \fB-foreground\fP +parameter. + +The ircd-hybrid package in your distribution may ship with an rc-script +which handles this for you. In Debian, it is \fB/etc/init.d/ircd-hybrid.\fP + +.SH EXAMPLE +# ircd -configfile /usr/share/ircd/ircd.conf -logfile /var/log/ircd.log + +Starts \fBircd\fP with the config file /usr/share/ircd/ircd.conf and +with a log file /var/log/ircd.log. It implicitly forks back to the +console -- to prevent this use -foreground. + +Many of the above paths are hardcoded at compile time in the +\fBinclude/defaults.h\fP file, so it may be convenient to edit these to +suit your needs before you compile the ircd. +.SH COPYRIGHT +(c) 1988,1989 University of Oulu, Computing Center, Finland, +.LP +(c) 1988,1989 Department of Information Processing Science, +University of Oulu, Finland +.LP +(c) 1988-1991 Jarkko Oikarinen +.LP +(c) 1997-2012 The IRCD-Hybrid project. +.LP +For full COPYRIGHT see the LICENSE file within the IRC source package. +.LP +.RE +.SH BUGS +If you find a bug and you have a core file from ircd as a result, use a +debugger like \fBgdb(1)\fP to process the core file and send a backtrace +to \fBbugs@ircd-hybrid.org\fP. + +.SH AUTHORS +irc2.8 and earlier: Jarkko Oikarinen, currently jto@tolsun.oulu.fi. See +doc/old/Authors for more credits. +.LP +ircd-hybrid-7: the IRCD-Hybrid Project, bugs@ircd-hybrid.org. +.LP +Manual page written by Jeff Trim, jtrim@orion.cair.du.edu, +later modified by jto@tolsun.oulu.fi. +.LP +Updated by W. Campbell, wcampbel@botbay.net, Edward Brocklesby, +ejb@klamath.uucp.leguin.org.uk, and highly revised by Joshua Kwan +(joshk@triplehelix.org) for the Debian distribution. diff --git a/doc/kline.txt b/doc/kline.txt new file mode 100644 index 0000000..6c72310 --- /dev/null +++ b/doc/kline.txt @@ -0,0 +1,101 @@ +/* doc/kline.txt - Overview of the remote kline system + * + * Copyright (C) 2005-2012 Hybrid Development Team + * + * $Id$ + */ + + +Introduction +------------ + +Since ircd-hybrid-7, opers are allowed to add and remove K-Lines on multiple +servers, an extension and replacement of the old ircd-hybrid-6 method of sharing +all K-Lines between servers. + +In this implementation, it is extended to be routable among servers which +understand the "KLN" capability. This allows us to continue to "talk" +to non remote kline capable servers without breaking anything. + + +Usage +----- + +The old K-Line method has not been changed. To place a K-Line it is still: + +/quote kline <nick|user@host> :reason +/quote kline [tkline_duration] <nick|user@host> :reason + +Scenario 1 +---------- + +Oper wishes to K-Line user@host on server irc.xyz.net + +/quote kline <nick|user@host> on irc.xyz.net :reason +/quote kline [duration] <nick|user@host> on irc.xyz.net :reason + +Scenario 2 +---------- + +Oper wishes to K-Line user@host on all servers named *.uk + +/quote kline <nick|user@host> on *.uk :reason +/quote kline [duration] <nick|user@host> on *.uk :reason + +Scenario 3 +---------- + +Oper wishes to place a network wide K-Line on user@host + +/quote kline <nick|user@host> on * :reason +/quote kline [duration] <nick|user@host> on * :reason + + +Authorization +------------- + +For the K-Line to be accepted by the remote server, the server must have +explicitly allowed K-Lines from that user. This is done via a shared {}; +block in ircd.conf. + +The shared block contains two settings, a user@host mask of the oper +who is allowed to K-Line, and a servername. + +- If both of these options are present, K-Lines will only be allowed + from that specific user@host on that specific server. +- If only the servername is present, all K-Lines from opers on that + server will be accepted. +- If only the user@host is present, all K-Lines from that user@host on + any server will be accepted. +- If neither are present, the shared block is invalid. + +shared { + /* The name of the server we allow K-Lines from */ + name = "this.server.net"; + + /* the user@host allowed to K-Line */ + user = "user@host.com"; +}; + +Server to Server Protocol +------------------------- + +As mentioned above, each server capable of remote K-Lines passes +the capability KLN along. No server will send a KLINE to a server +without a KLN capability. + +Server to server messages are formatted like this: + + ":oper KLINE target.server duration user host :reason" + +Note the difference between hybrid-6 GLINE which explicitly passed +the oper user@host and server along. This was originally done to handle +possible desync conditions, but is now shelved in favor of saving +some bandwidth. + +oper: the nick of the oper performing the K-Line +target.server: the server(s) this K-Line is destined for +duration: the duration if a TK-Line, 0 if permanent. +user: the 'user' portion of the K-Line +host: the 'host' portion of the K-Line +reason: the reason for the K-Line. diff --git a/doc/messages.txt b/doc/messages.txt new file mode 100644 index 0000000..a8c6227 --- /dev/null +++ b/doc/messages.txt @@ -0,0 +1,54 @@ + Message Customization Overview + + $Id$ + + Copyright (c) 2005-2012 by ircd-hybrid team + + ---------------------------------------------------------------------- + + Hybrid now supports its own .lang format for i18n'd IRC status messages. + + This document is split into two parts, using message files, and creating + your own. + + ---------------------------------------------------------------------- + + Using Provided or Pre-made Message Files + + There are a number of message files provided with ircd-hybrid. These can + be found in the source tree in messages/. + + These files are automatically installed by `make install'. + + These message files can be used in ircd once they are installed. Try the + installed message file with /quote SET MSGLOCALE <locale> first. The + locale will be 'standard' for the plain messages that are Hybrid's + default. + + If the desired message file works without any issues, it can be set to be + the default message file in the ircd.conf file. Refer to example.conf's + documentation on the message_locale setting. + + ---------------------------------------------------------------------- + + Creating Your Own Messages + + This process is a little more complicated. The easiest way to start + editing messages is to take ircd-standard.example.lang, make a copy, + and change whichever status lines you wish. + + Once you have your customized message file ready, just copy it into the + same place as the rest of the messages, typically $PREFIX/messages. + + If you think your .lang file deserves to be in the official distribution, + submit it to us at bugs@ircd-hybrid.org. It must be complete and as error- + free as you can make it since it is subject to public consumption. Providing + a translation will be a way that nearly anyone who knows multiple languages + to contribute to ircd, and get their name in the translation credits. + + When making such a translation, you should base it off + ircd-standard.example.lang, which is a conversion of our base (English) + messages.tab into the .lang format. You should edit it from there into your + own language, and of course give credit to yourself and whoever else you + may have done the translation with. Then, send it off to us, and we'll see + what we can do. diff --git a/doc/modeg.txt b/doc/modeg.txt new file mode 100644 index 0000000..f3b91dc --- /dev/null +++ b/doc/modeg.txt @@ -0,0 +1,144 @@ + User Mode +g Documentation + +Hybrid 7 includes a new and power feature that all users can take advantage +of to help prevent flooding and unwanted messages. This new feature is +invoked by setting user mode +g. When a client is set +g, that user will +be in "Caller ID" mode. Any user that messages a +g client will receive +a numeric saying that they are in +g (server side ignore) mode. The target +client (who is set +g) will also receive a numeric saying that so and so +messaged them, and that they are in +g mode. + +The target of the message will only receive one notification per minute, from +any client, in order to help prevent flooding. The sender will NOT have the +rate limit, and will receive a numeric saying the target is in +g mode every +time they send a message. Note that this behavior is similar to the way AWAY +messages are done. + +There are numerous benefits for both opers and regular users, including the +ability to stop spambot messages from ever reaching your client, stopping +private message and CTCP floods, and being able to sit on IRC in privacy. + +There is also a softer variation of +g named +G, which allows people you see +on your channels talk to you. In other words, messages from users/spambots +sitting on no common channels with you are automagically blocked. + +One question that arises is how to message specific users, while blocking +out everyone else. The command ACCEPT is your answer. To add a user to +your accept list, issue the raw command ACCEPT <nick>,<nick>,<nick>,... + +You will not receive a reply from the ACCEPT command if it is successful, +only if an error has occured. There are three possible errors, shown by +numerics: + + ERR_ACCEPTFULL (456): :irc.server 456 client :Accept list is full + - This is sent when an accept list is full. + ERR_ACCEPTEXIST (457): :irc.server 457 client target :already exists + - This is sent when a client tries to add a user to the accept list + that already exists there + ERR_ACCEPTNOT (458): :irc.server 458 client target :doesn't exist + - This is sent when a client tries to remove a user from their accept + list who is not on the accept list. + +That user will now be able to send messages to your client until the +association is broken. + +Associations break in one of the following situations: when an accepted user +QUIT's (or is on the other side of a split), you QUIT, or the accepted user +changes their nick. The reason why a remote user's nick change will remove +them from your accept list is so that you cannot track a user after they +changed their nick. + +Viewing the accept list is also very easy. Issue the raw command ACCEPT *. +Removing a user from your accept list is also simple. Issue the command +ACCEPT -<nick>. + + Sample Session + +The easiest way to see how this works is by experiencing it. Seeing a sample +session can help understand what goes on though. + +Client Hwy-LL is set +g initially. +Client Hwy101 wants to message Hwy-LL + +Note that some clients may have to use /quote ACCEPT instead of /accept. + +-- + +Client Hwy101: /msg Hwy-LL hi +Hwy101 will see: -Hwy-LL- *** I'm in +g mode (server side ignore). + -Hwy-LL- *** I've been informed you messaged me. + +Hwy-LL will see: Client Hwy101 [wcampbel@admin.irc.monkie.org] is messaging + you and you are +g + +The sender will receive the numeric from the target of the message, while +the recipient will receive the numeric from the server. + +-- + +If Hwy101 sends another message to Hwy-LL (before the minute expires), he will +see: -Hwy-LL- *** I'm in +g mode (server side ignore). +and will not receive the second numeric + +Hwy-LL will NOT see any numeric. + +-- + +Hwy-LL now wishes to see messages from Hwy101 and SpamBot + +Client Hwy-LL: /accept Hwy101,SpamBot + +Neither side will be told of the change in the accept list, Hwy-LL should +presume that the accept was successful if no error occurs. + +Now Hwy-LL can see messages from Hwy101 and SpamBot without any blockage. +If Hwy101 was also set +g, then he would have to issue /accept Hwy-LL +before he would be able to see messages from Hwy-LL. + +-- + +Hwy-LL now wants to see who is on his accept list. + +Client Hwy-LL: /accept * + +Hwy-LL will see: + irc.server 281 Hwy-LL Hwy101 SpamBot + irc.server 282 Hwy-LL :End of /ACCEPT list + +The replies are in numeric form to help parsing by scripts. +-- + +Hwy-LL realises he added a spambot to his list, and wants to remove it, and +allow messages from services + +Client Hwy-LL: /accept -SpamBot,services + +Hwy-LL will now only accept messages from Hwy101 and services. + +-- + +The nicks to be added can be in ANY order, however you cannot add or remove +AND list. + /ACCEPT x,y,-z,f,-a would be acceptable. + /ACCEPT x,y,-z,* would ignore the * and generate an invalid nick + response. + +Like Dalnet and Undernet's SILENCE system, the accept list only exists while +you are connected to IRC. In order for you to have the same accept list +every time you come onto IRC, you must put the accept commands into your +client's auto-perform, or manually issue the commands each time. + +This system may seem similar to the SILENCE system, but it is actually a +reverse SILENCE. SILENCE ignores certain users and allows the rest. Mode ++g ignores all users except certain ones (on your accept list.) Both systems +have their place, but the mode +g in Hybrid 7 is what the developers thought +would be most useful for clients. + +The goals of this user mode is to provide protection from flooding and +spamming, and to provide users with a means to keep their privacy. + +We hope that these goals are obtained. + +-- +W. Campbell +$Id$ diff --git a/doc/modes.txt b/doc/modes.txt new file mode 100644 index 0000000..0a5e4fb --- /dev/null +++ b/doc/modes.txt @@ -0,0 +1,72 @@ + User and Channel Modes Guide + ---------------------------- + +In /VERSION one might see something like this: + +irc.corefailure.com hybrid-7beta5 oiwszcerkfydnxbaugl biklmnopstveIh bkloveIh + +These describe the user modes, channel modes, and channel modes that require +arguments that are available to the user. It is hardcoded into src/messages.tab. + +Here is a guide to the preceding modes: + +User Modes: + ++a - admin - Admin status. Can for example see IPs in "STATS c" ++b - bots - See bot and drone flooding notices ++c - cconn - Client connection/quit notices ++D - deaf - Don't receive channel messages ++d - debug - See debugging notices ++f - full - See I: line full notices ++G - softcallerid - Server Side Ignore for users not on your channels ++g - callerid - Server Side Ignore (see modeg.txt) ++h - hidden - Hides operator status to other users ++i - invisible - Not shown in NAMES or WHO unless you share a channel ++j - rej - See rejected client notices ++k - skill - See server generated KILL messages ++l - locops - See LOCOPS messages ++n - nchange - See client nick changes ++o - oper - Operator status ++r - registered - User has been registered and identified for its nick. + This mode can be set by servers and services only. ++R - regonly - Only registered clients may message you ++s - servnotice - See general server notices ++u - unauth - See unauthorized client notices ++w - wallop - See server generated WALLOPS ++x - external - See remote server connection and split notices ++y - spy - See LINKS, STATS (if configured), TRACE notices ++z - operwall - See oper generated WALLOPS + +Channel Modes: + ++b - ban - Channel ban on nick!user@host ++e - exempt - Exemption from bans ++I - invex - Invite exceptions, nick!user@host does not need to be + explicitly INVITE'd into the channel before being able + JOIN ++i - invite - Invite only ++k - key - Key/password for the channel ++l - limit - Limit the number of users in a channel ++m - moderated - Users without +v/h/o cannot send text to the channel ++n - noexternal - Users must be in the channel to send text to it ++o - chanop - Full operator status ++O - operonly - This mode will prevent anyone who hasn't obtained + IRCOp status from joining the channel. Can be set by an IRCOp + only ++p - private - Private is obsolete, this now restricts KNOCK, and can be + set at the same time as +s. ++r - registered - Channel has been registered ++R - regonly - Only registered clients may join a channel with that mode set ++s - secret - The channel does not show up on NAMES or LIST or in the + WHOIS channel list unless you are a member of the channel ++S - sslonly - This mode will prevent anyone who isn't securely connected + via SSL/TLS from joining the channel. ++t - topic - Only chanops can change the topic ++v - voice - Can speak in a moderated channel, and is exempt from flood + restrictions + +The third part of the 004 numeric lists channel modes that require arguments. +Currently these are bkloveIh. + + +# $Id$ diff --git a/doc/resv.txt b/doc/resv.txt new file mode 100644 index 0000000..d1e0fdc --- /dev/null +++ b/doc/resv.txt @@ -0,0 +1,115 @@ +/* + * doc/resv.txt - Overview of the resv system + * Lee Hardy <lee@leeh.co.uk> + * + * Copyright (C) 2001 Hybrid Development Team + * + * $Id$ + */ + + RESV + -======- + +- What is resv, and why was it coded? + + Resv is a method of 'juping' or 'reserving' nicks and channels, to prevent + local clients using them. It is commonly used to block channels which + are home to abusers, and which attract DoS. It can also be used to stop + people pretending to be services, on a network that doesn't support them. + + It was coded to replace the method in hybrid-6 of blocking channels and + nicks, and was implemented in a much cleaner way to make it faster. + + The hybrid-6 method used to have to physically create channels, and + suffered flaws, resv does not. + +- How can I create a resv? + + There are two types of resv. 'permanent' and 'temporary'. Temporary + resv's will be erased when a server restarts (they will stay through a + rehash). Permanent resv's will stay through a restart. + + You may add permanent resv's into ircd.conf, but they are deprecated. + They should have the reason for the resv, followed by the nicks and + channels being resv'd. The following would block the channel + #services, the nick 'services' and any nick ending in 'serv' (ie: chanserv) + + resv { + reason = "There are no services on this network"; + channel = "#services"; + nick = "services"; + nick = "*serv"; + }; + + All resv's created by RESV are stored in cresv.conf or nresv.conf depending + on the nature of the RESV. + + Syntax: /quote resv <#channel|nick> :<reason> + + So to resv #warez: + /quote resv #warez :No warez on this network. + + To resv kiddie01: + /quote resv kiddie01 :Abuse + + To resv clone*: + /quote resv clone* :clones + + If a non admin does this, he will see: + -irc.leeh.co.uk- You must be an admin to perform a wildcard RESV + +- How do I remove a resv? + + If the resv is stored in ircd.conf, then the resv must be removed from there, + then a /rehash, should do the trick. + + If the resv was made using /RESV, then use the unresv command: + + Syntax: /quote unresv <#channel|nick> + +- Can I make a resv on all servers? + + No. In Hybrid resv's are local only. If a channel is full of abusers, + the solution is not to just block the channel, the abusers themselves + should be removed through /kline and /dline. + +- How do I list resv's? + + To list all current resv's: + /stats q + + Which will give a reply like: + q #warez No warez *@* + Q hax No hackers allowed here + + If the first letter is a 'q', then the resv is in [cn]resv.conf, if the + first letter is a 'Q' then the resv is hardcoded (in ircd.conf). + +- What does a client see if they try using a channel/nick that is resv'd? + + They see the numeric 437 (ERR_UNAVAILRESOURCE) + + Other networks (namely IRCNet) use this numeric on a split, to indicate + the channel cannot be joined, as such it is recognised by a lot of + clients. + +- Can an oper see when someone tries to use a resv'd nick/channel? + + No. When there is a valid reason for this, then possibly, but I honestly + don't see why anyone needs it. + +- Can I resv a local channel? + + Yes. It takes the same format as creating a resv on a normal channel: + /resv &clones :no clonebots! + +- Do you support wildcard channel resv's? + + No. This is mainly for speed reasons. When we are searching nicks, we + cannot just check if the nick, and the item in the list of resv'd nicks + are string equal, we have to check if they match, so we have to search a + full list. With channels however, we can search a hash table to see if an + entry exists, if it doesn't, then the channel isn't resv'd. We don't have + to search through all the channels. + + Besides.. it's legal for a channel to be called #*warez* anyway ;) diff --git a/doc/server-version-info b/doc/server-version-info new file mode 100644 index 0000000..619f823 --- /dev/null +++ b/doc/server-version-info @@ -0,0 +1,48 @@ + Server VERSION Info + + $Id$ + + Copyright (c) 2005 by ircd-hybrid team + + ---------------------------------------------------------------------- + + Updated for Hybrid 7.2 (2005/08/20) + + When you type /VERSION, you will often see something like this: + + hybrid-7.2beta1(20050820_4). test1.chatjunkies.org :eGgHIKMZ6 TS6ow + + Ever wondered what those funny chars mean after the version number? Well + here they are: + + +----------------------------+ + | 'e' | USE_EXCEPT | + |------+---------------------| + | 'G' | GLINES | + |------+---------------------| + | 'g' | NO_FAKE_GLINES | + |------+---------------------| + | 'H' | HUB | + |------+---------------------| + | 'I' | USE_INVEX | + |------+---------------------| + | 'K' | USE_KNOCK | + |------+---------------------| + | 'M' | IDLE_FROM_MSG | + |------+---------------------| + | 'Z' | ZIPLINKS | + |------+---------------------| + | 'T' | IGNORE_BOGUS_TS | + |------+---------------------| + | '6' | IPv6 | + |------+---------------------| + | --- | ------------------- | + |------+---------------------| + | 'TS' | Supports TS | + |------+---------------------| + | '6' | TS Version 6 | + |------+---------------------| + | 'o' | TS Only | + |------+---------------------| + | 'w' | TS Warnings | + +----------------------------+ diff --git a/doc/serverhide.txt b/doc/serverhide.txt new file mode 100644 index 0000000..83fd850 --- /dev/null +++ b/doc/serverhide.txt @@ -0,0 +1,120 @@ + Server Hide Reference + + $Id$ + + Copyright (c) 2001-2012 by ircd-hybrid team + + ---------------------------------------------------------------------- + + Due to pressures from abusers, the Hybrid developers have created a set of + options to limit what users can and cannot do on the server. Each option + can be enabled or disabled at runtime. + + This document describes the ircd-hybrid implementation of the server hiding + ideas originated by (and credited to) numerous people. + + * LINKS as a file: This option is always enabled. It will generate a + file at a certain interval, defined by the links_delay in ircd.conf, + that contains the current LINKS data. This data is sent to users + whenever a LINKS is requested. Opers will always see the current + server structure. + + The file that the LINKS data is stored in is by default etc/links.txt. + + The benefits of this are that transient splits will not be seen by + users issuing LINKS commands, and if a server is split, users can + still see what other servers are normally available. + + * Flattened LINKS: This option forces every server to look as if it is + connected to the local server. Users will see a flat LINKS tree. + + The benefit to using LINKS flattening is that users cannot get + information on how servers are routed. + + The flatten_links in the serverhide {} block in the ircd.conf controls + this feature. + + As a side effect, all netsplit quit messages will appear to originate + from the local server. + + +--------------------------------------------------------------------+ + | Flattened LINKS is needed for any network that uses the hidden hub | + | option. See below for more details. | + +--------------------------------------------------------------------+ + + + + * Hidden server option: This option will hide the server from a + flattened LINKS list on other servers. Opers will of course see the + true routing of the network. + + This is controlled by the hidden option in ircd.conf. + + +--------------------------------------------------------------------+ + | Technically, this code is a hack. With this option enabled, the | + | server will prepend '(H) ' to the server info field when | + | connecting to other servers. Other servers must understand that | + | the (H) means hidden. | + +--------------------------------------------------------------------+ + + * The allow_hidden option is needed to allow servers to use the hidden + server option described above. + + * The hide_servers option forces the server to not be shown when a user + issues WHOIS and other commands which may show what server a user is + on. + + Local user counts, as normally displayed in LUSERS, USERS, and the 255 + numeric, will be shown with the same values as the global counts. + Displaying it this way will help protect servers and avoid breaking + scripts that depend on the 265 and 266 numerics on connect. + + To be effective, this option must be used network wide. + + * The disable_remote_commands option takes care of most of the remaining + issues. These include, for example, ADMIN some.hub.server, VERSION + someuser, and similar commands. A server with this option enabled will + only prevent local users from issuing remote commands. Remote users + will not be affected. + + Remote WHOIS is not blocked. It is, however, restricted to only + querying WHOIS nick nick. The ircd will disregard the server parameter + and always use queried nick. + + * All server modes appear to originate from the server you are using. + This feature is not tunable; and opers also do not see the real server + setting the mode. + + Each item is briefly described in the serverhide {} block in ircd.conf. + + ---------------------------------------------------------------------- + +Using Non-QS Compliant Hubs + + The flattened LINKS option will, as a side effect, display all user QUITs + due to network splits in the following format: + + :user QUIT :*.net *.split + + This works extremely well as long as all servers on your network are + compliant with the QS capability, which sends a single SQUIT to the + network when a server (or tree of servers) splits. All quit messages are + generated on the local server. Certain older servers do not have this + ability, and as such will generate their own quit messages for users who + left because of the split. This can cause leaks in the hub server names + and the structure of the network. + + A quick example is the following network structure: + + servA(Hyb7) --- hubA(nonQS) --- servB(not-important) + + When servB splits from hubA, hubA will generate a QUIT command for every + user on servB (and anything behind servB). Since the QUIT message was not + created on your server, with server hiding enabled, the QUIT message will + contain the real server names. + + The only way to prevent this leak on a network is to only use hubs + supporting the QS capability. Hybrid 6, Hybrid 7, and csircd all are + currently running daemons that support QS. Hybrid 5 and 2.8.21+CSr servers + do not support QS, and will leak server names (and therefore routing + information) on splits. diff --git a/doc/technical/draft-mitchell-irc-capabilities-01.txt b/doc/technical/draft-mitchell-irc-capabilities-01.txt new file mode 100644 index 0000000..f0c6736 --- /dev/null +++ b/doc/technical/draft-mitchell-irc-capabilities-01.txt @@ -0,0 +1,1298 @@ + +Network Working Group K. Mitchell +Internet-Draft P. Lorier +Expires: September 5, 2005 Undernet IRC Network + L. Hardy + ircd-ratbox + P. Kucharski + IRCnet + March 7, 2005 + + IRC Client Capabilities Extension + draft-mitchell-irc-capabilities-01 + +Status of this Memo + + This document is an Internet-Draft and is subject to all provisions + of section 3 of RFC 3667. By submitting this Internet-Draft, each + author represents that any applicable patent or other IPR claims of + which he or she is aware have been or will be disclosed, and any of + which he or she become aware will be disclosed, in accordance with + RFC 3668. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as + Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft will expire on September 5, 2005. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + IRC (Internet Relay Chat) is a long-standing protocol for real-time + chatting. The basic client-server protocol is a very simple + text-based protocol with no explicit mechanism for introducing or + + +Mitchell, et al. Expires September 5, 2005 [Page 1] +Internet-Draft IRC CAP March 2005 + + negotiating backwards-incompatible extensions. This memo presents a + mechanism for negotiation of such extensions. + +Requirements Language + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in RFC + 2119 [1]. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + + 2. Problems to be Solved . . . . . . . . . . . . . . . . . . . . 4 + + 3. The CAP Command . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.1 CAP LS . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.2 CAP LIST . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.3 CAP REQ . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 3.4 CAP ACK . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 3.5 CAP NAK . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 3.6 CAP CLEAR . . . . . . . . . . . . . . . . . . . . . . . . 8 + 3.7 CAP END . . . . . . . . . . . . . . . . . . . . . . . . . 8 + + 4. Capability Negotiation . . . . . . . . . . . . . . . . . . . . 10 + + 5. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.1 Capability Modifiers . . . . . . . . . . . . . . . . . . . 11 + + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 + + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 + + 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 + + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 + + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 15 + + A. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 + + B. ABNF Description of Capabilities . . . . . . . . . . . . . . . 19 + + C. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + + Intellectual Property and Copyright Statements . . . . . . . . 28 + + +Mitchell, et al. Expires September 5, 2005 [Page 2] +Internet-Draft IRC CAP March 2005 + +1. Introduction + + The IRC protocol, as originally documented by RFC 1459 [2] and + updated by RFC 2812 [3], is a simple, text-based conferencing + protocol, involving a number of users spread across a number of + interconnected servers. These users may chat with other individual + users, or may chat with groups of users on "channels"--what other + chat systems refer to as "rooms" or "chat rooms". + + Over the years, various extensions to the basic IRC protocol have + been made by IRC server programmers. Often, these extensions are + intended to conserve bandwidth, close loopholes left by the original + protocol specification, or add features for users or for the server + administrators. Most of these changes are backwards-compatible with + the original protocol specification: A command may be added, a reply + may be extended to contain more parameters, etc. Recently, however, + there has been a desire to introduce changes that would not be + backwards-compatible with existing IRC clients. Ideally, these + protocol changes would only be used with clients and servers that can + understand the revised protocol. Unfortunately, the IRC protocol + does not provide any form of extension or protocol negotiation, + making it impossible to determine support for such extensions. + + This memo introduces a standardized mechanism for negotiation of + protocol extensions, known as *capabilities*, that will be + backwards-compatible with all existing IRC clients and servers. Any + server not implementing this extension will still interoperate with + clients that do implement it; similarly, clients that do not + implement the capabilities extension may successfully communicate + with a server that does implement the extension. + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 3] +Internet-Draft IRC CAP March 2005 + +2. Problems to be Solved + + The IRC protocol is not a lockstep protocol. This means that a + client may issue additional commands before the server has finished + responding to the first one. Additionally, unlike other protocols, + the server does not necessarily issue a banner response upon initial + connection. This, combined with the fact that some servers do not + complain about unknown commands prior to completion of the client + registration phase, means that a client cannot know for certain + whether a server implements the extension. If a client had to wait + for a banner message, it would fail to interoperate with a server not + implementing the capabilities extension. If the client must issue a + command and then wait for a response, a similar problem results. As + some potential protocol extensions must be set up prior to completion + of the client registration phase, there is no reliable way a server + may indicate implementation of the capabilities extension to a + client. + + The solution to these problems turns out to be to extend the client + registration procedure. The client sends a request to begin + capability negotiation, as well as the other information necessary + for client registration (user name, nick name, optional password, + etc.). If the server understands the capabilities extension, it will + suspend completion of the registration phase until the negotiation is + complete; negotiation may then proceed in a lockstep fashion. If the + server does not understand capabilities, then the registration will + complete immediately, and the client will receive the 001 numeric. + This will signal to the client that the server does not implement the + capabilities extension. + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 4] +Internet-Draft IRC CAP March 2005 + +3. The CAP Command + + The capabilities extension is implemented by addition of one command + with several subcommands. The command added is *CAP*. CAP takes a + single, required subcommand, optionally followed by a single + parameter consisting of a space-separated list of capabilities. Each + capability within the list MAY be preceded by a capability modifier. + (Section 5.1) + + The subcommands defined for CAP are: + + 1. LS (Section 3.1) + 2. LIST (Section 3.2) + 3. REQ (Section 3.3) + 4. ACK (Section 3.4) + 5. NAK (Section 3.5) + 6. CLEAR (Section 3.6) + 7. END (Section 3.7) + + The LS (Section 3.1), LIST (Section 3.2), REQ (Section 3.3), ACK + (Section 3.4), and NAK (Section 3.5) subcommands may be followed by a + single parameter consisting of a space-separated list of capability + names. If more than one capability is named, this argument MUST be + preceded by the IRC protocol colon (':') sentinel to signal that the + remainder of the line is a single argument. + + If a client sends a subcommand not listed above or issues an invalid + command, the server SHOULD reply with the ERR_INVALIDCAPCMD numeric + response, 410. The first parameter after the client nickname SHALL + be the subcommand the client sent; the second parameter SHOULD be a + textual description of the error. + + In ABNF [4] notation: + + capcmd = [ ":" servername SP ] "CAP" SP subcmd + + subcmd = lscmd / listcmd / reqcmd / ackcmd / + nakcmd / clearcmd / endcmd + + capcmderr = ":" servername SP "410" SP nick SP badcmd + SP ":Invalid CAP subcommand" + ; badcmd is the unrecognized subcommand + + caplist = [ ":" ] *( capmod ) capab + caplist =/ ":" *( capmod ) capab 1*( SP *( capmod ) capab ) + + where SP is as designated in Appendix A of RFC 2234 [4], and + servername and nick are as designated in section 2.3.1 of RFC 1459 + + +Mitchell, et al. Expires September 5, 2005 [Page 5] +Internet-Draft IRC CAP March 2005 + + [2]. + + The discussion in the following sections applies only to clients and + servers implementing the capabilities extension. Servers (and + clients) not implementing the capabilities extension are exempted + from the requirements of this section. + +3.1 CAP LS + + The LS subcommand is used to list the capabilities supported by the + server. The client SHALL send an LS subcommand with no arguments to + solicit a list of supported capabilities from the server. Servers + MUST respond to such LS subcommands with one or more LS subcommands + containing the list of recognized capabilities. All but the last + subcommand MUST have a parameter containing only an asterisk ('*') + preceding the capability list. + + If a client issues an LS subcommand during the client registration + phase, client registration MUST be suspended until an END (Section + 3.7) subcommand is received. + + ABNF [4] description of the LS subcommand: + + lscmd = "LS" + lscmd =/ "LS" SP [ "*" SP ] caplist + +3.2 CAP LIST + + The LIST subcommand is provided to permit the client to request a + list of the capabilities currently active for the connection. It is + similar to the LS (Section 3.1) subcommand--if a client issues a LIST + subcommand with no arguments, the server MUST respond with a sequence + of LIST subcommands, all but the last of which MUST have a single + parameter consisting solely of an asterisk ('*') preceding the list + of capabilities. If no capabilities have been enabled, the server + MUST send a LIST command with an empty capability list; the parameter + MUST NOT be omitted. The active capabilities MAY be listed in any + order. + + ABNF [4] description of the LIST subcommand: + + listcmd = "LIST" + listcmd =/ "LIST" SP ":" + listcmd =/ "LIST" SP [ "*" SP ] caplist + + + +Mitchell, et al. Expires September 5, 2005 [Page 6] +Internet-Draft IRC CAP March 2005 + +3.3 CAP REQ + + The REQ subcommand is sent by the client to request that a capability + or set of capabilities be enabled or disabled. Its sole parameter + MUST be a space-separated list of capabilities. Each capability name + MAY be preceded by a dash ('-') to indicate that the capability + should be disabled. Additionally, receipt of this subcommand during + the client registration MUST suspend client registration until an END + (Section 3.7) subcommand is received. + + Servers MUST respond to a REQ command with either the ACK (Section + 3.4) or NAK (Section 3.5) subcommands to indicate acceptance or + rejection of the capability set requested by the client. A server + MUST accept the entire capability set or reject it whole; servers + MUST NOT accept some capabilities in the set while rejecting others. + If a client requests that a "sticky" capability be disabled, the + server MUST reject the capability set. + + ABNF [4] description of the REQ subcommand: + + reqcmd = "REQ" SP caplist + +3.4 CAP ACK + + The ACK subcommand has three uses. It is used by the server to + acknowledge a REQ (Section 3.3) subcommand; by the server to + acknowledge a CLEAR (Section 3.6) subcommand and list the removed + capabilities; and by the client to acknowledge certain capabilities + designated as requiring acknowledgment. If more than one ACK is + required due to the IRC line length limitation of 512 characters, all + but the last SHALL contain a parameter consisting of a single + asterisk ('*') immediately preceding the list of capabilities, as for + LS (Section 3.1) and LIST (Section 3.2). + + If an ACK reply originating from the server is spread across multiple + lines, a client MUST NOT change capabilities until the last ACK of + the set is received. Equally, a server MUST NOT change the + capabilities of the client until the last ACK of the set has been + sent. + + In the first usage, acknowledging a REQ (Section 3.3) subcommand, the + ACK subcommand has a single parameter consisting of a space separated + list of capability names, which may optionally be preceded with one + or more modifiers (Section 5.1). + + The second usage, acknowledging a CLEAR (Section 3.6) subcommand, is + similar to the first usage. When a CLEAR (Section 3.6) subcommand is + + +Mitchell, et al. Expires September 5, 2005 [Page 7] +Internet-Draft IRC CAP March 2005 + + issued, all non-"sticky" capabilities are disabled, and a set of ACK + subcommands will be generated by the server with the disable modifier + preceding each capability. + + The third usage is when, in the preceding two cases, some capability + names have been preceded with the ack modifier. ACK in this case is + used to fully enable or disable the capability. Clients MUST NOT + issue an ACK subcommand for any capability not marked with the ack + modifier in a server-generated ACK subcommand. + + ABNF [4] description of the ACK subcommand: + + ackcmd = "ACK" SP [ "*" SP ] caplist + +3.5 CAP NAK + + The NAK subcommand MUST be sent by the server in response to a REQ + (Section 3.3) subcommand when any capability change requested cannot + be performed for any reason. The server MUST NOT make any change to + the set of capabilities for the client if it responds with a NAK + subcommand. The argument of the NAK subcommand MUST consist of at + least the first one hundred characters of the capability list in the + REQ (Section 3.3) subcommand which triggered the NAK. + + ABNF [4] description of the NAK subcommand: + + nakcmd = "NAK" SP ":" acklist + ; acklist is at least 100 characters of the + ; capability list from the REQ + +3.6 CAP CLEAR + + The CLEAR subcommand requests that the server clear the capability + set for the client. The server MUST respond with a set of ACK + (Section 3.4) subcommands indicating the capabilities being + deactivated. + + ABNF [4] description of the CLEAR subcommand: + + clearcmd = "CLEAR" + +3.7 CAP END + + The END subcommand signals to the server that capability negotiation + is complete and requests that the server continue with client + + +Mitchell, et al. Expires September 5, 2005 [Page 8] +Internet-Draft IRC CAP March 2005 + + registration. If the client is already registered, this command MUST + be ignored by the server. + + Clients that support capabilities but do not wish to enter + negotiation SHOULD send CAP END upon connection to the server. + + ABNF [4] description of the END subcommand: + + endcmd = "END" + + + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 9] +Internet-Draft IRC CAP March 2005 + +4. Capability Negotiation + + Clients implementing this extension SHOULD take one of the following + three actions upon initial connection to a server: + + o Issue an LS (Section 3.1) subcommand (with an empty capability + list) to solicit a list of supported capabilities from the server; + + o Issue the REQ (Section 3.3) subcommand to request a particular set + of capabilities without knowing what capabilities the server + supports or if it supports the capabilities extension; or + + o Issue the END (Section 3.7) subcommand to signal implementation of + the capabilities extension without entering into capability + negotiation. + + Although a client is permitted to not issue any CAP commands upon + connection, this is NOT RECOMMENDED. Servers MAY assume a client + does not implement the capabilities extension if it does not issue + any CAP commands upon initial connection. + + Clients SHOULD follow CAP commands issued upon connection with the + standard IRC client registration commands without waiting for any + responses from the server. See RFC 1459 [2] for more details about + the client registration procedure. + + If a client issues the LS (Section 3.1) or REQ (Section 3.3) + subcommands during the client registration procedure, a server + implementing the capabilities extension MUST NOT complete the client + registration until the client issues the END (Section 3.7) + subcommand. A client that sees a RPL_WELCOME (001) numeric response + before it sends CAP END (Section 3.7) SHOULD assume that the server + does not support the capabilities extension. + + Once the client is registered, CAP commands SHALL have no effect on + other connection operations, except that a client MAY change the + capabilities it has set. In particular, CAP commands and their + responses MAY be interspersed with other protocol messages. The END + (Section 3.7) subcommand SHALL have no effect once client + registration has been completed. + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 10] +Internet-Draft IRC CAP March 2005 + +5. Capabilities + + Capabilities are designated by a name composed of one or more + elements. Name elements are not case-sensitive. They must begin + with a letter and may contain any number of letters, numbers, and the + dash character ('-'). Names containing more than one name element + MUST also contain a period character ('.') in the first name element. + Name elements are separated from each other via the slash character + ('/'). + + There are two capability name spaces: + + Network Specific: Names whose first element contains a period + character ('.') designate a delegated capability name space. The + first element MUST be a valid, existing DNS domain name. These + names MUST contain at least two elements. + + Standardized: All other names MUST correspond to capabilities + documented by an RFC. Further, these names MUST contain only one + element. + + These rules are summarized by the following ABNF [4] representation: + + elem = ALPHA *( ALPHA / DIGIT / "-" ) + + netname = elem 1*( "." elem ) + + netDeleg = netname 1*( "/" elem ) + + standardized = elem + + capab = netDeleg / standardized + + where ALPHA and DIGIT are as designated in Appendix A of RFC 2234 + [4]. + +5.1 Capability Modifiers + + There are various capability modifiers available. If a capability + modifier is to be used, it MUST directly precede the capability name. + The following are the modifiers defined for capabilities. Certain + modifiers MAY be combined. + + The disable modifier is used by both the server and the client to + indicate that a capability should be disabled. The disable modifier + is defined as the dash character ('-'). A client MUST only use the + disable modifier in the REQ (Section 3.3) and ACK (Section 3.4) + subcommands. A server MUST use the disable modifier in the ACK + + +Mitchell, et al. Expires September 5, 2005 [Page 11] +Internet-Draft IRC CAP March 2005 + + (Section 3.4) subcommand when disabling a capability, or in + conjunction with a ack modifier in the LIST (Section 3.2) subcommand. + The server MUST NOT use the disable modifier in any other command + response. + + The sticky modifier is used by the server to indicate a capability + that, once enabled, cannot be disabled. The sticky modifier is + defined as the equals character ('='). A client MUST NOT use the + sticky modifier. A server MUST only use the sticky modifier in the + ACK (Section 3.4), LIST (Section 3.2) and LS (Section 3.1) + subcommands and MUST use the modifier for all such capabilities. + + The ack modifier is used by the server to indicate that the client + must issue an ACK (Section 3.4) subcommand to fully enable or disable + the capability. The ack modifier is defined as the tilde character + ('~'). The ack modifier indicates that traffic originating from the + server SHALL make use of the capability, but the server SHALL NOT + expect traffic originating from the client to make use of the + capability. When combined with the disable modifier, it indicates + traffic originating from the server SHALL NOT make use of the + capability, but the server expects traffic originating from the + client SHALL make use of the capability. The ack modifier MAY be + combined with the sticky modifier. + + A server MUST use the ack modifier in the ACK (Section 3.4) and LIST + (Section 3.2) subcommands to indicate capabilities that require an + ACK (Section 3.4) subcommand from the client to be fully enabled or + disabled. Servers MUST also use the ack modifier in the response to + an LS (Section 3.1) subcommand to indicate capabilities which will + require ACK (Section 3.4) subcommands from the client. Clients MUST + NOT use the ack modifier, but SHOULD issue the ACK (Section 3.4) + subcommand as soon as possible after receiving an ACK (Section 3.4) + or REQ (Section 3.3) subcommand from the server that contains a + capability marked with the ack modifier. + + In ABNF [4] notation: + + dismod = "-" + stickymod = "=" + ackmod = "~" + + capmod = dismod / stickymod / ackmod + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 12] +Internet-Draft IRC CAP March 2005 + +6. IANA Considerations + + The standardized capability name space shall be managed by IANA in + accordance with the description of capability names in Section 5. In + particular, any name not containing the period character ('.') must + be specified by an RFC. + + + + + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 13] +Internet-Draft IRC CAP March 2005 + +7. Security Considerations + + Capabilities are an extension to a preexisting, insecure chat + protocol. This extension does not add and does not purport to add + any security to the IRC protocol. Capability negotiation occurs + after client registration has already begun. Moreover, no mechanism + is defined that allows parameters to be passed for specific + capabilities. Although such a mechanism could be added, + cryptographic security systems frequently require several exchanges + to establish a secure context, particularly if authentication must + also be negotiated. Thus, the capabilities extension is unsuited to + the implementation of those protocols, and other mechanisms, such as + SSL-encapsulated IRC, should be used. + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 14] +Internet-Draft IRC CAP March 2005 + +8. Acknowledgments + + The authors wish to gratefully acknowledge the participation of Aaron + Wiebe and the members of the proto-desc@dal.net email list in the + design of this protocol extension. + +9 References + + [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [2] Oikarinen, J. and D. Reed, "Internet Relay Chat Protocol", RFC + 1459, May 1993. + + [3] Kalt, C., "Internet Relay Chat: Client Protocol", RFC 2812, + April 2000. + + [4] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [5] Bradner, S., "IETF Rights in Contributions", BCP 78, RFC 3667, + February 2004. + +Authors' Addresses + + Kevin L. Mitchell + Undernet IRC Network + 38 Eighth St., Apt. 7 + Cambridge, Massachusetts 02141 + US + + Phone: +1-617-230-1021 + EMail: klmitch@mit.edu + URI: http://www.mit.edu/~klmitch/ + + Perry Lorier + Undernet IRC Network + 3 Liston Cres + Hamilton, Waikato 2001 + NZ + + Phone: +64-7-859-1109 + EMail: isomer@undernet.org + + + +Mitchell, et al. Expires September 5, 2005 [Page 15] +Internet-Draft IRC CAP March 2005 + + Lee Hardy + ircd-ratbox Development Team + + EMail: lee@leeh.co.uk + URI: http://www.leeh.co.uk + + Piotr Kucharski + IRCnet + + EMail: Beeth@irc.pl + URI: http://42.pl/ + + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 16] +Internet-Draft IRC CAP March 2005 + +Appendix A. Examples + + In the following examples, lines preceded by "CLIENT:" indicate + protocol messages sent by the client, and lines preceded by "SERVER:" + indicate protocol messages sent by the server. For clarity, the + origin field for server-originated protocol messages has been + omitted. This field would consist of a colon (':') followed by the + full server name, and would be the first field in the command. + + A client communicating with a server not supporting CAP. + + CLIENT: CAP LS + CLIENT: NICK nickname + CLIENT: USER username ignored ignored :real name + SERVER: 001 [...] + + A client which does not wish to enter capability negotiation. + + CLIENT: CAP END + CLIENT: NICK nickname + CLIENT: USER username ignored ignored :real name + SERVER: 001 [...] + + A client entering into capability negotiation during registration, + and requesting a set of capabilities that the server does not + support. + + CLIENT: CAP LS + CLIENT: NICK nickname + CLIENT: USER username ignored ignored :real name + SERVER: CAP LS * :A B C D E F G H + SERVER: CAP LS :I J + CLIENT: CAP REQ :A B C D E F + SERVER: CAP NAK :A B C D E F + CLIENT: CAP REQ :A C E F + SERVER: CAP ACK :A C E F + CLIENT: CAP REQ :B + SERVER: CAP ACK :B + CLIENT: CAP REQ :D + SERVER: CAP NAK :D + CLIENT: CAP END + SERVER: 001 [...] + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 17] +Internet-Draft IRC CAP March 2005 + + A client requesting a capability that requires an ACK (Section 3.4) + subcommand from the client to be enabled. + + CLIENT: CAP LS + SERVER: CAP LS :~I ~J K + CLIENT: CAP REQ :I J K + SERVER: CAP ACK :~I ~J K + CLIENT: CAP ACK :I J + + A client requesting a capability that requires an ACK (Section 3.4) + subcommand from the client to be enabled and disabled, using the LIST + (Section 3.2) subcommand in between. + + CLIENT: CAP LS + SERVER: CAP LS :~A ~B + CLIENT: CAP REQ :A B + SERVER: CAP ACK :~A ~B + CLIENT: CAP LIST + SERVER: CAP LIST :~A ~B + CLIENT: CAP ACK :A B + CLIENT: CAP LIST + SERVER: CAP LIST :A B + CLIENT: CAP REQ :-B + SERVER: CAP ACK :-~B + CLIENT: CAP LIST + SERVER: CAP LIST :A -~B + CLIENT: CAP ACK :-B + CLIENT: CAP LIST + SERVER: CAP LIST :A + + A client requesting a capability that is sticky. + + CLIENT: CAP LS + SERVER: CAP LS :=I J + CLIENT: CAP REQ :I J + SERVER: CAP ACK :=I J + + A client requesting a capability be disabled. + + CLIENT: CAP LIST + SERVER: CAP LIST :=A B C D + CLIENT: CAP REQ :-B -C + SERVER: CAP ACK :-B -C + + + + +Mitchell, et al. Expires September 5, 2005 [Page 18] +Internet-Draft IRC CAP March 2005 + +Appendix B. ABNF Description of Capabilities + + This section summarizes the ABNF [4] description of the capabilities + extension. + + capcmd = [ ":" servername SP ] "CAP" SP subcmd + + subcmd = lscmd / listcmd / reqcmd / ackcmd / + nakcmd / clearcmd / endcmd + + capcmderr = ":" servername SP "410" SP nick SP badcmd + SP ":Invalid CAP subcommand" + ; badcmd is the unrecognized subcommand + + caplist = [ ":" ] *( capmod ) capab + caplist =/ ":" *( capmod ) capab 1*( SP *( capmod ) capab ) + + lscmd = "LS" + lscmd =/ "LS" SP [ "*" SP ] caplist + + listcmd = "LIST" + listcmd =/ "LIST" SP ":" + listcmd =/ "LIST" SP [ "*" SP ] caplist + + reqcmd = "REQ" SP caplist + + ackcmd = "ACK" SP [ "*" SP ] caplist + + nakcmd = "NAK" SP ":" acklist + ; acklist is at least 100 characters of the + ; capability list from the REQ + + clearcmd = "CLEAR" + + endcmd = "END" + + elem = ALPHA *( ALPHA / DIGIT / "-" ) + + netname = elem 1*( "." elem ) + + netDeleg = netname 1*( "/" elem ) + + standardized = elem + + capab = netDeleg / standardized + + dismod = "-" + stickymod = "=" + + +Mitchell, et al. Expires September 5, 2005 [Page 19] +Internet-Draft IRC CAP March 2005 + + ackmod = "~" + + capmod = dismod / stickymod / ackmod + + + + + + + + + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 20] +Internet-Draft IRC CAP March 2005 + +Appendix C. ChangeLog + + Note to RFC Editor: This section may be removed on publication as an + RFC. + + Here is a log of changes to this document: + + 2004-12-15 KLM Initial draft written. + + 2004-12-16 KLM + + * Added description of the argument to some CAP commands in + Section 3. + + * Clarified that requirements of Section 3 only apply to clients + and servers implementing capabilities. + + * Substitution of "performed" for "done" in Section 3.5 + + * Added LIST (Section 3.2) subcommand to provide a mechanism to + query active capabilities. + + * Added reference to RFC 2812 [3]. + + * Moved Examples (Appendix A) section into the back matter. + + * Corrected Perry Lorier's email address. + + * Added this ChangeLog section. + + * Corrected typo in Section 3.7: "sent" for "send". + + * Added <vspace> elements to enhance readability. + + * Changed to non-compact form. + + * Changed anchor for Section 5 to "capabilities" from "caps" to + reduce possible confusion. + + * Revise last sentence of first paragraph of Section 2 to remove + redundancy. + + * Revise last sentence of second paragraph of Section 2 + + * Added email addresses for Lee H and Beeth; updated contact + information for Isomer. + + + +Mitchell, et al. Expires September 5, 2005 [Page 21] +Internet-Draft IRC CAP March 2005 + + 2004-12-17 KLM + + * Augmented description of CAP command and subcommands with ABNF + description. + + * Revised Section 5 to remove "net." name space and replace it + with a delegated name space beginning with a DNS domain name + (suggested by Isomer). + + * Augmented ABNF description of capability names. + + * Revised Section 6 to reflect change in capability name space. + + * Added Appendix B to bring together the entire ABNF description + of capabilities. + + 2004-12-18 KLM + + * Added explanation of what should happen if an unrecognized + subcommand is given. + + * Clarified what to do if a client sends a subcommand that + shouldn't come from a client. + + * Add references to LIST (Section 3.2) to LSL and Section 3.1. + + * Section 3.3 omitted the caplist argument for the REQ command; + corrected. + + * Relax the prohibition against a client acknowledging a + capability that doesn't modify the protocol stream in Section + 3.4 + + * Relax the requirement for a client that understands + capabilities to send CAP END in Section 3.7 + + 2004-12-19 KLM + + * Converted a number of common xrefs into internal entities to + simplify the text. + + * Inserted some white space to make the <front> section a bit + more readable. + + * Added the keyword "Protocol". + + +Mitchell, et al. Expires September 5, 2005 [Page 22] +Internet-Draft IRC CAP March 2005 + + * Added the term "NOT RECOMMENDED" to the note on "Requirements + Language". + + * Moved LIST (Section 3.2) up in the list of CAP subcommands. + + * Minor formatting change to the ABNF representation of subcmd. + + * Capitalized "MAY" in "empty" subcommand. + + * Added text about capability list order and what to do if no + capabilities are implemented to "empty" subcommand. + + * Mention LIST (Section 3.2) also in LSL when talking about + sending more than one LSL subcommand. + + * Clarify language in Section 3.1 a little bit. + + * Substitute "set of capabilities" for "list of capabilities" in + Section 3.3. + + * Fix minor typo in preamble to ABNF description of NAK (Section + 3.5) subcommand: substitution of "ACK" for "NAK". + + * Add note about servers ignoring END (Section 3.7) after client + registration. + + * Fix minor typo in preamble to ABNF description of LIST (Section + 3.2) subcommand: substitution of "END" for "LIST". + + * Added Section 4 discussing capability negotiation. + + * Add ".xml" extension to include files in references section. + + * Simplification of preamble of first example (Appendix A). + + * Add 'type="ABNF"' to <artwork> sections so that they can be + extracted and used to create the abnf.xml now included in + Appendix B. + + * It's now RFC 3667 [5], not RFC 2026... + + 2004-12-27 KLM + + * Minor wording changes to second paragraph of Section 1 + + * Minor wording change to first paragraph of Section 2 + + +Mitchell, et al. Expires September 5, 2005 [Page 23] +Internet-Draft IRC CAP March 2005 + + * Minor wording changes to first paragraph of Section 3; remove + redundant note about the IRC colon sentinel. + + * Change a "must" to a "MUST" in Section 3.4; note that + capability list may be truncated if it would otherwise exceed + the 512 character limit. + + * In Section 3.5, note that capability list may be truncated if + it would otherwise exceed the 512 character limit. + + * Remove redundant line about ignoring END (Section 3.7) commands + after registration. + + * Correct spelling of "acknowledgments". + + * Empty <organization> elements for Lee H and Beeth; put Beeth's + real name, Piotr Kucharski, in the right place. + + * Switch to using a new preprocessor that consolidates all the + ABNF artwork and inserts it with the processing instruction + <?art type="foo"?>. + + * Remove deliberate page break after <abstract> section. + + * Reorder authors section to consolidate <organization> elements + for everyone. + + * Drop abbreviation for Undernet. + + * Expand Section 7 a bit to try to explain why capabilities are + not suited to securing IRC. + + 2005-01-04 KLM + + * Add Lee Hardy's information to the list of authors. + + 2005-01-05 KLM + + * Replace UNKNOWNCAPCMD with INVALIDCAPCMD. + + * Begin rewriting LS (Section 3.1) documentation + + + + +Mitchell, et al. Expires September 5, 2005 [Page 24] +Internet-Draft IRC CAP March 2005 + + 2005-01-19 KLM + + * Redesign the protocol substantially to simplify it. + + 2005-01-20 KLM + + * Update Piotr's contact information. + + * Drop the "x-" namespace... + + 2005-01-20 LH + + * Some servers do issue banner responses, now. + + * The CAP subcommand is now a requirement. + + * Minor grammatical fix-up in documentation of REQ (Section 3.3) + ("acceptance of or rejection of"--strike first "of"). + + * Clarify that sticky capabilities cause a REQ (Section 3.3) to + be NAK (Section 3.5)ed. + + * Mark the third case of an ACK (Section 3.4) with an explicit + indicator that it's the third case... + + * Strike redundant mention of not suspending client registration + in documentation for END (Section 3.7). + + 2005-01-21 LH + + * Move all references on capability modifiers to its own section + + * Clarify instructions on the ack ('~') modifier, indicating it + can be used with sticky capabilities. + + * Add a note into CAP section about capability modifiers + + 2005-01-21 KLM + + * Subcommands are not optional anymore; updated the description + of CAP and the ABNF to reflect this. + + * More than one modifier may precede a capability name. + + +Mitchell, et al. Expires September 5, 2005 [Page 25] +Internet-Draft IRC CAP March 2005 + + * Move ABNF for capmod into the "Capability Modifiers" section. + + * Fix a few minor grammatical errors (I think). + + * Note that capability names may be preceded by modifiers in the + first form of ACK. + + * Remove an unnecessary "MAY" in documentation for the third + usage of ACK. + + * Explicitly note in the ABNF for NAK that the parameter is an + opaque repeat of at least the first 100 characters of the + argument to REQ. + + * CLEAR may result in more than one ACK. + + * Clarify the language of what composes a capability name. + + * Add missing </figure>. + + * ACK subcommand should be sent in response to ACK with ack + modifier as soon as possible... + + * Allow disable modifier in LIST, but only in conjunction with an + ack modifier. + + * The ack modifier may also show up in an LS response; rewrote + the final paragraph to indicate that and clarify the language. + + * Add "Client" to the title in the appropriate place... + + * The "capability" rule in the ABNF got changed to "capab" for + brevity. + + * Update "date" to be current. + + 2005-01-22 LH + + * Clarify a client must not act upon an ACK spread across + multiple lines until it receives the final ACK of the set. + + 2005-01-23 KLM + + * Bump version number in preparation for any suggested edits... + + + +Mitchell, et al. Expires September 5, 2005 [Page 26] +Internet-Draft IRC CAP March 2005 + + 2005-01-26 LH + + * Clarify a server also must not change capabilities until its + finished sending its ACKs. + + 2005-01-27 KLM + + * Acknowledge Aaron Wiebe as participating. + + 2005-03-01 LH + + * Add examples on sticky modifiers, the removal modifier and the + sticky modifier. + + 2005-03-07 KLM + + * Submit second draft... + + + + + + + + + + + + + + + + +Mitchell, et al. Expires September 5, 2005 [Page 27] +Internet-Draft IRC CAP March 2005 + +Intellectual Property Statement + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Disclaimer of Validity + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Copyright Statement + + Copyright (C) The Internet Society (2005). This document is subject + to the rights, licenses and restrictions contained in BCP 78, and + except as set forth therein, the authors retain all their rights. + +Acknowledgment + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + +Mitchell, et al. Expires September 5, 2005 [Page 28] diff --git a/doc/technical/event.txt b/doc/technical/event.txt new file mode 100644 index 0000000..b09b0b7 --- /dev/null +++ b/doc/technical/event.txt @@ -0,0 +1,82 @@ +Overview of the event subsystem +Adrian Chadd <adrian@creative.net.au> + +$Id$ + +One of the things that immediately struck me whilst first looking at the +code was that the ircd periodically scheduled things in io_loop() but +it did them manually. This is very wasteful and very tedious. + +Therefore, an event system was added to hybrid. src/event.c contains an +event system ported from the squid web cache. It is pretty self contained, +and only a few things (debugging, time resolution) needed changing. + +An event is scheduled through eventAdd() or eventAddIsh() : + +eventAdd(const char *name, EVH * func, void *arg, time_t when, int weight) +eventAddIsh(const char *name, EVH * func, void *arg, time_t delta_ish, + int weight) + +after 'when' (or delta_ish) seconds has elapsed from the time the above +functions are called, the 'func' is called with the given data 'arg'. The +event is then deleted. + +To delete an event, use eventDelete() : + +eventDelete(EVH * func, void *arg) + +An event is identified by its callback function and data pair. + +Events are run through eventRun(). This is designed to be called *BEFORE* +your IO handlers, to let events scheduled immediately (ie a time of 0) +to initiate IO before the IO handlers are called. + +(Believe me, its useful.) + + + +Example: + +Say you have something which must be called every 15 seconds. + +* You would first define the callback in your module: + +static EVH foo_periodic_event; +static int initialised = 0; + +* You would then add the event in your initialization function: + +void foo_init(void) +{ + if (!initialised) { + eventAdd("foo_periodic_event", foo_periodic_event, NULL, 0, 0); + initialised = 1; + } +} + + This will force the event to be called the next time eventRun() is called, + rather than waiting 15 seconds. + +* You then define your event callback: + +static void +foo_periodic_event(void *data) +{ + /* We'd do our work here */ + + /* Then we'd finish */ + eventAdd("foo_periodic_event", foo_periodic_event, NULL, 15, 0); +} + + +Notes: + +* I really should change the timeout value to be in milliseconds. Squid used + a double, but Dianora had something against floating point code in the main + loop (which is understandable). If someone wants a fun task .. :-) + +* Note that the 'name' parameter to eventAdd() / eventAddIsh() is a const + char *, and is *not copied* but *referenced*. Therefore, it is in your + best interest to use string constants. + +* /stats E for an oper shows pending events. Thanks Diane! diff --git a/doc/technical/fd-management.txt b/doc/technical/fd-management.txt new file mode 100644 index 0000000..cb98e3f --- /dev/null +++ b/doc/technical/fd-management.txt @@ -0,0 +1,47 @@ +Overview of the filedescriptor subsystem +Adrian Chadd <adrian@creative.net.au> + +$Id$ + + +Filedescriptor lists +-------------------- + +The filedescriptor list is managed through the routines in fdlist.c . +These include: + +fd_open() - tag an FD as "open" and active +fd_close() - tag an FD as "closed" and close() the filedescriptor +fd_note() - update the filedescriptor tag + +You can get the current list of open filedescriptors through /stats F as +an oper. + + + +FD lists +-------- + +The FD list support is very alpha. There are a few lists defined: + +typedef enum fdlist_t { + FDLIST_NONE, + FDLIST_SERVICE, + FDLIST_SERVER, + FDLIST_IDLECLIENT, + FDLIST_BUSYCLIENT, + FDLIST_MAX +} fdlist_t; + +FDLIST_NONE Not on any list (ie close()d) +FDLIST_SERVICE A service - listen() sockets, resolver, etc +FDLIST_SERVER Server connections +FDLIST_IDLECLIENT An idle client +FDLIST_BUSYCLIENT A busy client +FDLIST_MAX Used for bounds checking + +The idea is that the SERVICE sockets need polling frequently, the SERVER +sockets also need polling frequently, BUSYCLIENT is for busy clients +which need frequent polling (eg we're trying to write to them), and +IDLECLIENT is for clients which we don't need to poll frequently. +THIS hasn't been decided upon yet. diff --git a/doc/technical/hostmask.txt b/doc/technical/hostmask.txt new file mode 100644 index 0000000..892bc93 --- /dev/null +++ b/doc/technical/hostmask.txt @@ -0,0 +1,136 @@ +The Hostmask and Netmask System +Copyright(c) 2001 by Andrew Miller(A1kmm)<a1kmm@mware.virtualave.net> + +$Id$ +------------------------------------------------------------------------ + +Contents :: +============ +* Section 1: Motivation +* Section 2: Underlying Mechanism + - 2.1: General Overview + - 2.2: IPv4 Netmasks + - 2.3: IPv6 Netmasks + - 2.4: Hostmasks +* Section 3: Exposed Abstraction Layer + - 3.1: Parsing Masks + - 3.2: Adding Configuration Items + - 3.3: Initialising or Rehashing + - 3.4: Finding IP/Hostname Confs + - 3.5: Deleting Entries + - 3.6: Reporting Entries + +Section 1: Motivation +===================== + +Looking up configuration hostnames and IP addresses (such as for I-Lines +and K-Lines) needs to be implemented efficiently. It turns out a hash +based algorithm like that employed here performs very will on the average +case, which is what we should be the most concerned about. A profiling +comparison with the mtre code using data from a real network confirmed +that this algorithm performs much better. + + +Section 2: Underlying Mechanism +=============================== + +2.1: General Overview +--------------------- + +In short, a hash-table with linked lists for buckets is used to locate +the correct hostname/netmask entries. In order to support CIDR IPs and +wildcard masks, the entire key cannot be hashed, and there is a need to +rehash. The means for deciding how much to hash differs between the +hostmasks and IPv4/6 netmasks. + +2.2: IPv4 Netmasks +------------------ + +In order to hash IPv4 netmasks for addition to the hash, the mask is first +processed into a 32-bit address and a number of bits is used. All unused +bits are set to 0. The mask could be in these forms: + +1.2.3.4 => 1.2.3.4 : 32 +1.2.3.* => 1.2.3.0 : 24 +1.2.*.* => 1.2.0.0 : 16 +1.2.3.64/26 => 1.2.3.64 : 26 + +The number of whole bytes is then calculated, and only those bytes are +hashed (e.g. 1.2.3.64/26 and 1.2.3.0/24 hash the same). When a complete +IPv4 address is given so that an IPv4 match can be found the entire IP +address is first hashed, and then looked up in the table. Then the most +significant three bytes are hashed, followed by the most significant two, +the most significant one, and finally the "identity hash" bucket is +searched (to match masks like 192/7). + +2.3: IPv6 Netmasks +------------------ + +As per the IPv4 netmasks, except that instead of rehashing with one byte +granularity, a 16-bit (two byte) granularity is used, as 16 rehashes is +considered too great a fixed offset to be justified for a (possible) +slight reduction in hash collisions. + +2.4: Hostmasks +-------------- + +On adding a hostmask to the hash, all of the hostmask right of the next +dot after the last wildcard character in the string is hashed, or in the +case that there are no wildcards in the hostmask, the entire string is +hashed. + +On searching for a hostmask match, the entire hostname is hashed, followed +by the entire hostmask after the first dot, followed by the entire hostmask +after the second dot, and so on. Finally the "identity hash" bucket is checked +to catch hostnames like *test*. + +Section 3: Exposed Abstraction Layer +==================================== + +Section 3.1: Parsing Masks +-------------------------- + +Call "parse_netmask()" with the netmask and a pointer to an irc_inaddr +structure to be filled in, as well as a pointer to an integer where the +number of bits will be placed. + +Always check the return value, if it returns HM_MOST, it means that the +mask is probably a hostmask. If it returns HM_IPV4, it means it was an +IPv4 address. If it returns HM_IPV6, it means it was an IPv6 address. +If parse_netmask() returns HM_MOST however, no change is made to the +irc_inaddr structure or the number of bits. + +Section 3.2: Adding Configuration Items +--------------------------------------- + +Call "add_conf_by_address()" with the hostname or IP mask, the username, +and the ConfItem* to associate with this mask. + +Section 3.3: Initialising and Rehashing +--------------------------------------- + +To initialise, call "init_host_hash()". This only needs to be done once +on start-up. On rehash, to wipe out the old unwanted configuration, and +free them if there are no references to them, call +"clear_out_address_conf()". + +Section 3.4: Finding IP/Hostname Confs +--------------------------------------- + +Call "find_address_conf()" with the hostname, the username, the address, +the address family and the client-supplied password. To find a D-Line, +call "find_dline()" with the address and address family. + +Section 3.5: Deleted Entries +---------------------------- + +Call "delete_one_address_conf()" with the hostname and the ConfItem*. + +Section 3.6: Reporting Entries +------------------------------ + +Call "report_dlines()", "report_exemptlines()", "report_Klines()", or +"report_Ilines()" with the client pointer to report to. Note these walk +the hash, which is inefficient, but these are not called often enough +to justify the memory and maintenance clockcycles to for more efficient +data structuring. diff --git a/doc/technical/index.txt b/doc/technical/index.txt new file mode 100644 index 0000000..32577e9 --- /dev/null +++ b/doc/technical/index.txt @@ -0,0 +1,16 @@ +$Id$ +----------------------------------------------- + +Technical Documentation for ircd-hybrid-8 + +event.txt - Outline of the event system +fd-management.txt - Outline of the file descriptor management system +hostmask.txt - Outline of hostmask handling +network.txt - Outline of the network traffic subsystem +rfc1459.txt - The IRC RFC +rfc2812.txt - The IRC Client RFC +rfc2813.txt - The IRC Server RFC +send.txt - Document on all of the send_to functions +ts3.txt - TSora Version 3 Protocol +ts5.txt - TSora Version 5 Protocol +ts6.txt - TSora Version 6 Protocol diff --git a/doc/technical/network.txt b/doc/technical/network.txt new file mode 100644 index 0000000..520adc0 --- /dev/null +++ b/doc/technical/network.txt @@ -0,0 +1,99 @@ +Overview of the network subsystem +Adrian Chadd <adrian@creative.net.au> + +$Id$ + +This document is an overview of the new and hopefully improved network +subsystem. + +The code is based loosely upon the network core found in the Squid web cache +server, with some optimizations for ircd-specific IO patterns. + +Filedescriptor IO +----------------- + +Filedescriptor IO is initiated using comm_setselect(). comm_setselect() +registers interest in reading from or writing to a file descriptor. +When a filedescriptor is ready for the required IO a callback is called +from the IO loop. + +The comm_setselect() usage is: + +void +comm_setselect(int fd, fdlist_t list, int type, PF *callback, void *cbdata, + int timeout) + +where: + fd filedescriptor + list Which list the FD should be put on + type IO type. Can currently include: + COMM_SELECT_READ - register for read + COMM_SELECT_WRITE - register for write + callback Function to call when the FD is ready + cbdata Data to be passed to above function + timeout Update the timeout value. 0 is "don't update". + + +A typical use is: + +.. + +/* Register interest in the FD for a read event */ +comm_setselect(fd, FDLIST_SERVICE, COMM_SELECT_READ, read_callback, read_data, + 0); + +.. + +(FD becomes ready for read in the IO loop) + +void +read_callback(int fd, void *data) +{ + /* called when the FD becomes ready for read */ + retval = read(fd, buf, len); + + .. + /* Ok, we need to read some more when its ready */ + comm_setselect(fd, FDLIST_SERVICE, COMM_SELECT_READ, read_callback, data, + 0); +} + +Socket timeouts +--------------- + +A "socket timeout" is a callback registered to be called when a certain +amount of time has elapsed. Think of it as an event, but against a FD. + +A good example of socket timeouts is in the comm_connect_tcp() code. +When the connect() begins, comm_settimeout() is called to call +comm_connect_timeout() if the timeout occurs. Once the connect() completes, +comm_settimeout() is called with a timeout of 0 and callback of NULL +to deregister the timeout. If the timeout occurs, comm_connect_timeout() +is called and the connection attempt is aborted. + + + + +Functions +--------- + +comm_open() - a socket() wrapper, enforcing fd limitations and tagging the + file descriptor with a note + +comm_accept() - an accept() wrapper, enforcing fd limitations and tagging + the file descriptor with a note + +comm_connect_tcp() - attempt an async connect(). Handles DNS lookups if + required, and will call the given callback at completion or error + +comm_settimeout() - set a callback to be called after a given time period. + This is good to implement things like PING checks and connect() timeouts. + +Notes: + +* All socket creation should go through comm_open() / comm_accept(). +* All socket closing should go through fd_close(). comm_close() isn't + implemented yet. +* comm_connect_tcp() is your best friend. :-) +* *ALL* network sockets should be non-blocking. If your OS doesn't support + non-blocking sockets, you shouldn't be here. diff --git a/doc/technical/rfc1459.txt b/doc/technical/rfc1459.txt new file mode 100644 index 0000000..768e176 --- /dev/null +++ b/doc/technical/rfc1459.txt @@ -0,0 +1,3110 @@ +$Id$ + +Network Working Group J. Oikarinen +Request for Comments: 1459 D. Reed + May 1993 + + Internet Relay Chat Protocol + +Status of This Memo + + This memo defines an Experimental Protocol for the Internet + community. Discussion and suggestions for improvement are requested. + Please refer to the current edition of the "IAB Official Protocol + Standards" for the standardization state and status of this protocol. + Distribution of this memo is unlimited. + +Abstract + + The IRC protocol was developed over the last 4 years since it was + first implemented as a means for users on a BBS to chat amongst + themselves. Now it supports a world-wide network of servers and + clients, and is stringing to cope with growth. Over the past 2 years, + the average number of users connected to the main IRC network has + grown by a factor of 10. + + The IRC protocol is a text-based protocol, with the simplest client + being any socket program capable of connecting to the server. + +Table of Contents + + 1. INTRODUCTION ............................................... 4 + 1.1 Servers ................................................ 4 + 1.2 Clients ................................................ 5 + 1.2.1 Operators .......................................... 5 + 1.3 Channels ................................................ 5 + 1.3.1 Channel Operators .................................... 6 + 2. THE IRC SPECIFICATION ....................................... 7 + 2.1 Overview ................................................ 7 + 2.2 Character codes ......................................... 7 + 2.3 Messages ................................................ 7 + 2.3.1 Message format in 'pseudo' BNF .................... 8 + 2.4 Numeric replies ......................................... 10 + 3. IRC Concepts ................................................ 10 + 3.1 One-to-one communication ................................ 10 + 3.2 One-to-many ............................................. 11 + 3.2.1 To a list .......................................... 11 + 3.2.2 To a group (channel) ............................... 11 + 3.2.3 To a host/server mask .............................. 12 + 3.3 One to all .............................................. 12 + + 3.3.1 Client to Client ................................... 12 + 3.3.2 Clients to Server .................................. 12 + 3.3.3 Server to Server ................................... 12 + 4. MESSAGE DETAILS ............................................. 13 + 4.1 Connection Registration ................................. 13 + 4.1.1 Password message ................................... 14 + 4.1.2 Nickname message ................................... 14 + 4.1.3 User message ....................................... 15 + 4.1.4 Server message ..................................... 16 + 4.1.5 Operator message ................................... 17 + 4.1.6 Quit message ....................................... 17 + 4.1.7 Server Quit message ................................ 18 + 4.2 Channel operations ...................................... 19 + 4.2.1 Join message ....................................... 19 + 4.2.2 Part message ....................................... 20 + 4.2.3 Mode message ....................................... 21 + 4.2.3.1 Channel modes ................................. 21 + 4.2.3.2 User modes .................................... 22 + 4.2.4 Topic message ...................................... 23 + 4.2.5 Names message ...................................... 24 + 4.2.6 List message ....................................... 24 + 4.2.7 Invite message ..................................... 25 + 4.2.8 Kick message ....................................... 25 + 4.3 Server queries and commands ............................. 26 + 4.3.1 Version message .................................... 26 + 4.3.2 Stats message ...................................... 27 + 4.3.3 Links message ...................................... 28 + 4.3.4 Time message ....................................... 29 + 4.3.5 Connect message .................................... 29 + 4.3.6 Trace message ...................................... 30 + 4.3.7 Admin message ...................................... 31 + 4.3.8 Info message ....................................... 31 + 4.4 Sending messages ........................................ 32 + 4.4.1 Private messages ................................... 32 + 4.4.2 Notice messages .................................... 33 + 4.5 User-based queries ...................................... 33 + 4.5.1 Who query .......................................... 33 + 4.5.2 Whois query ........................................ 34 + 4.5.3 Whowas message ..................................... 35 + 4.6 Miscellaneous messages .................................. 35 + 4.6.1 Kill message ....................................... 36 + 4.6.2 Ping message ....................................... 37 + 4.6.3 Pong message ....................................... 37 + 4.6.4 Error message ...................................... 38 + 5. OPTIONAL MESSAGES ........................................... 38 + 5.1 Away message ............................................ 38 + 5.2 Rehash command .......................................... 39 + 5.3 Restart command ......................................... 39 + + 5.4 Summon message .......................................... 40 + 5.5 Users message ........................................... 40 + 5.6 Operwall command ........................................ 41 + 5.7 Userhost message ........................................ 42 + 5.8 Ison message ............................................ 42 + 6. REPLIES ..................................................... 43 + 6.1 Error Replies ........................................... 43 + 6.2 Command responses ....................................... 48 + 6.3 Reserved numerics ....................................... 56 + 7. Client and server authentication ............................ 56 + 8. Current Implementations Details ............................. 56 + 8.1 Network protocol: TCP ................................... 57 + 8.1.1 Support of Unix sockets ............................ 57 + 8.2 Command Parsing ......................................... 57 + 8.3 Message delivery ........................................ 57 + 8.4 Connection 'Liveness' ................................... 58 + 8.5 Establishing a server-client connection ................. 58 + 8.6 Establishing a server-server connection ................. 58 + 8.6.1 State information exchange when connecting ......... 59 + 8.7 Terminating server-client connections ................... 59 + 8.8 Terminating server-server connections ................... 59 + 8.9 Tracking nickname changes ............................... 60 + 8.10 Flood control of clients ............................... 60 + 8.11 Non-blocking lookups ................................... 61 + 8.11.1 Hostname (DNS) lookups ............................ 61 + 8.11.2 Username (Ident) lookups .......................... 61 + 8.12 Configuration file ..................................... 61 + 8.12.1 Allowing clients to connect ....................... 62 + 8.12.2 Operators ......................................... 62 + 8.12.3 Allowing servers to connect ....................... 62 + 8.12.4 Administrivia ..................................... 63 + 8.13 Channel membership ..................................... 63 + 9. Current problems ............................................ 63 + 9.1 Scalability ............................................. 63 + 9.2 Labels .................................................. 63 + 9.2.1 Nicknames .......................................... 63 + 9.2.2 Channels ........................................... 64 + 9.2.3 Servers ............................................ 64 + 9.3 Algorithms .............................................. 64 + 10. Support and availability ................................... 64 + 11. Security Considerations .................................... 65 + 12. Authors' Addresses ......................................... 65 + +1. INTRODUCTION + + The IRC (Internet Relay Chat) protocol has been designed over a + number of years for use with text based conferencing. This document + describes the current IRC protocol. + + The IRC protocol has been developed on systems using the TCP/IP + network protocol, although there is no requirement that this remain + the only sphere in which it operates. + + IRC itself is a teleconferencing system, which (through the use of + the client-server model) is well-suited to running on many machines + in a distributed fashion. A typical setup involves a single process + (the server) forming a central point for clients (or other servers) + to connect to, performing the required message delivery/multiplexing + and other functions. + +1.1 Servers + + The server forms the backbone of IRC, providing a point to which + clients may connect to to talk to each other, and a point for other + servers to connect to, forming an IRC network. The only network + configuration allowed for IRC servers is that of a spanning tree [see + Fig. 1] where each server acts as a central node for the rest of the + net it sees. + + [ Server 15 ] [ Server 13 ] [ Server 14] + / \ / + / \ / + [ Server 11 ] ------ [ Server 1 ] [ Server 12] + / \ / + / \ / + [ Server 2 ] [ Server 3 ] + / \ \ + / \ \ + [ Server 4 ] [ Server 5 ] [ Server 6 ] + / | \ / + / | \ / + / | \____ / + / | \ / + [ Server 7 ] [ Server 8 ] [ Server 9 ] [ Server 10 ] + + : + [ etc. ] + : + + [ Fig. 1. Format of IRC server network ] + +1.2 Clients + + A client is anything connecting to a server that is not another + server. Each client is distinguished from other clients by a unique + nickname having a maximum length of nine (9) characters. See the + protocol grammar rules for what may and may not be used in a + nickname. In addition to the nickname, all servers must have the + following information about all clients: the real name of the host + that the client is running on, the username of the client on that + host, and the server to which the client is connected. + +1.2.1 Operators + + To allow a reasonable amount of order to be kept within the IRC + network, a special class of clients (operators) is allowed to perform + general maintenance functions on the network. Although the powers + granted to an operator can be considered as 'dangerous', they are + nonetheless required. Operators should be able to perform basic + network tasks such as disconnecting and reconnecting servers as + needed to prevent long-term use of bad network routing. In + recognition of this need, the protocol discussed herein provides for + operators only to be able to perform such functions. See sections + 4.1.7 (SQUIT) and 4.3.5 (CONNECT). + + A more controversial power of operators is the ability to remove a + user from the connected network by 'force', i.e. operators are able + to close the connection between any client and server. The + justification for this is delicate since its abuse is both + destructive and annoying. For further details on this type of + action, see section 4.6.1 (KILL). + +1.3 Channels + + A channel is a named group of one or more clients which will all + receive messages addressed to that channel. The channel is created + implicitly when the first client joins it, and the channel ceases to + exist when the last client leaves it. While channel exists, any + client can reference the channel using the name of the channel. + + Channels names are strings (beginning with a '&' or '#' character) of + length up to 200 characters. Apart from the the requirement that the + first character being either '&' or '#'; the only restriction on a + channel name is that it may not contain any spaces (' '), a control G + (^G or ASCII 7), or a comma (',' which is used as a list item + separator by the protocol). + + There are two types of channels allowed by this protocol. One is a + distributed channel which is known to all the servers that are + + connected to the network. These channels are marked by the first + character being a only clients on the server where it exists may join + it. These are distinguished by a leading '&' character. On top of + these two types, there are the various channel modes available to + alter the characteristics of individual channels. See section 4.2.3 + (MODE command) for more details on this. + + To create a new channel or become part of an existing channel, a user + is required to JOIN the channel. If the channel doesn't exist prior + to joining, the channel is created and the creating user becomes a + channel operator. If the channel already exists, whether or not your + request to JOIN that channel is honoured depends on the current modes + of the channel. For example, if the channel is invite-only, (+i), + then you may only join if invited. As part of the protocol, a user + may be a part of several channels at once, but a limit of ten (10) + channels is recommended as being ample for both experienced and + novice users. See section 8.13 for more information on this. + + If the IRC network becomes disjoint because of a split between two + servers, the channel on each side is only composed of those clients + which are connected to servers on the respective sides of the split, + possibly ceasing to exist on one side of the split. When the split + is healed, the connecting servers announce to each other who they + think is in each channel and the mode of that channel. If the + channel exists on both sides, the JOINs and MODEs are interpreted in + an inclusive manner so that both sides of the new connection will + agree about which clients are in the channel and what modes the + channel has. + +1.3.1 Channel Operators + + The channel operator (also referred to as a "chop" or "chanop") on a + given channel is considered to 'own' that channel. In recognition of + this status, channel operators are endowed with certain powers which + enable them to keep control and some sort of sanity in their channel. + As an owner of a channel, a channel operator is not required to have + reasons for their actions, although if their actions are generally + antisocial or otherwise abusive, it might be reasonable to ask an IRC + operator to intervene, or for the usersjust leave and go elsewhere + and form their own channel. + + The commands which may only be used by channel operators are: + + KICK - Eject a client from the channel + MODE - Change the channel's mode + INVITE - Invite a client to an invite-only channel (mode +i) + TOPIC - Change the channel topic in a mode +t channel + + A channel operator is identified by the '@' symbol next to their + nickname whenever it is associated with a channel (ie replies to the + NAMES, WHO and WHOIS commands). + +2. The IRC Specification + +2.1 Overview + + The protocol as described herein is for use both with server to + server and client to server connections. There are, however, more + restrictions on client connections (which are considered to be + untrustworthy) than on server connections. + +2.2 Character codes + + No specific character set is specified. The protocol is based on a a + set of codes which are composed of eight (8) bits, making up an + octet. Each message may be composed of any number of these octets; + however, some octet values are used for control codes which act as + message delimiters. + + Regardless of being an 8-bit protocol, the delimiters and keywords + are such that protocol is mostly usable from USASCII terminal and a + telnet connection. + + Because of IRC's scandanavian origin, the characters {}| are + considered to be the lower case equivalents of the characters []\, + respectively. This is a critical issue when determining the + equivalence of two nicknames. + +2.3 Messages + + Servers and clients send eachother messages which may or may not + generate a reply. If the message contains a valid command, as + described in later sections, the client should expect a reply as + specified but it is not advised to wait forever for the reply; client + to server and server to server communication is essentially + asynchronous in nature. + + Each IRC message may consist of up to three main parts: the prefix + (optional), the command, and the command parameters (of which there + may be up to 15). The prefix, command, and all parameters are + separated by one (or more) ASCII space character(s) (0x20). + + The presence of a prefix is indicated with a single leading ASCII + colon character (':', 0x3b), which must be the first character of the + message itself. There must be no gap (whitespace) between the colon + and the prefix. The prefix is used by servers to indicate the true + + origin of the message. If the prefix is missing from the message, it + is assumed to have originated from the connection from which it was + received. Clients should not use prefix when sending a message from + themselves; if they use a prefix, the only valid prefix is the + registered nickname associated with the client. If the source + identified by the prefix cannot be found from the server's internal + database, or if the source is registered from a different link than + from which the message arrived, the server must ignore the message + silently. + + The command must either be a valid IRC command or a three (3) digit + number represented in ASCII text. + + IRC messages are always lines of characters terminated with a CR-LF + (Carriage Return - Line Feed) pair, and these messages shall not + exceed 512 characters in length, counting all characters including + the trailing CR-LF. Thus, there are 510 characters maximum allowed + for the command and its parameters. There is no provision for + continuation message lines. See section 7 for more details about + current implementations. + +2.3.1 Message format in 'pseudo' BNF + + The protocol messages must be extracted from the contiguous stream of + octets. The current solution is to designate two characters, CR and + LF, as message separators. Empty messages are silently ignored, + which permits use of the sequence CR-LF between messages + without extra problems. + + The extracted message is parsed into the components <prefix>, + <command> and list of parameters matched either by <middle> or + <trailing> components. + + The BNF representation for this is: + +<message> ::= [':' <prefix> <SPACE> ] <command> <params> <crlf> +<prefix> ::= <servername> | <nick> [ '!' <user> ] [ '@' <host> ] +<command> ::= <letter> { <letter> } | <number> <number> <number> +<SPACE> ::= ' ' { ' ' } +<params> ::= <SPACE> [ ':' <trailing> | <middle> <params> ] + +<middle> ::= <Any *non-empty* sequence of octets not including SPACE + or NUL or CR or LF, the first of which may not be ':'> +<trailing> ::= <Any, possibly *empty*, sequence of octets not including + NUL or CR or LF> + +<crlf> ::= CR LF + +NOTES: + + 1) <SPACE> is consists only of SPACE character(s) (0x20). + Specially notice that TABULATION, and all other control + characters are considered NON-WHITE-SPACE. + + 2) After extracting the parameter list, all parameters are equal, + whether matched by <middle> or <trailing>. <Trailing> is just + a syntactic trick to allow SPACE within parameter. + + 3) The fact that CR and LF cannot appear in parameter strings is + just artifact of the message framing. This might change later. + + 4) The NUL character is not special in message framing, and + basically could end up inside a parameter, but as it would + cause extra complexities in normal C string handling. Therefore + NUL is not allowed within messages. + + 5) The last parameter may be an empty string. + + 6) Use of the extended prefix (['!' <user> ] ['@' <host> ]) must + not be used in server to server communications and is only + intended for server to client messages in order to provide + clients with more useful information about who a message is + from without the need for additional queries. + + Most protocol messages specify additional semantics and syntax for + the extracted parameter strings dictated by their position in the + list. For example, many server commands will assume that the first + parameter after the command is the list of targets, which can be + described with: + + <target> ::= <to> [ "," <target> ] + <to> ::= <channel> | <user> '@' <servername> | <nick> | <mask> + <channel> ::= ('#' | '&') <chstring> + <servername> ::= <host> + <host> ::= see RFC 952 [DNS:4] for details on allowed hostnames + <nick> ::= <letter> { <letter> | <number> | <special> } + <mask> ::= ('#' | '$') <chstring> + <chstring> ::= <any 8bit code except SPACE, BELL, NUL, CR, LF and + comma (',')> + + Other parameter syntaxes are: + + <user> ::= <nonwhite> { <nonwhite> } + <letter> ::= 'a' ... 'z' | 'A' ... 'Z' + <number> ::= '0' ... '9' + <special> ::= '-' | '[' | ']' | '\' | '`' | '^' | '{' | '}' + + <nonwhite> ::= <any 8bit code except SPACE (0x20), NUL (0x0), CR + (0xd), and LF (0xa)> + +2.4 Numeric replies + + Most of the messages sent to the server generate a reply of some + sort. The most common reply is the numeric reply, used for both + errors and normal replies. The numeric reply must be sent as one + message consisting of the sender prefix, the three digit numeric, and + the target of the reply. A numeric reply is not allowed to originate + from a client; any such messages received by a server are silently + dropped. In all other respects, a numeric reply is just like a normal + message, except that the keyword is made up of 3 numeric digits + rather than a string of letters. A list of different replies is + supplied in section 6. + +3. IRC Concepts. + + This section is devoted to describing the actual concepts behind the + organization of the IRC protocol and how the current + implementations deliver different classes of messages. + + 1--\ + A D---4 + 2--/ \ / + B----C + / \ + 3 E + + Servers: A, B, C, D, E Clients: 1, 2, 3, 4 + + [ Fig. 2. Sample small IRC network ] + +3.1 One-to-one communication + + Communication on a one-to-one basis is usually only performed by + clients, since most server-server traffic is not a result of servers + talking only to each other. To provide a secure means for clients to + talk to each other, it is required that all servers be able to send a + message in exactly one direction along the spanning tree in order to + reach any client. The path of a message being delivered is the + shortest path between any two points on the spanning tree. + + The following examples all refer to Figure 2 above. + +Example 1: + A message between clients 1 and 2 is only seen by server A, which + sends it straight to client 2. + +Example 2: + A message between clients 1 and 3 is seen by servers A & B, and + client 3. No other clients or servers are allowed see the message. + +Example 3: + A message between clients 2 and 4 is seen by servers A, B, C & D + and client 4 only. + +3.2 One-to-many + + The main goal of IRC is to provide a forum which allows easy and + efficient conferencing (one to many conversations). IRC offers + several means to achieve this, each serving its own purpose. + +3.2.1 To a list + + The least efficient style of one-to-many conversation is through + clients talking to a 'list' of users. How this is done is almost + self explanatory: the client gives a list of destinations to which + the message is to be delivered and the server breaks it up and + dispatches a separate copy of the message to each given destination. + This isn't as efficient as using a group since the destination list + is broken up and the dispatch sent without checking to make sure + duplicates aren't sent down each path. + +3.2.2 To a group (channel) + + In IRC the channel has a role equivalent to that of the multicast + group; their existence is dynamic (coming and going as people join + and leave channels) and the actual conversation carried out on a + channel is only sent to servers which are supporting users on a given + channel. If there are multiple users on a server in the same + channel, the message text is sent only once to that server and then + sent to each client on the channel. This action is then repeated for + each client-server combination until the original message has fanned + out and reached each member of the channel. + + The following examples all refer to Figure 2. + +Example 4: + Any channel with 1 client in it. Messages to the channel go to the + server and then nowhere else. + +Example 5: + 2 clients in a channel. All messages traverse a path as if they + were private messages between the two clients outside a channel. + +Example 6: + Clients 1, 2 and 3 in a channel. All messages to the channel are + sent to all clients and only those servers which must be traversed + by the message if it were a private message to a single client. If + client 1 sends a message, it goes back to client 2 and then via + server B to client 3. + +3.2.3 To a host/server mask + + To provide IRC operators with some mechanism to send messages to a + large body of related users, host and server mask messages are + provided. These messages are sent to users whose host or server + information match that of the mask. The messages are only sent to + locations where users are, in a fashion similar to that of channels. + +3.3 One-to-all + + The one-to-all type of message is better described as a broadcast + message, sent to all clients or servers or both. On a large network + of users and servers, a single message can result in a lot of traffic + being sent over the network in an effort to reach all of the desired + destinations. + + For some messages, there is no option but to broadcast it to all + servers so that the state information held by each server is + reasonably consistent between servers. + +3.3.1 Client-to-Client + + There is no class of message which, from a single message, results in + a message being sent to every other client. + +3.3.2 Client-to-Server + + Most of the commands which result in a change of state information + (such as channel membership, channel mode, user status, etc) must be + sent to all servers by default, and this distribution may not be + changed by the client. + +3.3.3 Server-to-Server. + + While most messages between servers are distributed to all 'other' + servers, this is only required for any message that affects either a + user, channel or server. Since these are the basic items found in + + IRC, nearly all messages originating from a server are broadcast to + all other connected servers. + +4. Message details + + On the following pages are descriptions of each message recognized by + the IRC server and client. All commands described in this section + must be implemented by any server for this protocol. + + Where the reply ERR_NOSUCHSERVER is listed, it means that the + <server> parameter could not be found. The server must not send any + other replies after this for that command. + + The server to which a client is connected is required to parse the + complete message, returning any appropriate errors. If the server + encounters a fatal error while parsing a message, an error must be + sent back to the client and the parsing terminated. A fatal error + may be considered to be incorrect command, a destination which is + otherwise unknown to the server (server, nick or channel names fit + this category), not enough parameters or incorrect privileges. + + If a full set of parameters is presented, then each must be checked + for validity and appropriate responses sent back to the client. In + the case of messages which use parameter lists using the comma as an + item separator, a reply must be sent for each item. + + In the examples below, some messages appear using the full format: + + :Name COMMAND parameter list + + Such examples represent a message from "Name" in transit between + servers, where it is essential to include the name of the original + sender of the message so remote servers may send back a reply along + the correct path. + +4.1 Connection Registration + + The commands described here are used to register a connection with an + IRC server as either a user or a server as well as correctly + disconnect. + + A "PASS" command is not required for either client or server + connection to be registered, but it must precede the server message + or the latter of the NICK/USER combination. It is strongly + recommended that all server connections have a password in order to + give some level of security to the actual connections. The + recommended order for a client to register is as follows: + + 1. Pass message + 2. Nick message + 3. User message + +4.1.1 Password message + + Command: PASS + Parameters: <password> + + The PASS command is used to set a 'connection password'. The + password can and must be set before any attempt to register the + connection is made. Currently this requires that clients send a PASS + command before sending the NICK/USER combination and servers *must* + send a PASS command before any SERVER command. The password supplied + must match the one contained in the C/N lines (for servers) or I + lines (for clients). It is possible to send multiple PASS commands + before registering but only the last one sent is used for + verification and it may not be changed once registered. Numeric + Replies: + + ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED + + Example: + + PASS secretpasswordhere + +4.1.2 Nick message + + Command: NICK + Parameters: <nickname> [ <hopcount> ] + + NICK message is used to give user a nickname or change the previous + one. The <hopcount> parameter is only used by servers to indicate + how far away a nick is from its home server. A local connection has + a hopcount of 0. If supplied by a client, it must be ignored. + + If a NICK message arrives at a server which already knows about an + identical nickname for another client, a nickname collision occurs. + As a result of a nickname collision, all instances of the nickname + are removed from the server's database, and a KILL command is issued + to remove the nickname from all other server's database. If the NICK + message causing the collision was a nickname change, then the + original (old) nick must be removed as well. + + If the server recieves an identical NICK from a client which is + directly connected, it may issue an ERR_NICKCOLLISION to the local + client, drop the NICK command, and not generate any kills. + + Numeric Replies: + + ERR_NONICKNAMEGIVEN ERR_ERRONEUSNICKNAME + ERR_NICKNAMEINUSE ERR_NICKCOLLISION + + Example: + + NICK Wiz ; Introducing new nick "Wiz". + + :WiZ NICK Kilroy ; WiZ changed his nickname to Kilroy. + +4.1.3 User message + + Command: USER + Parameters: <username> <hostname> <servername> <realname> + + The USER message is used at the beginning of connection to specify + the username, hostname, servername and realname of s new user. It is + also used in communication between servers to indicate new user + arriving on IRC, since only after both USER and NICK have been + received from a client does a user become registered. + + Between servers USER must to be prefixed with client's NICKname. + Note that hostname and servername are normally ignored by the IRC + server when the USER command comes from a directly connected client + (for security reasons), but they are used in server to server + communication. This means that a NICK must always be sent to a + remote server when a new user is being introduced to the rest of the + network before the accompanying USER is sent. + + It must be noted that realname parameter must be the last parameter, + because it may contain space characters and must be prefixed with a + colon (':') to make sure this is recognised as such. + + Since it is easy for a client to lie about its username by relying + solely on the USER message, the use of an "Identity Server" is + recommended. If the host which a user connects from has such a + server enabled the username is set to that as in the reply from the + "Identity Server". + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED + + Examples: + + USER guest tolmoon tolsun :Ronnie Reagan + + ; User registering themselves with a + username of "guest" and real name + "Ronnie Reagan". + + :testnick USER guest tolmoon tolsun :Ronnie Reagan + ; message between servers with the + nickname for which the USER command + belongs to + +4.1.4 Server message + + Command: SERVER + Parameters: <servername> <hopcount> <info> + + The server message is used to tell a server that the other end of a + new connection is a server. This message is also used to pass server + data over whole net. When a new server is connected to net, + information about it be broadcast to the whole network. <hopcount> + is used to give all servers some internal information on how far away + all servers are. With a full server list, it would be possible to + construct a map of the entire server tree, but hostmasks prevent this + from being done. + + The SERVER message must only be accepted from either (a) a connection + which is yet to be registered and is attempting to register as a + server, or (b) an existing connection to another server, in which + case the SERVER message is introducing a new server behind that + server. + + Most errors that occur with the receipt of a SERVER command result in + the connection being terminated by the destination host (target + SERVER). Error replies are usually sent using the "ERROR" command + rather than the numeric since the ERROR command has several useful + properties which make it useful here. + + If a SERVER message is parsed and attempts to introduce a server + which is already known to the receiving server, the connection from + which that message must be closed (following the correct procedures), + since a duplicate route to a server has formed and the acyclic nature + of the IRC tree broken. + + Numeric Replies: + + ERR_ALREADYREGISTRED + + Example: + +SERVER test.oulu.fi 1 :[tolsun.oulu.fi] Experimental server + ; New server test.oulu.fi introducing + itself and attempting to register. The + name in []'s is the hostname for the + host running test.oulu.fi. + +:tolsun.oulu.fi SERVER csd.bu.edu 5 :BU Central Server + ; Server tolsun.oulu.fi is our uplink + for csd.bu.edu which is 5 hops away. + +4.1.5 Oper + + Command: OPER + Parameters: <user> <password> + + OPER message is used by a normal user to obtain operator privileges. + The combination of <user> and <password> are required to gain + Operator privileges. + + If the client sending the OPER command supplies the correct password + for the given user, the server then informs the rest of the network + of the new operator by issuing a "MODE +o" for the clients nickname. + + The OPER message is client-server only. + + Numeric Replies: + + ERR_NEEDMOREPARAMS RPL_YOUREOPER + ERR_NOOPERHOST ERR_PASSWDMISMATCH + + Example: + + OPER foo bar ; Attempt to register as an operator + using a username of "foo" and "bar" as + the password. + +4.1.6 Quit + + Command: QUIT + Parameters: [<Quit message>] + + A client session is ended with a quit message. The server must close + the connection to a client which sends a QUIT message. If a "Quit + Message" is given, this will be sent instead of the default message, + the nickname. + + When netsplits (disconnecting of two servers) occur, the quit message + + is composed of the names of two servers involved, separated by a + space. The first name is that of the server which is still connected + and the second name is that of the server that has become + disconnected. + + If, for some other reason, a client connection is closed without the + client issuing a QUIT command (e.g. client dies and EOF occurs + on socket), the server is required to fill in the quit message with + some sort of message reflecting the nature of the event which + caused it to happen. + + Numeric Replies: + + None. + + Examples: + + QUIT :Gone to have lunch ; Preferred message format. + +4.1.7 Server quit message + + Command: SQUIT + Parameters: <server> <comment> + + The SQUIT message is needed to tell about quitting or dead servers. + If a server wishes to break the connection to another server it must + send a SQUIT message to the other server, using the the name of the + other server as the server parameter, which then closes its + connection to the quitting server. + + This command is also available operators to help keep a network of + IRC servers connected in an orderly fashion. Operators may also + issue an SQUIT message for a remote server connection. In this case, + the SQUIT must be parsed by each server inbetween the operator and + the remote server, updating the view of the network held by each + server as explained below. + + The <comment> should be supplied by all operators who execute a SQUIT + for a remote server (that is not connected to the server they are + currently on) so that other operators are aware for the reason of + this action. The <comment> is also filled in by servers which may + place an error or similar message here. + + Both of the servers which are on either side of the connection being + closed are required to to send out a SQUIT message (to all its other + server connections) for all other servers which are considered to be + behind that link. + + Similarly, a QUIT message must be sent to the other connected servers + rest of the network on behalf of all clients behind that link. In + addition to this, all channel members of a channel which lost a + member due to the split must be sent a QUIT message. + + If a server connection is terminated prematurely (e.g. the server on + the other end of the link died), the server which detects + this disconnection is required to inform the rest of the network + that the connection has closed and fill in the comment field + with something appropriate. + + Numeric replies: + + ERR_NOPRIVILEGES ERR_NOSUCHSERVER + + Example: + + SQUIT tolsun.oulu.fi :Bad Link ? ; the server link tolson.oulu.fi has + been terminated because of "Bad Link". + + :Trillian SQUIT cm22.eng.umd.edu :Server out of control + ; message from Trillian to disconnect + "cm22.eng.umd.edu" from the net + because "Server out of control". + +4.2 Channel operations + + This group of messages is concerned with manipulating channels, their + properties (channel modes), and their contents (typically clients). + In implementing these, a number of race conditions are inevitable + when clients at opposing ends of a network send commands which will + ultimately clash. It is also required that servers keep a nickname + history to ensure that wherever a <nick> parameter is given, the + server check its history in case it has recently been changed. + +4.2.1 Join message + + Command: JOIN + Parameters: <channel>{,<channel>} [<key>{,<key>}] + + The JOIN command is used by client to start listening a specific + channel. Whether or not a client is allowed to join a channel is + checked only by the server the client is connected to; all other + servers automatically add the user to the channel when it is received + from other servers. The conditions which affect this are as follows: + + 1. the user must be invited if the channel is invite-only; + + 2. the user's nick/username/hostname must not match any + active bans; + + 3. the correct key (password) must be given if it is set. + + These are discussed in more detail under the MODE command (see + section 4.2.3 for more details). + + Once a user has joined a channel, they receive notice about all + commands their server receives which affect the channel. This + includes MODE, KICK, PART, QUIT and of course PRIVMSG/NOTICE. The + JOIN command needs to be broadcast to all servers so that each server + knows where to find the users who are on the channel. This allows + optimal delivery of PRIVMSG/NOTICE messages to the channel. + + If a JOIN is successful, the user is then sent the channel's topic + (using RPL_TOPIC) and the list of users who are on the channel (using + RPL_NAMREPLY), which must include the user joining. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_BANNEDFROMCHAN + ERR_INVITEONLYCHAN ERR_BADCHANNELKEY + ERR_CHANNELISFULL ERR_BADCHANMASK + ERR_NOSUCHCHANNEL ERR_TOOMANYCHANNELS + RPL_TOPIC + + Examples: + + JOIN #foobar ; join channel #foobar. + + JOIN &foo fubar ; join channel &foo using key "fubar". + + JOIN #foo,&bar fubar ; join channel #foo using key "fubar" + and &bar using no key. + + JOIN #foo,#bar fubar,foobar ; join channel #foo using key "fubar". + and channel #bar using key "foobar". + + JOIN #foo,#bar ; join channels #foo and #bar. + + :WiZ JOIN #Twilight_zone ; JOIN message from WiZ + +4.2.2 Part message + + Command: PART + Parameters: <channel>{,<channel>} + + The PART message causes the client sending the message to be removed + from the list of active users for all given channels listed in the + parameter string. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL + ERR_NOTONCHANNEL + + Examples: + + PART #twilight_zone ; leave channel "#twilight_zone" + + PART #oz-ops,&group5 ; leave both channels "&group5" and + "#oz-ops". + +4.2.3 Mode message + + Command: MODE + + The MODE command is a dual-purpose command in IRC. It allows both + usernames and channels to have their mode changed. The rationale for + this choice is that one day nicknames will be obsolete and the + equivalent property will be the channel. + + When parsing MODE messages, it is recommended that the entire message + be parsed first and then the changes which resulted then passed on. + +4.2.3.1 Channel modes + + Parameters: <channel> {[+|-]|o|p|s|i|t|n|b|v} [<limit>] [<user>] + [<ban mask>] + + The MODE command is provided so that channel operators may change the + characteristics of `their' channel. It is also required that servers + be able to change channel modes so that channel operators may be + created. + + The various modes available for channels are as follows: + + o - give/take channel operator privileges; + p - private channel flag; + s - secret channel flag; + i - invite-only channel flag; + t - topic settable by channel operator only flag; + n - no messages to channel from clients on the outside; + m - moderated channel; + l - set the user limit to channel; + + b - set a ban mask to keep users out; + v - give/take the ability to speak on a moderated channel; + k - set a channel key (password). + + When using the 'o' and 'b' options, a restriction on a total of three + per mode command has been imposed. That is, any combination of 'o' + and + +4.2.3.2 User modes + + Parameters: <nickname> {[+|-]|i|w|s|o} + + The user MODEs are typically changes which affect either how the + client is seen by others or what 'extra' messages the client is sent. + A user MODE command may only be accepted if both the sender of the + message and the nickname given as a parameter are both the same. + + The available modes are as follows: + + i - marks a users as invisible; + s - marks a user for receipt of server notices; + w - user receives wallops; + o - operator flag. + + Additional modes may be available later on. + + If a user attempts to make themselves an operator using the "+o" + flag, the attempt should be ignored. There is no restriction, + however, on anyone `deopping' themselves (using "-o"). Numeric + Replies: + + ERR_NEEDMOREPARAMS RPL_CHANNELMODEIS + ERR_CHANOPRIVSNEEDED ERR_NOSUCHNICK + ERR_NOTONCHANNEL ERR_KEYSET + RPL_BANLIST RPL_ENDOFBANLIST + ERR_UNKNOWNMODE ERR_NOSUCHCHANNEL + + ERR_USERSDONTMATCH RPL_UMODEIS + ERR_UMODEUNKNOWNFLAG + + Examples: + + Use of Channel Modes: + +MODE #Finnish +im ; Makes #Finnish channel moderated and + 'invite-only'. + +MODE #Finnish +o Kilroy ; Gives 'chanop' privileges to Kilroy on + + channel #Finnish. + +MODE #Finnish +v Wiz ; Allow WiZ to speak on #Finnish. + +MODE #Fins -s ; Removes 'secret' flag from channel + #Fins. + +MODE #42 +k oulu ; Set the channel key to "oulu". + +MODE #eu-opers +l 10 ; Set the limit for the number of users + on channel to 10. + +MODE &oulu +b ; list ban masks set for channel. + +MODE &oulu +b *!*@* ; prevent all users from joining. + +MODE &oulu +b *!*@*.edu ; prevent any user from a hostname + matching *.edu from joining. + + Use of user Modes: + +:MODE WiZ -w ; turns reception of WALLOPS messages + off for WiZ. + +:Angel MODE Angel +i ; Message from Angel to make themselves + invisible. + +MODE WiZ -o ; WiZ 'deopping' (removing operator + status). The plain reverse of this + command ("MODE WiZ +o") must not be + allowed from users since would bypass + the OPER command. + +4.2.4 Topic message + + Command: TOPIC + Parameters: <channel> [<topic>] + + The TOPIC message is used to change or view the topic of a channel. + The topic for channel <channel> is returned if there is no <topic> + given. If the <topic> parameter is present, the topic for that + channel will be changed, if the channel modes permit this action. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOTONCHANNEL + RPL_NOTOPIC RPL_TOPIC + ERR_CHANOPRIVSNEEDED + + Examples: + + :Wiz TOPIC #test :New topic ;User Wiz setting the topic. + + TOPIC #test :another topic ;set the topic on #test to "another + topic". + + TOPIC #test ; check the topic for #test. + +4.2.5 Names message + + Command: NAMES + Parameters: [<channel>{,<channel>}] + + By using the NAMES command, a user can list all nicknames that are + visible to them on any channel that they can see. Channel names + which they can see are those which aren't private (+p) or secret (+s) + or those which they are actually on. The <channel> parameter + specifies which channel(s) to return information about if valid. + There is no error reply for bad channel names. + + If no <channel> parameter is given, a list of all channels and their + occupants is returned. At the end of this list, a list of users who + are visible but either not on any channel or not on a visible channel + are listed as being on `channel' "*". + + Numerics: + + RPL_NAMREPLY RPL_ENDOFNAMES + + Examples: + + NAMES #twilight_zone,#42 ; list visible users on #twilight_zone + and #42 if the channels are visible to + you. + + NAMES ; list all visible channels and users + +4.2.6 List message + + Command: LIST + Parameters: [<channel>{,<channel>} [<server>]] + + The list message is used to list channels and their topics. If the + <channel> parameter is used, only the status of that channel + is displayed. Private channels are listed (without their + topics) as channel "Prv" unless the client generating the query is + actually on that channel. Likewise, secret channels are not listed + + at all unless the client is a member of the channel in question. + + Numeric Replies: + + ERR_NOSUCHSERVER RPL_LISTSTART + RPL_LIST RPL_LISTEND + + Examples: + + LIST ; List all channels. + + LIST #twilight_zone,#42 ; List channels #twilight_zone and #42 + +4.2.7 Invite message + + Command: INVITE + Parameters: <nickname> <channel> + + The INVITE message is used to invite users to a channel. The + parameter <nickname> is the nickname of the person to be invited to + the target channel <channel>. There is no requirement that the + channel the target user is being invited to must exist or be a valid + channel. To invite a user to a channel which is invite only (MODE + +i), the client sending the invite must be recognised as being a + channel operator on the given channel. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHNICK + ERR_NOTONCHANNEL ERR_USERONCHANNEL + ERR_CHANOPRIVSNEEDED + RPL_INVITING RPL_AWAY + + Examples: + + :Angel INVITE Wiz #Dust ; User Angel inviting WiZ to channel + #Dust + + INVITE Wiz #Twilight_Zone ; Command to invite WiZ to + #Twilight_zone + +4.2.8 Kick command + + Command: KICK + Parameters: <channel> <user> [<comment>] + + The KICK command can be used to forcibly remove a user from a + channel. It 'kicks them out' of the channel (forced PART). + + Only a channel operator may kick another user out of a channel. + Each server that receives a KICK message checks that it is valid + (ie the sender is actually a channel operator) before removing + the victim from the channel. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL + ERR_BADCHANMASK ERR_CHANOPRIVSNEEDED + ERR_NOTONCHANNEL + + Examples: + +KICK &Melbourne Matthew ; Kick Matthew from &Melbourne + +KICK #Finnish John :Speaking English + ; Kick John from #Finnish using + "Speaking English" as the reason + (comment). + +:WiZ KICK #Finnish John ; KICK message from WiZ to remove John + from channel #Finnish + +NOTE: + It is possible to extend the KICK command parameters to the +following: + +<channel>{,<channel>} <user>{,<user>} [<comment>] + +4.3 Server queries and commands + + The server query group of commands has been designed to return + information about any server which is connected to the network. All + servers connected must respond to these queries and respond + correctly. Any invalid response (or lack thereof) must be considered + a sign of a broken server and it must be disconnected/disabled as + soon as possible until the situation is remedied. + + In these queries, where a parameter appears as "<server>", it will + usually mean it can be a nickname or a server or a wildcard name of + some sort. For each parameter, however, only one query and set of + replies is to be generated. + +4.3.1 Version message + + Command: VERSION + Parameters: [<server>] + + The VERSION message is used to query the version of the server + program. An optional parameter <server> is used to query the version + of the server program which a client is not directly connected to. + + Numeric Replies: + + ERR_NOSUCHSERVER RPL_VERSION + + Examples: + + :Wiz VERSION *.se ; message from Wiz to check the version + of a server matching "*.se" + + VERSION tolsun.oulu.fi ; check the version of server + "tolsun.oulu.fi". + +4.3.2 Stats message + + Command: STATS + Parameters: [<query> [<server>]] + + The stats message is used to query statistics of certain server. If + <server> parameter is omitted, only the end of stats reply is sent + back. The implementation of this command is highly dependent on the + server which replies, although the server must be able to supply + information as described by the queries below (or similar). + + A query may be given by any single letter which is only checked by + the destination server (if given as the <server> parameter) and is + otherwise passed on by intermediate servers, ignored and unaltered. + The following queries are those found in the current IRC + implementation and provide a large portion of the setup information + for that server. Although these may not be supported in the same way + by other versions, all servers should be able to supply a valid reply + to a STATS query which is consistent with the reply formats currently + used and the purpose of the query. + + The currently supported queries are: + + c - returns a list of servers which the server may connect + to or allow connections from; + h - returns a list of servers which are either forced to be + treated as leaves or allowed to act as hubs; + i - returns a list of hosts which the server allows a client + to connect from; + k - returns a list of banned username/hostname combinations + for that server; + l - returns a list of the server's connections, showing how + + long each connection has been established and the traffic + over that connection in bytes and messages for each + direction; + m - returns a list of commands supported by the server and + the usage count for each if the usage count is non zero; + o - returns a list of hosts from which normal clients may + become operators; + y - show Y (Class) lines from server's configuration file; + u - returns a string showing how long the server has been up. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_STATSCLINE RPL_STATSNLINE + RPL_STATSILINE RPL_STATSKLINE + RPL_STATSQLINE RPL_STATSLLINE + RPL_STATSLINKINFO RPL_STATSUPTIME + RPL_STATSCOMMANDS RPL_STATSOLINE + RPL_STATSHLINE RPL_ENDOFSTATS + + Examples: + +STATS m ; check the command usage for the server + you are connected to + +:Wiz STATS c eff.org ; request by WiZ for C/N line + information from server eff.org + +4.3.3 Links message + + Command: LINKS + Parameters: [[<remote server>] <server mask>] + + With LINKS, a user can list all servers which are known by the server + answering the query. The returned list of servers must match the + mask, or if no mask is given, the full list is returned. + + If <remote server> is given in addition to <server mask>, the LINKS + command is forwarded to the first server found that matches that name + (if any), and that server is then required to answer the query. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_LINKS RPL_ENDOFLINKS + + Examples: + +LINKS *.au ; list all servers which have a name + that matches *.au; + +:WiZ LINKS *.bu.edu *.edu ; LINKS message from WiZ to the first + server matching *.edu for a list of + servers matching *.bu.edu. + +4.3.4 Time message + + Command: TIME + Parameters: [<server>] + + The time message is used to query local time from the specified + server. If the server parameter is not given, the server handling the + command must reply to the query. + + Numeric Replies: + + ERR_NOSUCHSERVER RPL_TIME + + Examples: + + TIME tolsun.oulu.fi ; check the time on the server + "tolson.oulu.fi" + + Angel TIME *.au ; user angel checking the time on a + server matching "*.au" + +4.3.5 Connect message + + Command: CONNECT + Parameters: <target server> [<port> [<remote server>]] + + The CONNECT command can be used to force a server to try to establish + a new connection to another server immediately. CONNECT is a + privileged command and is to be available only to IRC Operators. If + a remote server is given then the CONNECT attempt is made by that + server to <target server> and <port>. + + Numeric Replies: + + ERR_NOSUCHSERVER ERR_NOPRIVILEGES + ERR_NEEDMOREPARAMS + + Examples: + +CONNECT tolsun.oulu.fi ; Attempt to connect a server to + tolsun.oulu.fi + +:WiZ CONNECT eff.org 6667 csd.bu.edu + ; CONNECT attempt by WiZ to get servers + eff.org and csd.bu.edu connected on port + 6667. + +4.3.6 Trace message + + Command: TRACE + Parameters: [<server>] + + TRACE command is used to find the route to specific server. Each + server that processes this message must tell the sender about it by + sending a reply indicating it is a pass-through link, forming a chain + of replies similar to that gained from using "traceroute". After + sending this reply back, it must then send the TRACE message to the + next server until given server is reached. If the <server> parameter + is omitted, it is recommended that TRACE command send a message to + the sender telling which servers the current server has direct + connection to. + + If the destination given by "<server>" is an actual server, then the + destination server is required to report all servers and users which + are connected to it, although only operators are permitted to see + users present. If the destination given by <server> is a nickname, + they only a reply for that nickname is given. + + Numeric Replies: + + ERR_NOSUCHSERVER + + If the TRACE message is destined for another server, all intermediate + servers must return a RPL_TRACELINK reply to indicate that the TRACE + passed through it and where its going next. + + RPL_TRACELINK + A TRACE reply may be composed of any number of the following numeric + replies. + + RPL_TRACECONNECTING RPL_TRACEHANDSHAKE + RPL_TRACEUNKNOWN RPL_TRACEOPERATOR + RPL_TRACEUSER RPL_TRACESERVER + RPL_TRACESERVICE RPL_TRACENEWTYPE + RPL_TRACECLASS + + Examples: + +TRACE *.oulu.fi ; TRACE to a server matching *.oulu.fi + +:WiZ TRACE AngelDust ; TRACE issued by WiZ to nick AngelDust + +4.3.7 Admin command + + Command: ADMIN + Parameters: [<server>] + + The admin message is used to find the name of the administrator of + the given server, or current server if <server> parameter is omitted. + Each server must have the ability to forward ADMIN messages to other + servers. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_ADMINME RPL_ADMINLOC1 + RPL_ADMINLOC2 RPL_ADMINEMAIL + + Examples: + + ADMIN tolsun.oulu.fi ; request an ADMIN reply from + tolsun.oulu.fi + + :WiZ ADMIN *.edu ; ADMIN request from WiZ for first + server found to match *.edu. + +4.3.8 Info command + + Command: INFO + Parameters: [<server>] + + The INFO command is required to return information which describes + the server: its version, when it was compiled, the patchlevel, when + it was started, and any other miscellaneous information which may be + considered to be relevant. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_INFO RPL_ENDOFINFO + + Examples: + + INFO csd.bu.edu ; request an INFO reply from + csd.bu.edu + + :Avalon INFO *.fi ; INFO request from Avalon for first + server found to match *.fi. + + INFO Angel ; request info from the server that + Angel is connected to. + +4.4 Sending messages + + The main purpose of the IRC protocol is to provide a base for clients + to communicate with each other. PRIVMSG and NOTICE are the only + messages available which actually perform delivery of a text message + from one client to another - the rest just make it possible and try + to ensure it happens in a reliable and structured manner. + +4.4.1 Private messages + + Command: PRIVMSG + Parameters: <receiver>{,<receiver>} <text to be sent> + + PRIVMSG is used to send private messages between users. <receiver> + is the nickname of the receiver of the message. <receiver> can also + be a list of names or channels separated with commas. + + The <receiver> parameter may also me a host mask (#mask) or server + mask ($mask). In both cases the server will only send the PRIVMSG + to those who have a server or host matching the mask. The mask must + have at least 1 (one) "." in it and no wildcards following the + last ".". This requirement exists to prevent people sending messages + to "#*" or "$*", which would broadcast to all users; from + experience, this is abused more than used responsibly and properly. + Wildcards are the '*' and '?' characters. This extension to + the PRIVMSG command is only available to Operators. + + Numeric Replies: + + ERR_NORECIPIENT ERR_NOTEXTTOSEND + ERR_CANNOTSENDTOCHAN ERR_NOTOPLEVEL + ERR_WILDTOPLEVEL ERR_TOOMANYTARGETS + ERR_NOSUCHNICK + RPL_AWAY + + Examples: + +:Angel PRIVMSG Wiz :Hello are you receiving this message ? + ; Message from Angel to Wiz. + +PRIVMSG Angel :yes I'm receiving it !receiving it !'u>(768u+1n) .br ; + Message to Angel. + +PRIVMSG jto@tolsun.oulu.fi :Hello ! + ; Message to a client on server + + tolsun.oulu.fi with username of "jto". + +PRIVMSG $*.fi :Server tolsun.oulu.fi rebooting. + ; Message to everyone on a server which + has a name matching *.fi. + +PRIVMSG #*.edu :NSFNet is undergoing work, expect interruptions + ; Message to all users who come from a + host which has a name matching *.edu. + +4.4.2 Notice + + Command: NOTICE + Parameters: <nickname> <text> + + The NOTICE message is used similarly to PRIVMSG. The difference + between NOTICE and PRIVMSG is that automatic replies must never be + sent in response to a NOTICE message. This rule applies to servers + too - they must not send any error reply back to the client on + receipt of a notice. The object of this rule is to avoid loops + between a client automatically sending something in response to + something it received. This is typically used by automatons (clients + with either an AI or other interactive program controlling their + actions) which are always seen to be replying lest they end up in a + loop with another automaton. + + See PRIVMSG for more details on replies and examples. + +4.5 User based queries + + User queries are a group of commands which are primarily concerned + with finding details on a particular user or group users. When using + wildcards with any of these commands, if they match, they will only + return information on users who are 'visible' to you. The visibility + of a user is determined as a combination of the user's mode and the + common set of channels you are both on. + +4.5.1 Who query + + Command: WHO + Parameters: [<name> [<o>]] + + The WHO message is used by a client to generate a query which returns + a list of information which 'matches' the <name> parameter given by + the client. In the absence of the <name> parameter, all visible + (users who aren't invisible (user mode +i) and who don't have a + common channel with the requesting client) are listed. The same + result can be achieved by using a <name> of "0" or any wildcard which + + will end up matching every entry possible. + + The <name> passed to WHO is matched against users' host, server, real + name and nickname if the channel <name> cannot be found. + + If the "o" parameter is passed only operators are returned according + to the name mask supplied. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_WHOREPLY RPL_ENDOFWHO + + Examples: + + WHO *.fi ; List all users who match against + "*.fi". + + WHO jto* o ; List all users with a match against + "jto*" if they are an operator. + +4.5.2 Whois query + + Command: WHOIS + Parameters: [<server>] <nickmask>[,<nickmask>[,...]] + + This message is used to query information about particular user. The + server will answer this message with several numeric messages + indicating different statuses of each user which matches the nickmask + (if you are entitled to see them). If no wildcard is present in the + <nickmask>, any information about that nick which you are allowed to + see is presented. A comma (',') separated list of nicknames may be + given. + + The latter version sends the query to a specific server. It is + useful if you want to know how long the user in question has been + idle as only local server (ie. the server the user is directly + connected to) knows that information, while everything else is + globally known. + + Numeric Replies: + + ERR_NOSUCHSERVER ERR_NONICKNAMEGIVEN + RPL_WHOISUSER RPL_WHOISCHANNELS + RPL_WHOISCHANNELS RPL_WHOISSERVER + RPL_AWAY RPL_WHOISOPERATOR + RPL_WHOISIDLE ERR_NOSUCHNICK + RPL_ENDOFWHOIS + + Examples: + + WHOIS wiz ; return available user information + about nick WiZ + + WHOIS eff.org trillian ; ask server eff.org for user + information about trillian + +4.5.3 Whowas + + Command: WHOWAS + Parameters: <nickname> [<count> [<server>]] + + Whowas asks for information about a nickname which no longer exists. + This may either be due to a nickname change or the user leaving IRC. + In response to this query, the server searches through its nickname + history, looking for any nicks which are lexically the same (no wild + card matching here). The history is searched backward, returning the + most recent entry first. If there are multiple entries, up to + <count> replies will be returned (or all of them if no <count> + parameter is given). If a non-positive number is passed as being + <count>, then a full search is done. + + Numeric Replies: + + ERR_NONICKNAMEGIVEN ERR_WASNOSUCHNICK + RPL_WHOWASUSER RPL_WHOISSERVER + RPL_ENDOFWHOWAS + + Examples: + + WHOWAS Wiz ; return all information in the nick + history about nick "WiZ"; + + WHOWAS Mermaid 9 ; return at most, the 9 most recent + entries in the nick history for + "Mermaid"; + + WHOWAS Trillian 1 *.edu ; return the most recent history for + "Trillian" from the first server found + to match "*.edu". + +4.6 Miscellaneous messages + + Messages in this category do not fit into any of the above categories + but are nonetheless still a part of and required by the protocol. + +4.6.1 Kill message + + Command: KILL + Parameters: <nickname> <comment> + + The KILL message is used to cause a client-server connection to be + closed by the server which has the actual connection. KILL is used + by servers when they encounter a duplicate entry in the list of valid + nicknames and is used to remove both entries. It is also available + to operators. + + Clients which have automatic reconnect algorithms effectively make + this command useless since the disconnection is only brief. It does + however break the flow of data and can be used to stop large amounts + of being abused, any user may elect to receive KILL messages + generated for others to keep an 'eye' on would be trouble spots. + + In an arena where nicknames are required to be globally unique at all + times, KILL messages are sent whenever 'duplicates' are detected + (that is an attempt to register two users with the same nickname) in + the hope that both of them will disappear and only 1 reappear. + + The comment given must reflect the actual reason for the KILL. For + server-generated KILLs it usually is made up of details concerning + the origins of the two conflicting nicknames. For users it is left + up to them to provide an adequate reason to satisfy others who see + it. To prevent/discourage fake KILLs from being generated to hide + the identify of the KILLer, the comment also shows a 'kill-path' + which is updated by each server it passes through, each prepending + its name to the path. + + Numeric Replies: + + ERR_NOPRIVILEGES ERR_NEEDMOREPARAMS + ERR_NOSUCHNICK ERR_CANTKILLSERVER + + KILL David (csd.bu.edu <- tolsun.oulu.fi) + ; Nickname collision between csd.bu.edu + and tolson.oulu.fi + + NOTE: + It is recommended that only Operators be allowed to kill other users + with KILL message. In an ideal world not even operators would need + to do this and it would be left to servers to deal with. + +4.6.2 Ping message + + Command: PING + Parameters: <server1> [<server2>] + + The PING message is used to test the presence of an active client at + the other end of the connection. A PING message is sent at regular + intervals if no other activity detected coming from a connection. If + a connection fails to respond to a PING command within a set amount + of time, that connection is closed. + + Any client which receives a PING message must respond to <server1> + (server which sent the PING message out) as quickly as possible with + an appropriate PONG message to indicate it is still there and alive. + Servers should not respond to PING commands but rely on PINGs from + the other end of the connection to indicate the connection is alive. + If the <server2> parameter is specified, the PING message gets + forwarded there. + + Numeric Replies: + + ERR_NOORIGIN ERR_NOSUCHSERVER + + Examples: + + PING tolsun.oulu.fi ; server sending a PING message to + another server to indicate it is still + alive. + + PING WiZ ; PING message being sent to nick WiZ + +4.6.3 Pong message + + Command: PONG + Parameters: <daemon> [<daemon2>] + + PONG message is a reply to ping message. If parameter <daemon2> is + given this message must be forwarded to given daemon. The <daemon> + parameter is the name of the daemon who has responded to PING message + and generated this message. + + Numeric Replies: + + ERR_NOORIGIN ERR_NOSUCHSERVER + + Examples: + + PONG csd.bu.edu tolsun.oulu.fi ; PONG message from csd.bu.edu to + + tolsun.oulu.fi + +4.6.4 Error + + Command: ERROR + Parameters: <error message> + + The ERROR command is for use by servers when reporting a serious or + fatal error to its operators. It may also be sent from one server to + another but must not be accepted from any normal unknown clients. + + An ERROR message is for use for reporting errors which occur with a + server-to-server link only. An ERROR message is sent to the server + at the other end (which sends it to all of its connected operators) + and to all operators currently connected. It is not to be passed + onto any other servers by a server if it is received from a server. + + When a server sends a received ERROR message to its operators, the + message should be encapsulated inside a NOTICE message, indicating + that the client was not responsible for the error. + + Numerics: + + None. + + Examples: + + ERROR :Server *.fi already exists; ERROR message to the other server + which caused this error. + + NOTICE WiZ :ERROR from csd.bu.edu -- Server *.fi already exists + ; Same ERROR message as above but sent + to user WiZ on the other server. + +5. OPTIONALS + + This section describes OPTIONAL messages. They are not required in a + working server implementation of the protocol described herein. In + the absence of the option, an error reply message must be generated + or an unknown command error. If the message is destined for another + server to answer then it must be passed on (elementary parsing + required) The allocated numerics for this are listed with the + messages below. + +5.1 Away + + Command: AWAY + Parameters: [message] + + With the AWAY message, clients can set an automatic reply string for + any PRIVMSG commands directed at them (not to a channel they are on). + The automatic reply is sent by the server to client sending the + PRIVMSG command. The only replying server is the one to which the + sending client is connected to. + + The AWAY message is used either with one parameter (to set an AWAY + message) or with no parameters (to remove the AWAY message). + + Numeric Replies: + + RPL_UNAWAY RPL_NOWAWAY + + Examples: + + AWAY :Gone to lunch. Back in 5 ; set away message to "Gone to lunch. + Back in 5". + + :WiZ AWAY ; unmark WiZ as being away. + +5.2 Rehash message + + Command: REHASH + Parameters: None + + The rehash message can be used by the operator to force the server to + re-read and process its configuration file. + + Numeric Replies: + + RPL_REHASHING ERR_NOPRIVILEGES + +Examples: + +REHASH ; message from client with operator + status to server asking it to reread its + configuration file. + +5.3 Restart message + + Command: RESTART + Parameters: None + + The restart message can only be used by an operator to force a server + restart itself. This message is optional since it may be viewed as a + risk to allow arbitrary people to connect to a server as an operator + and execute this command, causing (at least) a disruption to service. + + The RESTART command must always be fully processed by the server to + which the sending client is connected and not be passed onto other + connected servers. + + Numeric Replies: + + ERR_NOPRIVILEGES + + Examples: + + RESTART ; no parameters required. + +5.4 Summon message + + Command: SUMMON + Parameters: <user> [<server>] + + The SUMMON command can be used to give users who are on a host + running an IRC server a message asking them to please join IRC. This + message is only sent if the target server (a) has SUMMON enabled, (b) + the user is logged in and (c) the server process can write to the + user's tty (or similar). + + If no <server> parameter is given it tries to summon <user> from the + server the client is connected to is assumed as the target. + + If summon is not enabled in a server, it must return the + ERR_SUMMONDISABLED numeric and pass the summon message onwards. + + Numeric Replies: + + ERR_NORECIPIENT ERR_FILEERROR + ERR_NOLOGIN ERR_NOSUCHSERVER + RPL_SUMMONING + + Examples: + + SUMMON jto ; summon user jto on the server's host + + SUMMON jto tolsun.oulu.fi ; summon user jto on the host which a + server named "tolsun.oulu.fi" is + running. + +5.5 Users + + Command: USERS + Parameters: [<server>] + + The USERS command returns a list of users logged into the server in a + similar format to who(1), rusers(1) and finger(1). Some people + may disable this command on their server for security related + reasons. If disabled, the correct numeric must be returned to + indicate this. + + Numeric Replies: + + ERR_NOSUCHSERVER ERR_FILEERROR + RPL_USERSSTART RPL_USERS + RPL_NOUSERS RPL_ENDOFUSERS + ERR_USERSDISABLED + + Disabled Reply: + + ERR_USERSDISABLED + + Examples: + +USERS eff.org ; request a list of users logged in on + server eff.org + +:John USERS tolsun.oulu.fi ; request from John for a list of users + logged in on server tolsun.oulu.fi + +5.6 Operwall message + + Command: WALLOPS + Parameters: Text to be sent to all operators currently online + + Sends a message to all operators currently online. After + implementing WALLOPS as a user command it was found that it was + often and commonly abused as a means of sending a message to a lot + of people (much similar to WALL). Due to this it is recommended + that the current implementation of WALLOPS be used as an + example by allowing and recognising only servers as the senders of + WALLOPS. + + Numeric Replies: + + ERR_NEEDMOREPARAMS + + Examples: + + :csd.bu.edu WALLOPS :Connect '*.uiuc.edu 6667' from Joshua; WALLOPS + message from csd.bu.edu announcing a + CONNECT message it received and acted + upon from Joshua. + +5.7 Userhost message + + Command: USERHOST + Parameters: <nickname>{<space><nickname>} + + The USERHOST command takes a list of up to 5 nicknames, each + separated by a space character and returns a list of information + about each nickname that it found. The returned list has each reply + separated by a space. + + Numeric Replies: + + RPL_USERHOST ERR_NEEDMOREPARAMS + + Examples: + + USERHOST Wiz Michael Marty p ;USERHOST request for information on + nicks "Wiz", "Michael", "Marty" and "p" + +5.8 Ison message + + Command: ISON + Parameters: <nickname>{<space><nickname>} + + The ISON command was implemented to provide a quick and efficient + means to get a response about whether a given nickname was currently + on IRC. ISON only takes one (1) parameter: a space-separated list of + nicks. For each nickname in the list that is present, the server + adds that to its reply string. Thus the reply string may return + empty (none of the given nicks are present), an exact copy of the + parameter string (all of them present) or as any other subset of the + set of nicks given in the parameter. The only limit on the number + of nicks that may be checked is that the combined length must not be + too large as to cause the server to chop it off so it fits in 512 + characters. + + ISON is only be processed by the server local to the client sending + the command and thus not passed onto other servers for further + processing. + + Numeric Replies: + + RPL_ISON ERR_NEEDMOREPARAMS + + Examples: + + ISON phone trillian WiZ jarlek Avalon Angel Monstah + ; Sample ISON request for 7 nicks. + +6. REPLIES + + The following is a list of numeric replies which are generated in + response to the commands given above. Each numeric is given with its + number, name and reply string. + +6.1 Error Replies. + + 401 ERR_NOSUCHNICK + "<nickname> :No such nick/channel" + + - Used to indicate the nickname parameter supplied to a + command is currently unused. + + 402 ERR_NOSUCHSERVER + "<server name> :No such server" + + - Used to indicate the server name given currently + doesn't exist. + + 403 ERR_NOSUCHCHANNEL + "<channel name> :No such channel" + + - Used to indicate the given channel name is invalid. + + 404 ERR_CANNOTSENDTOCHAN + "<channel name> :Cannot send to channel" + + - Sent to a user who is either (a) not on a channel + which is mode +n or (b) not a chanop (or mode +v) on + a channel which has mode +m set and is trying to send + a PRIVMSG message to that channel. + + 405 ERR_TOOMANYCHANNELS + "<channel name> :You have joined too many \ + channels" + - Sent to a user when they have joined the maximum + number of allowed channels and they try to join + another channel. + + 406 ERR_WASNOSUCHNICK + "<nickname> :There was no such nickname" + + - Returned by WHOWAS to indicate there is no history + information for that nickname. + + 407 ERR_TOOMANYTARGETS + "<target> :Duplicate recipients. No message \ + + delivered" + + - Returned to a client which is attempting to send a + PRIVMSG/NOTICE using the user@host destination format + and for a user@host which has several occurrences. + + 409 ERR_NOORIGIN + ":No origin specified" + + - PING or PONG message missing the originator parameter + which is required since these commands must work + without valid prefixes. + + 411 ERR_NORECIPIENT + ":No recipient given (<command>)" + 412 ERR_NOTEXTTOSEND + ":No text to send" + 413 ERR_NOTOPLEVEL + "<mask> :No toplevel domain specified" + 414 ERR_WILDTOPLEVEL + "<mask> :Wildcard in toplevel domain" + + - 412 - 414 are returned by PRIVMSG to indicate that + the message wasn't delivered for some reason. + ERR_NOTOPLEVEL and ERR_WILDTOPLEVEL are errors that + are returned when an invalid use of + "PRIVMSG $<server>" or "PRIVMSG #<host>" is attempted. + + 421 ERR_UNKNOWNCOMMAND + "<command> :Unknown command" + + - Returned to a registered client to indicate that the + command sent is unknown by the server. + + 422 ERR_NOMOTD + ":MOTD File is missing" + + - Server's MOTD file could not be opened by the server. + + 423 ERR_NOADMININFO + "<server> :No administrative info available" + + - Returned by a server in response to an ADMIN message + when there is an error in finding the appropriate + information. + + 424 ERR_FILEERROR + ":File error doing <file op> on <file>" + + - Generic error message used to report a failed file + operation during the processing of a message. + + 431 ERR_NONICKNAMEGIVEN + ":No nickname given" + + - Returned when a nickname parameter expected for a + command and isn't found. + + 432 ERR_ERRONEUSNICKNAME + "<nick> :Erroneus nickname" + + - Returned after receiving a NICK message which contains + characters which do not fall in the defined set. See + section x.x.x for details on valid nicknames. + + 433 ERR_NICKNAMEINUSE + "<nick> :Nickname is already in use" + + - Returned when a NICK message is processed that results + in an attempt to change to a currently existing + nickname. + + 436 ERR_NICKCOLLISION + "<nick> :Nickname collision KILL" + + - Returned by a server to a client when it detects a + nickname collision (registered of a NICK that + already exists by another server). + + 441 ERR_USERNOTINCHANNEL + "<nick> <channel> :They aren't on that channel" + + - Returned by the server to indicate that the target + user of the command is not on the given channel. + + 442 ERR_NOTONCHANNEL + "<channel> :You're not on that channel" + + - Returned by the server whenever a client tries to + perform a channel effecting command for which the + client isn't a member. + + 443 ERR_USERONCHANNEL + "<user> <channel> :is already on channel" + + - Returned when a client tries to invite a user to a + channel they are already on. + + 444 ERR_NOLOGIN + "<user> :User not logged in" + + - Returned by the summon after a SUMMON command for a + user was unable to be performed since they were not + logged in. + + 445 ERR_SUMMONDISABLED + ":SUMMON has been disabled" + + - Returned as a response to the SUMMON command. Must be + returned by any server which does not implement it. + + 446 ERR_USERSDISABLED + ":USERS has been disabled" + + - Returned as a response to the USERS command. Must be + returned by any server which does not implement it. + + 451 ERR_NOTREGISTERED + ":You have not registered" + + - Returned by the server to indicate that the client + must be registered before the server will allow it + to be parsed in detail. + + 461 ERR_NEEDMOREPARAMS + "<command> :Not enough parameters" + + - Returned by the server by numerous commands to + indicate to the client that it didn't supply enough + parameters. + + 462 ERR_ALREADYREGISTRED + ":You may not reregister" + + - Returned by the server to any link which tries to + change part of the registered details (such as + password or user details from second USER message). + + 463 ERR_NOPERMFORHOST + ":Your host isn't among the privileged" + + - Returned to a client which attempts to register with + a server which does not been setup to allow + connections from the host the attempted connection + is tried. + + 464 ERR_PASSWDMISMATCH + ":Password incorrect" + + - Returned to indicate a failed attempt at registering + a connection for which a password was required and + was either not given or incorrect. + + 465 ERR_YOUREBANNEDCREEP + ":You are banned from this server" + + - Returned after an attempt to connect and register + yourself with a server which has been setup to + explicitly deny connections to you. + + 467 ERR_KEYSET + "<channel> :Channel key already set" + 471 ERR_CHANNELISFULL + "<channel> :Cannot join channel (+l)" + 472 ERR_UNKNOWNMODE + "<char> :is unknown mode char to me" + 473 ERR_INVITEONLYCHAN + "<channel> :Cannot join channel (+i)" + 474 ERR_BANNEDFROMCHAN + "<channel> :Cannot join channel (+b)" + 475 ERR_BADCHANNELKEY + "<channel> :Cannot join channel (+k)" + 481 ERR_NOPRIVILEGES + ":Permission Denied- You're not an IRC operator" + + - Any command requiring operator privileges to operate + must return this error to indicate the attempt was + unsuccessful. + + 482 ERR_CHANOPRIVSNEEDED + "<channel> :You're not channel operator" + + - Any command requiring 'chanop' privileges (such as + MODE messages) must return this error if the client + making the attempt is not a chanop on the specified + channel. + + 483 ERR_CANTKILLSERVER + ":You cant kill a server!" + + - Any attempts to use the KILL command on a server + are to be refused and this error returned directly + to the client. + + 491 ERR_NOOPERHOST + ":No O-lines for your host" + + - If a client sends an OPER message and the server has + not been configured to allow connections from the + client's host as an operator, this error must be + returned. + + 501 ERR_UMODEUNKNOWNFLAG + ":Unknown MODE flag" + + - Returned by the server to indicate that a MODE + message was sent with a nickname parameter and that + the a mode flag sent was not recognized. + + 502 ERR_USERSDONTMATCH + ":Cant change mode for other users" + + - Error sent to any user trying to view or change the + user mode for a user other than themselves. + +6.2 Command responses. + + 300 RPL_NONE + Dummy reply number. Not used. + + 302 RPL_USERHOST + ":[<reply>{<space><reply>}]" + + - Reply format used by USERHOST to list replies to + the query list. The reply string is composed as + follows: + + <reply> ::= <nick>['*'] '=' <'+'|'-'><hostname> + + The '*' indicates whether the client has registered + as an Operator. The '-' or '+' characters represent + whether the client has set an AWAY message or not + respectively. + + 303 RPL_ISON + ":[<nick> {<space><nick>}]" + + - Reply format used by ISON to list replies to the + query list. + + 301 RPL_AWAY + "<nick> :<away message>" + + 305 RPL_UNAWAY + ":You are no longer marked as being away" + 306 RPL_NOWAWAY + ":You have been marked as being away" + + - These replies are used with the AWAY command (if + allowed). RPL_AWAY is sent to any client sending a + PRIVMSG to a client which is away. RPL_AWAY is only + sent by the server to which the client is connected. + Replies RPL_UNAWAY and RPL_NOWAWAY are sent when the + client removes and sets an AWAY message. + + 311 RPL_WHOISUSER + "<nick> <user> <host> * :<real name>" + 312 RPL_WHOISSERVER + "<nick> <server> :<server info>" + 313 RPL_WHOISOPERATOR + "<nick> :is an IRC operator" + 317 RPL_WHOISIDLE + "<nick> <integer> :seconds idle" + 318 RPL_ENDOFWHOIS + "<nick> :End of /WHOIS list" + 319 RPL_WHOISCHANNELS + "<nick> :{[@|+]<channel><space>}" + + - Replies 311 - 313, 317 - 319 are all replies + generated in response to a WHOIS message. Given that + there are enough parameters present, the answering + server must either formulate a reply out of the above + numerics (if the query nick is found) or return an + error reply. The '*' in RPL_WHOISUSER is there as + the literal character and not as a wild card. For + each reply set, only RPL_WHOISCHANNELS may appear + more than once (for long lists of channel names). + The '@' and '+' characters next to the channel name + indicate whether a client is a channel operator or + has been granted permission to speak on a moderated + channel. The RPL_ENDOFWHOIS reply is used to mark + the end of processing a WHOIS message. + + 314 RPL_WHOWASUSER + "<nick> <user> <host> * :<real name>" + 369 RPL_ENDOFWHOWAS + "<nick> :End of WHOWAS" + + - When replying to a WHOWAS message, a server must use + the replies RPL_WHOWASUSER, RPL_WHOISSERVER or + ERR_WASNOSUCHNICK for each nickname in the presented + + list. At the end of all reply batches, there must + be RPL_ENDOFWHOWAS (even if there was only one reply + and it was an error). + + 321 RPL_LISTSTART + "Channel :Users Name" + 322 RPL_LIST + "<channel> <# visible> :<topic>" + 323 RPL_LISTEND + ":End of /LIST" + + - Replies RPL_LISTSTART, RPL_LIST, RPL_LISTEND mark + the start, actual replies with data and end of the + server's response to a LIST command. If there are + no channels available to return, only the start + and end reply must be sent. + + 324 RPL_CHANNELMODEIS + "<channel> <mode> <mode params>" + + 331 RPL_NOTOPIC + "<channel> :No topic is set" + 332 RPL_TOPIC + "<channel> :<topic>" + + - When sending a TOPIC message to determine the + channel topic, one of two replies is sent. If + the topic is set, RPL_TOPIC is sent back else + RPL_NOTOPIC. + + 341 RPL_INVITING + "<channel> <nick>" + + - Returned by the server to indicate that the + attempted INVITE message was successful and is + being passed onto the end client. + + 342 RPL_SUMMONING + "<user> :Summoning user to IRC" + + - Returned by a server answering a SUMMON message to + indicate that it is summoning that user. + + 351 RPL_VERSION + "<version>.<debuglevel> <server> :<comments>" + + - Reply by the server showing its version details. + The <version> is the version of the software being + + used (including any patchlevel revisions) and the + <debuglevel> is used to indicate if the server is + running in "debug mode". + + The "comments" field may contain any comments about + the version or further version details. + + 352 RPL_WHOREPLY + "<channel> <user> <host> <server> <nick> \ + <H|G>[*][@|+] :<hopcount> <real name>" + 315 RPL_ENDOFWHO + "<name> :End of /WHO list" + + - The RPL_WHOREPLY and RPL_ENDOFWHO pair are used + to answer a WHO message. The RPL_WHOREPLY is only + sent if there is an appropriate match to the WHO + query. If there is a list of parameters supplied + with a WHO message, a RPL_ENDOFWHO must be sent + after processing each list item with <name> being + the item. + + 353 RPL_NAMREPLY + "<channel> :[[@|+]<nick> [[@|+]<nick> [...]]]" + 366 RPL_ENDOFNAMES + "<channel> :End of /NAMES list" + + - To reply to a NAMES message, a reply pair consisting + of RPL_NAMREPLY and RPL_ENDOFNAMES is sent by the + server back to the client. If there is no channel + found as in the query, then only RPL_ENDOFNAMES is + returned. The exception to this is when a NAMES + message is sent with no parameters and all visible + channels and contents are sent back in a series of + RPL_NAMEREPLY messages with a RPL_ENDOFNAMES to mark + the end. + + 364 RPL_LINKS + "<mask> <server> :<hopcount> <server info>" + 365 RPL_ENDOFLINKS + "<mask> :End of /LINKS list" + + - In replying to the LINKS message, a server must send + replies back using the RPL_LINKS numeric and mark the + end of the list using an RPL_ENDOFLINKS reply. + + 367 RPL_BANLIST + "<channel> <banid>" + 368 RPL_ENDOFBANLIST + + "<channel> :End of channel ban list" + + - When listing the active 'bans' for a given channel, + a server is required to send the list back using the + RPL_BANLIST and RPL_ENDOFBANLIST messages. A separate + RPL_BANLIST is sent for each active banid. After the + banids have been listed (or if none present) a + RPL_ENDOFBANLIST must be sent. + + 371 RPL_INFO + ":<string>" + 374 RPL_ENDOFINFO + ":End of /INFO list" + + - A server responding to an INFO message is required to + send all its 'info' in a series of RPL_INFO messages + with a RPL_ENDOFINFO reply to indicate the end of the + replies. + + 375 RPL_MOTDSTART + ":- <server> Message of the day - " + 372 RPL_MOTD + ":- <text>" + 376 RPL_ENDOFMOTD + ":End of /MOTD command" + + - When responding to the MOTD message and the MOTD file + is found, the file is displayed line by line, with + each line no longer than 80 characters, using + RPL_MOTD format replies. These should be surrounded + by a RPL_MOTDSTART (before the RPL_MOTDs) and an + RPL_ENDOFMOTD (after). + + 381 RPL_YOUREOPER + ":You are now an IRC operator" + + - RPL_YOUREOPER is sent back to a client which has + just successfully issued an OPER message and gained + operator status. + + 382 RPL_REHASHING + "<config file> :Rehashing" + + - If the REHASH option is used and an operator sends + a REHASH message, an RPL_REHASHING is sent back to + the operator. + + 391 RPL_TIME + + "<server> :<string showing server's local time>" + + - When replying to the TIME message, a server must send + the reply using the RPL_TIME format above. The string + showing the time need only contain the correct day and + time there. There is no further requirement for the + time string. + + 392 RPL_USERSSTART + ":UserID Terminal Host" + 393 RPL_USERS + ":%-8s %-9s %-8s" + 394 RPL_ENDOFUSERS + ":End of users" + 395 RPL_NOUSERS + ":Nobody logged in" + + - If the USERS message is handled by a server, the + replies RPL_USERSTART, RPL_USERS, RPL_ENDOFUSERS and + RPL_NOUSERS are used. RPL_USERSSTART must be sent + first, following by either a sequence of RPL_USERS + or a single RPL_NOUSER. Following this is + RPL_ENDOFUSERS. + + 200 RPL_TRACELINK + "Link <version & debug level> <destination> \ + <next server>" + 201 RPL_TRACECONNECTING + "Try. <class> <server>" + 202 RPL_TRACEHANDSHAKE + "H.S. <class> <server>" + 203 RPL_TRACEUNKNOWN + "???? <class> [<client IP address in dot form>]" + 204 RPL_TRACEOPERATOR + "Oper <class> <nick>" + 205 RPL_TRACEUSER + "User <class> <nick>" + 206 RPL_TRACESERVER + "Serv <class> <int>S <int>C <server> \ + <nick!user|*!*>@<host|server>" + 208 RPL_TRACENEWTYPE + "<newtype> 0 <client name>" + 261 RPL_TRACELOG + "File <logfile> <debug level>" + + - The RPL_TRACE* are all returned by the server in + response to the TRACE message. How many are + returned is dependent on the the TRACE message and + + whether it was sent by an operator or not. There + is no predefined order for which occurs first. + Replies RPL_TRACEUNKNOWN, RPL_TRACECONNECTING and + RPL_TRACEHANDSHAKE are all used for connections + which have not been fully established and are either + unknown, still attempting to connect or in the + process of completing the 'server handshake'. + RPL_TRACELINK is sent by any server which handles + a TRACE message and has to pass it on to another + server. The list of RPL_TRACELINKs sent in + response to a TRACE command traversing the IRC + network should reflect the actual connectivity of + the servers themselves along that path. + RPL_TRACENEWTYPE is to be used for any connection + which does not fit in the other categories but is + being displayed anyway. + + 211 RPL_STATSLINKINFO + "<linkname> <sendq> <sent messages> \ + <sent bytes> <received messages> \ + <received bytes> <time open>" + 212 RPL_STATSCOMMANDS + "<command> <count>" + 213 RPL_STATSCLINE + "C <host> * <name> <port> <class>" + 214 RPL_STATSNLINE + "N <host> * <name> <port> <class>" + 215 RPL_STATSILINE + "I <host> * <host> <port> <class>" + 216 RPL_STATSKLINE + "K <host> * <username> <port> <class>" + 218 RPL_STATSYLINE + "Y <class> <ping frequency> <connect \ + frequency> <max sendq>" + 219 RPL_ENDOFSTATS + "<stats letter> :End of /STATS report" + 241 RPL_STATSLLINE + "L <hostmask> * <servername> <maxdepth>" + 242 RPL_STATSUPTIME + ":Server Up %d days %d:%02d:%02d" + 243 RPL_STATSOLINE + "O <hostmask> * <name>" + 244 RPL_STATSHLINE + "H <hostmask> * <servername>" + + 221 RPL_UMODEIS + "<user mode string>" + + - To answer a query about a client's own mode, + RPL_UMODEIS is sent back. + + 251 RPL_LUSERCLIENT + ":There are <integer> users and <integer> \ + invisible on <integer> servers" + 252 RPL_LUSEROP + "<integer> :operator(s) online" + 253 RPL_LUSERUNKNOWN + "<integer> :unknown connection(s)" + 254 RPL_LUSERCHANNELS + "<integer> :channels formed" + 255 RPL_LUSERME + ":I have <integer> clients and <integer> \ + servers" + + - In processing an LUSERS message, the server + sends a set of replies from RPL_LUSERCLIENT, + RPL_LUSEROP, RPL_USERUNKNOWN, + RPL_LUSERCHANNELS and RPL_LUSERME. When + replying, a server must send back + RPL_LUSERCLIENT and RPL_LUSERME. The other + replies are only sent back if a non-zero count + is found for them. + + 256 RPL_ADMINME + "<server> :Administrative info" + 257 RPL_ADMINLOC1 + ":<admin info>" + 258 RPL_ADMINLOC2 + ":<admin info>" + 259 RPL_ADMINEMAIL + ":<admin info>" + + - When replying to an ADMIN message, a server + is expected to use replies RLP_ADMINME + through to RPL_ADMINEMAIL and provide a text + message with each. For RPL_ADMINLOC1 a + description of what city, state and country + the server is in is expected, followed by + details of the university and department + (RPL_ADMINLOC2) and finally the administrative + contact for the server (an email address here + is required) in RPL_ADMINEMAIL. + +6.3 Reserved numerics. + + These numerics are not described above since they fall into one of + the following categories: + + 1. no longer in use; + + 2. reserved for future planned use; + + 3. in current use but are part of a non-generic 'feature' of + the current IRC server. + + 209 RPL_TRACECLASS 217 RPL_STATSQLINE + 231 RPL_SERVICEINFO 232 RPL_ENDOFSERVICES + 233 RPL_SERVICE 234 RPL_SERVLIST + 235 RPL_SERVLISTEND + 316 RPL_WHOISCHANOP 361 RPL_KILLDONE + 362 RPL_CLOSING 363 RPL_CLOSEEND + 373 RPL_INFOSTART 384 RPL_MYPORTIS + 466 ERR_YOUWILLBEBANNED 476 ERR_BADCHANMASK + 492 ERR_NOSERVICEHOST + +7. Client and server authentication + + Clients and servers are both subject to the same level of + authentication. For both, an IP number to hostname lookup (and + reverse check on this) is performed for all connections made to the + server. Both connections are then subject to a password check (if + there is a password set for that connection). These checks are + possible on all connections although the password check is only + commonly used with servers. + + An additional check that is becoming of more and more common is that + of the username responsible for making the connection. Finding the + username of the other end of the connection typically involves + connecting to an authentication server such as IDENT as described in + RFC 1413. + + Given that without passwords it is not easy to reliably determine who + is on the other end of a network connection, use of passwords is + strongly recommended on inter-server connections in addition to any + other measures such as using an ident server. + +8. Current implementations + + The only current implementation of this protocol is the IRC server, + version 2.8. Earlier versions may implement some or all of the + commands described by this document with NOTICE messages replacing + + many of the numeric replies. Unfortunately, due to backward + compatibility requirements, the implementation of some parts of this + document varies with what is laid out. On notable difference is: + + * recognition that any LF or CR anywhere in a message marks the + end of that message (instead of requiring CR-LF); + + The rest of this section deals with issues that are mostly of + importance to those who wish to implement a server but some parts + also apply directly to clients as well. + +8.1 Network protocol: TCP - why it is best used here. + + IRC has been implemented on top of TCP since TCP supplies a reliable + network protocol which is well suited to this scale of conferencing. + The use of multicast IP is an alternative, but it is not widely + available or supported at the present time. + +8.1.1 Support of Unix sockets + + Given that Unix domain sockets allow listen/connect operations, the + current implementation can be configured to listen and accept both + client and server connections on a Unix domain socket. These are + recognized as sockets where the hostname starts with a '/'. + + When providing any information about the connections on a Unix domain + socket, the server is required to supplant the actual hostname in + place of the pathname unless the actual socket name is being asked + for. + +8.2 Command Parsing + + To provide useful 'non-buffered' network IO for clients and servers, + each connection is given its own private 'input buffer' in which the + results of the most recent read and parsing are kept. A buffer size + of 512 bytes is used so as to hold 1 full message, although, this + will usually hold several commands. The private buffer is parsed + after every read operation for valid messages. When dealing with + multiple messages from one client in the buffer, care should be taken + in case one happens to cause the client to be 'removed'. + +8.3 Message delivery + + It is common to find network links saturated or hosts to which you + are sending data unable to send data. Although Unix typically + handles this through the TCP window and internal buffers, the server + often has large amounts of data to send (especially when a new + server-server link forms) and the small buffers provided in the + + kernel are not enough for the outgoing queue. To alleviate this + problem, a "send queue" is used as a FIFO queue for data to be sent. + A typical "send queue" may grow to 200 Kbytes on a large IRC network + with a slow network connection when a new server connects. + + When polling its connections, a server will first read and parse all + incoming data, queuing any data to be sent out. When all available + input is processed, the queued data is sent. This reduces the number + of write() system calls and helps TCP make bigger packets. + +8.4 Connection 'Liveness' + + To detect when a connection has died or become unresponsive, the + server must ping each of its connections that it doesn't get a + response from in a given amount of time. + + If a connection doesn't respond in time, its connection is closed + using the appropriate procedures. A connection is also dropped if + its sendq grows beyond the maximum allowed, because it is better to + close a slow connection than have a server process block. + +8.5 Establishing a server to client connection + + Upon connecting to an IRC server, a client is sent the MOTD (if + present) as well as the current user/server count (as per the LUSER + command). The server is also required to give an unambiguous message + to the client which states its name and version as well as any other + introductory messages which may be deemed appropriate. + + After dealing with this, the server must then send out the new user's + nickname and other information as supplied by itself (USER command) + and as the server could discover (from DNS/authentication servers). + The server must send this information out with NICK first followed by + USER. + +8.6 Establishing a server-server connection. + + The process of establishing of a server-to-server connection is + fraught with danger since there are many possible areas where + problems can occur - the least of which are race conditions. + + After a server has received a connection following by a PASS/SERVER + pair which were recognised as being valid, the server should then + reply with its own PASS/SERVER information for that connection as + well as all of the other state information it knows about as + described below. + + When the initiating server receives a PASS/SERVER pair, it too then + + checks that the server responding is authenticated properly before + accepting the connection to be that server. + +8.6.1 Server exchange of state information when connecting + + The order of state information being exchanged between servers is + essential. The required order is as follows: + + * all known other servers; + + * all known user information; + + * all known channel information. + + Information regarding servers is sent via extra SERVER messages, user + information with NICK/USER/MODE/JOIN messages and channels with MODE + messages. + + NOTE: channel topics are *NOT* exchanged here because the TOPIC + command overwrites any old topic information, so at best, the two + sides of the connection would exchange topics. + + By passing the state information about servers first, any collisions + with servers that already exist occur before nickname collisions due + to a second server introducing a particular nickname. Due to the IRC + network only being able to exist as an acyclic graph, it may be + possible that the network has already reconnected in another + location, the place where the collision occurs indicating where the + net needs to split. + +8.7 Terminating server-client connections + + When a client connection closes, a QUIT message is generated on + behalf of the client by the server to which the client connected. No + other message is to be generated or used. + +8.8 Terminating server-server connections + + If a server-server connection is closed, either via a remotely + generated SQUIT or 'natural' causes, the rest of the connected IRC + network must have its information updated with by the server which + detected the closure. The server then sends a list of SQUITs (one + for each server behind that connection) and a list of QUITs (again, + one for each client behind that connection). + +8.9 Tracking nickname changes + + All IRC servers are required to keep a history of recent nickname + changes. This is required to allow the server to have a chance of + keeping in touch of things when nick-change race conditions occur + with commands which manipulate them. Commands which must trace nick + changes are: + + * KILL (the nick being killed) + + * MODE (+/- o,v) + + * KICK (the nick being kicked) + + No other commands are to have nick changes checked for. + + In the above cases, the server is required to first check for the + existence of the nickname, then check its history to see who that + nick currently belongs to (if anyone!). This reduces the chances of + race conditions but they can still occur with the server ending up + affecting the wrong client. When performing a change trace for an + above command it is recommended that a time range be given and + entries which are too old ignored. + + For a reasonable history, a server should be able to keep previous + nickname for every client it knows about if they all decided to + change. This size is limited by other factors (such as memory, etc). + +8.10 Flood control of clients + + With a large network of interconnected IRC servers, it is quite easy + for any single client attached to the network to supply a continuous + stream of messages that result in not only flooding the network, but + also degrading the level of service provided to others. Rather than + require every 'victim' to be provide their own protection, flood + protection was written into the server and is applied to all clients + except services. The current algorithm is as follows: + + * check to see if client's `message timer' is less than + current time (set to be equal if it is); + + * read any data present from the client; + + * while the timer is less than ten seconds ahead of the current + time, parse any present messages and penalize the client by + 2 seconds for each message; + + which in essence means that the client may send 1 message every 2 + + seconds without being adversely affected. + +8.11 Non-blocking lookups + + In a real-time environment, it is essential that a server process do + as little waiting as possible so that all the clients are serviced + fairly. Obviously this requires non-blocking IO on all network + read/write operations. For normal server connections, this was not + difficult, but there are other support operations that may cause the + server to block (such as disk reads). Where possible, such activity + should be performed with a short timeout. + +8.11.1 Hostname (DNS) lookups + + Using the standard resolver libraries from Berkeley and others has + meant large delays in some cases where replies have timed out. To + avoid this, a separate set of DNS routines were written which were + setup for non-blocking IO operations and then polled from within the + main server IO loop. + +8.11.2 Username (Ident) lookups + + Although there are numerous ident libraries for use and inclusion + into other programs, these caused problems since they operated in a + synchronous manner and resulted in frequent delays. Again the + solution was to write a set of routines which would cooperate with + the rest of the server and work using non-blocking IO. + +8.12 Configuration File + + To provide a flexible way of setting up and running the server, it is + recommended that a configuration file be used which contains + instructions to the server on the following: + + * which hosts to accept client connections from; + + * which hosts to allow to connect as servers; + + * which hosts to connect to (both actively and + passively); + + * information about where the server is (university, + city/state, company are examples of this); + + * who is responsible for the server and an email address + at which they can be contacted; + + * hostnames and passwords for clients which wish to be given + + access to restricted operator commands. + + In specifying hostnames, both domain names and use of the 'dot' + notation (127.0.0.1) should both be accepted. It must be possible to + specify the password to be used/accepted for all outgoing and + incoming connections (although the only outgoing connections are + those to other servers). + + The above list is the minimum requirement for any server which wishes + to make a connection with another server. Other items which may be + of use are: + + * specifying which servers other server may introduce; + + * how deep a server branch is allowed to become; + + * hours during which clients may connect. + +8.12.1 Allowing clients to connect + + A server should use some sort of 'access control list' (either in the + configuration file or elsewhere) that is read at startup and used to + decide what hosts clients may use to connect to it. + + Both 'deny' and 'allow' should be implemented to provide the required + flexibility for host access control. + +8.12.2 Operators + + The granting of operator privileges to a disruptive person can have + dire consequences for the well-being of the IRC net in general due to + the powers given to them. Thus, the acquisition of such powers + should not be very easy. The current setup requires two 'passwords' + to be used although one of them is usually easy guessed. Storage of + oper passwords in configuration files is preferable to hard coding + them in and should be stored in a crypted format (ie using crypt(3) + from Unix) to prevent easy theft. + +8.12.3 Allowing servers to connect + + The interconnection of server is not a trivial matter: a bad + connection can have a large impact on the usefulness of IRC. Thus, + each server should have a list of servers to which it may connect and + which servers may connect to it. Under no circumstances should a + server allow an arbitrary host to connect as a server. In addition + to which servers may and may not connect, the configuration file + should also store the password and other characteristics of that + link. + +8.12.4 Administrivia + + To provide accurate and valid replies to the ADMIN command (see + section 4.3.7), the server should find the relevant details in the + configuration. + +8.13 Channel membership + + The current server allows any registered local user to join upto 10 + different channels. There is no limit imposed on non-local users so + that the server remains (reasonably) consistant with all others on a + channel membership basis + +9. Current problems + + There are a number of recognized problems with this protocol, all of + which hope to be solved sometime in the near future during its + rewrite. Currently, work is underway to find working solutions to + these problems. + +9.1 Scalability + + It is widely recognized that this protocol does not scale + sufficiently well when used in a large arena. The main problem comes + from the requirement that all servers know about all other servers + and users and that information regarding them be updated as soon as + it changes. It is also desirable to keep the number of servers low + so that the path length between any two points is kept minimal and + the spanning tree as strongly branched as possible. + +9.2 Labels + + The current IRC protocol has 3 types of labels: the nickname, the + channel name and the server name. Each of the three types has its + own domain and no duplicates are allowed inside that domain. + Currently, it is possible for users to pick the label for any of the + three, resulting in collisions. It is widely recognized that this + needs reworking, with a plan for unique names for channels and nicks + that don't collide being desirable as well as a solution allowing a + cyclic tree. + +9.2.1 Nicknames + + The idea of the nickname on IRC is very convenient for users to use + when talking to each other outside of a channel, but there is only a + finite nickname space and being what they are, its not uncommon for + several people to want to use the same nick. If a nickname is chosen + by two people using this protocol, either one will not succeed or + + both will removed by use of KILL (4.6.1). + +9.2.2 Channels + + The current channel layout requires that all servers know about all + channels, their inhabitants and properties. Besides not scaling + well, the issue of privacy is also a concern. A collision of + channels is treated as an inclusive event (both people who create the + new channel are considered to be members of it) rather than an + exclusive one such as used to solve nickname collisions. + +9.2.3 Servers + + Although the number of servers is usually small relative to the + number of users and channels, they two currently required to be known + globally, either each one separately or hidden behind a mask. + +9.3 Algorithms + + In some places within the server code, it has not been possible to + avoid N^2 algorithms such as checking the channel list of a set + of clients. + + In current server versions, there are no database consistency checks, + each server assumes that a neighbouring server is correct. This + opens the door to large problems if a connecting server is buggy or + otherwise tries to introduce contradictions to the existing net. + + Currently, because of the lack of unique internal and global labels, + there are a multitude of race conditions that exist. These race + conditions generally arise from the problem of it taking time for + messages to traverse and effect the IRC network. Even by changing to + unique labels, there are problems with channel-related commands being + disrupted. + +10. Current support and availability + + Mailing lists for IRC related discussion: + Future protocol: ircd-three-request@eff.org + General discussion: operlist-request@eff.org + + Software implemenations + cs.bu.edu:/irc + nic.funet.fi:/pub/irc + coombs.anu.edu.au:/pub/irc + + Newsgroup: alt.irc + +Security Considerations + + Security issues are discussed in sections 4.1, 4.1.1, 4.1.3, 5.5, and + 7. + +12. Authors' Addresses + + Jarkko Oikarinen + Tuirantie 17 as 9 + 90500 OULU + FINLAND + + Email: jto@tolsun.oulu.fi + + Darren Reed + 4 Pateman Street + Watsonia, Victoria 3087 + Australia + + Email: avalon@coombs.anu.edu.au diff --git a/doc/technical/rfc2812.txt b/doc/technical/rfc2812.txt new file mode 100644 index 0000000..3a77c66 --- /dev/null +++ b/doc/technical/rfc2812.txt @@ -0,0 +1,2916 @@ +$Id$ + +Network Working Group C. Kalt +Request for Comments: 2812 April 2000 +Updates: 1459 +Category: Informational + + Internet Relay Chat: Client Protocol + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +IESG NOTE: + + The IRC protocol itself enables several possibilities of transferring + data between clients, and just like with other transfer mechanisms + like email, the receiver of the data has to be careful about how the + data is handled. For more information on security issues with the IRC + protocol, see for example http://www.irchelp.org/irchelp/security/. + +Abstract + + The IRC (Internet Relay Chat) protocol is for use with text based + conferencing; the simplest client being any socket program capable of + connecting to the server. + + This document defines the Client Protocol, and assumes that the + reader is familiar with the IRC Architecture [IRC-ARCH]. + +Table of Contents + + 1. Labels ..................................................... 3 + 1.1 Servers ................................................ 3 + 1.2 Clients ................................................ 3 + 1.2.1 Users ............................................. 4 + 1.2.1.1 Operators .................................... 4 + 1.2.2 Services .......................................... 4 + 1.3 Channels ............................................... 4 + 2. The IRC Client Specification ............................... 5 + 2.1 Overview ............................................... 5 + 2.2 Character codes ........................................ 5 + 2.3 Messages ............................................... 5 + + 2.3.1 Message format in Augmented BNF ................... 6 + 2.4 Numeric replies ........................................ 8 + 2.5 Wildcard expressions ................................... 9 + 3. Message Details ............................................ 9 + 3.1 Connection Registration ................................ 10 + 3.1.1 Password message .................................. 10 + 3.1.2 Nick message ...................................... 10 + 3.1.3 User message ...................................... 11 + 3.1.4 Oper message ...................................... 12 + 3.1.5 User mode message ................................. 12 + 3.1.6 Service message ................................... 13 + 3.1.7 Quit .............................................. 14 + 3.1.8 Squit ............................................. 15 + 3.2 Channel operations ..................................... 15 + 3.2.1 Join message ...................................... 16 + 3.2.2 Part message ...................................... 17 + 3.2.3 Channel mode message .............................. 18 + 3.2.4 Topic message ..................................... 19 + 3.2.5 Names message ..................................... 20 + 3.2.6 List message ...................................... 21 + 3.2.7 Invite message .................................... 21 + 3.2.8 Kick command ...................................... 22 + 3.3 Sending messages ....................................... 23 + 3.3.1 Private messages .................................. 23 + 3.3.2 Notice ............................................ 24 + 3.4 Server queries and commands ............................ 25 + 3.4.1 Motd message ...................................... 25 + 3.4.2 Lusers message .................................... 25 + 3.4.3 Version message ................................... 26 + 3.4.4 Stats message ..................................... 26 + 3.4.5 Links message ..................................... 27 + 3.4.6 Time message ...................................... 28 + 3.4.7 Connect message ................................... 28 + 3.4.8 Trace message ..................................... 29 + 3.4.9 Admin command ..................................... 30 + 3.4.10 Info command ...................................... 31 + 3.5 Service Query and Commands ............................. 31 + 3.5.1 Servlist message .................................. 31 + 3.5.2 Squery ............................................ 32 + 3.6 User based queries ..................................... 32 + 3.6.1 Who query ......................................... 32 + 3.6.2 Whois query ....................................... 33 + 3.6.3 Whowas ............................................ 34 + 3.7 Miscellaneous messages ................................. 34 + 3.7.1 Kill message ...................................... 35 + 3.7.2 Ping message ...................................... 36 + 3.7.3 Pong message ...................................... 37 + 3.7.4 Error ............................................. 37 + + 4. Optional features .......................................... 38 + 4.1 Away ................................................... 38 + 4.2 Rehash message ......................................... 39 + 4.3 Die message ............................................ 39 + 4.4 Restart message ........................................ 40 + 4.5 Summon message ......................................... 40 + 4.6 Users .................................................. 41 + 4.7 Operwall message ....................................... 41 + 4.8 Userhost message ....................................... 42 + 4.9 Ison message ........................................... 42 + 5. Replies .................................................... 43 + 5.1 Command responses ...................................... 43 + 5.2 Error Replies .......................................... 53 + 5.3 Reserved numerics ...................................... 59 + 6. Current implementations .................................... 60 + 7. Current problems ........................................... 60 + 7.1 Nicknames .............................................. 60 + 7.2 Limitation of wildcards ................................ 61 + 7.3 Security considerations ................................ 61 + 8. Current support and availability ........................... 61 + 9. Acknowledgements ........................................... 61 + 10. References ................................................ 62 + 11. Author's Address .......................................... 62 + 12. Full Copyright Statement .................................. 63 + +1. Labels + + This section defines the identifiers used for the various components + of the IRC protocol. + +1.1 Servers + + Servers are uniquely identified by their name, which has a maximum + length of sixty three (63) characters. See the protocol grammar + rules (section 2.3.1) for what may and may not be used in a server + name. + +1.2 Clients + + For each client all servers MUST have the following information: a + netwide unique identifier (whose format depends on the type of + client) and the server which introduced the client. + +1.2.1 Users + + Each user is distinguished from other users by a unique nickname + having a maximum length of nine (9) characters. See the protocol + grammar rules (section 2.3.1) for what may and may not be used in a + nickname. + + While the maximum length is limited to nine characters, clients + SHOULD accept longer strings as they may become used in future + evolutions of the protocol. + +1.2.1.1 Operators + + To allow a reasonable amount of order to be kept within the IRC + network, a special class of users (operators) is allowed to perform + general maintenance functions on the network. Although the powers + granted to an operator can be considered as 'dangerous', they are + nonetheless often necessary. Operators SHOULD be able to perform + basic network tasks such as disconnecting and reconnecting servers as + needed. In recognition of this need, the protocol discussed herein + provides for operators only to be able to perform such functions. + See sections 3.1.8 (SQUIT) and 3.4.7 (CONNECT). + + A more controversial power of operators is the ability to remove a + user from the connected network by 'force', i.e., operators are able + to close the connection between any client and server. The + justification for this is very delicate since its abuse is both + destructive and annoying, and its benefits close to inexistent. For + further details on this type of action, see section 3.7.1 (KILL). + +1.2.2 Services + + Each service is distinguished from other services by a service name + composed of a nickname and a server name. As for users, the nickname + has a maximum length of nine (9) characters. See the protocol + grammar rules (section 2.3.1) for what may and may not be used in a + nickname. + +1.3 Channels + + Channels names are strings (beginning with a '&', '#', '+' or '!' + character) of length up to fifty (50) characters. Apart from the + requirement that the first character is either '&', '#', '+' or '!', + the only restriction on a channel name is that it SHALL NOT contain + any spaces (' '), a control G (^G or ASCII 7), a comma (','). Space + is used as parameter separator and command is used as a list item + separator by the protocol). A colon (':') can also be used as a + delimiter for the channel mask. Channel names are case insensitive. + + See the protocol grammar rules (section 2.3.1) for the exact syntax + of a channel name. + + Each prefix characterizes a different channel type. The definition + of the channel types is not relevant to the client-server protocol + and thus it is beyond the scope of this document. More details can + be found in "Internet Relay Chat: Channel Management" [IRC-CHAN]. + +2. The IRC Client Specification + +2.1 Overview + + The protocol as described herein is for use only with client to + server connections when the client registers as a user. + +2.2 Character codes + + No specific character set is specified. The protocol is based on a + set of codes which are composed of eight (8) bits, making up an + octet. Each message may be composed of any number of these octets; + however, some octet values are used for control codes, which act as + message delimiters. + + Regardless of being an 8-bit protocol, the delimiters and keywords + are such that protocol is mostly usable from US-ASCII terminal and a + telnet connection. + + Because of IRC's Scandinavian origin, the characters {}|^ are + considered to be the lower case equivalents of the characters []\~, + respectively. This is a critical issue when determining the + equivalence of two nicknames or channel names. + +2.3 Messages + + Servers and clients send each other messages, which may or may not + generate a reply. If the message contains a valid command, as + described in later sections, the client should expect a reply as + specified but it is not advised to wait forever for the reply; client + to server and server to server communication is essentially + asynchronous by nature. + + Each IRC message may consist of up to three main parts: the prefix + (OPTIONAL), the command, and the command parameters (maximum of + fifteen (15)). The prefix, command, and all parameters are separated + by one ASCII space character (0x20) each. + + The presence of a prefix is indicated with a single leading ASCII + colon character (':', 0x3b), which MUST be the first character of the + message itself. There MUST be NO gap (whitespace) between the colon + and the prefix. The prefix is used by servers to indicate the true + origin of the message. If the prefix is missing from the message, it + is assumed to have originated from the connection from which it was + received from. Clients SHOULD NOT use a prefix when sending a + message; if they use one, the only valid prefix is the registered + nickname associated with the client. + + The command MUST either be a valid IRC command or a three (3) digit + number represented in ASCII text. + + IRC messages are always lines of characters terminated with a CR-LF + (Carriage Return - Line Feed) pair, and these messages SHALL NOT + exceed 512 characters in length, counting all characters including + the trailing CR-LF. Thus, there are 510 characters maximum allowed + for the command and its parameters. There is no provision for + continuation of message lines. See section 6 for more details about + current implementations. + +2.3.1 Message format in Augmented BNF + + The protocol messages must be extracted from the contiguous stream of + octets. The current solution is to designate two characters, CR and + LF, as message separators. Empty messages are silently ignored, + which permits use of the sequence CR-LF between messages without + extra problems. + + The extracted message is parsed into the components <prefix>, + <command> and list of parameters (<params>). + + The Augmented BNF representation for this is: + + message = [ ":" prefix SPACE ] command [ params ] crlf + prefix = servername / ( nickname [ [ "!" user ] "@" host ] ) + command = 1*letter / 3digit + params = *14( SPACE middle ) [ SPACE ":" trailing ] + =/ 14( SPACE middle ) [ SPACE [ ":" ] trailing ] + + nospcrlfcl = %x01-09 / %x0B-0C / %x0E-1F / %x21-39 / %x3B-FF + ; any octet except NUL, CR, LF, " " and ":" + middle = nospcrlfcl *( ":" / nospcrlfcl ) + trailing = *( ":" / " " / nospcrlfcl ) + + SPACE = %x20 ; space character + crlf = %x0D %x0A ; "carriage return" "linefeed" + + NOTES: + 1) After extracting the parameter list, all parameters are equal + whether matched by <middle> or <trailing>. <trailing> is just a + syntactic trick to allow SPACE within the parameter. + + 2) The NUL (%x00) character is not special in message framing, and + basically could end up inside a parameter, but it would cause + extra complexities in normal C string handling. Therefore, NUL + is not allowed within messages. + + Most protocol messages specify additional semantics and syntax for + the extracted parameter strings dictated by their position in the + list. For example, many server commands will assume that the first + parameter after the command is the list of targets, which can be + described with: + + target = nickname / server + msgtarget = msgto *( "," msgto ) + msgto = channel / ( user [ "%" host ] "@" servername ) + msgto =/ ( user "%" host ) / targetmask + msgto =/ nickname / ( nickname "!" user "@" host ) + channel = ( "#" / "+" / ( "!" channelid ) / "&" ) chanstring + [ ":" chanstring ] + servername = hostname + host = hostname / hostaddr + hostname = shortname *( "." shortname ) + shortname = ( letter / digit ) *( letter / digit / "-" ) + *( letter / digit ) + ; as specified in RFC 1123 [HNAME] + hostaddr = ip4addr / ip6addr + ip4addr = 1*3digit "." 1*3digit "." 1*3digit "." 1*3digit + ip6addr = 1*hexdigit 7( ":" 1*hexdigit ) + ip6addr =/ "0:0:0:0:0:" ( "0" / "FFFF" ) ":" ip4addr + nickname = ( letter / special ) *8( letter / digit / special / "-" ) + targetmask = ( "$" / "#" ) mask + ; see details on allowed masks in section 3.3.1 + chanstring = %x01-07 / %x08-09 / %x0B-0C / %x0E-1F / %x21-2B + chanstring =/ %x2D-39 / %x3B-FF + ; any octet except NUL, BELL, CR, LF, " ", "," and ":" + channelid = 5( %x41-5A / digit ) ; 5( A-Z / 0-9 ) + + Other parameter syntaxes are: + + user = 1*( %x01-09 / %x0B-0C / %x0E-1F / %x21-3F / %x41-FF ) + ; any octet except NUL, CR, LF, " " and "@" + key = 1*23( %x01-05 / %x07-08 / %x0C / %x0E-1F / %x21-7F ) + ; any 7-bit US_ASCII character, + ; except NUL, CR, LF, FF, h/v TABs, and " " + letter = %x41-5A / %x61-7A ; A-Z / a-z + digit = %x30-39 ; 0-9 + hexdigit = digit / "A" / "B" / "C" / "D" / "E" / "F" + special = %x5B-60 / %x7B-7D + ; "[", "]", "\", "`", "_", "^", "{", "|", "}" + + NOTES: + 1) The <hostaddr> syntax is given here for the sole purpose of + indicating the format to follow for IP addresses. This + reflects the fact that the only available implementations of + this protocol uses TCP/IP as underlying network protocol but is + not meant to prevent other protocols to be used. + + 2) <hostname> has a maximum length of 63 characters. This is a + limitation of the protocol as internet hostnames (in + particular) can be longer. Such restriction is necessary + because IRC messages are limited to 512 characters in length. + Clients connecting from a host which name is longer than 63 + characters are registered using the host (numeric) address + instead of the host name. + + 3) Some parameters used in the following sections of this + documents are not defined here as there is nothing specific + about them besides the name that is used for convenience. + These parameters follow the general syntax defined for + <params>. + +2.4 Numeric replies + + Most of the messages sent to the server generate a reply of some + sort. The most common reply is the numeric reply, used for both + errors and normal replies. The numeric reply MUST be sent as one + message consisting of the sender prefix, the three-digit numeric, and + the target of the reply. A numeric reply is not allowed to originate + from a client. In all other respects, a numeric reply is just like a + normal message, except that the keyword is made up of 3 numeric + digits rather than a string of letters. A list of different replies + is supplied in section 5 (Replies). + +2.5 Wildcard expressions + + When wildcards are allowed in a string, it is referred as a "mask". + + For string matching purposes, the protocol allows the use of two + special characters: '?' (%x3F) to match one and only one character, + and '*' (%x2A) to match any number of any characters. These two + characters can be escaped using the character '\' (%x5C). + + The Augmented BNF syntax for this is: + + mask = *( nowild / noesc wildone / noesc wildmany ) + wildone = %x3F + wildmany = %x2A + nowild = %x01-29 / %x2B-3E / %x40-FF + ; any octet except NUL, "*", "?" + noesc = %x01-5B / %x5D-FF + ; any octet except NUL and "\" + matchone = %x01-FF + ; matches wildone + matchmany = *matchone + ; matches wildmany + + Examples: + + a?c ; Matches any string of 3 characters in length starting + with "a" and ending with "c" + + a*c ; Matches any string of at least 2 characters in length + starting with "a" and ending with "c" + +3. Message Details + + On the following pages there are descriptions of each message + recognized by the IRC server and client. All commands described in + this section MUST be implemented by any server for this protocol. + + Where the reply ERR_NOSUCHSERVER is returned, it means that the + target of the message could not be found. The server MUST NOT send + any other replies after this error for that command. + + The server to which a client is connected is required to parse the + complete message, and return any appropriate errors. + + If multiple parameters is presented, then each MUST be checked for + validity and appropriate responses MUST be sent back to the client. + In the case of incorrect messages which use parameter lists with + comma as an item separator, a reply MUST be sent for each item. + +3.1 Connection Registration + + The commands described here are used to register a connection with an + IRC server as a user as well as to correctly disconnect. + + A "PASS" command is not required for a client connection to be + registered, but it MUST precede the latter of the NICK/USER + combination (for a user connection) or the SERVICE command (for a + service connection). The RECOMMENDED order for a client to register + is as follows: + + 1. Pass message + 2. Nick message 2. Service message + 3. User message + + Upon success, the client will receive an RPL_WELCOME (for users) or + RPL_YOURESERVICE (for services) message indicating that the + connection is now registered and known the to the entire IRC network. + The reply message MUST contain the full client identifier upon which + it was registered. + +3.1.1 Password message + + Command: PASS + Parameters: <password> + + The PASS command is used to set a 'connection password'. The + optional password can and MUST be set before any attempt to register + the connection is made. Currently this requires that user send a + PASS command before sending the NICK/USER combination. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED + + Example: + + PASS secretpasswordhere + +3.1.2 Nick message + + Command: NICK + Parameters: <nickname> + + NICK command is used to give user a nickname or change the existing + one. + + Numeric Replies: + + ERR_NONICKNAMEGIVEN ERR_ERRONEUSNICKNAME + ERR_NICKNAMEINUSE ERR_NICKCOLLISION + ERR_UNAVAILRESOURCE ERR_RESTRICTED + + Examples: + + NICK Wiz ; Introducing new nick "Wiz" if session is + still unregistered, or user changing his + nickname to "Wiz" + + :WiZ!jto@tolsun.oulu.fi NICK Kilroy + ; Server telling that WiZ changed his + nickname to Kilroy. + +3.1.3 User message + + Command: USER + Parameters: <user> <mode> <unused> <realname> + + The USER command is used at the beginning of connection to specify + the username, hostname and realname of a new user. + + The <mode> parameter should be a numeric, and can be used to + automatically set user modes when registering with the server. This + parameter is a bitmask, with only 2 bits having any signification: if + the bit 2 is set, the user mode 'w' will be set and if the bit 3 is + set, the user mode 'i' will be set. (See Section 3.1.5 "User + Modes"). + + The <realname> may contain space characters. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED + + Example: + + USER guest 0 * :Ronnie Reagan ; User registering themselves with a + username of "guest" and real name + "Ronnie Reagan". + + USER guest 8 * :Ronnie Reagan ; User registering themselves with a + username of "guest" and real name + "Ronnie Reagan", and asking to be set + invisible. + +3.1.4 Oper message + + Command: OPER + Parameters: <name> <password> + + A normal user uses the OPER command to obtain operator privileges. + The combination of <name> and <password> are REQUIRED to gain + Operator privileges. Upon success, the user will receive a MODE + message (see section 3.1.5) indicating the new user modes. + + Numeric Replies: + + ERR_NEEDMOREPARAMS RPL_YOUREOPER + ERR_NOOPERHOST ERR_PASSWDMISMATCH + + Example: + + OPER foo bar ; Attempt to register as an operator + using a username of "foo" and "bar" + as the password. + +3.1.5 User mode message + + Command: MODE + Parameters: <nickname> + *( ( "+" / "-" ) *( "i" / "w" / "o" / "O" / "r" ) ) + + The user MODE's are typically changes which affect either how the + client is seen by others or what 'extra' messages the client is sent. + + A user MODE command MUST only be accepted if both the sender of the + message and the nickname given as a parameter are both the same. If + no other parameter is given, then the server will return the current + settings for the nick. + + The available modes are as follows: + + a - user is flagged as away; + i - marks a users as invisible; + w - user receives wallops; + r - restricted user connection; + o - operator flag; + O - local operator flag; + s - marks a user for receipt of server notices. + + Additional modes may be available later on. + + The flag 'a' SHALL NOT be toggled by the user using the MODE command, + instead use of the AWAY command is REQUIRED. + + If a user attempts to make themselves an operator using the "+o" or + "+O" flag, the attempt SHOULD be ignored as users could bypass the + authentication mechanisms of the OPER command. There is no + restriction, however, on anyone `deopping' themselves (using "-o" or + "-O"). + + On the other hand, if a user attempts to make themselves unrestricted + using the "-r" flag, the attempt SHOULD be ignored. There is no + restriction, however, on anyone `deopping' themselves (using "+r"). + This flag is typically set by the server upon connection for + administrative reasons. While the restrictions imposed are left up + to the implementation, it is typical that a restricted user not be + allowed to change nicknames, nor make use of the channel operator + status on channels. + + The flag 's' is obsolete but MAY still be used. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_USERSDONTMATCH + ERR_UMODEUNKNOWNFLAG RPL_UMODEIS + + Examples: + + MODE WiZ -w ; Command by WiZ to turn off + reception of WALLOPS messages. + + MODE Angel +i ; Command from Angel to make herself + invisible. + + MODE WiZ -o ; WiZ 'deopping' (removing operator + status). + +3.1.6 Service message + + Command: SERVICE + Parameters: <nickname> <reserved> <distribution> <type> + <reserved> <info> + + The SERVICE command to register a new service. Command parameters + specify the service nickname, distribution, type and info of a new + service. + + The <distribution> parameter is used to specify the visibility of a + service. The service may only be known to servers which have a name + matching the distribution. For a matching server to have knowledge + of the service, the network path between that server and the server + on which the service is connected MUST be composed of servers which + names all match the mask. + + The <type> parameter is currently reserved for future usage. + + Numeric Replies: + + ERR_ALREADYREGISTRED ERR_NEEDMOREPARAMS + ERR_ERRONEUSNICKNAME + RPL_YOURESERVICE RPL_YOURHOST + RPL_MYINFO + + Example: + + SERVICE dict * *.fr 0 0 :French Dictionary ; Service registering + itself with a name of "dict". This + service will only be available on + servers which name matches "*.fr". + +3.1.7 Quit + + Command: QUIT + Parameters: [ <Quit Message> ] + + A client session is terminated with a quit message. The server + acknowledges this by sending an ERROR message to the client. + + Numeric Replies: + + None. + + Example: + + QUIT :Gone to have lunch ; Preferred message format. + + :syrk!kalt@millennium.stealth.net QUIT :Gone to have lunch ; User + syrk has quit IRC to have lunch. + +3.1.8 Squit + + Command: SQUIT + Parameters: <server> <comment> + + The SQUIT command is available only to operators. It is used to + disconnect server links. Also servers can generate SQUIT messages on + error conditions. A SQUIT message may also target a remote server + connection. In this case, the SQUIT message will simply be sent to + the remote server without affecting the servers in between the + operator and the remote server. + + The <comment> SHOULD be supplied by all operators who execute a SQUIT + for a remote server. The server ordered to disconnect its peer + generates a WALLOPS message with <comment> included, so that other + users may be aware of the reason of this action. + + Numeric replies: + + ERR_NOPRIVILEGES ERR_NOSUCHSERVER + ERR_NEEDMOREPARAMS + + Examples: + + SQUIT tolsun.oulu.fi :Bad Link ? ; Command to uplink of the server + tolson.oulu.fi to terminate its + connection with comment "Bad Link". + + :Trillian SQUIT cm22.eng.umd.edu :Server out of control ; Command + from Trillian from to disconnect + "cm22.eng.umd.edu" from the net with + comment "Server out of control". + +3.2 Channel operations + + This group of messages is concerned with manipulating channels, their + properties (channel modes), and their contents (typically users). + For this reason, these messages SHALL NOT be made available to + services. + + All of these messages are requests which will or will not be granted + by the server. The server MUST send a reply informing the user + whether the request was granted, denied or generated an error. When + the server grants the request, the message is typically sent back + (eventually reformatted) to the user with the prefix set to the user + itself. + + The rules governing how channels are managed are enforced by the + servers. These rules are beyond the scope of this document. More + details are found in "Internet Relay Chat: Channel Management" [IRC- + CHAN]. + +3.2.1 Join message + + Command: JOIN + Parameters: ( <channel> *( "," <channel> ) [ <key> *( "," <key> ) ] ) + / "0" + + The JOIN command is used by a user to request to start listening to + the specific channel. Servers MUST be able to parse arguments in the + form of a list of target, but SHOULD NOT use lists when sending JOIN + messages to clients. + + Once a user has joined a channel, he receives information about + all commands his server receives affecting the channel. This + includes JOIN, MODE, KICK, PART, QUIT and of course PRIVMSG/NOTICE. + This allows channel members to keep track of the other channel + members, as well as channel modes. + + If a JOIN is successful, the user receives a JOIN message as + confirmation and is then sent the channel's topic (using RPL_TOPIC) and + the list of users who are on the channel (using RPL_NAMREPLY), which + MUST include the user joining. + + Note that this message accepts a special argument ("0"), which is + a special request to leave all channels the user is currently a member + of. The server will process this message as if the user had sent + a PART command (See Section 3.2.2) for each channel he is a member + of. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_BANNEDFROMCHAN + ERR_INVITEONLYCHAN ERR_BADCHANNELKEY + ERR_CHANNELISFULL ERR_BADCHANMASK + ERR_NOSUCHCHANNEL ERR_TOOMANYCHANNELS + ERR_TOOMANYTARGETS ERR_UNAVAILRESOURCE + RPL_TOPIC + + Examples: + + JOIN #foobar ; Command to join channel #foobar. + + JOIN &foo fubar ; Command to join channel &foo using + key "fubar". + + JOIN #foo,&bar fubar ; Command to join channel #foo using + key "fubar" and &bar using no key. + + JOIN #foo,#bar fubar,foobar ; Command to join channel #foo using + key "fubar", and channel #bar using + key "foobar". + + JOIN #foo,#bar ; Command to join channels #foo and + #bar. + + JOIN 0 ; Leave all currently joined + channels. + + :WiZ!jto@tolsun.oulu.fi JOIN #Twilight_zone ; JOIN message from WiZ + on channel #Twilight_zone + +3.2.2 Part message + + Command: PART + Parameters: <channel> *( "," <channel> ) [ <Part Message> ] + + The PART command causes the user sending the message to be removed + from the list of active members for all given channels listed in the + parameter string. If a "Part Message" is given, this will be sent + instead of the default message, the nickname. This request is always + granted by the server. + + Servers MUST be able to parse arguments in the form of a list of + target, but SHOULD NOT use lists when sending PART messages to + clients. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL + ERR_NOTONCHANNEL + + Examples: + + PART #twilight_zone ; Command to leave channel + "#twilight_zone" + + PART #oz-ops,&group5 ; Command to leave both channels + "&group5" and "#oz-ops". + + :WiZ!jto@tolsun.oulu.fi PART #playzone :I lost + ; User WiZ leaving channel + "#playzone" with the message "I + lost". + +3.2.3 Channel mode message + + Command: MODE + Parameters: <channel> *( ( "-" / "+" ) *<modes> *<modeparams> ) + + The MODE command is provided so that users may query and change the + characteristics of a channel. For more details on available modes + and their uses, see "Internet Relay Chat: Channel Management" [IRC- + CHAN]. Note that there is a maximum limit of three (3) changes per + command for modes that take a parameter. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_KEYSET + ERR_NOCHANMODES ERR_CHANOPRIVSNEEDED + ERR_USERNOTINCHANNEL ERR_UNKNOWNMODE + RPL_CHANNELMODEIS + RPL_BANLIST RPL_ENDOFBANLIST + RPL_EXCEPTLIST RPL_ENDOFEXCEPTLIST + RPL_INVITELIST RPL_ENDOFINVITELIST + RPL_UNIQOPIS + + The following examples are given to help understanding the syntax of + the MODE command, but refer to modes defined in "Internet Relay Chat: + Channel Management" [IRC-CHAN]. + + Examples: + + MODE #Finnish +imI *!*@*.fi ; Command to make #Finnish channel + moderated and 'invite-only' with user + with a hostname matching *.fi + automatically invited. + + MODE #Finnish +o Kilroy ; Command to give 'chanop' privileges + to Kilroy on channel #Finnish. + + MODE #Finnish +v Wiz ; Command to allow WiZ to speak on + #Finnish. + + MODE #Fins -s ; Command to remove 'secret' flag + from channel #Fins. + + MODE #42 +k oulu ; Command to set the channel key to + "oulu". + + MODE #42 -k oulu ; Command to remove the "oulu" + channel key on channel "#42". + + MODE #eu-opers +l 10 ; Command to set the limit for the + number of users on channel + "#eu-opers" to 10. + + :WiZ!jto@tolsun.oulu.fi MODE #eu-opers -l + ; User "WiZ" removing the limit for + the number of users on channel "#eu- + opers". + + MODE &oulu +b ; Command to list ban masks set for + the channel "&oulu". + + MODE &oulu +b *!*@* ; Command to prevent all users from + joining. + + MODE &oulu +b *!*@*.edu +e *!*@*.bu.edu + ; Command to prevent any user from a + hostname matching *.edu from joining, + except if matching *.bu.edu + + MODE #bu +be *!*@*.edu *!*@*.bu.edu + ; Comment to prevent any user from a + hostname matching *.edu from joining, + except if matching *.bu.edu + + MODE #meditation e ; Command to list exception masks set + for the channel "#meditation". + + MODE #meditation I ; Command to list invitations masks + set for the channel "#meditation". + + MODE !12345ircd O ; Command to ask who the channel + creator for "!12345ircd" is + +3.2.4 Topic message + + Command: TOPIC + Parameters: <channel> [ <topic> ] + + The TOPIC command is used to change or view the topic of a channel. + The topic for channel <channel> is returned if there is no <topic> + given. If the <topic> parameter is present, the topic for that + channel will be changed, if this action is allowed for the user + requesting it. If the <topic> parameter is an empty string, the + topic for that channel will be removed. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOTONCHANNEL + RPL_NOTOPIC RPL_TOPIC + ERR_CHANOPRIVSNEEDED ERR_NOCHANMODES + + Examples: + + :WiZ!jto@tolsun.oulu.fi TOPIC #test :New topic ; User Wiz setting the + topic. + + TOPIC #test :another topic ; Command to set the topic on #test + to "another topic". + + TOPIC #test : ; Command to clear the topic on + #test. + + TOPIC #test ; Command to check the topic for + #test. + +3.2.5 Names message + + Command: NAMES + Parameters: [ <channel> *( "," <channel> ) [ <target> ] ] + + By using the NAMES command, a user can list all nicknames that are + visible to him. For more details on what is visible and what is not, + see "Internet Relay Chat: Channel Management" [IRC-CHAN]. The + <channel> parameter specifies which channel(s) to return information + about. There is no error reply for bad channel names. + + If no <channel> parameter is given, a list of all channels and their + occupants is returned. At the end of this list, a list of users who + are visible but either not on any channel or not on a visible channel + are listed as being on `channel' "*". + + If the <target> parameter is specified, the request is forwarded to + that server which will generate the reply. + + Wildcards are allowed in the <target> parameter. + + Numerics: + + ERR_TOOMANYMATCHES ERR_NOSUCHSERVER + RPL_NAMREPLY RPL_ENDOFNAMES + + Examples: + + NAMES #twilight_zone,#42 ; Command to list visible users on + #twilight_zone and #42 + + NAMES ; Command to list all visible + channels and users + +3.2.6 List message + + Command: LIST + Parameters: [ <channel> *( "," <channel> ) [ <target> ] ] + + The list command is used to list channels and their topics. If the + <channel> parameter is used, only the status of that channel is + displayed. + + If the <target> parameter is specified, the request is forwarded to + that server which will generate the reply. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + + ERR_TOOMANYMATCHES ERR_NOSUCHSERVER + RPL_LIST RPL_LISTEND + + Examples: + + LIST ; Command to list all channels. + + LIST #twilight_zone,#42 ; Command to list channels + #twilight_zone and #42 + +3.2.7 Invite message + + Command: INVITE + Parameters: <nickname> <channel> + + The INVITE command is used to invite a user to a channel. The + parameter <nickname> is the nickname of the person to be invited to + the target channel <channel>. There is no requirement that the + channel the target user is being invited to must exist or be a valid + channel. However, if the channel exists, only members of the channel + are allowed to invite other users. When the channel has invite-only + flag set, only channel operators may issue INVITE command. + + Only the user inviting and the user being invited will receive + notification of the invitation. Other channel members are not + notified. (This is unlike the MODE changes, and is occasionally the + source of trouble for users.) + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHNICK + ERR_NOTONCHANNEL ERR_USERONCHANNEL + ERR_CHANOPRIVSNEEDED + RPL_INVITING RPL_AWAY + + Examples: + + :Angel!wings@irc.org INVITE Wiz #Dust + + ; Message to WiZ when he has been + invited by user Angel to channel + #Dust + + INVITE Wiz #Twilight_Zone ; Command to invite WiZ to + #Twilight_zone + +3.2.8 Kick command + + Command: KICK + Parameters: <channel> *( "," <channel> ) <user> *( "," <user> ) + [<comment>] + + The KICK command can be used to request the forced removal of a user + from a channel. It causes the <user> to PART from the <channel> by + force. For the message to be syntactically correct, there MUST be + either one channel parameter and multiple user parameter, or as many + channel parameters as there are user parameters. If a "comment" is + given, this will be sent instead of the default message, the nickname + of the user issuing the KICK. + + The server MUST NOT send KICK messages with multiple channels or + users to clients. This is necessarily to maintain backward + compatibility with old client software. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL + ERR_BADCHANMASK ERR_CHANOPRIVSNEEDED + ERR_USERNOTINCHANNEL ERR_NOTONCHANNEL + + Examples: + + KICK &Melbourne Matthew ; Command to kick Matthew from + &Melbourne + + KICK #Finnish John :Speaking English + ; Command to kick John from #Finnish + using "Speaking English" as the + reason (comment). + + :WiZ!jto@tolsun.oulu.fi KICK #Finnish John + ; KICK message on channel #Finnish + from WiZ to remove John from channel + +3.3 Sending messages + + The main purpose of the IRC protocol is to provide a base for clients + to communicate with each other. PRIVMSG, NOTICE and SQUERY + (described in Section 3.5 on Service Query and Commands) are the only + messages available which actually perform delivery of a text message + from one client to another - the rest just make it possible and try + to ensure it happens in a reliable and structured manner. + +3.3.1 Private messages + + Command: PRIVMSG + Parameters: <msgtarget> <text to be sent> + + PRIVMSG is used to send private messages between users, as well as to + send messages to channels. <msgtarget> is usually the nickname of + the recipient of the message, or a channel name. + + The <msgtarget> parameter may also be a host mask (#<mask>) or server + mask ($<mask>). In both cases the server will only send the PRIVMSG + to those who have a server or host matching the mask. The mask MUST + have at least 1 (one) "." in it and no wildcards following the last + ".". This requirement exists to prevent people sending messages to + "#*" or "$*", which would broadcast to all users. Wildcards are the + '*' and '?' characters. This extension to the PRIVMSG command is + only available to operators. + + Numeric Replies: + + ERR_NORECIPIENT ERR_NOTEXTTOSEND + ERR_CANNOTSENDTOCHAN ERR_NOTOPLEVEL + ERR_WILDTOPLEVEL ERR_TOOMANYTARGETS + ERR_NOSUCHNICK + RPL_AWAY + + Examples: + + :Angel!wings@irc.org PRIVMSG Wiz :Are you receiving this message ? + ; Message from Angel to Wiz. + + PRIVMSG Angel :yes I'm receiving it ! + ; Command to send a message to Angel. + + PRIVMSG jto@tolsun.oulu.fi :Hello ! + ; Command to send a message to a user + on server tolsun.oulu.fi with + username of "jto". + + PRIVMSG kalt%millennium.stealth.net@irc.stealth.net :Are you a frog? + ; Message to a user on server + irc.stealth.net with username of + "kalt", and connected from the host + millennium.stealth.net. + + PRIVMSG kalt%millennium.stealth.net :Do you like cheese? + ; Message to a user on the local + server with username of "kalt", and + connected from the host + millennium.stealth.net. + + PRIVMSG Wiz!jto@tolsun.oulu.fi :Hello ! + ; Message to the user with nickname + Wiz who is connected from the host + tolsun.oulu.fi and has the username + "jto". + + PRIVMSG $*.fi :Server tolsun.oulu.fi rebooting. + ; Message to everyone on a server + which has a name matching *.fi. + + PRIVMSG #*.edu :NSFNet is undergoing work, expect interruptions + ; Message to all users who come from + a host which has a name matching + *.edu. + +3.3.2 Notice + + Command: NOTICE + Parameters: <msgtarget> <text> + + The NOTICE command is used similarly to PRIVMSG. The difference + between NOTICE and PRIVMSG is that automatic replies MUST NEVER be + sent in response to a NOTICE message. This rule applies to servers + + too - they MUST NOT send any error reply back to the client on + receipt of a notice. The object of this rule is to avoid loops + between clients automatically sending something in response to + something it received. + + This command is available to services as well as users. + + This is typically used by services, and automatons (clients with + either an AI or other interactive program controlling their actions). + + See PRIVMSG for more details on replies and examples. + +3.4 Server queries and commands + + The server query group of commands has been designed to return + information about any server which is connected to the network. + + In these queries, where a parameter appears as <target>, wildcard + masks are usually valid. For each parameter, however, only one query + and set of replies is to be generated. In most cases, if a nickname + is given, it will mean the server to which the user is connected. + + These messages typically have little value for services, it is + therefore RECOMMENDED to forbid services from using them. + +3.4.1 Motd message + + Command: MOTD + Parameters: [ <target> ] + + The MOTD command is used to get the "Message Of The Day" of the given + server, or current server if <target> is omitted. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + RPL_MOTDSTART RPL_MOTD + RPL_ENDOFMOTD ERR_NOMOTD + +3.4.2 Lusers message + + Command: LUSERS + Parameters: [ <mask> [ <target> ] ] + + The LUSERS command is used to get statistics about the size of the + IRC network. If no parameter is given, the reply will be about the + whole net. If a <mask> is specified, then the reply will only + + concern the part of the network formed by the servers matching the + mask. Finally, if the <target> parameter is specified, the request + is forwarded to that server which will generate the reply. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + + RPL_LUSERCLIENT RPL_LUSEROP + RPL_LUSERUNKOWN RPL_LUSERCHANNELS + RPL_LUSERME ERR_NOSUCHSERVER + +3.4.3 Version message + + Command: VERSION + Parameters: [ <target> ] + + The VERSION command is used to query the version of the server + program. An optional parameter <target> is used to query the version + of the server program which a client is not directly connected to. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + + ERR_NOSUCHSERVER RPL_VERSION + + Examples: + + VERSION tolsun.oulu.fi ; Command to check the version of + server "tolsun.oulu.fi". + +3.4.4 Stats message + + Command: STATS + Parameters: [ <query> [ <target> ] ] + + The stats command is used to query statistics of certain server. If + <query> parameter is omitted, only the end of stats reply is sent + back. + + A query may be given for any single letter which is only checked by + the destination server and is otherwise passed on by intermediate + servers, ignored and unaltered. + + Wildcards are allowed in the <target> parameter. + + Except for the ones below, the list of valid queries is + implementation dependent. The standard queries below SHOULD be + supported by the server: + + l - returns a list of the server's connections, showing how + long each connection has been established and the + traffic over that connection in Kbytes and messages for + each direction; + m - returns the usage count for each of commands supported + by the server; commands for which the usage count is + zero MAY be omitted; + o - returns a list of configured privileged users, + operators; + u - returns a string showing how long the server has been + up. + + It is also RECOMMENDED that client and server access configuration be + published this way. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_STATSLINKINFO RPL_STATSUPTIME + RPL_STATSCOMMANDS RPL_STATSOLINE + RPL_ENDOFSTATS + + Examples: + + STATS m ; Command to check the command usage + for the server you are connected to + +3.4.5 Links message + + Command: LINKS + Parameters: [ [ <remote server> ] <server mask> ] + + With LINKS, a user can list all servernames, which are known by the + server answering the query. The returned list of servers MUST match + the mask, or if no mask is given, the full list is returned. + + If <remote server> is given in addition to <server mask>, the LINKS + command is forwarded to the first server found that matches that name + (if any), and that server is then required to answer the query. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_LINKS RPL_ENDOFLINKS + + Examples: + + LINKS *.au ; Command to list all servers which + have a name that matches *.au; + + LINKS *.edu *.bu.edu ; Command to list servers matching + *.bu.edu as seen by the first server + matching *.edu. + +3.4.6 Time message + + Command: TIME + Parameters: [ <target> ] + + The time command is used to query local time from the specified + server. If the <target> parameter is not given, the server receiving + the command must reply to the query. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + + ERR_NOSUCHSERVER RPL_TIME + + Examples: + TIME tolsun.oulu.fi ; check the time on the server + "tolson.oulu.fi" + +3.4.7 Connect message + + Command: CONNECT + Parameters: <target server> <port> [ <remote server> ] + + The CONNECT command can be used to request a server to try to + establish a new connection to another server immediately. CONNECT is + a privileged command and SHOULD be available only to IRC Operators. + If a <remote server> is given and its mask doesn't match name of the + parsing server, the CONNECT attempt is sent to the first match of + remote server. Otherwise the CONNECT attempt is made by the server + processing the request. + + The server receiving a remote CONNECT command SHOULD generate a + WALLOPS message describing the source and target of the request. + + Numeric Replies: + + ERR_NOSUCHSERVER ERR_NOPRIVILEGES + ERR_NEEDMOREPARAMS + + Examples: + + CONNECT tolsun.oulu.fi 6667 ; Command to attempt to connect local + server to tolsun.oulu.fi on port 6667 + +3.4.8 Trace message + + Command: TRACE + Parameters: [ <target> ] + + TRACE command is used to find the route to specific server and + information about its peers. Each server that processes this command + MUST report to the sender about it. The replies from pass-through + links form a chain, which shows route to destination. After sending + this reply back, the query MUST be sent to the next server until + given <target> server is reached. + + TRACE command is used to find the route to specific server. Each + server that processes this message MUST tell the sender about it by + sending a reply indicating it is a pass-through link, forming a chain + of replies. After sending this reply back, it MUST then send the + TRACE message to the next server until given server is reached. If + the <target> parameter is omitted, it is RECOMMENDED that TRACE + command sends a message to the sender telling which servers the local + server has direct connection to. + + If the destination given by <target> is an actual server, the + destination server is REQUIRED to report all servers, services and + operators which are connected to it; if the command was issued by an + operator, the server MAY also report all users which are connected to + it. If the destination given by <target> is a nickname, then only a + reply for that nickname is given. If the <target> parameter is + omitted, it is RECOMMENDED that the TRACE command is parsed as + targeted to the processing server. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + + ERR_NOSUCHSERVER + + If the TRACE message is destined for another server, all + intermediate servers must return a RPL_TRACELINK reply to indicate + that the TRACE passed through it and where it is going next. + + RPL_TRACELINK + + A TRACE reply may be composed of any number of the following + numeric replies. + + RPL_TRACECONNECTING RPL_TRACEHANDSHAKE + RPL_TRACEUNKNOWN RPL_TRACEOPERATOR + RPL_TRACEUSER RPL_TRACESERVER + RPL_TRACESERVICE RPL_TRACENEWTYPE + RPL_TRACECLASS RPL_TRACELOG + RPL_TRACEEND + + Examples: + + TRACE *.oulu.fi ; TRACE to a server matching + *.oulu.fi + +3.4.9 Admin command + + Command: ADMIN + Parameters: [ <target> ] + + The admin command is used to find information about the administrator + of the given server, or current server if <target> parameter is + omitted. Each server MUST have the ability to forward ADMIN messages + to other servers. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_ADMINME RPL_ADMINLOC1 + RPL_ADMINLOC2 RPL_ADMINEMAIL + + Examples: + + ADMIN tolsun.oulu.fi ; request an ADMIN reply from + tolsun.oulu.fi + + ADMIN syrk ; ADMIN request for the server to + which the user syrk is connected + +3.4.10 Info command + + Command: INFO + Parameters: [ <target> ] + + The INFO command is REQUIRED to return information describing the + server: its version, when it was compiled, the patchlevel, when it + was started, and any other miscellaneous information which may be + considered to be relevant. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_INFO RPL_ENDOFINFO + + Examples: + + INFO csd.bu.edu ; request an INFO reply from + csd.bu.edu + + INFO Angel ; request info from the server that + Angel is connected to. + +3.5 Service Query and Commands + + The service query group of commands has been designed to return + information about any service which is connected to the network. + +3.5.1 Servlist message + + Command: SERVLIST + Parameters: [ <mask> [ <type> ] ] + + The SERVLIST command is used to list services currently connected to + the network and visible to the user issuing the command. The + optional parameters may be used to restrict the result of the query + (to matching services names, and services type). + + Numeric Replies: + + RPL_SERVLIST RPL_SERVLISTEND + +3.5.2 Squery + + Command: SQUERY + Parameters: <servicename> <text> + + The SQUERY command is used similarly to PRIVMSG. The only difference + is that the recipient MUST be a service. This is the only way for a + text message to be delivered to a service. + + See PRIVMSG for more details on replies and example. + + Examples: + + SQUERY irchelp :HELP privmsg + ; Message to the service with + nickname irchelp. + + SQUERY dict@irc.fr :fr2en blaireau + ; Message to the service with name + dict@irc.fr. + +3.6 User based queries + + User queries are a group of commands which are primarily concerned + with finding details on a particular user or group users. When using + wildcards with any of these commands, if they match, they will only + return information on users who are 'visible' to you. The visibility + of a user is determined as a combination of the user's mode and the + common set of channels you are both on. + + Although services SHOULD NOT be using this class of message, they are + allowed to. + +3.6.1 Who query + + Command: WHO + Parameters: [ <mask> [ "o" ] ] + + The WHO command is used by a client to generate a query which returns + a list of information which 'matches' the <mask> parameter given by + the client. In the absence of the <mask> parameter, all visible + (users who aren't invisible (user mode +i) and who don't have a + common channel with the requesting client) are listed. The same + result can be achieved by using a <mask> of "0" or any wildcard which + will end up matching every visible user. + + The <mask> passed to WHO is matched against users' host, server, real + name and nickname if the channel <mask> cannot be found. + + If the "o" parameter is passed only operators are returned according + to the <mask> supplied. + + Numeric Replies: + + ERR_NOSUCHSERVER + RPL_WHOREPLY RPL_ENDOFWHO + + Examples: + + WHO *.fi ; Command to list all users who match + against "*.fi". + + WHO jto* o ; Command to list all users with a + match against "jto*" if they are an + operator. + +3.6.2 Whois query + + Command: WHOIS + Parameters: [ <target> ] <mask> *( "," <mask> ) + + This command is used to query information about particular user. + The server will answer this command with several numeric messages + indicating different statuses of each user which matches the mask (if + you are entitled to see them). If no wildcard is present in the + <mask>, any information about that nick which you are allowed to see + is presented. + + If the <target> parameter is specified, it sends the query to a + specific server. It is useful if you want to know how long the user + in question has been idle as only local server (i.e., the server the + user is directly connected to) knows that information, while + everything else is globally known. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + + ERR_NOSUCHSERVER ERR_NONICKNAMEGIVEN + RPL_WHOISUSER RPL_WHOISCHANNELS + RPL_WHOISCHANNELS RPL_WHOISSERVER + RPL_AWAY RPL_WHOISOPERATOR + RPL_WHOISIDLE ERR_NOSUCHNICK + RPL_ENDOFWHOIS + + Examples: + + WHOIS wiz ; return available user information + about nick WiZ + + WHOIS eff.org trillian ; ask server eff.org for user + information about trillian + +3.6.3 Whowas + + Command: WHOWAS + Parameters: <nickname> *( "," <nickname> ) [ <count> [ <target> ] ] + + Whowas asks for information about a nickname which no longer exists. + This may either be due to a nickname change or the user leaving IRC. + In response to this query, the server searches through its nickname + history, looking for any nicks which are lexically the same (no wild + card matching here). The history is searched backward, returning the + most recent entry first. If there are multiple entries, up to + <count> replies will be returned (or all of them if no <count> + parameter is given). If a non-positive number is passed as being + <count>, then a full search is done. + + Wildcards are allowed in the <target> parameter. + + Numeric Replies: + + ERR_NONICKNAMEGIVEN ERR_WASNOSUCHNICK + RPL_WHOWASUSER RPL_WHOISSERVER + RPL_ENDOFWHOWAS + + Examples: + + WHOWAS Wiz ; return all information in the nick + history about nick "WiZ"; + + WHOWAS Mermaid 9 ; return at most, the 9 most recent + entries in the nick history for + "Mermaid"; + + WHOWAS Trillian 1 *.edu ; return the most recent history for + "Trillian" from the first server + found to match "*.edu". + +3.7 Miscellaneous messages + + Messages in this category do not fit into any of the above categories + but are nonetheless still a part of and REQUIRED by the protocol. + +3.7.1 Kill message + + Command: KILL + Parameters: <nickname> <comment> + + The KILL command is used to cause a client-server connection to be + closed by the server which has the actual connection. Servers + generate KILL messages on nickname collisions. It MAY also be + available available to users who have the operator status. + + Clients which have automatic reconnect algorithms effectively make + this command useless since the disconnection is only brief. It does + however break the flow of data and can be used to stop large amounts + of 'flooding' from abusive users or accidents. Abusive users usually + don't care as they will reconnect promptly and resume their abusive + behaviour. To prevent this command from being abused, any user may + elect to receive KILL messages generated for others to keep an 'eye' + on would be trouble spots. + + In an arena where nicknames are REQUIRED to be globally unique at all + times, KILL messages are sent whenever 'duplicates' are detected + (that is an attempt to register two users with the same nickname) in + the hope that both of them will disappear and only 1 reappear. + + When a client is removed as the result of a KILL message, the server + SHOULD add the nickname to the list of unavailable nicknames in an + attempt to avoid clients to reuse this name immediately which is + usually the pattern of abusive behaviour often leading to useless + "KILL loops". See the "IRC Server Protocol" document [IRC-SERVER] + for more information on this procedure. + + The comment given MUST reflect the actual reason for the KILL. For + server-generated KILLs it usually is made up of details concerning + the origins of the two conflicting nicknames. For users it is left + up to them to provide an adequate reason to satisfy others who see + it. To prevent/discourage fake KILLs from being generated to hide + the identify of the KILLer, the comment also shows a 'kill-path' + which is updated by each server it passes through, each prepending + its name to the path. + + Numeric Replies: + + ERR_NOPRIVILEGES ERR_NEEDMOREPARAMS + ERR_NOSUCHNICK ERR_CANTKILLSERVER + + NOTE: + It is RECOMMENDED that only Operators be allowed to kill other users + with KILL command. This command has been the subject of many + controversies over the years, and along with the above + recommendation, it is also widely recognized that not even operators + should be allowed to kill users on remote servers. + +3.7.2 Ping message + + Command: PING + Parameters: <server1> [ <server2> ] + + The PING command is used to test the presence of an active client or + server at the other end of the connection. Servers send a PING + message at regular intervals if no other activity detected coming + from a connection. If a connection fails to respond to a PING + message within a set amount of time, that connection is closed. A + PING message MAY be sent even if the connection is active. + + When a PING message is received, the appropriate PONG message MUST be + sent as reply to <server1> (server which sent the PING message out) + as soon as possible. If the <server2> parameter is specified, it + represents the target of the ping, and the message gets forwarded + there. + + Numeric Replies: + + ERR_NOORIGIN ERR_NOSUCHSERVER + + Examples: + + PING tolsun.oulu.fi ; Command to send a PING message to + server + + PING WiZ tolsun.oulu.fi ; Command from WiZ to send a PING + message to server "tolsun.oulu.fi" + + PING :irc.funet.fi ; Ping message sent by server + "irc.funet.fi" + +3.7.3 Pong message + + Command: PONG + Parameters: <server> [ <server2> ] + + PONG message is a reply to ping message. If parameter <server2> is + given, this message MUST be forwarded to given target. The <server> + parameter is the name of the entity who has responded to PING message + and generated this message. + + Numeric Replies: + + ERR_NOORIGIN ERR_NOSUCHSERVER + + Example: + + PONG csd.bu.edu tolsun.oulu.fi ; PONG message from csd.bu.edu to + tolsun.oulu.fi + +3.7.4 Error + + Command: ERROR + Parameters: <error message> + + The ERROR command is for use by servers when reporting a serious or + fatal error to its peers. It may also be sent from one server to + another but MUST NOT be accepted from any normal unknown clients. + + Only an ERROR message SHOULD be used for reporting errors which occur + with a server-to-server link. An ERROR message is sent to the server + at the other end (which reports it to appropriate local users and + logs) and to appropriate local users and logs. It is not to be + passed onto any other servers by a server if it is received from a + server. + + The ERROR message is also used before terminating a client + connection. + + When a server sends a received ERROR message to its operators, the + message SHOULD be encapsulated inside a NOTICE message, indicating + that the client was not responsible for the error. + + Numerics: + + None. + + Examples: + + ERROR :Server *.fi already exists ; ERROR message to the other server + which caused this error. + + NOTICE WiZ :ERROR from csd.bu.edu -- Server *.fi already exists + ; Same ERROR message as above but + sent to user WiZ on the other server. + +4. Optional features + + This section describes OPTIONAL messages. They are not required in a + working server implementation of the protocol described herein. In + the absence of the feature, an error reply message MUST be generated + or an unknown command error. If the message is destined for another + server to answer then it MUST be passed on (elementary parsing + REQUIRED) The allocated numerics for this are listed with the + messages below. + + From this section, only the USERHOST and ISON messages are available + to services. + +4.1 Away + + Command: AWAY + Parameters: [ <text> ] + + With the AWAY command, clients can set an automatic reply string for + any PRIVMSG commands directed at them (not to a channel they are on). + The server sends an automatic reply to the client sending the PRIVMSG + command. The only replying server is the one to which the sending + client is connected to. + + The AWAY command is used either with one parameter, to set an AWAY + message, or with no parameters, to remove the AWAY message. + + Because of its high cost (memory and bandwidth wise), the AWAY + message SHOULD only be used for client-server communication. A + server MAY choose to silently ignore AWAY messages received from + other servers. To update the away status of a client across servers, + the user mode 'a' SHOULD be used instead. (See Section 3.1.5) + + Numeric Replies: + + RPL_UNAWAY RPL_NOWAWAY + + Example: + + AWAY :Gone to lunch. Back in 5 ; Command to set away message to + "Gone to lunch. Back in 5". + +4.2 Rehash message + + Command: REHASH + Parameters: None + + The rehash command is an administrative command which can be used by + an operator to force the server to re-read and process its + configuration file. + + Numeric Replies: + + RPL_REHASHING ERR_NOPRIVILEGES + + Example: + + REHASH ; message from user with operator + status to server asking it to reread + its configuration file. + +4.3 Die message + + Command: DIE + Parameters: None + + An operator can use the DIE command to shutdown the server. This + message is optional since it may be viewed as a risk to allow + arbitrary people to connect to a server as an operator and execute + this command. + + The DIE command MUST always be fully processed by the server to which + the sending client is connected and MUST NOT be passed onto other + connected servers. + + Numeric Replies: + + ERR_NOPRIVILEGES + + Example: + + DIE ; no parameters required. + +4.4 Restart message + + Command: RESTART + Parameters: None + + An operator can use the restart command to force the server to + restart itself. This message is optional since it may be viewed as a + risk to allow arbitrary people to connect to a server as an operator + and execute this command, causing (at least) a disruption to service. + + The RESTART command MUST always be fully processed by the server to + which the sending client is connected and MUST NOT be passed onto + other connected servers. + + Numeric Replies: + + ERR_NOPRIVILEGES + + Example: + + RESTART ; no parameters required. + +4.5 Summon message + + Command: SUMMON + Parameters: <user> [ <target> [ <channel> ] ] + + The SUMMON command can be used to give users who are on a host + running an IRC server a message asking them to please join IRC. This + message is only sent if the target server (a) has SUMMON enabled, (b) + the user is logged in and (c) the server process can write to the + user's tty (or similar). + + If no <server> parameter is given it tries to summon <user> from the + server the client is connected to is assumed as the target. + + If summon is not enabled in a server, it MUST return the + ERR_SUMMONDISABLED numeric. + + Numeric Replies: + + ERR_NORECIPIENT ERR_FILEERROR + ERR_NOLOGIN ERR_NOSUCHSERVER + ERR_SUMMONDISABLED RPL_SUMMONING + + Examples: + + SUMMON jto ; summon user jto on the server's + host + + SUMMON jto tolsun.oulu.fi ; summon user jto on the host which a + server named "tolsun.oulu.fi" is + running. + +4.6 Users + + Command: USERS + Parameters: [ <target> ] + + The USERS command returns a list of users logged into the server in a + format similar to the UNIX commands who(1), rusers(1) and finger(1). + If disabled, the correct numeric MUST be returned to indicate this. + + Because of the security implications of such a command, it SHOULD be + disabled by default in server implementations. Enabling it SHOULD + require recompiling the server or some equivalent change rather than + simply toggling an option and restarting the server. The procedure + to enable this command SHOULD also include suitable large comments. + + Numeric Replies: + + ERR_NOSUCHSERVER ERR_FILEERROR + RPL_USERSSTART RPL_USERS + RPL_NOUSERS RPL_ENDOFUSERS + ERR_USERSDISABLED + + Disabled Reply: + + ERR_USERSDISABLED + + Example: + + USERS eff.org ; request a list of users logged in + on server eff.org + +4.7 Operwall message + + Command: WALLOPS + Parameters: <Text to be sent> + + The WALLOPS command is used to send a message to all currently + connected users who have set the 'w' user mode for themselves. (See + Section 3.1.5 "User modes"). + + After implementing WALLOPS as a user command it was found that it was + often and commonly abused as a means of sending a message to a lot of + people. Due to this, it is RECOMMENDED that the implementation of + WALLOPS allows and recognizes only servers as the originators of + WALLOPS. + + Numeric Replies: + + ERR_NEEDMOREPARAMS + + Example: + + :csd.bu.edu WALLOPS :Connect '*.uiuc.edu 6667' from Joshua ; WALLOPS + message from csd.bu.edu announcing a + CONNECT message it received from + Joshua and acted upon. + +4.8 Userhost message + + Command: USERHOST + Parameters: <nickname> *( SPACE <nickname> ) + + The USERHOST command takes a list of up to 5 nicknames, each + separated by a space character and returns a list of information + about each nickname that it found. The returned list has each reply + separated by a space. + + Numeric Replies: + + RPL_USERHOST ERR_NEEDMOREPARAMS + + Example: + + USERHOST Wiz Michael syrk ; USERHOST request for information on + nicks "Wiz", "Michael", and "syrk" + + :ircd.stealth.net 302 yournick :syrk=+syrk@millennium.stealth.net + ; Reply for user syrk + +4.9 Ison message + + Command: ISON + Parameters: <nickname> *( SPACE <nickname> ) + + The ISON command was implemented to provide a quick and efficient + means to get a response about whether a given nickname was currently + on IRC. ISON only takes one (1) type of parameter: a space-separated + list of nicks. For each nickname in the list that is present, the + + server adds that to its reply string. Thus the reply string may + return empty (none of the given nicks are present), an exact copy of + the parameter string (all of them present) or any other subset of the + set of nicks given in the parameter. The only limit on the number of + nicks that may be checked is that the combined length MUST NOT be too + large as to cause the server to chop it off so it fits in 512 + characters. + + ISON is only processed by the server local to the client sending the + command and thus not passed onto other servers for further + processing. + + Numeric Replies: + + RPL_ISON ERR_NEEDMOREPARAMS + + Example: + + ISON phone trillian WiZ jarlek Avalon Angel Monstah syrk + ; Sample ISON request for 7 nicks. + +5. Replies + + The following is a list of numeric replies which are generated in + response to the commands given above. Each numeric is given with its + number, name and reply string. + +5.1 Command responses + + Numerics in the range from 001 to 099 are used for client-server + connections only and should never travel between servers. Replies + generated in the response to commands are found in the range from 200 + to 399. + + 001 RPL_WELCOME + "Welcome to the Internet Relay Network + <nick>!<user>@<host>" + 002 RPL_YOURHOST + "Your host is <servername>, running version <ver>" + 003 RPL_CREATED + "This server was created <date>" + 004 RPL_MYINFO + "<servername> <version> <available user modes> + <available channel modes>" + + - The server sends Replies 001 to 004 to a user upon + successful registration. + + 005 RPL_BOUNCE + "Try server <server name>, port <port number>" + + - Sent by the server to a user to suggest an alternative + server. This is often used when the connection is + refused because the server is already full. + + 302 RPL_USERHOST + ":*1<reply> *( " " <reply> )" + + - Reply format used by USERHOST to list replies to + the query list. The reply string is composed as + follows: + + reply = nickname [ "*" ] "=" ( "+" / "-" ) hostname + + The '*' indicates whether the client has registered + as an Operator. The '-' or '+' characters represent + whether the client has set an AWAY message or not + respectively. + + 303 RPL_ISON + ":*1<nick> *( " " <nick> )" + + - Reply format used by ISON to list replies to the + query list. + + 301 RPL_AWAY + "<nick> :<away message>" + 305 RPL_UNAWAY + ":You are no longer marked as being away" + 306 RPL_NOWAWAY + ":You have been marked as being away" + + - These replies are used with the AWAY command (if + allowed). RPL_AWAY is sent to any client sending a + PRIVMSG to a client which is away. RPL_AWAY is only + sent by the server to which the client is connected. + Replies RPL_UNAWAY and RPL_NOWAWAY are sent when the + client removes and sets an AWAY message. + + 311 RPL_WHOISUSER + "<nick> <user> <host> * :<real name>" + 312 RPL_WHOISSERVER + "<nick> <server> :<server info>" + 313 RPL_WHOISOPERATOR + "<nick> :is an IRC operator" + + 317 RPL_WHOISIDLE + "<nick> <integer> :seconds idle" + 318 RPL_ENDOFWHOIS + "<nick> :End of WHOIS list" + 319 RPL_WHOISCHANNELS + "<nick> :*( ( "@" / "+" ) <channel> " " )" + + - Replies 311 - 313, 317 - 319 are all replies + generated in response to a WHOIS message. Given that + there are enough parameters present, the answering + server MUST either formulate a reply out of the above + numerics (if the query nick is found) or return an + error reply. The '*' in RPL_WHOISUSER is there as + the literal character and not as a wild card. For + each reply set, only RPL_WHOISCHANNELS may appear + more than once (for long lists of channel names). + The '@' and '+' characters next to the channel name + indicate whether a client is a channel operator or + has been granted permission to speak on a moderated + channel. The RPL_ENDOFWHOIS reply is used to mark + the end of processing a WHOIS message. + + 314 RPL_WHOWASUSER + "<nick> <user> <host> * :<real name>" + 369 RPL_ENDOFWHOWAS + "<nick> :End of WHOWAS" + + - When replying to a WHOWAS message, a server MUST use + the replies RPL_WHOWASUSER, RPL_WHOISSERVER or + ERR_WASNOSUCHNICK for each nickname in the presented + list. At the end of all reply batches, there MUST + be RPL_ENDOFWHOWAS (even if there was only one reply + and it was an error). + + 321 RPL_LISTSTART + Obsolete. Not used. + + 322 RPL_LIST + "<channel> <# visible> :<topic>" + 323 RPL_LISTEND + ":End of LIST" + + - Replies RPL_LIST, RPL_LISTEND mark the actual replies + with data and end of the server's response to a LIST + command. If there are no channels available to return, + only the end reply MUST be sent. + + 325 RPL_UNIQOPIS + "<channel> <nickname>" + + 324 RPL_CHANNELMODEIS + "<channel> <mode> <mode params>" + + 331 RPL_NOTOPIC + "<channel> :No topic is set" + 332 RPL_TOPIC + "<channel> :<topic>" + + - When sending a TOPIC message to determine the + channel topic, one of two replies is sent. If + the topic is set, RPL_TOPIC is sent back else + RPL_NOTOPIC. + + 341 RPL_INVITING + "<channel> <nick>" + + - Returned by the server to indicate that the + attempted INVITE message was successful and is + being passed onto the end client. + + 342 RPL_SUMMONING + "<user> :Summoning user to IRC" + + - Returned by a server answering a SUMMON message to + indicate that it is summoning that user. + + 346 RPL_INVITELIST + "<channel> <invitemask>" + 347 RPL_ENDOFINVITELIST + "<channel> :End of channel invite list" + + - When listing the 'invitations masks' for a given channel, + a server is required to send the list back using the + RPL_INVITELIST and RPL_ENDOFINVITELIST messages. A + separate RPL_INVITELIST is sent for each active mask. + After the masks have been listed (or if none present) a + RPL_ENDOFINVITELIST MUST be sent. + + 348 RPL_EXCEPTLIST + "<channel> <exceptionmask>" + 349 RPL_ENDOFEXCEPTLIST + "<channel> :End of channel exception list" + + - When listing the 'exception masks' for a given channel, + a server is required to send the list back using the + RPL_EXCEPTLIST and RPL_ENDOFEXCEPTLIST messages. A + separate RPL_EXCEPTLIST is sent for each active mask. + After the masks have been listed (or if none present) + a RPL_ENDOFEXCEPTLIST MUST be sent. + + 351 RPL_VERSION + "<version>.<debuglevel> <server> :<comments>" + + - Reply by the server showing its version details. + The <version> is the version of the software being + used (including any patchlevel revisions) and the + <debuglevel> is used to indicate if the server is + running in "debug mode". + + The "comments" field may contain any comments about + the version or further version details. + + 352 RPL_WHOREPLY + "<channel> <user> <host> <server> <nick> + ( "H" / "G" > ["*"] [ ( "@" / "+" ) ] + :<hopcount> <real name>" + + 315 RPL_ENDOFWHO + "<name> :End of WHO list" + + - The RPL_WHOREPLY and RPL_ENDOFWHO pair are used + to answer a WHO message. The RPL_WHOREPLY is only + sent if there is an appropriate match to the WHO + query. If there is a list of parameters supplied + with a WHO message, a RPL_ENDOFWHO MUST be sent + after processing each list item with <name> being + the item. + + 353 RPL_NAMREPLY + "( "=" / "*" / "@" ) <channel> + :[ "@" / "+" ] <nick> *( " " [ "@" / "+" ] <nick> ) + - "@" is used for secret channels, "*" for private + channels, and "=" for others (public channels). + + 366 RPL_ENDOFNAMES + "<channel> :End of NAMES list" + + - To reply to a NAMES message, a reply pair consisting + of RPL_NAMREPLY and RPL_ENDOFNAMES is sent by the + server back to the client. If there is no channel + found as in the query, then only RPL_ENDOFNAMES is + + returned. The exception to this is when a NAMES + message is sent with no parameters and all visible + channels and contents are sent back in a series of + RPL_NAMEREPLY messages with a RPL_ENDOFNAMES to mark + the end. + + 364 RPL_LINKS + "<mask> <server> :<hopcount> <server info>" + 365 RPL_ENDOFLINKS + "<mask> :End of LINKS list" + + - In replying to the LINKS message, a server MUST send + replies back using the RPL_LINKS numeric and mark the + end of the list using an RPL_ENDOFLINKS reply. + + 367 RPL_BANLIST + "<channel> <banmask>" + 368 RPL_ENDOFBANLIST + "<channel> :End of channel ban list" + + - When listing the active 'bans' for a given channel, + a server is required to send the list back using the + RPL_BANLIST and RPL_ENDOFBANLIST messages. A separate + RPL_BANLIST is sent for each active banmask. After the + banmasks have been listed (or if none present) a + RPL_ENDOFBANLIST MUST be sent. + + 371 RPL_INFO + ":<string>" + 374 RPL_ENDOFINFO + ":End of INFO list" + + - A server responding to an INFO message is required to + send all its 'info' in a series of RPL_INFO messages + with a RPL_ENDOFINFO reply to indicate the end of the + replies. + + 375 RPL_MOTDSTART + ":- <server> Message of the day - " + 372 RPL_MOTD + ":- <text>" + 376 RPL_ENDOFMOTD + ":End of MOTD command" + + - When responding to the MOTD message and the MOTD file + is found, the file is displayed line by line, with + each line no longer than 80 characters, using + + RPL_MOTD format replies. These MUST be surrounded + by a RPL_MOTDSTART (before the RPL_MOTDs) and an + RPL_ENDOFMOTD (after). + + 381 RPL_YOUREOPER + ":You are now an IRC operator" + + - RPL_YOUREOPER is sent back to a client which has + just successfully issued an OPER message and gained + operator status. + + 382 RPL_REHASHING + "<config file> :Rehashing" + + - If the REHASH option is used and an operator sends + a REHASH message, an RPL_REHASHING is sent back to + the operator. + + 383 RPL_YOURESERVICE + "You are service <servicename>" + + - Sent by the server to a service upon successful + registration. + + 391 RPL_TIME + "<server> :<string showing server's local time>" + + - When replying to the TIME message, a server MUST send + the reply using the RPL_TIME format above. The string + showing the time need only contain the correct day and + time there. There is no further requirement for the + time string. + + 392 RPL_USERSSTART + ":UserID Terminal Host" + 393 RPL_USERS + ":<username> <ttyline> <hostname>" + 394 RPL_ENDOFUSERS + ":End of users" + 395 RPL_NOUSERS + ":Nobody logged in" + + - If the USERS message is handled by a server, the + replies RPL_USERSTART, RPL_USERS, RPL_ENDOFUSERS and + RPL_NOUSERS are used. RPL_USERSSTART MUST be sent + first, following by either a sequence of RPL_USERS + or a single RPL_NOUSER. Following this is + RPL_ENDOFUSERS. + + 200 RPL_TRACELINK + "Link <version & debug level> <destination> + <next server> V<protocol version> + <link uptime in seconds> <backstream sendq> + <upstream sendq>" + 201 RPL_TRACECONNECTING + "Try. <class> <server>" + 202 RPL_TRACEHANDSHAKE + "H.S. <class> <server>" + 203 RPL_TRACEUNKNOWN + "???? <class> [<client IP address in dot form>]" + 204 RPL_TRACEOPERATOR + "Oper <class> <nick>" + 205 RPL_TRACEUSER + "User <class> <nick>" + 206 RPL_TRACESERVER + "Serv <class> <int>S <int>C <server> + <nick!user|*!*>@<host|server> V<protocol version>" + 207 RPL_TRACESERVICE + "Service <class> <name> <type> <active type>" + 208 RPL_TRACENEWTYPE + "<newtype> 0 <client name>" + 209 RPL_TRACECLASS + "Class <class> <count>" + 210 RPL_TRACERECONNECT + Unused. + 261 RPL_TRACELOG + "File <logfile> <debug level>" + 262 RPL_TRACEEND + "<server name> <version & debug level> :End of TRACE" + + - The RPL_TRACE* are all returned by the server in + response to the TRACE message. How many are + returned is dependent on the TRACE message and + whether it was sent by an operator or not. There + is no predefined order for which occurs first. + Replies RPL_TRACEUNKNOWN, RPL_TRACECONNECTING and + RPL_TRACEHANDSHAKE are all used for connections + which have not been fully established and are either + unknown, still attempting to connect or in the + process of completing the 'server handshake'. + RPL_TRACELINK is sent by any server which handles + a TRACE message and has to pass it on to another + server. The list of RPL_TRACELINKs sent in + response to a TRACE command traversing the IRC + network should reflect the actual connectivity of + the servers themselves along that path. + + RPL_TRACENEWTYPE is to be used for any connection + which does not fit in the other categories but is + being displayed anyway. + RPL_TRACEEND is sent to indicate the end of the list. + + 211 RPL_STATSLINKINFO + "<linkname> <sendq> <sent messages> + <sent Kbytes> <received messages> + <received Kbytes> <time open>" + + - reports statistics on a connection. <linkname> + identifies the particular connection, <sendq> is + the amount of data that is queued and waiting to be + sent <sent messages> the number of messages sent, + and <sent Kbytes> the amount of data sent, in + Kbytes. <received messages> and <received Kbytes> + are the equivalent of <sent messages> and <sent + Kbytes> for received data, respectively. <time + open> indicates how long ago the connection was + opened, in seconds. + + 212 RPL_STATSCOMMANDS + "<command> <count> <byte count> <remote count>" + + - reports statistics on commands usage. + + 219 RPL_ENDOFSTATS + "<stats letter> :End of STATS report" + + 242 RPL_STATSUPTIME + ":Server Up %d days %d:%02d:%02d" + + - reports the server uptime. + + 243 RPL_STATSOLINE + "O <hostmask> * <name>" + + - reports the allowed hosts from where user may become IRC + operators. + + 221 RPL_UMODEIS + "<user mode string>" + + - To answer a query about a client's own mode, + RPL_UMODEIS is sent back. + + 234 RPL_SERVLIST + "<name> <server> <mask> <type> <hopcount> <info>" + + 235 RPL_SERVLISTEND + "<mask> <type> :End of service listing" + + - When listing services in reply to a SERVLIST message, + a server is required to send the list back using the + RPL_SERVLIST and RPL_SERVLISTEND messages. A separate + RPL_SERVLIST is sent for each service. After the + services have been listed (or if none present) a + RPL_SERVLISTEND MUST be sent. + + 251 RPL_LUSERCLIENT + ":There are <integer> users and <integer> + services on <integer> servers" + 252 RPL_LUSEROP + "<integer> :operator(s) online" + 253 RPL_LUSERUNKNOWN + "<integer> :unknown connection(s)" + 254 RPL_LUSERCHANNELS + "<integer> :channels formed" + 255 RPL_LUSERME + ":I have <integer> clients and <integer> + servers" + + - In processing an LUSERS message, the server + sends a set of replies from RPL_LUSERCLIENT, + RPL_LUSEROP, RPL_USERUNKNOWN, + RPL_LUSERCHANNELS and RPL_LUSERME. When + replying, a server MUST send back + RPL_LUSERCLIENT and RPL_LUSERME. The other + replies are only sent back if a non-zero count + is found for them. + + 256 RPL_ADMINME + "<server> :Administrative info" + 257 RPL_ADMINLOC1 + ":<admin info>" + 258 RPL_ADMINLOC2 + ":<admin info>" + 259 RPL_ADMINEMAIL + ":<admin info>" + + - When replying to an ADMIN message, a server + is expected to use replies RPL_ADMINME + through to RPL_ADMINEMAIL and provide a text + message with each. For RPL_ADMINLOC1 a + description of what city, state and country + the server is in is expected, followed by + details of the institution (RPL_ADMINLOC2) + + and finally the administrative contact for the + server (an email address here is REQUIRED) + in RPL_ADMINEMAIL. + + 263 RPL_TRYAGAIN + "<command> :Please wait a while and try again." + + - When a server drops a command without processing it, + it MUST use the reply RPL_TRYAGAIN to inform the + originating client. + +5.2 Error Replies + + Error replies are found in the range from 400 to 599. + + 401 ERR_NOSUCHNICK + "<nickname> :No such nick/channel" + + - Used to indicate the nickname parameter supplied to a + command is currently unused. + + 402 ERR_NOSUCHSERVER + "<server name> :No such server" + + - Used to indicate the server name given currently + does not exist. + + 403 ERR_NOSUCHCHANNEL + "<channel name> :No such channel" + + - Used to indicate the given channel name is invalid. + + 404 ERR_CANNOTSENDTOCHAN + "<channel name> :Cannot send to channel" + + - Sent to a user who is either (a) not on a channel + which is mode +n or (b) not a chanop (or mode +v) on + a channel which has mode +m set or where the user is + banned and is trying to send a PRIVMSG message to + that channel. + + 405 ERR_TOOMANYCHANNELS + "<channel name> :You have joined too many channels" + + - Sent to a user when they have joined the maximum + number of allowed channels and they try to join + another channel. + + 406 ERR_WASNOSUCHNICK + "<nickname> :There was no such nickname" + + - Returned by WHOWAS to indicate there is no history + information for that nickname. + + 407 ERR_TOOMANYTARGETS + "<target> :<error code> recipients. <abort message>" + + - Returned to a client which is attempting to send a + PRIVMSG/NOTICE using the user@host destination format + and for a user@host which has several occurrences. + + - Returned to a client which trying to send a + PRIVMSG/NOTICE to too many recipients. + + - Returned to a client which is attempting to JOIN a safe + channel using the shortname when there are more than one + such channel. + + 408 ERR_NOSUCHSERVICE + "<service name> :No such service" + + - Returned to a client which is attempting to send a SQUERY + to a service which does not exist. + + 409 ERR_NOORIGIN + ":No origin specified" + + - PING or PONG message missing the originator parameter. + + 411 ERR_NORECIPIENT + ":No recipient given (<command>)" + 412 ERR_NOTEXTTOSEND + ":No text to send" + 413 ERR_NOTOPLEVEL + "<mask> :No toplevel domain specified" + 414 ERR_WILDTOPLEVEL + "<mask> :Wildcard in toplevel domain" + 415 ERR_BADMASK + "<mask> :Bad Server/host mask" + + - 412 - 415 are returned by PRIVMSG to indicate that + the message wasn't delivered for some reason. + ERR_NOTOPLEVEL and ERR_WILDTOPLEVEL are errors that + are returned when an invalid use of + "PRIVMSG $<server>" or "PRIVMSG #<host>" is attempted. + + 421 ERR_UNKNOWNCOMMAND + "<command> :Unknown command" + + - Returned to a registered client to indicate that the + command sent is unknown by the server. + + 422 ERR_NOMOTD + ":MOTD File is missing" + + - Server's MOTD file could not be opened by the server. + + 423 ERR_NOADMININFO + "<server> :No administrative info available" + + - Returned by a server in response to an ADMIN message + when there is an error in finding the appropriate + information. + + 424 ERR_FILEERROR + ":File error doing <file op> on <file>" + + - Generic error message used to report a failed file + operation during the processing of a message. + + 431 ERR_NONICKNAMEGIVEN + ":No nickname given" + + - Returned when a nickname parameter expected for a + command and isn't found. + + 432 ERR_ERRONEUSNICKNAME + "<nick> :Erroneous nickname" + + - Returned after receiving a NICK message which contains + characters which do not fall in the defined set. See + section 2.3.1 for details on valid nicknames. + + 433 ERR_NICKNAMEINUSE + "<nick> :Nickname is already in use" + + - Returned when a NICK message is processed that results + in an attempt to change to a currently existing + nickname. + + 436 ERR_NICKCOLLISION + "<nick> :Nickname collision KILL from <user>@<host>" + + - Returned by a server to a client when it detects a + nickname collision (registered of a NICK that + already exists by another server). + + 437 ERR_UNAVAILRESOURCE + "<nick/channel> :Nick/channel is temporarily unavailable" + + - Returned by a server to a user trying to join a channel + currently blocked by the channel delay mechanism. + + - Returned by a server to a user trying to change nickname + when the desired nickname is blocked by the nick delay + mechanism. + + 441 ERR_USERNOTINCHANNEL + "<nick> <channel> :They aren't on that channel" + + - Returned by the server to indicate that the target + user of the command is not on the given channel. + + 442 ERR_NOTONCHANNEL + "<channel> :You're not on that channel" + + - Returned by the server whenever a client tries to + perform a channel affecting command for which the + client isn't a member. + + 443 ERR_USERONCHANNEL + "<user> <channel> :is already on channel" + + - Returned when a client tries to invite a user to a + channel they are already on. + + 444 ERR_NOLOGIN + "<user> :User not logged in" + + - Returned by the summon after a SUMMON command for a + user was unable to be performed since they were not + logged in. + + 445 ERR_SUMMONDISABLED + ":SUMMON has been disabled" + + - Returned as a response to the SUMMON command. MUST be + returned by any server which doesn't implement it. + + 446 ERR_USERSDISABLED + ":USERS has been disabled" + + - Returned as a response to the USERS command. MUST be + returned by any server which does not implement it. + + 451 ERR_NOTREGISTERED + ":You have not registered" + + - Returned by the server to indicate that the client + MUST be registered before the server will allow it + to be parsed in detail. + + 461 ERR_NEEDMOREPARAMS + "<command> :Not enough parameters" + + - Returned by the server by numerous commands to + indicate to the client that it didn't supply enough + parameters. + + 462 ERR_ALREADYREGISTRED + ":Unauthorized command (already registered)" + + - Returned by the server to any link which tries to + change part of the registered details (such as + password or user details from second USER message). + + 463 ERR_NOPERMFORHOST + ":Your host isn't among the privileged" + + - Returned to a client which attempts to register with + a server which does not been setup to allow + connections from the host the attempted connection + is tried. + + 464 ERR_PASSWDMISMATCH + ":Password incorrect" + + - Returned to indicate a failed attempt at registering + a connection for which a password was required and + was either not given or incorrect. + + 465 ERR_YOUREBANNEDCREEP + ":You are banned from this server" + + - Returned after an attempt to connect and register + yourself with a server which has been setup to + explicitly deny connections to you. + + 466 ERR_YOUWILLBEBANNED + + - Sent by a server to a user to inform that access to the + server will soon be denied. + + 467 ERR_KEYSET + "<channel> :Channel key already set" + 471 ERR_CHANNELISFULL + "<channel> :Cannot join channel (+l)" + 472 ERR_UNKNOWNMODE + "<char> :is unknown mode char to me for <channel>" + 473 ERR_INVITEONLYCHAN + "<channel> :Cannot join channel (+i)" + 474 ERR_BANNEDFROMCHAN + "<channel> :Cannot join channel (+b)" + 475 ERR_BADCHANNELKEY + "<channel> :Cannot join channel (+k)" + 476 ERR_BADCHANMASK + "<channel> :Bad Channel Mask" + 477 ERR_NOCHANMODES + "<channel> :Channel doesn't support modes" + 478 ERR_BANLISTFULL + "<channel> <char> :Channel list is full" + + 481 ERR_NOPRIVILEGES + ":Permission Denied- You're not an IRC operator" + + - Any command requiring operator privileges to operate + MUST return this error to indicate the attempt was + unsuccessful. + + 482 ERR_CHANOPRIVSNEEDED + "<channel> :You're not channel operator" + + - Any command requiring 'chanop' privileges (such as + MODE messages) MUST return this error if the client + making the attempt is not a chanop on the specified + channel. + + 483 ERR_CANTKILLSERVER + ":You can't kill a server!" + + - Any attempts to use the KILL command on a server + are to be refused and this error returned directly + to the client. + + 484 ERR_RESTRICTED + ":Your connection is restricted!" + + - Sent by the server to a user upon connection to indicate + the restricted nature of the connection (user mode "+r"). + + 485 ERR_UNIQOPPRIVSNEEDED + ":You're not the original channel operator" + + - Any MODE requiring "channel creator" privileges MUST + return this error if the client making the attempt is not + a chanop on the specified channel. + + 491 ERR_NOOPERHOST + ":No O-lines for your host" + + - If a client sends an OPER message and the server has + not been configured to allow connections from the + client's host as an operator, this error MUST be + returned. + + 501 ERR_UMODEUNKNOWNFLAG + ":Unknown MODE flag" + + - Returned by the server to indicate that a MODE + message was sent with a nickname parameter and that + the a mode flag sent was not recognized. + + 502 ERR_USERSDONTMATCH + ":Cannot change mode for other users" + + - Error sent to any user trying to view or change the + user mode for a user other than themselves. + +5.3 Reserved numerics + + These numerics are not described above since they fall into one of + the following categories: + + 1. no longer in use; + + 2. reserved for future planned use; + + 3. in current use but are part of a non-generic 'feature' of + the current IRC server. + + 231 RPL_SERVICEINFO 232 RPL_ENDOFSERVICES + 233 RPL_SERVICE + 300 RPL_NONE 316 RPL_WHOISCHANOP + 361 RPL_KILLDONE 362 RPL_CLOSING + 363 RPL_CLOSEEND 373 RPL_INFOSTART + 384 RPL_MYPORTIS + + 213 RPL_STATSCLINE 214 RPL_STATSNLINE + 215 RPL_STATSILINE 216 RPL_STATSKLINE + 217 RPL_STATSQLINE 218 RPL_STATSYLINE + 240 RPL_STATSVLINE 241 RPL_STATSLLINE + 244 RPL_STATSHLINE 244 RPL_STATSSLINE + 246 RPL_STATSPING 247 RPL_STATSBLINE + 250 RPL_STATSDLINE + + 492 ERR_NOSERVICEHOST + +6. Current implementations + + The IRC software, version 2.10 is the only complete implementation of + the IRC protocol (client and server). Because of the small amount of + changes in the client protocol since the publication of RFC 1459 + [IRC], implementations that follow it are likely to be compliant with + this protocol or to require a small amount of changes to reach + compliance. + +7. Current problems + + There are a number of recognized problems with the IRC Client + Protocol, and more generally with the IRC Server Protocol. In order + to preserve backward compatibility with old clients, this protocol + has almost not evolved since the publication of RFC 1459 [IRC]. + +7.1 Nicknames + + The idea of the nickname on IRC is very convenient for users to use + when talking to each other outside of a channel, but there is only a + finite nickname space and being what they are, it's not uncommon for + several people to want to use the same nick. If a nickname is chosen + by two people using this protocol, either one will not succeed or + both will removed by use of a server KILL (See Section 3.7.1). + +7.2 Limitation of wildcards + + There is no way to escape the escape character "\" (%x5C). While + this isn't usually a problem, it makes it impossible to form a mask + with a backslash character ("\") preceding a wildcard. + +7.3 Security considerations + + Security issues related to this protocol are discussed in the "IRC + Server Protocol" [IRC-SERVER] as they are mostly an issue for the + server side of the connection. + +8. Current support and availability + + Mailing lists for IRC related discussion: + General discussion: ircd-users@irc.org + Protocol development: ircd-dev@irc.org + + Software implementations: + ftp://ftp.irc.org/irc/server + ftp://ftp.funet.fi/pub/unix/irc + ftp://ftp.irc.org/irc/clients + + Newsgroup: alt.irc + +9. Acknowledgements + + Parts of this document were copied from the RFC 1459 [IRC] which + first formally documented the IRC Protocol. It has also benefited + from many rounds of review and comments. In particular, the + following people have made significant contributions to this + document: + + Matthew Green, Michael Neumayer, Volker Paulsen, Kurt Roeckx, Vesa + Ruokonen, Magnus Tjernstrom, Stefan Zehl. + +10. References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [HNAME] Braden, R., "Requirements for Internet Hosts -- + Application and Support", STD 3, RFC 1123, October 1989. + + [IRC] Oikarinen, J. & D. Reed, "Internet Relay Chat Protocol", + RFC 1459, May 1993. + + [IRC-ARCH] Kalt, C., "Internet Relay Chat: Architecture", RFC 2810, + April 2000. + + [IRC-CHAN] Kalt, C., "Internet Relay Chat: Channel Management", RFC + 2811, April 2000. + + [IRC-SERVER] Kalt, C., "Internet Relay Chat: Server Protocol", RFC + 2813, April 2000. + +11. Author's Address + + Christophe Kalt + 99 Teaneck Rd, Apt #117 + Ridgefield Park, NJ 07660 + USA + + EMail: kalt@stealth.net + +12. Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. diff --git a/doc/technical/rfc2813.txt b/doc/technical/rfc2813.txt new file mode 100644 index 0000000..175de1d --- /dev/null +++ b/doc/technical/rfc2813.txt @@ -0,0 +1,1173 @@ +$Id$ + +Network Working Group C. Kalt +Request for Comments: 2813 April 2000 +Updates: 1459 +Category: Informational + + Internet Relay Chat: Server Protocol + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + While based on the client-server model, the IRC (Internet Relay Chat) + protocol allows servers to connect to each other effectively forming + a network. + + This document defines the protocol used by servers to talk to each + other. It was originally a superset of the client protocol but has + evolved differently. + + First formally documented in May 1993 as part of RFC 1459 [IRC], most + of the changes brought since then can be found in this document as + development was focused on making the protocol scale better. Better + scalability has allowed existing world-wide networks to keep growing + and reach sizes which defy the old specification. + +Table of Contents + + 1. Introduction ............................................... 3 + 2. Global database ............................................ 3 + 2.1 Servers ................................................ 3 + 2.2 Clients ................................................ 4 + 2.2.1 Users ............................................. 4 + 2.2.2 Services .......................................... 4 + 2.3 Channels ............................................... 4 + 3. The IRC Server Specification ............................... 5 + 3.1 Overview ............................................... 5 + 3.2 Character codes ........................................ 5 + 3.3 Messages ............................................... 5 + 3.3.1 Message format in Augmented BNF ................... 6 + 3.4 Numeric replies ........................................ 7 + 4. Message Details ............................................ 7 + 4.1 Connection Registration ................................ 8 + 4.1.1 Password message .................................. 8 + 4.1.2 Server message .................................... 9 + 4.1.3 Nick .............................................. 10 + 4.1.4 Service message ................................... 11 + 4.1.5 Quit .............................................. 12 + 4.1.6 Server quit message ............................... 13 + 4.2 Channel operations ..................................... 14 + 4.2.1 Join message ...................................... 14 + 4.2.2 Njoin message ..................................... 15 + 4.2.3 Mode message ...................................... 16 + 5. Implementation details .................................... 16 + 5.1 Connection 'Liveness' .................................. 16 + 5.2 Accepting a client to server connection ................ 16 + 5.2.1 Users ............................................. 16 + 5.2.2 Services .......................................... 17 + 5.3 Establishing a server-server connection. ............... 17 + 5.3.1 Link options ...................................... 17 + 5.3.1.1 Compressed server to server links ............ 18 + 5.3.1.2 Anti abuse protections ....................... 18 + 5.3.2 State information exchange when connecting ........ 18 + 5.4 Terminating server-client connections .................. 19 + 5.5 Terminating server-server connections .................. 19 + 5.6 Tracking nickname changes .............................. 19 + 5.7 Tracking recently used nicknames ....................... 20 + 5.8 Flood control of clients ............................... 20 + 5.9 Non-blocking lookups ................................... 21 + 5.9.1 Hostname (DNS) lookups ............................ 21 + 5.9.2 Username (Ident) lookups .......................... 21 + 6. Current problems ........................................... 21 + 6.1 Scalability ............................................ 21 + 6.2 Labels ................................................. 22 + + 6.2.1 Nicknames ......................................... 22 + 6.2.2 Channels .......................................... 22 + 6.2.3 Servers ........................................... 22 + 6.3 Algorithms ............................................. 22 + 7. Security Considerations .................................... 23 + 7.1 Authentication ......................................... 23 + 7.2 Integrity .............................................. 23 + 8. Current support and availability ........................... 24 + 9. Acknowledgements ........................................... 24 + 10. References ................................................ 24 + 11. Author's Address .......................................... 25 + 12. Full Copyright Statement ................................... 26 + +1. Introduction + + This document is intended for people working on implementing an IRC + server but will also be useful to anyone implementing an IRC service. + + Servers provide the three basic services required for realtime + conferencing defined by the "Internet Relay Chat: Architecture" + [IRC-ARCH]: client locator (via the client protocol [IRC-CLIENT]), + message relaying (via the server protocol defined in this document) + and channel hosting and management (following specific rules [IRC- + CHAN]). + +2. Global database + + Although the IRC Protocol defines a fairly distributed model, each + server maintains a "global state database" about the whole IRC + network. This database is, in theory, identical on all servers. + +2.1 Servers + + Servers are uniquely identified by their name which has a maximum + length of sixty three (63) characters. See the protocol grammar + rules (section 3.3.1) for what may and may not be used in a server + name. + + Each server is typically known by all other servers, however it is + possible to define a "hostmask" to group servers together according + to their name. Inside the hostmasked area, all the servers have a + name which matches the hostmask, and any other server with a name + matching the hostmask SHALL NOT be connected to the IRC network + outside the hostmasked area. Servers which are outside the area have + no knowledge of the individual servers present inside the area, + instead they are presented with a virtual server which has the + hostmask for name. + +2.2 Clients + + For each client, all servers MUST have the following information: a + netwide unique identifier (whose format depends on the type of + client) and the server to which the client is connected. + +2.2.1 Users + + Each user is distinguished from other users by a unique nickname + having a maximum length of nine (9) characters. See the protocol + grammar rules (section 3.3.1) for what may and may not be used in a + nickname. In addition to the nickname, all servers MUST have the + following information about all users: the name of the host that the + user is running on, the username of the user on that host, and the + server to which the client is connected. + +2.2.2 Services + + Each service is distinguished from other services by a service name + composed of a nickname and a server name. The nickname has a maximum + length of nine (9) characters. See the protocol grammar rules + (section 3.3.1) for what may and may not be used in a nickname. The + server name used to compose the service name is the name of the + server to which the service is connected. In addition to this + service name all servers MUST know the service type. + + Services differ from users by the format of their identifier, but + more importantly services and users don't have the same type of + access to the server: services can request part or all of the global + state information that a server maintains, but have a more restricted + set of commands available to them (See "IRC Client Protocol" [IRC- + CLIENT] for details on which) and are not allowed to join channels. + Finally services are not usually subject to the "Flood control" + mechanism described in section 5.8. + +2.3 Channels + + Alike services, channels have a scope [IRC-CHAN] and are not + necessarily known to all servers. When a channel existence is known + to a server, the server MUST keep track of the channel members, as + well as the channel modes. + +3. The IRC Server Specification + +3.1 Overview + + The protocol as described herein is for use with server to server + connections. For client to server connections, see the IRC Client + Protocol specification. + + There are, however, more restrictions on client connections (which + are considered to be untrustworthy) than on server connections. + +3.2 Character codes + + No specific character set is specified. The protocol is based on a a + set of codes which are composed of eight (8) bits, making up an + octet. Each message may be composed of any number of these octets; + however, some octet values are used for control codes which act as + message delimiters. + + Regardless of being an 8-bit protocol, the delimiters and keywords + are such that protocol is mostly usable from US-ASCII terminal and a + telnet connection. + + Because of IRC's Scandinavian origin, the characters {}|^ are + considered to be the lower case equivalents of the characters []\~, + respectively. This is a critical issue when determining the + equivalence of two nicknames, or channel names. + +3.3 Messages + + Servers and clients send each other messages which may or may not + generate a reply. Most communication between servers do not generate + any reply, as servers mostly perform routing tasks for the clients. + + Each IRC message may consist of up to three main parts: the prefix + (OPTIONAL), the command, and the command parameters (maximum of + fifteen (15)). The prefix, command, and all parameters are separated + by one ASCII space character (0x20) each. + + The presence of a prefix is indicated with a single leading ASCII + colon character (':', 0x3b), which MUST be the first character of the + message itself. There MUST be NO gap (whitespace) between the colon + and the prefix. The prefix is used by servers to indicate the true + origin of the message. If the prefix is missing from the message, it + is assumed to have originated from the connection from which it was + received. Clients SHOULD not use a prefix when sending a message + from themselves; if they use one, the only valid prefix is the + registered nickname associated with the client. + + When a server receives a message, it MUST identify its source using + the (eventually assumed) prefix. If the prefix cannot be found in + the server's internal database, it MUST be discarded, and if the + prefix indicates the message comes from an (unknown) server, the link + from which the message was received MUST be dropped. Dropping a link + in such circumstances is a little excessive but necessary to maintain + the integrity of the network and to prevent future problems. Another + common error condition is that the prefix found in the server's + internal database identifies a different source (typically a source + registered from a different link than from which the message + arrived). If the message was received from a server link and the + prefix identifies a client, a KILL message MUST be issued for the + client and sent to all servers. In other cases, the link from which + the message arrived SHOULD be dropped for clients, and MUST be + dropped for servers. In all cases, the message MUST be discarded. + + The command MUST either be a valid IRC command or a three (3) digit + number represented in ASCII text. + + IRC messages are always lines of characters terminated with a CR-LF + (Carriage Return - Line Feed) pair, and these messages SHALL NOT + exceed 512 characters in length, counting all characters including + the trailing CR-LF. Thus, there are 510 characters maximum allowed + for the command and its parameters. There is no provision for + continuation message lines. See section 5 for more details about + current implementations. + +3.3.1 Message format in Augmented BNF + + The protocol messages must be extracted from the contiguous stream of + octets. The current solution is to designate two characters, CR and + LF, as message separators. Empty messages are silently ignored, + which permits use of the sequence CR-LF between messages without + extra problems. + + The extracted message is parsed into the components <prefix>, + <command> and list of parameters (<params>). + + The Augmented BNF representation for this is found in "IRC Client + Protocol" [IRC-CLIENT]. + + The extended prefix (["!" user "@" host ]) MUST NOT be used in server + to server communications and is only intended for server to client + messages in order to provide clients with more useful information + about who a message is from without the need for additional queries. + +3.4 Numeric replies + + Most of the messages sent to the server generate a reply of some + sort. The most common reply is the numeric reply, used for both + errors and normal replies. The numeric reply MUST be sent as one + message consisting of the sender prefix, the three digit numeric, and + the target of the reply. A numeric reply is not allowed to originate + from a client; any such messages received by a server are silently + dropped. In all other respects, a numeric reply is just like a normal + message, except that the keyword is made up of 3 numeric digits + rather than a string of letters. A list of different replies is + supplied in "IRC Client Protocol" [IRC-CLIENT]. + +4. Message Details + + All the messages recognized by the IRC server and client are + described in the IRC Client Protocol specification. + + Where the reply ERR_NOSUCHSERVER is returned, it means that the + target of the message could not be found. The server MUST NOT send + any other replies after this error for that command. + + The server to which a client is connected is required to parse the + complete message, returning any appropriate errors. If the server + encounters a fatal error while parsing a message, an error MUST be + sent back to the client and the parsing terminated. A fatal error + may follow from incorrect command, a destination which is otherwise + unknown to the server (server, client or channel names fit this + category), not enough parameters or incorrect privileges. + + If a full set of parameters is presented, then each MUST be checked + for validity and appropriate responses sent back to the client. In + the case of messages which use parameter lists using the comma as an + item separator, a reply MUST be sent for each item. + + In the examples below, some messages appear using the full format: + + :Name COMMAND parameter list + + Such examples represent a message from "Name" in transit between + servers, where it is essential to include the name of the original + sender of the message so remote servers may send back a reply along + the correct path. + + The message details for client to server communication are described + in the "IRC Client Protocol" [IRC-CLIENT]. Some sections in the + following pages apply to some of these messages, they are additions + to the message specifications which are only relevant to server to + + server communication, or to the server implementation. The messages + which are introduced here are only used for server to server + communication. + +4.1 Connection Registration + + The commands described here are used to register a connection with + another IRC server. + +4.1.1 Password message + + Command: PASS + Parameters: <password> <version> <flags> [<options>] + + The PASS command is used to set a 'connection password'. The + password MUST be set before any attempt to register the connection is + made. Currently this means that servers MUST send a PASS command + before any SERVER command. Only one (1) PASS command SHALL be + accepted from a connection. + + The last three (3) parameters MUST be ignored if received from a + client (e.g. a user or a service). They are only relevant when + received from a server. + + The <version> parameter is a string of at least four (4) characters, + and up to fourteen (14) characters. The first four (4) characters + MUST be digits and indicate the protocol version known by the server + issuing the message. The protocol described by this document is + version 2.10 which is encoded as "0210". The remaining OPTIONAL + characters are implementation dependent and should describe the + software version number. + + The <flags> parameter is a string of up to one hundred (100) + characters. It is composed of two substrings separated by the + character "|" (%x7C). If present, the first substring MUST be the + name of the implementation. The reference implementation (See + Section 8, "Current support and availability") uses the string "IRC". + If a different implementation is written, which needs an identifier, + then that identifier should be registered through publication of an + RFC. The second substring is implementation dependent. Both + substrings are OPTIONAL, but the character "|" is REQUIRED. The + character "|" MUST NOT appear in either substring. + + Finally, the last parameter, <options>, is used for link options. + The only options defined by the protocol are link compression (using + the character "Z"), and an abuse protection flag (using the character + + "P"). See sections 5.3.1.1 (Compressed server to server links) and + 5.3.1.2 (Anti abuse protections) respectively for more information on + these options. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED + + Example: + + PASS moresecretpassword 0210010000 IRC|aBgH$ Z + +4.1.2 Server message + + Command: SERVER + Parameters: <servername> <hopcount> <token> <info> + + The SERVER command is used to register a new server. A new connection + introduces itself as a server to its peer. This message is also used + to pass server data over whole net. When a new server is connected + to net, information about it MUST be broadcasted to the whole + network. + + The <info> parameter may contain space characters. + + <hopcount> is used to give all servers some internal information on + how far away each server is. Local peers have a value of 0, and each + passed server increments the value. With a full server list, it + would be possible to construct a map of the entire server tree, but + hostmasks prevent this from being done. + + The <token> parameter is an unsigned number used by servers as an + identifier. This identifier is subsequently used to reference a + server in the NICK and SERVICE messages sent between servers. Server + tokens only have a meaning for the point-to-point peering they are + used and MUST be unique for that connection. They are not global. + + The SERVER message MUST only be accepted from either (a) a connection + which is yet to be registered and is attempting to register as a + server, or (b) an existing connection to another server, in which + case the SERVER message is introducing a new server behind that + server. + + Most errors that occur with the receipt of a SERVER command result in + the connection being terminated by the destination host (target + SERVER). Because of the severity of such event, error replies are + usually sent using the "ERROR" command rather than a numeric. + + If a SERVER message is parsed and it attempts to introduce a server + which is already known to the receiving server, the connection, from + which that message arrived, MUST be closed (following the correct + procedures), since a duplicate route to a server has been formed and + the acyclic nature of the IRC tree breaks. In some conditions, the + connection from which the already known server has registered MAY be + closed instead. It should be noted that this kind of error can also + be the result of a second running server, problem which cannot be + fixed within the protocol and typically requires human intervention. + This type of problem is particularly insidious, as it can quite + easily result in part of the IRC network to be isolated, with one of + the two servers connected to each partition therefore making it + impossible for the two parts to unite. + + Numeric Replies: + + ERR_ALREADYREGISTRED + + Example: + + SERVER test.oulu.fi 1 1 :Experimental server ; New server + test.oulu.fi introducing itself and + attempting to register. + + :tolsun.oulu.fi SERVER csd.bu.edu 5 34 :BU Central Server ; Server + tolsun.oulu.fi is our uplink for + csd.bu.edu which is 5 hops away. The + token "34" will be used by + tolsun.oulu.fi when introducing new + users or services connected to + csd.bu.edu. + +4.1.3 Nick + + Command: NICK + Parameters: <nickname> <hopcount> <username> <host> <servertoken> + <umode> <realname> + + This form of the NICK message MUST NOT be allowed from user + connections. However, it MUST be used instead of the NICK/USER pair + to notify other servers of new users joining the IRC network. + + This message is really the combination of three distinct messages: + NICK, USER and MODE [IRC-CLIENT]. + + The <hopcount> parameter is used by servers to indicate how far away + a user is from its home server. A local connection has a hopcount of + 0. The hopcount value is incremented by each passed server. + + The <servertoken> parameter replaces the <servername> parameter of + the USER (See section 4.1.2 for more information on server tokens). + + Examples: + + NICK syrk 5 kalt millennium.stealth.net 34 +i :Christophe Kalt ; New + user with nickname "syrk", username + "kalt", connected from host + "millennium.stealth.net" to server + "34" ("csd.bu.edu" according to the + previous example). + + :krys NICK syrk ; The other form of the NICK message, + as defined in "IRC Client Protocol" + [IRC-CLIENT] and used between + servers: krys changed his nickname to + syrk + +4.1.4 Service message + + Command: SERVICE + Parameters: <servicename> <servertoken> <distribution> <type> + <hopcount> <info> + + The SERVICE command is used to introduce a new service. This form of + the SERVICE message SHOULD NOT be allowed from client (unregistered, + or registered) connections. However, it MUST be used between servers + to notify other servers of new services joining the IRC network. + + The <servertoken> is used to identify the server to which the service + is connected. (See section 4.1.2 for more information on server + tokens). + + The <hopcount> parameter is used by servers to indicate how far away + a service is from its home server. A local connection has a hopcount + of 0. The hopcount value is incremented by each passed server. + + The <distribution> parameter is used to specify the visibility of a + service. The service may only be known to servers which have a name + matching the distribution. For a matching server to have knowledge + of the service, the network path between that server and the server + to which the service is connected MUST be composed of servers whose + names all match the mask. Plain "*" is used when no restriction is + wished. + + The <type> parameter is currently reserved for future usage. + + Numeric Replies: + + ERR_ALREADYREGISTRED ERR_NEEDMOREPARAMS + ERR_ERRONEUSNICKNAME + RPL_YOURESERVICE RPL_YOURHOST + RPL_MYINFO + + Example: + +SERVICE dict@irc.fr 9 *.fr 0 1 :French Dictionary r" registered on + server "9" is being announced to + another server. This service will + only be available on servers whose + name matches "*.fr". + +4.1.5 Quit + + Command: QUIT + Parameters: [<Quit Message>] + + A client session ends with a quit message. The server MUST close the + connection to a client which sends a QUIT message. If a "Quit + Message" is given, this will be sent instead of the default message, + the nickname or service name. + + When "netsplit" (See Section 4.1.6) occur, the "Quit Message" is + composed of the names of two servers involved, separated by a space. + The first name is that of the server which is still connected and the + second name is either that of the server which has become + disconnected or that of the server to which the leaving client was + connected: + + <Quit Message> = ":" servername SPACE servername + + Because the "Quit Message" has a special meaning for "netsplits", + servers SHOULD NOT allow a client to use a <Quit Message> in the + format described above. + + If, for some other reason, a client connection is closed without the + client issuing a QUIT command (e.g. client dies and EOF occurs on + socket), the server is REQUIRED to fill in the quit message with some + sort of message reflecting the nature of the event which caused it to + happen. Typically, this is done by reporting a system specific + error. + + Numeric Replies: + + None. + + Examples: + + :WiZ QUIT :Gone to have lunch ; Preferred message format. + +4.1.6 Server quit message + + Command: SQUIT + Parameters: <server> <comment> + + The SQUIT message has two distinct uses. + + The first one (described in "Internet Relay Chat: Client Protocol" + [IRC-CLIENT]) allows operators to break a local or remote server + link. This form of the message is also eventually used by servers to + break a remote server link. + + The second use of this message is needed to inform other servers when + a "network split" (also known as "netsplit") occurs, in other words + to inform other servers about quitting or dead servers. If a server + wishes to break the connection to another server it MUST send a SQUIT + message to the other server, using the name of the other server as + the server parameter, which then closes its connection to the + quitting server. + + The <comment> is filled in by servers which SHOULD place an error or + similar message here. + + Both of the servers which are on either side of the connection being + closed are REQUIRED to send out a SQUIT message (to all its other + server connections) for all other servers which are considered to be + behind that link. + + Similarly, a QUIT message MAY be sent to the other still connected + servers on behalf of all clients behind that quitting link. In + addition to this, all channel members of a channel which lost a + member due to the "split" MUST be sent a QUIT message. Messages to + channel members are generated by each client's local server. + + If a server connection is terminated prematurely (e.g., the server on + the other end of the link died), the server which detects this + disconnection is REQUIRED to inform the rest of the network that the + connection has closed and fill in the comment field with something + appropriate. + + When a client is removed as the result of a SQUIT message, the server + SHOULD add the nickname to the list of temporarily unavailable + nicknames in an attempt to prevent future nickname collisions. See + + section 5.7 (Tracking recently used nicknames) for more information + on this procedure. + + Numeric replies: + + ERR_NOPRIVILEGES ERR_NOSUCHSERVER + ERR_NEEDMOREPARAMS + + Example: + + SQUIT tolsun.oulu.fi :Bad Link ? ; the server link tolson.oulu.fi + has been terminated because of "Bad + Link". + + :Trillian SQUIT cm22.eng.umd.edu :Server out of control ; message + from Trillian to disconnect + "cm22.eng.umd.edu" from the net + because "Server out of control". + +4.2 Channel operations + + This group of messages is concerned with manipulating channels, their + properties (channel modes), and their contents (typically users). In + implementing these, a number of race conditions are inevitable when + users at opposing ends of a network send commands which will + ultimately clash. It is also REQUIRED that servers keep a nickname + history to ensure that wherever a <nick> parameter is given, the + server check its history in case it has recently been changed. + +4.2.1 Join message + + Command: JOIN + Parameters: <channel>[ %x7 <modes> ] + *( "," <channel>[ %x7 <modes> ] ) + + The JOIN command is used by client to start listening a specific + channel. Whether or not a client is allowed to join a channel is + checked only by the local server the client is connected to; all + other servers automatically add the user to the channel when the + command is received from other servers. + + Optionally, the user status (channel modes 'O', 'o', and 'v') on the + channel may be appended to the channel name using a control G (^G or + ASCII 7) as separator. Such data MUST be ignored if the message + wasn't received from a server. This format MUST NOT be sent to + clients, it can only be used between servers and SHOULD be avoided. + + The JOIN command MUST be broadcast to all servers so that each server + knows where to find the users who are on the channel. This allows + optimal delivery of PRIVMSG and NOTICE messages to the channel. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_BANNEDFROMCHAN + ERR_INVITEONLYCHAN ERR_BADCHANNELKEY + ERR_CHANNELISFULL ERR_BADCHANMASK + ERR_NOSUCHCHANNEL ERR_TOOMANYCHANNELS + ERR_TOOMANYTARGETS ERR_UNAVAILRESOURCE + RPL_TOPIC + + Examples: + + :WiZ JOIN #Twilight_zone ; JOIN message from WiZ + +4.2.2 Njoin message + + Command: NJOIN + Parameters: <channel> [ "@@" / "@" ] [ "+" ] <nickname> + *( "," [ "@@" / "@" ] [ "+" ] <nickname> ) + + The NJOIN message is used between servers only. If such a message is + received from a client, it MUST be ignored. It is used when two + servers connect to each other to exchange the list of channel members + for each channel. + + Even though the same function can be performed by using a succession + of JOIN, this message SHOULD be used instead as it is more efficient. + The prefix "@@" indicates that the user is the "channel creator", the + character "@" alone indicates a "channel operator", and the character + '+' indicates that the user has the voice privilege. + + Numeric Replies: + + ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL + ERR_ALREADYREGISTRED + + Examples: + + :ircd.stealth.net NJOIN #Twilight_zone :@WiZ,+syrk,avalon ; NJOIN + message from ircd.stealth.net + announcing users joining the + #Twilight_zone channel: WiZ with + channel operator status, syrk with + voice privilege and avalon with no + privilege. + +4.2.3 Mode message + + The MODE message is a dual-purpose command in IRC. It allows both + usernames and channels to have their mode changed. + + When parsing MODE messages, it is RECOMMENDED that the entire message + be parsed first, and then the changes which resulted passed on. + + It is REQUIRED that servers are able to change channel modes so that + "channel creator" and "channel operators" may be created. + +5. Implementation details + + A the time of writing, the only current implementation of this + protocol is the IRC server, version 2.10. Earlier versions may + implement some or all of the commands described by this document with + NOTICE messages replacing many of the numeric replies. Unfortunately, + due to backward compatibility requirements, the implementation of + some parts of this document varies with what is laid out. One + notable difference is: + + * recognition that any LF or CR anywhere in a message marks + the end of that message (instead of requiring CR-LF); + + The rest of this section deals with issues that are mostly of + importance to those who wish to implement a server but some parts + also apply directly to clients as well. + +5.1 Connection 'Liveness' + + To detect when a connection has died or become unresponsive, the + server MUST poll each of its connections. The PING command (See "IRC + Client Protocol" [IRC-CLIENT]) is used if the server doesn't get a + response from its peer in a given amount of time. + + If a connection doesn't respond in time, its connection is closed + using the appropriate procedures. + +5.2 Accepting a client to server connection + +5.2.1 Users + + When a server successfully registers a new user connection, it is + REQUIRED to send to the user unambiguous messages stating: the user + identifiers upon which it was registered (RPL_WELCOME), the server + name and version (RPL_YOURHOST), the server birth information + (RPL_CREATED), available user and channel modes (RPL_MYINFO), and it + MAY send any introductory messages which may be deemed appropriate. + + In particular the server SHALL send the current user/service/server + count (as per the LUSER reply) and finally the MOTD (if any, as per + the MOTD reply). + + After dealing with registration, the server MUST then send out to + other servers the new user's nickname (NICK message), other + information as supplied by itself (USER message) and as the server + could discover (from DNS servers). The server MUST NOT send this + information out with a pair of NICK and USER messages as defined in + "IRC Client Protocol" [IRC-CLIENT], but MUST instead take advantage + of the extended NICK message defined in section 4.1.3. + +5.2.2 Services + + Upon successfully registering a new service connection, the server is + subject to the same kind of REQUIREMENTS as for a user. Services + being somewhat different, only the following replies are sent: + RPL_YOURESERVICE, RPL_YOURHOST, RPL_MYINFO. + + After dealing with this, the server MUST then send out to other + servers (SERVICE message) the new service's nickname and other + information as supplied by the service (SERVICE message) and as the + server could discover (from DNS servers). + +5.3 Establishing a server-server connection. + + The process of establishing a server-to-server connection is fraught + with danger since there are many possible areas where problems can + occur - the least of which are race conditions. + + After a server has received a connection following by a PASS/SERVER + pair which were recognized as being valid, the server SHOULD then + reply with its own PASS/SERVER information for that connection as + well as all of the other state information it knows about as + described below. + + When the initiating server receives a PASS/SERVER pair, it too then + checks that the server responding is authenticated properly before + accepting the connection to be that server. + +5.3.1 Link options + + Server links are based on a common protocol (defined by this + document) but a particular link MAY set specific options using the + PASS message (See Section 4.1.1). + +5.3.1.1 Compressed server to server links + + If a server wishes to establish a compressed link with its peer, it + MUST set the 'Z' flag in the options parameter to the PASS message. + If both servers request compression and both servers are able to + initialize the two compressed streams, then the remainder of the + communication is to be compressed. If any server fails to initialize + the stream, it will send an uncompressed ERROR message to its peer + and close the connection. + + The data format used for the compression is described by RFC 1950 + [ZLIB], RFC 1951 [DEFLATE] and RFC 1952 [GZIP]. + +5.3.1.2 Anti abuse protections + + Most servers implement various kinds of protections against possible + abusive behaviours from non trusted parties (typically users). On + some networks, such protections are indispensable, on others they are + superfluous. To require that all servers implement and enable such + features on a particular network, the 'P' flag is used when two + servers connect. If this flag is present, it means that the server + protections are enabled, and that the server REQUIRES all its server + links to enable them as well. + + Commonly found protections are described in sections 5.7 (Tracking + recently used nicknames) and 5.8 (Flood control of clients). + +5.3.2 State information exchange when connecting + + The order of state information being exchanged between servers is + essential. The REQUIRED order is as follows: + + * all known servers; + + * all known client information; + + * all known channel information. + + Information regarding servers is sent via extra SERVER messages, + client information with NICK and SERVICE messages and channels with + NJOIN/MODE messages. + + NOTE: channel topics SHOULD NOT be exchanged here because the TOPIC + command overwrites any old topic information, so at best, the two + sides of the connection would exchange topics. + + By passing the state information about servers first, any collisions + with servers that already exist occur before nickname collisions + caused by a second server introducing a particular nickname. Due to + the IRC network only being able to exist as an acyclic graph, it may + be possible that the network has already reconnected in another + location. In this event, the place where the server collision occurs + indicates where the net needs to split. + +5.4 Terminating server-client connections + + When a client connection unexpectedly closes, a QUIT message is + generated on behalf of the client by the server to which the client + was connected. No other message is to be generated or used. + +5.5 Terminating server-server connections + + If a server-server connection is closed, either via a SQUIT command + or "natural" causes, the rest of the connected IRC network MUST have + its information updated by the server which detected the closure. + The terminating server then sends a list of SQUITs (one for each + server behind that connection). (See Section 4.1.6 (SQUIT)). + +5.6 Tracking nickname changes + + All IRC servers are REQUIRED to keep a history of recent nickname + changes. This is important to allow the server to have a chance of + keeping in touch of things when nick-change race conditions occur + with commands manipulating them. Messages which MUST trace nick + changes are: + + * KILL (the nick being disconnected) + + * MODE (+/- o,v on channels) + + * KICK (the nick being removed from channel) + + No other commands need to check nick changes. + + In the above cases, the server is required to first check for the + existence of the nickname, then check its history to see who that + nick now belongs to (if anyone!). This reduces the chances of race + conditions but they can still occur with the server ending up + affecting the wrong client. When performing a change trace for an + above command it is RECOMMENDED that a time range be given and + entries which are too old ignored. + + For a reasonable history, a server SHOULD be able to keep previous + nickname for every client it knows about if they all decided to + change. This size is limited by other factors (such as memory, etc). + +5.7 Tracking recently used nicknames + + This mechanism is commonly known as "Nickname Delay", it has been + proven to significantly reduce the number of nickname collisions + resulting from "network splits"/reconnections as well as abuse. + + In addition of keeping track of nickname changes, servers SHOULD keep + track of nicknames which were recently used and were released as the + result of a "network split" or a KILL message. These nicknames are + then unavailable to the server local clients and cannot be re-used + (even though they are not currently in use) for a certain period of + time. + + The duration for which a nickname remains unavailable SHOULD be set + considering many factors among which are the size (user wise) of the + IRC network, and the usual duration of "network splits". It SHOULD + be uniform on all servers for a given IRC network. + +5.8 Flood control of clients + + With a large network of interconnected IRC servers, it is quite easy + for any single client attached to the network to supply a continuous + stream of messages that result in not only flooding the network, but + also degrading the level of service provided to others. Rather than + require every 'victim' to provide their own protection, flood + protection was written into the server and is applied to all clients + except services. The current algorithm is as follows: + + * check to see if client's `message timer' is less than current time + (set to be equal if it is); + + * read any data present from the client; + + * while the timer is less than ten (10) seconds ahead of the current + time, parse any present messages and penalize the client by two (2) + seconds for each message; + + * additional penalties MAY be used for specific commands which + generate a lot of traffic across the network. + + This in essence means that the client may send one (1) message every + two (2) seconds without being adversely affected. Services MAY also + be subject to this mechanism. + +5.9 Non-blocking lookups + + In a real-time environment, it is essential that a server process + does as little waiting as possible so that all the clients are + serviced fairly. Obviously this requires non-blocking IO on all + network read/write operations. For normal server connections, this + was not difficult, but there are other support operations that may + cause the server to block (such as disk reads). Where possible, such + activity SHOULD be performed with a short timeout. + +5.9.1 Hostname (DNS) lookups + + Using the standard resolver libraries from Berkeley and others has + meant large delays in some cases where replies have timed out. To + avoid this, a separate set of DNS routines were written for the + current implementation. Routines were setup for non-blocking IO + operations with local cache, and then polled from within the main + server IO loop. + +5.9.2 Username (Ident) lookups + + Although there are numerous ident libraries (implementing the + "Identification Protocol" [IDENT]) for use and inclusion into other + programs, these caused problems since they operated in a synchronous + manner and resulted in frequent delays. Again the solution was to + write a set of routines which would cooperate with the rest of the + server and work using non-blocking IO. + +6. Current problems + + There are a number of recognized problems with this protocol, all of + which are hoped to be solved sometime in the near future during its + rewrite. Currently, work is underway to find working solutions to + these problems. + +6.1 Scalability + + It is widely recognized that this protocol does not scale + sufficiently well when used in a large arena. The main problem comes + from the requirement that all servers know about all other servers + and clients and that information regarding them be updated as soon as + it changes. It is also desirable to keep the number of servers low + so that the path length between any two points is kept minimal and + the spanning tree as strongly branched as possible. + +6.2 Labels + + The current IRC protocol has 4 types of labels: the nickname, the + channel name, the server name and the service name. Each of the four + types has its own domain and no duplicates are allowed inside that + domain. Currently, it is possible for users to pick the label for + any of the first three, resulting in collisions. It is widely + recognized that this needs reworking, with a plan for unique names + for nicks that don't collide being desirable as well as a solution + allowing a cyclic tree. + +6.2.1 Nicknames + + The idea of the nickname on IRC is very convenient for users to use + when talking to each other outside of a channel, but there is only a + finite nickname space and being what they are, it's not uncommon for + several people to want to use the same nick. If a nickname is chosen + by two people using this protocol, either one will not succeed or + both will be removed by use of KILL (See Section 3.7.1 of "IRC Client + Protocol" [IRC-CLIENT]). + +6.2.2 Channels + + The current channel layout requires that all servers know about all + channels, their inhabitants and properties. Besides not scaling + well, the issue of privacy is also a concern. A collision of + channels is treated as an inclusive event (people from both nets on + channel with common name are considered to be members of it) rather + than an exclusive one such as used to solve nickname collisions. + + This protocol defines "Safe Channels" which are very unlikely to be + the subject of a channel collision. Other channel types are kept for + backward compatibility. + +6.2.3 Servers + + Although the number of servers is usually small relative to the + number of users and channels, they too are currently REQUIRED to be + known globally, either each one separately or hidden behind a mask. + +6.3 Algorithms + + In some places within the server code, it has not been possible to + avoid N^2 algorithms such as checking the channel list of a set of + clients. + + In current server versions, there are only few database consistency + checks, most of the time each server assumes that a neighbouring + server is correct. This opens the door to large problems if a + connecting server is buggy or otherwise tries to introduce + contradictions to the existing net. + + Currently, because of the lack of unique internal and global labels, + there are a multitude of race conditions that exist. These race + conditions generally arise from the problem of it taking time for + messages to traverse and effect the IRC network. Even by changing to + unique labels, there are problems with channel-related commands being + disrupted. + +7. Security Considerations + +7.1 Authentication + + Servers only have two means of authenticating incoming connections: + plain text password, and DNS lookups. While these methods are weak + and widely recognized as unsafe, their combination has proven to be + sufficient in the past: + + * public networks typically allow user connections with only few + restrictions, without requiring accurate authentication. + + * private networks which operate in a controlled environment often + use home-grown authentication mechanisms not available on the + internet: reliable ident servers [IDENT], or other proprietary + mechanisms. + + The same comments apply to the authentication of IRC Operators. + + It should also be noted that while there has been no real demand over + the years for stronger authentication, and no real effort to provide + better means to safely authenticate users, the current protocol + offers enough to be able to easily plug-in external authentication + methods based on the information that a client can submit to the + server upon connection: nickname, username, password. + +7.2 Integrity + + Since the PASS and OPER messages of the IRC protocol are sent in + clear text, a stream layer encryption mechanism (like "The TLS + Protocol" [TLS]) could be used to protect these transactions. + +8. Current support and availability + + Mailing lists for IRC related discussion: + General discussion: ircd-users@irc.org + Protocol development: ircd-dev@irc.org + + Software implementations: + ftp://ftp.irc.org/irc/server + ftp://ftp.funet.fi/pub/unix/irc + ftp://coombs.anu.edu.au/pub/irc + + Newsgroup: alt.irc + +9. Acknowledgements + + Parts of this document were copied from the RFC 1459 [IRC] which + first formally documented the IRC Protocol. It has also benefited + from many rounds of review and comments. In particular, the + following people have made significant contributions to this + document: + + Matthew Green, Michael Neumayer, Volker Paulsen, Kurt Roeckx, Vesa + Ruokonen, Magnus Tjernstrom, Stefan Zehl. + +10. References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [IRC] Oikarinen, J. and D. Reed, "Internet Relay Chat + Protocol", RFC 1459, May 1993. + + [IRC-ARCH] Kalt, C., "Internet Relay Chat: Architecture", RFC 2810, + April 2000. + + [IRC-CLIENT] Kalt, C., "Internet Relay Chat: Client Protocol", RFC + 2812, April 2000. + + [IRC-CHAN] Kalt, C., "Internet Relay Chat: Channel Management", RFC + 2811, April 2000. + + [ZLIB] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data + Format Specification version 3.3", RFC 1950, May 1996. + + [DEFLATE] Deutsch, P., "DEFLATE Compressed Data Format + Specification version 1.3", RFC 1951, May 1996. + + [GZIP] Deutsch, P., "GZIP file format specification version + 4.3", RFC 1952, May 1996. + + [IDENT] St. Johns, M., "The Identification Protocol", RFC 1413, + February 1993. + + [TLS] Dierks, T. and C. Allen, "The TLS Protocol", RFC 2246, + January 1999. + +11. Author's Address + + Christophe Kalt + 99 Teaneck Rd, Apt #117 + Ridgefield Park, NJ 07660 + USA + + EMail: kalt@stealth.net + +12. Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. diff --git a/doc/technical/send.txt b/doc/technical/send.txt new file mode 100644 index 0000000..38fd916 --- /dev/null +++ b/doc/technical/send.txt @@ -0,0 +1,262 @@ +PREFIXES +======== + + Server prefixes are the ":%s" strings at the beginning of messages. +They are used by servers to route the message properly and by servers to +local clients to update their idea of who is whom. + +":nick!user@host" is a prefix ":name" where name is either a nick +or name of a server is another valid prefix. + +Typical prefix for a local client to a channel: + +":Dianora!db@irc.db.net" + +for a prefix to a remote server: +":Dianora" + +e.g. as seen locally on a channel: + +":Dianora!db@irc.db.net PRIVMSG #us-opers :ON TOP OF ...\r\n" + +e.g. as seen sent to a remote server: +":Dianora PRIVMSG #us-opers :ON TOP OF ...\r\n" + + It has been argued that full prefixes sent locally are a waste of bandwidth +(Isomer from Undernet has argued this). i.e. instead of sending: +":nick!user@host" for a local prefix, one could just send ":nick".. +Unfortunately, this breaks many clients badly. Personally I feel that +until clients are updated to understand that a full prefix isn't always +going to be sent, that this should be held off on. + + As much as possible, prefix generation is now moved "upstairs" as +much as possible. i.e. if its known its a local client only, then the +onus of the prefix generation, is the users, not hidden in send.c +This allows somewhat faster code to be written, as the prefix doesn't +have to be regenerated over and over again. + + Prefixes aren't sent in all cases, such as a new user using NICK +A prefix is needed when it must be routed. + +i.e. + +NICK newnick + + There is obviously no prefix needed from a locally connected client. + + + +FUNCTIONS +========= + +sendto_one() - Should be used for _local_ clients only + it expects the prefix to be pre-built by user. + + usage - sendto_one(struct Client *to, char *pattern, ...); + + typical use: + + sendto_one(acptr,":%s NOTICE %s :I'm tired", me.name); + Note: This was from a server "me" hence only one + name in prefix. + + This would be an example of a client sptr, noticing + acptr IF acptr is known to be a local client: + + sendto_one(acptr,":%s!%s@%s NOTICE %s :You there?", + sptr->name, + sptr->username, + sptr->host, + acptr->name); + +sendto_channel_butone() + - This function sends a var args message to a channel globally, + except to the client specified as "one", the prefix + is built by this function on the fly as it has to + be sent both to local clients on this server and to + remote servers. +D clients are omitted, as this is used + only for PRIVMSG/NOTICE. + + usage - sendto_channel_butone(struct Client *one, + struct Client *from, + struct Channel *chptr, + const char *pattern, ... ); + + sendto_channel_butone(cptr, sptr, chptr + "PRIVMSG %s :HI!", + chptr->chname); + + e.g. if channel message is coming from "cptr" + it must not be sent back to cptr. + + +sendto_ll_serv_butone(struct Client *one, struct Client *sptr, int add, + const char *pattern, ...) + + - This function is almost identical to sendto_channel_butone + however, it will also not send on a nick as given by sptr, + if target server does not "know" about it. + As the name implies, it is used for "lazylinks" + +sendto_server() + - This function sends specified var args message + to all connected servers except the client "one" + - chptr can be NULL, in which case it goes to server + - caps is a set of CAPS to send =to= + - nocaps is a set of CAPS to not send =to= + + usage - sendto_server(struct Client *one, + struct Channel *chptr, + unsigned long caps, + unsigned long nocaps, + unsigned long llflags, + const char *pattern, ... ); + + +sendto_common_channels_local() + - This function is used only by m_nick and exit_one_client + its used to propagate nick changes to all channels user + is in, and QUIT messages to all channels user is in. + As it only sends to local clients, prefix generation + is left to the user. It also sends the message to the + user if the user isn't on any channels. + + usage - sendto_common_channels_local(struct Client *user, + const char *pattern, + ...); + +sendto_channel_local() + - This function is used only to send locally, never + to remote servers. This is useful when removing + local chanops, or adding a local chanop. MODE/SJOIN + sent to remote server allows that server to propagate + mode changes to its clients locally. If nodeaf is YES, + +D clients are omitted (used for delivering WALLCHOPS). + + usage - sendto_channel_local(type, nodeaf, + struct Channel *chptr, + const char *pattern, ... ); + + + prefix must be pre-built. type is a flag + denoting ONE of + ALL_MEMBERS - all members locally are sent to + NON_CHANOPS - only non-chanops see this + ONLY_CHANOPS_VOICED - both chanops and voiced see this + ONLY_CHANOPS - only chanops see this + + +sendto_match_butone() +match_it() - both only used for the old style oper masking + i.e. /msg #hostmask which in hyb7 is /msg $#hostmask + or /msg $servermask in hyb7 /msg $$servermask + + usage - match_it(struct Client *one, + const char *mask, + int what); + + one is the client to match on either hostmask or servermask + mask is the actual mask + what is either MATCH_HOST or MATCH_SERVER + + usage - sendto_match_butone(struct Client *one, + struct Client *from, + char *mark, + int what, + const char *pattern, ... ); + +sendto_channel_remote() + - Is only used to send a message to a remote server + + +sendto_match_cap_servs() + - Is used only to send MODE lists to remote server + who are capable of it. i.e. MODE #channel +e nick!user@host + +sendto_match_noncap_servs() + - Is used only to send MODE lists to remote servers that + are not capable of it. i.e. MODE #channel +o nick + - This allows you to send a MODE #channel +h nick via + sendto_match_cap_servs and MODE #channel +o nick to + servers which don't support it. + +sendto_anywhere() + - Allows the sending of a message to any client on the net + without knowing whether its local or remote. The penalty + is the calculation of a run-time prefix. + It is less efficient then sendto_one() + + usage - sendto_anywhere(struct Client *to, + struct Client *from, + const char *pattern, ...); + + e.g. + sendto_anywhere(acptr, sptr, + "PRIVMSG Larz :Hi, Where ever you are"); + +sendto_realops_flags() + - combines old sendto_realops and sendto_realops_flags + sends specified message to opers locally only + depending on two flags, UMODE i.e. +y +d or UMODE_SERVNOTICE + or special case, UMODE_ALL (see client.h UMODE flags ) + to send to any oper. The second flag gives the level + of whom to send the messages to, OPERS, ADMINS only or both. + (See send.h for those flags) + + usage - sendto_realops_flags(int umode, int level, + const char *pattern, ... ); + + e.g. + sendto_realops_flags(UMODE_ALL, L_ALL, + "Don't eat the yellow snow"); + +sendto_wallops_flags() + - sends specified message to opers locally, + depending on flags. used for messages that need + to be in wallops form + + usage - sendto_wall_flags(int flags, + struct Client *, const char *patterm ...); + + e.g. + sendto_wallops_flags(UMODE_WALLOP, + sptr, "Message"); + +ts_warn() - Only used to send warning messages to all opers + without flooding them with warnings. + It limits the number of warnings to no more than 5 + every 5 seconds. It probably can go away now. + + usage - ts_warn(const char *pattern, ... ); + +*** LOCAL HELPER FUNCTIONS (static) *** + +send_format() - Used to format a varargs buffer into given buffer + returns length of buffer built, enforces RFC1459 length + limits and appends \r\n as per rfc. + + usage - send_format(char *sendbuf, + const char *pattern, ... ); + +send_message() + - This local function does the actual send of message + + usage: send_message(struct Client *to, char *msg, int len); + + The message has to be pre-formatted and the length + must be pre-calculated. + +send_message_remote() + - This local function does the actual send of message to + remote clients + + usage: send_message_remote(struct Client *to, + struct Client *from, char *msg, int len); + + The message has to be pre-formatted and the length + must be pre-calculated. + + +-- Diane Bruce + +$Id$ diff --git a/doc/technical/ts3.txt b/doc/technical/ts3.txt new file mode 100644 index 0000000..e2f4927 --- /dev/null +++ b/doc/technical/ts3.txt @@ -0,0 +1,321 @@ +$Id$ + Protocol changes for +TSora + --------------------------- + +Note: + +The protocols described here implement TimeStamps on IRC channels and +nicks. The idea of IRC TimeStamps was started on Undernet, and first +implemented by Run <carlo@runaway.xs4all.nl>. The protocols used here +are not exactly the same as the ones used on Undernet; the nick-kill +handling is very similar and must be credited to Run, while the +"TimeStamped channel description" protocol is quite different. + +TSora servers keep track of which version of the TS protocol (if any) +their neighboring servers are using, and take it into account when +sending messages to them. This allows for seamless integration of TS +servers into a non-TS net, and for upgrades of the protocol. + +Each server knows which is the lowest and the highest version of the +TS protocol it can interact with; currently both of these are set to 1: + +#define TS_CURRENT 1 /* the highest TS ver we can do */ +#define TS_MIN 1 /* the lowest TS ver we can do */ + +Timings and TS versions: +======================== + +. Keep a 'delta' value to be added to the result of all calls to time(), + initially 0. + +. Send a second argument to the PASS command, ending in the 'TS' string. + +. Send a + + SVINFO <TS_CURRENT> <TS_MIN> <STANDALONE> :<UTC-TIME> + + just after "SERVER", where <STANDALONE> is 1 if we're connected to + more TSora servers, and 0 if not, and <UTC-TIME> is our idea of the + current UTC time, fixed with the delta. + +. When we receive a "SVINFO <x> <y> <z> :<t>" line from a connecting + server, we ignore it if TS_CURRENT<y or x<TS_MIN, otherwise we + set a flag remembering that that server is TS-aware, remember the TS + version to use with it (min(TS_CURRENT, x)). Additionally, if this is + our first connected TS server, we set our delta to t-<OUR_UTC> if + z==0, and to (t-<OUR_UTC>)/2 if z!=0. The SVINFO data is kept around + until the server has effectively registered with SERVER, and used + *after* sending our own SVINFO to that server. + +Explanations: + + Servers will always know which of their directly-linked servers can do + TS, and will use the TS protocol only with servers that do understand + it. This makes it possible to switch to full TS in just one + code-replacement step, without incompatibilities. + + As long as not all servers are TS-aware, the net will be divided into + "zones" of linked TS-aware servers. Channel modes will be kept + synchronized at least within the zone in which the channel was + created, and nick collisions between servers in the same zone will + result in only one client being killed. + + Time synchronization ensures that servers have the same idea of the + current time, and achieves this purpose as long as TS servers are + introduced one by one within the same 'zone'. The merging of two zones + cannot synchronize them completely, but it is to be expected that + within each zone the effective time will be very close to the real + time. + + By sending TSINFO after SERVER rather than before, we avoid the extra + lag created by the identd check on the server. To be able to send + immediately a connect burst of either type (TS or not), we need to + know before that if the server does TS or not, so we send that + information with PASS as an extra argument. And to avoid being + incompatible with 2.9 servers, which check that this second argument + begins with "2.9", we check that it *ends* with "TS". + + The current time is only used when setting a TS on a new channel or + nick, and once such a TS is set, it is never modified because of + synchronization, as it is much more important that the TS for a + channel or nick stays the same across all servers than that it is + accurate to the second. + + Note that Undernet's 2.8.x servers have no time synchronization at + all, and have had no problems because of it - all of this is more to + catch the occasional server with a way-off clock than anything. + +NICK handling patches (anti-nick-collide + shorter connect burst): +================================================================== + +. For each nick, store a TS value = the TS value received if any, or our + UTC+delta at the time we first heard of the nick. TS's are propagated + to TS-aware servers whenever sending a NICK command. + +. Nick changes reset the TS to the current time. + +. When sending a connect burst to another TS server, replace the + NICK/USER pair with only one NICK command containing the nick, the + hopcount, the TS, the umode, and all the USER information. + + The format for a full NICK line is: + NICK <nick> <hops> <TS> <umode> <user> <host> <server> :<ircname> + + The umode is a + followed by any applying usermodes. + + The format for a nick-change NICK line is: + :<oldnick> NICK <newnick> :<TS> + +. When a NICK is received from a TS server, that conflicts with an + existing nick: + + if the userhosts differ or one is not known: + * if the timestamps are equal, kill ours and the old one if it + was a nick change + * if the incoming timestamp is older than ours, kill ours and + propagate the new one + * if the incoming timestamp is younger, ignore the line, but kill + the old nick if it was a nick change + + if the userhosts are the same: + * if the timestamps are equal, kill ours and the old one if it + was a nick change + * if the incoming timestamp is younger, kill ours and propagate + the new one + * if the incoming timestamp is older, ignore the line but kill + the old nick if it was a nick change + +. When a NICK is received from a non-TS server that conflicts with + an existing nick, kill both. + +. Do not send "Fake Prefix" kills in response to lines coming from TS + servers; the sanitization works anyway, and this allows the "newer + nick overruled" case to work. + +Explanations: + + The modified nick-introduction syntax allows for a slightly shorter + connect-burst, and most importantly lets the server compare + user@host's when determining which nick to kill: if the user@host + is the same, then the older nick must be killed rather than the + newer. + + When talking to a non-TS server, we need to behave exactly like one + because it expects us to. When talkign to a TS server, we don't kill + the nicks it's introducing, as we know it'll be smart enough to do it + itself when seeing our own introduced nick. + + When we see a nick arriving from a non-TS server, it won't have a TS, + but it's safe enough to give it the current time rather than keeping + it 0; such TS's won't be the same all across the network (as long as + there is more than one TS zone), and when there's a collision, the TS + used will be the one in the zone the collision occurs in. + + Also, it is important to note that by the time a server sees (and + chooses to ignore) a nick introduction, the introducing server has + also had the time to put umode changes for that nick on its queue, so + we must ignore them too... so we need to ignore fake-prefix lines + rather than sending kills for them. This is safe enough, as the rest + of the protocol ensures that they'll get killed anyway (and the + Undernet does it too, so it's been more than enough tested). Just for + an extra bit of compatibility, we still kill fake prefixes coming from + non-TS servers. + + This part of the TS protocol is almost exactly the same as the + Undernet's .anc (anti-nick-collide) patches, except that Undernet + servers don't add usermodes to the NICK line. + +TimeStamped channel descriptions (avoiding hacked ops and desynchs): +==================================================================== + +. For each channel, keep a timestamp, set to the current time when the + channel is created by a client on the local server, or to the received + value if the channel has been propagated from a TS server, or to 0 + otherwise. This value will have the semantics of "the time of creation + of the current ops on the channel", and 0 will mean that the channel + is in non-TS mode. + + A new server protocol command is introduced, SJOIN, which introduces + a full channel description: a timestamp, all the modes (except bans), + and the list of channel members with their ops and voices. This + command will be used instead of JOIN and of (most) MODEs both in + connect bursts and when propagating channel creations among TS + servers. SJOIN will never be accepted from or sent to users. + + The syntax for the command is: + + SJOIN <TS> #<channel> <modes> :[@][+]<nick_1> ... [@][+]<nick_n> + + The fields have the following meanings: + + * <TS> is the timestamp for the channel + + * <modes> is the list of global channel modes, starting with a + + and a letter for each of the active modes (spmntkil), followed + by an argument for +l if there is a limit, and an argument for + +k if there's a key (in the same order they were mentioned in + the string of letters). + + A channel with no modes will have a "+" in that field. + + A special value of "0" means that the server does not specify the + modes, and will be used when more than one SJOIN line is needed + to completely describe a channel, or when propagating a SJOIN + the modes of which were rejected. + + * Each nick is preceded by a "@" if the user has ops, and a "+" if + the user has a voice. For mode +ov, both flags are used. + + SJOINs will be propagated (when appropriate) to neighboring TS + servers, and converted to JOINs and MODEs for neighboring non-TS + servers. + + To propagate channels for which not all users fit in one + SJOIN line, several SJOINs will be sent consecutively, only the first + one including actual information in the <mode> field. + + An extra ad-hoc restriction is imposed on SJOIN messages, to simplify + processing: if a channel has ops, then the first <nick> of the first + SJOIN sent to propagate that channel must be one of the ops. + + Servers will never attempt to reconstruct a SJOIN from JOIN/MODE + information being received at the moment from other servers. + +. For each user on a channel, keep an extra flag (like ops and voice) + that is set when the user has received channel ops from another + server (in a SJOIN channel description), which we rejected (ignored). + Mode changes (but NOT kicks) coming from a TS server and from someone + with this flag set will be ignored. The flag will be reset when the + user gets ops from another user or server. + +. On deops done by non-local users, coming from TS servers, on channels + with a non-zero TS, do not check that the user has ops but check that + their 'deopped' flag is not set. For kicks coming from a TS server, do + not check either. This will avoid desynchs, and 'bad' modechanges are + avoided anyway. Other mode changes will still only be taken into + account and propagated when done by users that are seen as having ops. + +. When a MODE change that ops someone is received from a server for a + channel, that channel's TS is set to 0, and the mode change is + propagated. + +. When a SJOIN is received for a channel, deal with it in this way: + * received-TS = 0: + + if we have ops or the SJOIN doesn't op anyone, SJOIN propagated + with our own TS. + + otherwise, TS set to 0 and SJOIN propagated with 0. + * received-TS > 0, own-TS = 0: + + if the SJOIN ops someone or we don't have ops, set our TS to the + received TS and propagate. + + otherwise, propagate with TS = 0. + * received-TS = own-TS: propagate. + * received-TS < own-TS: + + if the SJOIN ops someone, remove *all* modes (except bans) from + the channel and propagate these mode changes to all neighboring + non-TS servers, and copy the received TS and propagate the SJOIN. + + if the SJOIN does not op anyone and we have ops, propagate + with our own TS. + + otherwise, copy the received TS and propagate the SJOIN. + * received-TS > own-TS: + + if the SJOIN does not introduce any ops, process and propagate + with our own TS. + + if we have ops: for each person the mode change would op, set the + 'deopped' flag; process all the JOINs ignoring the '@' and '+' + flags; propagate without the flags and with our TS. + + if we don't have ops: set our TS to the received one, propagate + with the flags. + +Explanations: + + This part of the protocol is the one that is most different (and + incompatible) with the Undernet's: we never timestamp MODE changes, + but instead we introduce the concept of time-stamped channel + descriptions. This way each server can determine, based on its state + and the received description, what the correct modes for a channel + are, and deop its own users if necessary. With this protocol, there is + *never* the need to reverse and bounce back a mode change. This is + both faster and more bandwith-effective. + + The end goal is to have a protocol will eventually protect channels + against hacked ops, while minimizing the impact on a mixed-server net. + In order to do this, whenever there is a conflict between a TS server + and a non-TS one, the non-TS one's idea of the whole situation + prevails. This means that channels will only have a TS when they have + been created on a TS-aware server, and will lose it whenever a server + op comes from a non-TS server. Also, at most one 'zone' will have a TS + for any given channel at any given time, ensuring that there won't be + any deops when zones are merged. However, when TS zones are merged, if + the side that has a TS also has ops, then the TS is kept across the + whole new zone. Effective protection will only be ensured once all + servers run TS patches and channels have been re-created, as there is + no way servers can assign a TS to a channel they are not creating + (like they do with nicks) without having unwanted deops later. + + The visible effects of this timestamped channel-description protocol + are that when a split rejoins, and one side has hacked ops, the other + side doesn't see any server mode changes (just like with Undernet's + TS), but the side that has hacked ops sees: + + * first the first server on the other side deopping and devoicing + everyone, and fixing the +spmntkli modes + * then other users joining, and getting server ops and voices + + The less obvious part of this protocol is its behavior in the case + that the younger side of a rejoin has servers that are lagged with + each other. In such a situation, a SJOIN that clears all modes and + sets the legitimate ones is being propagated from one server, and + lagged illegitimate mode changes and kicks are being propagated in the + opposite direction. In this case, a kick done by someone who is being + deopped by the SJOIN must be taken into account to keep the name list + in sync (and since it can only be kicking someone who also was on the + younger side), while a deop does not matter (and will be ignored by + the first server on the other side), and an opping *needs* to be + discareded to avoid hacked ops. + + The main property of timestamped channel descriptions that makes them + a very stable protocol even with lag and splits, is that they leave a + server in the same final state, independently of the order in which + channel descriptions coming from different servers are received. Even + when SJOINs and MODEs for the same channel are being propagated in + different direction because of several splits rejoining, the final + state will be the same, independently of the exact order in which each + server received the SJOINs, and will be the same across all the + servers in the same zone. diff --git a/doc/technical/ts5.txt b/doc/technical/ts5.txt new file mode 100644 index 0000000..de10506 --- /dev/null +++ b/doc/technical/ts5.txt @@ -0,0 +1,147 @@ + Overview of the TS5 system + Lee H <lee@leeh.co.uk> + +$Id$ + +For the purposes of this document, ircd versions: + hybrid6.0 + ircd-comstud-1.12 + CSr31pl4 + +and prior, are TS3. + +ircd-hybrid-6.2 and later support TS5. + +Whats TS5? +---------- + +The difference between TS5 and TS3 is what happened on opless channels. TS +works by establishing which server has the oldest version of the channel, +the version that is oldest, keeps its modes and ops, the version that is +youngest, removes their modes and ops, and accepts the older version. + +There was an exception to this rule with opless channels, if a channel was +opless, TS3 would allow anybody to keep their ops and modes on the channel. +TS5 aims to stop this, by removing this exception. + +Example1: + +An irc network, with server A (every server is ts3) + +UserA is on ServerA, in channel #broken. This channel is opless, and has a +TS of 800000000. ServerA splits, and whilst it is split, UserA cycles +channel #broken, recreates the channel and is given ops. On ServerA #broken +now has a TS of 900000000 and has ops. ServerA rejoins with the network, +via HubB. HubB realises #broken is opless, so allows UserA to retain ops. +The TS is moved forward to 900000000. + +The network now sees #broken as having a TS of 900000000, with UserA being +opped. + +Example2: + +An irc network, with server C (every server is ts5) + +Same scenario as above. ServerC splits and UserC cycles channel #broken, +recreating it with a TS of 900000000. ServerC rejoins with the network via +HubD. HubD realises #broken has a TS of 800000000 locally, and ServerC is +showing a TS of 900000000, it ignores ServerC's modes and ops. The channel +remains opless. ServerC receives HubD's modes, and it notices HubD has a +lower TS of channel #broken. It removes UserC's ops, removes the channel +modes on #broken, and accepts HubD's status. + +The network version of #broken hasnt changed. It is still opless, with a TS +of 800000000. + + +As you can see, TS5 makes splitting a server to regain ops useless, as it +cannot be abused to give ops after a netsplit. + +The problem with TS5 however, is what happens on a mixed TS5/TS3 network. +Channels where the older TS has ops will behave the same way on TS5 and TS3, +however an opless channel will behave differently, as you can see above. + +The result of TS5/TS3 mixed can be a desync: + +Example1: + +As per Example1 above, except the rest of the network is TS5, ServerA is +TS3. ServerA would keep its modes and ops, whilst the rest of the network +would remove them. This means only ServerA would see UserA as opped. The +desync can be abused, as UserA can send modes. Hybrid6.0 servers will +accept these modes from the unopped client, so if UserA ops UserB, who then +ops UserA, the channel will be the same across all Hybrid6.0 and Hybrid6.1 +servers. + +Example2: + +As per Example2 above, except the rest of the network is TS3. ServerC is +TS5. ServerC would remove its modes and ops, therefore UserC would not be +opped on ServerC, therefore it could not send any mode changes to the +channel. Although it is opped elsewhere, it isnt opped locally, so the +desync cannot be abused. + +As you can see, the desync's that can occur can either be resynced, or are +useless to the user, so a mixed TS5/TS3 network is not a huge problem, +although a desync is NOT a good thing to have. + + +Why TS5? +-------- + +We have jumped to TS5 from TS3, because there was a version of ircd that was +TS4, so it was thought better to avoid a clash with an existing version. + + +Advantages +---------- + +It's a realistic event that a server will be attacked so it splits off a +network, then used to regain ops in a channel. TS5 makes this pointless, +the server will never give ops on a netsplit. TS5 is network wide, so it +leaves individual servers free to choose options like NO_JOIN_ON_SPLIT, +whilst keeping splits useless to users. + + +Disadvantages +------------- + +It's virtually impossible for a user to actively regain ops themselves (some +regard this as an advantage..) because on a large sized channel, its +impossible to get people to leave so it can be recreated, therefore if a +network did not have some form of services, it could possibly end up +requiring oper intervention, as you cant get everybody to leave, and you +cant use splits to regain ops, therefore if the channel is open (an +invite-only channel would gradually destroy itself as noone new can join) it +could be impossible for a user to regain ops. + +On a network that has some form of services, The effect of TS5 would be +minimal, however the services must be of sufficient quality to fix opless +channels, as TS5 renders netsplits for ops worthless. + + +Recommendations +--------------- + +If your network has good stable services, we recommend TS5 is enabled, as +people have no reason to abuse netsplits anyway. + +If your network has no services at all, then TS5 may cause problems with +users being left with a permanently opless channel. + +If your network occupies the middle ground, then its a choice between users +needing to be able to use splits to regain ops, or making netsplits that are +caused to regain ops worthless. + +If TS5 is chosen, the FULL network must upgrade and this should be done in a +relatively short space of time to minimise the possible desync effects. + + +Alternatives +------------ + +There is also NO_JOIN_ON_SPLIT and NO_OP_ON_SPLIT, however these use the +configuration of minimum servers and users, and sometimes a split that is +above these limits is enough to be abused to regain ops, whereas if the +limits are too high, clients will never be able to join anything or be opped +when they create a channel. diff --git a/doc/technical/ts6.txt b/doc/technical/ts6.txt new file mode 100644 index 0000000..d1e29e8 --- /dev/null +++ b/doc/technical/ts6.txt @@ -0,0 +1,267 @@ +$Id$ + +TS6 Proposal (v7) +Written by Lee H <lee@leeh.co.uk> + +Introduction +------------ + +This document aims to fix some of the flaws that are still present in the +current TS system. + +Whilst only one person may use a nickname at any one time, they are not +a reliable method of directing commands between servers. Clients can change +their nicknames, which can create desyncs. A reliable method of directing +messages between servers is required so that a message will always reach the +intended destination, even if the client changes nicks in between. + +UID solves this problem by ensuring that a client has a unique ID for the +duration of his connection. + +This document also aims to solve the lack of TS rules to channel 'bans' on +a netburst. Bans from both sides of a TS war (losing/winning) are kept. +Bursting the bans with a TS solves this problem. + +There is also a race condition in the current TS system, where a user can +issue a mode during a netburst and the mode will be set on the server +we are bursting to. + + +Definitions +----------- + +Throughout this document, the following terms are used: + +SID - A servers unique ID. This is three characters long and must be in + the form [0-9][A-Z0-9][A-Z0-9] +ID - A clients unique ID. This is six characters long and must be in + the form [A-Z][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9]. The + numbers [0-9] at the beginning of an ID are legal characters, but + reserved for future use. +UID - An ID concateneted to a SID. This forms the clients UID. +TS6 - The TS version 6. + + +Support +------- + +Support for this document is given by the TS version 6. + +Wherever a destination parameter or source parameter is used, it must use +the SID or UID if the server/client has one. A TS6 capable server must +translate any SIDs/UIDs back into the server/clients name when communicating +with a server that does not support TS6. + +A TS6 server must also support the QS (quitstorm) system, and the encap +specification found here: +http://www.leeh.co.uk/ircd/encap.txt + +The TS6 protocol does not supports masked entities. + + +Nick TS rules +------------- + +A server receiving a command that requires nick TS rules must check for a +collision between an existing user, and the nick in the received message. +(the "new user"). The collisions must obey the rules specified in Nick TS +collisions. + +If the TS received is lower than the TS of the existing user the server will +collide the existing user if the clients user@host are different, if the +clients user@hosts are identical it will collide the new user. + +If the TS received is equal to the TS of the existing user both clients are +collided. + +If the TS received is higher than the TS of the existing user, the server +will collide the existing user if the user@hosts are identical, if the +clients user@host are different it will collide the new user and drop the +message. + + +Nick TS collisions +------------------ + +If both users are to be collided, we must issue a KILL for the existing +user to all servers. If the new user has a UID then we must also issue a +KILL for that UID back to the server sending us data causing the collision. + +If only the existing user is being collided, we must issue a KILL for the +existing user to all servers except the server sending us data. If the +existing user has a UID and the server sending us data supports TS6 then +we must also issue a KILL for the existing users UID to the server sending +us data. + +If only the new user is being collided, we must issue a KILL for the new user +back to the server sending us data if the new user has a UID. + + +Channel TS rules +---------------- + +A server receiving a command that requires normal channel TS rules must +apply the following rules to the command. + +If the TS received is lower than our TS of the channel a TS6 server must +remove status modes (+ov etc) and channel modes (+nt etc). If the +originating server is TS6 capable (ie, it has a SID), the server must +also remove any ban modes (+b etc). The new modes and statuses are then +accepted. + +If any bans are removed, the server must send to non-TS6, directly connected +servers mode changes removing the bans after the command is propagated. +This prevents desync with banlists, and has to be sent after as clients are +still able to send mode changes before the triggering command arrives. + +If the TS received is equal to our TS of the channel the server should keep +its current modes and accept the received modes and statuses. + +If the TS received is higher than our TS of the channel the server should keep +its current modes and ignore the received modes and statuses. Any statuses +given in the received message will be removed. A server must mark clients +losing their op (+o) status who do not have a UID as 'deopped'. A server must +ignore any "MODE" commands from a user marked as 'deopped'. + + +Simple channel TS rules +----------------------- + +A server receiving a command that requires simple channel TS rules must +apply the following rules to the command. + +If the TS received is lower, or equal to our TS of the channel the modes are +accepted. If the TS received is higher than our TS of the channel the modes +are ignored and dropped. + +Simple channel TS rules do not affect current modes in the channel except +for the modes we are accepting. + + +The following commands are defined here as the TS6 protocol +----------------------------------------------------------- + +PASS: +PASS <PASSWORD> TS <TS_CURRENT> :<SID> + +This command is used for password verification with the server we are +connecting to. + +Due to the burst being sent on verification of the "SERVER" command, and +"SVINFO" being sent after "SERVER", we need to be aware of the TS version +earlier to decide whether to send a TS6 burst or not. + +The <PASSWORD> field is the password we have stored for this server, +<TS_CURRENT> is our current TS version. If this field is not present then +the server does not support TS6. <SID> is the SID of the server. + +UID: +:<SID> UID <NICK> <HOPS> <TS> +<UMODE> <USERNAME> <HOSTNAME> <IP> <UID> :<GECOS> + +This command is used for introducing clients to the network. + +The <SID> field is the SID of the server the client is connected to. +The <NICK> field is the nick of the client being introduced. The <HOPS> +field is the amount of server hops between the server being burst to and +the server the client is on. The <TS> field is the TS of the client, either +the time they connected or the time they last changed nick. The <UMODE> +field contains the clients usermodes that need to be transmitted between +servers. The <USERNAME> field contains the clients username/ident. The +<HOSTNAME> field contains the clients host. + +The <IP> field contains the clients IP. If the IP is not to be sent +(due to a spoof etc), the field must be sent as "0". The <UID> field is the +clients UID. The <GECOS> field is the clients gecos. + +A server receiving a UID command must apply nick TS rules to the nick. + +SID: +:<SID> SID <SERVERNAME> <HOPS> <SID> :<GECOS> + +This command is used for introducing servers to the network. + +The first <SID> field is the SID of the new servers uplink. The +<SERVERNAME> field is the new servers name. The <HOPS> field is the hops +between the server being introduced nd the server being burst to. + +The second <SID> field is the SID of the new server. The <GECOS> field i +is the new servers gecos. + +Upon receiving the SID command servers must check for a SID collision. +Two servers must not be allowed to link to the network with the same SID. +If a server detects a SID collision it must drop the link to the directly +connected server through which the command was received. + +Client and servers which do not have a UID/SID must be introduced by old +methods. + +SJOIN: +:<SID> SJOIN <TS> <CHANNAME> +<CHANMODES> :<UIDS> + +This command is used for introducing users to channels. + +The <SID> field is the SID of the server introducing users to the channel. +The <TS> field is the channels current TS, <CHANNAME> is the channels +current name, <CHANMODES> are the channels current modes. <UIDS> is a +space delimited list of clients UIDs to join to the channel. Each clients +UID is prefixed with their status on the channel, ie "@UID" for an opped +user. Multiple prefixes are allowed, "peons" (clients without a status) are +not prefixed. + +A server receiving an SJOIN must apply normal channel TS rules to the SJOIN. + +A TS6 server must not use the SJOIN command outside of a netburst +to introduce a single user to an existing channel. It must instead +use the "JOIN" command defined in this specification. A TS6 server must +still use SJOIN for creating channels. + +JOIN: +:<UID> JOIN <TS> <CHANNAME> +<CHANMODES> + +This command is used for introducing one user unopped to an existing channel. + +The <UID> field is the UID of the client joining the channel. The +<TS> field is the channels current TS, <CHANNAME> is the channels +current name, <CHANMODES> are the channels current modes. + +A server receiving a JOIN must apply normal channel TS rules to the JOIN. + +It should be noted that whilst JOIN would not normally create a +channel, during specific race conditions it can. This can create +a ban desync that this specification does not rectify. + +BMASK: +:<SID> BMASK <TS> <CHANNAME> <TYPE> :<MASKS> + +This command is used for bursting channel bans to a network. + +The <SID> field is the SID of the server bursting the bans. The +<TS> field is the channels current TS, <CHANNAME> is the channels +name. <TYPE> is a single character identifying the mode type (ie, +for a ban 'b'). <MASKS> is a space delimited list of masks of the +given mode,limited only in length to the size of the buffer as defined +by RFC1459. + +A server receiving a BMASK must apply simple channel TS rules to the BMASK. + +A TS6 server must translate BMASKs into raw modes for non-TS6 +capable servers. This command must be used only after SJOIN has +been sent for the given channel. + +It should be noted however, that a BMASK with a lower TS should +not be possible without a desync, due to it being sent after +SJOIN. + +TMODE: +:<UID> TMODE <TS> <CHANNAME> <MODESTRING> + +This command is used for clients issuing modes on a channel. + +<UID> is the UID of the client setting the mode. <TS> is the +current TS of the channel, <CHANNAME> is the channels name. +<MODESTRING> is the raw mode the client is setting. + +A server receiving a TMODE must apply simple channel TS rules to the TMODE. + +A TS6 server must translate MODEs issued by a local client into TMODE +to send to other TS6 capable servers. |