IRC Services Manual - 2. Installing and using Services

# IRC Services Manual

## 2. Installing and using Services

2-1. System and network requirements
2-2. Installing Services from a binary distribution
2-3. Installing Services from source code
2-4. Configuring Services
2-5. Starting, stopping and controlling Services

Table of Contents

### 2-1. System and network requirements

In order to run Services, you will need the following:

- A POSIX-compliant operating system. Services is designed for the Linux operating system, but should function on any POSIX-compliant (or nearly so) operating system; it is known to work on FreeBSD and Solaris, and has been reported to work on MacOS X as well.

  Notice: Services will not work on OpenBSD 3.4, as the version of GCC included in that release (2.95.3) has an OpenBSD-specific bug which causes Services to crash, and OpenBSD 3.4 is not yet supported by more recent versions of GCC due to an executable file format change. An enhancement request (#13891 [`gcc.gnu.org`]) has been filed with the GCC development team, and the OpenBSD developers are apparently working on importing GCC 3.3.2 into OpenBSD, but until one or the other is complete, you will need to use either an older version of OpenBSD or a different operating system to run Services. (It may be possible to compile Services on an OpenBSD 3.3 or earlier system and use the resulting executable on OpenBSD 3.4; this has not been tested.)

- A supported IRC server (IRCD). Services supports several different types of IRC servers, as listed in Table 2-1 below. Your IRC network must be using one of these servers in order to use Services (the "Services module" column indicates which protocol module is used with that server; see section 2-4 for details).

Additionally, if you plan to compile Services from the source code, you will also need the following (note that these are not necessary if you install from a binary package):

- GCC [`www.gnu.org`] (the GNU C compiler), either version 2.95.3, or version 3.2 or later. Services currently uses some extensions to the C language provided by GCC, and is unlikely to compile on other compilers; Services also takes advantage of recent additions to the C standard (often referred to as "C99") which are not supported by older versions of GCC. This version of Services may compile with such older versions, albeit with less specific error messages in some circumstances, but support for them is planned to be removed completely in Services 5.1.

  Notice: (1) Services will not work with the SSP (stack-smashing protector) [`www.trl.ibm.com`] patch to GCC, due to a bug in SSP triggered by Services that causes crashes. The `configure` script (see below) will automatically detect the presence of this patch and deactivate the stack-protection feature, or refuse to compile if it cannot be deactivated.

  (2) Versions of GCC before 3.4 have bugs which cause Services to crash. Services has workarounds for the Intel x86, SPARC, and PowerPC platforms, but you will need to use GCC 3.4 or later on other systems. See FAQ B.1.5 for details.

- GNU make [`www.gnu.org`], version 3.79 or later. Services uses complex Makefiles which may or may not work with other "make" programs, and are known not to work with earlier versions of GNU make. Note that GNU make may be installed on your system as either `make` or `gmake`; if you're not sure, type `make -v` or `gmake -v` in your shell, and if you get output that looks like "`GNU Make version 3.79.1, by Richard Stallman and Roland McGrath`", then it's installed.

- The Bourne shell or a compatible shell. This should be installed on your system as `/bin/sh`. If by any chance the `configure` script fails (see section 2-3), try installing Bash [`www.gnu.org`] and using it to run the `configure` script.

- Perl [`www.perl.com`] may also be needed if you modify certain files (the language data files in particular).

IRC server (IRCD) name | Services module
--- | ---
Bahamut [`bahamut.dal.net`] 1.8.0 and above (*) | `bahamut`
Chunky Monkey IRCD 1.0 and above | `monkey`
DALnet (ircd.dal) 4.4.13 and below | `dalnet`
DALnet (ircd.dal) 4.4.15 and above | `dreamforge`
Dreamforge (ircd.dal 4.6.x) | `dreamforge`
IRCD-Hybrid [`ircd-hybrid.com`] 7.0 (**) (experimental) | `hybrid`
ircd-2.8.x | `rfc1459`
ircd-2.8.x+TS8 | `ts8`
ircu (Undernet) [`coder-com.undernet.org`] 2.9.x | `undernet-p9`
PTlink IRCd [`www.ptlink.net`] 6.10.0 and above (experimental) | `ptlink`
tr-ircd [`tr-ircd.sourceforge.net`] 5.5 and above (5.7 recommended) | `trircd`
UltimateIRCD 2.8.1 | `dreamforge`
UltimateIRCD 3.0.0 | `bahamut`
UnrealIRCd [`www.unrealircd.com`] 3.1.1 and above | `unreal`

Table 2-1. Supported IRC server types
(servers listed in italics are listed based on user reports, but are not supported)

(*) When using Bahamut, do not configure your server as a "services hub" ("`servtype serviceshub`" in the `ircd.conf` file); this setting causes Bahamut to not send certain information needed by Services to work correctly. If Services detects that Bahamut is configured as a services hub, it will log a message to that effect and abort.

(**) To use Hybrid with Services, you must compile and install the `TBURST` module, found in the `contrib` directory of the Hybrid distribution. After compiling and installing Hybrid, execute the following command from the top-level directory of the distribution:
`make m_tburst.so ; cp m_tburst.so prefix/modules/autoload`
where `prefix` is the installation prefix you specified to the Hybrid `configure` script (default `/usr/local/ircd`). If the `TBURST` module is not properly installed, Services will refuse to connect to the server.

Back to top

### 2-2. Installing Services from a binary distribution

Binary distributions of Services are provided for Linux systems in the popular RPM and .deb formats. See the Services home page to download the latest binary distribution, then install or upgrade it the same way you would for any other package.

Note that executable files in the binary distributions are compiled statically, which means that they will work on any modern system regardless of version, at the cost of requiring slightly more disk space and requiring an upgrade (or recompile from source) if a bug is found in any of the system libraries used by Services.

Back to top

### 2-3. Installing Services from the source code

If no binary distribution is available for your platform or you prefer to compile Services yourself, you will need to install from the source code. Once you have downloaded the source, you need to:

1. Run the `configure` script. This script checks what type of system you are running and determines what adjustments to the base source code are necessary in order to compile. Certain compile-time options can be set by passing command-line flags to the script; the most common ones are:
   - `-ignore-cache` (ignore the results of any previous configuration)
   - `-prefix pathname` (set default installation location)
     (Note: installation directories are not automatically created when this option is used)
   - `-use-static-modules` (compile using statically-linked modules, even if dynamic linking is available)
   A full list of flags can be obtained with `./configure -help`. (If you prefer the GNU autoconf "`--option[=value]`" format, `configure` will accept that as well, e.g. "`--prefix=/usr`".) Note that `configure` will ignore environment variables like `CC` and `CFLAGS`; use the appropriate command-line options instead if you need to set these yourself.

   Note on using alternate C compilers: If you specify a particular C compiler using the `-cc` option, or if GCC is not installed on your system, you will also need to specify any necessary options using the `-cflags` option. In particular, Services uses a feature of C known as "pointer aliasing", which is technically forbidden by the C standard but necessary for clean programming. Some compilers attempt to optimize based on the assumption that pointer aliasing is not used; if your compiler does this, you will need to tell it not to (the option for GCC that does this is `-fno-strict-aliasing`).

   When the script starts up, it will first ask for the directories in which you want to install the Services program and data files. By default, these are `/usr/local/sbin` and `/usr/local/lib/ircservices`, respectively (if you have run `configure` before, the pathnames you used last time will be used here instead); press Enter to accept the default for each, or enter the path you want to use for installation. If you change the program installation directory, a "good" data directory pathname will be generated from the path you gave. Finally, if you use the `-prefix pathname` command-line option, then these questions will be skipped, and the program and data installation directories will be set to `pathname/sbin` and `pathname/lib/services` respectively.

   After setting the installation directories, `configure` will check your system and print out status messages as it proceeds. At the end, if no errors occur, it will print out a message telling you to proceed with compilation.

2. Edit `defs.h` and the `Makefile`, if necessary. There are a few settings at the top of these files which can be changed as needed. Usually, however, there is no need to change them, and you can proceed directly to compilation.

   One case in which you may want to modify a setting is if you run a regional network which uses a language other than English as its primary language; in this case, you can change the `DEF_LANGUAGE` setting in `defs.h` to your local langauge.

3. Compile the program. Run the command `make` (or `gmake`, depending on your system) from the top-level directory. Compilation time will vary depending on your system; on the author's system (1.7GHz Celeron, 1GB RAM), compiling the entire program takes approximately one minute. If you have a multiple-processor system, you can use `make -jN` (or `gmake -jN`) to compile in parallel using `N` threads, which will significantly reduce compilation time. Parallel compilation is also useful if your system has slow I/O (such as disk access), since it lets one compilation run while another is waiting for a disk access to complete.

4. Install the program and data files. Run the command `make install` (or `gmake install`) and the program and data files will be copied to their destinations. The program file is installed as `ircservices` in the program installation directory; the data installation directory will contain sample configuration files (see section 2-4), language data files, the `convert-db` utility, and (if you compiled modules with dynamic linking, which is the default on systems which support it) module files.

   Note that if you are compiling the program as the same user you will install as, you can just use the single command `make install` to compile and install in one step.

Back to top

### 2-4. Configuring Services

Once Services has been installed, it must be configured for your network. Services uses two text files to control its behavior: `ircservices.conf` and `modules.conf`. `ircservices.conf` contains settings that affect Services as a whole, such as the remote server to connect to; `modules.conf` contains settings that apply to individual modules, such as NickServ and ChanServ. These files are stored in the Services data directory (the directory you gave when running the `configure` script; this is `/usr/lib/ircservices` for the binary distributions).

When Services is installed, two sample files, `example-ircservices.conf` and `example-modules.conf`, are installed in the data directory; if you are installing Services for the first time, you should start out by copying or renaming these files to `ircservices.conf` and `modules.conf` respectively. Each file contains detailed information about all possible settings, which can also be found in Appendix A. When setting up Services for the first time, you should at least check these settings:

File | Setting and syntax | Description
--- | --- | ---
`ircservices.conf` | `RemoteServer host[:port] password` | Sets the server to which Services connects and the password used to connect.
`ircservices.conf` | `ServerName name` | Sets the server name Services will use on the IRC network.
`ircservices.conf` | `ServerDesc description` | Sets the server description provided by Services.
`ircservices.conf` | `ServiceUser user@host` | Sets the username and hostname used by Services clients. You may want to set this to an E-mail address at which users can ask questions about Services or your IRC network.
`ircservices.conf` | `LoadModule module-name` | Loads the specified module. The example configuration file lists all of the possible modules; select which ones you want to load or not load. In particular, make sure you select the correct protocol module and enter its name in the line which reads "`LoadModule protocol/(insert protocol name here)`" or Services will not be able to start.
`modules.conf` | `Module protocol/protocol-name` | Change this line (the first `Module` line in the file) so it contains the same protocol module you specified in `ircservices.conf`.
`modules.conf` | `FromAddress user@host` | `mail/main` module: Sets the E-mail address used as the sender on outgoing mail. Set this to an address at which users can contact you with questions about Services.
`modules.conf` | `FromName "name"` | `mail/main` module: Set this to the "name" you want to use as the sender on outgoing mail. If you don't want a name (just the E-mail address), leave this setting commented out.
`modules.conf` | `ServicesRoot nick` | `operserv/main` module: Set this to the nickname which should be granted Services root (super-user) privileges.
`modules.conf` | `ListenTo address:port` | `httpd/main` module: Sets the ports which the Services HTTP server will listen to. See section 3-6 for details.

Table 2-2. Commonly used configuration directives

Back to top

### 2-5. Starting, stopping and controlling Services

Services can be started by simply running the `ircservices` program from a shell prompt. Upon starting, Services will parse its command-line arguments and the `ircservices.conf` file, then open the log file; if there are no errors, it will then print a short message to the terminal, put itself in the background and return control to the shell. If an error does occur, Services will print an error message and exit.

Several command-line options can be used to modify Services' behavior or override settings in the `ircservices.conf` configuration file; these are summarized in table 2-3 below. The command-line option `-help` can be used to get a list of all available options.

Option | Meaning
--- | ---
`-help` | Print list of available options
`-dir=pathname` | Use `pathname` as the data directory instead of the compiled-in default
`-remote=host[:port]` | Connect to the specified server; overrides `RemoteServer` setting
`-log=filename` | Write logging information to `filename`; overrides `LogFilename` setting
`-debug` | Starts Services in debug mode; using this option multiple times will produce more debugging output
`-readonly` | Starts Services in read-only mode; databases and log file will not be written to
`-nofork` | Do not fork (go into the background) after initialization
`-noexpire` | Disable expiration of database entries (nicknames, channels, autokills, etc.)
`-noakill` | Disable autokill checking (autokill list can still be modified)
`-forceload` | Attempt to load corrupted databases as much as possible
`-import=filename` | Import data into Services' databases (see section 5-2)

Table 2-3. `ircservices` command-line options

Once in the background, Services will load language files and modules, then try to connect to the remote server specified in `ircservices.conf` (or on the command line). If any errors occur during these steps, an error message will be printed to the log file and Services will terminate. If Services appears to start up correctly but does not connect to your IRC network, check the log file for any errors that may have occurred.

Once Services successfully connects to your IRC network, it will continue running until either:

- the remote server closes the connection (for example, because of a `/SQUIT` command);
- an OperServ `RESTART`, `SHUTDOWN`, or `QUIT` command is received; or
- a termination signal (`SIGINT` [`^C`], `SIGQUIT`, `SIGTERM`, or `SIGKILL`, as well as fatal program errors) is received.

In any of these cases (except in the case of a `SIGKILL` signal, which Services cannot detect), an appropriate message will be written to the log file describing why Services terminated.

The debug output level and read-only setting can be modified while Services is running using the OperServ `SET` command as needed, and other OperServ commands can be used to monitor the status of Services or (as mentioned above) shut down or restart Services.

While it is running, Services will periodically save modified data (newly registered nicknames and channels, modified settings, and so on) to disk. This is done in such a way that even if Services crashes while writing the data, the previous contents of the databases will remain intact. However, should the database files become corrupt (whether because of a bug in Services or as the result of hardware failure or tampering), the `-forceload` command-line option can be used to recover as much data as possible from the corrupted data file. It is also strongly recommended that you make regular backups of your data files, to reduce potential damage from such problems.

If the contents of the `ircservices.conf` or `modules.conf` configuration files are changed, Services can be instructed to reread the files with either the OperServ `REHASH` command or the `SIGHUP` signal. If no errors are found in the configuration files, Services' settings will be updated with the new configuration file contents. Modules can also be loaded and unloaded this way without restarting Services by adding or removing `LoadModule` directives in `ircservices.conf`; however, modules will not be able to be unloaded if other loaded modules depend on them. (For example, since the ChanServ module depends on NickServ being available, you cannot remove the NickServ module while leaving the ChanServ module loaded. You can, however, unload both of them at once.)

If the system Services runs on supports periodic execution of programs, such as via the `cron` utility, you can use the supplied script `ircservices-chk`, installed in the same directory as the `ircservices` executable, to ensure that Services comes back up quickly if it should crash or otherwise terminate unexpectedly. (Of course, you will need to disable this check if you ever shut down Services intentionally!) On a typical Unix system, the following line, when added using the `crontab` utility, will cause the `ircservices-chk` script to be run once every five minutes (here, `/path/to/ircservices-chk` represents the full path to the `ircservices-chk` script):

> `0,5,10,15,20,25,30,35,40,45,50,55 * * * * /path/to/ircservices-chk`

If you need to pass options to the `ircservices` executable, simply add them after `ircservices-chk` in the line above. You can also prevent the script from generating output (which would be sent to you by mail) by adding the `-q` option after `ircservices-chk` and before any other options.

Back to top

Table of Contents | Previous section: About IRC Services | Top | Next section: Overview of Services features