X-Git-Url: https://git.distorted.org.uk/~mdw/disorder/blobdiff_plain/f03d418427984d413a11aa1de58fbffe33718403..b60ceb3caecce2c86c484e6173fb1428b71d456a:/README.upgrades.html diff --git a/README.upgrades.html b/README.upgrades.html new file mode 100644 index 0000000..c628b06 --- /dev/null +++ b/README.upgrades.html @@ -0,0 +1,349 @@ + + +
+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.
+ +# dpkg -i *.deb+ +
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+ +
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.
+ +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).
+ +See the top-level README.
+ +See version-specific information below.
+ +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+ +
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+ +
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.
+ +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).
+ +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:
+ +(As of 5.1 these options are completely gone.)
+ +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'.
+ +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.
+ +(Note: these options, and the code for upgrading old users, has been + removed entirely in release 5.1. You must either manually re-create your + users, or upgrade via 5.0.3.)
+ +See README for new setup instructions for the web interface.
+ +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.
+ +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+ +
'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.
+ +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.
+ +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.
+ +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/.+ +
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.
+ +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" *+ +
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.
+ +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.
+ + + + + + +