INSTALL

Magick IRC Services

$Id$
(c) 1997-2003 Preston A. Elder <prez@magick.tm>
(c) 1998-2003 William King <ungod@magick.tm>

Requirements
============

To compile Magick, you will need a GOOD C++ compiler.  Ones that
have been tested and found to work are:
    gcc 2.95 and above
    Borland C++ Builder 4.0 and above
Others may work, but have NOT been tested.

Before you begin compilation of Magick, you must have a fully compiled
version of the Adaptive Communications Environment (ACE), the ZLIB
compression library, and a threads library such as pthreads.

If you are missing any of the above, you may obtain them as follows:
ACE 	http://www.cs.wustl.edu/~schmidt/ACE.html
ZLIB	ftp://ftp.freesoftware.com/pub/infozip/zlib/index.html
PTH	http://www.gnu.org/pth

FreeBSD USERS - FreeBSD has inbuilt its threads library into its
default operating system, and you do not need a separate threads
library, however all versions before 3.4 with the standard libc_r
patch from FreeBSD dated 02-02-2000, or 4.0 will not work, due to
a badly implemented threads library.

You must compile each of the above products before attempting to
build Magick.  Magick will look for them in the configure phase.

Also, if you dont have about 128mb memory (including swap), and 150mb
hard disk space free, I wouldnt bother to compile magick.  Our main
philosophy is to try and get Magick as efficiant at run-time as
possible, to this end, we've had to trade off compile-time resources
and resulting binary size.  What this means in english is, the final
product is very efficient, however making it will take a large
chunk out of your available resources.

Host locking (ie. stopping magick from being run anywhere that
doesnt have the same host and system type compiled into magick)
is impossible with pre-compiled binaries.  If you wish to add
this level of protection in (ie. you want to ensure that even
if someone DOES get your binaries, they cant run them without
going through some special measures to try and do so), then you
will need to re-compile.  Essentially the rule of thumb is
'compile if you can, use pre-compiled binaries if you must'.

ACE Installation
================

Please note:  If you do not want to compile ACE yourself, or you
are having troubles compiling it, pre-compiled binaries of ACE are
available from ftp://ftp.magick.tm/pub/magick.tm/ace.  It is
recommended you get the 'shared' version first, and 'static' only
if the shared does not work.  If your OS is not listed, please
contact the Magick Development Team <devel@magick.tm>.
Above and beyong this help file, we will not help you compile ACE.

I've included this section now because people seem to have troubles
installing the ACE library obtained above.  One special note for
people wanting to install ACE.  Do NOT use the `configure' utility.
This utility is still in its infancy for ACE, and tends not to work.

Instead, you should follow the instructions that are outlined in the
ACE-INSTALL file, which is simply (from the ACE_wrappers directory):

export ACE_ROOT=$PWD
cd include/makeinclude
ls platform*     (find the one for your system)
ln -s platform_your_system.GNU platform_macros.GNU
cd ../../ace
ls config*     (find the one for your system)
ln -s config-your-system.h config.h
make

Linux Note: All linux systems with kernel versions 2.2.0 and beyond
should use the lxpthread linux configuration.
FreeBSD Note: You should use the pthread version of this library
if you hope to use it with Magick.  Please read FreeBSD note above.

Note on the above.  The `export ACE_ROOT=' command may not work on
your shell.  csh and tcsh users will have to use `set ACE_ROOT=',
and on some other weird shells, just `ACE_ROOT='.  Try them until
you get one that doesn't error.  Once you have one that doesn't have
an error, just type `echo $ACE_ROOT' to ensure it gives you your
current directory, if not, keep trying.  I love unix standards :)

Note, If you get problems in the make with errors like:

ACE_wrappers/include/makeinclude/wrapper_macros.GNU,
       line 135: Missing dependency operator

Your version of make is either old or not GNU standard.  ACE requires
a GNU standard make program to compile.  First see if the program
`gmake' exists, and if so try it, if not, or it doesn't work, please
download it by going to http://www.gnu.org/software/make/make.html
and downloading it from one of their mirror sites.  Incase your
wondering `do I need root for this?'  No, you don't.  Just download
it, compile it, and then type:

alias make=/path/to/make-x.y/make

Where /path/to are replaced with the full path before the make
directory (eg. /home/myuser), and the x and y in the make-x.y
directory are substituted for the version of make you have.  Once
you have aliased make, then try and build ACE again.

After ACE has been made, you have two options:

1) As root, you can copy *.so in the ace directory to /usr/local/lib
   and then copy *.h, *.i, *.inl and *.cpp in the ace directory to
   /usr/local/include/ace, which you will have to create.  On linux
   systems you will have to type 'ldconfig' after this.  Don't forget
   to make the libs chmod 755, and the includes chmod 644.

-OR-

2) When you don't have root, use the --with-acelib and --with-aceinc
   options to Magick's configure script to tell it where ACE is.
   Please note however, you will have to type the following line
   before you will be able to execute Magick:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ACE_wrappers/ace

Obviously the /path/to should be replaced with the full path leading
up to the ACE_wrappers directory (eg. /home/myuser).  The same note
above about `export ACE_ROOT=' applies to the above export.

Basic Installation
==================

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, a file
`config.cache' that saves the results of its tests to speed up
reconfiguring, and a file `config.log' containing compiler output
(useful mainly for debugging `configure').

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If at some point `config.cache'
contains results you don't want to keep, you may remove or edit it.

   The file `configure.in' is used to create `configure' by a program
called `autoconf'.  You only need `configure.in' if you want to change
it or regenerate `configure' using a newer version of `autoconf'.

The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.  If you're
     using `csh' on an old version of System V, you might need to type
     `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package.

  4. Type `make install' to install the programs and any data files and
     documentation.

  5. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

Compilers and Options
=====================

   Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  You can give `configure'
initial values for variables by setting them in the environment.  Using
a Bourne-compatible shell, you can do that on the command line like
this:
     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

Or on systems that have the `env' program, you can do it like this:
     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

Compiling For Multiple Architectures
====================================

   You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory.  To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'.  `cd' to the
directory where you want the object files and executables to go and run
the `configure' script.  `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.

   If you have to use a `make' that does not supports the `VPATH'
variable, you have to compile the package for one architecture at a time
in the source code directory.  After you have installed the package for
one architecture, use `make distclean' before reconfiguring for another
architecture.

Installation Names
==================

   By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving `configure' the
option `--prefix=PATH'.

   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
give `configure' the option `--exec-prefix=PATH', the package will use
PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

   In addition, if you use an unusual directory layout you can give
options like `--bindir=PATH' to specify different values for particular
kinds of files.  Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.

   If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

Optional Features
=================

   Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognises.

   For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.

Specifying the System Type
==========================

   There may be some features `configure' can not figure out
automatically, but needs to determine by the type of host the package
will run on.  Usually `configure' can figure that out, but if it prints
a message saying it can not guess the host type, give it the
`--host=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name with three fields:
     CPU-COMPANY-SYSTEM

See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the host type.

   If you are building compiler tools for cross-compiling, you can also
use the `--target=TYPE' option to select the type of system they will
produce code for and the `--build=TYPE' option to select the type of
system on which you are compiling the package.

Sharing Defaults
================

   If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Operation Controls
==================

   `configure' recognises the following options to control how it
operates.

`--cache-file=FILE'
     Use and save the results of the tests in FILE instead of
     `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
     debugging `configure'.

`--help'
     Print a summary of the options to `configure', and exit.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--version'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`--with-acelib=file'
`--with-aceinc=path'
     This specifies where the makefile should look for the ACE library
file, and its includes respectively.  You must specify full pathnames.
Verification on what you have entered is minimal (ie. will only verify
the existence of the library file, and OS.h in the include directory).
This should only be used if Magick does not detect the ACE library.
NOTE: this should point to the PARENT of the `ace' directory.

`--with-zlib=file'
`--with-zinc=path'
     This specifies where the makefile should look for the ZLIB library
file, and its includes respectively.  You must specify full pathnames.
Verification on what you have entered is minimal (ie. will only verify
the existence of the library file, and zlib.h in the include directory).
This should only be used if Magick does not detect the ZLIB library.

`--enable-bsdthreads'
     This is mutually exclusive of --with-threadlib and --with-threadinc,
it specifies to use the -pthreads option with GCC or CC when linking the
magick binary.  This is used for systems where pthreads is ingrained in
the standard C library, specifically, FreeBSD.

`--with-threadlib=file'
`--with-threadinc=path'
     This specifies where the makefile should look for a threads library
file, and its includes respectively.  You must specify full pathnames.
Verification on what you have entered is minimal (ie. will only verify
the existence of the library file, and the include directory exists).
This should only be used if Magick does not detect a threads library.

`--with-locknode=node'
`--with-locktype=type'
`--with-lockrel=rel'
     This will set the host lock values (see --enable-hostlock below)
for the purpose of building a locked binary for another system.  This
is mainly for people who want to run magick on a system that is not
capable of compiling it, but dont want to use an unlocked binary.  The
best way to to do this is after the configuration process, type 'make
ace_uname' and then execute ace_uname, the value on the 2nd line is the
node, the value on the 1st and 5th line are the type and should be
seperated by a `/' character (ie. 1st/5th).  The value of the 3rd line
is the rel.  Alternatively, you can try using the commands `uname -n'
for the 2nd line, `uname -s' for the 1st line, `uname -m' for the 5th
line, and `uname -r' for the 3rd line, but it is recommended you use
ace_uname instead (as the values may not match on some systems!).
NOTE: the release is currently not used in hostlock protection.

`--with-include=path'
`--with-libdir=path'
`--with-lib=lib'
     These will add -I, -L and -l options to the compile/link options.
If you find Magick wont compile on your system due to missing symbols,
or undefined references, it may not have been able to find a header it
needed, or it may not have included a required library.  The include
and libdir should both be directories where to find the include files
or libraries, where lib should be the library name with the lib prefix
and the .so or .a postfix truncated.  eg. libpthread.so becomes pthread.

`--enable-static'
`--disable-static'
     This determines weather the resulting Magick binaries will be
linked statically or dynamically.  Static binaries are larger than
dynamic, but may be taken across differing releases (of the same
operating system) without regard for what specific version of things
such as the C libraries are installed.  Static binaries require that
a static ACE, threads and zlib library exist to link with.  Dynamic
binaries may only be used on systems that have the same library
setup as the one they were compiled on, and because they dont include
all the extra stuff needed to statically link, are much smaller.

`--enable-quick'
`--disable-quick'
     This turns off the call to 'helper/build-ver' which increments
the build number displayed in Magick's version reply.  This is only
useful if you plan to compile alot, and dont want to have to re-
compile the entire program each time you make a change, however it
means you will not have an accurate build number indication.

`--enable-test'
`--disable-test'
     This creates testing binaries of Magick.  Test binaries will not
communicate through a socket, but instead will read all input from
standard input, and send all output to standard output.  With this
mode, you can play back certain test scenarios, to try and catch a
specific bug, or just verify the code still works as it should.

`--enable-crypt'
`--disable-crypt'
     This turns on or off encryption support in Magick.  Some versions
of Magick may not be distributed with encryption, in which case you
will have to download it and enable it to use it.  The encryption of
choice right now is 3BF (3 * blowfish).

`--enable-trace'
`--disable-trace'
     This turns on or off the internal tracing functions of Magick.  This
can cause problems right now with large databases.  It is therefore by
default disabled.  It does however allow debugging of Magick without
the need or use of core file analysis.

`--enable-convert'
`--disable-convert'
     This enables or disables the --convert commandline paramater that
can be used to convert older versions of Magick DB's or other services
databases.  Not needed for normal running of magick.

`--enable-getpass'
`--disable-getpass'
     This enables the ChanServ and NickServ GETPASS commands, as opposed
to the default SETPASS commands.  By doing this, passwords will be stored
as they are in the database.  This is disabled by default, which means
only SETPASS is available, and passwords are stored in a one-way hash
that makes it impossible to retrieve passwords.

`--enable-locks'
`--disable-locks'
     This turns on or off thread locking.  Thread locking is essential
for ensuring only one thread can access a bit of data at once.  On some
bad thread implementations, this will stop segfaults, however it is a
big target asking for data corruption turning this off.

`--enable-hostlock'
`--disable-hostlock'
     This will enable or disable host and system type checking on startup.
When enabled, if the binary is moved to a system where the hostname or
system specs are different from where the binary was compiled, it will
fail to operate, and a re-compile will be necessary.  This is enabled by
default, however if you want to create a portable binary (that can be
used anywhere) disable this option.  This is a security feature to protect
against people copying your services directory (binaries and all) and
stealing the databases.  This is not infallable, however it does help.
Disabling this will also disable automatic binary 'stamping' (ie.
putting random keys for keyfile encryption at compile time).  It is
assumed that you are making a binary ment to be portable and/or
distributed, in which case, the binaries should be stamped by the
end-user (or on each system it is deployed).

`--enable-mpatrol'
`--disable-mpatrol'
     This turns on or off the usage of the memory error checking and
profiling software mpatrol (http://www.cbmamiga.demon.co.uk/mpatrol).
This software is useful in the fact it looks for memory access errors
(eg. accessing unitialised memory, exceeding memory bounds, not freeing
memory, etc).  However it slows the program down dramatically.  Turning
this on causes a new log file (mpatrol.log) to be created.

`--enable-efence'
`--disable-efence'
     This turns on or off the usage of the memory error checking and
profiling software Electric Fence (http://ftp://ftp.perens.com/pub/ElectricFence).
This software is useful in the fact it looks for memory access errors
(eg. accessing unitialised memory, exceeding memory bounds, not freeing
memory, etc).  However it slows the program down dramatically.  Turning
this on causes the program to stop at the first memory problem (so it
is recommended you run this in a debugger).

`--with-keylen=size'
     This is the maximum size of the key file, and the input key that
you may type in.  This defaults to 1024, and you should not need more.

`configure' also accepts some other, not widely useful, options.

Security Tips
=============

     Magick has several facilities to ensure your databases and inter-
magick communications are kept secure and encrypted.  The main methods
of facilitating this are:
     * Databases and inter-magick communication is encrypted with a
       key through 3BF.  This key resides in a key file.
     * The key file itself is encrypted with two keys generated at
       compile time, to ensure the key file is never clear text.
     * EACH compile creates new key file keys, which means you must
       re-generate the key file each time you compile, ensuring it
       does not get stale (and becomes invalid if someone gets it!)
     * You may manually replace the key file keys by using the
       magick_stampkeys utility that comes with magick (you will
       have to regenerate your key file after this).

To ensure the security of your databases and communication, you should
     * Chose a long and complex database key, you must remember this
       somehow, incase you need to generate a new database key, however
       you wont need it often.  Also choose long and varied key file
       keys, they can be up to 1024 bytes long (or longer with the
       --with-keylen parameter to configure)!
     * Use the magick_stampkeys utility on all your binaries at once
       and regenerate your keys every so often, so stop them becoming
       stale.

Windows users will not automatically generate a new keyset with each
compile.  It is recommended you create your own using the
magick_stampkeys utility supplied if you intend to use encryption.
This must be done some time before the database encryption key is
generated.

Syntax for the magick_stampkeys utility is:
     magick_stampkeys <all binaries to be stamped>

You MUST do all executable files at once, so an example is:
     (UNIX) magick_stampkeys magick magick.debug magick_keygen
     (WIN ) magick_stampkeys magick.exe magick_keygen.exe

Keep in mind that to be able to stamp a binary, it must NOT have been
previously stamped, so you will need a 'freshly linked' file.  All
binary distributions contain un-stamped files, all source distributions
can create (and auto-restamp) files with the "make reilnk" command.

REMEMBER:  If you forget your database password, then you had BETTER
decrypt your databases (via. the config file) ASAP, as if you lose
your key, and do not know the password to generate a new one, you
may as well remove the file and start again.