Shared Configuration
Introduction
In IIS 6.0, synchronizing and replicating configuration between servers was difficult because no built-in functionality existed. Although the server administrator could use the script iiscnfg.vbs to copy configuration between servers, this would still leave ACLs on the metabase and machine-specific paths like the Windows directory to be fixed.
Shared Configuration in IIS
In IIS 7.0 and above, the shared configuration feature enables administrators to store the IIS server configuration files applicationHost.config and administration.config on a remote share. It can be used when building a Web farm to resolve issues related to replication and synchronization of configuration.
What is exported by shared configuration?
What is not exported?
Setup
To set up shared configuration
Create a user that will access the share containing the configuration. This can be a domain user or a local user, if the machine is not joined to a domain.
If the machine is not joined to the domain, the account will need to be created on the Web server(s) and the file server.
Create a share for storing the configuration files and set permissions. This can be done using the following commands:
Navigate to Administrative Tools and click Internet Information Services (IIS) Manager.
Click the server name node.
Double-click the Shared Configuration icon.
On the Shared Configuration page, to export the configuration files from the local machine to another location, click Export Configuration in the Actions pane.
In the Export Configuration dialog box, type a path in the Physical path text box.
Click Connect As. and type a user account and password, and then click OK. This account will be used to access the share. You should use a restricted Active Directory account that is not the domain administrator.
In the Export Configuration dialog box, type a password that will be used to protect the encryption keys, and then click OK.
On the Shared Configuration page, check Enable shared configuration.
Type the physical path, user account, and password that you entered previously, and then click Apply in the Actions pane.
In the Encryption Keys Password dialog box, type the encryption key password that you set earlier, and then click OK.
In the Shared Configuration dialog box, click OK.
Click OK.
Close and reopen IIS Manager.
Double-click the Management Service icon.
In the Actions pane, click Restart.
By clicking the Export Configuration task, the UI exports the applicationHost.config and administration.config files to the path, as well as the encryption keys that IIS uses to encrypt properties like custom application pool identity passwords. By default, there are no encrypted properties in the applicationHost.config file, unless the server administrator has entered custom identities for an application pool or Web site.
Shared configuration works by using a new file named redirection.config, located in the %windir%\system32\inetsrv\config folder, to specify a path and username for accessing the configuration files. When the shared configuration check box is enabled, the UI updates the redirection.config file with the path and username.
While this task can be performed manually (or programmatically) by xcopying the files and updating the redirection.config file, the server administrator must export and import the encryption keys unless they intend not to use encryption. The UI handles all of these tasks seamlessly for the administrator.
For more information, go to Shared Configuration.
Shared Configuration
Introduction
The Internet changes the ways in which companies handle their day-to-day business and how they compete in the marketplace. With the advent of new Web technologies and an increase in the number of customers accessing resources that are available through the Web, there is a pressing need for improved scalability, availability, reliability, and manageability of applications. The applications should rely on systems that provide the capability to deliver high uptime, improved request throughput, increased concurrent user transactions and better return-on-investment value, such as a better quality of service, than competing systems.
The server cluster provides improved availability by having multiple servers distribute the load. The cluster also scales better to an increased number of customers at any given point in time. Finally, the cluster provides an improved management experience by handling the provisioning and administration of the Web farm architecture with ease and without straining operational resources.
Overview
This article focuses on the shared centralized global configuration feature. This feature helps support homogeneous Web farms where servers share the same configuration across a server group. By using a UNC share, any changes to a central master configuration file will propagate across different servers without extra tools or programmatic support.
The first part of this article describes how to use the IIS 7 and above administration UI to enable and use shared configuration. The second part describes how to enable and use shared configuration from the command line.
Non-Goals: What This Article Does Not Cover
Multiple aspects contribute to a successful Web farm environment, including correct supportability, manageability, accessibility, scalability, etc.
Shared configuration focuses only on the configuration management aspect of a Web farm and deals with configuration across servers. There are tools and other features that can help with managing multiple servers, copying content, deploying modules, synchronizing application binaries, setting up third-party components, etc. These tools, features, and aspects are out of the scope of this article.
This article only details how to maintain the configuration by using a central file across servers.
Therefore, note that sharedconfiguration enables a server to access a configuration file in a back-end UNC share as if it were its local configuration. As a result, when you update the configuration by using a front-end Web server, the updates are made to all other servers.
It is important to take into consideration other situations, such as installing a third-party module or adding configuration settings, and include properties that only one server can understand and has the binaries and schema available to function correctly. Otherwise, this type of usage can break the other servers.
To avoid this problem in homogeneous farms, you should disable shared configuration on the cluster, update the local applicationHost file so that it mirrors the remote file, deploy and update modules and the configuration on a single server, and then re-enable shared configuration on that server. Then you can deploy and update the binaries and modules on the rest of the servers before enabling shared configuration again.
Domain and Non-domain Environments
Some administrators deploy Web server clusters in a domain environment, while others deploy in a workgroup (non-domain). This article discusses both scenarios and points out the differences and caveats. It is recommended that you set up IIS in a cluster in a domain, with the help and security that Active Directory provides by using a domain controller.
Prerequisites
You must complete the following steps in order:
Centralized Configuration
The IIS administration UI includes support for setting up configuration redirection and exporting configuration files and necessary encryption keys to a specified path.
To export files and set up configuration redirection by using the UI
The steps above describe how to export the configuration and turn on centralized configuration. However, you only need to export the configuration once. Perform steps 6 to 9 on each subsequent server that will use the centralized configuration.
Notes About Using the UI
When setting up configuration redirection, the exported files are expected to have been exported by using the UI. This is because the UI exports and imports items such as the password-protected encryption keys by using its own custom format.
For example, if you manually copied the administration.config and applicationHost.config files to a share and then manually exported the encryption keys, you would not be able to use the UI to set up configuration redirection to point to those files. This is because the exported encryption keys would not be in the format that is required by the UI.
Command Prompt
Throughout the remainder of this article, you must use a command prompt to run certain commands. It is recommended that you use a command prompt with elevated user rights, since certain commands will not work if you run a normal command prompt.
To open a command prompt with elevated user rights
Backing Up the Current applicationHost.config File
When trying new features or changing multiple configuration settings, it is good practice to back up the current applicationHost.config file.
To back up the applicationHost.config file
Open a command prompt.
Navigate to the IIS directory, which is located in %WINDIR%\System32\InetSrv by default. The configuration files are stored in the InetSrv\Config directory. Use the AppCmd tool to create a backup object and back up the applicationHost.config file by running the following command:
The AppCmd tool resides in the InetSrv directory. You must access the tool from this directory, unless the tool’s path is added to the system’s environment variables.
Ensure that the backup object, which includes the applicationHost.config file and the legacy metabase file for SMTP and other non-Web server settings, is present by running the following command:
To replace the current configuration file with the backup file
Open a command prompt.
Navigate to the IIS directory, which is located in the InetSrv directory by default. Restore the AppCmd backup file object by running the following command:
Creating a User to Access the UNC Share for Configuration
In a domain environment, an administrator must provide or create an account in the domain to use with Active Directory. This account must be set up with the correct user rights to access the UNC share.
In a non-domain environment, an administrator must create on both servers a local user with user rights to access content. The user name and password must be the same across servers to work in this setup. The following steps help in the creation of a user to read the share where the shared configuration resides.
To create a user that can read the share where the shared configuration resides (non-domain)
Open a command prompt.
On the Web Server (front-end server where IIS is installed), create a user called ConfigUser1 with the password ConfigPass1 by running the following command:
On the File Server (back-end server where the central configuration will reside), create a user called ConfigUser1 with the password ConfigPass1 by running the following command:
Creating the UNC Shares for Central Configuration and Content
The UNC share for configuration hosts the applicationHost.config file for any servers that want to pick up configuration data from this centralized location.
To create the UNC share
On the File Server, open a command prompt.
Navigate to the root of the drive. Run the following command to create a directory for configuration and share this directory, making sure to grant users with the user rights to read and write to the directory:
This command automatically grants user rights to the users group to this share. The user created for the non-domain scenario is granted change rights automatically, which can be further restricted if needed. For the domain scenario, the user must either have user rights set explicitly to access the share or be added to the users group in the system.
Non-domain scenario: To increase the security of the share, you can substitute the Users,Change portion of the /grant switch with the ConfigUser1,Change parameters. Only the specified user will have access to the share.
Domain scenario: To increase the security of the share, you can substitute the Users,Change portion of the /grant switch with the domain\user,Change parameters. Only the specified user will have remote access to the share.
The user rights on a share are a union between remote and local file system user rights. You must set the appropriate user rights to the directory for a domain account to be able to read the configuration share successfully.
Granting User Rights to the Accounts for the UNC Shares That Host Central Configuration and Content
You must ensure that the account that is used to access the configuration has the appropriate user rights. This account is used by IIS to access the UNC share in the same manner that it accesses content when a virtual directory is mapped to a UNC share. The read user rights for this account are useful when accessing the share only. After that point, whenever IIS reads the configuration file, it reverts back to the identity that the caller has: either the API, the administration tool that is being used, or the user that is logged in at that moment.
To grant user rights to the accounts for the UNC share (domain)
To add the UNC user (non-domain and domain)
For domain and non-domain scenarios, the user name must include the logon batch job configuration. This is not a default setting in Windows ServersВ® 2008; you must manually add it to the Web server.
Redirecting the Configuration
Introduction
Now that you have completed the preceding steps, the Web server is functional and the front-end Web server should be serving its Default Web Site by using the localhost loop back address.
You can now move the configuration to a central location. This allows you to declare a file as the master file and save it in a UNC share for the configuration of multiple servers. Changing this file once will provision and update all server configurations at once.
To store the configuration in a UNC share
Copy the applicationHost.config and administration.config files from the %windir%\system32\inetsrv\config directory on the front-end Web server to share on the back-end file server. If the user account that is currently logged in has write access to the back-end share, you can drop the file in the directory. If not, then you must authenticate the user account to the back-end to complete this step.
Access the existing redirection.config XML file in the front-end server’s configuration directory:
Open the redirection.config file. Set the following configuration with the correct server name, user name, and password for your environment.
Save your redirection.config file. You can access the sites again, but the configuration is now stored in a UNC share.
Testing the Configuration
With the configuration being referenced from the back-end, there are two key scenarios for which this feature was designed. You can update the configuration in the front-end Web servers in two ways:
Summary
This article introduced the new centralized configuration feature. This feature lets administrators that have homogeneous clusters in a Web farm environment set up and deploy a configuration to all servers in a seamless way.
Once the feature is setup, whether a change is made in the file at the UNC share, or a server is redirected to another location, the changes are picked up immediately by the Web server. Only the global changes that affect multiple sites and applications will cause them to recycle, but if changes are made in a localized scope, then the rest of the sites and applications will not be restarted.
Appendix 1: Accessing Redirection.config File Programmatically to Read the Values
This step provides a sample of how to access the redirection.config file programmatically by taking advantage of the new COM AHADMIN API. Use the AHADMIN COM API to implement this API from native code or from script and managed code.
To read the values programmatically
Save your redirection.js file. You can now run this file from a command prompt because of the Windows Script Host (WSH).
Appendix 2: Accessing the redirection.config File Programmatically to Write the Values
This step provides a sample of how to access the redirection.config file programmatically by taking advantage of the new COM AHADMIN API. Use this API from native code or from script and managed code from its COM object.
To write the values programmatically
Save your redirection.js file.
You can now run this file from a command prompt because of the Windows Script Host (WSH).
Appendix 3: Dealing With Machine-specific Encrypted Properties
By default, IIS includes two main providers for securing properties. These providers are located in the applicationHost.config file’s configuration section and are defined in the
The AesProvider is specific to dealing with encryption and decryption for properties that are in the system.webServer section.
The IISWASOnlyRsaProvider is specific to dealing with encryption and decryption for properties that are in the system.applicationHost section.
Steps
Open a command-prompt. Navigate to the Framework directory, which is located in %windir%\Microsoft.NET\Framework\v2.0.50727\ by default.
For reference, the machine keys for the system are located in %ALLUSERSPROFILE%\Microsoft\Crypto\RSA\MachineKeys\
Use the aspnet_regiis tool to export the key. The command to transfer the configuration key is stated below. The px switch identifies that you want to export an RSA key pair. The pri switch identifies that you also want to include both the private and public key.
This switch identification is necessary to do both encryption and decryption; otherwise, you can only encrypt data with the exported key. The parameter after the -px is the name of the key container to be exported. In this case, it is the «iisConfigurationKey» key container. The other key container that IIS uses is the «iisWasKey» key container.
Once exporting completes successfully, copy the XML file to the other machine in the cluster to prepare to import it there.
Navigate to the Framework directory and use the aspnet_regiis tool to import the key from the XML file. The command to finalize the transfer for the key is stated below.
The parameter after the -pi is the name of the key container to be imported. In this case, it is the «iisConfigurationKey» key container. The other key container that IIS uses is the «iisWasKey» key container.
Advanced configuration of the ASP.NET Core Module and IIS
This article covers advanced configuration options and scenarios for the ASP.NET Core Module and IIS.
Modify the stack size
Only applies when using the in-process hosting model.
Configure the managed stack size using the stackSize setting in bytes in the web.config file. The default size is 1,048,576 bytes (1 MB). The following example changes the stack size to 2 MB (2,097,152 bytes):
Proxy configuration uses HTTP protocol and a pairing token
Only applies to out-of-process hosting.
The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. There’s no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.
A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn’t come from some other source. The pairing token is created and set into an environment variable ( ASPNETCORE_TOKEN ) by the module. The pairing token is also set into a header ( MS-ASPNETCORE-TOKEN ) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren’t accessible from a location off of the server. Without knowing the pairing token value, an attacker can’t submit requests that bypass the check in the IIS Middleware.
ASP.NET Core Module with an IIS Shared Configuration
The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. Because the local system account doesn’t have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.
When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 1 :
When the path to the shared configuration isn’t on the same machine as the IIS installation, follow these steps:
Data protection
The ASP.NET Core Data Protection stack is used by several ASP.NET Core middlewares, including middleware used in authentication. Even if Data Protection APIs aren’t called by user code, data protection should be configured with a deployment script or in user code to create a persistent cryptographic key store. If data protection isn’t configured, the keys are held in memory and discarded when the app restarts.
If the Data Protection key ring is stored in memory when the app restarts:
To configure data protection under IIS to persist the key ring, use one of the following approaches:
Create Data Protection Registry keys
Data Protection keys used by ASP.NET Core apps are stored in the registry external to the apps. To persist the keys for a given app, create Registry keys for the app pool.
For standalone, non-webfarm IIS installations, the Data Protection Provision-AutoGenKeys.ps1 PowerShell script can be used for each app pool used with an ASP.NET Core app. This script creates a Registry key in the HKLM registry that’s accessible only to the worker process account of the app’s app pool. Keys are encrypted at rest using DPAPI with a machine-wide key.
In web farm scenarios, an app can be configured to use a UNC path to store its Data Protection key ring. By default, the keys aren’t encrypted. Ensure that the file permissions for the network share are limited to the Windows account that the app runs under. An X509 certificate can be used to protect keys at rest. Consider a mechanism to allow users to upload certificates. Place certificates into the user’s trusted certificate store and ensure they’re available on all machines where the user’s app runs. For more information, see Configure ASP.NET Core Data Protection.
Configure the IIS Application Pool to load the user profile
Use the file system as a key ring store
Adjust the app code to use the file system as a key ring store. Use an X509 certificate to protect the key ring and ensure the certificate is a trusted certificate. If the certificate is self-signed, place the certificate in the Trusted Root store.
When using IIS in a web farm:
Set a machine-wide policy for Data Protection
The Data Protection system has limited support for setting a default machine-wide policy for all apps that consume the Data Protection APIs. For more information, see ASP.NET Core Data Protection.
IIS configuration
Windows Server operating systems
Enable the Web Server (IIS) server role and establish role services.
Use the Add Roles and Features wizard from the Manage menu or the link in Server Manager. On the Server Roles step, check the box for Web Server (IIS).
After the Features step, the Role services step loads for Web Server (IIS). Select the IIS role services desired or accept the default role services provided.
Windows Authentication (Optional)
To enable Windows Authentication, expand the following nodes: Web Server > Security. Select the Windows Authentication feature. For more information, see Windows Authentication and Configure Windows authentication.
WebSockets (Optional)
WebSockets is supported with ASP.NET Core 1.1 or later. To enable WebSockets, expand the following nodes: Web Server > Application Development. Select the WebSocket Protocol feature. For more information, see WebSockets.
Proceed through the Confirmation step to install the web server role and services. A server/IIS restart isn’t required after installing the Web Server (IIS) role.
Windows desktop operating systems
Enable the IIS Management Console and World Wide Web Services.
Navigate to Control Panel > Programs > Programs and Features > Turn Windows features on or off (left side of the screen).
Open the Internet Information Services node. Open the Web Management Tools node.
Check the box for IIS Management Console.
Check the box for World Wide Web Services.
Accept the default features for World Wide Web Services or customize the IIS features.
Windows Authentication (Optional)
To enable Windows Authentication, expand the following nodes: World Wide Web Services > Security. Select the Windows Authentication feature. For more information, see Windows Authentication and Configure Windows authentication.
WebSockets (Optional)
WebSockets is supported with ASP.NET Core 1.1 or later. To enable WebSockets, expand the following nodes: World Wide Web Services > Application Development Features. Select the WebSocket Protocol feature. For more information, see WebSockets.
If the IIS installation requires a restart, restart the system.
Virtual Directories
IIS Virtual Directories aren’t supported with ASP.NET Core apps. An app can be hosted as a sub-application.
Sub-applications
An ASP.NET Core app can be hosted as an IIS sub-application (sub-app). The sub-app’s path becomes part of the root app’s URL.
Static asset links within the sub-app should use tilde-slash (
To host an ASP.NET Core app as a sub-app under another ASP.NET Core app:
Add the root site in IIS Manager with the sub-app in a folder under the root site.
Right-click the sub-app folder in IIS Manager and select Convert to Application.
In the Add Application dialog, use the Select button for the Application Pool to assign the app pool that you created for the sub-app. Select OK.
The assignment of a separate app pool to the sub-app is a requirement when using the in-process hosting model.
For more information on the in-process hosting model and configuring the ASP.NET Core Module, see ASP.NET Core Module.
Application Pools
App pool isolation is determined by the hosting model:
The IIS Add Website dialog defaults to a single app pool per app. When a Site name is provided, the text is automatically transferred to the Application pool textbox. A new app pool is created using the site name when the site is added.
Application Pool Identity
An app pool identity account allows an app to run under a unique account without having to create and manage domains or local accounts. On IIS 8.0 or later, the IIS Admin Worker Process (WAS) creates a virtual account with the name of the new app pool and runs the app pool’s worker processes under this account by default. In the IIS Management Console under Advanced Settings for the app pool, ensure that the Identity is set to use ApplicationPoolIdentity :
The IIS management process creates a secure identifier with the name of the app pool in the Windows Security System. Resources can be secured using this identity. However, this identity isn’t a real user account and doesn’t show up in the Windows User Management Console.
If the IIS worker process requires elevated access to the app, modify the Access Control List (ACL) for the directory containing the app:
Open Windows Explorer and navigate to the directory.
Right-click on the directory and select Properties.
Under the Security tab, select the Edit button and then the Add button.
Select the Locations button and make sure the system is selected.
Select OK.
Read & execute permissions should be granted by default. Provide additional permissions as needed.
Access can also be granted at a command prompt using the ICACLS tool. Using the DefaultAppPool as an example, the following command is used:
For more information, see the icacls topic.
HTTP/2 support
HTTP/2 is supported with ASP.NET Core in the following IIS deployment scenarios:
For more information on the in-process and out-of-process hosting models, see ASP.NET Core Module.
HTTP/2 is enabled by default. Connections fall back to HTTP/1.1 if an HTTP/2 connection isn’t established. For more information on HTTP/2 configuration with IIS deployments, see HTTP/2 on IIS.
CORS preflight requests
Application Initialization Module and Idle Timeout
When hosted in IIS by the ASP.NET Core Module version 2:
Application Initialization Module
Applies to apps hosted in-process and out-of-process.
IIS Application Initialization is an IIS feature that sends an HTTP request to the app when the app pool starts or is recycled. The request triggers the app to start. By default, IIS issues a request to the app’s root URL ( / ) to initialize the app (see the additional resources for more details on configuration).
Confirm that the IIS Application Initialization role feature in enabled:
On Windows 7 or later desktop systems when using IIS locally:
On Windows Server 2008 R2 or later:
Use either of the following approaches to enable the Application Initialization Module for the site:
Idle Timeout
Only applies to apps hosted in-process.
To prevent the app from idling, set the app pool’s idle timeout using IIS Manager:
To prevent apps hosted out-of-process from timing out, use either of the following approaches:
