ircd-ratbox installation instructions

Copyright (c) 2001-2002 ircd-hybrid development team
Copyright (c) 2002-2026 ircd-ratbox development team

 __               __                 __   __
|__|.----.----.--|  |___.----.---.-.|  |_|  |--.-----.--.--.
|  ||   _|  __|  _  |___|   _|  _  ||   _|  _  |  _  |_   _|
|__||__| |____|_____|   |__| |___._||____|_____|_____|__.__|

+-------------------------------------------------------+
|                        IMPORTANT                      |
| If you are upgrading from ANY VERSION of ircd-ratbox, |
| see the instructions under #3 UPGRADING .             |
+-------------------------------------------------------+

Read the ChangeLog to find out about the exciting new features in this version.
Other good reads are doc/whats-new.txt, BUGS, doc/example.conf and README.FIRST.

An example.conf for EFnet is in doc/ with values "approved" on 12 December 2001.

-------------------------------------------------------------------------------

#1 QUICK START

  1. Configure (see below under #2 CONFIGURE OPTIONS for more details):

+-----------------------------------------------------------------------------+
|                                  IMPORTANT                                  |
| At a minimum, you really ought to use the --prefix=/some/place option.      |
| By default, configure will select /usr/local/ircd-ratbox - YOU DO *NOT* WANT|
| THAT! You may *NOT* run the IRCD as root! The IRCD user needs to be able    |
| to write to its own directories. You have been warned!                      |
+-----------------------------------------------------------------------------+

    I. ./configure --prefix=/home/user/ircd

    II. Configure ircd-ratbox for running with minimal resources on a 64bit VPS.
        This creates a 32bit IRCD which takes up less memory:
          CFLAGS="-m32" ./configure --prefix=/home/user/ircd

  2. Build:

    I. On linux systems: make

    II. On *BSD systems: gmake

  3. Install:

    I. make install (or gmake install on *BSD).

    II. make install-strip - strips out debugging code
        for smaller binaries and modules.

        DO NOT SUBMIT BUGS IF YOU HAVE STRIPPED THE IRCD OF DEBUGGING
                SYMBOLS! WE WILL NOT BE ABLE TO HELP YOU.

#2 ADDITIONAL CONFIGURE OPTIONS

Note: These are some special optional parameters to the configure script
      that some admins may wish to use:

  --enable-openssl
      Enables the OpenSSL dependent crypto functions. This will allow CHALLENGE
      and encrypted links to work. On systems where the configure script can
      automatically detect OpenSSL, this option is not necessary. If configure
      cannot find OpenSSL, you must specify a path with this option:
        --enable-openssl=/path/to/openssl

      If you plan on using SSL features, you may wish to run
      /path/to/ircd/bin/genssl.sh to generate self-signed certificate.

  --enable-ipv6
      Enables IPv6 support. This should be auto-detected.

  --enable-static
      Enables a static-linked IRCD. You will not be able to unload or reload
      modules. You probably don't want this.

  --enable-assert
      Enables some of the debugging code. This should NOT be used on production
      servers. Doing so is a performance hit and can cause cores from things
      that shouldn't normally happen.

  --enable-services
      If your network runs services daemon, this enables extra code to actually
      make it useful on your IRCD. Read doc/services.txt for more information.
  --enable-jemalloc
  --enable-tcmalloc
  --enable-tcmalloc-minimal
      The above options enable jemalloc or tcmalloc.  Both are an alternate
      memory allocator. Both tend to perform faster than the default glibc
      malloc on Linux at least.
  --enable-ocf-services 
      This enables the hooks required for OpenChanfix(not packaged with
      ircd-ratbox)

   

#3 UPGRADING

Note: If this is a clean install of ircd-ratbox, you may skip this section.

  1. Upgrading from ircd-ratbox-2.x or ircd-hybrid-7.x:

  If you have an older version of ircd-ratbox or ircd-hybrid and you have
  klines, dlines, resvs, and xline config files, keep reading.

  ircd-ratbox no longer uses flat-file based configs for these types of entries,
  instead they are stored in a database. To prevent accidental clobbering or
  leaving behind old, unsupported modules, it would be best to install
  ircd-ratbox into a clean location.

  After you have finished installing the IRCD, you will likely wish to import
  your old ban files. ircd-ratbox-3 includes a tool to manage the database.
  Importing, backing up, error checking and reclaiming lost space are supported.
  For more information, run /path/to/ircd/bin/bantool with no parameters.

    I. Import old ban configs (pretend mode):
      /path/to/ircd/bin/bantool -i -d -p /path/to/oldircd/etc

      If everything looks good, you would want bantool to do the import.

    II. Import old ban configs:
      /path/to/ircd/bin/bantool -i -d /path/to/oldircd/etc

  2. Upgrading from ircd-ratbox-3.x:

+-----------------------------------------------------------------------------+
|                                  IMPORTANT                                  |
| EVERY TIME YOU UPGRADE ircd-ratbox-3 YOU NEED TO ISSUE THIS COMMAND.        |
| FAILURE TO DO SO CAN CAUSE YOUR IRCD TO CORE!                               |
|   /path/to/ircd/bin/bantool -u                                              |
+-----------------------------------------------------------------------------+

#4 HOW TO GET HELP

  Send check or money order to...
  Just kidding! However free beer is always appreciated.

  For bug reports, general questions, you may find us on #ratbox on EFnet.

  If you do fix anything, however, please post a context or unified diff to
  ircd-ratbox@lists.ratbox.org so the fixes can be incorporated into
  the next release of ircd-ratbox.

  If ircd-ratbox crashes on you, please submit a bug report and include the
  gdb backtrace or corefile to ircd-ratbox@lists.ratbox.org

  There is a low-volume mailing list for discussion of ircd-ratbox issues.
  To subscribe, visit: http://lists.ratbox.org/cgi-bin/mailman/listinfo/ircd-ratbox

#5 NOTES

  The best way to get a backtrace of the core is to follow this sequence of
  instructions:

  1. Change to the directory containing the core file;

  2. Run gdb on the binary and the core file (in the /path/to/ircd directory),
     with an unmodified ircd-ratbox installation, an example command line
     is below. This will be useless if you used 'make install-strip':

       gdb bin/ircd ircd.core

  3. At the "(gdb)" prompt, enter the command "bt"

  4. Save the output of the backtrace command and submit it to ircd-ratbox@lists.ratbox.org

  5. Be sure to save the ircd binary, the modules, and the core file in a safe
     place in case the developers need to look deeper than backtrace provides.
