IRC Services Manual - 3. Overview of Services features

# IRC Services Manual

## 3. Overview of Services features

3-1. Nickname management (NickServ)
3-1-1. Core NickServ features
3-1-2. Nickname linking
3-1-3. E-mail authorization
3-1-4. Access lists
3-1-5. Miscellaneous functions
3-2. Channel management (ChanServ)
3-2-1. Core ChanServ features
3-2-2. Channel access lists
3-2-3. Miscellaneous functions
3-3. Memo sending (MemoServ)
3-3-1. Core MemoServ features
3-3-2. Memos and channels
3-3-3. Memo ignore lists
3-3-4. Memo forwarding
3-4. Network/Services control and maintenance (OperServ)
3-4-1. Services privilege levels
3-4-2. Core OperServ features
3-4-3. Autokills and S-lines
3-4-4. Session limiting
3-4-5. News
3-5. Network statistics collection (StatServ)
3-6. Built-in HTTP server
3-6-1. Core HTTP server module
3-6-2. Authorization modules
3-6-3. Content modules
3-7. Password encryption

Table of Contents

### 3-1. Nickname management (NickServ)

#### 3-1-1. Core NickServ features

IRC Services' features are based around the concept of "registering" a nickname as one's own. Once you have registered a nickname, Services will recognize you as the "owner" of that nick, and will warn anyone else who tries to use the nick that it is owned by someone else; Services can even prevent other people from using a registered nick by removing ("killing") them from the network or forcibly changing their nickname to something else.

The "NickServ" pseudoclient provides the interface to functions related to nickname registration and maintenance. (The nickname "NickServ" can be changed via the `NickServName` setting in the `modules.conf` configuration file.) NickServ receives commands via `/msg`; for example, typing

> `/msg NickServ REGISTER password`

would send NickServ the "`REGISTER`" command, used to register a nickname, with "`password`" as its parameter. Command names are case-insensitive, so "`register`" or "`ReGiStEr`" could be used instead of "`REGISTER`", for example.

Typically, when first connecting to a network using Services, a user will use the `REGISTER` command (as in the example above) to register their nickname with Services, assuming it is not already used. Once the nickname is registered, the user would then use the `IDENTIFY` command with the password given in the `REGISTER` command every time they connected to the network, informing Services that they are the owner of the nick and should be permitted to use it; this can be thought of as similar to logging into an Internet service provider account. Finally, if the user decides to stop using their nickname, whether because of changing to another nickname or switching IRC networks entirely, they can use the `DROP` command to cancel the nickname's registration. (Even if the nickname is not explicitly dropped, it will expire if not used for 30 days, or whatever value is given for the `NSExpire` setting in `modules.conf`.)

Users can also include an E-mail address when they register a nickname. This will be stored with the nick and can be used to allow other users or IRC operators to contact the user outside of IRC. By setting the `NSRequireEmail` option in `modules.conf`, the E-mail address can be made mandatory at registration time. In addition, the `NSRegEmailMax` option can be used to set the maximum number of nicknames that can be registered to a single E-mail address.

The `LIST` and `INFO` commands are available to display, respectively, a list of registered nicknames matching a particular pattern or detailed information on a single nickname. The `LIST` command simply displays a list of nicknames with the last seen `user@host` address for each nick; the `INFO` command displays the nick owner's last seen address and "real name", the time of registration and of last use, and last quit message, as well as any URL, E-mail, or information line that have been set for the nickname (see below). Of this information, the nick owner can choose to hide the last seen address, last quit message, and E-mail address from ordinary users by using the `SET HIDE` command. Note that usage of the `LIST` command can be limited to IRC operators by setting the `NSListOpersOnly` option in `modules.conf`.

Normally, when a user tries to use a registered nickname, Services will only send a warning that the nickname is registered, and not take any further action (aside from denying privileges on registered channels, as described in section 3-2 on channel management). By using the `SET KILL` command, however, users can instruct Services to forcibly prevent other users from using their nicknames, using either a `/kill` to disconnect the user from the network or (if the IRC server supports it and the `NSForceNickChange` option is set in `modules.conf`) forcibly changing the user's nickname if they do not identify with the proper password within a certain period of time. Services will also introduce an "enforcer" pseudoclient with the nickname in question, to prevent the user from immediately reconnecting or changing their nick back; the enforcer will be removed after one minute. The `SET KILL` option defaults to off, but can be set to on (60 second time limit), quick (20 second time limit), or immediate—an option which comes into play with access lists, discussed below. (Note that the "immediate" setting is not available unless the `NSAllowKillImmed` option has been set in `modules.conf`.)

The `SET HIDE` and `SET KILL` commands mentioned above are just two of the options available for the `SET` command, which allows users to adjust various features of their nicknames. Users can change their nickname password (`SET PASSWORD`) or set a URL (home page address), E-mail address, or "information line" for their nickname (`SET URL`, `EMAIL`, and `INFO` respectively), which will be displayed when other users request information on the nick with the `INFO` command; a number of options for the nickname can be set as well, such as the aforementioned `KILL` and `HIDE` options, or whether the nickname should appear in output from a `LIST` command (`SET PRIVATE`). Default options for newly registered nicknames can be set using the `NSDef...` configuration options in `modules.conf`.

For the URL, E-mail address, and information line, the `UNSET` is available to clear any previously set value. (If the `NSRequireEmail` configuration option is set, the E-mail address may not be cleared.)

If the owner of a nickname discovers that another user is using their nick, then they can use the `RECOVER` command to have Services disconnect (or change the nick of) the user immediately; the `RELEASE` command is also available to remove the nickname enforcer before its one-minute timeout. A related command, `GHOST`, simply disconnects the user of the nickname immediately without using an enforcer, and is intended for cases where the nick's owner gets disconnected from and reconnects to the IRC server, and the disconnected ("ghost") session has not disappeared from IRC yet.

One other command, `STATUS`, allows users (and bots or other automated clients) to check whether a particular user is recognized as the owner of the nickname they are using; the reply will contain a number indicating whether the nickname is registered and whether the user has identified for that nickname.

In addition, Services administrators (see section 3-4-1) have access to:

- the `DROPNICK` command, which allows any nickname to be dropped;

- the `SET NOEXPIRE` command, which allows a nickname to be marked so that it never expires;

- the `GETPASS` command, which allows the password for a nickname to be retrieved (this may not be possible when encryption is in use—see section 3-7—and can be disabled anyway by unsetting the `EnableGetpass` configuration option in `ircservices.conf`);

- the `SUSPEND` command, which can be used to prevent a nickname's owner from using that nick for a certain period of time while retaining the nickname's settings;

- and the `FORBID` command, which completely prevents any use of a nickname and erases any previous settings.

Additionally, Services administrators may use the `SET` command for any nickname by inserting the nickname before the option name (see the `SET` documentation). Note, however, that if the `WallSetpass` configuration option is set in `ircservices.conf`, then a message will be broadcast to all IRC operators whenever the `SET PASSWORD` command is used in this way.

Back to top

#### 3-1-2. Nickname linking

Several additional functions are available through add-on modules. Chief among these is "nickname linking", available with the `nickserv/link` module.

Many users like to use variations on their main nickname; for example, a user with the nickname "Alice" might use "AliceAway" while away from her terminal, or "AliceZZZ" if she left her IRC client connected all night. While it is of course possible to register each of these nicknames separately, the owner would then have to identify for each nickname separately as well; nickname settings, such as setting an E-mail address or URL, would also have to be done individually for each nick. More importantly, channel access lists (see section 3-2-2) would require one entry for each nickname, causing the size of the access list to double, triple, or worse.

In order to avoid this problem, Services provides a way to link multiple nicknames together so that they are, for all practical purposes, treated as the same nick. Aside from information truly specific to each nickname—last seen time, address, name, and quit message—all information is shared among all of the linked nicknames, and they can be used interchangeably with no extra effort on the part of the nickname owner or other users.

Nickname owners can link other nicknames to their own with the `LINK` command; this command takes an unregistered nickname and links it to the user's current nickname. The `UNLINK` command does the reverse, cancelling a link from a nickname and releasing that nick for others to use. Additionally, the `LISTLINKS` command is available to give a list of all nicknames linked to the user's current nickname; one of these will be marked with an asterisk ("`*`"), which indicates the "main nickname" for the group of nicknames. The main nickname defaults to the first nickname registered in the group, and can be changed using the `SET MAINNICK` command. (Main nicknames are discussed in more detail in the section on channel access lists.)

Note that the `DROP` command will drop all nicks linked to the current nick (as well as the current nick itself); the `UNLINK` command must be used to cancel a single linked nick while leaving the others intact.

There is an additional module, `nickserv/oldlink`, that uses the same semantics for the `LINK`, `UNLINK`, and `LISTLINKS` commands as earlier (4.x) versions of Services did. This module is intended only to help users of earlier versions of Services migrate smoothly to the new format, and should not be used if at all possible; it will be removed in a future version of Services.

Back to top

#### 3-1-3. E-mail authorization

In order to help enforce accountability for registered nicknames, Services can require users to "authorize" their nickname registration using a numeric code sent via E-mail to the address provided when the nickname is registered. In order to have Services recognize the nickname as a valid, registered nickname, the owner must send the code back to Services first, thus verifying that the E-mail address the owner provided is in fact valid. This functionality is provided by the `nickserv/mail-auth` module.

When this module is in use, registration of a nickname proceeds as follows:

1. The user sends a `REGISTER` command to NickServ, just as with a normal registration; however, an E-mail address is mandatory with the command. (The `nickserv/mail-auth` module will refuse to load if the `NSRequireEmail` configuration option, mentioned above, is not set.)

2. The normal registration checks are made: if the nickname is forbidden, the E-mail address is invalid, or some other problem occurs, Services reports an error and discards the `REGISTER` command.

3. A random 9-digit authorization code is generated, stored with the nickname in Services' databases, and sent via E-mail to the user. The E-mail looks like this, if the default language is set to English:

   > `The authorization code for your nickname (NickName) is: 123456789
   > Please submit this code to NickServ with the command:
   > /msg NickServ AUTH 123456789
   > This message was sent by NickServ in response to registration by
   > username@hostname.example.com.`

4. Services informs the user that their nickname has been registered, and that they will need to authorize it with the code sent to their E-mail address before they can use it.

5. The user sends an `AUTH` command to NickServ with the code given in the E-mail.

6. Services checks that the code given matches the one sent, and if so, marks the nickname as authorized and allows it to be used normally (the user will get privileges in channels if on the channel's access list, etc.).

A procedure similar to the above is followed when a nickname owner changes the E-mail address associated with the nickname using the `SET EMAIL` command.

If for some reason, such as a mail server problem, the user does not receive the E-mail message containing the authorization code, they can request that an extra copy of the message be sent by using the `SENDAUTH` command. By default, Services will only allow this command to be used once a day per nickname (nickname group when links are in use) in order to minimize potential abuse of this command, e.g., to send "mail-bombs" to other users. If necessary, this interval can be changed using the `NSSendpassDelay` option in `modules.conf`; however, if it is set too low or disabled, malicious users will be able to abuse Services to send large amounts of mail to arbitrary users.

Services can be set to automatically drop unauthorized nicknames after a shorter period than the usual expiration time. The configuration option `NSNoAuthExpire` in `modules.conf` is used to set this time; by default it is not set, meaning that unauthorized nicknames will be retained until the usual expiration time (defined by `NSExpire`).

Additionally, the commands `SETAUTH`, `GETAUTH`, and `CLEARAUTH` are available to Services administrators. The `SETAUTH` command generates a new authorization code for the given nickname, requiring its owner to authorize the nick before continuing to use it; `GETAUTH` command retrieves the authorization code stored for the given nickname, if any; and the `CLEARAUTH` command clears any stored authorization code and allows the nickname's owner to use the nick normally, as if they had authorized it with the `AUTH` command.

Back to top

#### 3-1-4. Access lists

Normally, when a user connects to the IRC network, the user must identify to NickServ with their password before Services will recognize them as the owner of their nickname. Access lists, provided by the `nickserv/access` module, provide a way for users to be recognized as nickname owners based on the user's `user@host` address (the address shown in a `/whois` reply among other places) and given limited privileges without having to identify by password.

A nickname's access list consists of one or more "masks"; these are strings containing wildcards, similar to channel ban masks except that the mask includes a username and hostname only, no nickname. When a nickname is first registered, an access mask is added which matches the user's current username and hostname. If the `NSFirstAccessWild` configuration option is set, then the the leftmost part of the hostname (if a domain name; the rightmost part of an IP address) is replaced with a "*" to match any address in that network, in case the user's IP address changes (for example, from disconnecting from and reconnecting to the user's service provider). After registering a nickname, users can use the `ACCESS` command to view or modify the nickname's access list.

By default, even if a user matches an address on their nickname's access list, they are not granted any special permissions in channels. This can be changed with the `SET SECURE` command; disabling the `SECURE` option allows the user to obtain channel privileges without entering a password. (Note that there is also a `SET SECURE` command for ChanServ, which, if set on a channel, causes all nicknames to be treated as if the `SECURE` option was set with respect to that channel, regardless of whether the particular nickname actually has that option set.)

Nickname access lists have one other effect, which is to prevent users matching an access list entry from being disconnected or having their nickname changed regardless of the nickname's `KILL` setting. This allows a user to use the "quick" or even "immediate" setting to prevent other users from using the nickname, while still having time to identify to NickServ themselves. (When the "immediate" setting for the `KILL` option is used, any user who does not match an entry on the access list will immediately be disconnected or have their nickname changed; this has the effect that if the access list for such a nickname ever becomes empty, no one will be able to use it, and a Services administrator will need to either drop the nickname or change its settings before it can be used again.)

Warning: Access lists can lead to improper access to a nickname if the nickname's owner does not have a fixed IP address. For example, a user whose hostname may be any of `ppp01.city.example.com` through `ppp16.city.example.com` would need to use an access mask of at least `ppp*.city.example.com`, which would allow another user of the same provider to impersonate the nickname owner by setting the username sent by the impersonator's IRC client and/or RFC1413 ident server. Such users should always set the `SECURE` option on their nicknames to avoid having an impersonator improperly obtain channel or other privileges.

Back to top

#### 3-1-5. Miscellaneous functions

Two other additional functions are available via separate NickServ modules:

- Autojoin lists (module `nickserv/autojoin`), which cause Services to automatically make a user join certain channels when they identify for their nickname; this can be useful for users who connect from shared computers or public terminals, for example, and cannot customize the IRC client to automatically join channels upon connecting. The list of channels to automatically join can be viewed and updated with the `AJOIN` command.

  This functionality requires the use of an IRC server which allows users to be forcibly joined to certain channels (often known as `SVSJOIN`).

- The `SENDPASS` command (module `nickserv/sendpass`), which allows users to have Services send their nickname's password via E-mail to the address associated with the nickname. This can eliminate, or at least reduce, the need for Services administrators to intervene when a user forgets their password.

  As with the `GETPASS` command, this command may not be usable when encryption is enabled. This module will also refuse to load if E-mail authorization (section 3-1-3) is not in use, to prevent users from sending mail to arbitrary addresses.

Back to top

### 3-2. Channel management (ChanServ)

#### 3-2-1. Core ChanServ features

Just as with nicknames, channels can also be registered with Services. Once you register a channel, Services will automatically give you channel operator privileges ("ops") when you enter the channel, even if you are not the first user in the channel, and conversely it will not allow other users to gain ops simply by being the first user in the channel; you can also designate other users to be automatically granted ops or voice privileges (mode `+v`). In addition, Services will save the topic on the channel even when it is not in use, and can enforce various modes on the channel, such as `+m` (moderated) or `+s` (secret).

The "ChanServ" pseudoclient allows access to the various channel management functions, much like NickServ does for nicknames, and as with NickServ, ChanServ receives commands via `/msg`. (Also as with NickServ, ChanServ's nickname can be changed via a configuration setting: `ChanServName` in `modules.conf`.)

ChanServ uses the same basic commands as NickServ for managing channels: `REGISTER` to register a channel as one's own, `IDENTIFY` to obtain privileges on a channel via password, `SET` and `UNSET` to set various channel options, `DROP` to cancel a channel's registration, and `LIST` and `INFO` to display information about registered channels. Note that when a channel is registered, a "description" parameter is required in addition to a password; this description is displayed in the output from the `LIST` and `INFO` commands.

By default, a single user (i.e. nickname group) is not permitted to register more than 20 channels; any attempt to register channels above this limit will result in an error. This limit can be changed via the `CSMaxReg` option in `modules.conf`. Also by default, channels will expire in 14 days (changeable via the `CSExpire` option in `modules.conf`) if they are not "used" for that period of time; for this purpose, "used" means that a user with auto-op privileges (see section 3-2-2) has entered the channel.

When a user registers a channel, that user is recorded in Services' databases as the channel's founder. The founder of a channel will always receive ops in that channel when they enter (as well as "channel owner" mode on those IRC servers that support it), and is the only one permitted to use certain ChanServ commands, in particular `SET` and `DROP`. Channel founder privileges may be obtained either by identifying for the nickname used to register a channel (or any nickname linked to it) as described in section 3-1-1, or by using the ChanServ `IDENTIFY` command with the password given at registration to identify as the channel founder. The founder of a channel can be changed without dropping and re-registering the channel by using the `SET FOUNDER` command.

If the founder's nickname is dropped, or if it expires and no other unexpired nicknames are linked to it, then the channel will be automatically dropped. However, if a successor is set with the `SET SUCCESSOR` command, then the nickname designated as the successor will become the new founder of the channel, and the channel will not be dropped. (However, if the successor nickname has already registered channels up to the registration limit, the channel will be dropped as usual.) A channel's successor can be cleared with the `UNSET SUCCESSOR` command.

The `SET MLOCK` command allows a channel's founder to have Services always set certain modes on the channel. This command is used similarly to the IRC `/mode` command, with a list of mode characters interspersed with `+` and `-` characters possibly followed by mode parameters (such as a channel key or user limit for the `+k` or `+l` modes). The important difference is that modes specified here are always forced by Services to be as specified; for example, if a mode lock of `+s` is set on a channel, Services will always set `+s` on that channel when it is first joined by a user, and will not allow anyone to set `-s` on the channel. Any modes not specified in the mode lock are not forced either on or off, so in the previous example of a mode lock of `+s`, the `+i` mode could be set or unset freely by channel operators. The default mode lock for a new channel is `+nt`.

Other options available for the `SET` command include `PASSWORD` and `DESC`, to change the channel's password or description; `URL` and `EMAIL`, to set a URL or E-mail address for the channel (both of which can be cleared with `UNSET`); `ENTRYMSG`, to set a message to be sent from ChanServ to each user that enters the channel (this can also be cleared with `UNSET`); `KEEPTOPIC`, to set whether the channel's topic is saved when no one is in the channel; `PRIVATE`, to set whether the channel should be shown in the results for a `LIST` command; and `SECURE`, to enforce nickname password security for the channel even for nicknames that don't have the `SECURE` option set (as described in section 3-1-4).

To assist a channel founder in recovering control from a malicious user or out-of-control script, the `CLEAR` command may be used to remove certain modes from the channel, or even to remove all users from the channel at once (a "mass-kick").

Additionally, a channel founder may define an autokick list, also known as an "AKICK list" after the command used to maintain the list, `AKICK`. This is a list of users who should not be allowed to join the channel, and is similar to an ordinary channel ban list (set with `/mode channel +b ...`), except that Services will remember the list even when the channel is not in use, and automatically kick and set a ban on the user as necessary. Aside from the usual `ADD`, `DEL`, and `LIST` subcommands, the following subcommands are also available:

- `VIEW`: Displays the autokick list, much as the `LIST` subcommand does but with more details (including the last time a user matching the entry tried to join the channel, which can be helpful in finding out-of-date entries).

- `ENFORCE`: Causes Services to check all users in the channel against the autokick list and kick and ban any users which match any entries in the autokick list. This can be used after adding a new entry in place of kicking the user manually.

- `COUNT`: Returns the number of entries on the autokick list.

As with NickServ, several commands are reserved for Services administrators. These commands are:

- `SET NOEXPIRE`
- `GETPASS`
- `FORBID`
- `SUSPEND`
- `UNSUSPEND`

and operate on channels the same way as do their NickServ equivalents on nicknames; see the relevant part of section 3-1-1. The notes in that section on the `SET` command apply as well, in the sense that Services administrators need not identify for a channel in order to change its settings. Additionally, Services administrators are allowed to enter forbidden and suspended channels.

Finally, note that the channel "`#`" (a single "`#`" character with no name following) is treated specially by Services. While this channel is legal according to the IRC protocol (RFC1459) and in fact supported by most, if not all, IRC servers, it requires special treatment for use with a number of Services functions, and in fact bugs in previous versions of Services as well as other Services-like programs have allowed users to crash these programs using the channel "`#`". Thus, to avoid the potential for such problems, Services explicitly refuses to allow this channel to be registered (or forbidden), which in turn prevents any other Services functions from being used with it.

As a result of this (lack of) handling, users will be able to use the channel "`#`" freely. If this bothers you, the `CSForbidShortChannel` option in `modules.conf` can be enabled, which causes Services to treat this channel as a forbidden channel and not allow any clients to use it. (Unlike normal forbidden channels, even Services administrators will not be permitted to use the channel when this option is enabled.)

Back to top

#### 3-2-2. Channel access lists

The remainder of the ChanServ commands and options revolve around a concept known as the channel access list. This is a list of nicknames and associated access levels which describes who should be allowed what privileges on a particular channel. Depending on the access level assigned to a nickname, that nickname's user may be automatically granted ops on entering the channel, or may be allowed to use privileged commands such as `AKICK`. Alternatively, a low access level may prevent a user from obtaining ops on the channel or even entering the channel at all.

Access levels are integral numbers between -999 and 999 inclusive, with higher values meaning greater privilege; a user whose nickname are not on the access list, or who has not identified for their nickname (except as described for nickname access lists in section 3-1-4), has an access level of 0 (zero). A user with a given access level has all privileges listed in Table 3-1 with a lesser or equal minimum access level. (The "name" column in the table refers to privilege names for the `LEVELS` command, discussed later.)

Name | Level | Privilege
--- | --- | ---
Automatic-mode privileges
`AUTOVOICE` | 30 | Automatic mode `+v` (voice) on entering channel
`AUTOHALFOP` | 40 | Automatic mode `+h` (halfop) on entering channel (*)
`AUTOOP` | 50 | Automatic mode `+o` (channel operator) on entering channel
`AUTOPROTECT` | 100 | Automatic mode `+a` (protected) on entering channel (*)
Command privileges
`ACC-LIST` | 0 | Allowed to use the `LIST` subcommand for the `ACCESS` command
`VOICE` | 30 | Allowed to use the `VOICE` and `DEVOICE` commands
`HALFOP` | 40 | Allowed to use the `HALFOP` and `DEHALFOP` commands
`ACC-CHANGE` | 40 | Allowed to use the `ACCESS` command
`OPDEOP` | 50 | Allowed to use the `OP` and `DEOP` commands
`INVITE` | 50 | Allowed to use the `INVITE` command
`UNBAN` | 50 | Allowed to use the `UNBAN` command
`KICK` | 50 | Allowed to use the `KICK` command
`TOPIC` | 50 | Allowed to use the `TOPIC` command
`PROTECT` | 100 | Allowed to use the `PROTECT` command
`AKICK` | 100 | Allowed to use the `AKICK` command
`STATUS` | 100 | Allowed to use the `STATUS` command
`SET` | (**) | Allowed to use the `SET` and `UNSET` commands
`CLEAR` | (**) | Allowed to use the `CLEAR` command
Other privileges
`MEMO` | 100 | Allowed to read and delete channel memos (see section 3-3-2)

(*) Only on supporting IRC servers
(**) Founder only

Table 3-1. Channel privileges and default minimum access levels

Automatic modes

The most common use of access lists is to make Services automatically give certain users channel operator or some other status when they enter the channel. For example, by adding a user to the access list at level 50 (or above), that user will always gain channel operator privileges when they enter the channel, even if they are not the first user in the channel. Adding a user at level 30 (auto-voice) could be useful on moderated (mode `+m`) channels to allow a user to speak freely on the channel without giving them ops. Note that a user at level 50 or above does not get mode `+v`, because channel operator privilege implies voice privilege as well.

The remaining privileges, auto-halfop (level 40) and auto-protect (level 100), apply only to IRC servers that have those modes (`+h` and `+a` respectively), and cause users at or above those levels to be given the respective modes automatically on joining. As with `+o` and `+v`, a user at level 40 (`+h`) will not get `+v`, and a user at level 50 (`+o`) will not get `+h`. Channel protection (`+a`), however, is a separate status, and is given in addition to `+o` rather than instead of it.

Conversely, a user with a negative access level (-1 or less) will not be allowed channel operator or halfop privileges; even if another channel operator sets mode `+o` on such a user, Services will immediately remove it. Furthermore, users with level -100 or less will not be permitted to join the channel at all, and Services will kick and ban such users if they try to join. Note that this behavior is handled separately from the above privileges, and cannot be modified except with the `SET SECUREOPS` and `SET RESTRICTED` commands, discussed below.

Privileged commands

A number of ChanServ commands are available only to users with certain privileges; these are listed below.

The `VOICE`, `HALFOP`, `OP`, and `PROTECT` commands, as well as their negative counterparts `DEVOICE`, `DEHALFOP`, `DEOP`, and `DEPROTECT`, are the manual equivalents of the automatic-mode privilege levels, and each can be used only by users who would normally get the given automatic mode (or a better one). For example, a user at level 50 (auto-op) can use the `VOICE`, `HALFOP`, and `OP` commands, but not the `PROTECT` command. As with automatic modes, `HALFOP` / `DEHALFOP` and `PROTECT` / `DEPROTECT` are only available on IRC servers supporting those modes. Also, a channel option is available (`SET OPNOTICE`) which causes Services to send a message to the channel every time one of these commands is used.

The `ACCESS` command is used to modify or view the channel access list, and is discussed below. Note that this command has two separate privileges associated with it: `ACC-LIST`, for displaying the access list (think of this as "read-only" privilege for the list), and `ACC-CHANGE`, for modifying it ("read-write").

The `INVITE` and `UNBAN` commands can be used by users with sufficient privilege to circumvent restrictions on entering a channel. `INVITE` is used to cause Services to "invite" you to the channel, as if a channel operator had used the `/invite` IRC command, and is particularly useful when mode `+i` is locked on (with `SET MLOCK`). `UNBAN` causes Services to remove any bans on the channel which prevent you from entering.

The `KICK` and `TOPIC` commands do the same thing as their IRC equivalents, `/kick` and `/topic`. The latter command, `TOPIC`, is particularly useful in combination with the `TOPICLOCK` channel option (set with `SET TOPICLOCK`), which prevents users from changing the channel topic except via the `TOPIC` command.

The `STATUS` command allows a user to check the access level of another user on the channel.

Access-list-related channel options

Aside from the `OPNOTICE` and `TOPICLOCK` options mentioned above, several other options relating to channel access lists are available.

Services does not normally take any particular action for automatic modes after a user has joined the channel; thus, for example, an auto-op user may be deopped by another channel operator (or they may deop themselves) and Services will do nothing. By setting the "enforce" option with `SET ENFORCE`, Services can be made to watch for such improper mode changes and reverse them if they occur.

At the other end of the spectrum, the leave-ops option (`SET LEAVEOPS`) tells Services to not deop the first user that joins a channel (such a user is automatically given ops by the IRC server). This can be useful if a channel is registered simply to save the channel topic and modes or establish an autokick list, and control of channel operator and voice privileges is not needed.

As mentioned earlier, users not on the access list are assigned an access level of 0. Ordinarily, this means only that the users do not have any special privileges and are essentially ignored by Services; however, two channel options allow this behavior to be changed. `SET SECUREOPS` prevents users not on the access list from being opped by other users, as with users with negative access levels; `SET RESTRICTED` prevents such users from joining the channel at all, and will kick and ban them if they try.

Modifying the access list

Services provides two methods for modifying a channel's access list: the `ACCESS` command, provided by the `chanserv/access-levels` module, and the `SOP` / `AOP` / `HOP` / `VOP` command set (often referred to collectively as `XOP`), provided by the `chanserv/access-xop` module. (Thus, at least one of these two modules must be loaded for access lists to be usable!) The `ACCESS` command allows the access list to be viewed or modified using access level values directly, while the `XOP` commands provide a simpler interface with four levels of access.

Both the `ACCESS` command and the `XOP` command set share the same subcommands: `ADD` to add a user (nickname) to the access list, `DEL` to remove a user from the list, `LIST` to display all or part of the list, and `COUNT` to display the number of entries in the list. When a nickname is added to the access list, all nicknames in the same group (see section 3-1-2 on nickname linking) receive the same privileges; the nickname displayed when using the `LIST` command is the one marked as the "main nickname" for the group (set using the NickServ `SET MAINNICK` command).

Both of these methods operate internally on the same list of nicknames and access levels, and in fact both can be used simultaneously (with certain exceptions discussed later). The difference in the two methods is how access list entries are managed from the user's standpoint.

The `ACCESS` command provides direct access to the list of nicknames and access levels that comprise the channel access list. For example, a command like "`ACCESS #somechannel ADD SomeNick 50`" could be used to add the nickname "SomeNick" to the access list of channel "#somechannel" at level 50 (auto-op). The `ADD` subcommand can also be used to change the level of a user already on the list without having to remove them from the list first. When adding a new user to the access list or changing the access level of a user already on the list, the level given to the `ADD` command must be strictly less than the access level of the user giving the command; when removing a user or changing a user's access level, the current access level of the user being removed or changed must also be less than that of the user giving the command. The founder of a channel is treated as having an access level higher than any other user on that channel.

The `XOP` command set, on the other hand, treats the access list as four (three, on IRC servers not supporting halfops) separate lists, each managed by its own command:

- `SOP` (level 100), for the "super-op" list (auto-op, auto-protect on supporting servers, and access to the `AKICK` command);
- `AOP` (level 50), for the auto-op list (auto-op and access to most privileged channel commands);
- `HOP` (level 40), for the auto-halfop list (only available on servers supporting halfops); and
- `VOP` (level 30), for the auto-voice list.

This system, which is based roughly on the system employed by DALnet [`www.dal.net`] Services and other Services-like programs, hides the numeric access levels from the user, providing them instead with a small set of distinct levels for easy control. Since the name of the command directly indicates the access level, there is no need for the user to explicitly give an access level with the `ADD` subcommand. As with the `ACCESS` command, users can only add users to or remove users from lists at a lower access level than their own; for example, a user on the `AOP` list can only modify the `HOP` and `VOP` lists.

Note that since the `XOP` command set operates internally on a single access list, attempting to add a user to one `XOP` list when that user is already on another such list is treated as a change of access level, as with the `ACCESS ADD` command; the command will fail if the user being added is already on the same or a higher list than the user giving the command, and if the command succeeds, the target user will be removed from the list they were previously on. Also note that users added to the access list with the `ACCESS ADD` command at a level other than the four access levels given above (100, 50, 40, or 30) will be invisible to the `XOP` commands.

Changing the minimum access levels for privileges

Experienced users may want to change the minimum access levels required for certain privileges; for example, one could set the `AUTOVOICE` privilege to have a minimum level of zero, meaning that users not on the access list will automatically get mode `+v` upon entering the channel. This can be accomplished through the `LEVELS` command, provided by the `chanserv/access-levels` module (which also provides the `ACCESS` command).

The `LEVELS` command has four primary subcommands. `SET` takes a privilege name (from the "name" column in Table 3-2) and access level, and sets the minimum access level for that privilege to the given level. `DISABLE` (which may be abbreviated to `DIS`) disables a privilege; for automatic mode privileges, this means that no users get the mode regardless of their access level, and for command privileges, it means that only the founder is permitted to use the command in question. `RESET` resets all privileges to their default levels, and `LIST` displays the minimum access level for each privilege on the channel.

There is one important thing to remember when using the `LEVELS` command in combination with the `XOP` command set: Since the `XOP` commands always use the same fixed access levels (100, 50, 40, and 30), changing the automatic mode levels, in particular, can have unexpected effects! For example, if the auto-op level is raised to 75, then users on the `AOP` (supposedly "auto-op") list will not get ops when they enter the channel. In general, it is not a good idea to use both the `LEVELS` and `XOP` commands on the same channel.

Back to top

#### 3-2-3. Miscellaneous functions

One additional ChanServ module is available: the `chanserv/sendpass` module, which provides a `SENDPASS` command similar to the NickServ command of the same name. See section 3-1-5 for additional discussion.

Back to top

### 3-3. Memo sending (MemoServ)

#### 3-3-1. MemoServ core features

"Memos" are short messages which can be sent to users even if they are not online, and will be stored by Services for the recipient to read later. Memos are handled by the "MemoServ" pseudoclient, which functions in the same way as NickServ and ChanServ. (The nickname can be changed via the `MemoServName` option in `modules.conf`.) To avoid potential problems with anonymous memo flooding and other issues, as well as simplify memo storage, MemoServ requires a user to register and identify for their nickname before sending or receiving memos or performing other memo-related operations. If a user has two or more nicknames linked together into a group, then all of those nicknames share the same set of memos, and memos to one nickname in the group can be read using another one.

Sending a memo to another user is accomplished via the `SEND` command. When you send a memo to a user, it will be stored in Services' database, ready for the recipient to read the next time they connect. If the recipient happens to be online (and identified for their nickname) at the time the memo is sent, they will receive a notice that a memo has been sent to them; if the `MSNotifyAll` option is set in `modules.conf`, then all identified users of linked nicknames will likewise receive notices about the new memo.

When a user receives a memo, they can use the `READ` command to view its contents. This command displays the text of the memo whose number is given with the command (the string "`LAST`" can be used to mean "the last memo received", or "`NEW`" to mean "all unread memos"), as well as the nickname of the user who sent it and the date and time it was sent. It is also possible to read multiple memos at once, by separating the numbers with commas (for individual memos) or hyphens (for ranges of memos); for example, "`READ 2-4,7-9`" causes memos 2, 3, 4, 7, 8, and 9 to be displayed.

If a user has several new memos, or wants to look for an old memo, it is usually easier to get a one-line-per-memo list of memos; this is accomplished with the `LIST` command, which displays the sender's nickname and time sent for each memo requested. This command can take either a single memo number, a list or range of numbers, the string "`NEW`" for all new memos, or nothing at all to list every saved memo.

Once a memo has been read, it typically is not needed any more, and can be deleted. In fact, since a single nickname group can only receive a limited number of memos (20 by default, changeable via the `MSMaxMemos` option in `modules.conf`), deleting unused memos is important to make room for new ones. This is done with the `DEL` command, which takes as a parameter a single memo number or list of numbers, or the string "`ALL`" to delete every stored memo. Be aware that deletion is an irreversible operation: once memos are deleted, there is no way to get them back!

If the `MSExpire` option is set in `modules.conf`, then memos will be automatically deleted after the period of time given with that option even if they are not explicitly deleted with the `DEL` command (unread memos will not be automatically deleted unless the `MSExpireUnread` option is also set). However, the `SAVE` command is available to mark certain memos as non-expiring. Once a memo is so marked, it remains that way until the `DEL` command is used to delete it, and will never be automatically deleted.

Normally, users will be notified when they connect to the network of any new memos, and will also be notified when they receive new memos, as described above. This behavior can be altered using the `SET NOTIFY` command. Users can also set a limit on the number of memos they can receive between 0 (which prevents the user from receiving any memos at all) and the default limit using the `SET LIMIT` command.

However, the `SET LIMIT` command is more intended for Services administrators (see section 3-4-1), who can use it to allow a nickname to receive an unlimited number of memos ("`SET LIMIT nickname NONE`") or to prevent a user from changing their own limit ("`SET LIMIT nickname 0 HARD`" to enforce a limit of 0, i.e. prevent receipt of memos).

Finally, the `INFO` command can be used to display a user's number of stored and unread memos, memo limit, and notification options. Ordinary users can only use this command for their own nick, while Services administrators can view memo information for any nick ("`INFO nickname`").

Back to top

#### 3-3-2. Memos and channels

While MemoServ is typically used to send messages from one user (nickname) to another, it can also be used to leave messages for a channel instead. In this case, the memo is stored with the channel, and any user with the `MEMO` privilege on the channel (see section 3-2-2) can read or delete the memo. The channel must be registered in order to receive memos.

When sending the memo, simply replacing the target nickname with a channel name is sufficient to send the memo. However, the remaining commands (`READ`, `DEL` and so on) do not normally allow users to operate on memos other than those of their own nickname. For these commands, the channel name is inserted immediately after the command name; for example, "`LIST #channel NEW`" or "`DEL #channel ALL`".

Currently, there is no facility for notifying users of new memos in channels. Thus, channel founders and other privileged channel users should periodically use the `INFO` or `LIST` commands to check for channel memos if they expect to receive any.

Back to top

#### 3-3-3. Memo ignore lists

Users may, on occasion, want to avoid receiving memos from certain other users, such as in cases of harrassment. The `memoserv/ignore` module allows users to do exactly that, by maintaining an ignore list of wildcard masks (which can be either nickname or `user@host` masks) from which memos should not be received. When a memo is sent to the user, Services compares the nickname and `user@host` address of the sender to each entry on the recipient's ignore list; if a match is found, Services will refuse to send the memo, informing the sender that the recipient is "not allowed to receive memos" (using the same message sent when the recipient has used the `SET LIMIT 0` command to prevent receipt of any memos at all; this way, the sender cannot tell directly whether the user is refusing all memos or only memos from that particular nickname or address).

The `IGNORE` command is used to manage the ignore list. It has three subcommands: `ADD` to add a mask to the ignore list, `DEL` to delete a mask, and `LIST` to display all masks on the list.

Back to top

#### 3-3-4. Memo forwarding

Some users may find it easier to have their memos forwarded directly to their E-mail address rather than connecting to IRC to check them. The `memoserv/forward` module allows users to select this behavior for their nicknames, and will convert each memo to the user into an E-mail message sent to the E-mail address registered with the nickname. (To prevent spamming, this module requires that nickname E-mail authorization be active; see section 3-1-3 for details.)

When this module is loaded, users can use the `SET FORWARD` command to select whether to have their memos forwarded to their E-mail address. This option can be set to either "`ON`" (forward memos via E-mail), "`OFF`" (do not forward), or "`COPY`" (forward memos but also store a copy in the Services database). When set to `COPY`, the limit on the number of stored memos per nickname group applies to E-mail as well: if the limit is reached, all further memos will be refused, even though they could potentially have been sent via E-mail. In such a case, the user must connect to IRC and delete unneeded memos before being allowed to receive more, just as if the `FORWARD` option was set to `OFF`.

Additionally, a separate `FORWARD` command is available which allows users to selectively forward memos to their E-mail address. This can be useful, for example, to save certain messages in a more permanent form without having every single memo sent to one's mailbox.

Back to top

### 3-4. Network/Services control and maintenance (OperServ)

#### 3-4-1. Services privilege levels

Before discussing OperServ's functions, it is necessary to understand the concept of Services privilege levels. These are privilege levels assigned to IRC operators which are used by both OperServ and other parts of Services to limit access to certain functions. There are four different Services privilege levels a user can have:

- No privilege
- Services operator privilege
- Services administrator privilege
- Services super-user privilege

By default, all users have no special privileges.

Services operator (also known as "services oper" or "servoper") privilege allows IRC operators to change modes on or kick users from any channel or "mass-kill" users sharing the same hostname (clones, for example), as well as modify the autokill, session exception, and S-line lists when the relevant modules are in use, and is intended for IRC operators who can be trusted not to run wild on the network. The `OPER` command is used to change or view the list of users with Services operator status.

Services administrator (also known as "services admin" or "servadmin") privilege allows IRC operators control of Services itself; Services administrators can set various Services options, rehash (re-read) the configuration files and update settings, and restart or terminate Services entirely. Services administrator privilege is also needed to modify the Services operator list or to gain Services super-user privilege (see below). The `ADMIN` command is used to change or view the list of users with Services administrator status. Note that giving a user Services administrator status will cause them to be removed from the Services operator list if they are on it; users on the Services administrator list must first be removed from that list before they can be added to the Services operator list, thus preventing one Services administrator from downgrading another's privilege level by making them a Services operator.

Services super-user (also known as "Services root", after the Unix super-user username `root`) privilege is the highest Services privilege level available, and is required for modifying the Services administrator list. It also allows the use of the dangerous `RAW` command, which sends text directly to the IRC network without intervention by Services, if the `AllowRaw` option is set in `modules.conf`; this can be useful for testing new features of an IRC server, but improper use can cause Services and other servers on the network to behave improperly or even crash. Normally, only the nickname given with the `ServicesRoot` configuration directive in `modules.conf` has Services super-user privilege, but if that user sets a super-user password with the `SET SUPASS` command, Services administrators can obtain temporary Services super-user privilege by giving that password with the `SU` command.

Back to top

#### 3-4-2. Core OperServ features

This section discusses the core features provided by OperServ (in the `operserv/main` module). It is split into four subsections by Services privilege level:

- Commands for all IRC operators
- Commands limited to Services operators
- Commands limited to Services administrators
- Commands limited to the Services super-user

An IRC operator with a certain Services privilege level also has access to commands for lower privilege levels; for example, a Services administrator has access to Services operator commands as well, and a user with Services super-user privilege can use every OperServ command. If a user who is not an IRC operator sends a command to OperServ, it will be refused regardless of content, and (if the `WallBadOS` option is set in `modules.conf`) a message will be broadcast to all online IRC operators.

Note that all commands sent to OperServ are recorded in the Services log file (with the exception of passwords given for the `SU` and `SET SUPASS` commands, discussed later), so be careful of what you type!

Commands for all IRC operators

IRC operators without any Services privileges are primarily limited to commands for displaying the current status of Services and the IRC network. These commands include `STATS` command, which displays the time elapsed since Services was started and current/maximum number of users and IRC operators, and the `SERVERMAP` command, which displays the IRC network's topology from the viewpoint of Services. Another command, `GLOBAL`, allows a notice to be sent to all users on the IRC network.

Additionally, the `ADMIN` and `OPER` commands can be used by any IRC operator to view the current list of Services administrators and operators, respectively (the `LIST` subcommand). However, Services will not permit any changes to either of these lists from a user without the necessary privileges.

Commands limited to Services operators

In addition to the commands usable by all IRC operators, Services operators have access to commands which can be used to maintain stability and resolve problems in the IRC network. Four of these commands—`MODE`, `CLEARMODES`, `KICK`, and `CLEARCHAN`—allow control of channel modes as well as providing the ability to remove a user (or all users) from a channel. The last Services operator-specific command, `KILLCLONES`, allows quick resolution to "clone" problems, where many clients connect to the IRC network at once from the same address; this command causes all clients with the same address as the nickname given to the command to be immediately disconnected, and will also add a temporary autokill (if autokill support is enabled) to prevent the clients from immediately reconnecting.

Commands limited to Services administrators

Services administrators have access to commands which control Services itself. One of these is the `SET` command, which allows various Services options to be set: `READONLY`, which controls whether Services allows changes to be made to its database, and `DEBUG`, which controls whether and how much debugging information is written to the log file. (The third `SET` option, `SUPASS`, is restricted to users with Services super-user privileges.) Services admins can also force Services to update the on-disk copies of its databases with the `UPDATE` command, make Services re-read its configuration file with the `REHASH` command, and shut down or restart Services with the `SHUTDOWN`, `QUIT`, and `RESTART` commands.

With respect to the IRC network, Services administrators can use the `JUPE` command to "jupiter" a server—that is, to make Services create a fake server with a particular name to prevent a real server of the same name from connecting. This can be useful if a server on your network is broken (or hacked into) and causes problems for other servers on the network.

Finally, if the Services super-user has set a super-user password with the `SET SUPASS` command, Services administrators can use that password with the `SU` command to gain super-user privileges.

Commands limited to the Services super-user

The Services super-user privilege level is similar to the Services administrator level; it primarily exists to allow modification of the Services administrator list (with the `ADMIN` command) and setting of the super-user password (with the `SET SUPASS`). However, one other command is limited to the Services super-user (or Services administrators with super-user privilege): the `RAW` command, which allows any arbitrary data to be sent directly to the server to which Services is connected. This can be used to achieve certain kinds of "special effects" or to aid in development or debugging of an IRC server or Services module. As mentioned earlier, however, this command is very dangerous, and improper use can easily cause Services or your network's IRC servers (or both) to crash or corrupt data. For this reason, the `RAW` command is unavailable unless the `AllowRaw` option is set in `modules.conf` (it is disabled by default).

Additionally, certain debugging commands are available to the Services super-user if enabled in the `Makefile`. These commands are not documented; see the source code (`modules/operserv/main.c`) for information.

Back to top

#### 3-4-3. Autokills and S-lines

Just about any network will have its share of troublemakers or other "unwanted" users. IRC servers have always provided a method—"K-lines", so named because the lines in the configuration file defining them begin with the letter "`K`"—of preventing these users from connecting to the network. The problem with these, however, is that they only affect the server on which they are defined; to prevent a user from connecting to the network at all, every server has to add the appropriate K-lines for that user. Additionally, K-lines can only be used to block username/hostname combinations; in some circumstances it may be desirable to block users based on nickname, "real name", or IP address.

The former problem, of keeping K-lines synchronized across servers, is solved by Services' autokill feature, provided by the `operserv/akill` module. This module keeps a list of K-lines (i.e., username/hostname wildcard masks) which should be maintained across all servers, and if a user matching any such mask attempts to connect to the network, Services will automatically issue a `KILL` message for that user, removing them from the network (hence the name "autokill"). Some servers support a feature which allows Services to dynamically update K-lines for all servers, and Services takes advantage of this as well.

The latter problem, of blocking users based on things other than their username and hostname, is handled by the S-line feature, provided by the `operserv/sline` module. There are three varieties of S-line:

- SGline, which matches against a user's "real name" (also called "gecos", hence the "G");
- SQline, which matches against a user's nickname (the "Q" comes from "quarantine", and some servers support "Q-lines" in configuration files to ban certain nicknames from being used on that server); and
- SZline, which matches against a user's IP address (the "Z" comes from "zap", and some servers support "Z-lines" in configuration files).

As with autokills, Services will automatically issue a `KILL` message for any user which matches any of these masks, with two exceptions. For SQlines, if the IRC server in use supports forced nick changing and if `SQlineKill` is not set in `modules.conf`, Services will not kill the user, but rather change the user's nickname to a "guest" nickname, and also send an error message which will cause the client to force the user to choose a different nickname. IRC operators can be exempted from the SQline check by setting the `SQlineIgnoreOpers` option in `modules.conf`. Also, some servers do not provide IP address information, and thus Services will be unable to check SZlines on these servers; in this case, Services will issue a warning and SZlines will be disabled. (Some servers allow SZlines to be set by Services on each server, and in this case SZlines can still be used if the `ImmediatelySendSline` option is set in `modules.conf`.)

Since the autokill and S-line features are virtually identical, only the autokill feature will be described in detail here; see the documentation for the `SGLINE`, `SQLINE`, and `SZLINE` commands and the `operserv/sline` section of `modules.conf` for details on S-line usage.

How autokills work

When a user connects to the IRC network, the server to which the user connected will forward information about that user, including the user's username and hostname, to Services along with the other IRC servers on the network. When Services receives this information, it joins the username and hostname with an at-sign character to form a `username@hostname` string. This string is then compared against each mask in the autokill list. If a match is found, Services issues a `KILL` message for the user, causing the user to be disconnected from the network; the text used in the `KILL` message can be set with the `AutokillReason` option in `modules.conf`. Additionally, for servers supporting a "network K-line" mechanism, which includes every supported server except for classic RFC1459 and TS8-based servers, Services will send out a K-line for the username and hostname which the user matched; this directs the servers to immediately disconnect any user matching that username and hostname mask. (If more than one autokill mask matches, then the first one found will be used.)

Autokills can be set to expire (be automatically deleted) after a certain length of time. This length of time is set by the `AutokillExpiry` configuration option in `modules.conf`, and is set to 30 days in the example `modules.conf` file distributed with Services. After this length of time, Services will remove the mask from the autokill list, allowing users matching the mask to connect again; if the `WallAutokillExpire` configuration option is set, Services will inform all IRC operators when this occurs. For servers with a "network K-line" mechanism, K-lines corresponding to a mask will automatically be removed when it expires (or is explicitly deleted). The length of time before expiration can also be set for each individual autokill mask, as described below.

Using the `AKILL` command

The `AKILL` command, available only to Services operators, is used to manage the autokill list. It has five subcommands:

- `ADD`, to add a mask to the autokill list;
- `DEL`, to remove a mask from the autokill list;
- `LIST`, to list all masks on the autokill list;
- `VIEW`, to give detailed information about masks on the autokill list; and
- `COUNT`, to show the number of masks on the autokill list.

Autokill masks take the form `user@host`—note that nicknames are not used. (S-lines use different formats; see the relevant command documentation.) When adding a mask to the autokill list, you must also include a reason for it; this allows other Services operators (or you, if you later forget) to know why the mask was added. The reason is shown in the response to a `LIST` or `VIEW` command.

Autokills expire by default after the amount of time specified in the `AutokillExpiry` option in `modules.conf`. A particular autokill can be set to expire in a different amount of time, or to not expire at all, by including the desired expiration time in the `ADD` command, as described in the `AKILL` command documentation. It is also possible to place an upper limit on expiration times set by Services operators (as opposed to Services administrators), using the `OperMaxExpiry` option in `modules.conf`; if this is set, Services operators will not be allowed to set autokills that last longer than the given period of time (which includes non-expiring autokills).

The difference between the `LIST` and `VIEW` subcommands is their verbosity. `LIST` displays each autokill mask on one line, showing only the mask and the reason (note that if the mask or reason is long, this may be wrapped onto multiple lines by your IRC client). `VIEW`, on the other hand, uses two lines (again possibly wrapped) for each mask, displaying the nickname of the person who added it, the date and time it was added, the last time it was used (if at all), and when it expires, in addition to the mask itself and reason. The last-used time is helpful when determining whether an autokill mask is still needed; it shows the last time a user who matched the mask connected to the network. However, this may not be accurate if your IRC servers support a server-based autokill mechanism; such servers will block the user from connecting without informing Services, so the last-used time will show only the first time a matching user connected. (If the `ImmediatelySendAutokill` option in `modules.conf` is enabled, the last-used time will never be set at all on these servers.)

Autokill exclusions

(Note: this section applies to autokills only; S-lines do not have exclusion capability.)

It is also possible to add "anti-autokill" masks—that is, masks for users that should be allowed to connect even if they match an autokill. These are known as autokill exclusions, and are enabled with the `EnableExclude` option in `modules.conf`. The autokill exclusion list is managed with the `EXCLUDE` command, which functions in much the same way as the `AKILL` command described above.

When autokill exclusions are in use, Services will first check the exclusion list for each user connecting to the network. If a matching mask is found on the exclusion list, Services allows that user to connect, skipping the ordinary check of the autokill list for that user. For example, if an autokill was placed on `*@*.example.com`, but one of the IRC operators for a server on the network connected from the host `foo.example.com`, an autokill exception for `*@foo.example.com` would allow that user to connect, while still preventing any other users in the `example.com` domain from connecting.

One important side effect of autokill exclusions should be considered before enabling them. If the IRC server in use supports server-based autokills, then ordinarily Services will take advantage of it to prevent users matching autokills from connecting to the network on the server end. However, if the servers do not support server-based autokill exclusions (currently, the only supported servers which have this ability are the Unreal 3.2 and trircd IRC servers), then Services will not be able to use server-based autokills either—if it did, the servers would block users on the exclusion list as well without Services being able to intervene—and will fall back to the default method of sending a `KILL` message for each user matching an autokill mask (and no exclusion mask) that connects. This results in somewhat more traffic on the IRC network, as well as the potential for autokilled users to send messages before getting killed if there is enough lag between Services and the server the user connected to.

Back to top

#### 3-4-4. Session limiting

One other way of preventing undesired clients from connecting to the network is via session limiting, provided by the `operserv/sessions` module. When session limiting is active (i.e., the module is loaded), Services will keep track of the number of clients connected from each host, and issue `KILL` messages for any clients exceeding the limit set by the `DefSessionLimit` configuration option in `modules.conf` (or specific limits for the host as set by session exceptions, described below). Before actually disconnecting the client, Services can be configured to send notices with the `SessionLimitExceeded` and `SessionLimitDetailsLoc` configuration options.

If the autokill module (see section 3-4-3) is loaded, Services can also add an autokill if a particular host's session limit is exceeded frequently in a short period of time. This is controlled by the `SessionLimitAutokill` configuration directive, which allows precise definitions of "frequently" and "short", as well as the expiration time for such autokills.

Session exceptions are managed through the `EXCEPTION` command. This command functions similarly to the `AKILL` (autokill management) command, with the exception that when adding session exceptions, you need to include the limit (the maximum number of clients to allow) in the command; an upper bound can be set on this value with the `MaxSessionLimit` option. As with autokills, exceptions can be set to expire after a certain amount of time (`ExceptionExpiry`), and Services can be set to inform IRC operators when an exception is added or deleted (`WallOSException`) or expires (`WallExceptionExpire`),

Back to top

#### 3-4-5. News

The `operserv/news` module provides a simple "news" service to allow messages to be automatically sent to all users when logging onto the network, or to IRC operators when they give the `/oper` command. News items are added and deleted through the `LOGONNEWS` and `OPERNEWS` commands, respectively. For each set, the most recent three items (or all the items, if there are three or less) are displayed.

Back to top

### 3-5. Network statistics collection (StatServ)

IRC Services provides a simple network statistics collection service, accessible through the "StatServ" pseudoclient. Currently, StatServ tracks the last time each server on the network connected and disconnected, and the number of users on each server as well as the total number of users on the network. Normally all users have access to this information, but use of StatServ can be limited to IRC operators only by setting the `SSOpersOnly` option in `modules.conf`.

Server information is accessed through the `SERVERS` command. StatServ can display information on all servers or only online or offline servers, including the last connect and disconnect time, the current number of users and IRC operators, and the respective percentages of the total number of users and IRC operators on the network. Additionally, Services administrators can copy, rename, or delete server entries to keep the data up-to-date with respect to network changes.

The `USERS` command can be used to display the current number of users and IRC operators on the network, as well as the average number of users and operators per server.

Back to top

### 3-6. Built-in HTTP server

Aside from interacting directly with the IRC network, Services is also capable of providing information to World Wide Web clients (browsers) via the HTTP protocol. While this functionality is not nearly as extensive as full-fledged HTTP servers such as Apache, it does provide the ability to access current information on Services and the IRC network without having to go through a CGI or other external program.

Services' HTTP server functionality is comprised of three parts: the core HTTP server module, authorization modules, and content modules. These are discussed in the following sections.

#### 3-6-1. Core HTTP server module

The core HTTP server module, `httpd/main`, provides the foundation for the other HTTP modules, including the ability to listen for and parse HTTP requests. This module is akin to, although considerably less full-featured than, a typical standalone HTTP server (`httpd`).

The HTTP server's behavior is defined by settings in the `modules.conf` file. The most important of these, `ListenTo`, specifies the IP address and port number on which the HTTP server listens for connections; it is possible to specify multiple addresses, which will cause Services to listen for connections on all of them. The port number can be any port which is not already used by another service on the same machine, although using ports under 1024 normally requires super-user privileges. The IP address can be specified as "`*`" in the simplest case; this means "listen for connections on any IP address". However, if you are using a machine with multiple IP addresses, you may need to enter a specific IP address to avoid collisions with services listening on other IP addresses. You may also choose to only allow connections from clients on the same machine by specifying the "`localhost`" address, `127.0.0.1`; the same sort of access control can also be performed on a per-resource basis using the `httpd/auth-ip` authorization module, discussed later, but if you want to limit all resources to the local machine, this method is safer and more efficient.

It is also possible to use a hostname in place of the IP address; in this case, Services will look up the hostname at startup and use the IP address found (all addresses, if more than one is found) as the address to listen to. However, these addresses will not change even if the hostname's DNS information changes, unless Services is restarted or instructed to reread the configuration files (see section 2-5).

The number of connections allowed at once and the length of time a single connection can remain open are set by the `MaxConnections`, `MaxRequests`, and `IdleTimeout` directives. `MaxConnections` sets the maximum number of simultaneous connections Services will accept; any connections above this limit will be dropped as soon as they are accepted. `MaxRequests` sets the maximum number of HTTP requests that can be sent over a single connection, while `IdleTimeout` gives the maximum length of time a connection can be idle (i.e., not receiving any data from the client); if either of these limits are passed, the connection is dropped. (Note that some resources cause the connection to be dropped after the server finishes sending data, regardless of these settings.)

If the `LogConnections` directive is given, the HTTP server will write a log message to the Services log file for each connection accepted. Note that the resource (URL) requested is not logged, and only one message is written per connection, even if several HTTP requests are made over the same connection. (If per-request logging is desired, `MaxRequests` can be set to 1 to force clients to open a new connection for each request.)

The remaining settings, `ListenBacklog` and `RequestBufferSize`, can usually be left as is. `ListenBacklog` specifies how many connections the OS should allow to be made to a single HTTP server port without being accepted by Services, a situation which can arise if the HTTP server is under heavy load and requests come in faster than Services can process them. (However, some operating systems do not allow a value greater than the default of 5; on such systems, increasing the value will not cause an error but will have no effect.) `RequestBufferSize` specifies the size of the receive buffer allocated for each request; if a request exceeds this size, the client will be sent a "Request Entity Too Large" error and the connection will be dropped. There should be no need to modify this value for the modules currently distributed with Services.

Note that the `RequestBufferSize` setting only affects the size of the receive buffer itself; in addition to this buffer, a fixed-size control structure and a list of headers and form variables are also allocated. In the worst case, the latter will require approximately 4/3 of the value given for `RequestBufferSize`. Thus, the maximum amount of memory used by the HTTP server module can be calculated as approximately

> `MaxConnections * RequestBufferSize * 2.5`

Back to top

#### 3-6-2. Authorization modules

Since it may not be desirable to allow anyone access to the resources provided by the HTTP server, Services provides "authorization modules", whose names start with "`auth-`", to control access to those resources.

Control by client IP address: the `httpd/auth-ip` module

The `httpd/auth-ip` module allows access control based on the IP address of the connecting client. The module uses two configuration directives, `AllowHost` and `DenyHost`, to control access to particular resources (URLs). Both directives take two parameters: the resource to control access to, and the IP address or hostname to allow or deny access from.

The first parameter, the resource to control access to, consists of a relative URL beginning with the `/` character; i.e., not including the leading "`http://host.name`" typed into the browser. Services will control access as specified by the directive to this resource, and to any resource whose URL begins with the same string; for example, giving "/dir" as the resource to control will affect not only "/dir/file" but "/dirty" as well. To limit the directive's effect to a particular directory, make sure to include a "`/`" at the end of the resource URL, e.g., "`/dir/`". Access control can be applied to every resource on the server by using the resource URL "/".

The second parameter, the IP address, is specified much the same as with the core module's `ListenTo` directive: the string "`*`" can be used to mean "all IP addresses", and a hostname will be replaced at startup with the IP address or addresses associated with that hostname. However, one additional type of IP address specification is possible: a network specification of the form `aaa.bbb.ccc.ddd/xx`, where `xx` is an integer from 1 to 31 inclusive that gives the number of bits in the network part of the address. For example, `192.168.1.64/26` represents the range of IP addresses from 192.168.1.64 through 192.168.1.127 (all IP addresses whose upper 26 bits are the same as those in 192.168.1.64).

When specifying multiple control directives, it is important that they are given in the proper order. All `AllowHost` and `DenyHost` directives are checked in the order they are listed in `modules.conf` without regard to specificity of either the IP address or the resource, and the first matching entry found is used; as a result, a more specific entry will have no effect if placed below (after) a more general one. As an example, consider the following pair of directives:

> `AllowHost / 192.168.0.1
> DenyHost / 192.168.0.0/24`

The first one allows access to the entire server from the IP address `192.168.0.1`, while the second denies access from all IP addresses in the `192.168.0.*` network. In the order given, this allows access from only `192.168.0.1` in that network, while preventing all other hosts in the network from connecting. However, if the directives are given in the reverse order:

> `DenyHost / 192.168.0.0/24
> AllowHost / 192.168.0.1`

then clients from `192.168.0.1` will be blocked along with the rest of the `192.168.0.*` network, because the first directive tells Services to deny access to `192.168.0.1` as well as other hosts on that network, so the second directive is never checked.

The list of directives should always end with either "`AllowHost / *`" or "`DenyHost / *`" to control whether requests which do not match any other directive should be allowed or denied. In the current version of Services, requests that do not match any directive will be allowed by default, but this behavior may change in future versions; to ensure the same behavior across upgrades, always include one of these two directives at the end of the access control list.

Control by password: the `httpd/auth-password` module

It is also possible to control access by requiring the client to enter a username and password to access a particular resource. This is accomplished using the `httpd/auth-password` module. Like the `httpd/auth-ip` module, access is controlled by a list of directives; for this module, the directive name is `Protect`, and the second parameter is a username and password pair with the username and password separated by a colon (e.g., "`username:password`"). Additionally, the `AuthName` directive specifies the name used by the HTTP client in password prompts, such as "Enter username and password for name:".

Like the `httpd/auth-ip` module, the first `Protect` directive matching a particular request will be used, so specific entries should be placed before general ones. However, it is not necessary to include a `Protect /` directive at the end of the list, unless you want password protection for the entire server; if a request does not match any directives, then it is allowed through without a password (this behavior is not expected to change in future versions).

Back to top

#### 3-6-3. Content modules

The remainder of the HTTP server modules are "content modules", which, as the name suggests, provide the actual content served to browsers.

"Index" page: the `httpd/top-page` module

This simple module allows you to provide an HTML (or other) file to be served when the HTTP server's "top page" (the "`/`" URL) is accessed. Since in a typical setup, other content modules will each have their own sub-path within the HTTP server, this module lets you provide (for example) an index of the information available. The file to serve is given by the `Filename` directive in `modules.conf`; the file's MIME type can optionally be specified as well.

It is also possible to specify a URL to a remote site (which could be a separate HTTP server on the same machine) for the top page, using the `Redirect` directive; in this case, Services will redirect top-page accesses to the given URL. If both `Redirect` and `Filename` are given, `Redirect` takes precedence, and `Filename` is ignored.

Note that with `Filename`, the file specified is served as-is; Services will not attempt to execute it even if it looks like a CGI script, and cannot process PHP or other such languages embedded in the file.

Providing links to nickname and channel URLs: the `httpd/redirect` module

The `httpd/redirect` module can be used to provide automatic redirects from a nickname or channel to the URL (if any) registered for the nickname or channel. This can be used as a simple way to let your users provide information about themselves without requiring the viewer to log onto IRC and execute a NickServ or ChanServ `INFO` command.

Nickname and channel redirects each use a base URL specified in `modules.conf`: `NicknamePrefix` for nicknames, and `ChannelPrefix` for channels. The nickname or channel whose URL is used is the string immediately following the given prefix (in the case of channels, the leading "`#`" is discarded, since it cannot be used in URLs). This means that to get URLs like "`http://services.example.net/channel/channel-name`", the prefix should be specified as "`/channel/`" with a trailing slash, but also allows you to specify "`/~`" for the nickname prefix and get URLs like "`http://services.example.net/~nickname`". (Both of these are the default settings.)

`NicknamePrefix` and `ChannelPrefix` should be specified so that they do not overlap; if a particular URL can be interpreted as both a nickname reference and a channel reference, the nickname will always take precedence, even if it is not registered or does not have a URL associated with it.

Online database access: the `httpd/dbaccess` module

Warning: This module provides complete access to all Services data; unauthorized access can result in password theft, denial of service attacks, or worse. Be certain to protect access to this module with using authorization modules or other means.

The `httpd/dbaccess` module is an administrative tool which allows the Services databases to be accessed through the simple point-and-click interface of a browser rather than the text-based commands of IRC. While the module does not permit the databases to be modified, registered nicknames and channels, autokills and S-lines, and so on can all be accessed and viewed through a simple menu system. Additionally, a copy of all Services data in XML format can be downloaded if the `misc/xml-export` module is loaded (see section 5-1 for details).

Especially when performing an XML download of the Services databases, keep in mind that Services will not respond to any network activity until the HTTP request completes; if you have a slow machine or a large database, this can cause Services to appear to "lag" on the IRC network, or in extreme cases get disconnected from the network entirely, so use caution.

The URL at which the data is accessible is set by the `Prefix` directive in `modules.conf`; if it does not end with a slash, one will be appended automatically. Accessing this URL will bring up a menu of available data. If you want to use different access rules for different categories of data, refer to the following table for the appropriate pathnames (in all cases, `path` is the URL pathname given in the `Prefix` directive):

`path/` | Main menu
`path/operserv/` | OperServ data and menu
`path/operserv/akill/` | Autokill list
`path/operserv/news/` | News item list
`path/operserv/sessions/` | Session and exception lists
`path/operserv/sline/` | S-line lists
`path/nickserv/` | Nickname list and information
`path/chanserv/` | Channel list and information
`path/statserv/` | Network statistics
`path/xml-export/` | XML-format database download

Debugging information: the `httpd/debug` module

The `httpd/debug` module is intended primarily for module developers, and provides information about the HTTP request received by Services at a URL specified by the `DebugURL` directive in `modules.conf`. This module is unneeded and should not be enabled for normal operation of Services.

Back to top

### 3-7. Password encryption

Services has the ability to encrypt passwords (nickname passwords, channel passwords, and the OperServ super-user password) to provide an additional layer of protection against password theft. Normally, passwords are not encrypted, and if an unauthorized user gains access to the databases, users' passwords will be compromised; encryption prevents this compromise from occurring (although it is still possible for an attacker to "crack" the encrypted passwords, especially if the passwords are easily guessable). Note that under the default installation of Services, only the user installing Services and the administrator of the machine Services is installed on will have access to the databases.

The downside to using encryption, although minor, is that (depending on the type of encryption used) the NickServ and ChanServ `GETPASS` commands will become unusable. This is because some types of encryption are one-way only (also known as "trapdoor functions"); such encryption types allow a password to be converted into an encrypted string, but do not allow the password to be recovered from that string.

To enable encryption of passwords, simply load the appropriate encryption module with a `LoadModule` directive in `ircservices.conf`. The available encryption modules are as follows:

- `encryption/md5`: Uses the MD5 hashing algorithm1 to encrypt passwords. This is a one-way encryption algorithm which generates a 128-bit "digest" of the password, and is used by several Unix systems to encrypt user passwords as well.

Other types of encryption will be added in future versions.

1Technically, the "RSA Data Security, Inc. MD5 Message-Digest Algorithm".

Back to top

Table of Contents | Previous section: Installing and using Services | Top | Next section: Services command reference