Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Below is a list of guides for Health Checks in Umbraco.
Checks if your site is allowed to be IFRAMEd by another site and thus would be susceptible to click-jacking.
This health check can be fixed by adding a header before the response is started.
Preferable you use a security library like NWebSec.
If you take a NuGet dependency on NWebsec.AspNetCore.Middleware/, you can use third extension methods on IApplicationBuilder
.
Avoid third-party library dependency by using custom middleware added to the request pipeline.
Health Checks are used to determine the state of your Umbraco project. Learn more about each of them in this section.
The Settings section of the Umbraco backoffice holds a dashboard named "Health Check". It is a handy list of checks to see if your Umbraco installation is configured according to best practices. It's possible to add your custom-built health checks.
For inspiration when building your checks you can look at the checks we've built into Umbraco, as well as our guides. Some examples will follow in this document.
Umbraco comes with the following checks by default:
Category Configuration
Notification Email Settings (id: 3E2F7B14-4B41-452B-9A30-E67FBC8E1206
) - checks that the "from" email address used for email notifications has been changed from its default value
Category Data Integrity
Database data integrity check (id: 73DD0C1C-E0CA-4C31-9564-1DCA509788AF
) - checks for various data integrity issues in the Umbraco database
Category Live Environment
Debug Compilation Mode (id: 61214FF3-FC57-4B31-B5CF-1D095C977D6D
) - should be set to debug="false"
on your live site
Runtime Mode (id: 8E31E5C9-7A1D-4ACB-A3A8-6495F3EDB932
) - should be set to Production
on your live site
Category Permissions
Folder & File Permissions (id: 53DBA282-4A79-4B67-B958-B29EC40FCC23
) - checks that the folders and files set with write permissions that are either required or recommended can be accessed
Category Security
Application URL Configuration (id: 6708CA45-E96E-40B8-A40A-0607C1CA7F28
) - checks if the Umbraco application URL is configured for your site.
Click-Jacking Protection (id: ED0D7E40-971E-4BE8-AB6D-8CC5D0A6A5B0
) - checks to see if a header or meta-tag is in place to indicate whether the site can be hosted in an IFRAME. Normally this is best set to deny permission for this to be done, to prevent what is known as click-jacking attacks
Content/MIME Sniffing Protection (id: 1CF27DB3-EFC0-41D7-A1BB-EA912064E071
) - checks that your site contains a header used to protect against Multipurpose Internet Mail Extensions (MIME) sniffing vulnerabilities
Cookie hijacking and protocol downgrade attacks Protection (HSTS) (id: E2048C48-21C5-4BE1-A80B-8062162DF124
) - checks if your HTTPS site contains the Strict-Transport-Security Header (HSTS). If not - adds with a default of 18 weeks
Cross-site scripting Protection (id: F4D2B02E-28C5-4999-8463-05759FA15C3A
) - checks for the presence of the X-XSS-Protection-header
Excessive Headers (id: 92ABBAA2-0586-4089-8AE2-9A843439D577
) - checks to ensure that various headers that can provide details about the technology used to build and host the website have been removed
HTTPS Configuration (id: EB66BB3B-1BCD-4314-9531-9DA2C1D6D9A7
) - to determine if the current site is running on a secure connection
UseHttps check - when the site is running on HTTPS, Umbraco.Cms.Core.Configuration.Models.GlobalSettings.UseHttps
needs to be enabled to secure the backoffice. The setting can be found under Umbraco:CMS:Global
in the appsettings.json
file
Category Services
SMTP Settings (id: 1B5D221B-CE99-4193-97CB-5F3261EC73DF
) - checks that an Simple Mail Tranfer Protocol (SMTP) server is configured and is accepting requests for sending emails
Each check returns a message indicating whether or not the issue in question has been found on the website installation. This could be an error that should be fixed, or a warning you should be aware of.
Some of them can also be rectified via the dashboard, by clicking the Fix button and in some cases providing some required information. These changes usually involve writing to configuration files that will often trigger a restart of the website.
As well as viewing the results of health checks via the Settings section dashboard, you can set up the checks to be run on a schedule and be notified of the results by email. It's also possible to disable certain checks if they aren't applicable in your environment.
For more information, see the Reference > Configuration > Health checks article.
You can build your own health checks. There are two types of health checks you can build: configuration checks and general checks.
Each health check is a class that needs to have a HealthCheck
attribute. This attribute has a few things you need to fill in:
GUID - a unique ID that you've generated for this specific check
Name - give it a short name so people know what the check is for
Description - describes what the check does in detail
Group - this is the category for the check if you use an existing group name (like "Configuration") the check will be added in that category, otherwise a new category will appear in the dashboard
These are small checks that take an IConfiguration key and confirm that the value that's expected is there. If the value is not correct, there will be a link to a guide on how to set this value correct.
A configuration check needs to inherit from Umbraco.Cms.Core.HealthChecks.Checks.AbstractSettingsCheck
A configuration check needs the HealthCheck
attribute as noted at the start of this document
ReadMoreLink
is a link to an external guide that will help you to troubleshoot any problems
ValueComparisonType
can either be ValueComparisonType.ShouldEqual
or ValueComparisonType.ShouldNotEqual
ItemPath
is the IConfiguration key path leading to the configuration value that you want to verify
Values
is a list of values that are available for this configuration item - in this example it can be RemoteOnly
or On
, they're both acceptable for a live site.
For checks using the ShouldEqual
comparison method, make sure to set one of these values to IsRecommended = true
.
Where ShouldNotEqual
is used the fix will require the user to provide the correct setting
CurrentValue
is the current value from the configuration setting
CheckSuccessMessage
and CheckErrorMessage
are the messages returned to the user
It is highly recommended to use the LocalizedTextService
so these can be localized. You can add the text in ~/Config/Lang/en-US.user.xml
(or whatever language you like)
This can be anything you can think of, the results and the rectify action are completely under your control.
A general check needs to inherit from Umbraco.Cms.Core.HealthChecks.HealthCheck
A general check needs the HealthCheck
attribute as noted at the start of this document
All checks run when the dashboard is loaded, this means that the GetStatus()
method gets executed
You can return multiple status checks from GetStatus()
A status check returns a HealthCheckStatus
If a HealthCheckStatus
has a HealthCheckAction
defined then the "Fix" button will perform that action once clicked
Sometimes, the button to fix something should not be called "Fix", change the Name
property of a HealthCheckAction
to provide a better name
HealthCheckAction
has a Description
property so that you can provide information on what clicking the "Rectify" button will do (or provide links to documentation, for example)
HealthCheckStatus
has a few result levels:
StatusResultType.Success
StatusResultType.Error
StatusResultType.Warning
StatusResultType.Info
A HealthCheckAction
needs to provide an alias for an action that can be picked up in the ExecuteAction
method
It is highly recommended to use the LocalizedTextService
so text can be localized. You can add the text in ~/Config/Lang/en-US.user.xml
(or whatever language you like)
An example check:
Health check notifications can be scheduled to run periodically and notify you of the results. Included with Umbraco is a notification method to deliver the results via email. In a similar manner to how it's possible to create your health checks, you can also create custom notification methods to send the message summarising the status of the health checks via other means. Again, for further details on implementing this please refer to the existing notification methods within the core code base.
Each notification method needs to implement the core interface IHealthCheckNotificationMethod
and, for ease of creation, can inherit from the base class NotificationMethodBase
, which itself implements the IHealthCheckNotificationMethod
interface. The class must also be decorated with an instance of the HealthCheckNotificationMethod
attribute. There's one method to implement - SendAsync(HealthCheckResults results)
- which is responsible for taking the results of the health checks and sending them via the mechanism of your choice.
The following example shows how the core method for sending notification via email is implemented:
If a custom configuration is required for a custom notification method, the following extract can be merged in the appsettings.json
file, which will enable the email notification method to be configured:
If you want to get the notifications by email, Simple Mail Tranfer Protocol (SMTP) settings should also be configured in the same JSON file.
This header is non-standard and should not be used.
For more information about the X-XSS-Protection header, and why it should not be used, see MDN web docs.
This health check can be fixed by ensuring no middleware adds the header.
Checks that your site contains a header used to protect against Multipurpose Internet Mail Extensions (MIME) sniffing vulnerabilities.
This health check can be fixed by adding a header before the response is started.
Preferable you use a security library like NWebSec.
If you take a NuGet dependency on NWebsec.AspNetCore.Middleware/, you can use third extension methods on WebApplication
.
If you do not like to have a dependency on third party libraries, you can add the following custom middleware to the request pipeline.
First create the middleware class:
Next register it in Program.cs
Leaving debug compilation mode enabled can severely slow down a website and take up more memory on the server.
This health check can be fixed by providing configuration on the following path: Umbraco:CMS:Hosting:Debug
.
This configuration can be setup in a configuration source of your choice. This guide shows how to set it up in one of the JSON file sources.
The following JSON needs to be merged into one of your JSON sources. By default the following JSON sources are used: appSettings.json
and appSettings.<environment>.json
, e.g. appSettings.Development.json
or appSettings.Production.json
.
One example that can be used for production:
Checks to see if your site reveals information in its headers that gives away unnecessary details about the technology used to build and host it.
This health check can be fixed by removing headers before the response is started.
Be aware these headers are often added by the server and not by the application.
Unless you publicly expose the Kestrel server (not recommended by Microsoft), you can't handle this directly in middleware.
For IIS you will need to manipulate web.config
(If you don't have web.config
already in your project you will need to add it at the root). Ensure to remove the custom X-Powered-By
and Server
header as shown in the following example.
The removeServerHeader
attribute is added in IIS 10.0 and does not work in versions of Windows prior to Windows Server version 1709 or Windows 10 version 1709.
By default Kestrel will only expose the Server
header. To disable this, you have to configure Kestrel in Program.cs
. You can use the UseKestrel
extension method on WebApplicationBuilder
like in the following example.
Check to make sure a fixed application URL is specified. This URL is for example used when sending emails from backoffice. If this is not specified in configuration, Umbraco gets the application URL from last host used to request the application
This health check can be fixed by providing configuration on the following path: Umbraco:CMS:WebRouting:UmbracoApplicationUrl
.
This configuration can be setup in a configuration source of your choice. This guide shows how to set it up in one of the JSON file sources.
The following JSON needs to be merged into one of your JSON sources. By default the following JSON sources are used: appSettings.json
and appSettings.<environment>.json
, e.g. appSettings.Development.json
or appSettings.Production.json
.
One example that can be used in production
If the site is hosted on Umbraco Cloud, changing the above configuration will have no effect. The site will always use the URL set in the`umbraco-cloud.json` file, which can not be changed.
Checks that the web server folder and file permissions are set correctly for Umbraco to run.
This health check can be fixed by ensuring that the process running Umbraco also has write access to the listed folders and files.
Here's an example of how to adjust permissions for a folder. This process works the same way for files.
First we see an example of an error from the health check
To fix this, we find the specified folder, from the report and choose Properties
and the Security
tab.
From here you can edit the permissions for a specific user or user group.
For security reasons we recommend only giving write access to the required users or groups.
Checks if your site is configured to work over HTTPS and if the Umbraco related configuration for that is correct.
This health check checks a couple of things.
First of all, it ensures that your website is running on HTTPS using a valid certificate.
Furthermore, it is used to specify the configuration on the following path: Umbraco:CMS:Global:UseHttps
.
This configuration can be setup in a configuration source of your choice. This guide shows how to set it up in one of the JSON file sources.
The following JSON needs to be merged into one of your JSON sources. By default the following JSON sources are used: appSettings.json
and appSettings.<environment>.json
, e.g. appSettings.Development.json
or appSettings.Production.json
.
One example that can be used:
If notifications are used, the 'from' email address should be specified and changed from the default value.
This health check can be fixed by providing configuration on the following path: Umbraco:CMS:Content:Notifications:Email
.
This configuration can be setup in a configuration source of your choice. This guide shows how to set it up in one of the JSON file sources.
The following JSON needs to be merged into one of your JSON sources. By default the following JSON sources are used: appSettings.json
and appSettings.<environment>.json
, e.g. appSettings.Development.json
or appSettings.Production.json
.
One example that can be used:
Checks that valid settings for sending emails are in place.
This health check can be fixed by providing configuration on the following path: Umbraco:CMS:Global:Smtp
This configuration can be setup in a configuration source of your choice. This guide shows how to set it up in one of the JSON file sources.
The following JSON needs to be merged into one of your JSON sources. By default the following JSON sources are used: appSettings.json
and appSettings.<environment>.json
, e.g. appSettings.Development.json
or appSettings.Production.json
.
An example that can be used on localhost, is if you have a local Simple Mail Transfer Protocol (SMTP) server running during development. This could be a tool like Smtp4dev.
Learn about the health checks that check for cookie hijacking and protocol downgrade attacks protection.
Checks if your site, when running with HTTPS, contains the Strict-Transport-Security Header (HSTS).
This health check can be fixed by adding the Strict-Transport-Security
header to responses. The header tells browsers that future requests should be made over HTTPS only.
Enabling HSTS on a domain will cause browsers to only use HTTPS (not HTTP) to communicate with your site. Only enable HSTS on domains that can, and should, use HTTPS exclusively.
ASP.NET Core implements HSTS with the UseHsts
extension method.
You can add UseHsts
after the env.IsDevelopment()
check-in Program.cs
.
This example only enables HSTS if the app is not running in development mode. UseHsts
isn't recommended in development because the HSTS settings are highly cacheable by browsers.
Full details of UseHsts
, and additional configuration, can be found in the ASP.NET Core documentation.