Kentik's network agent for synthetics is covered in the following topics.
Notes:
As of December 2022, the Synthetics Network Agent is deprecated in favor of the Synthetics App Agent.
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.
For assistance with any aspect of the agent setup process, contact Kentik (see Customer Care).
Network Agent Versions
Packages for private installation of the network agent are available for the common Linux distributions shown in the table below.
Debian | Ubuntu | RedHat Enterprise Linux | CentOS |
---|---|---|---|
Buster (10.0) | Bionic Beaver (18.04 LTS) | 8.0 | 8 |
Note: For versions not listed above, contact Kentik (see Customer Care).
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
ksynth
Version Rollout
The release process for new ksynth
network agent versions includes the following stages:
Distribute a release candidate (RC) build internally for testing by employees.
Post release versions on PackageCloud and Docker Hub (see links above) for customers who wish to update their private agents manually.
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.
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.
Network Agent Deployment
The following considerations apply when deploying the network agent.
Note: For additional considerations that apply when deploying
ksynth
agents, see ksynth Deployment Considerations.
Hardware Requirements
The following resources must be available (at minimum) to each instance of the ksynth
network agent:
RAM allocation: 2GB
CPU cores: 2
Local CA Certificate Override
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.
ksynth
Directory
Starting with version 0.0.4, the binary executable file for ksynth is stored at /opt/kentik/ksynth/ksynth
.
Network Agent Command Line
The ksynth
network agent command line is covered in the following topics.
Network Agent CLI Structure
ksynth
uses a standard UNIX command line that is structured as follows:
ksynth <optional_args> agent <agent_args>
Network Agent CLI Config
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.
Network Agent CLI Arguments
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
.
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 ofksynth
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 adocker run
command (see Network Agent Docker Install) — a challenge code fromksynth
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 wantksynth
processes to run as. Defaults to ksynth.--update
(optional): Enables auto-update ofksynth
(version 0.0.4 and higher).
Network Agent Setup
The installation process for the ksynth
network agent is covered in the following topics.
Note: If the
ksynth
network agent has previously been installed to the same machine you must delete the existingagent.id
file before reinstalling.
Network Agent Setup Stages
The setup of a private ksynth
instance involves two main stages:
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.
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 Package Install
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:
On the host where you'll run
ksynth
, run the following command to install theksynth
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
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
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 toeu
. If not specified, the region will default tous
.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.
Start or restart the
ksynth
instance with the following commands:systemctl stop ksynth
systemctl start ksynthActivate the agent instance in the portal (see Network Agent Activation).
Network Agent Docker Install
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:
Pull down the latest
ksynth
image from Kentik's Docker hub repository:
docker pull kentik/ksynth:latest
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
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 aksynth
directory to be created on the server (if it doesn't already exist) and mounted in the Docker container at/var/lib/ksynth
. Whenksynth
runs, theksynth.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 runksynth 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 toeu
, else set--region
tous
.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 theksynth
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.
Network Agent Activation
Registration and activation of an installed instance of the network agent is covered in the following topics.
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 your organization's company ID has been passed during installation.
Company Specified at Install
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 theksynth
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 yourdocker 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.
Company Not Specified at Install
If you haven't specified the company ID at install, 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).
Activate Network Agent
To activate a ksynth
instance that was installed with the company ID specified (see Company Specified at Install):
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.
Click the agent to open the Agent Details drawer (right sidebar).
Click the Activate button in the drawer, which opens the Activate Agent dialog.
Review the settings in the dialog and make any needed changes, then click the Activate button. The dialog will close.
In the Private Agents tab of the Agents List, the agent's status will now be indicated as Active.
Register Network Agent
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.
In
ksynth
, run one or the other of the following commands:
(a)systemctl status ksynth --full
... or...
(b)journalctl -u ksynth
ksynth
will return a challenge code, as shown in the following example:INFO ksynth::watch] auth challenge:
2cffbb843844985f5400135dd0f8d3dc0f9e7df56b9fee0d13f88a43ec0509c2In the portal, go to the Agent Management page (Synthetics » Agent Management) and click the Enter Challenge Code button.
In the resulting Register Agent dialog, enter the code and click the Register button. The dialog will close.
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.
© 2014-25 Kentik