- 29 Aug 2024
- 3 Minutes to read
- Print
- PDF
Windows
- Updated on 29 Aug 2024
- 3 Minutes to read
- Print
- PDF
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:
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.Note the transport name property, which should be something like -
"\Device\Tcpip_{D7F2A7DC-EA23-44EF-8EBE-84GAD862A9D8}"
Replace the word
Tcpip
withNPF
in the above string.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:
Enter the following command to import the module:
Import-Module .\traceable-install-module.psm1
Run the
Install-Deps
function.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.