Run a Small ASP.NET Site with xsp4 on a Local Port

You need to preview an old Mono ASP.NET site, and xsp4 will serve it from a chosen directory on a local port in under a minute. This guide binds it safely, checks it is actually listening, and flags the one thing you must never do with its default address. It uses xsp4 from Debian package mono-xsp4 4.2-2.5, which the installed manual identifies as XSP 4.2.

Allow about fifteen minutes if the application already exists. You need a shell, a readable ASP.NET application directory, and permission to read the files it contains. Run the server as your ordinary user; you should not need sudo for a development port above 1024.

Checkpoint: This guide changes only the foreground process and its listening socket. Stop it with Ctrl-C; there is no service installation or persistent configuration to undo afterwards.

1. Confirm the installed command

Check which executable will run and record the package version:

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

The local manual documents xsp4 as a minimal web server for testing, debugging and small sites, not a replacement for a production HTTP server. The installed program on this machine currently fails before option processing with a Mono TypeLoadException when asked for --version or --help. If the same happens on your host, fix the Mono runtime and package compatibility first; changing XSP's arguments will not fix an error raised during startup.

2. Choose the application directory

By default, XSP uses the directory it was run from as its root. Make that choice explicit with --root, so a later change of working directory does not silently serve a different tree:

$ APP_ROOT=/srv/example-app
$ test -d "$APP_ROOT" && test -r "$APP_ROOT" && printf '%s\n' 'application root is readable'
application root is readable

Replace /srv/example-app with the directory containing the application files. The --root option changes XSP's current directory to that path before it creates an application; it does not copy, install or modify the application itself.

If the directory contains an index file, XSP checks these names by default, in order: index.aspx, Default.aspx, default.aspx, index.html and index.htm. A missing index is not proof the server failed; request a known file, or configure a different default through xsp4.exe.config.

3. Bind to loopback and a development port

The documented default address for XSP is 0.0.0.0, which listens on every IPv4 interface, a poor default for a test site containing source, configuration or half-finished endpoints. Bind to loopback explicitly and choose a port above 1024:

$ xsp4 --root "$APP_ROOT" --address 127.0.0.1 --port 8080

This is an ordinary foreground command that keeps the terminal occupied while the server runs. The default port is already 8080, but specifying it makes the command easier to review and avoids confusion if something else is already using that port.

Security boundary: Do not swap 127.0.0.1 for 0.0.0.0 just to let a remote browser reach the site. That exposes the development server to the network. If remote access is genuinely required, put a controlled firewall and a production-grade front end in front of it, and review exactly which files XSP can serve first.

4. Verify the listener from another terminal

Leave XSP running and open a second terminal. Check the TCP listener:

$ ss -ltn | grep ':8080 '
LISTEN 0      500          127.0.0.1:8080       0.0.0.0:*

The exact spacing and receive queue values can differ. What matters is LISTEN, 127.0.0.1:8080, and the documented default backlog of 500 unless you supplied --backlog. If nothing appears, look at the first terminal: a port collision, unreadable root or runtime error is more useful there than a browser's generic failure page.

Request a harmless known file if your application has one:

$ curl --fail http://127.0.0.1:8080/index.html

Use the actual path and file name for your application. A successful response proves the HTTP request reached XSP and that the application root exposed that file. It does not prove every ASP.NET route, dependency or configuration setting works.

5. Map more than one application only when needed

The default application mapping is /:.: virtual root / maps to the current directory, which becomes the explicit --root directory in the earlier command. To expose a second tree at /blog, provide a comma-separated list with a colon between each virtual and real path:

$ xsp4 --root "$APP_ROOT" --address 127.0.0.1 --port 8080 \
    --applications "/:$APP_ROOT,/blog:/srv/example-blog"

Keep the value quoted. The colon separates the virtual path from the physical path, and the comma separates applications. The real directories must exist and be readable by the user running XSP; this option maps content, it does not create either directory.

6. Handle hidden files and stop cleanly

XSP protects hidden files and directories by default. On Unix, that includes names beginning with a dot, and content below a hidden directory is inaccessible. Keep this protection on unless you have a specific, reviewed reason not to. The --no-hidden option disables it and adds a per-request security decision to your application, so do not reach for it as a troubleshooting reflex.

Press Ctrl-C in the server terminal when testing is done. If you started with --nonstop, XSP avoids stopping when the return key is pressed, but it remains a foreground process you can interrupt. If you used a --pidfile, remove that stale PID file only after confirming the process has stopped, and only if your surrounding tooling does not already manage it.

Done means