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 the increase of the number of customers accessing resources 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 capabilities 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.

Web farms - server clusters - have become a standard in helping deliver highly scalable, available and manageable applications by distributing load. More specifically, these application attributes are the main reasons behind web farms and load balancing. Through a web farm, an organization can provide a scalable way to increase the capacity of the user base that accesses the application and its resources concurrently.

The server cluster provides improved availability by having multiple machines distribute the load. The cluster also scales better to an increased number of customers at a 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 walkthrough focuses on the shared centralized global configuration feature. This is a new feature in the IIS 7.0 web server that helps support homogeneous web farms where machines share the same configuration across a server group. This aspect of web farms has improved in IIS 7.0 through the advent of centralized configuration via a UNC share, in which a change in a central master configuration file will propagate across different machines at once without extra tools or programmatic support.

The first part of the walkthrough shows how to use the new IIS 7.0 administration UI to enable and use shared configuration. The second part looks at how to do this from the command-line.      

This article contains:

• Prerequisites
• Centralized Configuration – Using the UI 
• Command-Line Prompt
• Backing Up the Current applicationHost.config
• Have a User Available to Access the UNC Share for Configuration
• Create the UNC Shares for Central Configuration and Content
• Give Permissions to the Accounts for the UNC Shares That Host Central Configuration and Content
• Redirecting the Configuration
• Testing the Configuration
• Summary
• Appendix 1: Accessing Redirection.config Programmatically to Read the Values
• Appendix 2: Accessing redirection.config Programmatically to Write the Values
• Appendix 3: Dealing With Machine-specific Encrypted Properties

Non-Goals: What This Does Not Cover 

There are multiple aspects that compose 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 machines. There are tools and other features that help with managing multiple machines with tools or user interfaces, copying content, deploying modules, synchronizing application binaries, setting up third party components, etc. All of these tools, features, and aspects are out-of-the-scope of this document.

This document only details maintaining configuration via a central file across machines.

Therefore, note that shared configuration enables a machine to access a configuration file in a back end UNC share as if it were its local configuration. This enables a key scenario: updating configuration via a front-end Web server updates all other machines. This is good for updating configuration properties that can be understood by the system.

It very important to take into consideration other situations (such as installing a third-party module or adding configuration settings) and include properties that only one machine understands (and has the binaries and schema available for its correct functionality). Otherwise, this type of usage breaks the other machines.

To avoid this problem in homogeneous farms, disable shared configuration on the cluster, update the local applicationHost file so that it mirrors the remote one, deploy and update modules and configuration on a single machine, and then re-enable shared configuration on that machine. Once that step works, it is only a matter of deploying and updating the binaries and modules on the rest of the machines before enabling shared configuration again.

Note: Domain and Non-domain Environments

Some administrators deploy web server clusters in a domain environment while others in a workgroup (non-domain). This walkthrough covers both scenarios, and points out the differences and caveats. Note that the recommended way of setting up IIS 7.0 in a cluster is in a domain with the help and security that Active Directory provides via a domain controller. However, given that the workgroup (non-domain) environment is also prevalent, this document explains that setup as well.

Prerequisites

Observe the following in order to complete this walkthrough:

Centralized Configuration – Using the UI

The new IIS 7.0 administration UI includes support for setting up configuration redirection. The UI provides support for exporting configuration files and necessary encryption keys to a specified path.

The steps below use the UI to export the necessary files and setup configuration redirection.

Steps

1. Open InetMgr.exe - click Start, type Inetmgr.exe into the Start Search box and press Enter.
2. When the UI opens, select the server connection in the tree view for which you want to setup configuration redirection.
3. Open the Shared Configuration feature.

    4. To export the necessary configuration files from the local machine to another location (e.g., a UNC share), click the Export Configuration task on the Actions pane.

 

6. Next, enable the configuration redirection. Check the Enable shared configuration check box.

7. Before you can click Apply, you must specify the path where the configuration and encryption keys are located and specify the credentials used to access that path. Click Connect As... and enter the credentials.

8. After entering the path and credentials, click Apply to save the settings. The UI checks to ensure that the necessary files exist at the specified location -- if they do, the UI asks for the password that was used to password protect the encryption keys.

9. Enter the correct password and click OK to finish setting up the configuration redirection.

The steps above show how to both export the configuration and turn on centralized configuration. However, you only need to export configuration once and then perform steps 6 to 9 on each subsequent machine that will use that centralized configuration.

Some Notes About Using the UI

There are some important things to note about using the UI to enable configuration redirection. When using the setup configuration redirection, the UI expects that the exported files it is being told to use have been exported using the UI. This is because the UI exports and imports items such as the password protected encryption keys using its own custom format.

If you were to manually copy the administration.config and applicationHost.config files to a share and then manually export the encryption keys (as explained in the "Dealing with machine-specific encrypted properties" appendix), you would not be able to use the UI to setup configuration redirection to point to those files; this is due to the fact that the exported encryption keys are not in the format required by the UI.

Command-Line Prompt

Throughout the remainder of this article, you must use a command-line prompt to run certain commands. It is recommended that you use a command prompt with elevated privileges, as certain commands will not work if you run a normal command prompt. Here is how to open a command prompt with elevated privileges:

Backing Up the Current applicationHost.config

It is always a good practice to back up the current applicationHost.config file when trying out new features or changing multiple configuration settings.

Steps:

1. Open up a command-line prompt by pressing the Windows Key + Run and typing CMD in the text prompt.

2. Go to the IIS 7.0 directory. This is located in the %WINDIR%\System32\InetSrv directory by default. The configuration files are stored in the InetSrv\Config directory. Backup the applicationHost.config file by creating a backup object with the aid of the APPCMD command-line tool.

Note: The APPCMD tool resides in the InetSrv directory. Unless the tool has its path added to the system's environment variables, you must access it from within the InetSrv directory.

cd /d %windir%\system32\inetsrv
appcmd add backup centralConfigBackup

3. This creates a backup object which will include the applicationHost.config file and the legacy metabase file (for SMTP and other non-web server settings) into a backup folder. List this backup object and make sure it is present.

In order to replace the current configuration file with the backed-up one, do the following steps.

1. Open up a command-line prompt by pressing the Windows Key + Run and typing CMD in the text prompt.

2. Go to the IIS 7.0 directory. This is located in the InetSrv directory by default. Restore the APPCMD backup file object.

Have a User Available to Access the UNC Share for Configuration

In a domain environment, another administrator will provide this account or you create it. The creation of an account in a domain to use with Active Directory is out of the scope of this document.

However, this account has to be setup with the correct permissions to access the UNC share. In a non-domain account scenario, there must be a local user created on both machines that has rights to access the content. The name and password of the user must be the same across machines in order for it to work on this setup. The following steps help in the creation of a user to read the share where the shared configuration resides.

Steps: Non-domain

1. Open up a command-line prompt by pressing the Windows Key + Run and typing CMD in the text prompt.

2. Create a user called ConfigUser1 with password ConfigPass1 on the web server machine (the front-end machine where the IIS 7.0 server is installed).

3. Do the same on the other machine. Create a user called ConfigUser1 with password ConfigPass1 on the file server machine (the back-end machine, where the central configuration will reside).

Create the UNC Shares for Central Configuration and Content

This UNC share for configuration hosts the applicationHost.config file for any machines that wish to pickup configuration data from this centralized location.

Steps

1. Open up a command-line prompt in the file server machine by pressing the Windows Key + Run and typing CMD in the text prompt.

2. Go to the root of the drive. Create a directory for configuration and then share this directory, making sure to grant users permissions to read and write to it.

Note: This command has automatically given permissions to the user group to this share. The user created for the non-domain scenario will have change permissions automatically, which can be restricted more if needed. As for the domain account scenario, it will either have to have permissions set explicitly to access the share or be added as part of the users group in the system.

3. Non-domain scenario: In order to increase the security of the share, substitute the Users,Change portion of the /grant switch with ConfigUser1,Change parameters. That way, only that user has access to the share and not the other users on the system.

4. Domain scenario: In order to increase the security of the share, you can substitute the Users,Change portion of the /grant switch with domain\user,Change parameters. That way, only that user has remote access to the share and not the other users on the system.

Note: Permissions on a share are a union between remote and local filesystem permissions. The next step in the walkthrough, setting up permissions to the directory, must occur in order for a domain account to be able to read the configuration share successfully.

Give Permissions to the Accounts for the UNC Shares That Host Central Configuration and Content

This step ensures that the account used to access configuration has the permissions it needs. This account is used by IIS 7.0 to access the UNC share in the same manner in which it accesses content when a virtual directory is mapped to a UNC share. The read permissions for this account are useful when accessing the share only. After that point, whenever IIS 7.0 reads the configuration file, it reverts back to the identity that the caller has: either the API, the administration tool being used, or the user logged at that moment.

Note: The ConfigUser1 account - or the equivalent domain account used to read configuration - is not the same as the one used for writing configuration. These accounts are not required to have write permissions to the share or configuration file.

Steps: Domain

1. If the domain account is part of the local users group, and the users were granted access when the share was created, then skip the next steps of domain setup. However, since a common situation is that the domain account to access the local fileshare is not part of any local user groups, then the next permission command must be executed.

2. Open up a command-line prompt in the file server machine by pressing the Windows Key + Run and typing CMD in the text prompt.

3. Provide permissions to the domain account to read the directory where configuration is stored.

icacls %SystemDrive%\centralconfig\ /grant domain\user:R

Steps: Non-Domain and Domain

For both domain and non-domain scenarios, the username must include logon batch job configuration. This is not a default setting in Windows Servers® 2008; add it manually to the web server machine.

1.  Open the Start menu and then go to Administrative Tools and select Local Security Policy from the menu that appears.

2.  Under "Local Policies" select "User Rights Assignments".

3.  Double-click "Log on as a batch job" and add the created UNC user.

Redirecting the Configuration

Introduction

The webserver is functional. The front-end web server should be serving its Default Web Site via the localhost loop back address.

Now to move its configuration to a central location. This is the purpose of this document: showcasing the shared configuration feature via configuration redirection. This feature provides the benefit of the ability to declare a file and save it in a UNC share that is the master file for configuration for multiple machines. Changing this file once will provision and update all the machine's configuration at once.

Steps

1. Copy the applicationHost.config and administration.config files from the %windir%\system32\inetsrv\config directory on the front-end web server machine to share on the the back-end file server machine. If the current logged-in account can have write access to the back-end share, this is as easy as dropping the file in the directory. If not, then be sure to authenticate yourself to the back-end to be able to complete this step.

2. Access the existing redirection configuration XML file titled "redirection.config" in the front-end machine's configuration directory:

a. Open via Windows Explorer %windir%\system32\inetsrv\config.

b. Open redirection.config. This file and its contents are created when the web server is setup to provide a way for tools and APIs to access this file and determine whether or not this feature is enabled.

3. Open the redirection.config file. Set the following configuration, taking care to put the correct machine name, username and password for your environment.

<configuration>
    <configSections>
        <section name="configurationRedirection" />
    </configSections>
    <configurationRedirection enabled="true" path="\\machinename\centralconfig$\" userName="ConfigUser1 or domain\user" password="ConfigPass1 or domainPassword" />
</configuration>      

4. Save your redirection.config file. You now can access the sites again, but the configuration is now stored in a UNC share.

Testing the Configuration

With configuration being referenced from the back-end, there are two key scenarios that this feature was designed for. These are ways to update configuration in the front-end webservers.

The first way is to edit the applicationHost.config file directly on the fileshare. Once this is done, change notifications take place and the web servers pickup the changes in the file.

The other option is to drop a second applicationHost.config file in the back-end file share and change the web server's redirection.config file to point to the new version of the file. This is useful for rollback purposes or staged deployments.

Summary

This walkthrough introduced the new centralized configuration feature. This feature aids administrators that have homogeneous clusters in a web farm environment and helps set and deploy configuration to all the machines 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 webserver. 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. There are several aspects and solutions to deal with configuration and content, its provisioning, changing and deployment. This document only covered the central configuration aspect.

Appendix 1: Accessing Redirection.config Programmatically to Read the Values

This step provides a sample of how to access redirection.config 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.

Steps

1. Create a text file and save it with the .js extension. This script provides a sample on how to read the enabled attribute, machine name, username and password for your environment.

2. Save your redirection.js file. You should now be able to run this file from a command-line window thanks to Windows Script Host (WSH).   

Appendix 2: Accessing redirection.config Programmatically to Write the Values

This step provides a sample of how to access redirection.config 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.

Steps

1. Create a text file and save it with the .js extension. This script provides a sample on how to write the enabled attribute, machine name, username and password for your environment.

try
{
    var config = WScript.CreateObject( "Microsoft.ApplicationHost.WritableAdminManager" );
  config.CommitPath = "MACHINE/REDIRECTION";
    var section = config.GetAdminSection( "configurationRedirection","MACHINE/REDIRECTION" );
  section.Properties.Item( "enabled" ).Value = true;
  section.Properties.Item( "path" ).Value = "\\\\somemachine\\sharefile://folder/";
  section.Properties.Item( "userName" ).Value = "testuser";
  section.Properties.Item( "password" ).Value = "testuser";
  config.CommitChanges();
}
catch(e)
{
  WScript.Echo(e.number);
  WScript.Echo(e.description);
}

2. Save your redirection.js file.

3. You should now be able to run this file from a command-line window thanks to Windows Script Host (WSH).

Appendix 3: Dealing With Machine-specific Encrypted Properties

By default, IIS 7.0 includes two main providers for securing properties. These providers are found in the applicationHost.config configuration section <configProtectedData> section and are defined in the <providers> element.

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.

These keys are in the iisConfigurationKey and iisWasKey key containers. These are machine specific keys. In a web farm scenario, if encryption is required, then a key from one machine - usually the one that created the applicationHost.config file - is exported and brought into the other machines so that secure properties can be decrypted and used by the webserver.

Steps

1. Open your a command-prompt. Navigate to the Framework directory, which by default is %windir%\Microsoft.NET\Framework\v2.0.50727\.
Note: For reference, the machine keys for the system are in %ALLUSERSPROFILE%\Microsoft\Crypto\RSA\MachineKeys\

2. 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 wish 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 in order 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 7.0 uses is the "iisWasKey" key container.

aspnet_regiis -px "iisConfigurationKey" "D:\iisConfigurationKey.xml" -pri

3. The tool states that exporting was a success. Copy the XML file to the other machine in the cluster to prepare to import it there.

4. 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 7.0 uses is the "iisWasKey" key container.

aspnet_regiis -pi "iisConfigurationKey" "D:\iisConfigurationKey.xml"

Related Content

Comments