- 22 Nov 2024
- 5 Minutes to read
- Print
- DarkLight
- PDF
Installation using script
- Updated on 22 Nov 2024
- 5 Minutes to read
- Print
- DarkLight
- PDF
The Platform agent is an agent that receives various information from different tracing agents. The Platform agent is deployed between a tracing agent and the Traceable Platform and works to collect data. It also works to classify data along with redacting the data. The Platform agent makes sure that no sensitive information reaches the Traceable Platform. The Platform agent receives the blocking rule information from the Traceable Platform and sends it to the instrumentation agent.
Before you begin
You would require an Agent token to proceed with Platform agent installation. Complete the following steps to generate a unique Agent token:
Log in to your Traceable account.
Navigate to Settings () → Account → Agent Tokens.
Click on Generate Token.
Make sure to copy and save the generated token, as you cannot reaccess it. You can only edit or delete the name of the token. This token is used in the steps detailed below. If this token is deleted from Traceable Platform (UI), the communication between Traceable Platform agent and Traceable Platform (UI) will break. In such a case, generate and update a new token in the Platform agent.
Download
To download the script, navigate to Traceable's download site. Navigate to install → traffic-mirroring → linux → latest. Click on the install.sh
script to download it, or enter the following command in your terminal:
curl -O https://downloads.traceable.ai/install/traffic-mirroring/linux/latest/install.sh
Provide the execute permission to the script. Enter the following command:
chmod +x install.sh
Installation tpa-only
The tpa-only
sub-command installs the Traceable Platform agent and runs it as a systemctl
service. For more details of this command (synopsis, example usages, argument descriptions), enter the following:
./install.sh tpa-only help
The command has the following syntax:
./install.sh tpa-only -e ENVIRONMENT [-s SERVICE_NAME] [-r REMOTE_ENDPOINT]
[--loglevel LOGLEVEL] [--remote-cert-path ROOT_CA_CERT] [-t]
[--log-max-size-mb SIZE] [--log-max-backups COUNT] [--no-download]
[--tls-endpoint ENDPOINT --tls-key KEY --tls-cert CERT --tls-root-cert ROOT_CA_CERT]
[--max-memory MAX_MEMORY] [--set-memory-accounting]
[--otlp-max-connection-age OTLP_MAX_CONNECTION_AGE]
[--http-proxy HTTP_PROXY] [--https-proxy HTTPS_PROXY] [--no-proxy NO_PROXY]
[--max-cpu MAX_CPU]
The following table explains the usage of the command arguments:
Argument | Mandatory | Description |
---|---|---|
| Yes | Environment name for the mirrored traffic. |
| No | The service name for the mirrored traffic. |
| No | Remote endpoint for Traceable Platform agent. |
| No | Logging level for the Traceable service. The allowed values are |
| No | Root CA used to sign certificate for the Traceable Platform. |
| No | Prompt for Traceable token for authentication. Check token for more details. |
| No | Maximum log file size in MB created by the Traceable service. The default value is 10 MB. |
| No | Maximum number of backup log files created by the eBPF service. The default value is 10. |
| No | Use local packages to install Traceable and its components. For more information, see Airgapped installation. |
| No | Maximum memory limit for the Traceable service. Takes a memory size in bytes. If the value is suffixed with K, M, G, or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system. |
| No | set MemoryAccounting to true for the Traceable service. This is required on VMs where the DefaultMemoryAccounting property is not enabled. |
| No | Sets the keepalive duration for the OTLP server in the Traceable Platform agent. The duration can be expressed as a string. The acceptable units are ns, us, s, m, and h. Example: 100ms = 100 milliseconds, 120s = 120 seconds, |
| No | Used for setting proxy URL for HTTP requests until overwritten by |
| No | Used for setting proxy URL for HTTPS requests until overwritten by |
| No | Specifies a string that contains comma-separated values specifying hosts that should be excluded from proxying. |
--max-cpu MAX_CPU | no | Sets the maximum percentage of CPU that the TPA (Traceable Platform Agent) process is allowed to use. This option limits CPU utilization, preventing the process from consuming more than the specified percentage. For example, |
Traceable Platform agent with TLS
You can choose to enable the TLS server on the Traceable Platform agent. The following arguments enable TLS:
Argument | Mandatory | Description |
---|---|---|
| Yes | TLS Endpoint of Traceable Platform agent. |
| Yes | Path to the private key for Traceable Platform agent. |
| Yes | Path to the certificate file for Traceable Platform agent. |
| Yes | Path to the root CA file for Traceable Platform agent. |
Password-protected private key
These steps are applicable only if your private key is password-protected. A password-protected private key is encrypted and requires a passphrase to unlock. This encryption ensures additional security by preventing unauthorized use of the private key unless the passphrase is known. To verify if a private key is password-protected, check if the file contains the following line:
-----BEGIN ENCRYPTED PRIVATE KEY-----
Enter the following command to find if the file contains the above line:
cat server.key | head -n1
If the private key is password-protected use the openssl
command to create a new private key without a passphrase:
openssl rsa -in private.key -out private_no_passphrase.key
This command decrypts the existing private key and generates a new one that TPA can use without requiring a password. Replace the password-protected key with the new, unencrypted key in the TLS configuration.
tpa-only examples
Following are a few examples of using the tpa-only
sub-command:
If you wish to install Traceable Platform Agent without a TLS server, enter the following command:
ActionScriptActionScript
sudo ./install.sh tpa-only -e myEnvironment -t
If you wish to set up a TLS server with an endpoint as
0.0.0.0:5443
, enter the following command:ActionScriptActionScript
sudo ./install.sh tpa-only -e myEnvironment -t --tls-endpoint 0.0.0.0:5443 --tls-key /path/to/key --tls-cert /path/to/cert --tls-root-cert /path/to/root/ca
Verify installation
Enter the following command to verify a successful installation of the Traceable agent:
systemctl is-active traceable
Ensure no ERROR
logs are present, and a Started metric exporter
message appears in the logs
cat /var/traceable/log/traceable.YYYY_mm_dd_ss_mil.log
Uninstallation
Enter the following command to uninstall. Note that the install script is used for both installation and uninstallation.
sudo ./install.sh cleanup
Airgapped installation
Traceable provides a script for setting up traffic mirroring in an air-gapped environment. An air-gapped system is a computer or network physically isolated from the internet and other unsecured networks. This system protects sensitive data and systems from external threats such as hackers and malware. Airgapped systems are often used in industries where data security is paramount.
Traceable provides two archives for air-gapped installation, one for AMD64 machines and the other for arm64 devices. To download the archive, go to Traceable's download site. Navigate to install → traffic-mirroring → linux → latest.
Transfer the downloaded archive to your airgapped system. Untar the archive by entering the following command, for example, for an amd64 machine:
tar xvzf traffic-mirroring-amd64.tar.gz
Change directory:
cd traffic-mirroring-amd64/bin/
The bin directory contains install.sh
.
To install, run any sub-command mentioned in the Installation section by adding the --no-download
option. This option uses the local packages from the tar file to complete the installation instead of depending on the network.
Token
When installing the Traceable Platform Agent, you must provide the platform token to authenticate with the platform. This can be done in multiple ways.
Export the token as an environment variable:
ActionScriptActionScript
export TA_REFRESH_TOKEN=""
Put the token in the default token file:
ActionScriptActionScript
echo "" | sudo tee /etc/traceable/agent/token
Provide the command-line flag
-t
or--token
and enter the token when prompted.