Register an ASP.NET Application with mono-xsp4-admin

You will register an existing ASP.NET application as a Mono XSP 4 virtual host, inspect the generated configuration, and know how to remove the registration later. The installed package here is mono-xsp4 4.2-2.5. Allow about ten minutes if the application directory is ready.

You need a shell, an existing directory containing the application files, and root access. The command changes /etc/xsp4/conf.d, regenerates /etc/xsp4/debian.webapp, and may restart Mono XSP 4 when its service is running. These are system-wide changes, so use a maintenance window if the server hosts live traffic.

1. Choose a stable application name and path

Pick a short name using letters, digits or a simple hyphen, then choose the real directory containing the ASP.NET files. The name becomes the URL alias as well as a directory name under /etc/xsp4/conf.d. In the examples below, replace both placeholders before running a command:

$ APP_NAME='myapp'
$ APP_PATH='/srv/www/myapp'
$ test -d "$APP_PATH" && printf 'directory exists: %s\n' "$APP_PATH"
directory exists: /srv/www/myapp

The check above is an ordinary read-only command. If it prints nothing, stop and correct the path. mono-xsp4-admin add also checks that the path exists, but an early check avoids creating a partial configuration while troubleshooting a typo.

2. Check the installed command and package

Confirm that the command comes from the expected package. This does not need elevated privileges:

$ command -v mono-xsp4-admin
/usr/sbin/mono-xsp4-admin
$ dpkg-query -W -f='${Package} ${Version}\n' mono-xsp4
mono-xsp4 4.2-2.5

The manpage describes the syntax as mono-xsp4-admin [action] [args]. The installed script accepts the action add or del, and expects the options in equals form: --path=/real/path --app=/application. Keep the option values as separate, plainly quoted shell assignments when they contain spaces.

3. Add the application

Checkpoint: this step writes configuration and can restart the service. Run it with sudo from a shell where the two variables are set:

$ sudo mono-xsp4-admin add --path="$APP_PATH" --app="$APP_NAME"
done!

The script creates /etc/xsp4/conf.d/myapp/10_myapp. It records the path and maps the application at /myapp. It then calls mono-xsp4-update, which rebuilds /etc/xsp4/debian.webapp from the directories in conf.d.

A successful done! is only the script's final message. It does not show the generated file, so inspect it before treating the registration as complete:

$ sudo sed -n '1,80p' "/etc/xsp4/conf.d/$APP_NAME/10_$APP_NAME"
This is the configuration file
for the myapp virtualhost
path = /srv/www/myapp
alias = /myapp
$ sudo sed -n '1,120p' /etc/xsp4/debian.webapp
<apps>
  <web-application>
    <name>myapp</name>
    <vpath>/myapp</vpath>
    <path>/srv/www/myapp</path>
  </web-application>
</apps>

The exact surrounding entries depend on other installed applications. Check that your path and alias are present, and that the XML has its opening and closing apps elements. If the path later disappears, a future regeneration will omit that application from the generated file.

4. Check service impact and test the route

mono-xsp4-update compares the generated file with its previous content. If the content changed, it restarts the service when the configured service state allows it and the service has a PID file. This means the add command can briefly interrupt other XSP 4 applications. Check the service state after the update:

$ sudo systemctl status mono-xsp4 --no-pager
$ sudo ss -ltnp | grep -E ':(8080|8081)\b' || true

The port is installation-specific, commonly 8080 or 8081. Do not assume either port is free or that a successful registration proves the application itself starts. Make an HTTP request using the port and route shown by your local service configuration:

$ curl --fail --silent --show-error 'http://127.0.0.1:8080/myapp/' > /tmp/myapp-response.html
$ sed -n '1,20p' /tmp/myapp-response.html

A successful request proves that something answered at that route; it does not validate every application page. If the request fails, inspect the service log and confirm the route, port, permissions and application prerequisites before changing the host file again.

5. Handle an existing name without overwriting it

add refuses to continue when /etc/xsp4/conf.d/$APP_NAME already exists. It prints a message asking you to change the application name. Treat that as a safety boundary: do not delete the directory merely to make a retry pass.

Inspect the current registration first:

$ sudo find "/etc/xsp4/conf.d/$APP_NAME" -maxdepth 1 -type f -print -exec sed -n '1,80p' {} \;

If the existing entry is the application you meant to update, edit its configuration only after backing it up and planning a service check. The admin command is a creator and remover, not a general editor. Keep a copy outside conf.d so a later update cannot treat it as another host file.

6. Remove a registration and recover from a mistake

Warning: del recursively removes the named directory under /etc/xsp4/conf.d. It does not delete APP_PATH, but a mistaken application name can remove the wrong host configuration. Confirm the target first:

$ sudo find "/etc/xsp4/conf.d/$APP_NAME" -maxdepth 2 -print
/etc/xsp4/conf.d/myapp
/etc/xsp4/conf.d/myapp/10_myapp

In this package version, del still requires a --path argument even though deletion does not use its value. Supply the original path to satisfy that argument check:

$ sudo mono-xsp4-admin del --path="$APP_PATH" --app="$APP_NAME"
done!
$ sudo test ! -e "/etc/xsp4/conf.d/$APP_NAME" && echo 'registration removed'
registration removed

The command regenerates debian.webapp and may restart XSP 4 again. If you removed the wrong entry, recreate its directory and host file from your backup, then run sudo mono-xsp4-update. Do not put an application directory inside /etc/xsp4/conf.d; that directory is for host configuration only.