/************************************************************************ * IRC - Internet Relay Chat, doc/INSTALL * Copyright (C) 1990,1991,1992, Jeff Trim, Mike Bolotski, * Jarkko Oikarinen and Darren Reed. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 1, or (at your option) * any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ Installing IRC - The Internet Relay Chat Program Overview of this document: 1) Installing IRC 2) The config.h file 3) Editing the Makefile, and compiling 4) The ircd.conf file 5) Mailing list 1) So that ircd/irc will compile and work correctly with your version of Unix, it is necessary that you run "make" first. This will run configure which will probe your system for any peculiarities it has and setup the Makefile and a file of default #define's ($arch/setup.h). To change the default directory into which ircd will install using "make install", invoke "make" using the "CONFIGARGS=--prefix=/dir" command line option. 2) Edit the "config.h" file and make changes to the various #DEFINE's: a) Define what type of UNIX your machine uses. Pick the machine type which best describes your machine and change the #undef to #define (if needed). Some flavours of Unix require no #define and in such cases all others should be #undef'd. b) DEBUGMODE Define DEBUGMODE if you want to see the ircd debugging information as the daemon is running. Normally this function will be undefined as ircd produces a considerable amount of output. DEBUGMODE must be defined for either of -t or -x command line options to work. Defining this induces a large overhead for the server as it does a large amount of self diagnostics whilst running. c) SPATH, CPATH, MPATH, LPATH, PPATH, TPATH Define SPATH to be the directory path to ircd. This is usually /usr/local/bin/ircd, unless you don't have installation permission there. Define CPATH to be the directory path to the "ircd.conf" file. This path is usually /usr/local/lib/ircd.conf. The format of this file will be discussed later. The LPATH #define should be set to "/dev/null" unless you plan to debug the program. Note that the logfile grows very quickly. Define MPATH to be the path to the 'motd' (message of the day) file for the server. Keep in mind this is displayed whenever anyone signs on to your server. The PPATH is optional, but if defined, should point to a file which either doesn't exist (but is creatable) or a previously used PPATH file. It is used for storing the server's PID so a ps(1) isn't necessary. Define TPATH to be the directory path to the "ircd.tune" file. This path is usually /usr/local/lib/ircd.tune. This file is used by the server to optimize memory use. d) CHROOTDIR To use the CHROOTDIR feature, make sure it is #define'd and that the server is being run as root. The server will chroot to the directory name provded by IRCDDIR (in Makefile). e) ENABLE_SUMMON, ENABLE_USERS For security conscious server admins, they may wish to leave ENABLE_USERS undefined, disabling the USERS command which can be used to glean information the same as finger can. ENABLE_SUMMON toggles whether the server will attempt to summon local users to irc by writing a message similar to that from talk(1) to a user's tty. f) SHOW_INVISIBLE_LUSERS, NO_DEFAULT_INVISIBLE On large IRC networks, the number of invisible users is likely to be large and reporting that number cause no pain. To aid and effect this, SHOW_INVISIBLE_LUSERS is provided to cause the LUSERS command to report the number of invisible users to all people and not just operators. The NO_DEFAULT_INVISIBLE define is used to toggle whether clients are automatically made invisible when they register. g) OPER_KILL, OPER_REHASH, OPER_RESTART, LOCAL_KILL_ONLY The three operator only commands, KILL, REHASH and RESTART, may all be disabled to ensure that an operator who does not have the correct privilidges does not have the power to cause untoward things to occur. To further curb the actions of guest operators, LOCAL_KILL_ONLY can be defined to only allow locally connected clients to be KILLed. h) ZIP_LINKS, ZIP_LEVEL As of the 2.9.3 version of the server, server-server connections may be compressed using the zlib. In order to compile the server with this feature, you MUST have the zlib package (version 1.0 or higher) already compiled and define ZIP_LINKS in the config.h file. Compression use for server-server connections is separately configured in the ircd.conf file for each server-server link. ZIP_LEVEL allows you to control the compression level that will be used. Values above 5 will noticeably increase the CPU used by the server. The zlib package may be found at http://quest.jpl.nasa.gov/zlib/ The data format used by the zlib library is described by RFCs (Request for Comments) 1950 to 1952 in the files ftp://ds.internic.net/rfc/rfc1950.txt (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format). These documents are also available in other formats from ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html i) SLOW_ACCEPT This option is defined by default and is needed on some OSes. It creates an artificial delay in processing incoming connections. On a given port, no more than 1 connection per 2 seconds will be processed. Undefining this will let the server process connections as fast as it can which can cause problems on some OSes (such as SunOS) and be abused (fast massive join of clonebots..), for these reasons, if you decide to undefine SLOW_ACCEPT you MUST define CLONE_CHECK. j) CLONE_CHECK This option acts as a wrapper, by checking incoming connections early before starting ident query. By default, the server will not accept more than 2 connections from the same host within 10 seconds. k) The rest of the user changable #define's should be pretty much self explanatory in the config.h file. It is *NOT* recommended that any of the file undef the line with "STOP STOP" in it be changed. 3) Editting Makefile and compilation. Once configure has been run, it is safe to edit the Makefile. You will most likely need to uncomment the correct IRCDLIBS, IRCLIBS and IRCDDIR lines. To now build and install the server, type "make && make install". If you have trouble compiling ircd, copy Makefile.in to Makefile and edit Makefile as appropriate. 4) The ircd.conf file. After installing the ircd and irc programs, edit the ircd.conf file as per the instructions in this section and install it in the location you specified in the config.h file. There is a sample conf file called example.conf in the /doc directory. Appendix A describes the differences between IP addresses and host names. If you are unfamiliar with this, you should probably scan through it before proceeding. The ircd.conf file contains various records that specify configuration options. The record types are as follows: 1. Server connections (C,c,N) 2. Machine information (M) 3. Client connections (I,i) 4. Default local server (U) 5. Operator priviliges (O) 6. Administrative info (A) 7. Excluded accounts (K) 8. Excluded machines (Q) 9. Connection Classes (Y) 10. Leaf connections (L) 11. Service connections (S) 12. Port connections (P) 13. Hub connections (H) 14. Version limitations (V) 1. SERVER CONNECTIONS: How to connect to other servers How other servers can connect to you WARNING: The hostnames used as examples are really only examples and not meant to be used (simply because they don't work) in real life. Now you must decide WHICH hosts you want to connect to and WHAT ORDER you want to connect to them in. For my example let us assume I am on the machine "rieska.oulu.fi" and I want to connect to irc daemons on 3 other machines: "garfield.mit.edu" - Tertiary Connection "irc.nada.kth.se" - Secondary Connection "nic.funet.fi" - Primary Connection And I prefer to connect to them in that order, meaning I first want to try connecting to "nic.funet.fi", then to "irc.nada.kth.edu", and finally to "garfield.mit.edu". So if "nic.funet.fi" is down or unreachable, the program will try to connect to "irc.nada.kth.se". If irc.nada.kth.se is down it will try to connect to garfield and so forth. PLEASE limit the number of hosts you will attempt to connect to down to 3. This is because of two main reasons: a) to save your server from causing extra load and delays to users b) to save internet from extra network traffic (remember the old rwho program with traffic problems when the number of machines increased). The format for the CONNECT entry in the "ircd.conf" is: C::::: Field: 1 2 3 4 5 6 for example: C:nic.funet.fi:passwd:nic.funet.fi:6667:1 - or - C:128.214.6.100:passwd:nic.funet.fi:6667:1 - or - C:root@nic.funet.fi:passwd:nic.funet.fi:6667:1 Explanation: Each field is separated with a ":" charcter: Field 1: Field 1 tells the IRC program which option is being configured. "C" corresponds to a server Connect option. Field 2: Specifies the host name or IP address of the machine to connect to. If "user@" prefixes the actual hostname or IP address the server will require that the remote username returned by the ident server be the same as the one given before the "@". Field 3: The password of the other host. A password must always be present for the line to be recognized. Field 4: The full hostname of the target machine. This is the name that the TARGET server will identify itself with when you connect to it. If you were connecting to nic.funet.fi you would receive "nic.funet.fi" and that is what you should place in this field. Field 5: The INTERNET Port that you want to connect to on the TARGET machine. Most of the time this will be set to "6667". If this field is left blank, then no connections will be attempted to the TARGET host, and your host will accept connections FROM the TARGET host instead. The port field can contain 2 ports, separated by a . In this case, the first port is used when auto-connecting, the second port is used for the UDP pings to the targer server. Field 6: The class field should refer to an existing class and determines the maximum number of simultaneous uses of the C-line allowable through the max. links field in the Y-line. NEW!!! As of the 2.9.3 version of the server, server connections can be compressed with the zlib library. To define a compressed connection, you must have compiled the server with ZIP_LINKS defined (cf 2.h), and use a _lowercase_ C line. Some examples: C:nic.funet.fi::nic.funet.fi:6667:1 This reads: Connect to host "nic.funet.fi", with no password and expect this server to identify itself to you as "nic.funet.fi". Your machine will connect to this host to PORT 6667. C:18.72.0.252:Jeff:garfield.mit.edu:6667:1 This reads: Connect to a host at address "18.72.0.252", using a password of "Jeff". The TARGET server should identify itself as "garfield.mit.edu". You will connect to Internet Port 6667 on this host. C:irc.nada.kth.se::irc.nada.kth.se:1 This reads: do not attempt to connect to "irc.nada.kth.se", but if "irc.nada.kth.se" requests a connection, allow it to connect. Now back to our original problem, we wanted OUR server CONNECT to 3 hosts, "nic.funet.fi", "irc.nada.kth.se" and "garfield.mit.edu" in that order. So as we enter these entries into the file they must be done in REVERSE order of how we could want to connect to them. Here's how it would look if we connected "nic.funet.fi" first: C:garfield.mit.edu::garfield.mit.edu:6667:1 C:irc.nada.kth.se::irc.nada.kth.se:6667:1 C:nic.funet.fi::nic.funet.fi:6667:1 Ircd will attempt to connect to nic.funet.fi first, then to irc.nada and finally to garfield. Reciprocal entries: Each "C" entry requires a corresponding 'N' entry that specifies connection priviliges to other hosts. The 'N' entry contains the password, if any, that you require other hosts to have before they can connect to you. These entries are of the same format as the "C" entries. The format for the NOCONNECT entry in the "ircd.conf" is: N::::: Field: 1 2 3 4 5 6 Let us assume that "garfield.mit.edu" connects to your server and you want to place password authorization authorization on garfield. The "N" entry would be: N:garfield.mit.edu:golden:garfield.mit.edu:: This line says: expect a connection from host "garfield.mit.edu", and expect a login password of "golden" and expect the host to identify itself as "garfield.mit.edu". N:18.72.0.252::garfield.mit.edu:: This line says: expect a Connection from host "18.72.0.252", and don't expect login password. The connecting host should identify itself as "garfield.mit.edu". Explanation: Each field is separated with a ":" charcter: Field 1: "N" corresponds to a server Noconnect option. Field 2: Specifies the host name or IP address of the machine to connect to. If "user@" prefixes the actual hostname or IP address the server will require that the remote username returned by the ident server be the same as the one given before the "@". Field 3: The password of the other host. A password must always be present for the line to be recognized. If CRYPT_LINK_PASSWORD is defined in config.h, this password must be crypted. Field 4: The full hostname of the target machine. This is the name that the TARGET server will identify itself with when you connect to it. If you were connecting to nic.funet.fi you would receive "nic.funet.fi" and that is what you should place in this field. Field 5: Domain masking, see below. Field 6: The class field should refer to an existing class. Wildcards domains: To reduce the great amount of servers in IRCnet wildcard DOMAINS were introduced in 2.6. To explain the usage of wildcard domains we take an example of such: *.de - a domain name matching all machines in Germany. Wildcard domains are useful in that ALL SERVERS in Germany (or any other domain area) can be shown as one to the rest of the world. Imagine 100 servers in Germany, it would be incredible waste of netwotk bandwidth to broadcast all of them to all servers around the world. So wildcard domains are a great help, but how to use them ? They can be defined in the N-line for a given connection, in place of port number you write a magic number called wildcard count. Wildcard count tells you HOW MANY PARTS of your server's name should be replaced by a wildcard. For example, your server's name is "tolsun.oulu.fi" and you want to represent it as "*.oulu.fi" to "nic.funet.fi". In this case the wildcard count is 1, because only one word (tolsun) is replaced by a wildcard. If the wildcard count would be 2, then the wildcard domain would be "*.fi". Note that with wildcard name "*.fi" you could NOT connect to "nic.funet.fi", because that would result in a server name COLLISION (*.fi matches nic.funet.fi). I advice you to not to use wildcard servers before you know for sure how they are used, they are mostly beneficial for backbones of countries and other large areas with common domain. 2. MACHINE INFORMATION Introduction. IRC needs to know a few things about your UNIX site, and the "M" command specifies this information for IRC. The fomat of this command is: M:::: Field: 1 2 3 4 5 Explanation: Field 1: "M" specifies a Machine description line Field 2: The name of YOUR server adding any Internet DOMAINNAME that might also be present. If this hostname can be resolved, the IP# found will be used to for outgoing connections. Otherwise the default interface address of the host is used. The server name may not be FQDN of another host. (This means all outgoing connections will be done from the same IP#, even if your host has several IP#). Field 3: If the machine on which you run the server has several IP addresses, you can define which IP# to use for outgoing connections. This overrides field 2. See Also the "Port Connections" section. Field 4: Geographic Location is used to say WHERE YOUR SERVER is, and gives people in other parts of the world a good idea of where you are! If your server is in the USA, it is usually best to say: , USA. Like for Denver I say: "Denver Colorado, USA". Finnish sites (like tolsun.oulu.fi generally say something like "Oulu, Finland". Field 5: Defines the port on which your server will listen for udp pings from other servers. This should be the port were other servers are set to autoconnect. (Also see the port field description in connect lines). Example: M:tolsun.oulu.fi::Oulu, Finland:6667: This line reads: My Host's name is "tolsun.oulu.fi" and my site is located in "Oulu, Finland". M:orion.cair.du.edu::Denver Colorado, USA:6667: This line reads: My Hosts name is "orion.cair.du.edu" and my site is located in "Denver Colorado, USA". 3. CLIENT CONNECTIONS - How to let clients connect to your IRCD. Introduction. A client is a program that connects to the ircd daemon (ircd). There are clients written in C, GNU Emacs Lisp and many other languages. The "irc" program is the C client. Each person that talks via IRC is running their own client. The ircd.conf files contains entries that specify which clients are allowed to connect to your irc daemon. Obviously you want to allow your own machine's clients to connect. You may want to allow clients from other sites to connect. These remote clients will use your server as a connection point. All messages sent by these clients will pass through your machine. The format of this entry in the conf file is: I::::: Field:1 2 3 4 5 6 i::::: For example, if you were installing IRC on tolsun.oulu.fi and you wanted to allow examples sake let us assume you were making this file for tolsun and you wanted to let your own clients to connect to your server, you would add this entry to the file: I:x::tolsun.oulu.fi::1 If you wanted to let remote clients connect, you could add the following lines: I:x::*.du.edu::1 Allow any clients from machines whose names end in "du.edu" to connect with no password. I:128.214.6.100::nic.funet.fi::1 Allow clients from a machine with that IP number to connect. Numeric match is enough, name is not required anymore. I:x:secret:*.tut.fi::1 Allow clients from machines matching *.tut.fi to connect with the password 'secret'. I:*::*::1 Allow anyone from anywhere to connect your server. This is the easiest way, but it also allows people to for example dump files to your server, or connect 1000 (or how many open sockets per process your OS allows) clients to your machine and take your network ports. Of course the same things can be done by simply telnetting to your machine's SMTP port (for example). I:x::*.fi:6667:1 Allow clients from machines matching *.fi to connect on the port 6667. I:*@*::*@*::1 Allow clients from anywhere to connect your server. If the client machine does not reply to your server ident query, the client's username will be prefixed by ~ NEW!!! As of the 2.7.2d version of the server, the server is able to accept connections on multiple ports. I-lines are required for each P-line to allow connections to be accepted. For unix sockets, this means either adding I:/path/port::/path/port or some variation (wildcards are recognised here). For internet ports, there must be an I-line which allows the host access as normal, but the port field of the I-line must match that of the port of the socket accepting the connectiion. A port number of 0 is a wildcard (matches all ports). NEW!!! As of the 2.9.1 version of the server, i lines are introduced. They work the same way as I lines, but the clients matching an i line will have a restricted connection. (no nick/mode change, no kick) Such users will have their username prefixed by +, = or - depending on the ident reply. 4. DEFAULT HOSTS (for local clients) *obsoleted* Introduction. This defines the default connection for the irc client. If you are running an ircd server on the same machine, you will want to define this command to connect to your own host. If your site is not running a server then this command should contain the TARGET host's connection information and password (if any). The format for this command is: U:::: Field: 1 2 3 4 5 For example: U:tolsun.oulu.fi::tolsun.oulu.fi:6667 U:128.214.5.6::tolsun.oulu.fi:6667 U:tolsun.oulu.fi::tolsun.oulu.fi If the port number is omitted, irc will default to using 6667. 5. OPERATOR Privileges: How to become the IRC administrator on your site Introduction. To become an IRC Administrator, IRC must know who is authorized to become an operator and what their "Nickname" and "Password" is. To add this information, EDIT your "ircd.conf" file and add the following command line to it: O::::: Field: 1 2 3 4 5 6 Explanation: Field 1: Speficies Operator record. If you use capital letter ('O') in it, it specifies a global operator. Small letter ('o') specifies a local operator. Local operator has basically the same rights except global operator with some restrictions. Field 2: Tells IRC which host you have the privileges FROM. This means that you should be logged into this host when you ask for the priviliges. If you specify "tolsun.oulu.fi" then IRC will expect your CLIENT to be connected at "tolsun.oulu.fi" - when you ask for OPERATOR privileges from "tolsun.oulu.fi". You cannot be logged in at any other host and be able to use your OPERATOR privileges at tolsun, only when you are connected at TOLSUN will this work - this is a safeguard against unauthorized sites. Field 3: If your AUTHORIZATION Password - this is the password that let's IRC know you are who you say you are! Never tell anyone your password and always keep the "ircd.conf" file protected from all of the other users. Field 4: The Nickname you usually go by - but you can make this what you want. It is better to make this a NICKNAME that no one else knows, but anything will do. I usually use my own loginname. Field 5: Unused. Field 6: The class field should refer to an existing class (preferably having a lower number than that for the relevant I-line) and determines the maximum number of simultaneous uses of the O-line allowable through the max. links field in the Y-line. Example: O:orion.cair.du.edu:pyunxc:Jeff::1 There is an OPERATOR at "orion.cair.du.edu" that can get Operator priviliges if he specifies a password of "pyunxc" and uses a NICKNAME of "Jeff". 6. ADMINISTRATIVE INFORMATION Introduction. The "A" command is used for administrative information about a site. The e-mail address of the person running the server should be included here in case problems arise. A::::: Field: 1 2 3 4 Explanation: Field 1: "A" specifies an Admin record. Field 2: Use this field to say tell your FULL NAME and where in the world your machine is. Be sure to add your City, State/Province and Country. Field 3: Use this field to specify your Electronic Mailing Address preferably your Internet Mailing Address. If you have a UUCP or ARAPnet address - please add that as well. Be sure to add any extra DOMAIN information that is needed, for example "mail jtrim@orion" probably won't work as a mail address to me if you happen to be in Alaska. But "mail jtrim@orion.cair.du.edu" would work because you know that "orion" is part of the DOMAIN "cair.du.edu". So be sure to add your DOMAINNAMES to your mailing addresses. Field 4: Is really an OTHER field - you can add what you want here, Examples (the line is just one line in the confuration file, here it is cut into two lines to make it clearer to read): A:Jeff Trim - Denver Colorado, USA:INET jtrim@orion.cair.du.edu UUCP {hao, isis}!udenva!jtrim:Terve! Heippa! Have you said hello in Finnish today?;):: Would look like this when printed out with the /admin command: Jeff Trim - Denver Colorado, USA INET jtrim@orion.cair.du.edu UUCP {hao,isis}!udenva!jtrim Terve! Hei! Heippa! Have you said hello in Finnish today? ;) Note that the A record cannot be split across multiple lines; it will typically be longer than 80 characters and will therefore wrap around the screen. 7. REMOVING A USER FROM IRC Remove an errant user from IRC on your site. Introduction. Obviously it is hoped that you wouldn't have to use this command. Unfortunately sometimes a user can become unmanageable and this is your only recourse - the KILL USER command. THIS COMMAND ONLY AFFECTS YOUR SERVER - If this user can connect to another SERVER somewhere else in the IRC-Network then you would have to talk to the administrator on that site to disable his access from that IRCD Server as well. The format of this command is: K::