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