Skip to content

How to set up an Enterprise Station

Technical requirements

Hardware specifications

The “Enterprise Station” is a container-based software that allows you to perform different types of synthetic tests. At this stage of development, we provide the “Net-Tracer” as the first possible test (based on advanced Trace Route).

The Kadiska Enterprise Station can run on any type of hardware and software platforms that comply with the following minimum specifications:

  • 2GB of RAM
  • 1GB of hard disk space (no need for high-speed SSD disk)
  • Docker container engine support
  • Docker compose software version 1.21.0 or higher installed

Network flows

During the setup phase, the machine on which the station is running must be able to connect to the internet on port TCP 443 (HTTPS) to download Kadiska’s Docker image from a DockerHub repository. A standard HTTP connection will also be required for the OS updates. Once the station is installed, it has to communicate with our platform to authenticate and register. To perform this, an HTTPS connection (port TCP 443) is required to the destination https://app.kadiska.com.

Screenshot

During the monitoring operations, the required network flows depend on the configured method (see here for more details). The following picture and associated table provide the details of these flows.

Screenshot

Method Egress flows Ingress flows
ICMP ICMP Echo Request ICMP Echo Reply
UDP UDP (ports 33.435 - 33.535) ICMP Destination Unreachable (port unreachable)
TCP TCP (ports 33.435 - 33.535) ICMP Destination Unreachable (port unreachable)

In case you need Kadiska to provide technical support, ingress SSH (TCP port 22) is required. This implies the Enterprise Station to have a public IP address or to use port mapping to make it reachable. This access can be activated on-demand, only when support is required.

If you use FQDN (Fully Qualified Domain Name) as Net-Tracer target, the Kadiska Enterprise Station should also have a DNS server present in its TCP/IP stack configuration.

Step 1: Enterprise Station creation

Once you have access to the Kadiska platform, login and click on the “Configuration” icon: Screenshot

By default, you're directed to the "Watchers" configuration page. Click on "Stations" to go the Kadiska Stations configuration page. Screenshot

On your screen, you may already see a list of managed Stations that we publicly provide access to. Screenshot

You can deploy your own Station(s) by first clicking on the button "Create".

Screenshot

The fields "Name", "Country" and "City" are mandatory.
The "Provider" and "Allowed IP Addresses" fields are optional.
When you leave the "Allowed IP Addresses" empty, it will automatically match your Enterprise Station public IP address discovered during the registration step (see below).

"Gap Limit" is an optional field that can be used to finetune the Kadiska Tracer behavior.
It corresponds to the maximum number of consecutive hops that cannot be identified (no response to Tracer tests) before aborting the Tracer test. It prevents a Tracer to indefinitely try to reach a target that will never respond. The default value is 8. In case you are dealing with really complex network architectures, this value may need to be increased. The maximum value is 16.
If the Tracer does not discover any node and does not reach the target, no data will be reported in the Kadiska platform.

Sharing preferences are selected from the "Sharing" dropdown menu:

Sharing option Description
public Your Station will be visible by all other Kadiska customers
organization Your Station will only be visible to your own organization (multiple tenants)
private Your Station will only be visible to you (active tenant)

Click on "Create" to confirm your settings. The Station is now created but is not activated yet. Screenshot

If you go to the list of available Stations (button "Back"), you can see the newly created Station and its status ("unconfigured"). Screenshot

To come back in the Station configuration menu, just click on its name from the list. For obvious security reasons, each Station has to authenticate to the Kadiska platform. This is done through an API Key. Click on the "Generate a key" button. Screenshot

You’ll use this API key later, when deploying the docker container.

Step 2: Enterprise Station deployment

Automated installation

The easiest way to deploy a Kadiska Enterprise Station is by using an installation script.
In this case, you only have to provision a machine running a Linux operating system complying with the minimal technical requirements mentioned above.

The following operating systems are supported:

Operating System Supported releases
Debian/Raspbian Release 10 and higher
Ubuntu Release 18.04 and higher (LTS only)
RHEL/Centos/Rocky Release 7 and higher
openSUSE Leap Release 15.3 and higher

Once this is done, you just have to issue the following command to launch the installation script:

  • For Debian/Raspbian and Ubuntu:
bash <(wget -qO- https://docs.kadiska.com/downloads/station_install.sh)
  • For RHEL/Centos/Rocky/openSUSE:
bash <(curl -sLo- https://docs.kadiska.com/downloads/station_install.sh)

During the installation process, you'll be prompted to provide the Enterprise Station API Key you have created during the step 1 of the deployment.
Optionally, you can provide the parameters to connect the Station through a proxy (login/pwd or certificate). See next section for more details.

Manual installation

Before manually deploying the Station container, make sure the host on which you’ll deploy it contains a Docker engine. Then install docker-compose in version 1.21.0 or higher.

Once this is done, create the following docker-compose.yml file (for example in a /srv/kadiska/ folder).

version: '3'

services:

    # Kadiska Station
    kd-station:
        image: "unicats/kd-station:stable"
        environment:
            KD_LOG_LEVEL: INFO
            KD_STATION_API_KEY: "YOUR KEY HERE"
        labels:
            com.centurylinklabs.watchtower.enable: true
        restart: unless-stopped

    # Upgrade the station periodically
    watchtower:
        image: "containrrr/watchtower"
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            WATCHTOWER_LABEL_ENABLE: 1
            WATCHTOWER_POLL_INTERVAL: 3600
            WATCHTOWER_CLEANUP: 1
            WATCHTOWER_INCLUDE_RESTARTING: 1
            WATCHTOWER_INCLUDE_STOPPED: 1
            WATCHTOWER_REVIVE_STOPPED: 1
        restart: unless-stopped

Now you can launch the Station. Do not forget to replace the KD_STATION_API_KEY variable provided in the example above by your own key.

$ cd /srv/kadiska/
$ docker-compose up -d
$ docker-compose ps
      Name            Command       State    Ports
----------------------------------------------------
srv_kd-station_1   /entrypoint.sh   Up
srv_watchtower_1   /watchtower      Up      8080/tcp

Both services must be Up.

Step 3: Enterprise Station activation

If the deployment is successful, you will see the deployed Station's public IP address. Check it and confirm the Station registration by clicking on "Yes, this is the correct IP address". Screenshot

Now your Station is fully activated and ready to perform Tracer tests.

Screenshot

Using a proxy

You can configure the Station so that it connects through a proxy.
Only the HTTP(S) traffic will obviously pass through the proxy. This corresponds to:

  • fetching the Station configuration
  • updating the Station software version
  • sending the collected performance metrics to the Kadiska platform

The traffic generated by the Tracer tests themselves does not go through the proxy.

Simple login/pwd authentication

A simple authentication based on a login and password can be configured by adding the following environment variable:

 http[s]_proxy: "http[s]://user:pass@proxy-address:port"

Authentication with certificate

Instead of using plaintext login and password, which may not guarantee the level of security required by your organization, you can use a certificate as an alternative to authenticate the Station. The corresponding environment variables are the following:

https_proxy: "https://proxy-address:port"
PROXY_CERT: |
              -----BEGIN CERTIFICATE-----
              your_certificate
              -----END CERTIFICATE-----            

Using a certificate chain

You can connect Kadiska Enterprise Stations through proxies that perform HTTPS decryption.
For this you need to import the certification chain in the Station.
This is done through the volumes variable, REQUESTS_CA_BUNDLE environment variable and HTTPS_PROXY environment variable.
The template of the docker-compose.yml file looks like this:

version: '3'

services:

    # Kadiska Station
    kd-station:
        image: "unicats/kd-station:stable"
        volumes:
            # Replace /PATH/TO/YOUR-CERTIFICATE-HERE.CRT by the path to the proxy certificate chain
            - /PATH/TO/YOUR-CERTIFICATE-HERE.CRT:/etc/ssl/certs/proxy.crt
        environment:
            KD_LOG_LEVEL: INFO
            KD_STATION_API_KEY: "YOUR_API_KEY_HERE"
            HTTPS_PROXY: "https://xxxxxxxxxxxxxxxxxxxxx"
            REQUESTS_CA_BUNDLE: "/etc/ssl/certs/proxy.crt"
        labels:
            com.centurylinklabs.watchtower.enable: true
        restart: unless-stopped

    # Upgrade the station periodically
    watchtower:
        image: "containrrr/watchtower"
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
            # Replace /PATH/TO/YOUR-CERTIFICATE-HERE.CRT by the path to the proxy certificate chain
            - /PATH/TO/YOUR-CERTIFICATE-HERE.CRT:/etc/ssl/certs/proxy.crt
        environment:
            HTTPS_PROXY: "https://xxxxxxxxxxxxxxxxxxxxx"
            WATCHTOWER_LABEL_ENABLE: 1
            WATCHTOWER_POLL_INTERVAL: 3600
            WATCHTOWER_CLEANUP: 1
            WATCHTOWER_INCLUDE_RESTARTING: 1
            WATCHTOWER_INCLUDE_STOPPED: 1
            WATCHTOWER_REVIVE_STOPPED: 1
        restart: unless-stopped

The file containing the certificates can be provided as a bundle containing multiple consecutive certificates. The required format is the following:

-----BEGIN CERTIFICATE-----
your_certificate_1
-----END CERTIFICATE-----   

-----BEGIN CERTIFICATE-----
your_certificate_2
-----END CERTIFICATE-----   
etc..

Troubleshooting

In case your Enterprise Station does not operate as expected, the first step to troubleshoot the issue consists of analysing the docker-compose logs.
Connect to your Station in SSH, go to the folder containing your docker-compose.yml file and issue the following command:

sudo docker-compose logs --tail 200

Send the output to our CSM (Customer Success Management) team (csm@kadiska.com) for further analysis and guidance.

You can also try to rebuild the Station.
From the folder containing the docker-compose.yml file, issue the following command:

sudo docker-compose down
sudo docker-compose build --pull
sudo docker-compose up -d

Disabling a Station

If you want to temporarily deactivate a Station without deleting it, you can do it by clicking on the "Deactivate" button in the Station's configuration menu.
The Station can be reactivated at any time. The corresponding Tracers will be automatically reassigned and launched.

Screenshot


© 2022 Kadiska | Digital Experience Monitoring DEM. All rights reserved