| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <title>Upgrading DisOrder</title> |
| 5 | <link rel=StyleSheet type="text/css" href="docs.css"> |
| 6 | </head> |
| 7 | <body> |
| 8 | <h1>Upgrading DisOrder</h1> |
| 9 | |
| 10 | <ul> |
| 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> |
| 14 | </ul> |
| 15 | |
| 16 | <h2><a name="deb">.deb Installs</a></h2> |
| 17 | |
| 18 | <h3>Take A Backup</h3> |
| 19 | |
| 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> |
| 22 | |
| 23 | <pre># disorder-dump --dump <i>PATH</i></pre> |
| 24 | |
| 25 | <p>where <i>PATH</i> is the filename to write the backup to.</p> |
| 26 | |
| 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> |
| 30 | upgrades.</p> |
| 31 | |
| 32 | <h3>Install The New Packages</h3> |
| 33 | |
| 34 | <pre># dpkg -i *.deb</pre> |
| 35 | |
| 36 | <h3>Upgrade Databases</h3> |
| 37 | |
| 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> |
| 42 | |
| 43 | <pre># rm /var/lib/disorder/* |
| 44 | # disorder-dump --restore PATH |
| 45 | # dpkg --configure -a</pre> |
| 46 | |
| 47 | <h2><a name=source>Source Installs</a></h2> |
| 48 | |
| 49 | <h3>Take A Backup</h3> |
| 50 | |
| 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> |
| 53 | |
| 54 | <pre># disorder-dump --dump PATH</pre> |
| 55 | |
| 56 | <p>where PATH is the filename to write the backup to.</p> |
| 57 | |
| 58 | <h3>Stop The Server</h3> |
| 59 | |
| 60 | <p>Linux:</p> |
| 61 | |
| 62 | <pre># /etc/init.d/disorder stop</pre> |
| 63 | |
| 64 | <p>Mac:</p> |
| 65 | |
| 66 | <pre># launchctl stop uk.org.greenend.rjk.disorder |
| 67 | # launchctl unload /Library/LaunchDaemons/uk.org.greenend.rjk.disorder.plist</pre> |
| 68 | |
| 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> |
| 72 | |
| 73 | <h3>Build And Install The New Version</h3> |
| 74 | |
| 75 | <p>See the top-level <a href="README">README</a>.</p> |
| 76 | |
| 77 | <h3>Update Configuration Files</h3> |
| 78 | |
| 79 | <p>See version-specific information below.</p> |
| 80 | |
| 81 | <h3>Upgrade Databases</h3> |
| 82 | |
| 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> |
| 85 | |
| 86 | <pre># rm /usr/local/var/disorder/* |
| 87 | # disorder-dump --restore PATH</pre> |
| 88 | |
| 89 | <h3>Restart The Server</h3> |
| 90 | |
| 91 | <p>Linux:</p> |
| 92 | |
| 93 | <pre># /etc/init.d/disorder start</pre> |
| 94 | |
| 95 | <p>Mac:</p> |
| 96 | |
| 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> |
| 100 | |
| 101 | <h1><a name=ver>Version-Specific Details</a></h1> |
| 102 | |
| 103 | <h2>4.x -> 5.0</h2> |
| 104 | |
| 105 | <h3>Web Confirmation Strings</h3> |
| 106 | |
| 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> |
| 113 | |
| 114 | <h3>Handling Of Configuration Changes</h3> |
| 115 | |
| 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> |
| 121 | |
| 122 | <p>The result will be a log message of the form:</p> |
| 123 | |
| 124 | <pre>new database parameter string dbparams-0-sha256:61609f3e6395ec8dee317ee216fe2848d70c249d347dd03c6a219441a13dd456 - removing old data</pre> |
| 125 | |
| 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> |
| 128 | |
| 129 | <h3>Deprecation Notices</h3> |
| 130 | |
| 131 | <p>The player <tt>--wait-for-device</tt> option is deprecated and will be |
| 132 | removed in a future version.</p> |
| 133 | |
| 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 |
| 136 | is:</p> |
| 137 | |
| 138 | <ul> |
| 139 | <li>allow</li> |
| 140 | <li>gap</li> |
| 141 | <li>lock</li> |
| 142 | <li>prefsync</li> |
| 143 | <li>restrict</li> |
| 144 | <li>trust</li> |
| 145 | </ul> |
| 146 | |
| 147 | <h2>3.0 -> 4.x</h2> |
| 148 | |
| 149 | <p>If you customized any of the templates, you will pretty much have to |
| 150 | start from scratch as the web interface has been rewritten. See |
| 151 | disorder.cgi(8) for a starting point.</p> |
| 152 | |
| 153 | <p>The 'gap' directive will no longer work. You must delete it from any |
| 154 | configuration files that contain it.</p> |
| 155 | |
| 156 | <p>You may prefer to remove any 'smtp_server' directive you have, as the |
| 157 | web interface will now use the local sendmail executable if available.</p> |
| 158 | |
| 159 | <p>If you want to be able to do use management over non-local connections |
| 160 | (thereby potentially exposing passwords!) you must set 'remote_userman' to |
| 161 | 'yes'.</p> |
| 162 | |
| 163 | <h2>2.0 -> 3.0</h2> |
| 164 | |
| 165 | <h3>Authentication</h3> |
| 166 | |
| 167 | <p>Users are now stored in the database rather than in 'allow' directives |
| 168 | in a private configuration file. 'allow' is still understood in this |
| 169 | version, but is only used to populate the database on startup. After the |
| 170 | first (successful) run of the server the remaining 'allow' directives |
| 171 | should be deleted.</p> |
| 172 | |
| 173 | <p>'restrict' and 'trust' are replaced by a system of per-user rights. The |
| 174 | default user rights are based on the 'restrict' setting, and the rights of |
| 175 | users created frow 'allow' directives preserve the meaning of 'trust', but |
| 176 | after the first run you should remove these directives and (optionally) add |
| 177 | a 'default_rights' directive.</p> |
| 178 | |
| 179 | <p>'allow', 'restrict' and 'trust' will stop working entirely in a future |
| 180 | version but for now they will generate harmless error messages. Remove |
| 181 | them and the error messages will go away.</p> |
| 182 | |
| 183 | <p>See README for new setup instructions for the web interface.</p> |
| 184 | |
| 185 | <h3>Other Server Configuration</h3> |
| 186 | |
| 187 | <p>Sensible defaults for 'stopword', 'player' and 'tracklength' are now |
| 188 | built into the server. If you haven't modified the values from the example |
| 189 | or Debian configuration files then you can remove them.</p> |
| 190 | |
| 191 | <p>'gap' now defaults to 0 seconds instead of 2.</p> |
| 192 | |
| 193 | <p>The sound output API is now configured with the 'api' command although |
| 194 | 'speaker_backend' still works. If you use 'api alsa' then you may need to |
| 195 | change your 'mixer' and 'channel' settings.</p> |
| 196 | |
| 197 | <h3>Web Interface</h3> |
| 198 | |
| 199 | <p>The web interface no longer uses HTTP basic authentication and the web |
| 200 | server configuration imposing access control on it should be removed. |
| 201 | Users now log in using their main DisOrder password and the one in the |
| 202 | htpassed file is now obsolete. You should revisit the web interface setup |
| 203 | instructions in README from scratch.</p> |
| 204 | |
| 205 | <p>As part of this, the DisOrder URL has changed from (e.g.)</p> |
| 206 | |
| 207 | <pre>http://yourserver/cgi-bin/disorder/disorder</pre> |
| 208 | |
| 209 | <p>to just</p> |
| 210 | |
| 211 | <pre>http://yourserver/cgi-bin/disorder</pre> |
| 212 | |
| 213 | <h3>Checklist</h3> |
| 214 | |
| 215 | <ul> |
| 216 | <li>delete default 'stopword', 'player' and 'tracklength' directives</li> |
| 217 | <li>set 'gap' if you want a non-0 inter-track gap</li> |
| 218 | <li>set 'api' and maybe 'mixer' and 'channel'</li> |
| 219 | <li>perhaps add 'default_rights' directive</li> |
| 220 | <li>delete 'allow', 'restrict' and 'trust' directives after first run</li> |
| 221 | <li>follow new web interface setup in README</li> |
| 222 | </ul> |
| 223 | |
| 224 | <h2>1.4/1.5 -> 2.0</h2> |
| 225 | |
| 226 | <h3>'transform' and 'namepart' directives</h3> |
| 227 | |
| 228 | <p>'transform' has moved from the web options to the main configuration |
| 229 | file, so that they can be used by other interfaces. The syntax and |
| 230 | semantics are unchanged.</p> |
| 231 | |
| 232 | <p>More importantly however both 'transform' and 'namepart' are now |
| 233 | optional, with sensible defaults being built in. So if you were already |
| 234 | using the default values you can just delete all instances of both.</p> |
| 235 | |
| 236 | <p>See disorder_config(5) for the default values. Hopefuly they will be |
| 237 | suitable for many configurations. Please do send feedback.</p> |
| 238 | |
| 239 | <h3>'enabled' and 'random_enabled' directives</h3> |
| 240 | |
| 241 | <p>These have been removed. Instead the state persists from one run of the |
| 242 | server to the next. If they appear in your configuration file they must be |
| 243 | removed; the server will not start if they are present.</p> |
| 244 | |
| 245 | <h3>Database upgrade</h3> |
| 246 | |
| 247 | <p>It is strongly recommended that you back up your database before |
| 248 | performing the upgrade. For example, as root, with the server STOPPED:</p> |
| 249 | |
| 250 | <pre># cd /var/disorder |
| 251 | # mkdir BACKUP |
| 252 | # cp -p * BACKUP</pre> |
| 253 | |
| 254 | <p>To restore, again as root:</p> |
| 255 | <pre># cd /var/disorder |
| 256 | # rm * |
| 257 | # cp -p BACKUP/* .</pre> |
| 258 | |
| 259 | <p>The first thing the server does when upgrading from 1.5 is run the |
| 260 | disorder-dbupgrade program. This is necessary to modify any non-ASCII |
| 261 | track names to meet the latest version's stricter normalization practices. |
| 262 | The upgrade should succeed automtically; if not it should leave an error |
| 263 | message in syslog.</p> |
| 264 | |
| 265 | <h2>1.3 -> 1.4</h2> |
| 266 | |
| 267 | <h3>Raw Format Decoders</h3> |
| 268 | |
| 269 | <p>You will probably want reconfigure your install to use the new |
| 270 | facilities (although the old way works fine). See the example |
| 271 | configuration file and README.raw for more details.</p> |
| 272 | |
| 273 | <p>Depending on how your system is configured you may need to link the |
| 274 | disorder libao driver into the right directory:</p> |
| 275 | |
| 276 | <pre># ln -s /usr/local/lib/ao/plugins-2/libdisorder.so /usr/lib/ao/plugins-2/.</pre> |
| 277 | |
| 278 | <h2>1.2 -> 1.3</h2> |
| 279 | |
| 280 | <h3>Server Environment</h3> |
| 281 | |
| 282 | <p>It is important that $sbindir is on the server's path. The example init |
| 283 | script guarantees this. You may need to modify the installed one. You |
| 284 | will get "deadlock manager unexpectedly terminated" if you get this |
| 285 | wrong.</p> |
| 286 | |
| 287 | <h3>namepart directives</h3> |
| 288 | |
| 289 | <p>These have changed in three ways.</p> |
| 290 | |
| 291 | <p>Firstly they have changed to substitute in a more convenient way. |
| 292 | Instead of matches for the regexp being substituted back into the original |
| 293 | track name, the replacement string now completely replaces it. Given the |
| 294 | usual uses of namepart, this is much more convenient. If you've stuck with |
| 295 | the defaults no changes should be needed for this.</p> |
| 296 | |
| 297 | <p>Secondly they are matched against the track name with the collection |
| 298 | root stripped off.</p> |
| 299 | |
| 300 | <p>Finally you will need to add an extra line to your config file as |
| 301 | follows for the new track aliasing mechanisms to work properly:</p> |
| 302 | |
| 303 | <pre>namepart ext "(\\.[a-zA-Z0-9]+)$" "$1" *</pre> |
| 304 | |
| 305 | <h2>1.1 -> 1.2</h2> |
| 306 | |
| 307 | <h3>Web Interface Changes</h3> |
| 308 | |
| 309 | <p>The web interface now includes static content as well as templates. The |
| 310 | static content must be given a name visible to HTTP clients which maps to |
| 311 | its location in the real filesystem.</p> |
| 312 | |
| 313 | <p>The README suggests using a rule in httpd.conf to make /static in the |
| 314 | HTTP namespace point to /usr/local/share/disorder/static, which is where |
| 315 | DisOrder installs its static content (by default). Alternatively you can |
| 316 | set the url.static label to the base URL of the static content.</p> |
| 317 | |
| 318 | <h3>Configuration File Changes</h3> |
| 319 | |
| 320 | <p>The trackname-part web interface directive has now gone, and the |
| 321 | options.trackname file with it.</p> |
| 322 | |
| 323 | <p>It is replaced by a new namepart directive in the main configuration |
| 324 | file. This has exactly the same syntax as trackname-part, only the name |
| 325 | and location have changed.</p> |
| 326 | |
| 327 | <p>The reason for the change is to allow track name parsing to be centrally |
| 328 | configured, rather than every interface to DisOrder having to implement it |
| 329 | locally.</p> |
| 330 | |
| 331 | <p>If you do not install new namepart directives into the main |
| 332 | configuration file then track titles will show up blank.</p> |
| 333 | |
| 334 | <p>If you do not remove the trackname-part directives from the web |
| 335 | interface configuration then you will get error messages in the web |
| 336 | server's error log.</p> |
| 337 | |
| 338 | </body> |
| 339 | </html> |
| 340 | |
| 341 | <!-- Local Variables: --> |
| 342 | <!-- fill-column:79 --> |
| 343 | <!-- End: --> |