INSTALL

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