Hack 59 IIS Administration Scripts

Here are some handy scripts that can be used to administer IIS from the command line .

Microsoft does a pretty good job of developing GUI tools for managing most aspects of Windows, but until only a few years ago they were weak on the scripting side. With the advent of Visual Basic Scripting Edition (VBScript) and the Windows Scripting Host (WSH), administering Windows from the command line became a reality. Incorporating Active Directory Services Interface (ADSI) into Windows 2000 and adding a Windows Management Instrumentation (WMI) provider for IIS into Windows Server 2003 has taken Windows scripting even further, and now you can manage just about any aspect of IIS in particular and Windows servers in general remotely from the command line.

Of course, someone still has to write the scripts.

Unfortunately, most administrators who work in the real world of supporting businesses' computing infrastructures have little time for the luxury of learning VBScript and WMI. Learning to write your own scripts to administer Windows is a time-consuming affair, and if you're responsible for managing users, keeping servers running, maintaining security, and preparing for disasters, then time is something that's usually in limited supply.

Fortunately, Microsoft has done some of the work for you by developing some handy scripts that can be used to simplify or automate IIS administration. This is especially true of IIS 6 (Windows Server 2003), but there's also some useful stuff you can use for IIS 5 (Windows 2000).

IIS 5 Scripts

Windows scripting was still in its infancy when IIS 5 was released, but Microsoft decided to include a few basic scripts with it (along with other sample content) to illustrate the power of what IIS could do. Four pairs of sample scripts are found in C:\Inetpub\iissamples\sdk\admin ; one script in each pair is written in VBScript and the other is written in JScript, a Javascript (ECMAScript) derivative that's fallen out of favor lately for writing Windows administration scripts. Although these scripts are mainly intended for learning purposes, a couple of them are useful, so I'll briefly summarize what they can do (I'll focus here on the VBScript versions only).

Metabase backups and restores can be performed from the command line by using metaback.vbs and metabackrest.vbs . These sample scripts require that you use Cscript.exe , the command-line version of WSH, to run them. For example, if you want to back up the metabase using 14 Nov 03 Backup as the name of the backup, just open a command prompt and type the following command:

 cscript C:\Inetpub\iissamples\sdk\admin\metaback.vbs "14 Nov 03 Backup" 

A metabase backup with that name will be created in the %SystemRoot%\system32\inetsrv\MetaBack folder with the filename 14 Nov 03 Backup.MD0 . You can even create multiple backups with the same name but different version numbers using the -v switch, like so:

 cscript C:\Inetpub\iissamples\sdk\admin\metaback.vbs "14 Nov 03 Backup" -v 15 

This command creates the backup file 14 Nov 03 Backup.MD15 . Versioning is a good way to keep track of minor configuration changes made while tweaking the metabase to improve IIS performance. And running the script repeatedly with the same backup name but without a -v switch will increment the version number of the backup file each time. Of course, like any script, you can also schedule its execution by using the Scheduled Tasks Wizard so that your metabase backups can take place on a regular basis during off hours.

Another script included in iissamples is mkwebsrv.vbs , which lets you create a new web site from the command-line. Here's an example of how it works:

 cscript C:\Inetpub\iissamples\sdk\admin\mkwebsrv.vbs C:\data -c "New Site"  -p 80 

This command creates a new web site named New Site , listening on port 80 and having C:\data for its home directory. This script is flaky, though, and can create only one new site before errors happen, so I don't advise using it (there's a much better replacement, which we'll discuss in a moment).

The last script is logenum.vbs , which can be used to enumerate the different logging modules installed on IIS. This is basically just a sample script to show how ADSI and VBScript can be used to administer IIS. Because it's not very useful, I won't say more about it.

And that's all the scripts in C:\Inetpub\iissamples\sdk\admin .

AdminScripts

Hidden away in another folder, C:\Inetpub\AdminScripts , there are many more scripts you can play with. And I do mean hidden; there's absolutely nothing mentioned in Windows 2000 Help concerning these scripts, and there's almost nothing mentioned on Microsoft's web site. You have to dig around in the Knowledge Base at Microsoft Product Support Services (http://support.microsoft.com) to find any information concerning these scripts. That shows the level of commitment Microsoft had to scripting, even as late as Windows 2000, doesn't it?

Anyway, let's see what these scripts can do. Most of them are quite short and simple. First, the findweb.vbs script is a useful little utility that can display information about a web site you specify. Here's an example of how it works:

 cscript C:\Inetpub\AdminScripts\findweb.vbs -w "New Site" 

Typing this command on my machine displays the IP address, port number, and even the site ID of a web site named New Site . Once you know the ID of a site [Hack #56], you can stop, start, pause, or continue that particular web site by using the stopweb.vbs , startweb.vbs , pauseweb.vbs , and contweb.vbs scripts. For example, the following command stops the web site that has a site ID of 10 in other words, New Site:

 cscript C:\Inetpub\AdminScripts\stopweb.vbs -a 10 

There are also similar scripts, such as stopftp.vbs , which can be used to control the status of individual FTP sites. And stopsrv.vbs can be used to stop both web and FTP sites in one operation. For example:

 cscript C:\Inetpub\AdminScripts\stopsrv.vbs -a w3svc/1 msftpsvc/1 

This command stops both the Default Web Site and Default FTP Site, while leaving both the WWW Publishing Service and FTP Service running. Of course, if you prefer, you can stop these services entirely by using net stop w3svc or net stop msftpsvc .

Then there's mkw3site.vbs , which is used to create new web sites. This definitely has more functionality than the sample mkwebsrv.vbs script found in the \iissamples\sdk\admin folder, and it has options for specifying the site's home directory, friendly name, port number, IP address, host header name, and even the site ID if you desire . For example, the following command creates a web site named My Site with a site ID of 101 , a home directory of C:\home , and an IP address of 212.44.64.24:

 cscript C:\Inetpub\AdminScripts\mkw3site.vbs -r C:\home -t "My Site" -i 212.44.64.24 -n  101 

A similar script, mkwebdir.vbs , can be used to create virtual directories within a web site and has similar syntax.

Chaccess.vbs is an interesting script that lets you modify the web permissions of a site programmatically. For example, the following command sets the web permissions for New Site (site ID 10 ) to allow Read and Script permissions but deny Write, Execute, and Directory Browsing:

 cscript C:\Inetpub\AdminScripts\chaccess.vbs -a w3svc\ROOT +read -write +script  -execute -browse 

Another interesting script is dispnode.vbs , which can display a host of information about any node in the metabase you specify. For example:

 cscript C:\Inetpub\AdminScripts\dispnode.vbs -a IIS://localhost/w3svc 

This command lists the web permissions, default document, anonymous user account, maximum number of connections, connection timeout, whether logging is enabled, and schema information about the metabase node.

Finally, there's adsutil .vbs , the mother of all IIS scripts. This script leverages the Active Directory Services Interface (ADSI) to programmatically manipulate many different aspects of IIS. The power of this little gem is best seen by some examples. You can modify web permissions using a command like this:

 cscript C:\Inetpub\AdminScripts\adsutil.vbs set w3svc/1/root /accesssource "true" 

This command allows Script Source Access on your home directory. The same can be done with other permissions, such as Read, Execute, and so on.

The adsutil.vbs script can also be handy if you have to restore the metabase from backup after reinstalling IIS (this works only after reinstalling IIS components , not after reinstalling your operating system). If you reinstall IIS and then use Internet Services Manager to restore a metabase backup, you'll receive an error message saying the restore failed. You can simply ignore the error message and type the following command from a command prompt:

 cscript.exe C:\InetPub\AdminScripts\adsutil.vbs enum w3svc 

This retrieves the password for the IWAM_computername account used by IIS (the enum option displays pretty much the whole contents of the metabase, which you have to wade through manually or pipe to grep if you have grep installed). Then, open the properties of the IWAM_computername account in Local Users and Groups in Computer Management and type the password you retrieved for it earlier. Finally, restore the same metabase backup again in Internet Services Manager and the metabase should be restored.

You can do many other neat things using adsutil.vbs , such as disabling socket pooling [Hack #60], enabling reverse DNS lookups, enumerating server bindings, configuring IIS to support both NTLM and Kerberos authentication, and modifying just about anything in the metabase you want to play with. For more information on adsutil.vbs , you can find a pile of Knowledge Base articles at the Microsoft Product Support Services web site (http://support.microsoft.com). You should know, though, that with the advent of IIS 6 on Windows Server 2003, ADSI is now considered on the way out and Windows Management instrumentation (WMI) is all the rage. But that's a story for a different book.

IIS 6 Scripts

Scripted administration of IIS has really matured on the IIS 6 platform with nine well-designed scripts written in VBScript to play with (no IIS 6 scripts were written in JScript). These scripts are much more functional and less likely to break than the sample scripts included with IIS 5. They are found in the %Systemroot%\system32 directory, which is part of the system path and thus makes using them more convenient . Also, instead of using ADSI, these scripts make use of WMI, a more powerful programmatic approach that can do almost anything on both local and remote servers.

In the following discussion, I'll leave out the cscript portion of each script command, because by registering CScript instead of WScript (the GUI version of CScript ) as your default host for VBScript, you can omit typing cscript at the beginning of each script command.

To register Cscript as your default host, either type cscript //H:cscript at a command prompt or simply try to run one of these scripts. You'll be presented with a dialog box that says "Would you like to register CScript as your default host for VBScript?" Click OK. Once you've done this, you don't need to type cscript at the beginning of a script command and you don't need to include the file extension of your script in the command. This definitely makes things more convenient.

Creating and managing web sites

First, you can create and manage web sites easily using the iisweb.vbs script. The syntax here is similar to mkw3site.vbs in IIS 5, but it's easier to use because it needs fewer switches to specify options. For example, to create a web site named Sales Web with an IP address of 205.16.45.12 and a home directory of C:\Sales , all you have to do is type the following command:

 iisweb /create C:\Sales "Sales Web" /i 205.16.45.12 

Other options for the /create switch let you specify a port number, host header name, and whether the web site should be started or stopped once it's created. The command displays output that verifies each setting it configures, including the randomly generated site ID number used by IIS 6 to uniquely identify each web site internally. One limitation of creating web sites with this script is that the home directory must be specified as an absolute path and located on the local IIS machine. This means that if you want to use a network share on another server as a home directory for your site, you'll have to open the site using Internet Services Manager and specify a UNC path to the remote home directory.

What else can you do with iisweb.vbs ? Well, you can use the /delete switch to delete any web site on your server, including those you created using the Web Site Creation Wizard started from Internet Services Manager. Using the /stop , /pause , and /start switches, you can stop, pause, and restart an individual web site (whether it was created with iisweb.vbs or Internet Services Manager) independently of all other sites hosted on the server. You can even stop, pause, or start multiple sites simultaneously by including their names in a single command. Of course, if you want to stop, pause, or start all web sites on your server, using the iisreset command is easier. Finally, the /query switch lets you display a summary of information concerning all web sites running on your machine. By redirecting this summary to a text file, you can quickly document the sites on your server.

Once you've created a new web site, you can add new virtual directories to it by using the iisvdir.vbs script. Again, this script can be used to create only local virtual directories (mapped to a physical folder on the IIS machine), not remote virtual directories (mapped to a network share); you can get around this limitation only by using the GUI. But you can also use the /delete switch to delete virtual directories and the /query switch to display all virtual directories within a given web site, including nested virtual directories. The syntax is easy to remember:

 iisvdir /create "Sales Web" reps C:\SalesPersons 

This command creates a virtual directory named reps within the web site named Sales Web and maps this virtual directory to the C:\SalesPersons folder on the machine's hard drive.

And guess what? Everything you can do with web sites can also be done with FTP sites by using the iisftp .vbs and iisftpdr.vbs scripts included with IIS 6.

Managing the metabase

What about managing the metabase? In [Hack #54], we learned the importance of regular metabase backups, and earlier in this hack we saw how the metaback.vbs and metabackrest.vbs sample scripts included with IIS 5 provide basic backup and restore functionality. Such functionality is greatly increased in IIS 6 with two new scripts: iiscnfg.vbs and iisback.vbs .

Backing up and restoring the metabase is done by using the /backup and /restore switches of iisback.vbs . These switches include the option of encrypting your backups with a password to make them more secure. For example, the following command creates a backup of Metabase.xml and MBSchema.xml in the MetaBack folder and encrypts the backup with the complex password pa$$w0rD :

 iisback /backup /b "14 Nov 03" /e pa$$w0rD 

One nice added feature that the earlier metaback.vbs script of IIS 5 lacks is the ability to list all backups from the command line and delete any that are no longer necessary by using the /list and /delete switches, respectively. You can also use the /restore switch to restore the metabase from either a backup file or history file, depending on your needs.

The other script, iiscnfg.vbs , is a powerful tool for exporting and importing IIS configuration information. The simplest use of this script is iiscnfg /save , which flushes the current in-memory metabase to disk. This is usually done automatically by IIS shortly after configuration changes are made, but if you're experimenting with configuration changes, you can use this to force IIS to save the metabase immediately and create a new history file as well. Metabase exports take all or a portion of MetaBase.xml and save it as an XML file in the directory you specify. For example, the following command takes everything in the metabase about the web site with site ID 1 (usually the Default Web Site) and exports it to the site1.xml file in the C:\stuff folder:

 iiscnfg /export /f C:\stuff\site1.xml /sp /LM/W3SVC/1 /inherited  /recursively 

Here, the /inherited option ensures that any metabase properties inherited at the /LM/W3SVC/1 level from higher levels, such as /LM or /LM/W3SVC , are explicitly written to the export file (since the target import server might not have these properties specified) and the /children option indicates that metabase subkeys should be recursively included in the export file. This is a great feature, because you can use it to export the exact configuration of a web site and then import the configuration (using iiscnfg /import ) into another IIS machine to clone a copy of the web site (you still have to copy the site content, though).

You can even clone the entire configuration of your IIS server by using iiscnfg.vbs to export the root metabase key ( / ). There's a caveat, though: exported files of metabase properties that are encrypted can't be imported to other machines. Also, you can't export the metabase schema file ( MBSchema.xml ) by using iiscnfg /export , so if you've made any modifications to the schema, this approach won't work. But most administrators never try to modify the schema anyway, because it's too risky and complicated, so the second limitation isn't really a problem. You can work around the first limitation (encrypted metabase properties); all you need to do is remove or modify any machine-specific settings from the export file before importing it into another IIS server. That means deleting keys that refer to IUSR or IWAM, special built-in accounts used by IIS for authentication purposes; deleting AdminACL settings in the top level (.) of the metabase; deleting keys that specify passwords for remote virtual directories or any other purposes; and modifying any keys that specify paths to content directories not mirrored on the target server. Once you've hacked away and made the necessary changes to your export file, you can import it to another machine and gain an exact clone of your original machine's configuration.

There are also other ways to clone configurations. The iiscnfg /copy command overcomes the limitation of exports by copying both the metabase configuration and the schema files to a remote machine. The command calls the iisback.vbs script and removes all machine-specific settings from the metabase, with the exception of content paths. So, if your target machine has a content file structure that is identical to your original machine, you can use iiscnfg /copy to clone IIS in one easy stop.

Why not use iiscnfg /copy all the time instead of using iiscnfg /export /sp / ? Though using /export is more complex, it also provides you with greater flexibility. It allows you to make any custom modifications you want to the metabase before you import your configuration to a new machine. For example, the /export switch also includes a /merge option that lets you merge virtual directories to consolidate and simplify a site. You can also use this option to merge good metabase settings over corrupt ones to recover a working metabase after something goes wrong. Anyway, that's just another of those tradeoffs that are common in administering servers: the method that requires more work is more flexible than the rigid, simple approach. Choose the right tool to meet your needs.

Managing web applications

Finally, IIS includes two scripts to manage web applications ( iisapp.vbs ) and web service extensions ( iisext.vbs ). The simple Iisapp.vbs script lists all web applications running on the server, displays their process identity (PID), and indicates the application pool to which they're assigned.

The Iisext.vbs script is more powerful and lets you display all web service extensions running on the server, show the actual executables of these extensions, add new extensions, and enable or disable extensions. For example, iisext /listapp displays Active Server Pages, Server-Side Includes, WebDAV, and any other extensions running on your server; iisext /listext does this in shorter form by displaying ASP, SSINC, and WEBDAV; and iisext /listfile displays the DLLs associated with these extensions, such as asp.dll , ssinc.dll , and httpext .dll . Application pools and web service extensions are new features of IIS 6; for more information on them, see IIS 6 Administration (Osborne/McGraw-Hill).

Running scripts remotely

Finally, another powerful feature of IIS 6 administration scripts is the ability to run them remotely from a Windows XP workstation or another Windows Server 2003 machine (you can't run them from Windows 2000 because that platform lacks a WMI provider for IIS). All of these scripts support the /u and /p options (to specify credentials that work on the remote machine) and the /s option (to specify the DNS name or IP address of the remote machine).

To create a web site named Products with a home directory of C:\stuff , IP address 202.44.33.11, and port number 80 on the remote IIS machine named WEBSRV99 , type the following command at a command prompt on your XP workstation:

 iisweb /create C:\stuff Products /b 80 /i 202.44.33.11 /s websrv99.mtit.com /u WEBSRV99\ Administrator /p pa$$w0rD 

Alternatively, telnet into the remote machine (if the Telnet Server services has been enabled on it) and leave out the /s websrv99.mtit.com portion of the command. Or, to run the command locally on the remote server, open a Remote Desktop Connection to the remote machine (if Remote Desktop has been enabled on it) and again leave out /s websrv99.mtit.com .

Which method is best? Unfortunately, using the /s option sends the credentials over the network in unencrypted form, and Telnet does the same. So, your safest bet is to enable Remote Desktop and use it for remotely managing IIS machines in your server room from your administrator workstation in your office.

Custom Scripts

If you have a working knowledge of VBScript, ADSI and WMI, you can easily write your own IIS administration scripts to accomplish various tasks. Here are two short but useful scripts to back up and restore the metabase on a remote IIS 5 machine.

First, here's the backup script:

 Dim IISComputer Dim Flags Dim TargetComputer TargetComputer = "   IISComputerName   " Flags = (MD_BACKUP_SAVE_FIRST Or MD_BACKUP_FORCE_BACKUP) Set IISComputer = GetObject("IIS://" & TargetComputer) IISComputer.Backup "   MyBackupFile   ", MD_BACKUP_NEXT_VERSION, Flags 

To use this script, simply replace the variables IISComputerName and MyBackupFile with the name of your web server and the full path to the backup file you create. Then, copy and paste the script into Notepad (make sure to have Word Wrap disabled) and save it with a .vbs extension. Make sure you have the latest scripting engines on the workstation from which you run this script. You can download the latest scripting engines from the Windows Script home page at MSDN (http://msdn.microsoft.com/library/default.asp?url=/nhp/Default.asp?contentid=28001169).

Here's a similar script for restoring the IIS 5 metabase to a remote machine:

 Dim IISComputer Dim TargetComputer Dim BackupLocation TargetComputer = "IISComputerName" BackupLocation = "PathToBackup" Set IISComputer = GetObject("IIS://" & TargetComputer) IISComputer.Restore BackupLocation, MD_BACKUP_HIGHEST_VERSION, 0 

Where to Find More Scripts

If you're into rolling your own WMI scripts, then more power to you; you have more time on your hands than I do. Busy geeks like me prefer to create our toolkit by collecting prefab stuff from various sources. Here are some places where you can find additional scripts for administering IIS.

The IIS Resource Kit (Microsoft Press) was written for IIS 4 (Windows NT) and is a bit out of date. But it still provides a useful introduction to the subject for newbies to Windows scripting. I still use this book from time to time, since IIS 5 is not that much different from IIS 4, but don't use it if you plan to work only with IIS 6, because of the architectural changes and enhancements on that new platform. The CD-ROM included with this book includes a number of useful scripts.

The IIS 5 Resource Guide , which is part of the Windows Server 2003 Resource Kit from Microsoft Press, also has some information on ADSI scripting, but it's pretty minimal. Most of the book focuses on deployment issues and performance tuning.

Chris Crowe's popular IISFAQ web site [Hack #61] has a pile of useful scripts, many of them written by Chris himself. If you are an administrator who works with IIS, you'd do well to spend a few hours becoming familiar with all the resources on this site.

Finally, there's the Windows Script Development Center at MSDN (http://msdn.microsoft.com/scripting/), which has a ton of information on how to get started writing your own WMI scripts, if you have the time and patience to do so.

Rod Trent and Mitch Tulloch