Important! See README.upgrades when upgrading.

+ href="README.upgrades.html">README.upgrades when upgrading.

Platforms And Installation

diff --git a/Makefile.am b/Makefile.am index 5599ffd..4f98902 100644 --- a/Makefile.am +++ b/Makefile.am @@ -17,7 +17,8 @@ # EXTRA_DIST=CHANGES.html README.streams BUGS \ -README.upgrades README.client README.raw README.vhost README.developers +README.upgrades.html README.client README.raw README.vhost README.developers \ +docs.css SUBDIRS=@subdirs@ DISTCHECK_CONFIGURE_FLAGS:=httpdir=$(distdir)/_inst/httpdir cgiexecdir=$(shell pwd)/$(distdir)/_inst/cgiexecdir diff --git a/README b/README index b1ddc92..9df61fa 100644 --- a/README +++ b/README @@ -13,8 +13,8 @@ DisOrder is a multi-user software jukebox. GTK+ interface that runs on Linux and Mac systems. * Playing tracks can be paused or cancelled ("scratched"). -See CHANGES.html for details of recent changes to DisOrder and README.upgrades -for upgrade instructions. +See CHANGES.html for details of recent changes to DisOrder and +README.upgrades.html for upgrade instructions. Platform support: Linux Well tested on Debian @@ -67,7 +67,8 @@ Installation "This place'd be a paradise tomorrow, if every department had a supervisor with a machine-gun" -IMPORTANT: If you are upgrading from an earlier version, see README.upgrades. +IMPORTANT: If you are upgrading from an earlier version, see +README.upgrades.html. Debian/Ubuntu: steps 1 to 6 are dealt with automatically if you use the .deb files. diff --git a/README.upgrades b/README.upgrades deleted file mode 100644 index 1cb6aba..0000000 --- a/README.upgrades +++ /dev/null @@ -1,248 +0,0 @@ -* Upgrading DisOrder - -The general procedure is: - - * stop the old daemon: /etc/init.d/disorder stop - * back up your database directory (example below) - * build and install the new version as described in the README. Remember to - install the new version of the web interface too. - * update the configuration files (see below) - * start the new daemon, e.g. with - /etc/init.d/disorder start - -The rest of this file describes things you must pay attention to when -upgrading between particular versions. Minor versions are not -explicitly mentioned; a version number like 1.1 implicitly includes -all 1.1.x versions. - -If you install from .deb files then much of this work is automated. - -* 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: - allow - gap - lock - prefsync - restrict - trust - -* 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 - -** Authentication - -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.) - - http://yourserver/cgi-bin/disorder/disorder - -to just - - http://yourserver/cgi-bin/disorder - -** Checklist - - * delete default 'stopword', 'player' and 'tracklength' directives - * set 'gap' if you want a non-0 inter-track gap - * set 'api' and maybe 'mixer' and 'channel' - * perhaps add 'default_rights' directive - * delete 'allow', 'restrict' and 'trust' directives after first run - * follow new web interface setup in README - -* 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 automatically; 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. - -Local Variables: -mode:outline -fill-column:79 -End: diff --git a/README.upgrades.html b/README.upgrades.html new file mode 100644 index 0000000..842cf40 --- /dev/null +++ b/README.upgrades.html @@ -0,0 +1,343 @@ + + + + Upgrading DisOrder + + + +

Upgrading DisOrder

+ +

.deb Installs
Source Installs
Version-Specific Details

+ +

.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

+ +

Linux:

+ +

# /etc/init.d/disorder stop

+ +

Mac:

+ +

# 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

+ +

Linux:

+ +

# /etc/init.d/disorder start

+ +

Mac:

+ +

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

+ +

allow
gap
lock
prefsync
restrict
trust

+ +

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

+ +

Authentication

+ +

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

+ +

http://yourserver/cgi-bin/disorder/disorder

+ +

to just

+ +

http://yourserver/cgi-bin/disorder

+ +

Checklist

+ +

delete default 'stopword', 'player' and 'tracklength' directives
set 'gap' if you want a non-0 inter-track gap
set 'api' and maybe 'mixer' and 'channel'
perhaps add 'default_rights' directive
delete 'allow', 'restrict' and 'trust' directives after first run
follow new web interface setup in README

+ +

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.

+ + + + + + + diff --git a/debian/Makefile.am b/debian/Makefile.am index 293df22..4868419 100644 --- a/debian/Makefile.am +++ b/debian/Makefile.am @@ -25,4 +25,5 @@ EXTRA_DIST=README.Debian config.disorder-server control \ postrm.disorder-server overrides.disorder-server \ templates.disorder-server conffiles.disorder-server \ rules changelog usr.share.menu.disobedience \ + disorder.daily \ postinst.disobedience disobedience-manual diff --git a/debian/conffiles.disorder-server b/debian/conffiles.disorder-server index 5d44ee4..9e1f954 100644 --- a/debian/conffiles.disorder-server +++ b/debian/conffiles.disorder-server @@ -2,3 +2,4 @@ /etc/disorder/options /etc/disorder/options.user /etc/init.d/disorder +/etc/cron.daily/disorder diff --git a/debian/control b/debian/control index 57c3cc0..4036a11 100644 --- a/debian/control +++ b/debian/control @@ -28,7 +28,7 @@ Package: disorder-server Architecture: any Section: sound Priority: extra -Depends: disorder,httpd-cgi,sox,debconf,${shlibs:Depends},exim4|mail-transport-agent,adduser +Depends: disorder,httpd-cgi,sox,debconf,${shlibs:Depends},exim4|mail-transport-agent,adduser,findutils Suggests: disorder-playrtp,disobedience Description: Play random or selected digital audio files continuously DisOrder is a software jukebox. It can play OGG, MP3, WAV and FLAC files, diff --git a/debian/disorder.daily b/debian/disorder.daily new file mode 100755 index 0000000..3a4c64a --- /dev/null +++ b/debian/disorder.daily @@ -0,0 +1,30 @@ +#! /bin/sh +set -e + +# Maximum backup age +MAXAGE=7 + +# Enable backups +BACKUP=true + +# Enable pruning +PRUNE=true + +# All operator to override settings +if test -e /etc/default/disorder; then + . /etc/default/disorder +fi + +if ${BACKUP}; then + # Ensure the backup directory exists + mkdir -m 0700 -p /var/lib/disorder/backups + + # Take a backup + disorder-dump --dump /var/lib/disorder/backups/$(date +%F) +fi + +if ${PRUNE}; then + # Delete old backups + find /var/lib/disorder/backups -type -f -ctime +${MAXAGE} -print0 \ + | xargs -r0 rm -f +fi diff --git a/debian/rules b/debian/rules index 4d37b27..481b2ae 100755 --- a/debian/rules +++ b/debian/rules @@ -123,7 +123,7 @@ pkg-disorder: build dpkg-shlibdeps -Tdebian/substvars.disorder \ debian/disorder/usr/bin/* $(INSTALL_DATA) CHANGES.html README debian/README.Debian \ - BUGS README.* \ + BUGS README.* docs.css \ debian/disorder/usr/share/doc/disorder/. gzip -9f debian/disorder/usr/share/doc/disorder/README \ debian/disorder/usr/share/doc/disorder/README.* \ @@ -186,6 +186,7 @@ pkg-disorder-server: build $(MKDIR) debian/disorder-server/etc/init.d $(MKDIR) debian/disorder-server${cgiexecdir} $(MKDIR) debian/disorder-server/var/lib/disorder + $(MKDIR) debian/disorder-server/etc/cron.daily $(INSTALL_SCRIPT) examples/disorder.init \ debian/disorder-server/etc/init.d/disorder $(INSTALL_DATA) debian/etc.disorder.config \ @@ -194,6 +195,7 @@ pkg-disorder-server: build debian/disorder-server/etc/disorder/options $(INSTALL_DATA) debian/etc.disorder.options.user \ debian/disorder-server/etc/disorder/options.user + $(INSTALL_SCRIPT) debian/disorder.daily debian/disorder-server/etc/cron.daily/disorder $(LIBTOOL) --mode=install $(INSTALL_PROGRAM) cgi/disorder \ $(shell pwd)/debian/disorder-server${cgiexecdir}/disorder gzip -9f debian/disorder-server/usr/share/man/man*/* diff --git a/docs.css b/docs.css new file mode 100644 index 0000000..9a7f354 --- /dev/null +++ b/docs.css @@ -0,0 +1,56 @@ +body { + color: black; + background-color: white; + font-family: times,serif; + font-weight: normal; + font-size: 12pt; + font-variant: normal +} + +div.section { + margin-left:1em +} + +h1 { + background-color: #e0ffe0; + font-family: helvetica,sans-serif; + padding: 0.2em +} + +h2 { + background-color: #e0ffe0; + font-family: helvetica,sans-serif; + padding: 0.2em +} + +h3 { + background-color: #f0f0f0; + font-family: helvetica,sans-serif; + padding: 0.2em +} + +h4 { + font-family: helvetica,sans-serif +} + +table.bugs { + width: 100%; + font-size: 12pt; + border-collapse: collapse; + border:1px +} + +table.bugs th { + text-align: left; + border: 1px solid black; + background-color: black; + color: white +} + +table.bugs td { + border: 1px solid +} + +span.command { + font-family: monospace +}

Changes up to version 5.1

Platforms And Installation

Upgrading DisOrder

.deb Installs

Take A Backup

Install The New Packages

Upgrade Databases

Source Installs

Take A Backup

Stop The Server

Build And Install The New Version

Update Configuration Files

Upgrade Databases

Restart The Server

Version-Specific Details

4.x -> 5.0

Web Confirmation Strings

Handling Of Configuration Changes

Deprecation Notices

3.0 -> 4.x

2.0 -> 3.0

Authentication

Other Server Configuration

Web Interface

Checklist

1.4/1.5 -> 2.0

'transform' and 'namepart' directives

'enabled' and 'random_enabled' directives

Database upgrade

1.3 -> 1.4

Raw Format Decoders

1.2 -> 1.3

Server Environment

namepart directives

1.1 -> 1.2

Web Interface Changes

Configuration File Changes