1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.0//EN">
4 <title>Upgrading DisOrder
</title>
5 <link rel=StyleSheet
type=
"text/css" href=
"docs.css">
8 <h1>Upgrading DisOrder
</h1>
11 <li><a href=
"#deb">.deb Installs
</a></li>
12 <li><a href=
"#source">Source Installs
</a></li>
13 <li><a href=
"#ver">Version-Specific Details
</a></li>
16 <h2><a name=
"deb">.deb Installs
</a></h2>
18 <h3>Take A Backup
</h3>
20 <p>You should make a backup of DisOrder's databases before proceeding with
21 any upgrade. You can generate a backup as follows:
</p>
23 <pre># disorder-dump --dump
<i>PATH
</i></pre>
25 <p>where
<i>PATH
</i> is the filename to write the backup to.
</p>
27 <p>As of version
5.1, the Debian version of the server will take a daily
28 backup of its databases to
<tt>/var/lib/disorder/backups
</tt>, so it should
29 not be a disaster if you neglect this step in
<i>subsequent
</i>
32 <h3>Install The New Packages
</h3>
34 <pre># dpkg -i *.deb
</pre>
36 <h3>Upgrade Databases
</h3>
38 <p>If you have changed version of
<tt>libdb
</tt> then the new one may not
39 be compatible with the old one's file format. In this case the server will
40 not start, causing the upgrade to fail. Remove the database files and
41 restore from the backup you took above.
</p>
43 <pre># rm /var/lib/disorder/*
44 # disorder-dump --restore PATH
45 # dpkg --configure -a
</pre>
47 <h2><a name=source
>Source Installs
</a></h2>
49 <h3>Take A Backup
</h3>
51 <p>You should make a backup of DisOrder's databases before proceeding with
52 any upgrade. You can generate a backup as follows:
</p>
54 <pre># disorder-dump --dump PATH
</pre>
56 <p>where PATH is the filename to write the backup to.
</p>
58 <h3>Stop The Server
</h3>
62 <pre># /etc/init.d/disorder stop
</pre>
66 <pre># launchctl stop uk.org.greenend.rjk.disorder
67 # launchctl unload /Library/LaunchDaemons/uk.org.greenend.rjk.disorder.plist
</pre>
69 <p>If you are feeling cautious you can also make an exact copy of the
70 database files at this point (they are in
71 <tt>/usr/local/var/disorder
</tt>).
</p>
73 <h3>Build And Install The New Version
</h3>
75 <p>See the top-level
<a href=
"README">README
</a>.
</p>
77 <h3>Update Configuration Files
</h3>
79 <p>See version-specific information below.
</p>
81 <h3>Upgrade Databases
</h3>
83 <p>If you have changed version of
<tt>libdb
</tt> you may need to remove the
84 database files and restore from the backup you took above.
</p>
86 <pre># rm /usr/local/var/disorder/*
87 # disorder-dump --restore PATH
</pre>
89 <h3>Restart The Server
</h3>
93 <pre># /etc/init.d/disorder start
</pre>
97 <pre># cp examples/uk.org.greenend.rjk.disorder.plist /Library/LaunchDaemons/.
98 # launchctl load /Library/LaunchDaemons
99 # launchctl start uk.org.greenend.rjk.disorder
</pre>
101 <h1><a name=ver
>Version-Specific Details
</a></h1>
105 <h3>Web Confirmation Strings
</h3>
107 <p>The syntax of confirmation strings for online registrations has changed
108 and old ones no longer work. This only affects users who registered before
109 the upgrade but have not yet confirmed their login. You can delete such
110 half-created users with 'disorder deluser USERNAME' (as an administrative
111 user, for instance as root on the server) and they can start the
112 registration process again.
</p>
114 <h3>Handling Of Configuration Changes
</h3>
116 <p>There is a new mechanism to ensure that the search database and aliases
117 are reconstructed if any options that affect them change. Unfortunately
118 this means that the reconstruction step always takes place on upgrade from
119 4.3 or earlier, as those versions don't record sufficient information for
120 the server to tell whether it needs to reconstruct or not.
</p>
122 <p>The result will be a log message of the form:
</p>
124 <pre>new database parameter string dbparams-
0-sha256:
61609f3e6395ec8dee317ee216fe2848d70c249d347dd03c6a219441a13dd456 - removing old data
</pre>
126 <p>...and a slower rescan on startup. Subsequent restarts should not have
127 this problem (unless of course you change a relevant option).
</p>
129 <h3>Deprecation Notices
</h3>
131 <p>The player
<tt>--wait-for-device
</tt> option is deprecated and will be
132 removed in a future version.
</p>
134 <p>The 'lock' option no longer does anything. You must delete it from any
135 configuration files that contain it. The full set of deprecated options
147 <p>(As of
5.1 these options are completely gone.)
</p>
151 <p>If you customized any of the templates, you will pretty much have to
152 start from scratch as the web interface has been rewritten. See
153 disorder.cgi(
8) for a starting point.
</p>
155 <p>The 'gap' directive will no longer work. You must delete it from any
156 configuration files that contain it.
</p>
158 <p>You may prefer to remove any 'smtp_server' directive you have, as the
159 web interface will now use the local sendmail executable if available.
</p>
161 <p>If you want to be able to do use management over non-local connections
162 (thereby potentially exposing passwords!) you must set 'remote_userman' to
167 <h3>Authentication
</h3>
169 <p>Users are now stored in the database rather than in 'allow' directives
170 in a private configuration file. 'allow' is still understood in this
171 version, but is only used to populate the database on startup. After the
172 first (successful) run of the server the remaining 'allow' directives
173 should be deleted.
</p>
175 <p>'restrict' and 'trust' are replaced by a system of per-user rights. The
176 default user rights are based on the 'restrict' setting, and the rights of
177 users created frow 'allow' directives preserve the meaning of 'trust', but
178 after the first run you should remove these directives and (optionally) add
179 a 'default_rights' directive.
</p>
181 <p>'allow', 'restrict' and 'trust' will stop working entirely in a future
182 version but for now they will generate harmless error messages. Remove
183 them and the error messages will go away.
</p>
185 <p>(Note: these options, and the code for upgrading old users, has been
186 removed entirely in release
5.1. You must either manually re-create your
187 users, or upgrade via
5.0.3.)
</p>
189 <p>See README for new setup instructions for the web interface.
</p>
191 <h3>Other Server Configuration
</h3>
193 <p>Sensible defaults for 'stopword', 'player' and 'tracklength' are now
194 built into the server. If you haven't modified the values from the example
195 or Debian configuration files then you can remove them.
</p>
197 <p>'gap' now defaults to
0 seconds instead of
2.
</p>
199 <p>The sound output API is now configured with the 'api' command although
200 'speaker_backend' still works. If you use 'api alsa' then you may need to
201 change your 'mixer' and 'channel' settings.
</p>
203 <h3>Web Interface
</h3>
205 <p>The web interface no longer uses HTTP basic authentication and the web
206 server configuration imposing access control on it should be removed.
207 Users now log in using their main DisOrder password and the one in the
208 htpassed file is now obsolete. You should revisit the web interface setup
209 instructions in README from scratch.
</p>
211 <p>As part of this, the DisOrder URL has changed from (e.g.)
</p>
213 <pre>http://yourserver/cgi-bin/disorder/disorder
</pre>
217 <pre>http://yourserver/cgi-bin/disorder
</pre>
222 <li>delete default 'stopword', 'player' and 'tracklength' directives
</li>
223 <li>set 'gap' if you want a non-
0 inter-track gap
</li>
224 <li>set 'api' and maybe 'mixer' and 'channel'
</li>
225 <li>perhaps add 'default_rights' directive
</li>
226 <li>delete 'allow', 'restrict' and 'trust' directives after first run
</li>
227 <li>follow new web interface setup in README
</li>
230 <h2>1.4/
1.5 -
> 2.0</h2>
232 <h3>'transform' and 'namepart' directives
</h3>
234 <p>'transform' has moved from the web options to the main configuration
235 file, so that they can be used by other interfaces. The syntax and
236 semantics are unchanged.
</p>
238 <p>More importantly however both 'transform' and 'namepart' are now
239 optional, with sensible defaults being built in. So if you were already
240 using the default values you can just delete all instances of both.
</p>
242 <p>See disorder_config(
5) for the default values. Hopefuly they will be
243 suitable for many configurations. Please do send feedback.
</p>
245 <h3>'enabled' and 'random_enabled' directives
</h3>
247 <p>These have been removed. Instead the state persists from one run of the
248 server to the next. If they appear in your configuration file they must be
249 removed; the server will not start if they are present.
</p>
251 <h3>Database upgrade
</h3>
253 <p>It is strongly recommended that you back up your database before
254 performing the upgrade. For example, as root, with the server STOPPED:
</p>
256 <pre># cd /var/disorder
258 # cp -p * BACKUP
</pre>
260 <p>To restore, again as root:
</p>
261 <pre># cd /var/disorder
263 # cp -p BACKUP/* .
</pre>
265 <p>The first thing the server does when upgrading from
1.5 is run the
266 disorder-dbupgrade program. This is necessary to modify any non-ASCII
267 track names to meet the latest version's stricter normalization practices.
268 The upgrade should succeed automtically; if not it should leave an error
269 message in syslog.
</p>
273 <h3>Raw Format Decoders
</h3>
275 <p>You will probably want reconfigure your install to use the new
276 facilities (although the old way works fine). See the example
277 configuration file and README.raw for more details.
</p>
279 <p>Depending on how your system is configured you may need to link the
280 disorder libao driver into the right directory:
</p>
282 <pre># ln -s /usr/local/lib/ao/plugins-
2/libdisorder.so /usr/lib/ao/plugins-
2/.
</pre>
286 <h3>Server Environment
</h3>
288 <p>It is important that $sbindir is on the server's path. The example init
289 script guarantees this. You may need to modify the installed one. You
290 will get
"deadlock manager unexpectedly terminated" if you get this
293 <h3>namepart directives
</h3>
295 <p>These have changed in three ways.
</p>
297 <p>Firstly they have changed to substitute in a more convenient way.
298 Instead of matches for the regexp being substituted back into the original
299 track name, the replacement string now completely replaces it. Given the
300 usual uses of namepart, this is much more convenient. If you've stuck with
301 the defaults no changes should be needed for this.
</p>
303 <p>Secondly they are matched against the track name with the collection
304 root stripped off.
</p>
306 <p>Finally you will need to add an extra line to your config file as
307 follows for the new track aliasing mechanisms to work properly:
</p>
309 <pre>namepart ext
"(\\.[a-zA-Z0-9]+)$" "$1" *
</pre>
313 <h3>Web Interface Changes
</h3>
315 <p>The web interface now includes static content as well as templates. The
316 static content must be given a name visible to HTTP clients which maps to
317 its location in the real filesystem.
</p>
319 <p>The README suggests using a rule in httpd.conf to make /static in the
320 HTTP namespace point to /usr/local/share/disorder/static, which is where
321 DisOrder installs its static content (by default). Alternatively you can
322 set the url.static label to the base URL of the static content.
</p>
324 <h3>Configuration File Changes
</h3>
326 <p>The trackname-part web interface directive has now gone, and the
327 options.trackname file with it.
</p>
329 <p>It is replaced by a new namepart directive in the main configuration
330 file. This has exactly the same syntax as trackname-part, only the name
331 and location have changed.
</p>
333 <p>The reason for the change is to allow track name parsing to be centrally
334 configured, rather than every interface to DisOrder having to implement it
337 <p>If you do not install new namepart directives into the main
338 configuration file then track titles will show up blank.
</p>
340 <p>If you do not remove the trackname-part directives from the web
341 interface configuration then you will get error messages in the web
342 server's error log.
</p>
347 <!-- Local Variables: --
>
348 <!-- fill-column:
79 --
>