How to set up an Enterprise Station
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
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.
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.
|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:
By default, you're directed to the "Watchers" configuration page. Click on "Stations" to go the Kadiska Stations configuration page.
On your screen, you may already see a list of managed Stations that we publicly provide access to.
You can deploy your own Station(s) by first clicking on the button "Create".
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:
|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.
If you go to the list of available Stations (button "Back"), you can see the newly created Station and its status ("unconfigured").
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.
You’ll use this API key later, when deploying the docker container.
Step 2: Enterprise Station deployment
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:
- For RHEL, Centos, Rocky and openSUSE:
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.
Before manually deploying the Station container, make sure the host on which you’ll deploy it contains a Docker engine.
docker-compose in version 1.21.0 or higher.
Once this is done, create the following
docker-compose.yml file (for example in a
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.
Both services must be
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
If the HTTPS traffic required to download the docker image from DockerHub must pass through the proxy, this must be configured at the machine OS level. The traffic generated by the Tracer tests themselves does not go through the proxy.
Simple login/pwd authentication
A simple login and password based authentication can be configured by adding the following environment variable to both the Station and Watchtower containers:
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, and Watchtower container.
This is done in the
volumes sections, and with environment variables
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.pem by the path to the proxy certificate chain - /PATH/TO/YOUR-CERTIFICATE-HERE.pem:/usr/local/share/ca-certificates/station_proxy.crt:ro environment: KD_LOG_LEVEL: INFO KD_STATION_API_KEY: "YOUR KEY HERE" https_proxy: "http[s]://user:pass@proxy-address:port" PROXY_CERTS_FILE: "/usr/local/share/ca-certificates/station_proxy.crt" labels: com.centurylinklabs.watchtower.enable: true restart: unless-stopped # Upgrade the station periodically watchtower: image: "containrrr/watchtower" volumes: # Replace /PATH/TO/YOUR-CERTIFICATE-HERE.pem by the path to the proxy certificate chain - /PATH/TO/YOUR-CERTIFICATE-HERE.pem:/etc/ssl/certs/station_proxy.crt:ro - /var/run/docker.sock:/var/run/docker.sock environment: https_proxy: "http[s]://user:pass@proxy-address:port" 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
/PATH/TO/YOUR-CERTIFICATE-HERE.pem above must be replaced by the path to the proxy certificate chain.
Certificates can be provided as a bundle containing multiple consecutive certificates. The required format is the following:
Enable IPv6 support
By default, IPv6 support is not enabled. You can activate it as follows.
Make sure that your host and network are IPv6 compatible.
Add this configuration to the Docker daemon configuration file
/etc/docker/daemon.json. (Create the file if it does not exist):
Restart the docker daemon:
docker-compose.yml file, with these changes:
Note the addition of a network for both images, and the declaration of this network below.
You can restart the Station:
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".
Now your Station is fully activated and ready to perform Tracer tests.
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:
Send the output to our CSM (Customer Success Management) team (firstname.lastname@example.org) 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:
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.