IIS Modules Overview

by IIS Team, Mike Volodarsky

Compatibility

Introduction

The IIS 7 and above Web server feature set is componentized into more than thirty independent modules.

A module is either a Win32 DLL (native module) or a .NET 2.0 type contained within an assembly (managed module). Similar to a set of building blocks, modules are added to the server in order to provide the desired functionality for your applications. Likewise, all IIS modules can be removed, or replaced with custom modules developed using the IIS C++ APIs, or the familiar ASP.NET 2.0 APIs.

This article describes common IIS module management tasks, and details each module including its configuration settings and the potential effect a module removal has on the Web server. The management examples are given using both the graphical IIS Manager and the AppCmd command line tool.

Prerequisites

To follow the steps in this document it is best to do a full install of IIS.

To Perform a Full Installation of IIS on Windows Vista, Windows 7, Windows 8, Windows 10 or Windows 11

1. Click Start and then click Control Panel.
2. In the Control Panel, click Programs.
3. Under Programs and Features, click Turn Windows features on or off.
4. In the Windows Features dialog, expand Internet Information Services and select all features.
   You may need to expand some categories to select all the features in that category.
5. Click OK.

To Perform a Full Install of IIS on Windows Server 2008/R2, Windows Server 2012/R2, or Windows Server 2016

1. Open Server Manager > Roles and select Web Server (IIS).
2. Check all features under Web Server.

Getting Started with Modules

In order to add a module to the server, you must perform two steps:

1. Install a module on the server (native modules only).
2. Enable the module in an application.

The first step registers the module globally with the server, making it available within each server worker process. It is necessary only for native modules due to the trusted nature of native code, and is available only to administrators.

The second step enables the module to execute within a particular application and effectively allows the application administrator to control the server features enabled for the application. This step allows both installed native modules and managed modules to be enabled for each application.

To Install a Native Module

In order to install a native module, it must be registered with the server using one of the options below:

• Manually editing the IIS configuration store. In IIS 7.5 and later you can use the Configuration Editor in the IIS Manager.
• Using the IIS Manager
• Using the AppCmd.exe command line tool

All three of these options result in the module entry being added to the <globalModules> IIS configuration section, which can be set only at the server level. To examine the contents of this section, open the root configuration file located in %windir%\system32\inetsrv\config\applicationhost.config, and search for the string "<globalModules>".

After a full IIS installation, this section contains an entry for each of the native modules shipped with IIS, specifying a name and the path to the module DLL:

<globalModules>
    <add name="DefaultDocumentModule" image="%windir%\system32\inetsrv\defdoc.dll" />
    <add name="DirectoryListingModule" image="%windir%\system32\inetsrv\dirlist.dll" />
    <add name="StaticFileModule" image="%windir%\system32\inetsrv\static.dll" />
    ...

</globalModules>

All of these modules are described in detail later in this document.

To Uninstall a Native Module

You can uninstall a native module if that module is no longer in use on the server, or if you would like to replace it with another module. Remove the corresponding module entry from the <globalModules> configuration list, and the associated entry in the <modules> configuration list using one of the following options:

• Manually editing the IIS configuration store. In IIS 7.5 and above you can use the Configuration Editor.
• Using the IIS Manager
• Using the AppCmd.exe command line tool

Enabling a Module for an Application

A module must be enabled before it can provide service for a particular application. In order to enable a native module, it must first be installed on the server (see the previous section, To Install a Native Module).

A managed module does not require installation, and can be enabled directly for each application. This allows applications to include their managed modules directly within the application by registering them in the application's web.config file, and providing the implementation in /BIN or /App_Code directories.

To enable a module, do one of the following:

• Manually edit the IIS configuration store, either globally to enable the module for all applications on the server, or in a particular web.config file located within each application for which you would like to enable this module. In IIS 7.5 or above you can use the Configuration Editor.
• Use the IIS Manager
• Use the AppCmd.exe command line tool

All three of these options add the module entry to the <modules> IIS configuration section, which is can be set at both the server level and application level. Examine the contents of this section by opening the root configuration file located in %windir%\system32\inetsrv\config\applicationhost.config, and searching for the string "<modules>".

Unlike native modules, a managed module does not require adding an entry to the <globalModules> configuration section.

After a full IIS installation, the configuration section contains an entry for each of the modules (both managed and native) that shipped with IIS. The entry indicates that all these modules are enabled by default for all applications on the server. Each entry in this section specifies either the name of a native module that was previously installed on the server, or the name and .NET type of a managed module:

<modules>
<add name="DefaultDocumentModule" />
<add name="DirectoryListingModule" />
<add name="StaticFileModule"/>
 ...

</modules>

Disabling a Module in an Application

Disable a module if that module is no longer in use in the application, or if you want to replace it with another module. To disable a module, remove the corresponding module entry from the <modules> configuration collection for a particular application where you do not want this module to execute. If the module is enabled at the server level, remove it there to disable it in all applications on the server by default. Use one of the following options to remove the module at the server level:

• Manually edit the <system.webServer>/<modules> configuration section in your application.
• Use the IIS Manager.
• Use the AppCmd.exe command line tool.

After the module is removed from the application, it will not be active in that application. However, if the module is native, it will still be loaded in the server worker process, and may be used by other applications that did not remove it.

Preconditions

There is another attribute on a module entry called precondition. The IIS core engine uses preconditions to determine when to enable a particular module. Performance reasons, for example, might determine that you only want to execute managed modules for requests that also go to a managed handler. The precondition in the following example (precondition="managedHandler") only enables the forms authentication module for requests that are also handled by a managed handler, such as requests to .aspx or .asmx files:

<add name="FormsAuthentication"type="System.Web.Security.FormsAuthenticationModule" preCondition="managedHandler" />

If you remove the attribute precondition="managedHandler", Forms Authentication also applies to content that is not served by managed handlers, such as .html, .jpg, .doc, but also for classic ASP (.asp) or PHP (.php) extensions. See "How to Take Advantage of IIS Integrated Pipeline" for an example of enabling ASP.NET modules to run for all content.

You can also use a shortcut to enable all managed (ASP.NET) modules to run for all requests in your application, regardless of the "managedHandler" precondition. To enable all managed modules to run for all requests without configuring each module entry to remove the "managedHandler" precondition, use the runAllManagedModulesForAllRequests property in the <modules> section:

<modules runAllManagedModulesForAllRequests="true"/>

When you use this property, the "managedHandler" precondition has no effect and all managed modules run for all requests.

Querying, Adding and Removing Modules Using the IIS Manager

The IIS Manager provides an easy way to query, add or remove modules.

1. To open the IIS Manager, click Start, type inetmgr in the Search box, and then press ENTER.
2. Click the computer name of your IIS server.
3. Click the Modules icon in the IIS category.

Figure 1: IIS Manager

To manage the enabled modules for a particular application

1. Connect to that application using the tree view on the left.
2. Navigate to the Modules feature pane.
3. Click Add Managed Module to add a Managed Module to your application. Add Native Module only allows you to add a module that is already registered on the Server level.

To remove a module from your application

1. Click the module in the list. The Remove task displays in the left pane.
2. Click Remove.

Figure 2: Modules List in IIS Manager

Managing Modules from the Command Line

To quickly manage modules from the command line, or script module management tasks, use the AppCmd.exe command line tool.

To install a module using AppCmd.exe

At the Command Prompt, type the following command, replacing values in italics with the values for the module on your computer.

Appcmd.exe install module /name:MODULE_NAME /image:PATH_TO_DLL

For example, the following command installs the Default Document module.

%windir%\system32\inetsrv\appcmd.exe install module /name:DefaultDocumentModule /image:%windir%\system32\inetsrv\defdoc.dll

If you run the command on a computer where the module is already loaded, you wil get an error message similar to the following:

ERROR (message:Failed to add duplicate collection element "DefaultDocumentModule".)

To uninstall a module using AppCmd.exe

At the Command Prompt, type the following command, replacing values in italics with the values for the module on your computer.

Appcmd.exe uninstall module MODULE_NAME

For example, the following command uninstalls the Default Document module. This command is provided only as example. You should only run it on a test server.

%windir%\system32\inetsrv\appcmd.exe uninstall module DefaultDocumentModule

To list the modules enabled either for an application or globally

At the Command Prompt, type the following command, replacing values in italic text with the values for the module on your computer.

Appcmd.exe list modules [/app.name:APPLICATION_NAME]

For example, the following command lists the modules enabled for the Default Web Site.

%windir%\system32\inetsrv\appcmd.exe list modules /app.name:"Default Web Site"

And this command lists the modules installed globally.

%windir%\system32\inetsrv\appcmd.exe list modules

To enable a module either for a particular application or globally

At the Command Prompt, type the following command, replacing values in italic text with the values for the module on your computer.

Appcmd.exe add module /name:MODULE_NAME /type:MGD_TYPE

For example, the following command adds the Forms Authentication module to the Default Web Site.

%windir%\system32\inetsrv\appcmd.exe add module /name:FormsAuthentication /type:System.Web.Security.FormsAuthenticationModule /app.name:"Default Web Site"

And this command adds the Forms Authentication Module globally.

%windir%\system32\inetsrv\appcmd.exe add module /name:FormsAuthentication /type:System.Web.Security.FormsAuthenticationModule

To disable a module either for a particular application or globally

At the Command Prompt, type the following command, replacing values in italic text with the values for the module on your computer.

Appcmd.exe delete module MODULE_NAME [/app.name:APPLICATION_NAME]

For example, the following command removes the Forms Authentication module from the Default Web Site.

%windir%\system32\inetsrv\appcmd.exe delete module FormsAuthentication /app.name:"Default Web Site"

And this command removes the Forms Authentication Module globally.

%windir%\system32\inetsrv\appcmd.exe delete module FormsAuthentication

To get more help on the syntax for each of the App Cmd.exe commands

To display the commands supported on the Module object type the following command:

Appcmd.exe module /?

To display the usage of each command, type the following command:

Appcmd.exe install module /?Appcmd add module /?

Module Reference

The IIS server is ready for customizing. Read the following list carefully to avoid side-effects, feature loss or removing security features.

Utility Modules

These modules do not provide request services, but instead assist the server engine with its internal operation.

Managed Modules: