Synthetics Agent

The following topics cover the deployment of Kentik's synthetics agent, ksynth, within your infrastructure to enable Synthetic Monitoring internally and to/from Kentik's global and public cloud agents:

Notes:
- For assistance with any aspect of the setup process, please contact support@kentik.com.
- For a general explanation of Synthetic Monitoring 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.

 

About the Synthetics Agent

Kentik’s synthetic testing capabilities enable continuous network performance testing from and to network locations, both within your infrastructure and elsewhere around the Internet, running "ksynth," Kentik’s software agent for synthetic monitoring. The ksynth agent is used for the following types of deployments:

  • Global Agents: Available to every customer that has activated our synthetic monitoring services, Global agents refers to all agents in the Kentik Global Agent Network, a worldwide network of Kentik-maintained ksynth agents (hosted in data centers and public clouds) that enables performance testing to and from key Internet hubs worldwide. Global agents include Kentik-maintained agents in the following sub-categories:
    - Public Cloud agents: In some portal contexts, the subset of global agents that is deployed in the infrastructure of key cloud service providers (AWS, GCP, Azure, IBM, etc.) is referred to separately as "Public Cloud" agents.
    - App agents: App agents have the ability to run an instance of Headless Chromium, which allows Google Chromium to run in a headless/server environment. App agents are capable of performing advanced web-layer tests including full browser page load.
  • Private Agents: Every Kentik customer can deploy as many instances of ksynth as they care to in their own on-prem and/or cloud infrastructure (no additional license required). These private agents are for the exclusive use of the customer who deploys them (not available to other Kentik customers). Once a private agent has been installed (see ksynth Setup) and activated in Kentik (see ksynth Portal Activation) the agent will be available for use by any Synthetics test scenario (see Test Control Center).
 

ksynth Versions

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

Debian Ubuntu RedHat Enterprise Linux CentOS
Buster (10.0)
Stretch (9.0)
Jessie (8.0)
Bionic Beaver (18.04 LTS)
Focal Fossa (20.04 LTS)
8.0
7.0
8

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

Downloads are available from the following locations:

 

ksynth Deployment Considerations

The following considerations apply when deploying ksynth:

 
top  |  section

Hardware Requirements

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

  • RAM allocation: 2GB
  • CPU cores: 2
 
top  |  section

ksynth Protocols

The ksynth agent uses the following protocols:

  • For communication between ksynth and Kentik's SaaS platform (US or EU): TCP 443 (HTTPS).
  • For network tests (IPv4 and/or IPv6):
    - Ping: ICMP or TCP (with option to specify target port)
    - Traceroute: UDP or TCP (with option to specific target port)
    - ICMP Echo ping.
  • For HTTP(s) or API Tests:
    - HTTP GET/ POST/ PUT/ PATCH sent to TCP port 80/443

Note: Future support is planned for UDP in ping and ICMP in traceroute.

 
top  |  section

Whitelisting ksynth

When running one or more ksynth instances on your network, the following IP address ranges should be whitelisted in your firewall rules to ensure that the agents can communicate with Kentik:

  • 208.76.14.0/24
  • 2620:129::/44
 
top  |  section

NTP Configuration

The server on which ksynth is installed must be configured as an NTP client to avoid known issues related to clock skew. If the NTP service is correctly configured, the following command should return successfully:

sudo ntpq -p


 
top  |  section

ksynth Security

The ksynth agent generates a unique identity and uses this to authenticate with the Kentik platform. The identity is stored in a local file to be used across restarts and upgrades.

 
top  |  section

ksynth Directory

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

 

ksynth Command Line

The ksynth command line is covered in the following topics:

 
top  |  section

ksynth CLI Structure

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

ksynth <optional_args> agent <agent_args>


 
top  |  section

ksynth CLI Config

When ksynth is installed from a downloaded Linux package (see ksynth Package Installation) the installer creates and auto-starts a systemd service, during which it looks for a ksynth config file at /etc/defaults/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


 
top  |  section

ksynth CLI Arguments

The ksynth 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.
 
top  |  section

Agent Subcommand Arguments

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 ksynth CLI Config) or directly in a docker run command (see ksynth Docker Installation) — a challenge code from ksynth will be required to register the agent instance in the portal (see ksynth Registration).
  • --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).
 

ksynth Setup

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

Note: Refer to ksynth Deployment Considerations before installing.

 
top  |  section

ksynth Setup Stages

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

  1. Installation of ksynth on a server in your infrastructure, which is performed on that server. The steps vary depending on how you install:
    - To install via a package, see ksynth Package Installation.
    - To install via a container, see ksynth Docker Installation.
  2. Activation of the ksynth instance with Kentik, which is performed in the Kentik portal (see ksynth Portal Activation).
 
top  |  section

ksynth Package Installation

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

  • Automatic pulling of dependencies.
  • Update function for easier upgrades.
  • 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.

Note: When installing via package manager, if you wish to specify non-default values for any ksynth CLI arguments you must do so via a ksynth config file (see ksynth CLI Config).

Installing Debian Packages

To install Debian-based packages:

  1. On the host where you'll run ksynth, run the following command to install the ksynth repository:
    curl -s https://packagecloud.io/install/repositories/kentik/ksynth/script.deb.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).
    # install latest version
    sudo apt install ksynth
  3. Activate the agent instance in the portal (see ksynth Portal Activation).

Installing RPM Packages

To install RPM-based packages:

  1. On the host where you'll run ksynth, run the following command to install the ksynth repository:
    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).
    # install latest version
    sudo yum install ksynth
  3. Activate the agent instance in the portal (see ksynth Portal Activation).
 
top  |  section

ksynth Docker Installation

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

To install ksynth 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 this example:
    docker run -d --name ksynth -v ksynth:/var/lib/ksynth kentik/ksynth:latest --company=kentik_company_id --region=kentik_saas_region --name name_string --update
  3. Activate the agent instance in the portal (see ksynth Portal 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.).
  • The --update flag will turn on auto-updating of the ksynth executable (version 0.0.4 or higher). Omit this flag if you do not want auto-updating.

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

 

ksynth Portal Activation

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

 
top  |  section

About ksynth Activation

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 you use the ksynth CLI to specify the --company argument (see Agent Subcommand Arguments) during installation:

  • Default install: If you run a default package manager installation (no config file; see ksynth CLI Config) or you don’t specify the --company argument in the CLI of your docker run command, your company ID won't be passed automatically to the Kentik portal. For each deployment you do this way you'll need to 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 ksynth Registration).
  • Company specified at install: If you specify the --company argument using a config file (package manager installation) or via the CLI in a docker run command, it will be registered automatically. In the portal you won't need to enter a challenge code; instead you'll activate the agent directly (see ksynth Activation).

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

 
top  |  section

ksynth Registration

When --company was not specified during installation, you will need to register the ksynth instance, which will automatically activate it:

  1. If the ksynth instance is not already running, start it with the following command:
    sudo systemctl start ksynth
  2. Run the following command in ksynth to get the challenge code:
    systemctl status ksynth
  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.

 
top  |  section

ksynth Activation

To activate a ksynth instance that was installed with the --company argument specified:

  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.
© 2014- Kentik

In this article: