IIS

IIS, or Internet Information Services, is a powerful web server software developed by Microsoft to host websites, web applications, and Windows server services. As one of the world's most widely used web servers, IIS provides a robust and secure platform for delivering web content and applications to users across the internet or within private networks. The Traceable IIS agent is installed inline and is an ext_cap based agent. If, for some reason, Traceable cannot capture the request, the requests are passed through to the application. The following is a high-level deployment diagram:

Before you begin

Make a note of the following points before you begin with the installation:

• Traceable's IIS agent supports both .NET core and .NET applications.

• Make sure that your Traceable Platform agent is already installed and configured. Keep the IP address of your Traceable Platform agent handy, as the IP address would be required when you register the IIS agent. For more information on Traceable Platform agent, see Platform agent installation.

• Make sure that port number 5442 or 5443 on the Traceable Platform agent is reachable, as this is the default port for ext_cap.

• The Traceable IIS agent does not support request blocking.

• Make sure that you have reasonable knowledge of Microsoft IIS. For more information, see IIS documentation.

If you are installing the agent manually, make sure to not place the dll file in C:\user\* and its subdirectories, as this may create permission issues. The steps in the following sections are for automated deployment.

Download

Navigate to Traceable's download site to download the installation file. Browse to agent → iis and download the latest zip file. The downloaded zip file contains the dll file. 

Installation and instrumentation

The installation is a three-step process as listed below:

1. Install Traceable agent

2. Register the agent

3. Instrument, either globally or for an individual website

The Traceable agent exports the following functions:

• Install-Agent

• Uninstall-Agent

• Register-Agent

• Unregister-Agent

• Add-GlobalInstrumentation

• Remove-GlobalInstrumentation

• Add-AppInstrumentation

• Remove-AppInstrumentation

Import and install Traceable agent

To install the Traceable agent, open admin PowerShell from the folder that has the dll file. Import the agent by entering the following command in the PowerShell:

Import-Module .\traceable-install-module.psm1 -Force

Install the agent by using the Install-Agent command in PowerShell. This command places the agent dll inside C:\Program Files\Traceable IISAgent.

-Force is an optional parameter for the Import-Module command. When -Force is used, it ensures that the module or agent is imported even if it was already imported earlier. This can be useful for reloading a module if you have made changes to it or if there are conflicts with previously imported versions.

Register the agent

When you register the agent, it becomes available as a native module on IIS. Enter Register-Agent command in PowerShell. As part of the registration of the agent, you would need to provide the URL of your Traceable Platform agent. Provide the URL as http://<traceable_platform_agent_IP_address>:5442. You can verify whether the agent has registered by checking the list of configurable native modules. The script also prompts the Service name suffix, which will be appended to the website name, for example, `-QA`. Note to include separator as part of the entered suffix.

Following is a sample command:

Register-Agent -TPAEndpoint "https://example.com/tpa" -TPACertPath "C:\Path\To\TPACert.pem" -ServiceNameSuffix "MyService" -SSLEnabled "1"

TLS based connection

If you are setting up a TLS-based connection between Traceable Platform and .NET agent, provide the URL as https://<traceable_platform_agent_IP_address>:5443. The script also prompts you to enter the certificate path. Enter the location of the certificate. If you use a non-TLS-based connection, do not enter anything on the prompt. The script also gives you an option to enable or disable server-side certificate verification. Enter 1 to enable or 0 to disable server-side verification.

Instrument the agent

You need to instrument the IIS agent to collect the data for analysis. You can instrument the agent either at the global level or at an individual website level.

Instrument agent globally

To instrument the IIS agent globally, use Add-GlobalInstrumentation command in the PowerShell. This will instrument all IIS websites present on the server.

Instrument agent for a website

To instrument individual IIS websites, use Add-AppInstrumentation command in the PowerShell. When you instrument the agent, make sure to give the exact name of the website. For example, as shown in the screenshot below, the website name is 3.1-core. 

Following is a sample command:

Add-AppInstrumentation -website "Website name"

Note

Do not instrument the agent at the global and individual website level simultaneously as it would add duplicate entry in IIS configuration. If you wish to instrument the agent globally after instrumenting it for an individual website, then first uninstrument the agent for the website and then instrument it globally.

Environment variables

You can configure the following environment variable in your IIS server for additional control:

Verification

After a successful installation and instrumentation, you will see the Traceable agent listed as TraceableIISAgent inside the module list of the website in the IIS manager.

Uninstall

The uninstallation process is the reverse of installation and instrumentation. The process to uninstall is:

1. Uninstrument the website, either globally or individually, based on how you had instrumented it. Use Remove-GlobalInstrumentation and Remove-AppInstrumentation in the PowerShell.

2. Unregister the agent using the Unregister-Agent command in the PowerShell.

3. Uninstall the agent using the Uninstall-Agent command in the PowerShell.