Rebuild xsp4 Applications Safely with mono-xsp4-update

mono-xsp4-update rebuilds /etc/xsp4/debian.webapp from the snippets under /etc/xsp4/conf.d in one pass. You will regenerate that file, then check that xsp4 can see the expected paths and aliases. Allow about 15 minutes, plus time to investigate any invalid application directory. This guide describes the Debian package version 4.2-2.5 installed on the reference system.

The command needs write access to /etc/xsp4. Run it as root, normally through sudo. It has no dry-run mode and accepts no documented options, so inspect the inputs before you run it.

1. Check the installed command and inputs

Confirm which package supplies the command and list the configuration snippets that will be read:

$ command -v mono-xsp4-update
/usr/sbin/mono-xsp4-update
$ dpkg-query -W -f='${Package} ${Version}\n' mono-xsp4
mono-xsp4 4.2-2.5
$ find /etc/xsp4/conf.d -type f -print | sort
/etc/xsp4/conf.d/monodoc-http/10_monodoc-http

Your list will differ if other packages or locally managed virtual hosts are installed. Each file is read as an xsp4 host configuration. The Debian guidance describes the directories below conf.d as virtual-host configuration directories, with numbered files such as 10_monodoc-http.

Before continuing, inspect any file you did not expect:

$ sed -n '1,120p' /etc/xsp4/conf.d/monodoc-http/10_monodoc-http

Look for path = ... and alias = ... entries. The updater only emits an application when the path named by a path line is an existing directory. Keep the original snippets; they are the inputs and are not replaced by this command.

2. Record the current generated file

The updater rebuilds a fixed file, /etc/xsp4/debian.webapp. Save a readable copy of its current content before changing it:

$ sudo cp --preserve=all /etc/xsp4/debian.webapp /etc/xsp4/debian.webapp.before-update
$ sudo sed -n '1,160p' /etc/xsp4/debian.webapp

If the generated file does not exist yet, the copy command will fail. That is not a problem: record that fact and continue after checking the directory itself:

$ sudo test -e /etc/xsp4/debian.webapp && echo 'generated file exists' || echo 'no generated file yet'
$ sudo test -w /etc/xsp4 && echo 'directory is writable' || echo 'directory is not writable'

Checkpoint: do not proceed if the configuration snippets contain a path that should be present but its directory is missing. Fix the package or application installation first. The updater silently skips a snippet when its path check fails, so a successful command can still produce an incomplete application list.

3. Run the updater as root

Run the command with no arguments:

$ sudo mono-xsp4-update
$ printf 'exit status: %s\n' "$?"
exit status: 0

A successful run normally prints nothing. Internally, the installed Perl tool removes the old generated file, creates it again, writes an <apps> document, and appends one <web-application> block for each usable configuration file. It closes the document with </apps>.

This is a state-changing command. It deletes and recreates the generated file, and it can restart the service. Do not interrupt it while it is writing the file. Do not run it against a production machine merely to discover what it would do: there is no preview option in the installed interface.

4. Verify the generated applications

Check that the file exists, is readable XML-shaped configuration, and contains the expected alias and path:

$ sudo test -s /etc/xsp4/debian.webapp
$ sudo grep -E '^(  <web-application>|    <(name|vpath|path)>)' /etc/xsp4/debian.webapp
  <web-application>
    <name>monodochttp</name>
    <vpath>/monodoc-http</vpath>
    <path>/usr/share/monodoc/web</path>

The exact name, alias and path come from your configuration. The updater removes every slash from the alias when it creates the name, while it keeps the alias as the vpath. That is why an alias such as /monodoc-http can produce a name of monodochttp.

Count the generated blocks when you have several applications:

$ sudo grep -c '<web-application>' /etc/xsp4/debian.webapp

Compare that number with the snippets whose path directories exist. A lower count is expected when a snippet points to a missing directory, but it is a configuration fault to fix rather than a successful deployment.

5. Understand the service restart

The updater calculates an MD5 digest before and after rebuilding the file. If the content changed, it reads /etc/default/mono-xsp4. When that file contains start_boot set to a true value, and both /etc/init.d/mono-xsp4 and /var/run/mono-xsp4.pid exist, the updater runs the init script's restart action.

That restart is conditional. A changed file does not guarantee a restart, and an unchanged rebuild does not restart the service. If you need to check the service separately, use the package's init script:

$ sudo /etc/init.d/mono-xsp4 status

The exact status output depends on this older init-script package. Treat a non-zero status as a reason to inspect the service log and configuration, not as proof that the generated file was malformed.

6. Recover from a bad result

First preserve evidence: copy the generated file and note which input snippet changed. If the new file omitted an application, restore the missing directory or correct its path entry, then run the updater again:

$ sudo cp --preserve=all /etc/xsp4/debian.webapp /etc/xsp4/debian.webapp.failed
$ sudo test -d /the/expected/application/path && echo 'application path exists'
$ sudo mono-xsp4-update

If you must return immediately to the previous generated file and the backup from step 2 exists, restore it and check the service. This changes system state, so verify the backup before replacing anything:

$ sudo test -s /etc/xsp4/debian.webapp.before-update
$ sudo cp --preserve=all /etc/xsp4/debian.webapp.before-update /etc/xsp4/debian.webapp
$ sudo /etc/init.d/mono-xsp4 restart

Do not delete the backup until xsp4 has served each required application successfully. The updater itself does not provide an undo command.

Done means