- 31 Jul 2024
- 4 Minutes to read
- Print
- PDF
IIS
- Updated on 31 Jul 2024
- 4 Minutes to read
- Print
- PDF
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.
Support matrix
Component | Version |
---|---|
Windows Server | 2016 and above. |
Powershell | 6 and above. |
If you have a Windows server and Powershell version earlier than the one mentioned in the table above, contact Traceable support at support@traceable.ai.
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:
Install Traceable agent
Register the agent
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
Step 1 — 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.
Step 2 — 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 that you should include a 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 allows you to enable or disable server-side certificate verification. Enter 1 to enable or 0 to disable server-side verification.
Step 3 — Instrument the agent
To collect the data for analysis, you need to instrument the IIS agent. You can instrument the agent either at the global level or at the 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:
Environment variable | Description |
---|---|
| Configure this to disable capturing the response. Set |
| Configure this to disable capturing the request body. Set |
| Configure this to disable capturing the response body. Set |
| Configure this to set the maximum body size. The default value is 131072 bytes. |
| Configure this to enable debug logging. Set the value to |
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:
Uninstrument the website, either globally or individually, based on how you had instrumented it. Use
Remove-GlobalInstrumentation
andRemove-AppInstrumentation
in the PowerShell.Unregister the agent using the
Unregister-Agent
command in the PowerShell.Uninstall the agent using the
Uninstall-Agent
command in the PowerShell.