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.