INSTALL

   1                            Charybdis INSTALL Document
   2
   3    $Id: INSTALL 3384 2007-04-03 22:45:04Z jilles $
   4
   5    Copyright (c) 2001 by ircd-hybrid team
   6    Copyright (c) 2002-2004 ircd-ratbox development team
   7    Copyright (c) 2005-2008 charybdis development team
   8
   9      ----------------------------------------------------------------------
  10
  11                                   HOW TO BUILD
  12
  13    As of hybrid-4, the distribution uses GNU autoconf instead of the old
  14    Config script. The Makefile has also been updated to include CFLAGS
  15    defines for popular modern OSes.
  16
  17    1.
  18
  19        Read the NEWS file to find out about the exciting new features in
  20        this version. Other good reads are BUGS, doc/example.conf, and
  21        README.FIRST.
  22
  23    2.
  24
  25        Run the configure script. It will create include/setup.h and the
  26        Makefiles to match your system. In ircd-ratbox, the paths are now handled
  27        with the --prefix option to configure, not in config.h.
  28        /usr/local/ircd is the default if no prefix is specified.
  29
  30        ./configure --prefix="/usr/local/ircd"
  31
  32          Note: There are some special optional parameters to the configure
  33          script that some admins may wish to use.
  34
  35           *
  36
  37             --enable-kqueue - Use the superior kqueue(2) system call as
  38             opposed to the default poll(2). This is currently only available
  39             on FreeBSD 4.1 or higher.
  40
  41           *
  42
  43             --enable-devpoll - Enable the superior /dev/poll support on
  44             Solaris. Linux /dev/poll is broken and will not work with this
  45             option.
  46
  47           *
  48
  49             --enable-epoll - Enable the superior Linux Edge-Triggered Polling
  50             system. This is currently only available on 2.5 Linux kernel
  51             versions or later.
  52
  53           *
  54
  55             --enable-openssl - Enable the openssl dependent crypto functions.
  56             This will allow CHALLENGE to work and encrypted links. On systems
  57             where the configure script can automatically detect OpenSSL, this
  58             option is not necessary. If configure cannot find OpenSSL, you
  59             must specify a path with this option
  60             (--enable-openssl=/path/to/openssl)
  61
  62           *
  63
  64             --enable-ipv6 - Enable IPv6 support.
  65
  66           *
  67
  68             --enable-assert[=OPTION] - Enable some debugging code. OPTION is
  69             either 'soft' or 'hard' (default: hard). 'hard' should never be
  70             used on production servers as it may generate unnecessary cores.
  71             'soft' prevents cores from being generated but still imposes some
  72             additional load.
  73
  74           *
  75
  76             --enable-small-net - Tunes the server for smaller networks by
  77             reducing the startup memory footprint. This should really only be
  78             used for *small* networks, as this tends to be a performance hit
  79             on larger networks.
  80
  81           *
  82
  83             --with-nicklen=LENGTH - Sets the maximum NICK length. Note that
  84             this must be consistent across your entire network.
  85    3.
  86
  87        make should build ircd.
  88
  89    4.
  90
  91        make install will install the server, modules, and tools in the
  92        the prefix specified when configure was run.
  93
  94    5.
  95
  96        If you wish to enable the user log, oper log, and failed oper log,
  97        issue these commands at the shell prompt (in the prefix directory)
  98
  99  $ touch logs/userlog
 100  $ touch logs/operlog
 101  $ touch logs/foperlog
 102
 103          Note: If you use different names in ircd.conf, you must 'touch' the
 104          specific names.
 105
 106    6.
 107
 108        If you are upgrading from Hybrid 5 or Hybrid 6, the config file has
 109        changed drastically...
 110
 111        There is a utility to convert your old config file to the new format.
 112        In prefix/bin there is something called "convertconf". Its usage is:
 113        ./convertconf (old config file to convert) (converted file name)
 114
 115        Convertconf will NOT convert I: lines.  You must use "convertilines"
 116        for this which contains a much superior method of conversion and
 117        will group I: together under one auth {};.
 118
 119        Once this is done, move your new config to prefix/etc/ircd.conf and
 120        EDIT IT! There are still things that need changing in the config,
 121        including the fact that classes MUST be above auth/connect blocks!
 122
 123    7.
 124
 125        If you are upgrading from Hybrid 5 or Hybrid 6, the kline file has
 126        also changed...
 127
 128        There is a utility to convert the old kline configuration file to the
 129        new format. In prefix/bin there is a program called "convertklines".
 130        Its usage is: ./convertklines (old kline.conf filename) (new
 131        kline.conf filename) (dline.conf filename).
 132
 133        Once this is done, move the new files into the prefix/etc/ directory
 134        under their proper names. By default, the kline file is named
 135        kline.conf and the dline file is named dline.conf.
 136
 137      ----------------------------------------------------------------------
 138
 139                                 HOW TO GET HELP
 140
 141    Send Check or Money Order to... just kidding! You're on your own for
 142    support. Try asking other ircd-ratbox admins on EFnet if you can't fix it
 143    yourself. If you do fix anything, however, please send context or unified
 144    diffs to ircd-ratbox@lists.ratbox.org so the fixes can be incorporated into
 145    the next release of ircd-hybrid. If ratbox crashes on you, PLEASE contact
 146    ircd-ratbox@lists.ratbox.org ASAP with a backtrace of the core.
 147
 148    DISCUSSION: There is a mailing list for discussion of ratbox issues,
 149     To subscribe, visit:
 150        http://lists.ratbox.org/cgi-bin/mailman/listinfo/ircd-ratbox
 151
 152      ----------------------------------------------------------------------
 153
 154                                      NOTES
 155
 156    The best way to get a backtrace of the core is to follow this sequence of
 157    instructions:
 158
 159    1.
 160
 161        Change to the directory containing the core file
 162
 163    2.
 164
 165        Run gdb on the binary and the core file. With an unmodified ircd-ratbox
 166        installation, an example command line is below (in the /usr/local/ircd
 167        directory)
 168
 169  $ gdb bin/ircd ircd.core
 170
 171    3.
 172
 173        At the "(gdb)" prompt, enter the command "bt"
 174
 175    4.
 176
 177        Save the output of the backtrace command and send it to
 178        ircd-ratbox@lists.ratbox.org
 179
 180    5.
 181
 182        Be sure to save the ircd binary, the modules, and the core file in a
 183        safe place in case the developers need to look deeper than a backtrace
 184        provides.
 185
 186      ----------------------------------------------------------------------
 187
 188                                  OPENSSL NOTES
 189
 190    Older FreeBSD machines sometimes have the obsolete ports version of
 191    OpenSSL libcrypto in /usr/local/lib. When configure is used with
 192    --enable-openssl, and libintl is detected in /usr/local/lib, the
 193    /usr/local/lib directory will be searched BEFORE the system /usr/lib for
 194    libraries by the linker. The linker may try to link to the old
 195    /usr/local/lib libcrypto instead of the system /usr/lib libcrypto. Some
 196    older versions may cause error messages similar to the following:
 197
 198  gcc -g -O2 -DIRCD_PREFIX=\"/home/wcampbel/ircd\" -Wl,-export-dynamic
 199  -L/usr/local/lib -o ircd blalloc.o channel.o vchannel.o class.o client.o
 200  dline_conf.o event.o fdlist.o fileio.o hash.o irc_string.o ircd.o ircdauth.o
 201  ircd_signal.o linebuf.o list.o listener.o m_error.o match.o memdebug.o
 202  modules.o motd.o mtrie_conf.o oldparse.o numeric.o packet.o parse.o res.o rsa.o
 203  restart.o s_auth.o s_bsd.o s_bsd_kqueue.o s_conf.o s_debug.o s_gline.o s_log.o
 204  s_misc.o s_serv.o s_stats.o s_user.o scache.o send.o sprintf_irc.o tools.o
 205  whowas.o lex.yy.o y.tab.o version.o -lintl -ldescrypt  -lcrypto -lfl
 206  rsa.o: In function `get_randomness':
 207  /home/wcampbel/dev/ircd-ratbox/src/rsa.c(.text+0x60): undefined reference to
 208  `RAND_pseudo_bytes'
 209  /usr/local/lib/libcrypto.so: undefined reference to `ERR_load_RSAREF_strings'
 210  /usr/local/lib/libcrypto.so: undefined reference to `RSA_PKCS1_RSAref'
 211  *** Error code 1
 212
 213    If this is the case, you may need to rerun configure without the
 214    --enable-openssl option, manually edit src/Makefile and modules/Makefile
 215    to put -L/usr/lib before the -L/usr/local/lib in LDFLAGS, or remove the
 216    old OpenSSL from /usr/local, and recompile all applications that use
 217    libcrypto to use the system one.