Installation using script
  • 22 Nov 2024
  • 5 Minutes to read
  • Dark
    Light
  • PDF

Installation using script

  • Dark
    Light
  • PDF

Article summary

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: 

  1. Log in to your Traceable account.

  2. Navigate to Settings (image-1638268402925) → Account Agent Tokens.

  3. 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

-e ENVIRONMENT

Yes

Environment name for the mirrored traffic.

-s SERVICE_NAME

No

The service name for the mirrored traffic.

-r REMOTE_ENDPOINT

No

Remote endpoint for Traceable Platform agent.

--loglevel LOGLEVEL

No

Logging level for the Traceable service. The allowed values are info, warn, error, and debug. The default value is info.

--remote-cert-path ROOT_CA_CERT

No

Root CA used to sign certificate for the Traceable Platform.

-t | --token

No

Prompt for Traceable token for authentication. Check token for more details.

--log-max-size-mb SIZE

No

Maximum log file size in MB created by the Traceable service. The default value is 10 MB.

--log-max-backups COUNT

No

Maximum number of backup log files created by the eBPF service. The default value is 10.

--no-download

No

Use local packages to install Traceable and its components. For more information, see Airgapped installation.

--max-memory MAX_MEMORY

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.

--set-memory-accounting

No

set MemoryAccounting to true for the Traceable service. This is required on VMs where the DefaultMemoryAccounting property is not enabled.

--otlp-max-connection-age

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,
120m = 120 minutes, 2h = 2 hours. The default value is infinity.

--http-proxy

No

Used for setting proxy URL for HTTP requests until overwritten by --no-proxy.

--https-proxy

No

Used for setting proxy URL for HTTPS requests until overwritten by --no-proxy.

--no-proxy

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, --max-cpu 100% allows the process to use up to one full CPU core. If you set it as 200% then two cores would be used.

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

--tls-endpoint ENDPOINT

Yes

TLS Endpoint of Traceable Platform agent.

--tls-key KEY

Yes

Path to the private key for Traceable Platform agent.

--tls-cert CERT

Yes

Path to the certificate file for Traceable Platform agent.

--tls-root-cert ROOT_CA_CERT

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.


Was this article helpful?