IRC Services - Important information about upgrading

# IRC Services Manual

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

Table of Contents

### 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

Table of Contents | Top