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. Configuring your IRC server
2-6. Starting, stopping and controlling Services

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

2-1. System and network requirements

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

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):

Table 2-1. Supported IRC server types

IRC server (IRCD) nameServices module
Bahamut [] 1.8.0 and later (*) bahamut
Chunky Monkey IRCD 1.0 and later monkey
DALnet (ircd.dal) 4.4.13 and earlier dalnet
DALnet (ircd.dal) 4.4.15 and latre dreamforge
Dreamforge (ircd.dal 4.6.x) dreamforge
InspIRCd [] 1.1 and later inspircd
IRCD-Hybrid [] 7.0 and later (**) hybrid
ircd-2.8.x rfc1459
ircd-2.8.x+TS8 ts8
ircu (Undernet) [] 2.9.x undernet-p9
PTlink IRCd [] 6.10.0 and later ptlink
ircd-ratbox []2.1.x and later (***) ratbox
solid-ircd [], all versions (*) ratbox
tr-ircd [] 5.7 and later
UltimateIRCD 2.8.1 dreamforge
UltimateIRCD 3.0.0 bahamut
UnrealIRCd [] 3.1.1 and later unreal
(servers listed in italics are listed based on user reports, but are not supported)

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

(**) To use Hybrid with Services, you must load the module in your server's configuration. In recent versions of Hybrid (at least 7.2.3), this module is compiled automatically; in earlier versions, you may need to locate and compile it yourself. If the module is not loaded, Services will refuse to connect to the server.

(***) When using ircd-ratbox, make sure to include the "topicburst" server flag in the connect block for Services on the remote server; if topic burst support is not enabled, Services will refuse to connect to the server. Also, forced nickname changing will be unavailable unless all servers are compiled with the "--enable-services" option.

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; this means that they will work on any modern system regardless of version, at the cost of requiring slightly more disk space and runtime memory, 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 settings can be set by passing command-line options to the script; the most common ones are: See Table 2-2 below for a full list of options, which can also 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.

    Table 2-2. Options to the configure script

    Controlling the configure script
    -help Displays a list of command-line options and their meanings, then exits.
    -ignore-cache Prevents the cache file from being read. (The cache file, config.cache, is created the first time you run the configure script, and saves the results of configuration to speed up the script the next time you run it.)
    Controlling compilation
    -cc PROGRAM Specifies the C compiler to use, such as cc or gcc. If this option is given, the ordinary check for a compiler is skipped, and the given compiler is used. This option also causes the cached values of CFLAGS (compiler options) and LFLAGS (linker options) to be ignored; these options will revert to the defaults, unless the -cflags or -lflags options are also given.
    -cflags CFLAGS Specifies command-line options to pass to the compiler when compiling source files. The default depends on the compiler, but typically includes standard optimization flags, such as -O2 for GCC.
    -lflags LFLAGS Specifies command-line options to pass to the compiler when linking executable files. The default is no flags.
    -libs LIBS Specifies any extra libraries to be used when linking the main Services executable, using the linker library options -L and -l. Normally there is no need to use this option.
    -os2 Specifies that the system on which Services is being compiled is an OS/2 system. On such systems, Services may not compile correctly without this switch.
    Controlling installation
    -program NAME Specifies the name to be used for the executable file (default: ircservices). The configuration file ircservices.conf and the ircservices-chk script (see section 2-6) will also be renamed to NAME.conf and NAME-chk; the installation directories selected by the -prefix option (see below) will be changed to match; and the example configuration files will use the given name in the default log, PID, and MOTD files.
    -bindest DIR Specifies the directory to be used for program file installation. The main ircservices executable file and the ircservices-chk script will be installed in this directory.
    -datdest DIR Specifies the directory to be used for data file installation. All Services files and subdirectories except the two program files listed above will be installed in this directory.
    -prefix DIR Specifies the directory to be used for installation as a GNU-style installation prefix. Program files will be installed in DIR/sbin, and data files will be installed in DIR/lib/ircservices (or DIR/lib/NAME, where NAME is the executable name given to the -program option). If this option is given, the -bindest and -datdest options are ignored.
    Controlling Services features (use -no-option to disable)
    -use-local-funcs Forces the use of compatibility functions over system library functions. Normally, Services will use all system library functions available, except when a bug is detected in one of the functions; if this option is given, Services will instead make use of its own versions of these functions. This can be useful when debugging Services, or if you suspect a bug in the system libraries.
    -use-static-modules Forces modules to be compiled statically, even if dynamic modules could be used. Using static modules results in a larger executable file and more memory usage than using dynamic modules, but may be marginally faster. On some systems, dynamic modules are not supported, and modules will be compiled statically even if -no-use-static-modules is given.
    -sorted-lists Causes Services to keep the nickname and channel lists sorted; this can cause a performance penalty on large networks. Enabled by default (use -no-sorted-lists to disable).
    -clean-compile Attempts to compile Services with no compiler warnings; this may cause a slight performance penalty. Enabled by default (use -no-clean-compile to disable).
    -memchecks Performs extra checks on memory allocation. This option is intended for debugging only, and causes a significant performance penalty.
    -showallocs Causes all memory allocation activity to be logged to the Services logfile. This option is intended for debugging only, and will generate extremely large log files. This option is ignored unless -memchecks is enabled.
    -dumpcore Causes Services to attempt to write a core file if it crashes. This option can be useful in obtaining a backtrace to aid debugging; however, it prevents Services from shutting down cleanly, so you will not see a "shutting down" notice from Services when it detects a crash.
    Other options
    -check Checks whether this script has already been run and whether the cache is up-to-date. Exits with status 0 if up-to-date, 1 if not. This option is used by the Makefile to ensure that the configure script is run before compilation.

    When the script starts up, it will first determine the directories in which Services should be installed. These can be specified either through the -bindest/-datdest options or the -prefix option; if none of these are present, the script will use the same directories as when you last ran the script (if you have not run the script before or you use the -ignore-cache option, the defaults are /usr/local/sbin for the executable program and /usr/local/lib/ircservices for the data files).

    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 (Athlon64X2 4400+, 2GB 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.

    If you need to install Services to a separate subtree, for example when setting up Services in a chroot'd environment, set the INSTALL_PREFIX variable on the make command line. For example, if the installation prefix is set as /usr/local, then:
        make install INSTALL_PREFIX=/usr/local/chroot/
    will install files into /usr/local/chroot/usr/local/bin and /usr/local/chroot/usr/local/lib/ircservices. (The path given must include a trailing slash.)

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. (If Services is configured with a different program name, the first file's name will change to program-name.conf as well; however, in this manual, the default of ircservices.conf is assumed.) 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 /var/opt/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:

Table 2-3. Commonly used configuration directives

FileSetting and syntaxDescription
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 to which the Services HTTP server will listen. See section 3-6 for details.

Back to top

2-5. Configuring your IRC server

The IRC server to which Services will connect must be configured to allow Services to connect as a server. For traditional irc2-based servers, this involves adding appropriate C: and N: lines to the server's configuration file; consult your IRC server program's documentation for details.

Some IRC server programs, including traditional irc2-based ones, do not allow servers to introduce other servers, i.e. act as hubs, without a special configuration setting (an H: line in irc2-based servers). If this setting is missing from any server in your network, Services may be disconnected when you use the JUPE command.

In addition, some server programs support a "U-line" or similar concept, allowing servers named in a U: line or other configuration directive to override normal privilege checks (and consequently preventing other servers from overriding those checks). If your server program has such an option, ensure that it is set on all servers in your network, or you may encounter problems such as ChanServ being unable to change channel modes.

Also see the notes in table 2-1 above for special considerations when configuring particular types of IRC servers.

2-6. 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-4 below. The command-line option -help can be used to get a list of all available options.

Table 2-4. ircservices command-line options

-help Prints a list of available options.
-dir=pathname Uses pathname as the data directory instead of the compiled-in default.
-remote=host[:port] Connects to the specified server, overriding the RemoteServer setting in ircservices.conf.
-log=filename Writes logging information to filename, overriding the LogFilename setting in ircservices.conf.
-debug Starts Services in debug mode; using this option multiple times will produce more debugging output.
-readonly Starts Services in read-only mode; database and log files will not be written to, and online data modification will be limited to Services administrators.
-nofork Prevents Services from forking (going into the background) after initialization, and causes log messages to be written to the terminal as well as the log file.
-noexpire Disables expiration of database entries (nicknames, channels, autokills, and so on).
-noakill Disables autokill checking. (However, the autokill list itself can still be modified.)
-forceload When using the database/version4 module, attempts to load as much data from corrupted databases as possible, rather than aborting when an error is found.
-encrypt-all Re-encrypts all passwords on startup using the encryption type selected in ircservices.conf. (Passwords encrypted with one type generally cannot be re-encrypted with a different type, so this is generally useful only to ensure that no passwords are left unencrypted after activating encryption.)
-import=filename Imports data into Services' databases (see section 5-2).

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:

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

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