# IRC Services Manual

## Important information for users upgrading from previous versions of Services

Upgrading from version 4.5 and earlier to 5.0
Upgrading from version 5.0 to 5.1

Note that information for later versions is applicable to earlier versions as well, so please read through to the end of the document.

Table of Contents

## Upgrading from version 4.5 and earlier

### 1. Executable and configuration files

In previous versions of Services, the main executable file (program file) was called "`services`"; in version 5.0 it has been renamed to "`ircservices`" to match the package name. Once you are satisfied that you don't need the old `services` executable file, you should delete it (`make install` will leave it alone).

Also, previous versions of Services (since 4.1.0) used a file called "`services.conf`" to control various aspects of the behavior of Services. Services 5.0 also uses such a file, but it has been renamed to "`ircservices.conf`" and its format has changed from previous versions. In particular, many of the options from previous versions are now module options, and must be placed in a separate file called "`modules.conf`". Please see the manual, and the `example-ircservices.conf` and `example-modules.conf` files in the data directory, for details.

### 2. Running the `configure` script

The `configure` script has been redesigned to require as little input as possible; many of the options that previously required user input during the configuration process have been moved to the `ircservices.conf` file, and the script can now be completely automated if you provide the `-prefix` option or both of the `-bindest` and `-datdest` options to specify the pathnames for installation. Run `configure` with the `-help` option for details on available command-line options.

The `configure` script also now accepts all options in the GNU long-option (two leading hyphens) style, so if you are used to the GNU autoconf-style `configure`, you can now type `./configure --prefix=/usr` (for example) to get the same effect with Services.

### 3. `listnicks` and `listchans`

Earlier versions of Services provided two additional programs, "`listnicks`" and "`listchans`", to show nickname and channel data from the command line. These programs have been removed in version 5.0 in favor of the new HTTP interface; the `httpd/dbaccess` module provides the same functionality and much, much more. (It is still possible to retrieve data from the command line as well, using the `-export` option; see section 5-1 for details.)

### 4. Encrypted passwords

Unlike previous versions of Services, encryption is no longer an "on/off" setting; instead, encryption is enabled by specifying an encryption module in `ircservices.conf`. See the manual (section 3-7) for details.

If you are upgrading from version 4.4.x or earlier, and you use MD5-encrypted passwords, your passwords will no longer work due to a bug in those versions of Services. Support is available in version 4.5 for reading the broken passwords and allowing them to be reset; if you want to give users a chance to change their passwords, you should first upgrade to the most recent 4.5.x release, then when most or all of the users have reset their passwords, upgrade to version 5.0. For details, see the What's New notes for version 4.5.

### 5. Using the `mail-auth` module with existing databases

The `mail-auth` module is a new feature in version 5.0 which allows E-mail addresses to be checked for validity. When enabled, all new nickname registrations and E-mail address changes will require the user to verify that the address provided is valid, by entering an authentication code mailed by Services to the address. However, if you are upgrading from an earlier version of Services, some users may already have entered invalid E-mail addresses for their nicknames.

To correct this situation, the command-line option "`-clear-nick-email`" can be given (note that this option is only valid if NickServ is enabled). When this option is used, Services will clear the E-mail address associated with all registered nicknames; all users will then be required to enter their E-mail address again and verify it with an authentication code before being allowed to identify for their nicknames.

If you intend to use the `mail-auth` module, it is recommended that you use this option once when starting up Services 5.0 for the first time. This option only needs to be specified once to take effect.

### 6. Nickname linking system changes

The nickname linking system used in Services 5.0 is different from that used in previous versions. Rather than a multiple-level "tree" of linked nicknames, nicknames are now organized into groups, and the `LINK` and `UNLINK` commands add nicknames to or remove nicknames from this group. Functionally, there is little difference between this system and using only one level of links in the previous system. However, the `LINK` and `UNLINK` commands work in the opposite direction from version 4.x, taking a nickname parameter and adding or removing that nickname (for example, "`LINK OtherNick`"), and nicknames to be linked must be unregistered nicknames, which is also a change from version 4.x; make sure your users are aware of these changes.

Related to these changes, it is also important to note that the behavior of the NickServ `UNLINK` and `DROP` commands has changed with respect to de-registration of nicknames; in particular, the `DROP` command will now drop all linked nicknames! The syntax for the `DROP` command has changed as well, requiring a password to confirm the action, and the help message includes a warning, but be aware that users may simply append their password to the command without checking the help message, resulting in the unintended de-registration of all of the user's nicks. The `UNLINK` command should be used to cancel single nicknames out of a group of links (a nickname which is unlinked is deregistered as well, similar to `UNLINK` followed by `DROP` in version 4.x).

### 7. Memo expiration

Version 5.0 of Services provides the ability to automatically delete (expire) memos after a certain period of time. Since this feature was not present in previous versions and users may have important information saved in memos, Services will not expire any memos which were sent before upgrading to version 5.0; thus, it is safe to enable memo expiration without having to warn users about loss of saved memos or taking other preventative measures. (However, it would be prudent to inform users that any future memos will expire after a certain period of time, if you choose to enable memo expiration.)

### 8. Channel access levels

Channel access levels have been rescaled in this version of Services to make better use of the available range of values; instead of a range of -9999 through 9999 where only values -2 through 10 are used, the range has been reduced to -999 through 999, and default levels now range from -100 to 100 (all defaults have been increased by a factor of 10, with the exception of `AUTODEOP` and `NOJOIN`, which are no longer changeable in version 5.0 but are fixed internally at -1 and -100 respectively). Level values from version 4.x databases will be properly converted to use the new range, so that all users will still have the same privileges as they did in previous versions. However, be aware that in some cases involving two users with levels outside the range -50 through 50 in version 4.x, if the levels are different but close (e.g. 1001 and 1002), then the users will have the same access level in version 5.0. The exact conversion function is stepwise linear, as follows (negative levels are converted to the negative of the conversion of the absolute value of the level):

Old level (o) | New level (n) | Conversion function
--- | --- | ---
0 | . . . | 25 | 0 | . . . | 250 | n = 10o
25 | . . . | 50 | 250 | . . . | 300 | n = 2o + 200
50 | . . . | 100 | 300 | . . . | 320 | n = 2o/5 + 280
100 | . . . | 1000 | 320 | . . . | 500 | n = o/5 + 300
1000 | . . . | 2000 | 500 | . . . | 600 | n = o/10 + 400
2000 | . . . | 9999 | 600 | . . . | 999 | n = o/20 + 500

Back to top

## Upgrading from version 5.0

### 1. Switching to the new database format

A new, more robust database file format has been developed for version 5.1 which is incompatible with the format used in earlier versions. To switch your databases to this format, ensure that the `misc/xml-export` and `misc/xml-import` modules are loaded by your `ircservices.conf`, and:

1. Shut down Services.
2. Export your databases to an XML file using the command: `ircservices -export=database.xml` (any filename can be used).
3. Edit your `ircservices.conf` file and change the line reading
   `LoadModule database/version4`
   to
   `LoadModule database/standard`
   Also enable the `misc/xml-import` module if it is commented out.
4. Import the XML data from step 2 into the new database format using the command: `ircservices -import=database.xml`
5. Start up Services.

Note that switching to the new database format is not required; you can continue to use your 5.0 databases by leaving the `LoadModule database/version4` configuration line alone. However, the new database format allows you to recover more data even if the database files get corrupted, so its use is recommended. (It is also possible to switch back to the old format from the new one in a similar manner, though all 5.1-specific data will be lost if the databases are used in an older version of Services.)

### 2. Channel memos

Version 5.1 includes a redesigned channel memo system which distributes channel memos to users of the channel (based on the channel access list) rather than storing the memos with the channel. As a result of this change, all stored channel memos will be deleted when starting up version 5.1. Users should be instructed to save any needed information before the upgrade.

### 3. Encryption handling

Version 5.1 allows passwords encrypted with different ciphers (or not encrypted at all) to coexist in the same database, by keeping track of what cipher was used to encrypt the password; this allows for enabling or disabling encryption, or changing the encryption type used, without concerns of old passwords becoming unusable.

However, since this ability was not present in version 5.0 and earlier, Services has no way to know what encryption type was used in databases from those versions, and simply defaults to the cipher given in the `EncryptionType` directive in `ircservices.conf` for all passwords. Therefore, if you continue to use the `database/version4` database module in version 5.1, you must ensure that `EncryptionType` is set correctly when you first load the data; once you have saved the databases using version 5.1, such as with the OperServ `UPDATE` or `SHUTDOWN` commands, you can change `EncryptionType` freely.

This also applies, of course, to converting databases from 5.0 to the new `database/standard` module format; be certain that you do not change `EncryptionType` until after you have exported the databases to an XML file.

### 4. NickServ/ChanServ `SENDPASS`

The NickServ and ChanServ `SENDPASS` commands have been removed in favor of the new NickServ `REAUTH` command, and the corresponding modules (`nickserv/sendpass` and `chanserv/sendpass`) have been deleted. Make certain to remove these modules from your `ircservices.conf` file before starting Services 5.1.

### 5. NickServ `SET` and `UNSET`

Services administrators should be aware that the NickServ `SET` and `UNSET` commands now require a "`!`" before the nickname; for example, instead of
`/msg NickServ SET nick NOEXPIRE ON`
type
`/msg NickServ SET !nick NOEXPIRE ON`
This is to avoid ambiguity where the nickname is the same as an option name.

Back to top

Table of Contents | Top