Windows Server 2008 Server Core : Managing IIS - Using the AppCmd Utility

1. Working from the Client

Working with IIS 7 from the client presents some special challenges. The IIS 6 utilities that come with Windows XP and older versions of Windows won't work with IIS 7. In addition, the GUI utilities for IIS 7 supplied with Vista won't work with Server Core because Server Core doesn't provide the required .NET Framework support. Therefore, it might seem as if your chances of working with IIS 7 from a client are limited. Of course, there are ways to overcome most problems and you do have options for working with IIS 7 from the client.

The first choice you have for working with IIS 7 from the client is to rely on Remote Desktop. If you plan to use the command line for management tasks, this is actually the best choice. You won't have to fight with the command line over rights or other issues that can plague you when you work from the command line on the client. Of course, you can always use any command line command or utility that does support a remote connection directly from the client command line. Be sure that Server Core grants you appropriate rights to complete the task when you use a remote connection.

A second choice for working with IIS 7 from the client is to install Windows PowerShell on the client. All of the Windows PowerShell commands include a -computer-computer command line switch because Windows PowerShell will log you into the remote system automatically. However, if you don't have the appropriate rights, then you can use Get-Credential command to obtain the proper credentials and pass them to the server. Of course, using Windows PowerShell currently represents a significant increase in complexity. command line switch that you can use to access the remote system. If you have the appropriate rights on the remote system using your current account, all you need to provide is the

A fourth choice is to modify the CONFIG files directly from the client system. You can create a share on the server, use the ICACLs utility to set security properly, and then map a drive to it. Windows Explorer provides the access you require to the server and the CONFIG files it contains. Now you can open the CONFIG files on the client using a product such as XML Notepad as if the file were local to your machine.

The four options provide you with some good ideas for working with Server Core from the client. Using these four techniques, you can create any setup you require. Of course, there are probably other ways to perform the task as well. When working with Server Core, creativity is the key word. You're working with a stripped down version of the operating system that gives you some significant advantages, but you must find ways to overcome some of the connectivity disadvantages and, of course, the lack of a functional GUI for configuring applications.

2. Using the AppCmd Utility

The AppCmd utility is the command line utility used to manage every aspect of IIS 7.  This utility uses the following syntax:

APPCMD (command) (object type) [<identifier>] [</parameter1:value1 ...>]

Each of these entries provides a complex data entry. The following sections describe each of these entries in detail. AppCmd provides vast capabilities, so it's important to work with this utility for a while using a test system so that you can see the results of any configuration tasks you perform.

2.1. An Overview of the Object Types

The commands that you can use are directly related to the object type you choose to use. However, AppCmd supports an assortment of general commands that meet most needs. While a command specifies the kind of task to perform, the object type determines how to apply the command. For example, you might want to apply the command to the CONFIG object. The identifier determines which Web site to work with. If you don't provide an identifier, any task you perform applies to the Web site as a whole. Finally, some tasks require that you provide input parameters (arguments). Here are the object types that the AppCmd utility supports.

APP

Performs management tasks with applications. You can add, delete, and list applications. In addition, you can change the application configuration using the Set command. IIS 7 comes with one default application, APP "Default Web Site/" (applicationPool:DefaultAppPool), which you can see by typing AppCmd List APP and pressing Enter. The default information only shows the application name and its associated application pool. If you want see a complete listing, type AppCmd List APP /text:* and press Enter.

APPPOOL

Manages the application pools used to run each application. IIS 7 creates worker processes for each application in an application pool. You can create as many application pools as needed to ensure applications perform as expected and don't interfere with other applications. IIS 7 comes with a single application pool, the DefaultAppPool. When an error does occur and the applications within a particular application pool fail, the system normally starts a new worker process and gracefully terminates the existing worker process in a process called recycling. You can manually recycle an application pool to fix errors immediately by typing AppCmd Recycle APPPOOL "DefaultAppPool" and pressing Enter (where DefaultAppPool is the name of the application pool you want to fix). You'll see a success message when the recycling process completes.

BACKUP Backs up and restores data on your server. You can also delete backups you no longer need and configure backups to meet specific needs. The default settings perform backups automatically, so if you have used IIS 7 for any length of time you can type AppCmd List BACKUP and press Enter to see a list of the backups. To restore a backup, you must know the name of a backup on your system. For example, typing AppCmd Restore BACKUP "CFGHISTORY_0000000006" and pressing Enter restores the backup entitled, CFGHISTORY_0000000006. If you want to restore the backup without stopping the server first, include the /stop:false command line switch.

CONFIG

Performs general configuration of the server and individual Web sites.

MODULE

Installs, uninstalls, and manages server modules. IIS 7 uses a modular approach to working with server components. You don't have to install all of the modules that IIS 7 provides to obtain certain levels of functionality. In addition, IIS 7 only loads the modules it actually needs to perform a task.  Don't confuse the Install and Uninstall commands with the Add and Delete commands. You use the Install and Uninstall commands to add or remove modules. The Add and Delete commands configure modules you already have installed.

REQUEST

Monitors HTTP requests for your system. This object has only one command, List. You use it to obtain a list of current HTTP requests for the server. You can only use this object for monitoring purposes—it doesn't let you add or delete requests.

SITE

Manages the virtual sites on your server. IIS 7 comes with one virtual site installed, the Default Web Site. You can use the commands associated with this object to add or remove sites, start or stop them, configure them, or provide a detailed listing of configuration information. The default output information of the List command is usually inadequate for learning anything about the site—it only includes the virtual site name, identifier, bindings, and state. If you really want to know as much about the sites as possible, type AppCmd List SITE /text:* > SiteConfiguration.TXT. The SiteConfiguration. TXT file contains complete statistics about the sites on your server. Remember that you can specify a site if you don't need to know about all of the sites on your server. For example, type AppCmd List SITE "Default Web Site" /text:* and press Enter to learn about the Default Web Site. It's also possible to work with sites using their URL. For example, type AppCmd List SITE http://localhost /text:* to discover everything about the Default Web Site by accessing it using its URL. Sometimes you need specific information. In this case, you can specify the information you want to see using the /text command line switch. For example, type AppCmd List SITE /text:limits.maxBandwidth and press Enter to see the maximum bandwidth for each site.

TRACE

Manages the failed request trace logs. IIS 7 doesn't configure any trace logs by default because this is a debugging object. Consequently, you must first configure a trace log before you can do anything with it. After some time, the trace log will have entries in it. You use the List command to see all of the trace logs you have created on the server. The Inspect command lets you see the content of the logs. For example, if you want to configure a trace log for the Default Web Site for all ASP requests that take more than 60 seconds, you would type AppCmd Configure TRACE "Default Web Site/" /enablesite and press Enter to enable tracing on the Web site (which is turned off by default). You would then type AppCmd Configure TRACE "Default Web Site/" /enable /path:*.ASP /timeTaken:"00:01:00" and press Enter to create the trace log. Notice that you must supply the Default Web Site path, not the Default Web Site name (which is why the example includes a completing backslash). AppCmd also lets you use an URL as input to the command. The following list describes the special command line switches for this object.

/enablesite

Enables the Failed Request Event Buffering feature on the site.

/disablesite

Disables the Failed Request Event Buffering feature on the site.

/enable

Enables (adds, when necessary) a log file for a particular Failed Request Event Buffering rule. The rule specifies what kind of monitoring to perform. For example, you can specify a particular path. You can enable monitoring for all requests by supplying the asterisk (*) instead of a specific path.

/disable

Disables (removes) a Failed Request Event Buffering rule.

/path:

Pathname

Defines the path that you want to use for debugging purposes. You can use any valid filename specification and include wildcard characters as needed for the Pathname variable. If you decide that you want to monitor all paths, then use the asterisk (*) by itself.

/areas:

Provider/Area[,Provider/Area...]

Defines the areas of interest for a trace log. These areas help determine what the trace log tracks. This command line switch lets you include multiple entries. Examples of common areas include ASP/ (note that there isn't an area in this case), ASPNET/Infrastructure, ASPNET/Module, ASPNET/Page, ASPNET/ AppServices, ISAPI Extension/ (note that there isn't an area in this case), WWW Server/ Authentication, WWW Server/Security, WWW Server/Filter, WWW Server/StaticFile, WWW Server/CGI, WWW Server/Compression, WWW Server/Cache, WWW Server/ RequestNotifications, WWW Server/IISGeneral, and WWW Server/All. In order to use a particular provider, you must register in the system.webServer/tracing/traceProviderDefinitions section of the ApplicationHost.CONFIG file. The default setting is to add all of the providers and areas defined for the current system.

/verbosity:{Ignore | CriticalError | Error | Warning}

Determines the amount of information that IIS 7 records about entries in the trace log. The Ignore setting provides the least amount of information, while the Warning setting provides the most information. The default verbosity is Error.

/timeTaken:

Timespan

Determines how long IIS waits to make an entry in the trace log, even when the request eventually succeeds. This setting helps you track down requests that require too much time to complete. Even if there isn't anything wrong with your server, you can use this setting to monitor the performance of the Web site under a normal load. You must define either the /timeTaken or the /statuscodes arguments to create a functional entry.

/statuscodes:

CodesAsInt

Defines the status codes that the trace log will track. For example, you might not be interested in tracking the 200 (success) messages. You can see a list of the standard HTML codes at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html. This command line switch is inclusive. You can't use it to exclude the 200 messages, but you can use it to include the 500 messages. The default status codes include 500,400,401, and 403. You must define either the /timeTaken or the /statuscodes arguments to create a functional entry.

VDIR

Creates, removes, and manages virtual directory entries for the server. The default setup includes a root directory for the Default Web Site. When adding a new virtual directory, you normally include an application name, path within the Web site, and physical path. For example, if you want to add a new virtual directory with the name MyVDir that has a physical path of C:\Temp, you would type AppCmd Add VDIR /app.name:"Default Web Site/" /path: /MyVDir /physicalpath:C:\Temp and press Enter. The VDIR object is often used with other commands. For example, if you type FOR /F %f IN ('AppCmd List VDIR /text:physicalPath') DO DIR %f and press Enter, you'll receive a directory listing for each of the virtual directories on the server.

WP

Monitors the worker processes currently executing on the server. You can only list the worker processes—you can't add or delete worker processes. If you find that a particular worker process is frozen or otherwise incapacitated, use the APPPOOL Recycle command to fix the problem.

You provide an object type every time you want to perform a task. For example, if you want to create a virtual directory for a Web site, then you must use the VDIR object.

2.2. An Overview of the General Command Line Switches

The AppCmd utility also supports a number of general command line switches that work with every object type. These general command line switches modify how AppCmd performs a task in some way. The following list describes each of these general command line switches.

/?

Displays context sensitive help that depends on the content of any other command line arguments. For example, if you type AppCmd /? and press Enter, you'll see a listing of the object types and general command line switches. However, if you type AppCmd CONFIG /? and press Enter, you'll see a list of commands the that CONFIG object supports. When you type AppCmd List CONFIG /? and press Enter, you'll see examples of how to use the List command with the CONFIG object.

/text:{

*

|

value}

Specifies the preferred output information. When you include the asterisk (*), the command outputs all available information about the object. You can also specify a value that reflects a particular entry for the object. For example, if you want to display just the maximum bandwidth for each of the Web sites on the server, you'd type AppCmd List SITE /text:limits.maxBandwidth and press Enter.

/xml

Outputs the information as XML instead of pure text. Seeing the information in this format helps you locate the correct entries in the CONFIG file when modifying files by hand. In addition, you can ensure you typed a command correctly when you see blank output. For example, when you type AppCmd List APP /XML and press Enter, you'll see XML output such as this for the default setup.

<?xml version="1.0" encoding="UTF-8"?>
<appcmd>
    <APP path="/"
         APP.NAME="Default Web Site/"
         APPPOOL.NAME="DefaultAppPool"
         SITE.NAME="Default Web Site" / />
<appcmd>

/in or - Accepts input from the standard input device in XML format. You can use this feature to transfer information from one application to another in XML format.

/config[:*]

Displays the configuration information for the selected object. Adding the asterisk (*)provides all of the configuration information, including inherited information, rather than a summary. For example, if you type AppCmd List APP /config and press Enter, you'll see the following output for the default configuration (notice that this output lacks the XML header provided with the /xml command line switch, but it also includes additional configuration information).

<application path="/">
  <virtualDirectoryDefaults />
  <virtualDirectory
     path="/"
     physicalPath="%SystemDrive%\inetpub\wwwroot" />
  <virtualDirectory path="/MyVDir" physicalPath="C:\Temp" />
</application>

/metadata Displays the configuration metadata for the selected object.

/commit:{app | parent | url | apphost | webroot | machine}

Determines where AppCmd saves configuration changes that you make. In most cases, you'll never use this command line switch on Server Core. When Microsoft eventually adds ASP.NET support, you may use it to configure some ASP.NET features. The TechNet article at http://technet2.microsoft.com/windowsserver2008/en/library/30884867-a56d-4f31-8143-be0f35a30f8d1033.mspx describes these commands in detail. Note that you normally combine this command line switch with a /section command line switch and an attribute argument.

/debug

Displays debugging information for each of the commands that you type. For example, when you type AppCmd List APP /debug and press Enter, you see an additional line of output that includes INFO (timetaken:31, hresult:00000000, objects:1). The time taken to perform the task is in milliseconds. The hresult value tells you whether there are any errors (a value of 0 indicates no errors). The object's value tells you how many objects participated in the command.

Working with the AppCmd Commands

The AppCmd utility provides a number of basic commands that you can use with particular objects. The purpose is essentially the same in each case. For example, the Create command creates a new instance of a particular object and you can use the List command to display a list of all of the objects of that type. Table 1 shows which commands you can use with each object.

Now that you have a basic idea of which commands are available, you'll want some additional information on how to use them. The following list describes each of the commands and helps you understand what they do.

Add

Adds a new object or a new object entry. The goal of the Add command is to add a new entry to the configuration file for an existing object. When you need to add a new object, you'll normally rely on another command such as Configure or Install.

Clear

Clears a configuration setting without actually removing it. This command comes in handy when you need to remove the values associated with a configuration entry, without deleting it. For example, if you type AppCmd Clear CONFIG "Default Web Site/" -section: defaultDocument and press Enter, you'll clear the default documents associated with the Default Web Site. You must provide a defaultDocuments section, but it need not contain any document entries.

Configure

Adds or removes trace log entries.

Delete

Removes an existing object or object entry. The goal of the Delete command is to remove an entry in the configuration file for an existing object.

Inspect

Displays the content of trace log entries.

Install

Adds a new module to the server. You can also achieve this goal using the PkgMgr utility.

List

Outputs information about the requested object. The information is based on the XML data contained within the CONFIG files for the Web site or server.

Lock

Makes it impossible to change a configuration entry.

Migrate

Creates a backup of the configuration settings for a server. This command isn't the same as performing a data backup using the BACKUP object. While the BACKUP object works with the Web site data, this command works with the Web site settings.

Recycle

Resets the specified application pool to ensure that all worker threads are working as intended.

Reset

Sets a configuration setting to its default setting. This command is contrasted with the Clear command, which makes the configuration setting blank. For example, if you clear the default document settings, then the Web site won't have any default documents associated. However, resetting the configuration adds the default documents found in IIS when you first install it.

Restore

Restores a previous backup when working with BACKUP object.

Search

Locates a particular configuration setting within the CONFIG file.

Set

Modifies an existing object or object entry. The goal of the Modify command is to change an entry in the configuration file for an existing object. AppCmd will always tell you whether the changes you make are successful.

Start

Starts an application pool or Web site so that it can perform useful work. As soon as the application pool or Web site is running, the associated application or Web site will begin responding to user requests (this action can require several seconds to complete).

Stop

Stops an application pool or Web site. Any applications or Web sites that rely on the object will cease to respond to user requests.

Unlock

Makes it possible to change a previously locked configuration entry.

Uninstall

Removes a module from the server. You can also achieve this goal using the PkgMgr utility.