rg3 / saircd Goto Github PK

Copyright 2012 Ricardo Garcia Gonzalez
See the COPYING file and section 7 of this document for license details.
--

saircd User Guide

1. About
2. Build instructions
3. Installation
4. Running the server
5. Supported features
	5.1. Network
	5.2. IRC protocol
		5.2.1. Limitations and unsupported features
		5.2.2. Supported optional features
		5.2.3. IRC operators
		5.2.4. Supported user modes
		5.2.5. Supported channel types and modes
	5.3. Special features
6. Recommendations
7. License
8. Contact information



1. About

saircd is a Stand-Alone IRC Daemon, that is, a simple IRC daemon oriented to
home and corporate use which does not support being connected to other IRC
servers. It is very easy to configure and use and will happily deliver several
thousand messages per second between users if run on appropriate hardware.

saircd is designed to build and run on most UNIX-like operaring systems.



2. Build instructions

saircd is written in plain C, so you will need a C compiler and a make tool. In
addition, it uses SQLite (www.sqlite.org) and the PCRE library (www.pcre.org).
You will need the development files from both libraries if you intend to build
the program.

Once your system meets the appropriate requirements, running "make" in the base
directory of the source code should build the executable file called "saircd"
and run some unit tests. If everything is fine, the make command will finish
successfully.

A manpage is provided in AsciiDoc format. If you want to generate it, you need
"asciidoc" and "xmlto". It can be generated running "make man".



3. Installation

Strictly speaking, the "saircd" binary file is the only one needed to run the
server, so once it has been built you can copy it to any directory in your
system and optionally create a configuration file somewhere (see the next
section).

However, for ease of use, an "install" target is provided in the Makefile. It
supports DESTDIR, PREFIX, BINDIR, MANDIR and other variables. It will install
the program, the default config file and the server manpage in the specified
directories. If you want to change them, you can edit the Makefile or set the
appropriate environment variables and run make with the "-e" option.

Other post-installation steps will be detailed in the next section.



4. Running the server

The server has a few configuration parameters that can be tuned from a
configuration file. If run without arguments, the server will use the default
value in every option. However, you can provide a single argument to the program
to indicate the path to a configuration file. In that file you can override
none, some or all the default configuration parameters and give them your own
values if you wish.

The "extra" directory in the source code distribution should contain a file
named "default-saircd.conf" describing the configuration file format and every
option in detail. That file can be used as a template to set your own values.
Other sample configuration files may be present in that directory too, tuned for
typical different use cases.

A brief description of every possible configuration option follows.

	max_clients
		Maximum number of clients the server will support.

	address
		Listening IP address for the server, if needed.

	port
		Listening server port.

	timeout_seconds
		Time to ping an inactive client and to wait for the reply.

	whowas_timeout_seconds
		Expiration time for WHOWAS entries.

	kill_timeout_seconds
		Amount of time a killed nick will be forbidden after the kill.

	max_channels
		Maximum number of channels that may be formed.

	max_client_channels
		Maximum number of channels a single client may be a member of.

	max_channel_members
		Absolute maximum number of client members for any given channel,
		independently of the limit set with the +l mode.

	max_bans
	max_exceptions
	max_invitations
		Maximum number of ban, exception and invite masks in any
		channel, for channel modes b, e and I.

	server_name
		Hostname or pseudo-hostname for the IRC server.

	motd
		Single line containing the message of the day.

	location
	entity
	email
		Information to be displayed in reply to the ADMIN command,
		specifying the server location, organization or company and
		administrator email, respectively.

	operators_file
		File containing username and passwords for IRC Operators. More
		information about this can be found in the "IRC protocol"
		section.

	username
		User to drop privileges to when running the server, after
		obtaining the listening socket and performing other server
		initialization steps.

	chroot_dir
		Directory to chroot to after initializing the server.

	daemonize
		Boolean option to run the server in the background or not.



5. Supported features


5.1. Network

The server works on TCP/IP and supports both IPv4 and IPv6. SSL is not
supported but external tools like stunnel (www.stunnel.org) could be used in
case SSL connections are needed.


5.2. IRC protocol

The server supports a broad subset of the protocol as specified in RFCs 1459 and
2812, and should be compatible with the most popular IRC clients in use. It has
been tested with mIRC, X-Chat or Irssi, among others.

A few IRC messages have been coded with limitations, and not every optional
feature has been implemented, but the resulting server should cover the needs of
most home and corporate uses.


5.2.1. Limitations and unsupported features

Messages related to server connections and services are not supported (e.g.
SERVICE, SQUIT, SQUERY or CONNECT).

A detailed list of limitations and unsupported messages follows.

  * During the connection registration phase, PASS is accepted but ignored.
  * SERVICE is not supported.
  * SQUIT is not supported.
  * Unlike other servers, saircd enforces "0" to be the only JOIN command
    argument if present, as required by the protocol specification. This means
    "JOIN 0" works but "JOIN #channel,0" does not.
  * NAMES and LIST cannot be used without arguments.
  * PRIVMSG and NOTICE require channels or nicknames. Masks are not supported.
  * Most messages accepting a server or subnet "target" argument ignore the
    argument or require it to match the server_name configuration parameter.
  * CONNECT is not supported.
  * SERVLIST is not supported.
  * SQUERY is not supported.
  * WHO and WHOIS require channels or nicknames. Masks are not supported.


5.2.2. Supported optional features

Server support for "optional features" as named in the RFCs is as follows.

  * AWAY is supported.
  * DIE is supported.
  * USERHOST is supported.
  * ISON is supported.
  * REHASH is not supported.
  * RESTART is not supported.
  * SUMMON is not supported.
  * USERS is not supported.
  * WALLOPS is not supported.


5.2.3. IRC operators

The IRC operator status can be reached with the classic OPER command. For that
to work properly, the operators_file option must have been set in the
configuration file.

As described in the "default-saircd.conf" template, this option specifies a file
containing username and password pairs to authenticate as an IRC operator. If
one client is currently authenticated as an IRC operator, no other user will be
able to authenticate to the same username and password pair while the client
remains connected, receiving an authentication failure message.

Blank lines and lines starting with # are considered comments, but any other
line should contain one username/password pair each. The username and the
password must be separated by a space character.


5.2.4. Supported user modes

The following user modes are supported:

  * a: toggled using AWAY messages.
  * i: toggled with user MODE messages.
  * w: toggled with user MODE messages, but it will not be used for anything.
  * r: toggled with user MODE messages.
  * o: set with OPER messages, and unset with user MODE messages.
  * s: toggled with user MODE messages, but it will not be used for anything.


5.2.5. Supported channel types and modes

Channel types # and & are supported and equivalent. Channel types + and ! are
not supported. Most channel modes described in RFC 2811 are supported. In
particular:

  * Channel modes o and v are supported for voice and operator privileges.
  * Basic modes n are t are supported.
  * Mode i for invite-only channels is supported.
  * Mode m for moderated channels is supported.
  * Modes p and s are supported and cannot be set at the same time (RFC).
  * Mode q is supported, but it should be set before any other user joins the
    channel to achieve the desired effect.
  * Mode a for anonyous channels is supported and can be toggled in any given
    moment.
  * Modes k and l to set a key or a limit are supported.
  * Modes b and e are supported, to set ban masks and exception masks.
  * Mode I for invitation masks is supported.
  * Modes O and r are not supported.



5.3. Special features

The server has a few special features worth mentioning.

Nickname "anonymous" is reserved for anonymous channels as described by RFC
2811. In addition, nickname "root" is also reserved.

There is a special channel called #log that only IRC operators may join. It's a
special quiet channel where the special nickname "root" writes server log
messages about JOINs, PARTs, connection and disconnection messages, and also IRC
operator authentication-related messages. Any client joining this channel could
save the channel log, which results in having remotely-saved server logs.



6. Recommendations

The typical recommended way of running the server is as follows:

Store the server executable file in /usr/local/bin, /usr/bin or other equivalent
directory.

Create /usr/local/etc/saircd, /etc/saircd or other equivalent directory. In it,
store a configuration file typically named saircd.conf. Also in the same
directory, create an operators file with at least one operator username and
password pair. Typical advice for secure passwords apply. Inside the
configuration file, indicate the full path to the operators file using the
"operators_file" option. The operators file should belong to the superuser and
have restricted read permissions.

Create a specific unprivileged user to run the server as, and indicate that
username in the "username" option. Using a generic unprivileged user, typically
named "nobody", may also be acceptable.

Create a specific empty directory in the file system and indicate its path in
the "chroot_dir" option. Using a generic empty directory, typically /var/empty,
may also be acceptable.

Obviously, operator passwords are stored in plain text and travel unprotected
through the network unless an external tool like stunnel is being used. In case
a security breach takes place regarding operator username and passwords, you do
not want the attacker to gain access to anything outside the virtual world of
the IRC server, so the username and passwords should not match the ones from any
other system or service in the same machine or in the corporate network in
general.

In case the server code contains an exploitable bug, the username and chroot_dir
options should be able to help minimize the problems derived from it, preventing
the attacker from accessing system files or performing privileged operations.

Once the configuration has been set in the file, the server should be called
with its full path as its only argument.



7. License

This file is part of saircd.

saircd is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

saircd is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with saircd.  If not, see <http://www.gnu.org/licenses/>.



8. Contact information

Ricardo Garcia <[email protected]>