INSTALL

   1               X3 Installation Instructions
   2
   3 Introduction:
   4 ----------
   5 If you encounter any problems compiling/running X3, please make sure
   6 you have followed the directions in this file correctly and that all
   7 of the requirements listed below are met.
   8
   9 If the problem persists, report it to one (or all) of the coders
  10 listed in the AUTHORS file. Please try to include ALL relevant
  11 information about the error/bug, including anything out of the
  12 ordinary reported from make and the appropriate entries from the log
  13 files.
  14
  15 Requirements:
  16 ----------
  17 This release of X3 (1.8) only supports the Undernet P10
  18 protocol and nefarious extensions. It is tested with Nefarious IRCu
  19 1.3. It does not support bahamut, hybrid, Unreal, or any other ircd
  20 not listed. Should you find other compatible ircds, please let us know.
  21 Most of the testing has been done on Nefarious IRCu 1.3.0 (Based on ircu2.10.11.x).
  22
  23 X3 is known to compile on the following systems as long as you
  24 are using GNU make (make on Linux, gmake on many other systems):
  25
  26   * Linux (libc5 or glibc2); glibc2.1 recommended+    (SPARC, ALPHA, x86, PPC)
  27   * FreeBSD 4.x; tested on 4.2-RELEASE and 4.2-STABLE (SPARC, x86)
  28   * FreeBSD 3.x; tested on 3.3-RELEASE and 3.4-STABLE (SPARC, x86)
  29   * FreeBSD 2.x; tested on 2.2.8-RELEASE              (SPARC, x86)
  30   * NetBSD 1.6+;                                      (ALPHA, MIPS, x86)
  31   * SunOS 5.x; tested on 5.8                          (SPARC, x86)
  32   * OpenBSD 2.x; tested on 2.8                        (x86)
  33   * BSDi 4.x; tested on 4.0.1                         (x86)
  34   * CYGWIN 1.1.x and 1.3.x; tested on 1.1.8           (x86)
  35
  36 X3 should compile on other system types also.  If you have success
  37 on other platforms/archs or problems on any platforms/archs, please
  38 contact the authors to let us know.
  39
  40 gcc 2.96 tends to emit spurious warnings; before reporting any
  41 compiler warnings from it, make sure you are using the most recent
  42 version of it or try using an official release of gcc.
  43
  44 You may also have trouble unless your compiler's C preprocessor
  45 supports ISO C99 varadic macros.  gcc is the compiler we use for
  46 almost all our testing, and we recommend it for use with X3.
  47
  48 Quick Install:
  49 ==============
  50 $ ./configure --prefix=~/x3run
  51     # Will install to x3run directory in your home directory
  52 $ make
  53 $ cp x3.conf.example x3.conf
  54 $ nano -w x3.conf
  55     # use -w (no wrapping) option with nano, or use your favorite editor
  56 $ ./x3
  57     # launches x3.
  58     # Note: x3 runs in the background as a service by default. Give it arguments
  59     # -f -d  to have it run in the foreground and print debug information.
  60
  61 Detailed Install:
  62 =================
  63 It is generally a bad idea to run or install x3 as root. Choose an account x3
  64 will run under, and configure it to install and run from somewhere that user
  65 has permissions.
  66
  67 Compiling:
  68 ----------
  69   1) cd to the main directory of the X3 source tree.
  70
  71      $ cd evilnet-x3serv
  72
  73   2) Run the configure script with correct arguments. You need to tell configure
  74      at minimum a path to install to (--prefix). Later, after x3 is working,
  75      you may want to recompile it with additional modules by adding
  76      "--modules=memoserv,helpserv" but leave modules out for now.
  77
  78      Configure will verify that your system will have the resources needed for
  79      X3 to compile. You should also turn debugging on to assist with setup:
  80
  81      $ ./configure --prefix=/path/to/install --enable-debug
  82
  83   3) Run "make" to begin compiling.  If you encounter any
  84      uncorrectable errors/warnings, please scroll up to the introduction
  85      section and follow the instructions.
  86
  87      $ make
  88
  89   4) You may now either type "make install" to install it to your
  90      installation path, or work from your build directory, either is fine.
  91
  92      $ make install
  93
  94   5) Change to the install directory.
  95
  96      $ cd /path/to/install
  97
  98   6) Copy x3.conf.example to x3.conf
  99
 100      $ cp x3.conf.example x3.conf
 101
 102   7) The example config contains help to assist you with modifications.
 103      Remember to begin by only editing the bare minimum ammount you need to
 104      edit to make it run. Then, when it is working, gradually customize the
 105      config more. This way errors can be identified at their source.
 106
 107      Errors in the configuration file will be logged to
 108      main.log (and if X3 is running in the foreground with -f, printed to
 109      stdout) when you start x3.
 110
 111      To start with you will want to tell x3 where to connect. Modify the "Hub"
 112      entry in "uplinks" with your ircd info. You'll need a matching connect
 113      block in ircd.conf and a server type listen block for the  port.
 114
 115      You probably also want to modify the "hostname", "description", and "prefix",
 116      "numeric", "admin" etc. Other bits are documented, but generally must match
 117      how your ircd is configured.
 118
 119      $ nano -w x3.conf
 120
 121   8) You can now run x3 for the first time. You can debug by
 122      running it with '-fd'. It will not background itself, and it
 123      will be fairly verbose if you gave the configure script the
 124      --enable-debug flag. If you would like to run in the foreground
 125      with no verbosity, use the '-f' flag. If you just want to run it,
 126      execute X3 without any flags.
 127      $ ./x3 -fd
 128
 129   9) Once you have X3 started, you'll need to register a AuthServ
 130      account:
 131        /msg AuthServ@services.irc.com register <account> <password>
 132      Make sure that you register the first account -- it is
 133      automatically granted owner privileges and gives you admin
 134      access to O3 once you are opered up.
 135
 136  10) New operators can be given access to O3 through AuthServ's
 137      (or whatever you've named the nick/authentication service) oset
 138      command:
 139        /msg AuthServ oset <nick>|*<account> level <level>
 140      Levels are generally beween 0 and 1000 by convention; higher
 141      numbers correspond to more access. You can also add helpers
 142      (users with extra privileges such as security override in
 143      traditional configurations) through AuthServ:
 144        /msg AuthServ oset <nick>|*<account> flags +H
 145
 146  11) X3 stores its information in a flat text file (x3.db by default). If
 147      you shut down x3 first, you can edit this file by hand (but be careful!)
 148      If you delete it, x3 will start up brand new at step 9 (above) which
 149      can be handy if you think you have made a mistake.
 150
 151
 152
 153 If you get into trouble, stop by channel #Evilnet on irc.afternet.org for help.
 154
 155 --------------
 156 Help guide originally created for srvx by: -Jedi (jedi@turboflux.net)
 157 Adapted by Rubin
 158