Windows

Traceable provides a Windows mirroring agent. The mirroring agent captures and stitches your application's request and response data and sends it to the Traceable Platform agent. The mirroring agent can be installed on the same machine as your application or on a different virtual machine. The following deployment diagram shows a setup where the application and the mirroring agent are installed on other machines.

Traceable’s Windows mirroring agent uses WinPcap. WinPcap is a network packet capture library designed for Windows operating systems. It provides tools and APIs for capturing and analyzing network traffic, and it is primarily used for network monitoring, packet analysis, and network-related development tasks.

Before you begin

• Make sure to download the Windows mirroring agent from Traceable’s download site. Navigate to agent → mirroring-agent.

• You must have already downloaded and installed the Traceable Platform agent. For more information, see Platform agent.

• Make sure that you have admin privileges for PowerShell on Windows.

Extract interface name

To install the Windows mirroring agent, you would need the interface name of the machine where you would like to install the mirroring agent. Complete the following names to extract the interface name:

1. Run getmac /fo csv /v

   Information

   The command getmac is used in Windows operating systems to retrieve information about the MAC (Media Access Control) addresses of network interfaces on a computer.

2. Note the transport name property, which should be something like - "\Device\Tcpip_{D7F2A7DC-EA23-44EF-8EBE-84GAD862A9D8}"

3. Replace the word Tcpip with NPF in the above string.

4. Note the network interface value as the edited string - \Device\NPF_{D7F2A7DC-EA23-44EF-8EBE-84GAD862A9D8}. Your machine’s interface name should be similar to this.

Installation

To start the installation process, import the module by entering the following command in an admin PowerShell:

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

Traceable mirroring agent module exports the following six functions:

• Install-Deps

• Update-Config

• Install-Agent

• Start-Traceable

• Stop-Traceable

• Uninstall-Agent

You can install the mirroring agent using either the interactive or silent installation.

Option 1 — Interactive installation

The Install-Agent function places the binary and config file in the C:\Program Files\Traceable MirroringAgent directory. Run Install-Deps from your PowerShell. Install-Deps is a non-interactive WinPcap installer. It silently installs required drivers.

The Install-Agent function asks for the following:

• Interface — Provide an interface where you wish to attach the mirroring agent to capture the data packet. Select the number corresponding to the interface you want to capture.

• Remote endpoint of Traceable Platform agent — The endpoint used to communicate with the Traceable Platform agent for platform configurations. Provide the input in <ip/DNS>:5441 or <ip/DNS>:5443 format depending on whether you wish to communicate over TLS or not.

• Reporting endpoint for Traceable Platform agent — The endpoint that is used to send spans to the Traceable collector. Provide the input in <ip/DNS>:4317 or <ip/DNS>:5443 format depending on whether you wish to communicate over TLS or not.

• (Optional) BPF filter to capture specific traffic — This is used to capture specific traffic. You can leave this empty to capture all TCP traffic on the machine.

• (Optional ) Path to certificate file to — Provide the path to the certificate if TLS is configured; otherwise, leave it empty.

Option 2 — Silent installation

You can also perform a silent installation of the mirroring agent by providing all the options in a single command. Complete the following steps:

1. Enter the following command to import the module:

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

2. Run the Install-Deps function.

3. Enter the following command for silent installation:

   install-Agent -Remote "<ip_address:port>" -Reporting "<ip_address:port>" -Interface "<Interface_Name>" -CertFile "<Cert file if conneciton is on tls>" -BPFfilter "<BPF Filter>" -SilentInstall $true

   For example:

   install-Agent -Remote "<ip_address:5441>" -Reporting "<ip_address:4317>" -Interface "\Device\NPF_{D7F2A7DC-EA23-44EF-8EBE-84GAD862A9D8}" -CertFile "<Cert file if conneciton is on tls>" -BPFfilter "<BPF Filter>" -SilentInstall $true

   Here, the interface value is the value that you extracted earlier using the getmac /fo csv /v command.

Note that -CertFile and -BPFfilter are optional arguments.

Here’s an example of how to use the -BPFfilter parameter in the install-Agent command:

Example:

-BPFfilter "tcp port 443"

This example filter captures only TCP traffic on port 443, which is commonly used for HTTPS traffic.

If you want to capture traffic for multiple ports or protocols, you can expand the filter:

Example for multiple ports:

-BPFfilter "tcp port 80 or tcp port 443"

This filter captures TCP traffic on both port 80 (HTTP) and port 443 (HTTPS).

Example for capturing mirror traffic over VXLAN:

-BPFfilter "udp and port 4789"

This filter captures all UDP traffic on port 4789, which is typically used for VXLAN encapsulated traffic.

Start the agent

To start the Traceable mirroring agent, enter the following command. This starts the agent as a Windows service:

PS C:\traceable-mirroring-windows-amd64.zip\traceable-mirroring-windows-amd64> Start-Traceable

Verification

To verify a successful deployment, see the Traceable Mirroring Agent under Windows Services, as shown below.

Traceable Mirroring Agent writes logs under C:\Program Files\Traceable MirroringAgent. You can check the logs for any errors.

Uninstall

To uninstall the Traceable Mirroring agent, enter the Uninstall-Agent command in your admin PowerShell.