IIS Site Logging | Windows NT/2000 ADSI Scripting for System Administration

IIS Site Logging

With IIS, you have a host of options available for configuring site access logs. These logs are useful for auditing site access, for use with trend analysis tools (such as WebTrends), or even for replaying a specific historical event with the IIS Log Replay utility for troubleshooting.

Four logging providers are included with IIS 4.0:

Microsoft IIS Log File Format
NCSA Common Log File Format
ODBC Logging
W3C Extended Log File Format

Logging Provider Support in Each IIS Service

The ability to log user activities is common to all IIS services; however, each IIS service maintains its own set of supported logging providers.

Use Table 8.1 to determine which log formats are supported in each IIS service:

+ The plus symbol indicates that the log file format is supported by the service.

- The minus symbol indicates that the log file format is not supported by the service.

Table 8.1. Service Support for Log File Formats

Logging Provider	WWW Service	FTP Service	SMTP Service	NNTP Service
Microsoft IIS Log File Format	+	+	+	+
NCSA Common Log File Format	+	-	+	+
ODBC Logging	+	+	+	+
W3C Extended Log File Format	+	+	+	+

Enable Logging

To begin, logging must be enabled for the site. In the Internet Service Manager, click the check box captioned Enable Logging. Using Visual Basic, the process is also fairly simple ”you simply modify the LogType property's value to log access to the site.

Tip

For each code example, although the W3SVC IIS service is used in the binding string, you can easily substitute the appropriate service provider name (such as MSFTPSVC, SmtpSvc, or NNTPSVC) into the string.

Querying Current Logging Status Using Visual Basic

Use the following Visual Basic code to determine whether logging is enabled for a particular site:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Debug.Print Site.LogType

Setting Logging Status Using Visual Basic

To enable logging for a particular site, set the value of the LogType property to 1. To disable logging for the site, set the property to 0.

Use the following Visual Basic code as a guide for your efforts:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Site.LogType = 1 Site.SetInfo

Active Log Format

Using the LogPluginCLSID property of each IIS service provider object, you can query and toggle the active log format used for logging client requests . The IIS Metabase refers to this object by class ID (CLSID), not by name. This makes life rather interesting because you must relate names to CLSIDs in order to query or select the active log format.

By binding the Web server's logging object, you can find the names and CLSIDs of all installed providers. After you have obtained this information, you then have enough data to relate CLSIDs to friendly names anywhere the CLSID is returned from a property Get statement.

Querying Active Log Format Using Visual Basic

Use the following Visual Basic code to determine the active log file format for a given resource:

 Dim Site As IADs Dim Log As IADs Dim ServerName As String Dim SiteIndex As Long ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Set Log = GetObject("IIS://" & ServerName & "/logging") For Each Item In Log   If Site.LogPluginCLSID = Item.LogModuleID Then     Debug.Print Item.Name   End If Next

Setting Active Log Format Using Visual Basic

If you want to set the log format programmatically, you must know either the CLSID or the friendly name of the logging object to be able to assign a new provider.

In the following code example, you'll pass in the friendly name (it must be exact) to assign the new logging provider using Visual Basic:

 Dim Site As IADs Dim Log As IADs Dim ServerName As String Dim SiteIndex As Long Dim NewLogFormatName As String ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value NewLogFormatName = "NCSA Common Log File Format" 'NewLogFormatName = "ODBC Logging" 'NewLogFormatName = "Microsoft IIS Log File Format" 'NewLogFormatName = "W3C Extended Log File Format" Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Set Log = GetObject("IIS://" & ServerName & "/logging") For Each Item In Log     If Item.Name = NewLogFormatName Then         Site.LogPluginCLSID = Item.LogModuleID         Site.SetInfo     End If Next

Tip

To enumerate the logging provider names on your machine, use the following Visual Basic code:

 Dim Log As IADs Dim ServerName As String ServerName = "IIS_Server_Name" Set Log = GetObject("IIS://" & ServerName & "/logging") For Each Item In Log    Debug.Print Item.Name Next

Advanced Log Format Properties

Each log provider exposes properties that allow you to manipulate extended information specific to the provider. In the case of ASCII text file-based logging, this may include the collection period and log path . In the case of the ODBC logging provider, you can specify the Data Source Name (DSN), table name, and user credentials.

Each provider maintains a unique configuration. In this section, you will examine each provider and explore the programmatic mechanism to manipulate the extended properties.

Log Period and Path Property Configuration for ASCII-Based Log Providers

Both the Microsoft IIS Log File Format and NCSA Common Log File Format providers create an ASCII text file containing a variety of information, which is not user-configurable. The only configurable parameters for these providers are the collection period and directory to be used to store the logs (see Figure 8.3).

The W3C Extended Log File Format log provider extends the logging configuration options beyond simple file path and collection period properties to include the ability to specify the events you wish to view in the log.

Figure 8.3. Microsoft Logging Properties dialog box. (Similar to NCSA Common Log File Format and W3C Extended Log File Format General Properties tab.)

graphics/08fig03.gif

To query or set the log collection period, you can manipulate the LogFilePeriod property of the bound service provider object.

Querying New Log Time Period Using Visual Basic

IIS uses four integers to represent the collection period for log files:

Integer	Time Period
	Unlimited
1	Daily
2	Weekly
3	Monthly

To query this property, simply examine the current value of the LogFilePeriod property, as shown in the following Visual Basic code:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Debug.Print Site.LogFilePeriod

Setting New Log Time Period Using Visual Basic

To set a new log file collection period, use the following Visual Basic code:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long Dim NewLogFilePeriod As Integer ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value NewLogFilePeriod = 1 Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Site.LogFilePeriod = NewLogFilePeriod Site.SetInfo

Closing Logs Based on File Size

In addition to closing chronology-based logs, you can also close log files based on the size of the file. To do this, simply assign the LogFileTruncateSize property to the maximum size of the file you wish to create.

After the log has reached the specified size, the server opens a new log file. This can be especially handy for archiving logs to removable media where a specific size may be needed to get the log to fit on the disk.

Querying Maximum Log File Size Using Visual Basic

Consider the following Visual Basic code to query the log file truncation point:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Debug.Print Site.LogFileTruncateSize

Setting Maximum Log File Size Using Visual Basic

To set a new maximum size for a log file, use the following Visual Basic code:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long Dim NewLogFileSize As Long ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value NewLogFileSize = 1048576 Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Site.LogFileTruncateSize = NewLogFileSize Site.SetInfo

Note

To truncate the log at the specified size, you must also set the LogFilePeriod property to 0.

W3C Extended Log File Provider Properties

Of all the log file providers, the W3C Extended Log File Format provides the most detailed and configurable set of options for which data you include in your log files (see Figure 8.4). In addition to the basic file path and collection period information, you can also choose from as many as 20 different parameters to make your logs as detailed or basic as you wish.

Figure 8.4. W3C Extended Logging Properties dialog box.

graphics/08fig04.gif

Note

Each extended logging option uses a Boolean value to describe its state.

Additionally, it is important to note that some options are not utilized by all IIS providers.

Querying Extended Logging Options Using Visual Basic

Use the following code to generate a table of these parameters in the Immediate window of the Visual Basic IDE:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Debug.Print "Log Date: " & vbTab & vbTab & vbTab & Site.LogExtFileDate Debug.Print "Log Time: " & vbTab & vbTab & vbTab & Site.LogExtFileTime Debug.Print "Log Client IP Address: " & vbTab & Site.LogExtFileClientIp Debug.Print "Log User Name: " & vbTab & vbTab & Site.LogExtFileUserName Debug.Print "Log Service Name: " & vbTab & vbTab & Site.LogExtFileSiteName Debug.Print "Log Server Name: " & vbTab & vbTab & Site.LogExtFileComputerName Debug.Print "Log Server IP: " & vbTab & vbTab & Site.LogExtFileServerIp Debug.Print "Log Server Port: " & vbTab & vbTab & Site.LogExtFileServerPort Debug.Print "Log Method: " & vbTab & vbTab & vbTab & Site.LogExtFileMethod Debug.Print "Log URI Stem: " & vbTab & vbTab & vbTab & Site.LogExtFileUriStem Debug.Print "Log URI Query: " & vbTab & vbTab & Site.LogExtFileUriQuery Debug.Print "Log Http Status: " & vbTab & vbTab & Site.LogExtFileHttpStatus Debug.Print "Log Win32 Status: " & vbTab & vbTab & Site.LogExtFileWin32Status Debug.Print "Log Bytes Sent: " & vbTab & vbTab & Site.LogExtFileBytesSent Debug.Print "Log Bytes Received: " & vbTab & Site.LogExtFileBytesRecv Debug.Print "Log Time Taken: " & vbTab & vbTab & Site.LogExtFileTimeTaken Debug.Print "Log Protocol Version: " & vbTab & Site.LogExtFileProtocolVersion Debug.Print "Log User Agent: " & vbTab & vbTab & Site.LogExtFileUserAgent Debug.Print "Log Cookie: " & vbTab & vbTab & vbTab & Site.LogExtFileCookie Debug.Print "Log Referrer: " & vbTab & vbTab & vbTab & Site.LogExtFileReferer

Setting Extended Logging Options Using Visual Basic

Use the following code as a guide to specify the extended logging options for the W3C Extended Log File Format log provider:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Site.LogExtFileDate = True Site.LogExtFileTime = True Site.LogExtFileClientIp = True Site.LogExtFileUserName = True Site.LogExtFileSiteName = True Site.LogExtFileComputerName = True Site.LogExtFileServerIp = True Site.LogExtFileServerPort = True Site.LogExtFileMethod = True Site.LogExtFileUriStem = True Site.LogExtFileUriQuery = True Site.LogExtFileHttpStatus = True Site.LogExtFileWin32Status = True Site.LogExtFileBytesSent = True Site.LogExtFileBytesRecv = True Site.LogExtFileTimeTaken = True Site.LogExtFileProtocolVersion = True Site.LogExtFileUserAgent = True Site.LogExtFileCookie = True Site.LogExtFileReferer = True Site.SetInfo

ODBC Log Provider Properties

If you want to view the log file using an ASP, you can set up an ODBC database to handle all logging requests (see Figure 8.5).

Although the ODBC log file provider makes viewing access logs from the Web extremely easy (using ADO in an ASP directly to the logging table), it comes at the cost of performance. ODBC logging has the worst performance of all logging providers available in the default installation of IIS. It should not be used unless you plan to implement a Web-based tool for monitoring site access logs or have a specific reason to use it.

Figure 8.5. ODBC Logging Properties dialog box.

graphics/08fig05.gif

To enable ODBC logging, you must first use an ODBC-compliant database platform (such as Access, SQL Server, Oracle, or Sybase) to create a table with the fields as shown in Table 8.2.

Table 8.2. Field Definitions for ODBCLog Format Tables

Field Name	DataType
ClientHost	varchar(255)
Username	varchar(255)
LogTime	Datetime
Service	varchar(255)
Machine	varchar(255)
ServerIP	varchar(50)
ProcessingTime	Int
BytesReceived	Int
BytesSent	Int
ServiceStatus	Int
Win32Status	Int
Operation	varchar(255)
Target	varchar(255)
Parameters	varchar(255)

Next, you must set up a system DSN on the IIS Server to point to the database. If the database requires user credentials, these credentials can be specified in the IIS ODBC log properties. With the logging environment established, you can now configure IIS to begin using the ODBC database for logging.

Note

To configure ODBC logging, only four properties must be assigned:

The DSN to use ( LogOdbcDataSource )
The name of the table ( LogOdbcTableName )
The username required to access the table ( LogOdbcUsername )
The associated password for the username ( LogOdbcPassword )

Querying ODBC Logging Information Using Visual Basic

To query the ODBC logging configuration parameters, use the following Visual Basic code:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Debug.Print Site.LogOdbcDataSource Debug.Print Site.LogOdbcPassword Debug.Print Site.LogOdbcTableName Debug.Print Site.LogOdbcUserName

Setting ODBC Logging Information Using Visual Basic

To modify an existing site's ODBC logging configuration, use the following Visual Basic code:

 Dim Site As IADs Dim ServerName As String Dim SiteIndex As Long Dim ODBC_DSN As String Dim DBPassword As String Dim TableName As String Dim UserName As String ODBC_DSN = "Name_of_Data_Source_to_Use_With_ODBC_Logging" DBPassword = "DB_Access_Credential" TableName = "Logging_Table_in_DB" UserName = "DB_Access_Credential" ServerName = "IIS_Server_Name" SiteIndex = Site_Index_Value Set Site = GetObject("IIS://" & ServerName & "/W3SVC/" & SiteIndex) Site.LogOdbcDataSource = ODBC_DSN Site.LogOdbcPassword = DBPassword Site.LogOdbcTableName = TableName Site.LogOdbcUserName = UserName Site.SetInfo

Top