Run Mono's ASP.NET Session State Server with asp-state4

asp-state4 is Mono's out-of-process session state server for ASP.NET, and it will happily drop every logged-in user's session the moment you stop it. This guide starts it, confirms it is listening on the right port, points an application at it, and stops it without leaving a stray process running or users stuck mid-checkout. The examples match asp-state4 from the installed mono-xsp4 package, version 4.2-2.5. Allow about fifteen minutes, plus time to arrange a service account or supervisor if this is going into production.

This is a stateful service: it holds session data in memory, so stopping it can end sessions and interrupt requests that depend on them. Test with a disposable application first. There is no command-line option for choosing a port or a config file: the wrapper passes its arguments straight to Mono, and the program rejects any it gets. The remoting configuration supplies the endpoint instead.

1. Confirm the installed interface

Run these read-only checks as your ordinary account. None of them need sudo:

$ command -v asp-state4
/usr/bin/asp-state4
$ dpkg-query -W -f='${Package} ${Version}\n' mono-xsp4
mono-xsp4 4.2-2.5
$ asp-state4 --help
ERROR: asp-state4 doesn't recognize any command line arguments!!!

Usage is:
    asp-state4

Notice the help output is unusual: the only supported invocation is argument-free. Do not borrow options from a different ASP.NET state-server implementation. The local manual describes the program as an out-of-process ASP.NET session state server and gives the StateServer connection-string shape.

Checkpoint: if your installed package version or help output differs from this, stop and read that host's manual before following this guide. Everything below is verified against the package shown above.

2. Inspect the endpoint configuration

The installed program loads /usr/lib/xsp/4.0/asp-state4.exe.config. Read it without changing it:

$ sed -n '1,220p' /usr/lib/xsp/4.0/asp-state4.exe.config
<configuration>
  <system.runtime.remoting>
    <application name="ASP.NET State Server">
      <service>
        <wellknown mode="Singleton" objectUri="StateServer" ... />
      </service>
      <channels>
        <channel ref="tcp" port="42424" />
      </channels>
    </application>
  </system.runtime.remoting>
</configuration>

On this installation, the TCP endpoint is port 42424 and the registered remoting object is StateServer. The XML above is abbreviated for readability. Treat this file as local packaging, not a universal Mono default: if an administrator changed the port, use the value in the file and make the application's connection string match it.

3. Start the server in the foreground

Start it as the account that should own the process. An unprivileged account is fine for port 42424, and preferable whenever the application does not require root:

$ asp-state4
Loaded configuration from /usr/lib/xsp/4.0/asp-state4.exe.config that contains
=============================================
... configuration contents ...
=============================================
Press <Enter> to stop...

The process stays in the foreground. Keep this terminal open while testing, or let a service supervisor manage it. That prompt is not a shell prompt: it means the server has loaded its configuration and is waiting.

In a second terminal, check the listener without touching service state:

$ ss -ltn | awk '$4 ~ /:42424$/ {print}'
LISTEN 0 128 0.0.0.0:42424 0.0.0.0:*

The address and queue columns can vary; what matters is that a TCP listener exists on the configured port. No line back means trouble, so read the first terminal's error, check the configuration, and see whether something else already owns the port:

$ ss -ltnp | grep ':42424'
$ printf 'listener check status: %s\n' "$?"

Do not fix a port conflict by changing only the application's connection string. Both sides must agree on the same endpoint, and the installed program takes its port from the remoting configuration, not from anything the application says.

4. Point an ASP.NET application at it

In the application's web.config, set the session mode to StateServer and use the server's address and configured port:

<configuration>
  <system.web>
    <sessionState mode="StateServer"
      stateConnectionString="tcpip=127.0.0.1:42424"
      stateNetworkTimeout="10" />
  </system.web>
</configuration>

The manual documents the same three settings: mode, stateConnectionString and stateNetworkTimeout. Use 127.0.0.1 when the application and the state server share a host. For a separate host, use the server's real name or address, restrict the TCP port with a host firewall, and never expose a session-state endpoint to the public internet.

Security boundary: session contents can include authentication and application data. The local remoting configuration uses a plain TCP channel and shows no transport encryption or authentication. Keep the endpoint on a trusted network, limit its source addresses, and get a security review before pointing a remote application at it.

5. Test a session, then check failure behaviour

Exercise a page that writes and reads a session value through your normal application test path. The exact page and output belong to your application, so a successful TCP connection is not proof that session serialisation works. Confirm a value survives a second request and that the application logs no state-provider exception.

When diagnosing a failure, check these three things independently:

$ grep -nE 'sessionState|stateConnectionString|stateNetworkTimeout' /path/to/application/web.config
$ ss -ltn | awk '$4 ~ /:42424$/ {print}'
$ ps -C asp-state4 -o pid,user,args

Do not edit the package configuration while the process is running, and do not guess at extra command-line flags: there are none.

6. Stop it and recover cleanly

Warning: stopping the process is service-disrupting. Every in-memory session goes with it, and requests that depend on the provider can fail until a new server is ready. Arrange a maintenance window or drain the application first.

Return to the terminal running asp-state4 and press Enter: the program prints that stop prompt for exactly this purpose. Then confirm the process and listener are both gone:

$ ps -C asp-state4 -o pid,user,args
  PID USER     COMMAND
$ ss -ltn | awk '$4 ~ /:42424$/ {print}'
$ printf 'listener check status: %s\n' "$?"
listener check status: 0

To recover after an accidental stop, start asp-state4 again with the same configuration, confirm the listener, then retest a session request. There is no persistent session database here to restore. If sessions genuinely need to survive process restarts, that means choosing a different session-state provider, not hoping this one can recover them.

Done means