From 35b8bcc2a182c7465f6c6b9ccc35895bc87f2d6e Mon Sep 17 00:00:00 2001 From: Michael Poole Date: Sun, 17 Jul 2005 00:03:44 +0000 Subject: [PATCH] Update documentation to reflect impending release. git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1451 c9e4aea6-c8fd-4c43-8297-357d70d61c8c --- ChangeLog | 28 ++++++ README | 96 ++++++++++++++++---- README.FreeBSD | 37 -------- README.Solaris | 20 ----- RELEASE.NOTES | 4 +- doc/api/features.txt | 18 ++-- doc/api/modebuf.txt | 8 +- doc/api/motd.txt | 9 +- doc/example.conf | 4 +- doc/iauth.txt | 205 ------------------------------------------- doc/readme.features | 23 +++-- doc/readme.log | 43 ++++----- 12 files changed, 162 insertions(+), 333 deletions(-) delete mode 100644 README.FreeBSD delete mode 100644 README.Solaris delete mode 100644 doc/iauth.txt diff --git a/ChangeLog b/ChangeLog index 014f922..2219f05 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,31 @@ +2005-07-16 Michael Poole + + * RELEASE.NOTES: Mention that 2.10.11 does not support oplevels. + + * README.FreeBSD: Remove (merged into README). + + * README.Solaris: Remove (merged into README). + + * README: Merge in the above; also update for 2.10.12. + + * doc/example.conf: Change mention of K-lines to say Kill blocks + instead. + + * doc/iauth.txt: Remove (out of date). + + * doc/readme.features: Update to reflect that 2.10.11 is not the + current release. Change mention of various config lines to use + the equivalent config entries or blocks instead. + + * doc/readme.log: Likewise. + + * doc/api/features.txt: Change F-line mentions to say Feature + entry instead. + + * doc/api/modebuf.txt: Change U-line mention to say Uworld entry. + + * doc/api/motd.txt: Change T-line mentions to say Motd entry. + 2005-07-15 Michael Poole * ircd/ircd_features.c (feature_init): Always call diff --git a/README b/README index 9cff13a..e722967 100644 --- a/README +++ b/README @@ -1,7 +1,7 @@ - Welcome to ircu2.10.11, the Undernet IRC daemon + Welcome to ircu2.10.12, the Undernet IRC daemon -Version u2.10.11 of the Undernet ircd incorporates many new features +Version u2.10.12 of the Undernet ircd incorporates many new features over its predecessor, and we feel that using it will make you very happy indeed. @@ -26,24 +26,23 @@ README. files. COMPATIBILITY This version of ircu will only work with servers that use the P10 protocol, -some of the new features will only work between ircu2.10.11 servers. +some of the new features will only work between ircu2.10.12 servers. GENERAL PERFORMANCE HINTS -For platform-specific notes and hints, see the various README. -files included in this distribution. The notes below apply to servers that -will serve large numbers (thousands) of clients simultaneously. If your -server serves a small amount of users, you will not really have to do much -of anything about performance tuning. +For platform-specific notes and hints, see the platform-specific +sections below. These notes apply to servers that will serve large +numbers (thousands) of clients simultaneously. If your server serves +a small amount of users, the defaults should work well enough. - Run an OS that supports an asynchronous network event engine; currently these are FreeBSD (kqueue), and Solaris (/dev/poll); possibly other BSDs will also support kqueue. This will have a dramatic effect on performance. - Make things as lean as possible: Make your server dedicated to ircu, disable anything that is not neccesary, and build a custom kernel (where - possible). - - Tune kernel parameters; see the various README. files as well - as your OS documentation for more information. + possible). + - Tune kernel parameters as described in the platform-specific + sections below. - With many clients connecting each second, ircu will be doing lots of DNS lookups. Make sure that the DNS server(s) in your /etc/resolv.conf are as close as possible, or run a local caching DNS server on your IRC server. @@ -59,10 +58,8 @@ INFORMATION HIDING As per undernet-admins CFV-165, this server contains code that will, by default, hide certain information from ordinary users. If you do -not want this, please make sure you add -DINCLUDED_ircd_policy_h to -CFLAGS prior to running ./configure, like in: - -> CFLAGS=-DINCLUDED_ircd_policy_h ./configure +not want this, override the default "HIS" feature settings in your +ircd.conf. MORE INFORMATION @@ -72,3 +69,72 @@ in the doc/ directory, as well as http://coder-com.undernet.org. For general information on the Undernet, vist http://www.undernet.org Happy IRCing! + +RUNNING THIS SERVER ON LINUX + +If you run Linux 2.6 or above (or 2.4 with appropriate patches), ircu +can use the epoll family of system calls for much more efficient +checks of which connections are active. Most pre-epoll systems will +use 100% CPU with 2000 clients; with epoll, a server may use only a +few percent of CPU with the same load. + +To handle that many connections, the ircd must be started with a high +enough file descriptor resource. Check your distribution's docs on +how to set the global and per-user limits according to your expected +load. + +RUNNING THIS SERVER ON FREEBSD + +When running on FreeBSD, ircu can make use of the kqueue() event engine, which +results in much improved performance over the old poll()-based method. kqueue +is included in the more recent 4.x releases of FreeBSD. + +In order for ircu to be able to serve many clients simultaneously, you need +to increase the maximum allowable number of open files in the system. To do +this, add commands such as the following during your system's boot sequence: + +sysctl -w kern.maxfiles=16384 +sysctl -w kern.maxfilesperproc=16384 + +Unless you will be serving thousands of clients simultaneously, you will not +need to do the following, unless of course you just can't stand having a +system that is not optimized to its limits :) + +Build a custom kernel: Make your kernel as lean as possible by removing all +drivers and options you will not need. The following parameters will affect +performance, they are listed with suggested values only. For more information +on what they do exactly, see FreeBSD's documentation. + +maxusers 2048 +options NMBCLUSTERS=65535 +options ICMP_BANDLIM + +Also, you may wish to run the following at system startup (from /etc/rc.local, +or whichever other method you prefer): + +sysctl -w net.inet.tcp.rfc1323=1 +sysctl -w net.inet.tcp.delayed_ack=0 +sysctl -w net.inet.tcp.restrict_rst=1 +sysctl -w kern.ipc.maxsockbuf=2097152 +sysctl -w kern.ipc.somaxconn=2048 + +Created by Sengaia , July 20 2002. + +RUNNING THIS SERVER ON SOLARIS + +When running on Solaris, ircu can make use of the /dev/poll event engine, which +results in much improved performance over the old poll()-based method. Solaris +versions 8 and 9 include /dev/poll out of the box, for Solaris 7 you will have +to grab and install Patch-ID 106541-21. + +In order to increase the number of clients ircu can handle, add lines such as +the following to /etc/system: + +* set hard limit on file descriptors +set rlim_fd_max = 16384 +* set soft limit on file descriptors +set rlim_fd_cur = 8192 + +For more useful hints see http://www.sean.de/Solaris/soltune.html + +Created by Sengaia on July 20, 2002. diff --git a/README.FreeBSD b/README.FreeBSD deleted file mode 100644 index 2534ec5..0000000 --- a/README.FreeBSD +++ /dev/null @@ -1,37 +0,0 @@ -Running ircu2.10.11 on FreeBSD - -When running on FreeBSD, ircu can make use of the kqueue() event engine, which -results in much improved performance over the old poll()-based method. kqueue -is included in the more recent 4.x releases of FreeBSD. - -In order for ircu to be able to serve many clients simultaneously, you need -to increase the maximum allowable number of open files in the system. To do -this, add commands such as the following during your system's boot sequence: - -sysctl -w kern.maxfiles=16384 -sysctl -w kern.maxfilesperproc=16384 - -Unless you will be serving thousands of clients simultaneously, you will not -need to do the following, unless of course you just can't stand having a -system that is not optimized to its limits :) - -Build a custom kernel: Make your kernel as lean as possible by removing all -drivers and options you will not need. The following parameters will affect -performance, they are listed with suggested values only. For more information -on what they do exactly, see FreeBSD's documentation. - -maxusers 2048 -options NMBCLUSTERS=65535 -options ICMP_BANDLIM - -Also, you may wish to run the following at system startup (from /etc/rc.local, -or whichever other method you prefer): - -sysctl -w net.inet.tcp.rfc1323=1 -sysctl -w net.inet.tcp.delayed_ack=0 -sysctl -w net.inet.tcp.restrict_rst=1 -sysctl -w kern.ipc.maxsockbuf=2097152 -sysctl -w kern.ipc.somaxconn=2048 - -Created by Sengaia , July 20 2002. - diff --git a/README.Solaris b/README.Solaris deleted file mode 100644 index 565260a..0000000 --- a/README.Solaris +++ /dev/null @@ -1,20 +0,0 @@ - -Running ircu2.10.11 on Solaris - -When running on Solaris, ircu can make use of the /dev/poll event engine, which -results in much improved performance over the old poll()-based method. Solaris -versions 8 and 9 include /dev/poll out of the box, for Solaris 7 you will have -to grab and install Patch-ID 106541-21. - -In order to increase the number of clients ircu can handle, add lines such as -the following to /etc/system: - -* set hard limit on file descriptors -set rlim_fd_max = 16384 -* set soft limit on file descriptors -set rlim_fd_cur = 8192 - -For more useful hints see http://www.sean.de/Solaris/soltune.html - -Created by Sengaia on July 20, 2002. - diff --git a/RELEASE.NOTES b/RELEASE.NOTES index 0fe5523..5fe8067 100644 --- a/RELEASE.NOTES +++ b/RELEASE.NOTES @@ -7,8 +7,8 @@ Braden . This document briefly describes changes in ircu2.10.12 relative to ircu2.10.11. ircu2.10.12 is only compatible with servers that implement the P10 protocol. It has been tested to link against -ircu2.10.11, but some features (notably IPv6 support) are not -supported by ircu2.10.11. +ircu2.10.11, but some features (notably IPv6 support and oplevels) are +not supported by ircu2.10.11. Enhancements: diff --git a/doc/api/features.txt b/doc/api/features.txt index c4da018..f7288ee 100644 --- a/doc/api/features.txt +++ b/doc/api/features.txt @@ -61,13 +61,13 @@ through the configuration file. Marking Features When the configuration file is read, there must be some way to -determine if a particular F-line has been removed since the last time -the configuration file was read. The way this is done in the features -subsystem is to have a "mark" for each feature. Prior to reading the -configuration file, all marks are cleared for all features (and all -"unmark" call-backs are called). As each F-line is encountered and -processed, that feature's mark is set. Finally, when the -configuration file has been fully read, all remaining unmarked +determine if a particular Feature entry has been removed since the +last time the configuration file was read. The way this is done in +the features subsystem is to have a "mark" for each feature. Prior to +reading the configuration file, all marks are cleared for all features +(and all "unmark" call-backs are called). As each Feature entry is +encountered and processed, that feature's mark is set. Finally, when +the configuration file has been fully read, all remaining unmarked features are reset to their default values (and all "mark" call-backs are called). @@ -148,8 +148,8 @@ values for all features correctly. void feature_report(struct Client* to); -Reports all F-lines to a user using RPL_STATSFLINE, except those which -the user is not permitted to see due to flag settings. +Reports all Feature entries to a user using RPL_STATSFLINE, except +those which the user is not permitted to see due to flag settings. diff --git a/doc/api/modebuf.txt b/doc/api/modebuf.txt index 6655426..87568cb 100644 --- a/doc/api/modebuf.txt +++ b/doc/api/modebuf.txt @@ -101,10 +101,10 @@ should be sent. This flag will cause the server to generate a #define MODEBUF_DEST_HACK4 0x8000 /* Send a HACK(4) notice, TS == 0 */ -Some servers are special. When a server that has a U-line issues a -mode change, we send a "HACK(4)" message to differentiate it from an -ordinary server changing a channel mode. This is the flag that must -be passed to modebuf_init() to cause that behavior. +Some servers are special. When a server that has a Uworld entry +issues a mode change, we send a "HACK(4)" message to differentiate it +from an ordinary server changing a channel mode. This is the flag +that must be passed to modebuf_init() to cause that behavior. diff --git a/doc/api/motd.txt b/doc/api/motd.txt index 5d54cf4..d491162 100644 --- a/doc/api/motd.txt +++ b/doc/api/motd.txt @@ -19,12 +19,11 @@ int motd_send(struct Client* cptr); This function sends an appropriate MOTD to the client specified by _cptr_. If _cptr_ is not a local client, the remote MOTD will be -sent; otherwise, an attempt will be made to find a T-line in the -configuration file that matches the client. If no T-line can be +sent; otherwise, an attempt will be made to find a Motd entry in the +configuration file that matches the client. If no Motd entry can be found, the default MOTD will be sent to the client. This function returns 0 for the convenience of other functions that must have an -integer return value. - +integer return value. void motd_signon(struct Client* cptr); @@ -60,7 +59,7 @@ and remote MOTD are not affected by this function. void motd_report(struct Client *to); -The motd_report() function sends a list of the T-lines stored in +The motd_report() function sends a list of the Motd entries stored in memory to the client specified by _to_. Access control should be handled by the caller. diff --git a/doc/example.conf b/doc/example.conf index 85f4ec9..ae68ae0 100644 --- a/doc/example.conf +++ b/doc/example.conf @@ -461,9 +461,9 @@ Jupe { # # # The default reason is: "You are banned from this server" -# Note that K-lines are local to the server; if you ban a person or a +# Note that Kill blocks are local to the server; if you ban a person or a # whole domain from your server, they can get on IRC via any other server -# that doesn't have them K-lined (yet). +# that doesn't have them Killed (yet). # # With a simple comment, using quotes: Kill { host = "*.au"; reason = "Please use a nearer server"; }; diff --git a/doc/iauth.txt b/doc/iauth.txt deleted file mode 100644 index be39fb0..0000000 --- a/doc/iauth.txt +++ /dev/null @@ -1,205 +0,0 @@ -$Id: iauth.txt,v 1.1 2001-05-01 11:38:34 isomer Exp $ - -Patrick Alken -01/09/2000 - -Ircd Authentication -==== ============== - -1. Introduction - - This document describes the protocol used for the IAuth server. -IAuth performs authorization checks for all clients that connect -to the ircd server. - -2. Protocol - - Ircd and IAuth communicate through a TCP/IP connection. The -Ircd server will always initiate the connection to the IAuth -server. - -2.1 Server - - When an Ircd server first connects to an IAuth server, it will -send IAuth a string of the form: - - Server - - - Ircd server name - - This is used for identification purposes in case more than one -Ircd server is using an IAuth server. - -2.2 Class - -2.2.1 Class Add - - When an Ircd server first connects to an IAuth server, it will -send IAuth it's class list in the form: - - Class Add - - - Class number - - Maximum number of clients in this class - - This is needed for the I-line check, in case the number of -clients allowed to use a certain I-line is limited. - -2.2.2 Class Clear - - Upon a rehash, the Ircd server will send I-line a string of the -form: - - Class Clear [number] - - [number] - optional number - - In case the Ircd server's Y: lines were changed prior to the -rehash, IAuth will clear it's old class list to make room for -the new one Ircd will send after the rehash (via Class Add). - -2.3 DoAuth - - When a client connects to the Ircd server, Ircd will send -a string of the form: - - DoAuth [password] - - - A unique ID used to identify each client - - Client's nickname - - Client's username - - Client's hostname - - Client's IP Address in unsigned int format - [password] - *Optional* Client password - - The DoAuth directive will initiate an authorization check on -the client. The following checks are performed. - -2.3.1 I-line Check - - This check will ensure that the client matches a valid I-line -(as given in iauth.conf). If the client fails this check, he/she -will not be allowed to remain connected to the Ircd server. -The actual reason they failed authorization will be told to them. -(See the BadAuth directive). - See the section on iauth.conf for more information on I-lines. - -2.3.2 Server Ban Check - - K-lines are server-wide bans for individual (or groups of) clients. -If a client matches a K-line, they will be disconnected from the -Ircd server with the reason they are banned. The only exception to -this is if they have an exemption flag in their I-line. See the -iauth.conf section for more details on this. - -2.3.3 Quarantine Check - - Q-lines specify nicknames which are not allowed to be used on -the Ircd server. If a client's nickname matches that of a Q-lined -nickname, they will be informed they have selected a quarantined -nickname and be disconnected from the server. - -2.4 DoneAuth - - If a client passes all of the above checks, they will pass -authorization and be allowed to continue their connection to -the Ircd server. IAuth will send a string back to the Ircd -server of the form: - - DoneAuth - - - Client's unique ID - - Client's username - - Client's hostname (may be different from original - if they are allowed a spoof) - - Client's I-line class - - This will inform the Ircd server that the specified client is -authorized to connect. - -2.5 BadAuth - - If a client fails any of the above checks, IAuth will send a -string to the Ircd server of the form: - - BadAuth : - - - Client's unique ID - - Reason client failed authorization - - The Ircd server will then send an error back to the client -containing and disconnect them. - -3. Configuration file (iauth.conf) - - IAuth reads a configuration file upon startup. The name of the -file is located in setup.h, under #define CONFFILE. The format -of this file is identical to that of ircd.conf, except it supports -less directives. - -3.1 I-lines (Server Access) - - I-lines allow clients access to the Ircd server and are of the -form: - - I::[password]:[flags][user@]:: - - - Hostname to give client if SPOOF_FREEFORM - is defined. - [password] - *Optional* password that clients will - be required to supply to gain access. - [flags] - *Optional* flags (see below) - [user] - *Optional* username (if not given, defaults - to "*") - - Client's hostname - - I-line class (see section Class Add) - - Possible values to go in the [flags] section are: - - = - Spoof their IP Address (requires #define - SPOOF_FREEFORM) - ! - Limit 1 client per IP Address - - - Do not give them a tilde (~) character if they - are not running identd - + - Do not allow them to connect if they are not - running identd - ^ - Client is exempt from K/G lines - > - Client is also exempt from connection limits - -3.2 K-lines (Server Bans) - - K-lines specify clients who are banned from the Ircd server and -are of the form: - - K:@: - - - Client's username - - Client's hostname - - Reason client is banned - -3.3 Q-lines (Quarantined Nicknames) - - Q-lines specify illegal nicknames. A client that attempts to use -a quarantined nickname will be exited from the Ircd server. Q-lines -are of the form: - - Q:::[[username@]hostname]] - - - Quarantined nickname - - Reason nickname is quarantined - [username] - *Optional* exempted username - [hostname] - *Optional* exempted hostname - - Examples: - - Q:dcc*:Dcc bots not allowed - Q:GoodOper:GoodOper may use this nick:goodoper@oper.irc.server.com - -3.4 P-lines (Ports) - - P-lines specify ports on which the IAuth server will listen for -incoming Ircd server connections. They are of the form: - - P: - - - Port number diff --git a/doc/readme.features b/doc/readme.features index 63fa54d..cf0274e 100644 --- a/doc/readme.features +++ b/doc/readme.features @@ -1,7 +1,7 @@ Many of the old compile-time options are now configured through the server configuration file, ircd.conf. This file is intended to document each of these features. Logging, although also configured -through the use of F-lines, is documented in doc/readme.log. NOTE +through the use of Feature entries, is documented in doc/readme.log. NOTE THAT THESE NAMES ARE CASE SENSITIVE! Values are not case sensitive unless stated otherwise in the documentation for that feature. @@ -363,8 +363,8 @@ CONNECTFREQUENCY This is the default frequency that the server attempts to reconnect with its uplink server if it is set to auto connect to it. Note that -this value is overridden by a Class block in ircd.conf if the C-lines -in ircd.conf assign a specific class to the connection (recommended). +this value is overridden by a Class block in ircd.conf if the Connect +entries in ircd.conf assign a specific class to the connection. DEFAULTMAXSENDQLENGTH * Type: integer @@ -372,9 +372,7 @@ DEFAULTMAXSENDQLENGTH This is the default value of the maximum sendQ length of connection classes (see doc/example.conf for details on Class blocks). You will -probably always override this value in your "ircd.conf" with the -Y-lines. The given value used to be an often used value for client -sendQs. +generally override this value in your "ircd.conf" with a Class block. GLINEMAXUSERCOUNT * Type: integer @@ -439,13 +437,12 @@ CONFIG_OPERCMDS * Type: boolean * Default: FALSE -For u2.10.11, several new oper-only features have been added that -involve changes to the server<->server protocol. Until the entire -network is running the new version, these features cannot be enabled. -This configuration option provides a single switch to prevent the use -of these features until the entire network has been upgraded. It is -not required that all servers set this to "TRUE" in order for the -features to be used. +Since u2.10.11, several new oper-only features have been added that +involve changes to the server<->server protocol. This configuration +option provides a single switch to prevent the use of these features +until the entire network has been upgraded. It is not required that +all servers set this to "TRUE" in order for the features to be used, +as long as all servers are running u2.10.11 or above. HIS_MAP * Type: boolean diff --git a/doc/readme.log b/doc/readme.log index c5dda89..1e635ca 100644 --- a/doc/readme.log +++ b/doc/readme.log @@ -2,7 +2,7 @@ Older versions of ircd had no consistent way of logging various actions. Some things, such as G-lines, were written out to log files with names compiled into the server. Others could only be logged through syslog. Some required that their log files exist beforehand. -For u2.10.11, this situation has changed dramatically. +Starting with u2.10.11, this situation has changed dramatically. All logging in the server is now unified through a single logging subsystem. Unfortunately, the server still does not generate all the @@ -137,30 +137,31 @@ Default Syslog Facility The IRC server has a default facility that it uses when sending log messages to syslog. The default facility may be overridden for each individual subsystem, but the default itself can be changed with an -appropriate F-line in the configuration file. The facility normally -defaults to "USER," but may be configured to be any of AUTH, CRON, -DAEMON, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, +appropriate Feature entry in the configuration file. The facility +normally defaults to "USER," but may be configured to be any of AUTH, +CRON, DAEMON, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7, LPR, MAIL, NEWS, USER, or UUCP. Some systems also have the -AUTHPRIV facility. To configure this default, add an F-line to the -configuration file that looks like "F:LOG:"; -should be replaced with the string for the desired default syslog -facility. +AUTHPRIV facility. To configure this default, add a Feature line to +the configuration file that looks like "LOG" = ""; + should be replaced with the string for the desired default +syslog facility. Log Files Each subsystem may be configured to send its log messages to any -single log file with an F-line like "F:LOG::FILE:"; - should be replaced with one of the subsystem names described -above, and should be a file name for the log file. The file -name may be relative to the server's data directory ("DPATH"), or it -may be an absolute path name. Note that if you're using chroot, these -absolute path names will be relative to the server's root directory. +single log file with a Feature entry like "LOG" = "" "FILE" +""; should be replaced with one of the subsystem names +described above, and should be a file name for the log file. +The file name may be relative to the server's data directory +("DPATH"), or it may be an absolute path name. Note that if you're +using chroot, these absolute path names will be relative to the +server's root directory. Logging to Syslog By default, except for the CONFIG subsystem, no logs are sent to -syslog. This can be overridden using an F-line like -"F:LOG::FACILITY:"; , as above, should be +syslog. This can be overridden using an Feature entry like "LOG" = +"" "FACILITY" ""; , as above, should be replaced with one of the subsystem names described above, and must be one of the facility strings mentioned under "Default Syslog Facility." The facility string may also be "NONE," to @@ -180,14 +181,14 @@ notice masks, please see doc/snomask.html.) The available mask names are OLDSNO, SERVKILL, OPERKILL, HACK2, HACK3, UNAUTH, TCPCOMMON, TOOMANY, HACK4, GLINE, NETWORK, IPMISMATCH, THROTTLE, OLDREALOP, CONNEXIT, and DEBUG. The special mask name "NONE" inhibits sending of -server notices for a particular subsystem. The F-line for this -configuration looks like "F:LOG::SNOMASK:"; again, +server notices for a particular subsystem. The Feature entry for this +configuration looks like "LOG" = "" "SNOMASK" ""; again, is one of the subsystems described above, and is one of the mask names. Setting Minimum Logging Level The minimum log level for a particular subsystem may be set with an -F-line like "F:LOG::LEVEL:"; here, is yet -again one of the subsystems described above, and is one of the -level names, also described above. +Feature entry like "LOG" = "" "LEVEL" ""; here, + is yet again one of the subsystems described above, and + is one of the level names, also described above. -- 2.20.1