1   ircd-ratbox INSTALL Document
2
3   $Id: INSTALL 27223 2011-10-12 01:26:35Z dubkat $
4
5   Copyright (c) 2001 by ircd-hybrid team
6   Copyright (c) 2002-2011 ircd-ratbox development team
7
8     ----------------------------------------------------------------------
9
10          __               __                 __   __
11         |__|.----.----.--|  |___.----.---.-.|  |_|  |--.-----.--.--.
12         |  ||   _|  __|  _  |___|   _|  _  ||   _|  _  |  _  |_   _|
13         |__||__| |____|_____|   |__| |___._||____|_____|_____|__.__|
14
15
16     +--------------------------------------------------------------------+
17     | IMPORTANT: for those who don't bother reading docs...              |
18     | If you are upgrading from ANY VERSION of ircd-ratbox, see the      |
19     | instructions under UPGRADING, #3. YES, THIS MEANS YOU!             |
20     ` ------------------------------------------------------------------ '
21
22       Read the ChangeLog file to find out about the exciting
23       new features in this version. Other good reads are
24       doc/whats-new.txt, BUGS, doc/example.conf, and README.FIRST.
25
26       An example.conf for EFnet is in doc/ with the values "approved"
27       on 12 December 2001.
28
29
30
31  > QUICK START
32
33   1. Configure (see below under CONFIGURE OPTIONS for more details):
34
35     I.   Large networks (with thousands of users):
36          ./configure --prefix=/home/user/ircd
37
38     II.  Small networks (with only a few hundred users or less):
39          ./configure --prefix=/home/user/ircd --enable-small-net
40
41     III. Configure ircd-ratbox for running with minimal resources
42          on a 64bit VPS (Virtual Private Server). This creates
43          a 32bit IRCD which takes up less memory:
44          CFLAGS="-m32" ./configure --prefix=/home/user/ircd \
45          --enable-small-net
46
47   2. Build:
48
49     I.  On linux systems: make
50     II. On *BSD systems: gmake
51
52
53   3. Install:
54
55    I.  make install (or gmake install on *BSD)
56    II. make install-strip (strips out debugging code for smaller
57        binaries and modules)
58
59        DO NOT SUBMIT BUGS IF YOU HAVE STRIPPED THE IRCD OF DEBUGGING
60        SYMBOLS. WE WILL NOT BE ABLE TO HELP YOU.
61
62
63
64
65  > ADDITIONAL CONFIGURE OPTIONS
66
67   Note: There are some special optional parameters to the configure
68         script that some admins may wish to use.
69
70   *  --enable-kqueue
71            Use the superior kqueue(2) system call as opposed to
72            the default poll(2). This is currently only available
73            on FreeBSD 4.1 or higher, and should be auto-detected.
74
75   *  --enable-devpoll
76            Enable the superior /dev/poll support on Solaris.
77            Linux /dev/poll is broken and will not work with this
78            option. Do not use this unless you comprehend the implications.
79
80   * --enable-openssl
81            Enable the openssl dependent crypto functions.
82            This will allow CHALLENGE to work and encrypted links.
83            On systems where the configure script can automatically
84            detect OpenSSL, this option is not necessary.
85            If configure cannot find OpenSSL, you must specify a
86            path with this option.
87            (--enable-openssl=/path/to/openssl)
88
89            If you plan on using SSL encrypted client connections,
90            or encrypted links, you may wish to run
91            /path/to/ircd/bin/genssl.sh to generate self-signed
92            certificates.
93
94   * --enable-ipv6
95            Enable IPv6 support. This should be auto-detected.
96
97   * --enable-static
98            Enable a static-linked ircd. You will not be able to unload,
99            or reload modules. You probably don't want this.
100
101   * --enable-assert
102            Enable some of the debugging code. This should NOT be used
103            on production servers. Doing so is a performance hit,
104            and can cause cores from things that shouldn't normally happen.
105
106   * --enable-small-net
107            Tunes the server for smaller networks by reducing the
108            startup memory footprint. This should really only be used
109            for *small* networks, as this tends to be a performance hit
110            on larger networks.
111
112   * --with-nicklen
113            Sets the maximum NICK length. Note that this MUST be
114            consistant across your entire network.
115
116   * --enable-services
117            If your network runs ratbox-services, this enables extra
118            code to actually make it useful on your ircd.
119            Please read doc/services.txt for more information.
120
121
122
123  > UPGRADING
124
125   1. If this is a clean install of ircd-ratbox, you may skip this section.
126
127   2. Upgrading from ircd-ratbox-2.x, ircd-hybrid-7.x
128
129      If you have an older version of ircd-ratbox or ircd-hybrid, and
130      you have klines, dlines, resvs, and xline config files, keep
131      reading.
132
133      ircd-ratbox no longer uses flat-file based configs for these
134      types of entries, instead they are stored in a database. To
135      prevent accidental clobbering, or leaving behind old, unsupported
136      modules it would be best to install ratbox into a clean location.
137
138      After you have finished installing the ircd, you will likey wish
139      to import your old ban files.  ircd-ratbox-3 includes a tool
140      to manage the database. Importing, backing up, error checking,
141      and reclaiming lost space are all supported. For more information,
142      run /path/to/ircd/bin/bantool with no arguments.
143
144      I.  import old ban configs (pretend mode):
145          /path/to/ircd/bin/bantool -i -d -p /path/to/oldircd/etc
146
147          If everything looks good, you will want to actually let
148          bantool do the import.
149
150      II. import old ban configs:
151          /path/to/ircd/bin/bantool -i -d /path/to/oldircd/etc
152
153
154   3. Upgrading from another version ircd-ratbox-3.x
155
156      * IMPORTANT: EVERY TIME YOU UPGRADE ircd-ratbox-3 YOU NEED TO
157        ISSUE THIS COMMAND. FAILURE TO DO SO CAN CAUSE YOUR IRCD TO CORE!
158
159      I. /path/to/ircd/bin/bantool -u
160
161
162
163
164  > HOW TO GET HELP
165
166   Send Check or Money Order to... just kidding!
167   (However free beer is always appreciated)
168
169   * For Bug Reports, visit: http://bugs.ratbox.org
170
171   * For General Question, you may ask your question
172     on #ratbox on EFnet.
173
174   If you do fix anything, however, please post a context or unified
175   diff on http://bugs.ratbox.org so the fixes can be incorporated into
176   the next release of ircd-ratbox.
177
178   If ratbox crashes on you, please submit a bug report, and include the
179   gdb backtrace or corefile on http://bugs.ratbox.org
180
181   DISCUSSION: There is a low-volume mailing list for discussion of
182   ratbox issues, To subscribe, visit:
183       http://lists.ratbox.org/cgi-bin/mailman/listinfo/ircd-ratbox
184
185     ----------------------------------------------------------------------
186
187  > NOTES
188
189   The best way to get a backtrace of the core is to follow this sequence of
190   instructions:
191
192   1. Change to the directory containing the core file
193
194   2. Run gdb on the binary and the core file. With an unmodified
195      ircd-ratbox installation, an example command line is below
196      (in the /path/to/ircd directory). This will be useless
197      if you used 'make install-strip'.
198
199      $ gdb bin/ircd ircd.core
200
201   3. At the "(gdb)" prompt, enter the command "bt"
202
203   4.  Save the output of the backtrace command and submit it to
204       http://bugs.ratbox.org
205
206   5.  Be sure to save the ircd binary, the modules, and the core file
207       in a safe place in case the developers need to look deeper
208       than a backtrace provides.
209
210
211