README.md

   1 # shroudBNC
   2
   3 shroudBNC is a modular IRC proxy written in C++. It is capable of proxying IRC connections for multiple users. Using TCL scripts it can be extended.
   4
   5 # Installation
   6
   7 First of all make sure that you have the following software (and accompanying development files) installed:
   8
   9 - C++ compiler (usually GCC)
  10 - Autoconf
  11 - Automake
  12 - Libtool
  13 - OpenSSL (if you're going to use SSL-encrypted connections; README.ssl contains more details about how to use SSL)
  14 - SWIG and TCL (if you're going to use the tcl module, version 8.4 or later, earlier versions have not been tested)
  15 - Optional: c-ares
  16
  17 On Debian you can install all the required packages using this command:
  18
  19     apt install build-essential autoconf automake libtool libssl-dev tcl-dev swig libc-ares-dev
  20
  21 In order to compile and install shroudBNC you will have to use the `autogen.sh` and `configure` scripts:
  22
  23     $ ./autogen.sh
  24     $ ./configure
  25
  26 If you are planning to install shroudBNC as root you will need to manually specify another prefix, e.g.:
  27
  28     # ./configure --prefix=/usr/local
  29
  30 Note: While loading TCL scripts shroudBNC will fall back to trying the `$PREFIX/share/sbnc` directory when a script isn't available in the user's configuration directory. Therefore it is NOT necessary to use absolute paths in the `sbnc.tcl` configuration file.
  31
  32 The configure script will tell you which features have been enabled (e.g. SSL, TCL). In case any of the required libraries are missing you can now fix these errors and re-run the configure script.
  33
  34 Afterwards you can build shroudBNC:
  35
  36     $ make
  37     $ make install
  38
  39 Unless you have manually specified another prefix `make install` will install shroudBNC in a directory named `sbnc` in your home directory:
  40
  41     [gunnar@hermes ~]$ ls -l ~/sbnc
  42     total 6
  43     drwxr-xr-x  2 gunnar  gunnar    3 Aug 22 18:28 bin
  44     drwxr-xr-x  3 gunnar  gunnar    3 Aug 22 18:28 lib
  45     -rwxr-xr-x  1 gunnar  gunnar  243 Aug 22 18:28 sbnc
  46     drwxr-xr-x  3 gunnar  gunnar    3 Aug 22 18:28 share
  47     [gunnar@hermes ~]$
  48
  49 Once you've compiled shroudBNC you will need to edit its configuration files:
  50
  51 You can do that by simply starting shroudBNC in the installation directory:
  52
  53     [gunnar@hermes ~]$ cd ~/sbnc
  54     [gunnar@hermes ~/sbnc]$ ./sbnc
  55     shroudBNC (version: 1.3alpha18 $Revision: 1158 $) - an object-oriented IRC bouncer
  56     Configuration directory: /usr/home/gunnar/sbnc
  57     [Sun August 22 2010 18:37:29]: Log system initialized.
  58     No valid configuration file has been found. A basic
  59     configuration file can be created for you automatically. Please
  60     answer the following questions:
  61     1. Which port should the bouncer listen on (valid ports are in the range 1025 - 65535): 9000
  62     2. What should the first user's name be? test
  63     Please note that passwords will not be echoed while you type them.
  64     1. Please enter a password for the first user:
  65     2. Please confirm your password by typing it again:
  66     Writing main configuration file... DONE
  67     Writing first user's configuration file... DONE
  68     Configuration has been successfully saved. Please restart shroudBNC now.
  69     [gunnar@hermes ~/sbnc]$
  70
  71 If you've installed shroudBNC as root you can simply start `sbnc` in any directory (as a non-root user). shroudBNC will pick up any existing configuration directories (i.e. `~/sbnc`, `~/.sbnc` or the current working directory). If no configuration directory could be found it defaults to `~/.sbnc` and asks you to create a config file.
  72
  73 After creating the configuration files you can start shroudBNC:
  74
  75     [gunnar@hermes ~/sbnc]$ ./sbnc
  76     shroudBNC (version: 1.3alpha18 $Revision: 1158 $) - an object-oriented IRC bouncer
  77     Configuration directory: /usr/home/gunnar/sbnc
  78     [Sun August 22 2010 18:42:53]: Log system initialized.
  79     [Sun August 22 2010 18:42:53]: Created main listener.
  80     [Sun August 22 2010 18:42:53]: Starting main loop.
  81     Daemonizing... DONE
  82     [gunnar@hermes ~/sbnc]$
  83
  84 You might want to edit the sbnc.tcl config file if you plan to use the TCL module. Load any scripts you want. You will have to rehash the tcl module after every change you make to `sbnc.tcl` or any other `.tcl` script which you have loaded:
  85
  86     /sbnc tcl rehash (while you're connected to the bouncer using an IRC client)
  87
  88 # Usage
  89
  90 Just connect to the bouncer using your favorite IRC client. You will have to set your username (i.e. e-mail address in most clients) to the account name you've chosen for your bouncer account. If for some reason you can't change your client's username you can specify the username in the password setting (of the form `username:password`).
  91
  92 Once you're connected you should type /msg -sBNC help to get a list of available commands.
  93
  94 shroudBNC supports oidentd in order to provide unique idents for each bouncer user. You will need to enable ident-spoofing for the Unix account you're using to run shroudBNC if you want each user to have their own ident. Read oidentd's manual.
  95
  96 # TCL
  97
  98 The tcl module is automatically built and installed if the configure script was able to find the appropriate tcl libraries and headers.
  99
 100 If the configure script was unable to find the TCL libraries/headers and you are sure that they are installed you might use the --with-tcl parameter to specify the location of the tclConfig.sh file manually; e.g.:
 101
 102     ./configure --with-tcl=/usr/local/ActiveTcl/tcl8.4
 103
 104 # Log files
 105
 106 shroudBNC automatically re-creates log files if they disappear during runtime. It also re-opens them if their inode of dev numbers change. Therefore rotating logs is as easy as moving the existing logs to a different location.
 107
 108 # Security
 109
 110 It is vital that you understand that any bouncer admin has access to:
 111
 112 a) the shell account where the bouncer is running
 113 b) any user connections
 114
 115 Using the TCL module any admin can perform shell commands (using the exec command) and send IRC commands for any user's connection. Thus you should choose your admins wisely. Do not load arbitrary scripts and make sure you understand any scripts you want to load.
 116
 117 # Credits
 118
 119 I'd like to thank all the beta testers who have been using shroudBNC so far. Feature requests and bug reports are welcome; please use our issue tracker at https://github.com/gunnarbeutner/shroudbnc
 120
 121 In case you encounter problems while compiling and/or using shroudBNC you can contact us on IRC:
 122
 123 Server: irc.quakenet.org / 6667
 124 Channel: #sbnc
 125
 126 # Third Party Software
 127
 128 This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)
 129
 130 For a more detailed list of third-party code in this project please refer to the README.copyright file.