- Sux Services Installation Guide -

Prerequisites

You are about to install Sux Services, the new-generation IRC services: they aim to be robust, flexible and scalable.

Remember that the code is nor complete neither heavily tested: random crashes can occur, and they could even put your machine on fire.

Read the license (the COPYING file) for informations about warranty.

What do you need:

Component Notes
A supported Operating System Currently supported systems are:

  • Linux 2.4.18 or later
  • FreeBSD 4.7-STABLE or later Other Operating Systems are currently not supported.
    Porting efforts are really wanted. mailto: vjt@openssl.it.

    Linux notes: Not tested with older 2.4 kernels, tested a little with 2.2 kernels. But they should work.
    FreeBSD notes: You need to recompile some ports and to run ./configure with specific options. See README.FreeBSD for more information.

    • GCC 2.95 or later Tested also with gcc 3.{0,2}
    LinuxThreads

    Make sure you have /lib/libpthread.so on a Linux System, /usr/local/lib/liblthread.so on a FreeBSD System

    GLib >= 2.2.0 with gthreads

    You can get source tarballs of GLib from The GTK Site or you can install it with your favourite package manager.

    mySQL server and threaded
    mySQL client library.

    You can download source tarballs from http://www.mysql.com.
    Tested only with version 3.23.55, but should work with any recent release.
    If you compile libmysqlclient on your own, make sure to give the --enable-threaded-client
    option to ./configure

    Bahamut 1.4.34 or later

    You can download bahamut from http://bahamut.dal.net.
    Tested only with version .34 and .35.
    Refer to the bahamut documentation for information on how to setup it.
    For increased performance, you can #define SERVICESHUB in include/config.h

    !!!! NOT TESTED WITH ANY OTHER IRC DAEMON !!!!
       

    Step by step compilation and installation guide

    First of all you need to build the core services:

  • Run the ./configure script.
  • Run make

    After that, sux services should have been succesfully compiled. If the ./configure script or the build fails, please drop me a note: vjt@openssl.it. Thanks :).

  • You need to create a mysql user and database for services. For more information on how to create a database, please refer to the official mySQL documentation.

    If you are looking for a graphical client for mysql, I suggest mysqlcc.
    If you are looking for a web-based client for mysql, I suggest phpMyAdmin.
    If you are an SQL expert, you can use the command line mysql client :).

  • Ok, let`s assume that you have created a user called 'suxserv' with the 'sUx4L07' password and a database called 'suxdb'.
    Now you need to import the sql dumps into the newly created database. The dumps are located into the doc/ subdirectory of the source distribution: 
     -rw-r-----    1 vjt      vjt          5943 Mar  1 02:10 sux-db.sql
 -rw-r-----    1 vjt      vjt         14143 Feb 28 18:19 sux-help.sql

    The first file contains the database schema, the second one contains the help files. You must import the schema first, and then the help files.
    You can do this by issuing these commands: 

     $ mysql -h host.where.the.mysql.server.is -u suxserv -p suxdb < sux-db.sql
 $ mysql -h host.where.the.mysql.server.is -u suxserv -p suxdb < sux-help.sql

    Insert the password for the 'suxserv' user when asked ('sUx4L07' in this example).

    Editing the configuration file

    You are almost done !
    Now you need to edit the sux.conf file to reflect your installation-specific parameters.

    sux.conf is located into the src/ subdirectory. For correct operation, you must keep the 'sux' binary and the 'sux.conf' file into the same subdirectory. Keeping both files into the src/ subdirectory is also a good idea.

    Editing sux.conf is really straigthforward. The file is broken in three main parts:

  • Global configuration variables,
  • Mysql-related variables,
  • Modules section,
  • Per-agent configuration, which includes parameters for service agents.

    The file is also heavily commented, so open it now and insert your parameters :).

    Congratulations ! You have just installed Sux Services. Start your ircd, and then go into the src/ subdirectory of sux services and type ./sux They should link to your server and start to process data.

    Debugging

    If something goes wrong, and you want to help me finding bugs, you can compile a debug version of Sux Services: 

     $ make clean
 $ ./configure --enable-debug-build
 $ make

    After that, you can run the binary into gdb: 

     $ gdb ./sux
 GNU gdb 5.3-debian
 Copyright 2002 Free Software Foundation, Inc.
 GDB is free software, covered by the GNU General Public License, and you are
 welcome to change it and/or distribute copies of it under certain conditions.
 Type "show copying" to see the conditions.
 There is absolutely no warranty for GDB.  Type "show warranty" for details.
 This GDB was configured as "i386-linux"...
 (gdb) run -d
    And then you could try to repeat the commands that made services crash. At this point, the gdb will catch the SIGSEGV and give you his prompt. Now, type 'bt full' 
     (gdb) bt full
 #0  0x46d85ae2 in sigsuspend () from /lib/libc.so.6
 .... etc ...
    and email me those strange lines. Core dumps ( they can be also quite large ) and binaries are also welcome. Thanks :)

    Enjoy !


    --
    Marcello Barnaba (vjt@openssl.it)
    Aleksandr Krejnin (aleksandr@openssl.it)

    EOF