INSTALL

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