Synthetics App Agent

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

• App Agent Versions
• Hardware Requirements
• App Agent Command Line
• About App Agent Setup
• App Agent Package Install
• App Agent Docker Install
• Register and Activate ksynth

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 ksynth app agent (ksynth-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-agent:
  - Debian-based distributions: APT package manager.
  - RPM based distributions: YUM package manager.
• Docker hub: https://hub.docker.com/r/kentik/ksynth-agent

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

• RAM allocation: 2GB
• CPU cores: 2

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

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

• App Agent CLI Structure
• App Agent CLI Arguments

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

ksynth-agent [options]

The ksynth app agent command line takes the following arguments:

-b, --browser-max <pool:value...>: Max instances for pools, multiples allowed`-b main:2 -b notls:5`
--browser-path <value>: Absolute path to Chromium browser binary (env: KA_BROWSER_PATH)
--basic-trace: Use basic trace (no paris methods)
-c, --company-id <value>: Init with company id
-d, --disable <value...>: Disable task type (choices: "browser", "scamper")
-e, --elu: Monitor event loop utilization (this has cpu/memory impacts)
--external-repo-url <value>: Override default external repo url
-f, --fuzz-window-ms <value>: Time (ms) to spread start of tasks over (default 60000)
-g, --global: Init as Global agent
--install-scamper: Install scamper from ksynth-agent pre-build binary NOTE: requires elevated permissions
-j, --show-json-export: Show JSON export data
-l, --log-levels <category:level...>: Change logging, multiples allowed `-l info -l httpRequest:debug`
-m, --browser-instance-test-max <value>: Max tests any browser instance will run before being destroyed/respawned
-n, --name <name>: Agent name (default host name)
-p, --pid-path <value>: Path to use for pidfile (default current working directory) (env: KA_PID_PATH)
-r, --region <region>: Region (default: "us")
-s, --scampers-per-worker <value>: size of scamper instance pool
--scamper-archive <value>: Only used with --install-scamper flag, omit this to use default
--scamper-path <value>: Provide absolute path to installed scamper binary
-t, --use-threads: Use worker threads rather than forks (default forks)
-u, --show-udr-export: Show UDR export data
-v, --version: output the version number
-w, --worker-count <value>: Number of worker threads to use (default 1)
-z, --max-concurrent-browser-tests <value>: Max concurrent browser tests
-h, --help: display help for command

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

• App Agent Setup Stages
• Default vs. Scripted Install

The setup of a private ksynth app agent instance (ksynth-agent) involves two main stages:

1. Installation of the agent in your network infrastructure or public cloud instance. The steps vary depending on how you install:
   - To install via a package, see App Agent Package Install.
   - To install via a container, see App Agent Docker Install.
2. Registration and activation of the ksynth instance on the Agent Management page of the Kentik portal (see Activate App Agent). These steps vary depending on whether the installation performed in step 1 above used the default method or scripted method (see Default vs. Scripted Install).

Note: Before installing, refer to:
- Hardware Requirements
- ksynth Deployment Considerations

Kentik uses your organization's company ID to identify the company to which a given instance of the ksynth agent is assigned. Whether the agent is installed via package or container (Docker), there are two methods of providing the correct ID to Kentik:

• Default install: Retrieve a challenge code during the installation procedure, then enter the code during the registration process on the Kentik portal's Agent Management page, which will include activation of the agent (see Register App Agent).
• Scripted install: On the Kentik portal's Licenses Page, copy the value next to Account#. During the installation process you'll pass this value to the installer with a command-line parameter. The agent will be automatically registered during installation, but you will have to activate it manually on the Kentik portal's Agent Management page (see Activate App Agent).

Note: Details of the above methods are outlined in the topics below.

The two installation methods (see Default vs. Scripted Install) for a Debian-based or RPM-based ksynth package are covered in the following topics:

• Default Package Install
• Scripted Package Install
• Linux Installation Troubleshooting

Notes:
- Kentik recommends the default install unless you are installing via script.
- In case of errors, see Linux Installation Troubleshooting.

To install via package using the default method:

1. On the host where you'll run ksynth, run the following command to install the ksynth-agent repository:
   - For Debian-based packages:
   curl -s https://packagecloud.io/install/repositories/kentik/ksynth-agent/script.deb.sh | sudo bash
   - For RPM-based packages:
   curl -s https://packagecloud.io/install/repositories/kentik/ksynth-agent/script.rpm.sh | sudo bash
2. Use the package manager to install the ksynth-agent service:
   - For Debian-based packages:
   apt-get install ksynth-agent
   - For RPM-based packages:
   yum install ksynth-agent
   Note: Depending on the Linux distro/version, the agent may notify you of additional libraries that you'll need to install.
3. Optional: The ksynth agent is now configured to run in Network Agent mode (no "web tests" as described in Synthetics Test Types). To install with both Network Agent and web test functionality, see Add Web Test Functionality. Otherwise skip this step.
4. If your Kentik account is on our EU cluster, before starting the agent you must edit the KENTIK_REGION environment variable in the file at /etc/default/ksynth-agent, replacing US with EU (if you already started the agent restart it after this step).
5. Start the ksynth-agent service:
   systemctl start ksynth-agent
6. Retrieve the challenge code you'll need to register the new agent in the portal (see Register App Agent):
   systemctl status ksynth-agent
7. The agent will be listed on the Private Agents tab of the portal's Agent Management page.

This installation method, primarily used for mass or scripted deployments, involves retrieval of your organization's ID from the Kentik portal and activation in the portal after installation.

To install via package with company ID:

1. In the Kentik portal, copy your Kentik company ID, which is the value next to Account# on the Licenses page.
2. On the host where you'll run ksynth, run the following command to install the ksynth-agent repository:
   - For Debian-based packages:
   curl -s https://packagecloud.io/install/repositories/kentik/ksynth-agent/script.deb.sh | sudo bash
   - For RPM-based packages:
   curl -s https://packagecloud.io/install/repositories/kentik/ksynth-agent/script.rpm.sh | sudo bash
3. Use the package manager to install the ksynth-agent service:
   - For Debian-based packages:
   apt-get install ksynth-agent
   - For RPM-based packages:
   yum install ksynth-agent
   Note: Depending on the Linux distro/version, the agent may notify you of additional libraries that you'll need to install.
4. Optional: The ksynth agent is now configured to run in Network Agent mode (no "web tests" as described in Synthetics Test Types). To enable the agent to also perform web tests (HTTPS, Page Load, etc.), see Add Web Test Functionality. Otherwise skip this step.
5. Paste the company ID (from step 1 above) after KENTIK_COMPANY= in the file /etc/default/ksynth-agent.
6. Start the ksynth-agent service:
   systemctl start ksynth-agent
7. Activate the agent instance in the portal (see Activate App Agent).
8. The agent will be listed on the Private Agents tab of the portal's Agent Management page.

To enable web test functionality when installing a ksynth agent, include the following procedure as step 4 of the process outlined above:

1. Open the service configuration file in your editor of choice (nano is used in the following example):
   nano /etc/default/ksynth-agent
2. Remove or comment-out the following line and save the file: K_AGENT_DISABLE=browser
3. Navigate to the scripts folder in the agent's working directory:
   cd /var/lib/ksynth-agent/scripts
4. Run the appropriate configuration script and ensure successful completion:
   - For Debian-based packages:
   ./install-browser-deps_debian
   - For RPM-based packages:
   ./install-browser-deps_centos

During package installation, if you receive an error message about missing dependencies, run the commands below to install the commonly required dependencies.

• Debian-based packages:
  sudo apt-get install ca-certificates fonts-liberation libappindicator3-1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release wget xdg-utils
• RPM-based packages:
  sudo yum install alsa-lib.x86_64 atk.x86_64 cups-libs.x86_64 gtk3.x86_64 ipa-gothic-fonts libXcomposite.x86_64 libXcursor.x86_64 libXdamage.x86_64 libXext.x86_64 libXi.x86_64 libXrandr.x86_64 libXScrnSaver.x86_64 libXtst.x86_64 pango.x86_64 xorg-x11-fonts-100dpi xorg-x11-fonts-75dpi xorg-x11-fonts-cyrillic xorg-x11-fonts-misc xorg-x11-fonts-Type1 xorg-x11-utils
• RHEL8 RPM-based packages:
  sudo yum install -y alsa-lib.x86_64 atk.x86_64 cups-libs.x86_64 gtk3.x86_64 libdrm.x86_64 mesa-libgbm.x86_64 libXcomposite.x86_64 libXcursor.x86_64 libXdamage.x86_64 libXext.x86_64 libXi.x86_64 libXrandr.x86_64 libXScrnSaver.x86_64 libXtst.x86_64 pango.x86_64 xorg-x11-fonts-100dpi xorg-x11-fonts-75dpi xorg-x11-fonts-cyrillic xorg-x11-fonts-misc xorg-x11-fonts-Type1 xorg-x11-utils

After installing dependencies, update the nss library using this command:
yum update nss -y

Notes:
- The dependencies referenced above are subject to change. For the latest information, check the lists at Chrome headless doesn't launch on UNIX.
- If you continue to experience installation errors after trying the above, please contact Customer Support.

Installation of the ksynth app agent from a downloaded Docker image (see App Agent Versions) provides a convenient and easy deployment mechanism for systems that already use Docker-based containerized applications. The two ksynth installation methods (see Default vs. Scripted Install) for Docker are covered in the following topics:

• Default Docker Install
• Scripted Docker Install

Note: Kentik recommends the default install unless you are installing via script.

To install via Docker using the default method:

1. Create a local directory to mount into the docker container. This is needed so agent identity can persist between docker runs.
2. Pull and run the latest ksynth-agent docker image:
   docker run -it --rm -v /path/to/local/directory:/var/lib/ksynth-agent kentik/ksynth-agent:latest ksynth-agent -u
3. Activate and register the agent in the portal using the challenge code provided (see Register App Agent):
   docker logs ksynth-agent
4. The agent will be listed on the Private Agents tab of the portal's Agent Management page.

This installation method, primarily used for mass or scripted deployments, involves retrieval of your organization's ID from the Kentik portal and activation in the portal after installation.

To install via Docker with company ID:

1. In the Kentik portal, copy your Kentik company ID, which is the value next to Account# on the Licenses page.
2. Create a local directory to mount into the docker container. This is needed so agent identity can persist between docker runs.
3. Pull and run the latest ksynth-agent docker image while passing in the company ID:
   docker run -it --rm -v /path/to/local/directory:/var/lib/ksynth-agent kentik/ksynth-agent:latest ksynth-agent -u -c kentik_company_id
4. Activate the agent in the portal (see Activate App Agent).
5. The agent will be listed on the Private Agents tab of the portal's Agent Management page.

In the above docker run command (step 3):

• The Docker run -it argument is a combination of two separate flags. -i stands for interactive and allows you to interact with the container's command line. -t stands for terminal which tells Docker to allocate a pseudo terminal for the container.
• The -rm argument (remove) tells Docker to automatically remove the container and its file system when the container exits.
• 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-agent:latest statement will run ksynth-agent, passing to it the agent subcommand arguments that follow (--company-id, etc.).
• The App Agent -u argument shows UDR export data.
• The value of the --company-id argument is your organization's Kentik company ID, which is the number next to Account # on the portal's Licenses page.
• If your organization uses Kentik's EU cluster, set the optional -r argument to eu. If not specified the agent will default to the US region.

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

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

• Registration and Activation
• Register App Agent
• Activate App Agent

Registering a private instance of ksynth involves securely associating the agent with your Kentik account, which you'll do on the Agent Management page in the Synthetics section of the portal. As noted in Default vs. Scripted Install, package and Docker install procedures each support two installation methods, default and scripted, which in turn determine how ksynth is registered and activated on this page:

• Default installs:
  - The agent must be manually registered in the portal.
  - The agent is automatically activated as part of the registration process.
• Scripted installs:
  - The agent is automatically registered during installation.
  - The agent must be manually activated in the portal.

If you installed ksynth via package or Docker using the default method (see Default vs. Scripted Install), complete the following steps to register and activate the app agent:

1. In ksynth, run one or the other of the following commands:
   - For Debian/RPM installations:
   systemctl status ksynth-agent -f or journalctl -u ksynth-agent
   - For Docker package installations: docker logs ksynth-agent
2. ksynth will return a challenge code, as shown in the following example:
   [INFO] authenticate - Activation challenge code: f4dd8632fbdb09714a38c17a7b536a4fe84d973beb4172d01abbba1c77exxxxx
3. In the portal, go to the Agent Management page (Synthetics » Agent Management) and click the Enter your Agent challenge code button.
4. In the resulting Register Agent dialog, enter the code and click the Register button. The dialog will close and the Activate Agent dialog will open.
5. Review the settings in the dialog and make any needed changes, then click the Activate button.
6. The agent instance corresponding to the entered code will now appear in the Private Agents tab of the Agents List. 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.

If you installed ksynth via package or Docker using the scripted method (see Default vs. Scripted Install), complete the following steps to activate the installed agent:

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.