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