IIS Web Server

Supported Technologies

Confirm that the tCell agent supports your IIS Web Server configuration, as shown below:

Prerequisites

Before starting, confirm you have:

• Set up a tCell account
• Created a tCell application (Admin > Applications)

Installation

Get the Config File

1. Click on "Admin" in tCell console top navigation bar
2. Create New API Key
3. Click "Download Agent"
4. Select the "Web Server Agent" tab
5. Select "IIS"
6. Download the msi installer
7. Click "Download Config File" to download the agent's config file, (which is prefilled with the application and key information)

Install the agent manually

To manually install the agent:

1. Run the msi installer and follow the instructions. This will install the agent and put the required files in the directory you specify. By default, the directory is C:\Program Files\Rapid7, Inc\tCell IIS Agent.
2. Place the "tcell_agent.config" file in the root directory of your web application.
3. If you have more than 1 application running on the same IIS you only need to add a separate tcell_agent.config (configuration) file and place it in the root directory for each application. You will want to create separate applications in the tCell console for each application and modify the config file with the correct app_id and api_key for each application.
4. Open a command prompt as administrator and run the command "iisreset" to restart IIS.
5. Initialize the agent by running some HTTP/S requests through your application, since the agent will not fully initialize and run without HTTP/S requests. tCell now protects your application.

Installing the agent via command line

A command line-based installation is helpful for some use cases, such as CI/CD deployment. To install using command line, follow these steps:

1. Launch Windows command line
2. Change the directory to the location of the installer
3. Run the following command, substituting with the IIS agent version:.

Command Line Example
1
msiexec /i tcell-iisagent-<VERSION>.msi /quiet

Note: version numbers normally have 4 digits, such as 1.1.2.0

For example, for version 1.1.2.0, one would run:

1.1.2.0 install example
1
msiexec /i tcell-iisagent-1.1.2.0.msi /quiet

If the agent is not installed, this normally occurs because:

• msiexec is not running from the installed directory
• The version number is incorrect

Prevent IIS recycling on IIS 7.5 or later

If you’re running IIS 7.5 or later, IIS will recycle your application if it's idle for 20 minutes or longer. When this happens, the agent will unload, stop running, and will show as offline in the tCell console. If a request comes in, the agent will start again. If you don't want IIS to recycle the application when it's idle, you can change your application’s start mode and idle-timeout for your application pool. Note that IIS will still recycle based on its regular recycle schedule. By default, this is set to 1740 minutes, or 29 hours. To change your Start Mode and Idle Time-out:

1. Go to advanced settings for your application pool by right clicking on you application pool and selecting advanced settings
2. Set the Start Mode to AlwaysRunning, which is found under “General”
3. Set the Idle Time-out (in minutes) to 0. This can be found under Process Model.

Uninstall the IIS Agent

You can uninstall the agent in one of these ways:

• Manually
• Through command line

Uninstall the agent manually

1. Open "Program and Features/Apps & Features"
2. Search for tCell
3. Right click the tCell IIS Agent
4. Select uninstall If the agent is in use, a restart might be required.

Uninstall the IIS Agent through command line

1. Launch Windows command line
2. Go to the directory where tCell installer is located
3. Type the following, substituting with the IIS agent version:.

Command Line Details
1
msiexec /x tcell-iisagent-<VERSION>.msi /quiet

Limitations

Login events and OS Command features are not supported in IIS Agent.

Troubleshooting

Startup errors for IIS Web Server

To enable startup error logging, set the TCELL_AGENT_STARTUP_ERROR_LOGGING environment variable to true or specify a valid path. This flag will create a file called tcell_critical_error.log in the root folder of the application running or at the path specified if there's an error at startup.

Logging

As of IIS agent v2.0.0, the default location for log and cache files is c:\ProgramData\Rapid7, inc\tCell IIS Agent[IIS application id].

You can customize the log level in the tcell_agent.config file by adding a block such as the following:

agent config snippet
1
"logging_options": {
2
    "enabled":true,
3
    "level":"DEBUG"
4
 }

IIS Agent debug log

If no logs appear in the log directory you can create the directory "C:\tcell". This is the default directory for IIS agent debug logs.

1. Add the user running the IIS application as full control to the directory.
2. Restart IIS.
3. A log file should be created with information about the agent startup.

Valid log levels are:

• ERROR
• WARN
• INFO (default)
• DEBUG
• TRACE

The preceding list indicates the precedence among the levels, from top to bottom. When you enable a log level, the higher log levels are also enabled. For example, if you enable WARN, then ERROR is also enabled.

When a log file becomes full, logging continues in a new log file. See Log Rolling for more information.