Synthetics Network Agent

Kentik's network agent for synthetics is covered in the following topics:

• Network Agent Versions
• Network Agent Deployment
• Network Agent Command Line
• Network Agent Setup
• Network Agent Activation

Notes:
- For a high-level overview of agent types and deployment types for synthetics, see Synthetics Agents.
- For a general explanation of synthetic testing in Kentik, see Synthetics Overview.
- For information on specific modules within the Synthetics section of the Kentik portal, refer to the articles listed under Synthetics in the Contents tab of the KB.
- For assistance with any aspect of the agent setup process, please contact Customer Support.

Packages for private installation of the network agent are available for the common Linux distributions shown in the table below.

Note: For versions not listed above, please contact Customer Support.

Downloads are available from the following locations:

• PackageCloud: https://packagecloud.io/kentik/ksynth:
  - Debian-based distributions: APT package manager.
  - RPM based distributions: YUM package manager.
• Docker hub: https://hub.docker.com/r/kentik/ksynth

The release process for new ksynth network agent versions includes the following stages:

1. Distribute a release candidate (RC) build internally for testing by employees.
2. Post release versions on PackageCloud and Docker Hub (see links above) for customers who wish to update their private agents manually.
3. Roll out updates incrementally to global agents. This process may take a few days because we deploy in a few locations, wait and watch for issues, deploy to more locations, etc.
4. After global agents are updated with no reported issues, we set the new version to be the autoupdate version. At this point customer (private) agents whose --update argument is true will be updated automatically.

The following considerations apply when deploying the network agent:

• Hardware Requirements
• Local CA Certificate Override
• ksynth Directory

Note: For additional considerations that apply when deploying ksynth agents, see ksynth Deployment Considerations.

The following resources must be available (at minimum) to each instance of the ksynth network agent:

• RAM allocation: 2GB
• CPU cores: 2

ksynth will honor an OpenSSL-compliant local override for the location of a CA certificate if the alternate location is set with an environment variable (SSL_CERT_FILE or SSL_CERT_DIR) as described in OpenSSL documentation.

Starting with version 0.0.4, the binary executable file for ksynth is stored at /opt/kentik/ksynth/ksynth.

The ksynth network agent command line is covered in the following topics:

• Network Agent CLI Structure
• Network Agent CLI Config
• Network Agent CLI Arguments
• Agent Subcommand Arguments

ksynth uses a standard UNIX command line that is structured as follows:

ksynth <optional_args> agent <agent_args>

When ksynth is installed from a downloaded Linux package (see Network Agent Package Install) the installer creates and auto-starts a systemd service, during which it looks for a ksynth config file at /etc/default/ksynth:

• If the config file isn't found, ksynth is run using default values for CLI arguments.
• If the config file is found, the CLI arguments will be taken from the file.

The following snippet illustrates a ksynth config file:

root@probe-2-cmh-0:˜# cat /etc/default/ksynth
KENTIK_COMPANY=kentik_company_id
KENTIK_REGION=kentik_saas_region # us or eu
AGENT_IDENTITY=ksynth.id
AGENT_UPDATE=true # enables auto-update of ksynth (version 0.0.4 and higher)
AGENT_NAME=name_string

Note: For more information on setting the config variables as part of the install procedure, see Network Agent Package Install.

The ksynth network agent command line takes the following arguments:

• --verbose, -v (optional): Increase log output verbosity, may be specified multiple times (e.g. "-vv").
• --bind (optional): The bound source IP address for all synthetic traffic on this instance of ksynth. If not specified, ksynth will rely on the kernel to choose the appropriate source IP address.
• -4 (optional): Use only IPv4 addresses when resolving host names for synthetic test targets.
  Note: Conflicts with -6
• -6 (optional): Use only Ipv6 addresses when resolving host names for synthetic test targets.
  Note: Conflicts with -4
• agent (optional): A subcommand that must be included in order to use Agent Subcommand Arguments such as --id.

The following arguments are used with the agent subcommand.

• --id, -i (optional): The location (path) at which the binary file containing an opaque private identifier for this instance of ksynth should be installed. If not specified, ksynth will install this file to the directory /var/lib/ksynth/ksynth.id.
• --name (optional): The user-assigned name of this agent. Default is the system hostname.
• --company (optional): The Kentik-assigned company ID for your organization. If not specified during installation — either via a config file for package manager (see Network Agent CLI Config) or directly in a docker run command (see Network Agent Docker Install) — a challenge code from ksynth will be required to register the agent instance in the portal (see Register Network Agent).
• --proxy (optional): The URL of the HTTP proxy server used to communicate with Kentik. If not specified, ksynth will communicate directly with Kentik (no proxy server).
• --region (optional): The region of the Kentik SaaS cluster with which your organization is registered, either us (default) or eu (for accounts that log in on portal.kentik.eu).
• --user (optional): The user that you want ksynth processes to run as. Defaults to ksynth.
• --update (optional): Enables auto-update of ksynth (version 0.0.4 and higher).

The installation process for the ksynth network agent is covered in the following topics:

• Network Agent Setup Stages
• Network Agent Package Install
• Network Agent Docker Install

The setup of a private ksynth instance involves two main stages:

1. Installation of ksynth in your network infrastructure or public cloud instance. The steps vary depending on how you install:
   - To install via a package, see Network Agent Package Install.
   - To install via a container, see Network Agent Docker Install.
2. Activation of the ksynth instance with Kentik, which is performed in the Kentik portal (see Network Agent Activation).

Note: Before installing, refer to:
- Network Agent Deployment
- ksynth Deployment Considerations

Installation from a downloaded Linux package (see Network Agent Versions) enables you to take advantage of standard capabilities including:

• Automatic pulling of dependencies.
• Update function for easier upgrades (for additional update information see ksynth Version Rollout).
• Clean package removal via the remove/delete/uninstall functions.

Kentik-provided Linux packages perform the necessary systemd configuration to run ksynth as a service under a specific ksynth user. The package starts the service after installation and provides, via systemctl, the commands needed to start/stop/restart ksynth.service at any time.

To install Debian-based or RPM-based packages:

1. On the host where you'll run ksynth, run the following command to install the ksynth repository:
   - For Debian-based packages:
   curl -s https://packagecloud.io/install/repositories/kentik/ksynth/script.deb.sh | sudo bash
   - For RPM-based packages:
   curl -s https://packagecloud.io/install/repositories/kentik/ksynth/script.rpm.sh | sudo bash
2. Use the package manager to install the ksynth service (latest version will be installed unless an alternate version number is specified):
   - For Debian-based packages: apt-get install ksynth
   - For RPM-based packages: yum install ksynth
3. Set the following config variables in the ksynth config file (see Network Agent CLI Config) at /etc/default/ksynth:
   - KENTIK_REGION (EU customers only): If your organization uses Kentik's EU cluster, you must set the Kentik SaaS region to eu. If not specified, the region will default to us.
   - AGENT_NAME: The name by which you want the agent to appear in portal UI. If not specified, the agent name will default to the hostname.
   - KENTIK_COMPANY: Your organization's Kentik company ID. This is the “Account #” shown on the Settings » Licenses page in the portal.
   Note: If you don't set the company ID in the config file you will be required to register this ksynth instance manually (see Register Network Agent) before activation.
4. Start or restart the ksynth instance with the following commands:
   systemctl stop ksynth
   systemctl start ksynth
5. Activate the agent instance in the portal (see Network Agent Activation).

Installation of the ksynth network agent from a downloaded Docker image (see Network Agent Versions) provides a convenient and easy deployment mechanism for systems that already use Docker-based containerized applications.

To install via Docker:

1. Pull down the latest ksynth image from Kentik's Docker hub repository:
   docker pull kentik/ksynth:latest
2. Run the docker image as shown in one or the other of the following examples:
   (a) docker run --name ksynth -d -v /opt/kentik/ksynth:/var/lib/ksynth kentik/ksynth:latest --company=kentik_company_id --region=us_or_eu --name name_string --update
   ... or...
   (b) docker run -d --name ksynth -v ksynth:/var/lib/ksynth kentik/ksynth:latest --company=kentik_company_id --region=us_or_eu --name name_string --update
3. Activate the agent instance in the portal (see Network Agent Activation).

In the above docker run command (step 2):

• The Docker --name argument (as distinct from the ksynth --name argument later in the command) names the Docker container. If not included the container will be assigned an ID, which you'll have to know in order to run any future commands on the container.
• The -v argument (volume) will cause a ksynth directory to be created on the server (if it doesn't already exist) and mounted in the Docker container at /var/lib/ksynth. When ksynth runs, the ksynth.id ID file will, by default, be written to this location, where it will persist between container upgrades (otherwise every Docker image upgrade will prompt an attempt to register a new agent).
• The kentik/ksynth:latest statement will run ksynth agent, passing to it the agent subcommand arguments that follow (--company, etc.).
• To specify kentik_company_id for the --company argument, paste in your organization's Kentik company ID (the number next to “Account #”) from the portal's Licenses page (Settings » Licenses).
• If your organization uses Kentik's EU cluster, set the --region argument to eu, else set --region to us.
• The value you provide for name_string (for the --name argument in the agent subcommands) will be the name by which the agent will appear in the portal.
• The --update flag (version 0.0.4 or higher) will turn on auto-updating of the ksynth executable (see ksynth Version Rollout). Omit this flag if you do not want auto-updating.

Note: For a reference to the CLI values in the above run command, see Network Agent Command Line.

Registration and activation of an installed instance of the network agent is covered in the following topics:

• About ksynth Activation
• Activate Network Agent
• Register Network Agent

Activation of a private instance of ksynth involves securely associating the agent with your Kentik account (trial or customer), which you'll do on the Agent Management page in the Synthetics section of the portal. The specific steps depend on whether your organization's company ID has been passed during installation.

If you've passed the company ID at install, the agent will be registered automatically and you need only activate the agent directly in the portal (see Activate Network Agent). The company ID can be passed in the following ways:

• Package-based installs (Debian/RPM): The company ID is specified with the KENTIK_COMPANY variable in the ksynth config file (see Network Agent CLI Config) at /etc/default/ksynth. See step 2 in Network Agent Package Install.
• Docker-based installs: The company ID is specified with the --company argument in the CLI of your docker run command. See step 2 in Network Agent Docker Install.

Note: Providing the company ID during the installation process facilitates mass or scripted ksynth deployment.

If you haven't specified the company ID at install then the information required for registration won't be passed automatically to the Kentik portal. For each deployment you do this way you'll need to manually register the ksynth instance, at which point it will be automatically activated. To do so you get a challenge code from the agent and enter the code on the Agent Management page (see Register Network Agent).

To activate a ksynth instance that was installed with the company ID specified (see Company Specified at Install):

1. In the portal, go to the Agent Management page (Synthetics » Agent Management) and find the newly installed agent in the Private Agents tab of the Agents List. The agent's status will be indicated as Pending.
2. Click the agent to open the Agent Details drawer (right sidebar).
3. Click the Activate button in the drawer, which opens the Activate Agent dialog.
4. Review the settings in the dialog and make any needed changes, then click the Activate button. The dialog will close.
5. In the Private Agents tab of the Agents List, the agent's status will now be indicated as Active.

When the company ID was not specified during installation (see Company Not Specified at Install), you will need to manually register the ksynth instance, which will automatically activate it. Manual ksynth registration involves getting a challenge code from the agent and entering the code on the portal's Agent Management page.

1. In ksynth, run one or the other of the following commands:
   (a) systemctl status ksynth --full
   ... or...
   (b) journalctl -u ksynth
2. ksynth will return a challenge code, as shown in the following example:
   INFO ksynth::watch] auth challenge:
   2cffbb843844985f5400135dd0f8d3dc0f9e7df56b9fee0d13f88a43ec0509c2
3. In the portal, go to the Agent Management page (Synthetics » Agent Management) and click the Enter Challenge Code button.
4. In the resulting Register Agent dialog, enter the code and click the Register button. The dialog will close.
5. The agent instance corresponding to the entered code will now appear in the Private Agents tab of the Agents List, and the agent's status will be indicated as Active.

Note: To register multiple installed ksynth instances repeat the above steps with the challenge code corresponding to each instance.