Magick IRC Services $Id$ (c) 1997-2003 Preston A. Elder <prez@magick.tm> (c) 1998-2003 William King <ungod@magick.tm> Magick Services are released under the GNU General Public License, see the "COPYING" file for further details. By downloading this software you are bound by the terms and conditions described therein. CONTENTS ======== Please read the file "FAQ" for a list of frequently asked questions and their answers. Please read the file "AUTHORS" to find out about who wrote Magick, and how to be on the testing teams. Please read the file "INSTALL" for information about how to compile and install Magick on your system. Please read the file "ChangeLog" for a summary list of changes since the previous release of Magick. 1. DEDICATION 2. INTRODUCTION 3. SUPPORT FILES 4. CONFIGURATION 5. GENERAL USAGE 6. FUNCTIONALITY 7. NOTE TO DEVELOPERS 1. DEDICATION ============= Magick is dedicated to the memory of PreZ's loving sister, Stacey Louise Elder (1st Jan, 1975 - 25th Feb, 1998). She has been there for me more than anyone over the years, and I was distraught when she died, may her Lord love her as much as I did, and keep her safe like I could not. Merry Parting, Dear Sister. Magick is also dedicated to the memory of Ungod's brother, Edward Kevin King (28th Aug, 1982 - 21st Nov, 1997), His life was short, but his memory is great, never will those who knew him forget him. 2. INTRODUCTION =============== Magick IRC Services are a program that is designed to interface with an Internet Relay Chat (IRC) network, and offer its users, operators and administrators services such as the ability to register nicknames so they cannot be taken by anyone else, the ability to register channels with pre-defined access lists and kick lists so that channels may not be taken over, the ability to leave offline messages for other users, and many network control mechanisms to stop things like flooding, abusive users, and many other things. Magick services adhere to RFC 1459, and many variants of it. The changes to the base protocol will not be discussed in this document, as there are too many of them, and so many different distinct protocols around nowadays, however Magick has been designed to cope with them all, with a minimum of fuss (as long as they support services of this nature). The Magick home page can be found at: http://www.magick.tm Magick is freely downloadable from: ftp://ftp.magick.tm/pub/magick.tm/Magick-II The Magick public mailing list is general@magick.tm. Yoy may subscribe to this mailing list at: http://lists.sourceforge.net/lists/listinfo/magick-general 3. SUPPORT FILES ================ All files and directories listed are relative to the current 'Services Directory'. The services directory is set with the --dir command-line option. If none is specified, it will default to the current directory. magick.ini - This file is included with your Magick distribution in the docs directory. This file must either be specified on the command-line with the --config option, or in the services directory. This file contains all settings that Magick II will use throughout its execution (these can be changed and reloaded online). magick.mnd - This is the Magick New Datafile (or mound) file. This stores all data that is stored by Magick. This file is not human readable, and is often encrypted and/or compressed. This filename is a setting in the magick.ini file, and may be changed. This file will be created if it does not exist. magick.log - This is the logfile which logs all activity of note that happens inside Magick. The verbosity of this log file can vary depending on the --debug option, or the VERBOSE config option. This file may be zeroed without any detrimental effects, or if it is removed, the OFF LOG and ON LOG online commands (OperServ) will re-establish the filehandle (ie. close and re-open the file respectively). This filename is a setting in the magick.ini file, and may be changed. This file is created if it doesn't exist. magick.pid - This file indicates the process ID of the currently running Magick on UNIX-based systems. This may be used to easily determine if Magick is running, and to kill a running copy. This filename is a setting in the magick.ini file, and may be changed. This file is overwritten on Magick startup and removed on shutdown. magick.motd - This contains the text of the server motd that will be displayed to any user who types /MOTD services.server in their IRC client. This filename is a setting in the magick.ini file, and may be changed. magick.key - This contains the key for your databases, encrypted. This key file should be generated with magick_keygen. This file may not be used by more than one set of services (unless the binaries are copied), as each compile requires regenerating this file. This filename is a setting in the magick.ini file, and may be changed. ircd/*.ini - These files contain the details that define how each IRC protocol works. The IRC protocol (RFC1459) has been expanded by many different IRCD coding teams, and in many different ways, and these files help cope with the differences. lang - This directory is where all language files (*.lng, *.lfo and *.hlp) will be stored. The path name actually used is a setting in the magick.ini file. lang/*.lng - These files contain the responses Magick will send back to users for any command, or output from any procedure. These files are 'tokenised', and are substituted with actual values. The default language file to used is set by the DEF_LANGUAGE parameter in the magick.ini file, however languages may be set per-user. lang/*.lfo - These files contain the log file outputs Magick will use for all messages going to the magick.log file. These files are 'tokenised', and are substituted with actual values. The file that is used is set by the DEF_LANGUAGE parameter in the magick.ini file. lang/*.hlp - These files contain the help text that Magick uses to respond to all HELP commands. The default help file used is set by the DEF_LANGUAGE parameter in the magick.ini file, however languages may be set per-user. files/pic - This directory is where all user's pictures are stored. The files themselves are stored as hexadecimal numbers, with no extension -- the map to real filenames is stored in the database. The path name actually used is a setting in the magick.ini file. files/memo - This directory is where all attachments are stored. The files themselves are stored as hexadecimal numbers, with no extension -- the map to real filenames is stored in the database. The path name actually used is a setting in the magick.ini file. files/public - This directory is where all files in the public filesystem (uploaded by SOPS) are stored. The files themselves are stored as hexadecimal numbers, with no extension -- the map to real filenames is stored in the database. The path name actually used is a setting in the magick.ini file. files/temp - This directory is where all files involved in DCC transfers (sending or receiving) are stored. These files are considered volatile, and if Magick is not running, can safely be removed. The files themselves are stored as hexadecimal numbers, with no extension. The path name actually used is a setting in the magick.ini file. 4. CONFIGURATION ================ Magick may be configured in one of three ways. First, you may manually edit the magick.ini file. This file is what is read in by magick to tell it how to operate. A sample INI file can be found in the docs directory. This file contains full text on what each configuration item does, and what the valid settings for it are. The second method requires you to have the Java Runtime Environment (version 1.4.0 or greater) installed on your machine. Inside the gui directory, a jar file called mct.jar is included. This will be installed in the same location as the magick binaries upon make install. This is the Magick Configuration Tool. To run it, type: java -jar mct.jar This will load up a java applet, which allows you to create a magick.ini file from within. Simply go through each of the tabs and configure the options within. The advantage of this tool over hand-editing the INI file is that the Magick Configuration Tool does syntax validation for you. However, any magick.ini file generated with this tool will not have comments in it. The third method of configuring magick is simply to go to the URL http://www.magick.tm/config. If your browser does not have Java installed, it will prompt you to install it. This web page will bring up the Magick Configuration Tool in your browser. The first thing it will do is prompt to verify the signature on the applet. If you do not do this, you will not be able to save a configuration file directly, but will instead have to generate it in the applet (in the Current File tab), and cut and paste it to a file yourself. Otherwise, the applet performs exactly like it would if run locally. 5. GENERAL USAGE ================ Magick once started, becomes a background process. It accepts a number of command-line options that override the settings of their equivalents on load. NOTE: If the config file is loaded again at runtime, the settings in the config file will be used. --help (-h) Help output (summary of the below). --version (-v) Display the Magick version string. --dir X Set the initial services directory. --config X Set the name (and/or path) of the config file. --nofork Do not become a daemon/service process (dont fork()). --service X [Y Z] Manipulate Magick's NT Service settings, where X is one of insert, start, stop, remove, or change. If X is change, you must specify what property to change and what to change it to (Y and Z). If Y = startup, Z = auto, manual or disabled. If Y = depend, Z = another service (magick will not startup if this service is not running. Setting this to none removes any dependancy. If Y = user, Z = the username Magick will run as, and the password for that user (separated by a colon (:)). eg. somebody:mypassword. Setting this to default means system user. This option is only available on WinNT-based systems. --convert X Convert another version of services databases to Magick II format, where X is the type of database to convert. After the name of the services to convert is the version that the conversion utilities were taken from (you can usually assume previous versions will also work). magick (1.4), ircservices (5.0.9), sirv (2.9.0), hybserv (1.9.0), auspice (2.8), ptlink (2.22.3), epona (1.4.14), wrecked (1.2.0), trircd (4.26), cygnus (0.1.1), bolivia (1.2.0). MUST BE COMPILED INTO BINARY TO BE AVAILABLE. --trace X:Y Set the trace level on startup, equivalent of using the OperServ TRACE SET command while running, where X is the trace type (or ALL), and Y is the trace level in hex. MUST BE COMPILED INTO BINARY TO BE AVAILABLE. All other command line options just override the configuration file settings. Below is a list of the overrides available, and the settings they override in the configuration file. Please see the configuration file's comments for more information on each option, and what it does. PARAMETER SHORT GROUP OPTION --------- ----- ----- ------ --name X -N STARTUP SERVER_NAME --desc X -D STARTUP SERVER_DESC --user X -U STARTUP SERVICES_USER --host X -H STARTUP SERVICES_HOST --ownuser -o STARTUP OWNUSER=true --level X -l STARTUP LEVEL --maxlevel X -G STARTUP MAX_LEVEL --lagtime X -g STARTUP LAGTIME --umask X -u FILES UMASK --verbose -V FILES VERBOSE=true --log X -L FILES LOGFILE --logchan X -C FILES LOGCHAN --dbase X -d FILES DATABASE --protocol X -P FILES PROTOCOL --langdir X -S FILES LANGDIR --encrypt -E FILES ENCRYPTION=true --decrypt -e FILES ENCRYPTION=false --keyfile X -K FILES KEYFILE --compress X -c FILES COMPRESSION --relink X -r CONFIG SERVER_RELINK --norelink CONFIG SERVER_RELINK=0 --save X -w CONFIG SAVETIME --cycle X -t CONFIG CYCLETIME --check X -T CONFIG CHECKTIME --ping X -p CONFIG PING_FREQUENCY --minthreads X -q CONFIG MIN_THREADS --axthreads X -Q CONFIG MAX_THREADS --lwm X -m CONFIG LOW_WATER_MARK --hwm X -M CONFIG HIGH_WATER_MARK --append -a NICKSERV APPEND_RENAME=true --rename -A NICKSERV APPEND_RENAME=false --ident X -R NICKSERV IDENT --language X -s NICKSERV DEF_LANGUAGE --nodcc -x NICKSERV PICEXT= (nothing) MEMOSERV FILES=0 --inflight X -f MEMOSERV INFLIGHT --logignore -i OPERSERV LOG_IGNORE=true --ignore X -I OPERSERV IGNORE_METHOD Example: ./magick --config /etc/magick.ini After Magick is running, it should be totally driven through the on-line clients (NickServ, ChanServ, OperServ, etc). However, in certain cases, events happen and these interfaces are either not available, not responding, too slow, or don't recognise you. For this eventuality, all UNIX SIGNALS have been trapped, and some perform extra functions than 'originally' intended. SIGNAL NUMBER EQUIVALENT DESCRIPTION ------ ------ ---------- ----------- SIGHUP 1 OS RELOAD Re-loads the config file. SIGINT 2 OS SIGNON Attempts to sign on all clients. SIGPIPE 13 IGNORE Flushes trace output immediately. SIGTERM 15 OS UPDATE Saves the databases. Some have queried me on why SIGTERM saves the databases. During shutdown of many systems, the shutdown scripts will send a SIGTERM to all running processes, wait a while, then send a SIGKILL (9). This gives us a chance to save our databases before we're killed. This also means that you must use kill -KILL (kill -9) to kill Magick once it has been started. To use encryption, you must generate a key file with the program magick_keygen. This program accepts a maximum of one argument, being the output key filename. If no argument is supplied, it will ask you to enter the filename interactively. On unix terminals that support it, the text entered at the key prompts will be hidden, however to not bank on this, and always ensure no one can look over your shoulder or sniff your network traffic to find out what the clear-text password is. Example: ./magick_keygen Magick IRC Services - http://www.magick.tm (c) 1997-2003 Preston A. Elder <prez@magick.tm> (c) 1998-2003 William King <ungod@magick.tm> Enter filename to output to [magick.key]: NOTE: A key must be at least 18 bytes long and may be up to 288 bytes long. Enter database key 1: Re-Enter database key 1: Enter database key 2: Re-Enter database key 2: Created 160 byte keyfile. 6. FUNCTIONALITY ================ Magick has 6 main services, and offers the ability to script either added functionality to these existing services, or create totally new services through its scripting language. This section gives an overview of the main functionality and purpose of the hard-coded services. Please note, the actual nicknames of each of the below services may be different on each network. NickServ is a services that allows users to register their IRC nicknames so that no one else may take them. Users may then set various options on their nickname record, such as privacy mode, kill protection, etc that affect the way their nickname is treated, and how services respond to them. They may also set purely informational fields in their nickname record that is displayed on an INFO request. NickName registration is required to execute many other commands in services, be added to a channel access list, or receive memos from other users. ChanServ is a service that allows users to register a channel on the IRC network, so that they may specify who has access to them, and who shall be automatically kicked from them. This not only prevents such things as channel takeovers, but establishes a definite 'seniority' system in the channel. ChanServ also allows users to set various options on their channel records, from the purely informational that is displayed in an INFO request, to options that change the behaviour of services, and how users are treated in a channel. This service also offers such features as on-join greetings, user-based greetings, etc. MemoServ is a service that allows users to send memos to other users, or post news articles to channels. This service also allows such features as forwarding, or replying to memos, and even attaching files via. DCC to memos (to other users only). This service also integrates with NickServ's ignore list, and ChanServ's access list to vary the ability to send, or read memos or news articles. CommServ is a service that maintains 'committees' or groups of users. These groups can be simply a list of users who have a common interest, or can alter a user's access to certain features of services. You may also send memos to all members of a committee or set logon messages for committees that all members will see on signon. Services has 6 'default' committees: SADMIN - Services Administrators - Members of this committee are hard-coded into the Magick configuration file. SOP - Services Operators - Members of this committee are added by members of the SADMIN committee. ADMIN - Server Administrators - Members of this committee are added by members of the SADMIN committee. OPER - IRC Operators - Members of this committee are added by members of the ADMIN committee. REGD - All Registered Users - This committee may not be modified, and its members are dynamic. ALL - All Users - This committee may not be modified, and its members are dynamic. OperServ is a service that allows IRC Operators to keep control on the network. This service offers functions like an Automatic Kill list, Clone Protection (and overriding), Services Ignore, IRC Operator Denying, as well as the ability to JUPE (fake-link) a server, change a user or channels modes, and many more functions. ServMsg is mainly an informational service, users may get help, statistics and information about services, and the network they are connected to from this service. This service also offers the ability for Server Administrators to send a global message that will be sent to all users on the network, and services operators to offer files to users through the public file system. 7. NOTE TO DEVELOPERS ===================== If you feel the insane urge to modify Magick's code in any way, we have made it slightly easier to distribute your code to a userbase. In the helper directory, you will find a blank-patch file, which you just plug in the name of the patch, your name and email address, a description of the patch, and the output from DIFF between the base magick distribution, and your modified version, and that it. Send it out to users, they run it, and it automatically updates the version info, etc -- all maintenance is done -- they just run your patch :) We DO ask however that you not rename Magick to another name because you think its cool, or remove any of our copyrights throughout the source, documentation, and other places. We do deserve some credit, just as you do for your addition, and you are free to add credit for your work where it has been done.