xsp4(1)

📦 version 4.2, in debian bookworm, ubuntu jammy, ubuntu noble

✨ NAME ✨

okay so bestie, meet XSP — the Mono ASP.NET Web Server 💖 and it shows up as two whole icons: xsp4 and xsp42. yes it's giving legacy naming, we love her anyway 🎀

🌸 SYNOPSIS 🌸

xsp4 [options]

or

mod-mono-server [options]

or

fastcgi-mono-server [options]

💖 DESCRIPTION 💖

so like, XSP, mod-mono-server and fastcgi-mono-server are all hosts for ASP.NET-based applications. that's the whole vibe. they host. they serve. they slay 💅

If you run it as xsp4, the process is a minimalistic web server that hosts the ASP.NET runtime, and you can use it to test and debug web applications that use the System.Web facilities in Mono. this one is the move for testing and running small sites — but heads up, it does not offer everything a production web server offers. it's the cute lil studio apartment of web servers, not the whole mansion 🏠✨

mod-mono-server and fastcgi-mono-server are both ASP.NET runtime hosts that can talk to another web server — and at the time of this writing, Apache 1.3-2.2 were supported through mod_mono, plus several other web servers through FastCGI. this mechanism is way better for high-traffic servers or production systems, because it can integrate with the main HTTP server and leverage all of the optimizations and extensions of an existing server while still providing the ASP.NET runtime. main character energy fr fr 👑

You get to choose the communication channel used between mod_mono and mod-mono-server:

  • if you pass a --filename option, a unix socket is used 🦋
  • otherwise, you can give --port to use a TCP socket 🔥

🎀 OPTIONS 🎀

  • --address addr — sets the IP address to listen on. by default it's 0.0.0.0 for xsp4 and 127.0.0.1 for mod-mono-server. AppSettings key name: MonoServerAddress
  • --port PORT — changes the default port where the XSP server listens for requests. by default XSP listens on port 8080, and mod-mono-server has no default. AppSettings key name: MonoServerPort
  • --backlog N — the backlog of connections to set on the listener socket. by default this value is set to 500.
  • --minThreads N — the minimum number of threads the threadpool allocates. bump this up to better handle a sudden arrival of connections (the crowd rush, if you will 😭). the default value is determined by the mono runtime.
  • --filename file (mod-mono-server and fastcgi-mono-server) — the unix socket file name to listen on. default value: /tmp/mod_mono_server (for fastcgi-mono-server: /tmp/fastcgi-mono-server). AppSettings key name: UnixSocketFileName (for fastcgi-mono-server: MonoUnixSocket)
  • --root PATH — the root directory for XSP. the default is the directory where XSP is executed. the current directory will be changed to this one before creating any application. AppSettings key name: MonoServerRootDir
  • --appconfigfile FILENAME — adds application definitions from the XML configuration file. see the sample configuration file that comes with the server (sample.webapp) and the WEBAPP FILE FORMAT section below. AppSettings key name: MonoApplicationsConfigFile
  • --appconfigdir DIR — adds application definitions from all XML files found in the specified directory DIR. files must have the .webapp extension. AppSettings key name: MonoApplicationsConfigDir
  • --applications APPS — a comma separated list of virtual directory and real directory for all the applications we want to manage with this server. the virtual and real dirs are separated by a colon. the default value is /:.'... okay no, the default value is /:.' — wait, let me be exact: the default value is /:.' — ugh, one more time, the default value is /:.' — NO. deep breath. the default value is:
/:.

there we go 😭💀

Some examples:

'/:.'

The virtual / is mapped to the current directory.

'/blog:../myblog'

The virtual /blog is mapped to ../myblog.

'/:.,/blog:../myblog'

Two applications like the above ones are handled.

myhost.someprovider.net:/blog:../myblog

The virtual /blog at myhost.someprovider.net is mapped to ../myblog.

  • --master — this instance will be used by mod_mono to create ASP.NET applications on demand. if this option is provided, there is no need to provide a list of applications to start. this applies only to mod-mono-server.exe.
  • --nonstop — by default xsp4/mod-mono-server will stop processing requests when the return key is pressed. use this to avoid that behavior. (she does not take a break, periodt 💅)
  • --no-hidden — do not protect hidden files/directories from being accessed by clients. hidden files/directories are those with the Hidden attribute on Windows, and whose name starts with a dot on Unix. any file/directory below a hidden directory is inaccessible. this option turns the default behavior of protecting such locations off. if your application does not contain any hidden files/directories, you might want to use this option, since the checking process has a per-request cost. AppSettings key name: MonoServerCheckHiddenFiles (a boolean accepting 'true' or 'false')
  • --https — enables HTTPS support on the server. you must supply an X.509 certificate and a private key with either the --cert/--pkfile options, or with the --p12file (which combines both the certificate and the private key into a single file). 🔐

To use it you must first create an X.509 certificate for your server, for example:

$ makecert -r -eku 1.3.6.1.5.5.7.3.1 -n "CN=server" -p12 server.p12 s3kr3t
Mono MakeCert - version 1.1.9.0
X.509 Certificate Builder
Copyright 2002, 2003 Motus Technologies. Copyright 2004-2005 Novell. BSD licensed.

Success

Then you must pass the following flags to xsp4:

$ xsp4 --https --p12file server.p12 --pkpwd s3kr3t
This option is only valid for XSP. for mod_mono you should configure Apache for SSL/TLS.
  • --https-client-accept — like --https, this enables HTTPS support on the server. however, this option also sends an "invitation" to clients to provide client-certificates to authenticate themselves. clients are free to provide, or not, a client certificate. the web application can detect if a client certificate is used and react accordingly. most web browsers will not send a client certificate unless they have been explicitly requested to do so.
This option is only valid for XSP. for mod_mono you should configure Apache for SSL/TLS.
  • --https-client-require — like --https, this enables HTTPS support on the server. however, this option also requires clients to use client-certificates to authenticate themselves. clients who do not provide client certificates will receive an error. note that a client may send an empty certificate structure, so the web application should check the certificate content. 🙈
This option is only valid for XSP. for mod_mono you should configure Apache for SSL/TLS.
  • --p12file FILENAME — used to specify the PKCS#12 file to use. this file includes both the X.509 certificate and the private key required to encrypt the HTTP traffic.
This option is only valid for XSP. for mod_mono you should configure Apache for SSL/TLS.
  • --cert FILENAME — used to specify the server X.509 certificate file. this is normally used with the --pkfile.
This option is only valid for XSP. for mod_mono you should configure Apache for SSL/TLS.
  • --pkfile FILENAME — used to specify the path to the private keyfile. the PVK format isn't very secure and you should use the PKCS#12 format (the --p12file option) to store new private keys. ⚠️
This option is only valid for XSP. for mod_mono you should configure Apache for SSL/TLS.
  • --pkpwd PASSWORD — if your private key is password protected, PASSWORD is the password used to decode the private key. this option works for both PVK and PKCS#12 formats.
This option is only valid for XSP. for mod_mono you should configure Apache for SSL/TLS.
  • --protocol PROTOCOL — specifies which protocols are available for encrypting the communications. the possible values are Default, Tls and Ssl3. Ssl2 isn't supported. the default value is "Default", which auto-detects the client protocol and adjusts the server protocol accordingly.
This option is only valid for XSP. for mod_mono you should configure Apache for SSL/TLS.
  • --terminate (mod-mono-server only) — gracefully terminates a running mod-mono-server instance. all other options except --filename or --address and --port are ignored if this option is provided. bye bestie 👋
  • --version — displays version information and exits.
  • --help — shows the list of options and exits.
  • --verbose — prints extra messages. useful for debugging. (she's a yapper but it's for a good cause 🫶)
  • --pidfile FILE — writes the xsp4 PID to the specified file.

🦋 MONO RUNTIME OPTIONS 🦋

xsp4 and xsp42 are scripts that call mono. if you want to pass options to mono (for example, options to get line numbers in stack traces), you can use the MONO_OPTIONS environment variable when invoking xsp4 or xsp42. 💜

For example:

$ MONO_OPTIONS=--debug xsp42

🌈 DEFAULT INDEX FILES 🌈

you can choose which files are considered as index using the xsp4.exe.config configuration file, like this:

<appSettings>
<add key="MonoServerDefaultIndexFiles"
     value="index.aspx" />
</appSettings>

by default, it has index.aspx, Default.aspx, default.aspx, index.html and index.htm. the order matters. yes, literally. do not come for her ⭐

🍓 WEBAPP FILE FORMAT 🍓

the format of the .webapp files used for --appconfigfile and --appconfigdir is:

<apps>
<web-application>
        <name>{appname}</name>
        <vhost>{virtual host for application}</vhost>
        <vport>{port for the application}</vport>
        <vpath>{virtual directory in apache}</vpath>
        <path>{physical path to aspx files}</path>
        <!-- <enabled> is true by default -->
        <enabled>{true|false}</enabled>
</web-application>
</apps>

you can include any number of <web-application> nodes — one per ASP.NET application to run. go off, add as many as you want, no cap 👑

there's a sample.webapp file in the XSP samples directory, iykyk 🎀

👑 AUTHORS 👑

the Mono XSP server was written by Gonzalo Paniagua Javier (gonzalo@ximian.com). Fastcgi-mono-server was written by Brian Nickel <http://kerrick.wordpress.com>. legends, both of them 💖

💅 ENVIRONMENT VARIABLES 💅

  • MONO_ASPNET_NODELETE — if set to any value, temporary source files generated by ASP.NET support classes will not be removed. they will be kept in the user's temporary directory. (she's a hoarder, but a documented one 🫶)

🌸 FILES 🌸

  • Web.config, web.config — ASP.NET applications are configured through these files, and the configuration is done on a per-directory basis. for more information on this subject, see the http://www.mono-project.com/Config_system.web page.

💖 SEE ALSO 💖

okay bestie, here's the squad that runs with xsp4 — go read these when you wanna level up:

  • mono(1) — the runtime that's literally carrying the whole thing 🫶
  • dbsessmgr(1) — session storage manager vibes
  • asp-state(1) — the state service, keeping your sessions alive ngl
  • mod_mono(8) — the Apache module bestie
  • makecert(1) — for when you need to make a cert, iconic behaviour

For more info on creating certificates, they point you here (no cap, this is the link):

http://pages.infinit.net/ctech/20050701-1048.html

Also, the namespaces you'll be living in: System.Web and System.Web.Hosting — those two are the main characters of this whole story ✨

And http://www.asp.net is Microsoft's official site for ASP.NET, in case you wanted it straight from the source 👑

🌈 MORE INFORMATION 🌈

The Mono project (http://www.go-mono.com) is a collaborative effort led by Novell (http://www.novell.com) to implement an open source version of the .NET Framework. Slay, honestly. Open source supremacy 💅

🎀 MAILING LISTS 🎀

All the mailing lists are listed right here, go subscribe bestie:

http://www.mono-project.com/Mailing_Lists

That's the whole page, bestie — you made it to the end. So proud of you fr fr 🥹✨

This little beauty is xsp4, version 4.2, and it's been dated 21 Nov 2004 — a classic, an OG, a vintage icon. The page itself is xsp4(1). Drink some water, go forth, and serve those web apps 💖🦋🎀

📦 where this page comes from