Allows you to configure the basic authentication settings for Umbraco. A basic authentication section fully populated with default values can be seen here:

"Umbraco": {
  "CMS": {
    "BasicAuth": {
      "AllowedIPs": [],
      "Enabled": false,
      "RedirectToLoginPage": false,
      "SharedSecret": {
        "HeaderName": "X-Authentication-Shared-Secret",
        "Value": null
      }
    }
  }
}

AllowedIPs

This is a comma-separated list of IP addresses you want to limit where the requests can come from.

Enabled

If the value is set to true, the basic authentication is enabled. By default, the value is set to false.

RedirectToLoginPage

If the value is set to true, instead of showing the basic authentication popup in the browser, the user is redirected to the login page. This is required for external logins to work. By default, the value is set to false.

SharedSecret

A shared secret can be sent using an HTTP header to bypass the basic authentication. This can be valuable for server-to-server communication.

HeaderName

The header name used to compare the shared secret. By default, the value is set to X-Authentication-Shared-Secret.

Value

The value of the shared secret. Must be a string longer than 0 characters to be enabled. The default value is null.

This section contains configurations regarding debugging, and should therefore only be used in development.

The debug section has two settings you can configure, "LogIncompletedScopes" and "DumpOnTimeoutThreadAbort", both of these are false by default:

"Umbraco": {
  "CMS": {
    "Debug": {
      "DumpOnTimeoutThreadAbort": false,
      "LogIncompletedScopes": false
    }
  }
}

Log incompleted scopes

If this value is set to true, any scope that gets disposed without first being completed will trigger a log entry containing the stacktrace.

DumpOnTimeoutThreadAbort

If this value is set to true, a memory dump will be taken if a thread aborts due to a timeout. This dump will be saved to /umbraco/Data/MiniDump.

The connection strings settings section contains the connection string to the database Umbraco will connect to. This section is similar to what is used by default in .NET Core. The important thing is that the key for the connection string Umbraco will use is "umbracoDbDSN". It is also important to know that this section is outside the Umbraco.CMS section, and is therefore in the root of the config.

An connection strings config can look like this:

{
  "ConnectionStrings": {
    "umbracoDbDSN": "Data Source=|DataDirectory|/Umbraco.sqlite.db;Cache=Private;Foreign Keys=True;Pooling=True",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.SQLite"
  }
}

The connection string used here is an SQLite connection string, that will connect to a data in the file Umbraco.sqlite.db located in /umbraco/Data .

Umbraco currently supports using either a Microsoft SQL Server or a SQLite database. Both of these options will have different connection strings. For more information about the specific connection strings, see:

• SQL Server 2019 connection strings

• SQLite connection strings

Provider name

Because Umbraco cannot determine the provider name from the connection string in all cases. Umbraco follows Microsoft's convention for provider names, which involves specifying it as a postfix in the connection string name.

Allows you to configure the behavior of data types.

{
  "Umbraco": {
    "CMS": {
      "DataTypes": {
        "CanBeChanged": "True"
      }
    }
  }
}

CanBeChanged

Gets or sets a value indicating if data types can be changed after they've been used.

Valid values:

• "True"

  • Allows data types to be changed after creation. This can lead to data on content is not valid on the Data Type.

• "False"

  • Disallow Data Type changes. (Recommeded value, unless you really know what you are doing)

• "FalseWithHelpText"

  • Disallow Data Type changes, but show the users a help text so they understand why.

Since the majority of Examine configuration takes place in code, this section is small and contains only one setting to change: LuceneDirectoryFactory. This setting allows you to change the behavior of the ExamineIndexes directory.

This section has a default value, and does not need to be configured, configuring Examine might look something like this:

"Umbraco": {
  "CMS": {
    "Examine": {
      "LuceneDirectoryFactory": "Default"
    }
  }
}

This is how Examine is configured by default. There is three different types of Lucene directory factories:

• Default - The index will operate from the default location: umbraco/Data/TEMP/ExamineIndexes

• SyncedTempFileSystemDirectoryFactory - The index will operate on a local index created in the processes %temp% location and will replicate back to main storage in umbraco/Data/TEMP/ExamineIndexes

• TempFileSystemDirectoryFactory - The index will operate only in the processes %temp% directory location

Filesystem providers are configured via code, you can either configure it in a composer, or in the Program.cs file.

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Infrastructure.DependencyInjection;
using IHostingEnvironment = Umbraco.Cms.Core.Hosting.IHostingEnvironment;

namespace FilesystemProviders;

public class FilesystemComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder) =>
        builder.SetMediaFileSystem(factory =>
        {
            IHostingEnvironment hostingEnvironment = factory.GetRequiredService<IHostingEnvironment>();
            var folderLocation = "~/CustomMediaFolder";
            var rootPath = hostingEnvironment.MapPathWebRoot(folderLocation);
            var rootUrl = hostingEnvironment.ToAbsolute(folderLocation);

            return new PhysicalFileSystem(
                factory.GetRequiredService<IIOHelper>(),
                hostingEnvironment,
                factory.GetRequiredService<ILogger<PhysicalFileSystem>>(),
                rootPath,
                rootUrl);
        });
}

By default Umbraco will save Media in a folder called /media within the webroot on the Physical file system. The code snippet above will change the location to instead save the media in a folder called /CustomMediaFolder within the webroot.

The media provider can be of many types, for example in case you want to store media on Azure, Amazon or even DB. But the provider that comes by default with the installation of Umbraco is the PhysicalFileSystem provider.

PhysicalFileSystem Configuration

The physical file system provider manages the interaction of Umbraco with the local file system. It can be configured for two different scenarios:

• Media files stored inside a virtual folder of the site

• Media files stored somewhere else outside of the site and accessed via a custom URL

Virtual Folder

To configure the PhysicalFileSystem for a virtual folder, create a new filesystem with a root path and URL within the wwwroot folder. Refer to the example above and Extending FileSystemProviders for more information.

Physical path

There are a few more steps involved if you want to store the media files in a separate folder outside the webroot.

First you must register the folder as a static file provider in your Program.cs file like so:

...
WebApplication app = builder.Build();
app.UseStaticFiles(new StaticFileOptions
    {
        FileProvider = new PhysicalFileProvider(Path.Combine("C:", "storage", "umbracoMedia")),
        RequestPath = "/CustomPath"
    });

Now you can register the folder as the media filesystem

using System.IO;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Hosting;
using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Infrastructure.DependencyInjection;

namespace FilesystemProviders;

public class FilesystemComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.SetMediaFileSystem((factory) =>
        {
            IHostingEnvironment hostingEnvironment = factory.GetRequiredService<IHostingEnvironment>();
            var rootPath = Path.Combine("C:", "storage", "umbracoMedia");
            var rootUrl = hostingEnvironment.ToAbsolute("/CustomPath");

            return new PhysicalFileSystem(
                factory.GetRequiredService<IIOHelper>(),
                hostingEnvironment,
                factory.GetRequiredService<ILogger<PhysicalFileSystem>>(),
                rootPath,
                rootUrl);
        });
    }
}

This is much the same as when you register it within the wwwroot with a virutal folder. The only differnce is that now you provide an absolute root path and root URL to the physical filesystem.

• rootPath is the full filesystem path where you want media files to be stored. It has to be rooted, must use directory separators (\) and must not end with a separator. For example, Z: or C:\path\to\folder or \\servername\path.

• rootUrl is the URL where the files will be accessible from. It must use URL separators (/) and must not end with a separator. It can either be a folder, like /UmbracoMedia, in which case it will considered as subfolder of the main domain (example.com/UmbracoMedia) or can be a fully qualified URL, with also domain name and protocol (for ex http://media.example.com/media).

For more information see Extending FileSystemProviders.

Custom providers

To store media files in different systems, the type of provider must be changed. You can learn how to build a custom filesystem provider in the Extending Umbraco section.

Get the contents of a file as a stream

The recommended approach to obtain a file's content as a stream is to utilize the MediaFileManager. It is advised to avoid reading the file directly from the server using methods like Server.MapPath. This will ensure that, regardless of the file system provider, the stream will be returned correctly. TThis example demonstrates using MediaFileManager to validate file existence and stream it back from a controller.

using System.IO;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.StaticFiles;
using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Hosting;
using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.Logging;
using Umbraco.Cms.Core.Routing;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Infrastructure.Persistence;
using Umbraco.Cms.Web.Website.Controllers;

namespace FilesystemProviders;

public class MediaController : SurfaceController
{
    private readonly MediaFileManager _mediaFileManager;
    private readonly IHostingEnvironment _hostingEnvironment;

    public MediaController(
        IUmbracoContextAccessor umbracoContextAccessor,
        IUmbracoDatabaseFactory databaseFactory,
        ServiceContext services,
        AppCaches appCaches,
        IProfilingLogger profilingLogger,
        IPublishedUrlProvider publishedUrlProvider,
        MediaFileManager mediaFileManager,
        IHostingEnvironment hostingEnvironment)
        : base(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider)
    {
        _mediaFileManager = mediaFileManager;
        _hostingEnvironment = hostingEnvironment;
    }

    public IActionResult Index(string id, string file)
    {
        var path = _hostingEnvironment.MapPathWebRoot($"/media/{id}/{file}");

        if (_mediaFileManager.FileSystem.FileExists(path))
        {
            var stream = _mediaFileManager.FileSystem.OpenFile(path);
            stream.Seek(0, SeekOrigin.Begin);

            var provider = new FileExtensionContentTypeProvider();
            string contentType;
            if (!provider.TryGetContentType(file, out contentType))
            {
                contentType = "application/octet-stream";
            }

            return new FileStreamResult(stream, contentType);
        }

        return new NotFoundResult();
    }
}

In Umbraco 9+, we have moved away from the previous configuration using .config files, to instead using the .NET built-in configuration pattern. This means that there is no longer separate files for different configuration, the configuration is now primarily done using IConfiguration with diffent sources. E.g. The appsettings.json file.

For more in depth information on the configuration pattern see Microsofts article.

Managing Configuration

You might not always want to have the configuration stored in the appsettings.json file, for instance, you might not want to have the admin password in the file if using the unattended feature. You might also want to use a specific set of configurations when developing your solution. To achieve this, the IConfiguration pattern can be used for this.

With the configuration pattern the settings can be read from multiple different source, where some take precedence over other, you can configure you site with:

1. The appsettings.json file

2. An appsettings.{environment}.json file

3. UserSecrets (Only when in development)

4. Environment variables

5. Command line arguments

This list is in order of precedence, so the values from appsettings.json will only be used if they're not also defined in the environment variables. If they are, then the environment variable will be used instead.

There is one caveat, to this precedence though, the appsettings.{environment}.json file will only be used if the current environment matches the name of the config file, for instance, the appsettings.Development.json file will only be used when the environment is set to development.

Using Environment Variables for Configuration

It is not feasible to have an entire json file as an environment variable, and the : doesn't work with environment variables on all platforms, so instead a double underscore is used to create the hierachy.

As an example, if you want to set your unattended username, you would normally write it in the appsettings.json like so:

As an environment variable it becomes a variable with the name Umbraco__CMS__Unattended__UnattendedUserName and a value of A.N. Other.

Using Command Line Arguments Configuration

Like with environment variables, it's not feasible to use an entire JSON file as a command line argument. However, with the command line the : will work without issues, so each section of the hierarchy is separated with a : character. If we use the same example as above, you can achieve the same result by using the following when starting the site via the command line:

dotnet run Umbraco:CMS:Unattended:UnattendedUserName="A.N Other"

Using UserSecrets for Configuration

In the development environment it is possible to use UserSecrets for configuration, which is ideal for connection strings and similar settings that shouldn't be committed to source control. To use UserSecrets you need to first enable them for the project - this is done with the following command, issued within the directory that contains the .csproj file:

dotnet user-secrets init

Now it's possible to store the connection string with this command:

dotnet user-secrets set "ConnectionStrings:umbracoDbDSN" "CONNECTION_STRING_IN_HERE"

IntelliSense

A great thing about appsettings.json is that it allows for intellisense with a schema file. For most editors this should work out of the box, without having to configure anything, since the schema is specified in the top of the file like so: "$schema": "https://json.schemastore.org/appsettings.json".

Reading Configuration in Code

You might need to read the configuration from your code.

First off using Microsoft.Extensions.Options is added, to gain access to the IOptions type, and using Umbraco.Cms.Core.Configuration.Models; is added to get access to the GlobalSettings type.

IOptions<GlobalSettings> is then injected into the constructor of the class, where we can use the Value property to gain access to the actual settings object.

Now we have a typed object containing our settings, so we can get the Host value by calling _globalSettings.Smtp.Host.

To see what setting types you can access see the complete list below, each document corresponds to a settings type.

Configuration Options

A complete list of all the configuration sections included in Umbraco, by default, can be seen here along with any keys they contain:

Configured by code

Allows you to configure the Content Dashboard settings for Umbraco.

AllowContentDashboardAccessToAllUsers

Gets a value indicating whether the Content Dashboard should be available to all users.

When the value is true the dashboard is visible for all user groups. Otherwise, when the value is false, the default access rules for that dashboard will be in use.

ContentDashboardPath

Gets the path to use when constructing the URL for retrieving data for the content dashboard.

ContentDashboardUrlAllowlist

Gets the allowed addresses to retrieve data for the content dashboard.

No addresses specified indicates that any URL is allowed.

This section allows you to disable the ModelBindingExceptionFilter, this filter is only enable if the models builder mode is set to InMemoryAuto. This filter will return a redirect to the page being loaded after one second, if a ModelsBindingException or InvalidCastException occurs. The reason for this filter is that a page might be requested at the same time as the content type has been changed. If this occurs, the new model might not have been generated and loaded yet. This filter will take care of this. By default this filter is enabled, but will be ignored if the mode is not InMemoryAuto. To manually disable the filter add the "ExecptionFilter" section to your config with the "Disabled" key set to true like so:

The health checks section allows you to disable certain health checks, and configure your own custom notification methods, that will automatically run the health checks every so often, and notify you if any health checks fails.

An example of a HealthChecks settings can look something like this:

This config will disable the macro errors check, and enable notifications to run the checks and notify via email if a check fails. The checks will run the first time five minutes after the site is booted, and then once every day.

But let's go through the config one by one

Disabled checks

A list of DisabledHealthCheckSettings objects, each of these objects represents a disabled health check. Only the Id key needs to be present and have a value, corosponding to the GUID of the health check to disable.

There is also a DisabledOn key representing the date the health check was disabked and a DisabledBy key containing the ID of the user that disabled the health check, however these values are currently not used.

Notification

Settings relating to running the health checks automatically and sending out notifications.

Enabled

Allows you to disable or enable all notifications methods, if set to false, the health checks will not automatically run.

First run time

This will configure when you run the health checks for the first time, if the value is not configured the health checks will run immediately after the site boots for the first time. This value is specified as a string in crontab format, so in this example, the health checks will first run at 4 a.m.

Period

Specifies how often the health checks should run, as a DateTime string, in this example the checks will run every day (every 24 hours).

Notification methods

A dictionary of all the notification methods that should be used.

The key of the dictionary is the alias of the notification method, and the value is a HealthChecksNotificationMethodSettings configuration object, in this case it's the built in email notification method.

Each object allows the following to be configured:

Enabled

Allows you to enable or disable specific checks.

Verbosity

Configures how verbose the reporting should be, the available options are:

• Summary

• Detailed

Failure only

If set to true, the notification method will only run if a check has failed.

Settings

Allows you to set custom settings for a given implementation of a notification method, which settings are available depends on the specific implementation.

Content settings contains a handful of settings related to the content in the CMS. It includes settings such as allowed upload files, image settings, and much more. All the values in the content settings has default values, so all configuration is optional.

The following snippet will give an overview of the keys and values in the content section including the default values:

Root level settings

In the root level section, that is those without a seperate sub section like Imaging, you can configure:

Allow Edit Invariant From Non-Default

Invariant properties are properties on a multilingual site that are not varied by culture. This means that they share the same value across all languages added to the website.

When the setting is set to false the invariant properties that are shared between all languages can only be edited from the default language. This means you need access to the default language, in order to edit the property.

When set to true (default) the invariant properties will need to be unlocked before they can be edited. The lock exists in order to make it clear that this change will affect more languages.

Allowed upload files

If greater control is required than available from the above, this setting can be used to store a list of file extensions. If provided, only files with these extensions can be uploaded via the backoffice.

Allowed media hosts

By default, only relative URLs are allowed when getting URLs for resized images or thumbnails using the ImagesController. If you need absolute URLs you will have to add the allowed hosts to this list. The value could be ["umbraco.com", "www.umbraco.com", "our.umbraco.com"].

Disable delete when referenced

This setting allows you to specify whether a user can delete content or media items that depend on other items. This also includes any descendants that have dependencies. Setting this to true will remove or disable the Delete button.

Disable unpublish when referenced

This setting allows you to specify whether or not users can unpublish content items that depend on other items or have descendants that have dependencies. Setting this to true will disable the Unpublish button.

Disallowed upload files

This setting consists of a list of file extensions that editors shouldn't be allowed to upload via the backoffice.

Error 404 collection

In case of a 404 error (page not found) Umbraco can return a default page instead. This is set here. Notice you can also set a different error page, based on the current culture so a 404 page can be returned in the correct language.

The above example shows what you need to do if you only have a single site that needs to show a custom 404 page. You specify which node that should be shown when a request for a non-existing page is being made. You can specify the node in three ways:

1. Enter the nodes id ("ContentId": 1)

2. Enter the node's GUID ("ContentKey": "4f96ffdd-b969-46a8-949e-7935c41fabc0")

3. Enter the XPath to find the node ("ContentXPath": "/root/Home//TextPage[@urlName = 'error404'")

If you have multiple sites, with different cultures, setup in your tree then you will need to setup the errors section like below:

If you have more than two sites and forget to add a 404 page and a culture, the default page will act as fallback. Same happens if you for some reason forget to define a hostname on a site.

Hide backoffice logo

This setting can be used to hide the Umbraco logo in backoffice.

Login background image

You can specify your own background image for the login screen here. The image will automatically get an overlay to match backoffice colors. This path is relative to the wwwroot/umbraco path. The default location is: wwwroot/umbraco/assets/img/installer.jpg.

Login logo image

You can specify your own image for the small logo in the top left corner of the login screen. This path is relative to the wwwroot/umbraco path. The default location is: wwwroot/umbraco/assets/img/application/umbraco_logo_white.svg.

Macro errors

This setting allows you to specify how errors in macros should be handled.

Options:

• Inline - Default Umbraco behavior, show an inline error within the macro but allow the page to continue rendering.

• Silent - Silently suppress the error and do not display the offending macro.

• Throw - Throw an exception.

• Content - Silently suppress the error, and display custom content reported in the error event args.

Preview badge

This allows you to customize the preview badge being shown when you're previewing a node.

Resolve urls from text string

This setting is used when you're running Umbraco in virtual directories. Setting this to true can increase render time for pages with a large number of links. However, this is required if Umbraco is running in a virtual directory.

Show deprecated property editors

This setting is used for controlling whether or not the Data Types marked as obsolete should be visible in the dropdown when creating new Data Types.

By default this is set to false. To make the obsolete data types visible in the dropdown change the value to true.

Show Domain Warnings

If you do not configure Domains for each language in a multilingual site then every time you publish your content you get this warning:

Content published: Domains are not configured for multilingual site, please contact an administrator, see log for more information.

If you have a use case for not setting the domains, you can set this setting ShowDomainWarnings to false to stop the warning from displaying.

ContentVersionCleanupPolicy

The global settings for the scheduled job which cleans historic content versions. These settings can be overridden per Document Type.

Current draft and published versions will never be removed, nor will individual content versions which have been marked as "preventCleanup".

To retain only the current draft and published version, set both the "keep" settings values to 0. The next time the scheduled job runs (hourly) all non-current versions (except those marked "prevent cleanup") will be removed.

EnableCleanup

When set to true, a scheduled job will delete historic content versions that are not retained according to the policy every hour.

When set to false, the scheduled job will not delete any content versions, regardless of any overridden settings for a Document Type.

The dotnet new template provides an appsettings.json file with the default value set to true for all sites.

KeepAllVersionsNewerThanDays

All versions that fall in this period will be kept.

KeepLatestVersionPerDayForDays

For content versions that fall in this period, the most recent version for each day is kept. All previous versions for that day are removed unless marked as preventCleanup.

This variable is independent of KeepAllVersionsNewerThanDays, if both were set to the same value KeepLatestVersionPerDayForDays would never apply as KeepAllVersionsNewerThanDays is considered first.

Imaging

This section is used for managing how Umbraco handles images, allowed attributes and, which properties of an image that should be automatically updated on upload.

Let's break it down.

ImageFileTypes

This is a separated list of accepted image formats

AutoFillImageProperties

You can define what properties should be automatically updated when an image is being uploaded. This means that if you decide to rename the default umbracoWidth and umbracoHeight properties the values in "WidthFieldAlias" and "HeightFieldAlias" need to be updated. This needs to happen in order to automatically populate the values when the image is being uploaded.

Custom media document

If you need to create a custom Media Type to handle images you need to add another object using the custom Media Type alias. Like below. Keep in mind that the width and height attributes have also been changed in this example.

Notifications

Global settings contains at set of global settings for the CMS such as default UI language, reserved urls, and much more. All of these, except for SMTP settings contains default values, meaning that all configuration is optional, unless you wish to send emails from your site.

The following snippet contains all the available options, with default values, and some example values for the required keys From, Host and Port keys of the SMTP settings:

Root level settings

In the root level section, that is those without a seperate sub section like SMTP, you can configure

Reserved urls

A comma-seperated list of files to be left alone by Umbraco, these files will be served, and the Umbraco request pipeline will not be triggered.

Reserved paths

A comma-separated list of all the folders in your directory to be left alone by Umbraco. If you have folders with custom files, add them to this setting to make sure Umbraco leaves them alone.

Timeout

Configure the session timeout to determine how much time without a request being made can pass before the user is required to log in again. The session timeout format needs to be set as HH:MM:SS. Any activity within the backoffice will reset the timer.

Default UI language

The default language to use in the backoffice if a user isn't explicitly assigned one.

Hide top level nodes from path

If you are running multiple sites, you don't want the top level node in your URL and can disable it with this setting.

Use https

Makes sure that all of the requests in the backoffice are called over HTTPS instead of HTTP when set to true.

Version check period

When this value is set above 0, the backoffice will check for a new version of Umbraco every 'x' number of days where 'x' is the value defined for this setting. Set this value to 0 to never check for a new version.

Icons path

By adding this value you can specify a new/different folder for storing your icon resources. It's important to be aware of NetCore's limitations regarding serving static file content. By default, static content will only be served from the wwwroot folder.

Umbraco CSS path

Umbraco scripts path

Umbraco media path

Umbraco media physical root path

Install missing database

This is not a setting that commonly needs to be configured.

If enabled Umbraco will try to automatically install the database when it's missing. This is primarily used in conjuction with unattended installs.

Disable election for single server

This is not a setting that commonly needs to be configured.

Database factory version

This is not a setting that commonly needs to be configured.

This setting is used to specify which sql server version that the database is running, this setting is only required if you use SqlServer 2008, if this is the case set the setting to "SqlServer.V2008"

Main dom lock

Specifies the implementation of IMainDomLock to be used.

IMainDomLock is used to synchronize access to resources like the Lucene indexes.

Available options:

• "FileSystemMainDomLock"- Available cross-platform, uses lock files written to LocalTempPath to control acquisition of MainDom status.

• "MainDomSemaphoreLock" - Windows only, uses a named system Semaphore with a maximumCount of 1 to control acquisition of MainDom status.

• "SqlMainDomLock" - Available cross-platform, uses the database to control acquisition of MainDom status.

The default implementation unless configured otherwise is FileSystemMainDomLock.

Main dom key discriminator

For advanced use cases e.g. deployment slot swapping on Azure app services.

When using SqlMainDomLock a MainDomKey is used to identify an instance of a running application.

The MainDomKey is by default comprised of the server's machine name & the application id.

This is generally all that is required to control MainDom status as starting a new process for the same application on the same server will result in a matching MainDomKey. This will then require that an existing instance yields MainDom status to the new process.

To prevent this from occurring you can specify a MainDomKeyDiscriminator which should be set as a slot-specific configuration to prevent the slots from competing for MainDom status.

It's worth noting that during the swap operation there is a period where both instances will share the same configuration and at this point, the old instance will yield MainDom status to the new instance.

Main dom release signal polling interval

Gets or sets the duration (in milliseconds) for which the MainDomLock release signal polling task should sleep. The default value is 2000ms.

Id

This setting doesn't need to be configured.

This setting contains a unique ID used to identify your project, and is populated the first time your site runs, you shouldn't change this setting.

No nodes view path

This setting specifies what view to render when there is no content on the site.

SMTP settings

By adding this settings to the appsettings.json you will be able to send out emails from your Umbraco installation. This could be notifications emails if you are using content workflow, or you are using Umbraco Forms you also need to specify SMTP settings to be able use the email workflows. The forgot password function from the backoffice also needs a SMTP server to send the email with the reset link.

From

Specifies the default address emails will be sent from, this setting may be overridden some place, such as when inviting a user, where the email of the user sending the invite will be used instead. The format of the address follows the RFC 822 standard so you can include a friendly name using the format "Friendly Name <your@emailaddress.com>"

Host

Address of the SMTP host used to send the email from.

Port

The port of the SMTP host, port 25 is a common port for SMTP.

Username

The username used to authenticate with the specified SMTP server, when sending an email.

Password

The password used to authenticate with the specified SMTP server, when sending an email.

Secure socket options

Allows you to specify what security should be used for the connection sending the email.

The options are:

• None - No SSL or TLS encryption should be used.

• Auto - Allow the IMailService to decide which SSL or TLS options to use (default). If the server does not support SSL or TLS, then the connection will continue without any encryption.

• SslOnConnect - The connection should use SSL or TLS encryption immediately.

• StartTls - Elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server. If the server does not support the STARTTLS extension, then the connection will fail and a NotSupportedException will be thrown.

• StartTlsWhenAvailable - Elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server, but only if the server supports the STARTTLS extension.

Delivery method

Specifies what delivery method should be used for emails, most of the time you'd want to use the default "Network" option to send emails over the network. It might be useful during development to use "SpecifiedPickupDirectory" to place the email messages in a folder on disk, instead of trying to send them over the network.

Pickup directory location

If you're using the "SpecifiedPickupDirectory" option on as the delivery method, this setting allows you to specify what folder the emails should be saved to.

Database server registrar settings

It's unlikely that you will have to change these settings unless you're using a load balanced setup.

Wait time between calls

Sets a value for the amount of time to wait between calls to the database on the background thread.

Stale server timeout

Sets a value for the time span to wait before considering a server stale, after it has last been accessed.

Database server messenger

It's unlikely that you will have change these settings, unless you're using a load balanced setup. These settings are all about how load balancing instructions from the database are processed and pruned.

Max processing instruction

Sets a value for the maximum number of instructions that can be processed at startup; otherwise the server cold-boots (rebuilds its caches).

Time to retain instructions

Sets a value for the time to keep instructions in the database; records older than this number will be pruned.

Time between sync operations

Sets a value for the time to wait between each sync operation.

Time between prune operations

Sets a value for the time to wait between each prune operation.

Sanitize TinyMce

Gets or sets a value indicating whether TinyMCE scripting sanitization should be applied.

The default value is false.

Distributed Locking Mechanism

This is not a setting that commonly needs to be configured.

Gets or sets a value representing the DistributedLockingMechanism to use.

Valid values:

• "SqlServerDistributedLockingMechanism"

• "SqliteDistributedLockingMechanism"

Distributed Read Lock DefaultTimeout

Gets or sets a value representing the maximum time to wait whilst attempting to obtain a distributed read lock.

The default value is 60 seconds.

Distributed Write Lock DefaultTimeout

Gets or sets a value representing the maximum time to wait whilst attempting to obtain a distributed write lock.

The default value is 5 seconds.

Hosting settings contains settings regarding the hosting of the site, such as application virtual path, local temporary storage location and debug.

A full configuration with default values can be seen here:

Setting overview

Application virtual path

This setting specified the virtual path of the application, this path must start with a slash.

Local temp storage location

This setting specifies the location of the local temp storage.

Options:

• Default

• EnvironmentTemp

Debug

This setting allows you to run Umbraco in debug mode, by setting the value to true.

Site name

Allows you to configure the keep alive service of Umbraco. A keep alive section fully populated with default values can be seen here:

"Umbraco": {
  "CMS": {
    "KeepAlive": {
      "DisableKeepAliveTask": false,
      "KeepAlivePingUrl": "~/api/keepalive/ping"
    }
  }
}

Disable keep alive task

Allows you to disable the keep alive http calls.

Keep alive ping URL

If you want to change the URL you need to call to keep the site alive, update this property. The URL should not contain a trailing slash.

The imaging settings section lets you configure the cache and resize settings for processed images on your project (using ImageSharp.Web as default implementation). If you need to configure allowed image file types or auto fill image properties, you want to use content settings instead.

All these settings contain default values, so nothing needs to be explicitly configured. A complete settings section for imaging can be seen here with all the default values:

"Umbraco": {
  "CMS": {
    "Imaging": {
      "Cache": {
        "BrowserMaxAge": "7.00:00:00",
        "CacheMaxAge": "365.00:00:00",
        "CacheFolderDepth": 8,
        "CacheHashLength": 12,
        "CacheFolder": "~/umbraco/Data/TEMP/MediaCache"
      },
      "Resize": {
        "MaxWidth": 5000,
        "MaxHeight": 5000
      }
    }
  }
}

Cache

Contains configuration for browser and server caching. When changing these cache headers, it is recommended to clear your media cache. This is due to the data being stored in the cache and not updated when the configuration is changed.

Browser max age

Specifies how long a requested processed image may be stored in the browser cache by using this value in the Cache-Control response header. The default is 7 days (formatted as a timespan).

Cache max age

Specifies how long a processed image may be used from the server cache before it needs to be re-processed again. The default is one year (365 days, formatted as a timespan).

Cache folder depth

Gets or sets the depth of the nested cache folders structure to store the images. Defaults to 8.

Cache hash length

Gets or sets the length of the filename to use (minus the extension) when storing images in the image cache. Defaults to 12 characters.

Cache folder

Allows you to specify the location of the cached images folder. By default, the cached images are stored in ~/umbraco/Data/TEMP/MediaCache. The tilde (~) resolves to the content root of your project/application.

Resize

Contains configuration for image resizing.

Max width/max height

Specifies the maximum width and height an image can be resized to. If the requested width and height are both above the configured maximums, no resizing will be performed. This adds basic security to prevent resizing to big dimensions and using a lot of server CPU/memory to do so.

The maximum width and height settings are enforced by setting the ImageSharpMiddlewareOptions.OnParseCommandsAsync option of ImageSharp to an Umbraco-specific function. If you want to add your own logic without overwriting this behaviour, use the following code:

public class ConfigureImageSharpMiddlewareOptionsComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<ImageSharpMiddlewareOptions>(options =>
        {
            // Capture existing task to not overwrite it
            var onParseCommandsAsync = options.OnParseCommandsAsync;
            options.OnParseCommandsAsync = async context =>
            {
                // Custom logic before

                await onParseCommandsAsync(context);

                // Custom logic after
            };
        });
}

This section allows you to configure how content is indexed for Examine.

"Umbraco": {
  "CMS": {
    "Indexing": {
      "ExplicitlyIndexEachNestedProperty": true
    }
  }
}

ExplicitlyIndexEachNestedProperty

When indexing content, each property contained within certain complex editors are indexed as separate fields by default. These complex editors include:

• Block List

• Block Grid

The complex editors are also indexed to their own separate fields, which then contains "the sum" of all properties contained within.

In some cases this yields a lot of fields in the index, which can lead to errors when performing searches. Changing this setting to false can mend that issue. It prevents each contained property from being written to the index in its own field.

The majority of logging related configuration has been moved to the Serilog configuration see Serilog settings for more information.

The following configuration is available in the Logging settings:

"Umbraco": {
  "CMS": {
    "Logging": {
      "MaxLogAge": "2.00:00:00",
      "Directory": "~/CustomLogFileLocation"
    }
  }
}

MaxLogAge

This setting allows you to configure the maximum log age for the internal audit log scrubbing. The default maximum age for the internal audit log is 24 hours. Change the duration with the MaxLogAge key in the Logging settings.

To increase the maximum age of the entries in the audit log to 48 hours (2 days), set the value to 2.00:00:00.

Directory

By default, all log files are saved to the umbraco/Logs directory. You can define a custom directory for your log files by using the Directory key in the Logging settings.

Set the value to ~/LogFiles to add all log files to a LogFiles directory in the root of the file structure.

Umbraco does not touch the default maximum allowed content size of the different services, but you can configure this yourself.

Using IIS

To configure the default 28.6MB upload limit using IIS, we have to create a web.config file at the root of the project. It should contain this:

<?xml version="1.0"?>
<configuration>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- ~ Below is the number of bytes allowed, 4GB is the maximum -->
        <requestLimits maxAllowedContentLength="2000000" />
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>

maxAllowedContentLength is specified in bytes, so this configuration would limit requests, and therefore uploaded files, to 2 megabytes

Using Kestrel

Runtime settings allow you to configure the MaxRequestLength and MaxQueryStringLength for kestrel. If you want to upload files larger than 28.6MB, then you have to configure these settings. If nothing is configured requests and query strings can only be the default size and smaller.

An example of a configuration could look something like this:

"Umbraco": {
  "CMS": {
    "Runtime": {
      "MaxQueryStringLength": 90,
      "MaxRequestLength": 2000
    }
  }
}

MaxRequestLength is specified in kilobytes. This configuration will limit requests, and therefore uploaded files, to 2 megabytes, and a maximum query string length of 90 characters.

Using Nginx (external)

Using apache (external)

This settings section allows you to specify the block size of the BTree used by NuCache. This is configured by default, so you don't need to configure this. However it is possible with something like:

"Umbraco": {
  "CMS": {
    "NuCache": {
      "BTreeBlockSize": 4096
    }
  }
}

This is how NuCache is configured by default. It is important to mention that the block size must be a power of two, at least 512, and at most 65536 (64K).

UsePagedSqlQuery

Setting UsePagedSqlQuery to False your project will use the Fetch method instead of the QueryPaged method when rebuilding the NuCache files. This will increase performance on bigger Umbraco websites with a lot of content when rebuilding the NuCache.

"Umbraco": {
  "CMS": {
    "NuCache": {
      "UsePagedSqlQuery": false
    }
   }
 }

Additional Settings

It is possible to configure NuCache to work in memory only without reading/writing the NuCache database files.

Startup duration may increase for larger sites during a "warm boot" but smaller sites should see minimal impact.

The settings have not yet been exposed via the new configuration setup, instead you must configure with a composer.

public class DisableNuCacheDatabaseComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        var settings = new Umbraco.Cms.Infrastructure.PublishedCache.PublishedSnapshotServiceOptions
        {
            IgnoreLocalDb = true
        };
        builder.Services.AddSingleton(settings);
    }
}

The Plugins settings allow you to configure how Umbraco handles plugins. Currently, you can only configure browsable file extensions, which allows you to customize what file types plugins are allowed to use for the front end. The default configuration looks like this:

"Umbraco": {
  "CMS": {
    "Plugins": {
      "BrowsableFileExtensions": [
        ".html",
        ".css",
        ".js",
        ".jpg", ".jpeg", ".gif", ".png", ".svg",
        ".eot", ".ttf", ".woff", ".woff2",
        ".xml", ".json", ".config",
        ".lic"]
    }
  }
}

As you can see above, by default, markup, styles, scripts, images, fonts, configurations, and license type are included. If you were to, for example, remove the ".html" entry, then plugins would no longer be allowed to use HTML files.

This settings section provides control over how package migrations are executed in different environments (local, development, live etc.)

Package migrations are defined by package developers allowing them to add functionality to their package that enhances the Umbraco CMS. There can be various types of migrations applied, including creating custom database tables and installing Umbraco schema and content.

They run on start-up, thus ensuring that the functionality of the package has the necessary infrastructure, schema, and content in place when it is used.

Migration steps that are explicitly created by the package developer to make database schema changes will always run in all environments.

Depending on your workflow, for those steps that install Umbraco data - whether schema such as document types, content, or media - you may want them run in all environments, or you may prefer to only do this in certain ones.

The default behavior for Umbraco CMS is for all package migrations to run in all environments.

If using Umbraco Cloud, the default is to run package migrations fully only in local environments. By doing this, for schema, .uda files will be generated in the /umbraco/Deploy/Revision folder, which when pushed to a Cloud environment will be used to install the schema and content there. For content and media, the "queue for transfer" operation can be used. With this behavior, we avoid any issues caused by both a package migration and a deployment operation attempting to create schema and content.

If different behavior is required, or if using Umbraco Deploy On-Premises, the following settings can be applied:

{
  "$schema": "https://json.schemastore.org/appsettings.json",
  "Umbraco": {
    "CMS": {
      "PackageMigration": {
        "RunSchemaAndContentMigrations": true,
        "AllowComponentOverrideOfRunSchemaAndContentMigrations": true
      }
    }
  }
}

RunSchemaAndContentMigrations

If set to true, the default behavior described above for Umbraco CMS on-premises and Umbraco Cloud will be applied. By setting to false, the installation of Umbraco schema and content from a package migration will be skipped. If missing the default value is true.

AllowComponentOverrideOfRunSchemaAndContentMigrations

If this is set to the default value of true, Umbraco Cloud (or other deployment tools) can override the configured value of RunSchemaAndContentMigrations as is appropriate for their operation. By setting to false such tools should respect this setting, not make any overrides and use the configured value.

This section allows you to configure the Umbraco models builder, a complete section with default values can be seen here:

"Umbraco": {
  "CMS": {
    "ModelsBuilder": {
      "ModelsMode": "InMemoryAuto",
      "ModelsNamespace": "Umbraco.Cms.Web.Common.PublishedModels",
      "FlagOutOfDateModels": false,
      "ModelsDirectory": "~/umbraco/models",
      "AcceptUnsafeModelsDirectory": false,
      "DebugLevel": 0
    }
  }
}

Let's go through them one by one

Models mode

Specifies how the models builder will generate models and when to generate them. The options are:

• Nothing - The modelsbuilder will not generate any models, this means that all views will use IPublishedContent, instead of strongly typed models.

• InMemoryAuto - Models will automatically be generated each time a content type change occurs, and will then be compiled, and loaded into memory dynamically. This means that the models are only availabe in views, however they will be available instantly.

• SourceCodeManual - Models will be generated as .cs files whenever a user clicks the "Generate models" button on the models builder dashboard - however, the models will not be compiled and loaded into memory dynamically. This means that models are available to edit within the project. The project needs to be recompiled and restarted for the new models, or model changes, to take effect.

• SourceCodeAuto - This mode behaves the same as SourceCodeManual with one difference, the generation of models happens automatically every time a content type change occurs.

Models namespace

This setting allows you to customize the namespace of the generated models, for instance you might want to change this to something that aligns better with your project structure, such as MySite.ContentModels.

Flag out of date models

This setting allows you to specify if a model should be flagged as out of date if its content type, or a datatype the content type depends on, are changed. When a model is flagged as out of date you will be able to see that you need to regenerated models in modelsbuilder dashboard.

This setting is only really relevant if you use the SourceCodeManual models mode, since otherwise the models will be automatically regenerated, and will therefore never be out of date.

If you set this setting to true while using an Auto mode, it will automatically be interpreted as false.

Models directory

Allows you to specify a custom directory for your generated models. By default this settings has to be a virtual directory, that is, it must start with ~/, if needed AccceptUnsafeModelsDirectory can be set to true, to allow the path to be outside the website root, be aware though that this is a potential security risk.

Accept unsafe models directory

By setting this to true, you specify that the models directory is allowed to be outside the websites root. This is not allowed by default since it can be a potential security risk.

Debug level

This setting specifies the logging level for the models builder. By default this is set to 0, which means minimal logging. Anything higher that 0 means increased logging. Be aware that this setting should only be set to something higher than 0 for development use, not on live sites.

When Umbraco is installed for the first time, it creates a set of default data. These include a language, some Data Types, and some Media and Member Types.

In certain setups, you may want to take control over what is installed and opt-out of the creation of certain items.

When working in a team and using Umbraco Deploy for schema updates, consider your colleague's local project setup. The default installed data may not always be useful.

For example, if different languages are set up in Umbraco, it's better not to recreate them from the default language (en-US). In other situations, certain Umbraco default Data, Member and Media Types may not be required.

The following example configuration shows how this default data installation can be customized:

"Umbraco": {
  "CMS": {
  "InstallDefaultData": {
      "Languages": {
        "InstallData": "Values",
        "Values": [
          "en-US"
        ]
      },
      "DataTypes": {
        "InstallData": "ExceptValues",
        "Values": [
          "0225af17-b302-49cb-9176-b9f35cab9c17"
        ]
      },
      "MediaTypes": {
        "InstallData": "All",
      },
      "MemberTypes": {
        "InstallData": "None"
      }
    }
  }
}

Each InstallData setting can be one of the following values:

• All - all default data for the type will be installed (this is the default behavior if the configuration is omitted).

• Values - only the default data specified will be installed. For languages, the values are the ISO codes for the language. For all other types, the Guid for the type should be listed.

• ExceptValues - all default data except those specified will be installed.

• None - no default data of the type will be installed.

For example, if you check the info tab of the Label (bigint) Data Type, you can see that it is referenced by the Media Types:

Data Identifiers

For DataTypes, MediaTypes and MemberTypes the Guid identifiers for the default data items need to be provided in the Values collection.

For Languages, the Values collection expects the standard language ISO codes to be provided. Given this code is enough to fully specify a language, it's possible to use this collection to install additional default data.

As an example, the following configuration would omit the default "English (United States)" language and instead install the "English (United Kingdom)" and "Italian" languages. As "English (United Kingdom)" is provided first, it would be created as Umbraco's default language for content creation.

"Umbraco": {
  "CMS": {
    "InstallDefaultData": {
      "Languages": {
        "InstallData": "Values",
        "Values": [
          "en-GB",
          "it"
        ]
      }
    }
  }
}

Reference

The Guid values representing the default Data, Media, and Member Types installed are as follows.

Data types:

ApprovedColor = 0225af17-b302-49cb-9176-b9f35cab9c17
Checkbox = 92897bc6-a5f3-4ffe-ae27-f2e7e33dda49
CheckboxList = fbaf13a8-4036-41f2-93a3-974f678c312a
ContentPicker = FD1E0DA5-5606-4862-B679-5D0CF3A52A59
DatePicker = 5046194e-4237-453c-a547-15db3a07c4e1
DatePickerWithTime = e4d66c0f-b935-4200-81f0-025f7256b89a
Dropdown = 0b6a45e7-44ba-430d-9da5-4e46060b9e03
DropdownMultiple = f38f0ac7-1d27-439c-9f3f-089cd8825a53
ImageCropper = 1df9f033-e6d4-451f-b8d2-e0cbc50a836f
LabelBigInt = 930861bf-e262-4ead-a704-f99453565708
LabelDateTime = 0e9794eb-f9b5-4f20-a788-93acd233a7e4
LabelDecimal = 8f1ef1e1-9de4-40d3-a072-6673f631ca64
LabelInt = 8e7f995c-bd81-4627-9932-c40e568ec788
LabelString = f0bc4bfb-b499-40d6-ba86-058885a5178c
LabelTime = a97cec69-9b71-4c30-8b12-ec398860d7e8
ListViewContent = C0808DD3-8133-4E4B-8CE8-E2BEA84A96A4
ListViewMedia = 3A0156C4-3B8C-4803-BDC1-6871FAA83FFF
ListViewMembers = AA2C52A0-CE87-4E65-A47C-7DF09358585D
MediaPicker = 135D60E0-64D9-49ED-AB08-893C9BA44AE5
MediaPicker3 = 4309A3EA-0D78-4329-A06C-C80B036AF19A
MediaPicker3Multiple = 1B661F40-2242-4B44-B9CB-3990EE2B13C0
MediaPicker3MultipleImages = 0E63D883-B62B-4799-88C3-157F82E83ECC
MediaPicker3SingleImage = AD9F0CF2-BDA2-45D5-9EA1-A63CFC873FD3
Member = d59be02f-1df9-4228-aa1e-01917d806cda
MemberPicker = 1EA2E01F-EBD8-4CE1-8D71-6B1149E63548
MultipleMediaPicker = 9DBBCBBB-2327-434A-B355-AF1B84E5010A
Numeric = 2e6d3631-066e-44b8-aec4-96f09099b2b5
Radiobox = bb5f57c9-ce2b-4bb9-b697-4caca783a805
RelatedLinks = B4E3535A-1753-47E2-8568-602CF8CFEE6F
RichtextEditor = ca90c950-0aff-4e72-b976-a30b1ac57dad
Tags = b6b73142-b9c1-4bf8-a16d-e1c23320b549
Textarea = c6bac0dd-4ab9-45b1-8e30-e4b619ee5da3
Textstring = 0cc0eba1-9960-42c9-bf9b-60e150b429ae
Upload = 84c6b441-31df-4ffe-b67e-67d5bc3ae65a
UploadArticle = bc1e266c-dac4-4164-bf08-8a1ec6a7143d
UploadAudio = 8f430dd6-4e96-447e-9dc0-cb552c8cd1f3
UploadVectorGraphics = 215cb418-2153-4429-9aef-8c0f0041191b
UploadVideo = 70575fe7-9812-4396-bbe1-c81a76db71b5

Media types:

MediaTypes.Article - a43e3414-9599-4230-a7d3-943a21b20122
MediaTypes.Audio - a5ddeee0-8fd8-4cee-a658-6f1fcdb00de3
MediaTypes.File - 4c52d8ab-54e6-40cd-999c-7a5f24903e4d
MediaTypes.Folder - f38bd2d7-65d0-48e6-95dc-87ce06ec2d3d
MediaTypes.Image - cc07b313-0843-4aa8-bbda-871c8da728c8
MediaTypes.Video - f6c515bb-653c-4bdc-821c-987729ebe327
"Vector Graphics (SVG)" - c4b1efcf-a9d5-41c4-9621-e9d273b52a9c

Member types:

MemberTypes.DefaultAlias - d59be02f-1df9-4228-aa1e-01917d806cda

Runtime settings allows you to configure the MaxRequestLength and MaxQueryStringLength for your application. Neither of these settings needs to be configured. If nothing is configured reqests and query string can be any size.

An example of a configuration could look something like:

MaxRequestLength is specified in kilobytes, limiting requests, and therefore uploaded files, to 2 megabytes. Additionally, it sets a maximum query string length of 90 characters.

Mode can have three values: BackofficeDevelopment (default), Development, and Production.

For more information, see the article.

This section allows you to configure the runtime minifications (defaults shown), used by

Use 'in memory' cache

This setting determines whether Smidge should save it's cached output in memory, or in a file on disk. If set to false, then the folder will be created at the wwwroot of your Umbraco site in a folder called 'Smidge'/

Cache buster

Specifies mechanism for cache invalidation.

The options are:

• Version - Caches will be busted when your assembly version changes, when the upstream Umbraco version changes and when the version string specified in Configuration changes.

• AppDomain - Caches will be busted when the app restarts.

• Timestamp - Caches will be busted based on a timestamp of the bundled files.

Manually changing the Cache buster version

If you use a CacheBuster setting of "Version" you can add an additional configuration option, also called 'Version' , which allows you to set a value that you can incremement manually, or via a build server to make sure the version number changes for Smidge and busts the cache.

The actual 'Version' number will not be visible in the url of the assets, this is because it is combined, along with the Umbraco Version from configuration and the your project assembly dll, and then once combined a 'hash' is generated to obscure these details.

So if you increased the Version in the configuration by 1 to 1235, all you would see is a different hash!

Another configuration option (of Smidge) is the "dataFolder" setting, this setting specifies what folder Smidge will use for its temporary data, it should not be necessary to change this either, it will only be used if UseInMemoryCache is set to false.

This settings section allows you to configure the behaviour of the rich text editor, everything from plugins to commands. Everything has a default value, so it's not required to configure any of this yourself.

A config with all the values can be seen underneath. Since there are a lot of defaults configured, some of these have been omitted for the sake of readability. Anywhere something has been omitted it is shown with {...}.

Plugins

Allows you to specify what plugins should be enabled for the rich text editor as a comma seperated list of the plugin names.

Valid elements

Allows you to specify the valid HTML elements for the rich text editor as well as the allowed properties. For instance, in the config above the a element is allowed, and it's allowed to have onclick, href, and many more attributes.

Invalid elements

Specifies invalid HTML elements for the rich text editor. For instance, in the config above the font element is not allowed.

Commands

Allows you to specify what commands should be available, as a list of object. These commands are the little buttons you find at the top of the editor, such as bold, italic, and so on.

When specifying these, every object should contain:

• Alias - The alias of the command

• Name - A friendly name descriping the command

• Mode - The mode the command runs on

  • Insert - The command will insert something

  • Selection - The command operate on the text, or elements, selected

  • All - The command operates on everything

Custom config

Allows you to specify custom key value pairs for the rich text editor.

Examples

Remove default <p> tag.

Add custom styles to the Formats dropdown list in the Richtext Editor.

Cloud API key

The options in the security section allows you to configure all things security, whether to keep users logged in, password rules and more.

A full configuration with all default values can be seen here:

Root level settings

At the root level of security you can configure the following

Keep user logged in

Hide disabled users in backoffice

When this is set to "true" it's not possible to see disabled users. This means it's not possible to re-enable their access to the backoffice again. It also means you can't create an identical username if the user was disabled by a mistake.

Allow password reset

This feature allows users to reset their passwords if they have forgotten them. By default, this is enabled. It can be disabled at both the UI and API level by setting this value to "false".

Auth cookie name

The authentication cookie which is set in the browser when a backoffice user logs in, and defaults to UMB_UCONTEXT.

Auth cookie domain

The authentication cookie which is set in the browser when a backoffice user logs in is automatically set to the current domain.

Username is email

This setting specifies whether the username and email address are separate fields in the backoffice editor. When set to "false", you can specify an email address and username, only the username can be used to log on. When set to "true" (the default value) the username is hidden and always the same as the email address.

User password settings

This section lets you define the password rules for users.

Required length

Specifies the minimum length a user password is allowed to be.

Require non letter or digit

Requires a users password to contain at least one character which is not a letter or a digit if enabled.

Require digit

Requires a users password to contain at least one digit if enabled.

Require lowercase

Requires a users password to contain at least on lowercase letter if enabled.

Max failed access attempts before lockout

Specifies the max amount of failed password attempts is allowed before the user is locked out of the site.

Hash algorithm type

Allows you to specify what hashing algorithm should be used to store the users password.

Options are:

• "PBKDF2.ASPNETCORE.V3"

• "PBKDF2.ASPNETCORE.V2"

• "HMACSHA256"

• "HMACSHA1"

Member password settings

This section allows you to define the password rules for members. This section is identical to the one for users.

User Default Lockout Time In Minutes

Use this setting to configure how long time a User is locked out of the Umbraco backoffice when a lockout occurs. The setting accepts an integer which defines the lockout in minutes.

The default lockout time for users is 30 days (43200 minutes).

Member Default Lockout Time In Minutes

Use this setting to configure how long time a Member is locked out of the Umbraco website when a lockout occurs. The setting accepts an integer which defines the lockout in minutes.

The default lockout time for users is 30 days (43200 minutes).

Allow concurrent logins

When set to false, any user account is prevented from having multiple simultaneous sessions. In this mode, only one session per user can be active at any given time. This enhances security and prevents concurrent logins with the same user credentials.

The options in the request handler let us do some useful things. It could be deciding whether or not to use trailing slashes and setting URL replacement for special characters.

Let's have a further look at each option below.

Here is a snippet containing all the default values of the RequestHandler section.

Add trailing slash

This will add a trailing slash to the URL when <addTrailingSlash> is set to "true". If you don't want to have a trailing slash, set the value to false.

Convert URLs to ascii

This setting tells Umbraco to convert all URLs to ASCII: American Standard Code for Information Interchange, if set to false the URLs will remain UTF-8.

This setting can be set to try This will make the engine try to convert the name to an ASCII implementation. If it fails, it will fallback to the name. Reason is that some languages don't have ASCII implementations, therefore the URLs would end up being empty.

Enable default character replacements

This setting tells Umbraco to use the default character replacements. If you don't want the default character replacements, set this to false.

Char collection

This settings contains objects with a "Char" and "Replacement key. Each of these objects holds a character that should be replaced and what it should be replaced with.

When something like the following is added to the list, the ñ will be shown as a n in the URL.

Umbraco uses Serilog as its logging library, this means that the configuration of logging is offloaded to Serilog instead of the CMS. This means that logging specific configuration is not in the Umbraco.Cms section, but instead the Serilog section.

We will go through some of the more common logging configurations here, but for more information see the .

Default configuration

When you create a new Umbraco project the following Serilog section will be included by default:

Specifying minimum log level

As you can see above, the CMS comes with a default Serilog config that defines the minimum log level with the "MinimumLevel" key.

You can specify the overall minimum log level with the "Default" key. This will apply to all namespaces, however it's also possible to override this log level for specific names spaces with the "Override" key. In the example above, any logging coming from the Microsoft and System namespaces will only log warnings and up, however the Microsoft.Hosting.Lifetime namespace will log information and up.

The possible values, from most verbose to least, is:

• Verbose

• Debug

• Information

• Warning

• Error

• Fatal

Changing the log level for specific namespaces

This can be done by updating the appsettings.json configuration file to specify namespaces in which you want to change the log level for.

Logging to a different output

Serilog has the ability to log to a number of different mechanisms, from console to files, even to Slack or email. This is all configured using what Serilog calls sinks.

An example of this can be seen in the default appsettings.Development.json, where Serilog is configured to log to the console using the Async wrapper sink:

Here you can see that we use the "WriteTo" key to specify a list of sinks the logger should write to. In this case we use the "Async" sink configured to write to the console, this means that we'll log to the console asynchronously.

Changing the Umbraco 'sink'

By default, Umbraco uses a special Serilog 'sink' that is optimized for performance. To change parameters for only this sink, but not the default. For E.g higher log level for this compared to other sinks you can do it in the following way:

Adding a custom log property to all log items

You may wish to add a log property to all log messages. A good example could be a log property for the environment to determine if the log message came from development or production.

This is useful when you could be writing logs from all environments or multiple customer projects into a single logging source, such as Elasticsearch. This would allow you to search and filter for a specific project and its environment to see the log messages. You can also reference your hosting server's environment variables in the property values.

In the appsettings.json configuration file you can add the following lines