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/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
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.
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:
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:
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
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:
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 (email@example.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:
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.