.net 7.0 kestrel appsettings.json configuration for unix sockets

Question

I have an open-source service application written in c#, running on .net 7, on Linux, which exposes an HTTP service, using Kestrel, to provide some monitoring endpoints for application state and important metrics for monitoring the application. It is configured to listen on a TCP endpoint, in appsettings.json, and that's great for when that's the desired configuration.

I also want to have Kestrel be able to listen on unix sockets, for reverse-proxy setups, among other reasons, at a specific path.

I can do it in code, fairly easily, but I would prefer to be able to configure it using the Kestrel section of my appsettings.json, as is done for the TCP socket listener, so end-users of the application can use standard configuration, rather than settings specific to just this application, that then get consumed in code to make kestrel listen at the desired socket path.

Documentation on how to do that seems to be non-existent, after many hours of scouring the net, including SO, Microsoft Learn, and numerous blogs.

Does anybody know how to configure Kestrel to listen on unix sockets at a specific socket path using appsettings.json?

Here's how the configuration is being given to Kestrel:

public static Task Main(string[] args)
{
    // ...
    WebApplicationBuilder serviceBuilder = WebApplication.CreateBuilder( );
    // ...
    serviceBuilder.WebHost
                  .UseKestrel( ConfigureKestrelOptions );
    // ...
}
      
private static void ConfigureKestrelOptions( WebHostBuilderContext builderContext, KestrelServerOptions kestrelOptions )
{
    kestrelOptions.Configure(_configurationRoot!.GetRequiredSection("Monitoring").GetSection("Kestrel") )
                  .Load( );
}

One attempted configuration was this:

{
  "Monitoring": {
    "Kestrel": {
      "AllowedHosts": "*",
      "Endpoints": {
        "HttpMonitoringEndpoint": {
          "Url": "http://*:60765"
        },
        "UnixSocketMonitoringEndpoint": {
          "SocketPath": "/run/myapp/monitor.sock"
        } 
      }
    }
  }
}

I have also tried putting the unix socket endpoint in a "UnixSocketEndpoints" and "UnixDomainSocketEndpoints" section, instead of "Endpoints." Those result in a unix socket being opened, but at a random temporary path, rather than the path specified.

You can't put everything as configuration. There has to be some code... perhaps if you show us the code that you want in config we can advise, as you've found there's not a lot of supporting documentation. — Jeremy Thompson, Aug 09 '23 at 01:36
An IConfigurationSection object is created from a call to GetSection("Kestrel") on the IRootConfiguration object loaded from the json. It is passed in the call to Configure(). I'll update the question with what's being done for the attempt to do it purely with JSON (since doing it purely in code works, but is just not what I'd prefer to do). — dodexahedron, Aug 09 '23 at 01:40
Ultimately, the c# to make it listen on a specific socket path is just two more lines of code (one for a conditional and one for the call to UnixSocketEndpoint(socketPath), but I just dislike the idea of having settings that aren't standard, ya know? If there's a way to achieve it purely in config, that's my preference, especially since that means the user can open up as many listeners as they want wherever they want, rather than me having to deal with those edge cases in code that is ostensibly redundant with what configuration SHOULD be able to do and does do for TCP endpoints. — dodexahedron, Aug 09 '23 at 02:04
Side note: We could really use a JSON schema for all possible Kestrel options. That, also, does not exist anywhere that I could find, though it seemingly _should_ be able to use anything that matches the classes used for configuration, since it's all just done with an IConfiguration binder. But even that class hierarchy is rather difficult to grok. Maybe I'll go suggest that on github for .net... — dodexahedron, Aug 09 '23 at 02:14
What's more... In the code for KestrelServerOptions.cs in the .net 7.0.9 source, it literally uses the same classes to open the unix sockets. See https://github.com/dotnet/aspnetcore/blob/v7.0.9/src/Servers/Kestrel/Core/src/KestrelServerOptions.cs and https://github.com/dotnet/aspnetcore/blob/v7.0.9/src/Servers/Kestrel/Core/src/ListenOptions.cs — dodexahedron, Aug 09 '23 at 02:23

score 1 · Answer 1 · answered Aug 09 '23 at 07:32

After going over the current source code for .net 7.0.9, in github, following every function call during the loading of configuration, I figured out what needed to be done.

The relevant source files for kestrel configuration are these:

First, there's the KestrelServerOptions class, which Kestrel uses, both for configuration in code and from ConfigurationProviders that can provide IConfigurationSections to Kestrel.

Following the code around eventually leads you to realizing that the "Endpoints" collection in the JSON is made up of instances of the EndpointConfiguration class, which both represents what can be defined in configuration for items in the "Endpoints" section, as well as what can be done in code, for an abstract "Endpoint."

All Endpoints have a ListenOptions property, which defines the specific settings each EndPoint entry can have, such as the familiar options Url and Protocols, among others. That property is of a type with the same name, located in ListenOptions.cs.

If you combine all of that and apply how those classes are structured to the configuration, you end up with something like this (TCP endpoint also included to show similarity):

{
  "Endpoints": {
    "HttpMonitoringEndpoint": {
      "Url": "http://*:60763"
    },
    "UnixSocketMonitoringEndpoint": {
      "Url": "http://unix:/path/to/my.sock"
    }
  }
}

This works, and creates a unix socket at the specified Url.

This can, of course, be placed in any part of your appsettings.json (or other json file you load), so long as the IConfigurationSection you give to Kestrel, in the call to Configure() is that specific section.

Notes:

The .net code for the KestrelConfigurationLoader will ignore anything between the unix: and the first slash. If the socket path is not rooted, you'll get an exception.

You must also make sure the directory the socket file is going to be placed in already exists, or you'll get this exception:

Unhandled exception. System.Net.Sockets.SocketException (99): Cannot assign requested address

Key is to note that 99 is an errno value as defined in libc, which is EADDRNOTAVAIL.

.net will not create any directories for you, for this, so just be sure the directory you're placing the socket file in already exists and that the account/group your process is executing as has appropriate permissions to the directory.

.net 7.0 kestrel appsettings.json configuration for unix sockets

1 Answers1