This article has been updated for .NET 6 and RHEL 8 on 03/20/2022.
This article walks us through running a ASP.NET Core web application on Red Hat Enterprise Linux (RHEL) 8 using systemd. Here's what we'll cover: 1. Running ASP.NET Core using **systemd** 2. Adding **Systemd integration package** 3. Making ASP.NET Core **accessible externally** (Kestrel only, no reverse proxy) 4. Serving ASP.NET Core over **port 80 & 443** (Kestrel only, no reverse proxy)Your website will use HTTPS over 443, however, this tutorial will use the out-of-the-box development certificates, and not walk you through installing your own certificates for secure HTTPS communication.
The end goal is to serve ASP.NET Core directly via the built-in Kestrel webserver over port 80/443.This walkthrough should work for most .NET supported Linux distributions, not just RHEL, albeit with small modifications. This tutorial should also work for older versions of .NET too.
## Run ASP.NET Core using Systemd {#run-aspnet-core-using-systemd} Let's start by creating a new ASP.NET Core application using the web-template:mkdir ~/AspNetSite cd ~/AspNetSite dotnet new webWe'll be using this application throughout the walkthrough. Let's verify that the web application works:
dotnet run # Output should looks like this: # info: Microsoft.Hosting.Lifetime[0] # Now listening on: https://localhost:5001 # info: Microsoft.Hosting.Lifetime[0] # Now listening on: http://localhost:5000 # info: Microsoft.Hosting.Lifetime[0] # Application started. Press Ctrl+C to shut down. # info: Microsoft.Hosting.Lifetime[0] # Hosting environment: Development # info: Microsoft.Hosting.Lifetime[0] # Content root path: /home/yourusername/AspNetSiteIn the output you can find an HTTPS and an HTTP URL, take note of the HTTP URL for the next command. **Open a separate shell** (leave the other shell running) and use the curl HTTP-client to send an HTTP request to the application using the HTTP URL:
# while 'dotnet run' is running, open a new shell to run this curl command curl http://localhost:5000 # Output should be 'Hello World!'If the application works, go back to the first shell and stop the application by pressing ctrl + c.
sudo mkdir /srv/AspNetSite sudo chown yourusername /srv/AspNetSite/ dotnet publish -c Release -o /srv/AspNetSite/The published result contains an executable called AspNetSite which will run the application. Let's verify we can also run the published application:
/srv/AspNetSite/AspNetSite # output: # info: Microsoft.Hosting.Lifetime[14] # Now listening on: http://localhost:5000 # info: Microsoft.Hosting.Lifetime[14] # Now listening on: https://localhost:5001 # info: Microsoft.Hosting.Lifetime[0] # Application started. Press Ctrl+C to shut down. # info: Microsoft.Hosting.Lifetime[0] # Hosting environment: Production # info: Microsoft.Hosting.Lifetime[0] # Content root path: /home/yourusername/AspNetSite/To run services on Linux, Systemd uses 'service unit configuration' files to describe how to run services. Let's create the file AspNetSite.service inside our project so we can store it in source control along with our code. Add the following content to AspNetSite.service:
[Unit] Description=ASP.NET Core web template [Service] # will set the Current Working Directory (CWD) WorkingDirectory=/srv/AspNetSite # systemd will run this executable to start the service # if /usr/bin/dotnet doesn't work, use `which dotnet` to find correct dotnet executable path ExecStart=/usr/bin/dotnet /srv/AspNetSite/AspNetSite # to query logs using journalctl, set a logical name here SyslogIdentifier=AspNetSite # Use your username to keep things simple, for production scenario's I recommend a dedicated user/group. # If you pick a different user, make sure dotnet and all permissions are set correctly to run the app. # To update permissions, use 'chown yourusername -R /srv/AspNetSite' to take ownership of the folder and files, # Use 'chmod +x /srv/AspNetSite/AspNetSite' to allow execution of the executable file. User=yourusername # ensure the service restarts after crashing Restart=always # amount of time to wait before restarting the service RestartSec=5 # copied from dotnet documentation at # https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/linux-nginx KillSignal=SIGINT Environment=ASPNETCORE_ENVIRONMENT=Production Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false [Install] WantedBy=multi-user.target**Make sure to update the 'User' to your username.** Refer to the comments for an explanation of the specified options. For more information on the service unit configuration file, read the freedesktop manual page or the Red Hat documentation. Systemd expects all configuration files to be put under /etc/systemd/system/. Copy the service configuration file to /etc/systemd/system/AspNetSite.service and tell systemd to reload the configuration files.
sudo cp AspNetSite.service /etc/systemd/system/AspNetSite.service sudo systemctl daemon-reloadNow systemd is aware of the new 'AspNetSite' service. Using \``systemctl start AspNetSite`\` we can start the service.
sudo systemctl start AspNetSite sudo systemctl status AspNetSite # Output should be similar to below: # ● AspNetSite.service - ASP.NET Core web template # Loaded: loaded (/etc/systemd/system/AspNetSite.service; enabled; vendor preset: disabled) # Active: active (running) since Wed 2020-01-29 17:06:24 UTC; 13s ago # Main PID: 5187 (AspNetSite) # CGroup: /system.slice/AspNetSite.service # └─5187 /srv/AspNetSite/AspNetSite # # Jan 29 17:06:25 rhtest AspNetSite[5187]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:06:25 rhtest AspNetSite[5187]: Now listening on: http://localhost:5000 # Jan 29 17:06:25 rhtest AspNetSite[5187]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:06:25 rhtest AspNetSite[5187]: Now listening on: https://localhost:5001 # Jan 29 17:06:25 rhtest AspNetSite[5187]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:06:25 rhtest AspNetSite[5187]: Application started. Press Ctrl+C to shut down. # Jan 29 17:06:25 rhtest AspNetSite[5187]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:06:25 rhtest AspNetSite[5187]: Hosting environment: Production # Jan 29 17:06:25 rhtest AspNetSite[5187]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:06:25 rhtest AspNetSite[5187]: Content root path: /srv/AspNetSite**Due to the** `Restart=always` **option, systemd will restart our service in case it crashed.** But it will **not automatically start the service when the machine reboots**. To enable automatic startup, use the following command:
sudo systemctl enable AspNetSite
If everything is working correctly, we should be able to curl the application via localhost:5000:
curl http://localhost:5000 # Output should be 'Hello World!'The website is now running as a systemd service. There's a systemd-package provided by Microsoft to improve the integration with systemd. Let's set that up next. ## Add Systemd integration package {#add-systemd-integration-package} Microsoft recently added a package to better integrate with systemd. When the integration is installed, the application will notify systemd when it's ready and when it's stopping. Additionally, systemd will understand the different log levels that the application logs. Using the dotnet CLI, add the 'Microsoft.Extensions.Hosting.Systemd' (nuget) package:
dotnet add package Microsoft.Extensions.Hosting.SystemdNext, we'll need to add one line to the *Program.cs*, `builder.Host.UseSystemd()`:
var builder = WebApplication.CreateBuilder(args); builder.Host.UseSystemd(); var app = builder.Build(); app.MapGet("/", () => "Hello World!"); app.Run();For demonstration purposes of the logging integration, update the Program.cs file with the following code:
var builder = WebApplication.CreateBuilder(args); builder.Host.UseSystemd(); var app = builder.Build(); app.MapGet("/", () => { app.Logger.LogInformation("Information - Hello World"); app.Logger.LogWarning("Warning - Hello World"); app.Logger.LogError("Error - Hello World"); app.Logger.LogCritical("Critical - Hello World"); return "Hello World!"; }); app.Run();Lastly, we need to update the file AspNetSite.service to specify 'type=Notify':
[Unit] Description=ASP.NET Core web template [Service] Type=notify # will set the Current Working Directory (CWD) WorkingDirectory=/srv/AspNetSite # systemd will run this executable to start the service # if /usr/bin/dotnet doesn't work, use `which dotnet` to find correct dotnet executable path ExecStart=/usr/bin/dotnet /srv/AspNetSite/AspNetSite # to query logs using journalctl, set a logical name here SyslogIdentifier=AspNetSite # Use your username to keep things simple, for production scenario's I recommend a dedicated user/group. # If you pick a different user, make sure dotnet and all permissions are set correctly to run the app. # To update permissions, use 'chown yourusername -R /srv/AspNetSite' to take ownership of the folder and files, # Use 'chmod +x /srv/AspNetSite/AspNetSite' to allow execution of the executable file. User=yourusername # ensure the service restarts after crashing Restart=always # amount of time to wait before restarting the service RestartSec=5 # copied from dotnet documentation at # https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/linux-nginx KillSignal=SIGINT Environment=ASPNETCORE_ENVIRONMENT=Production Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false [Install] WantedBy=multi-user.targetLet's deploy all our changes. We'll need to publish the .NET app and stop/reload/start the systemd service:
sudo systemctl stop AspNetSite dotnet publish -c Release -o /srv/AspNetSite/ sudo cp AspNetSite.service /etc/systemd/system/AspNetSite.service sudo systemctl daemon-reload sudo systemctl start AspNetSiteThe application logs are being captured by systemd. We can query the logs using 'journalctl', here are some examples:
sudo journalctl -u AspNetSite #query all output, oldest to newest sudo journalctl -u AspNetSite -f #query all output and follow live sudo journalctl -u AspNetSite -r #query all output, newest to oldest sudo journalctl -u AspNetSite --since="2020-01-17 11:00:00" --until="2020-01-17 11:15:00" #filter by timeThe unit-flag (-u) allows us to filter by 'SyslogIdentifier' which we specified in 'AspNetSite.service'.
| LogLevel | Syslog level | systemd name |
| Trace/Debug | 7 | debug |
| Information | 6 | info |
| Warning | 4 | warning |
| Error | 3 | err |
| Critical | 2 | crit |
sudo journalctl -u AspNetSite -p 4 # Output should be emptyLet's first make a couple of HTTP request to the application using curl and then run the 'journalctl' query:
curl http://localhost:5000 curl http://localhost:5000 curl http://localhost:5000 sudo journalctl -u AspNetSite -p 4The 'journalctl' command should now return the different log statements we wrote 3 times.
The 'UseSystemd' function will not do anything when run outside of a systemd service. The implementation checks if the OS is a Unix system and whether the parent process is systemd.
If not, the systemd integration is skipped.
curl http://localhost:5000 # Output should be 'Hello World!' # try curl'ing using your machine's IP, to list IP's on RHEL use 'ip addr show' curl http://10.0.0.4:5000 # Output should be 'curl: (7) Failed to connect to 10.0.0.4 port 5000: Connection refused'
Out of the box, the application is configured to listen to http://localhost:5000 & https://localhost:5001. This works great for development, but we want to expose our application to other machines in the network or even to the internet. To serve our application outside of the localhost, we'll need to figure out the IP address that you want to serve your app on, and then tell ASP.NET Core to bind to the IP address and a port.
On RHEL, you can use the command \`ip addr show\` to list the IP addresses on your machine, while on other OS's, the command you'll need may be \`ifconfig\` or something else. Find the IP address that you'll send HTTP requests to from outside the machine, and take note of it. In my case, the IP address attached to my network interface in Azure is 10.0.0.4. I'll use this IP address throughout this article, however, keep in mind that your IP address may be different. In ASP.NET Core there are many ways to configure the URL's. We can **configure it through code, appsettings.json, environment variables, or command line arguments**.[Unit] Description=ASP.NET Core web template [Service] Type=notify # will set the Current Working Directory (CWD) WorkingDirectory=/srv/AspNetSite # systemd will run this executable to start the service # if /usr/bin/dotnet doesn't work, use `which dotnet` to find correct dotnet executable path ExecStart=/usr/bin/dotnet /srv/AspNetSite/AspNetSite # to query logs using journalctl, set a logical name here SyslogIdentifier=AspNetSite # Use your username to keep things simple, for production scenario's I recommend a dedicated user/group. # If you pick a different user, make sure dotnet and all permissions are set correctly to run the app. # To update permissions, use 'chown yourusername -R /srv/AspNetSite' to take ownership of the folder and files, # Use 'chmod +x /srv/AspNetSite/AspNetSite' to allow execution of the executable file. User=yourusername # ensure the service restarts after crashing Restart=always # amount of time to wait before restarting the service RestartSec=5 # copied from dotnet documentation at # https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/linux-nginx KillSignal=SIGINT Environment=ASPNETCORE_ENVIRONMENT=Production Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false # When using the out of the box ASP.NET Tempates, this environment variable will allow you to override # which IP & ports the Kestrel Web Server will listen to. Environment=ASPNETCORE_URLS=http://10.0.0.4:5000;https://10.0.0.4:5001 [Install] WantedBy=multi-user.target
You can also use an asterisk (*) instead of an IP address which will act as a wild card. The application will then listen to localhost and all IP-addresses assigned to the machine, however, this is a security risk, so it's best to explicitly specify the IP address you want to listen to.
Let's copy the updated configuration file and reload/restart the systemd service:sudo cp AspNetSite.service /etc/systemd/system/AspNetSite.service sudo systemctl daemon-reload sudo systemctl restart AspNetSite sudo systemctl status AspNetSite # Output should be similar to below: # ● AspNetSite.service - ASP.NET Core web template # Loaded: loaded (/etc/systemd/system/AspNetSite.service; enabled; vendor preset: disabled) # Active: active (running) since Wed 2020-01-29 17:17:48 UTC; 5s ago # Main PID: 5937 (AspNetSite) # CGroup: /system.slice/AspNetSite.service # └─5937 /srv/AspNetSite/AspNetSite # # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Now listening on: http://10.0.0.4:5000 # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Now listening on: https://10.0.0.4:5001 # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Application started. Press Ctrl+C to shut down. # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Hosting environment: Production # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Content root path: /srv/AspNetSite
Instead of http://localhost:5000, we can now see http://10.0.0.4:5000. Now that the application is bound to the machine's IP-address, we should be able to curl it via IP from within the machine:
# try curl'ing using your machine's IP, to list IP's on RHEL use 'ip addr show' curl http://10.0.0.4:5000 # Output should be 'Hello World!'Does this mean the website is accessible from outside the machine now?
sudo firewall-cmd --zone=public --add-port 5000/tcp --permanent sudo firewall-cmd --zone=public --add-port 5001/tcp --permanent sudo firewall-cmd --reloadNow the website will be accessible from other machines within the network.
/srv/AspNetSite/AspNetSite --urls "http://*:80;https://*:443" # Output: # crit: Microsoft.AspNetCore.Server.Kestrel[0] # Unable to start Kestrel. # System.Net.Sockets.SocketException (13): Permission denied # ...There are many ways to work around this restriction. ### Use a Reverse Proxy {#use-a-reverse-proxy} We can setup a reverse proxy to listen to port 80 & 443 and have it forward traffic to the ASP.NET Core application. This process is well documented by Microsoft: - Reverse proxy guide for Nginx by Microsoft - Reverse proxy guide for Apache by Microsoft This is a great option for many reasons, but we're not going to do this since our goal for this walkthrough is to stick to the built-in Kestrel server exclusively. ### Grant CAP_NET_BIND_SERVICE capability {#grant-capnetbindservice-capability} Using the following command, we can give the AspNetSite executable the **'CAP\_NET\_BIND\_SERVICE'** capability. This capability will allow the process to bind to well known ports.
sudo setcap CAP_NET_BIND_SERVICE=+eip /srv/AspNetSite/AspNetSite /srv/AspNetSite/AspNetSite --urls "http://*:80;https://*:443" # Output: # info: Microsoft.Hosting.Lifetime[0] # Now listening on: http://10.0.0.4:80 # info: Microsoft.Hosting.Lifetime[0] # Now listening on: https://10.0.0.4:443 # info: Microsoft.Hosting.Lifetime[0] # Application started. Press Ctrl+C to shut down. # info: Microsoft.Hosting.Lifetime[0] # Hosting environment: Production # info: Microsoft.Hosting.Lifetime[0] # Content root path: /home/yourusername/AspNetSiteEvery time the executable is updated the 'CAP\_NET\_BIND\_SERVICE' capability will be lost. We could make this command as part of a deployment script, but the **systemd service unit configuration files has an option called 'AmbientCapabilities'**.
[Unit] Description=ASP.NET Core web template [Service] Type=notify # will set the Current Working Directory (CWD) WorkingDirectory=/srv/AspNetSite # systemd will run this executable to start the service # if /usr/bin/dotnet doesn't work, use `which dotnet` to find correct dotnet executable path ExecStart=/usr/bin/dotnet /srv/AspNetSite/AspNetSite # to query logs using journalctl, set a logical name here SyslogIdentifier=AspNetSite # Use your username to keep things simple, for production scenario's I recommend a dedicated user/group. # If you pick a different user, make sure dotnet and all permissions are set correctly to run the app. # To update permissions, use 'chown yourusername -R /srv/AspNetSite' to take ownership of the folder and files, # Use 'chmod +x /srv/AspNetSite/AspNetSite' to allow execution of the executable file. User=yourusername # ensure the service restarts after crashing Restart=always # amount of time to wait before restarting the service RestartSec=5 # copied from dotnet documentation at # https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/linux-nginx KillSignal=SIGINT Environment=ASPNETCORE_ENVIRONMENT=Production Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false # When using the out of the box ASP.NET Tempates, this environment variable will allow you to override # which IP & ports the Kestrel Web Server will listen to. Environment=ASPNETCORE_URLS=http://10.0.0.4:80;https://10.0.0.4:443 # give the executed process the CAP_NET_BIND_SERVICE capability. This capability allows the process to bind to well known ports. AmbientCapabilities=CAP_NET_BIND_SERVICE [Install] WantedBy=multi-user.targetFor the last time, copy the *AspNetSite.service* file and reload/restart the AspNetSite service.
sudo cp AspNetSite.service /etc/systemd/system/AspNetSite.service sudo systemctl daemon-reload sudo systemctl restart AspNetSite sudo systemctl status AspNetSite # Output should be similar to below: # ● AspNetSite.service - ASP.NET Core web template # Loaded: loaded (/etc/systemd/system/AspNetSite.service; enabled; vendor preset: disabled) # Active: active (running) since Wed 2020-01-29 17:17:48 UTC; 5s ago # Main PID: 5937 (AspNetSite) # CGroup: /system.slice/AspNetSite.service # └─5937 /srv/AspNetSite/AspNetSite # # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Now listening on: http://10.0.0.4:80 # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Now listening on: https://10.0.0.4:443 # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Application started. Press Ctrl+C to shut down. # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Hosting environment: Production # Jan 29 17:17:48 rhtest AspNetSite[5937]: info: Microsoft.Hosting.Lifetime[0] # Jan 29 17:17:48 rhtest AspNetSite[5937]: Content root path: /srv/AspNetSiteThe web application is now listening to port 80 & 443, but the built-in firewall will still block traffic coming in over those ports. Update the built-in firewall and any other network security to allow traffic over port 80 & 443:
sudo firewall-cmd --zone=public --add-port 80/tcp --permanent sudo firewall-cmd --zone=public --add-port 443/tcp --permanent sudo firewall-cmd --reloadVisiting the website over port 80 using the browser should now return "Hello World!".
