Upgrading DisOrder

.deb Installs

Take A Backup

You should make a backup of DisOrder's databases before proceeding with any upgrade. You can generate a backup as follows:

# disorder-dump --dump PATH

where PATH is the filename to write the backup to.

As of version 5.1, the Debian version of the server will take a daily backup of its databases to /var/lib/disorder/backups, so it should not be a disaster if you neglect this step in subsequent upgrades.

Install The New Packages

# dpkg -i *.deb

Upgrade Databases

If you have changed version of libdb then the new one may not be compatible with the old one's file format. In this case the server will not start, causing the upgrade to fail. Remove the database files and restore from the backup you took above.

# rm /var/lib/disorder/*
# disorder-dump --restore PATH
# dpkg --configure -a

Source Installs

Take A Backup

You should make a backup of DisOrder's databases before proceeding with any upgrade. You can generate a backup as follows:

# disorder-dump --dump PATH

where PATH is the filename to write the backup to.

Stop The Server


# /etc/init.d/disorder stop


# launchctl stop uk.org.greenend.rjk.disorder
# launchctl unload /Library/LaunchDaemons/uk.org.greenend.rjk.disorder.plist

If you are feeling cautious you can also make an exact copy of the database files at this point (they are in /usr/local/var/disorder).

Build And Install The New Version

See the top-level README.

Update Configuration Files

See version-specific information below.

Upgrade Databases

If you have changed version of libdb you may need to remove the database files and restore from the backup you took above.

# rm /usr/local/var/disorder/*
# disorder-dump --restore PATH

Restart The Server


# /etc/init.d/disorder start


# cp examples/uk.org.greenend.rjk.disorder.plist /Library/LaunchDaemons/.
# launchctl load /Library/LaunchDaemons
# launchctl start uk.org.greenend.rjk.disorder

Version-Specific Details

4.x -> 5.0

Web Confirmation Strings

The syntax of confirmation strings for online registrations has changed and old ones no longer work. This only affects users who registered before the upgrade but have not yet confirmed their login. You can delete such half-created users with 'disorder deluser USERNAME' (as an administrative user, for instance as root on the server) and they can start the registration process again.

Handling Of Configuration Changes

There is a new mechanism to ensure that the search database and aliases are reconstructed if any options that affect them change. Unfortunately this means that the reconstruction step always takes place on upgrade from 4.3 or earlier, as those versions don't record sufficient information for the server to tell whether it needs to reconstruct or not.

The result will be a log message of the form:

new database parameter string dbparams-0-sha256:61609f3e6395ec8dee317ee216fe2848d70c249d347dd03c6a219441a13dd456 - removing old data

...and a slower rescan on startup. Subsequent restarts should not have this problem (unless of course you change a relevant option).

Deprecation Notices

The player --wait-for-device option is deprecated and will be removed in a future version.

The 'lock' option no longer does anything. You must delete it from any configuration files that contain it. The full set of deprecated options is:

3.0 -> 4.x

If you customized any of the templates, you will pretty much have to start from scratch as the web interface has been rewritten. See disorder.cgi(8) for a starting point.

The 'gap' directive will no longer work. You must delete it from any configuration files that contain it.

You may prefer to remove any 'smtp_server' directive you have, as the web interface will now use the local sendmail executable if available.

If you want to be able to do use management over non-local connections (thereby potentially exposing passwords!) you must set 'remote_userman' to 'yes'.

2.0 -> 3.0


Users are now stored in the database rather than in 'allow' directives in a private configuration file. 'allow' is still understood in this version, but is only used to populate the database on startup. After the first (successful) run of the server the remaining 'allow' directives should be deleted.

'restrict' and 'trust' are replaced by a system of per-user rights. The default user rights are based on the 'restrict' setting, and the rights of users created frow 'allow' directives preserve the meaning of 'trust', but after the first run you should remove these directives and (optionally) add a 'default_rights' directive.

'allow', 'restrict' and 'trust' will stop working entirely in a future version but for now they will generate harmless error messages. Remove them and the error messages will go away.

See README for new setup instructions for the web interface.

Other Server Configuration

Sensible defaults for 'stopword', 'player' and 'tracklength' are now built into the server. If you haven't modified the values from the example or Debian configuration files then you can remove them.

'gap' now defaults to 0 seconds instead of 2.

The sound output API is now configured with the 'api' command although 'speaker_backend' still works. If you use 'api alsa' then you may need to change your 'mixer' and 'channel' settings.

Web Interface

The web interface no longer uses HTTP basic authentication and the web server configuration imposing access control on it should be removed. Users now log in using their main DisOrder password and the one in the htpassed file is now obsolete. You should revisit the web interface setup instructions in README from scratch.

As part of this, the DisOrder URL has changed from (e.g.)


to just



1.4/1.5 -> 2.0

'transform' and 'namepart' directives

'transform' has moved from the web options to the main configuration file, so that they can be used by other interfaces. The syntax and semantics are unchanged.

More importantly however both 'transform' and 'namepart' are now optional, with sensible defaults being built in. So if you were already using the default values you can just delete all instances of both.

See disorder_config(5) for the default values. Hopefuly they will be suitable for many configurations. Please do send feedback.

'enabled' and 'random_enabled' directives

These have been removed. Instead the state persists from one run of the server to the next. If they appear in your configuration file they must be removed; the server will not start if they are present.

Database upgrade

It is strongly recommended that you back up your database before performing the upgrade. For example, as root, with the server STOPPED:

# cd /var/disorder
# mkdir BACKUP
# cp -p * BACKUP

To restore, again as root:

# cd /var/disorder
# rm *
# cp -p BACKUP/* .

The first thing the server does when upgrading from 1.5 is run the disorder-dbupgrade program. This is necessary to modify any non-ASCII track names to meet the latest version's stricter normalization practices. The upgrade should succeed automtically; if not it should leave an error message in syslog.

1.3 -> 1.4

Raw Format Decoders

You will probably want reconfigure your install to use the new facilities (although the old way works fine). See the example configuration file and README.raw for more details.

Depending on how your system is configured you may need to link the disorder libao driver into the right directory:

# ln -s /usr/local/lib/ao/plugins-2/libdisorder.so /usr/lib/ao/plugins-2/.

1.2 -> 1.3

Server Environment

It is important that $sbindir is on the server's path. The example init script guarantees this. You may need to modify the installed one. You will get "deadlock manager unexpectedly terminated" if you get this wrong.

namepart directives

These have changed in three ways.

Firstly they have changed to substitute in a more convenient way. Instead of matches for the regexp being substituted back into the original track name, the replacement string now completely replaces it. Given the usual uses of namepart, this is much more convenient. If you've stuck with the defaults no changes should be needed for this.

Secondly they are matched against the track name with the collection root stripped off.

Finally you will need to add an extra line to your config file as follows for the new track aliasing mechanisms to work properly:

namepart        ext     "(\\.[a-zA-Z0-9]+)$"                   "$1"    *

1.1 -> 1.2

Web Interface Changes

The web interface now includes static content as well as templates. The static content must be given a name visible to HTTP clients which maps to its location in the real filesystem.

The README suggests using a rule in httpd.conf to make /static in the HTTP namespace point to /usr/local/share/disorder/static, which is where DisOrder installs its static content (by default). Alternatively you can set the url.static label to the base URL of the static content.

Configuration File Changes

The trackname-part web interface directive has now gone, and the options.trackname file with it.

It is replaced by a new namepart directive in the main configuration file. This has exactly the same syntax as trackname-part, only the name and location have changed.

The reason for the change is to allow track name parsing to be centrally configured, rather than every interface to DisOrder having to implement it locally.

If you do not install new namepart directives into the main configuration file then track titles will show up blank.

If you do not remove the trackname-part directives from the web interface configuration then you will get error messages in the web server's error log.