Skip to content

Prepare to install KX Sensors

This page explains what to prepare before you install KX Sensors: SSH keys, network settings, sudo permissions, host prerequisites, the installation bundle, and your license.

Complete the following preparation on every host that runs KX Sensors, then continue to Install KX Sensors.

SSH keys

Both the installer and KX Sensors use SSH to run commands across the hosts in the cluster. Provision SSH keys before you install so that you don't need a password. First, some terminology:

  • Installation user: the user who runs the installation. For example, a system administrator, or the user that your CI or Ansible job uses for automated deployments.
  • Application user: the user that a KX Sensors deployment runs as. If you run multiple KX Sensors deployments on one server, each needs its own application user. When you view the processes of a running deployment, the application user is the owner.

SSH for the installer

The installer copies files and runs commands remotely on all target hosts. The installation user must therefore be able to SSH to all target hosts without a password. You can run the installation from a separate host or from one of the target hosts. Even if you run it from a target host, SSH must work from that host to itself. You need this access only during installation, and you can revoke it afterwards.

The only case where SSH access isn't required is a single-node install run by the application user on the same host. In that case, all commands run locally.

For example, if:

  • The installation user is sysadmin.
  • The application user is kxs-dev.
  • You install to a single node, host-a, and run the installer on host-a.

Then the following must work without a password, when run as sysadmin on host-a:

sysadmin@host-a$ ssh kxs-dev@host-a

SSH for KX Sensors

The application user must be able to SSH from any host in the cluster to any other host, without a password. This must work for both the HOSTS and HOSTS_PRIVATE names in install.profile. The kxsctl command line interface uses this access to operate the cluster, so it must remain in place while the cluster is active. This applies to single-node deployments too.

For example, if the application user is kxs-dev and you install to a single node, host-a, the following must work without a password, when run as kxs-dev on host-a:

kxs-dev@host-a$ ssh kxs-dev@host-a

Provision the keys

Both the installer and KX Sensors connect as the application user, so every public key goes into the application user's ~/.ssh/authorized_keys file on each host. The following examples use kxs-dev as the application user.

  1. As the installation user, on the host where you run the installer, create a key pair if you don't already have one. Then copy the public key to the application user on every target host:

    ssh-keygen -t rsa -b 4096
    ssh-copy-id kxs-dev@<host>    # Repeat for each host in HOSTS
    
  2. As the application user, on every host in the cluster, create a key pair without a passphrase. Then copy the public key to every host in the cluster, including the host itself:

    ssh-keygen -t rsa -b 4096 -N "" -f ~/.ssh/id_rsa
    ssh-copy-id kxs-dev@<host>    # Repeat for each host in the cluster
    
  3. As the application user, on every host, connect once to each host by both its HOSTS name and its HOSTS_PRIVATE name. This confirms that no password is needed and records each host key:

    ssh kxs-dev@<host> true
    

The application user's key has no passphrase because KX Sensors uses it unattended. The installation user's key can have a passphrase if you load it in ssh-agent, because the installer's SSH calls can use the agent. The examples use RSA keys because hosts that run RHEL in FIPS mode don't allow ed25519 keys.

ssh-copy-id needs password authentication on the target host. If password authentication is disabled, append the contents of the .pub file to ~/.ssh/authorized_keys on the target host instead. sshd ignores authorized_keys if other users can write to it or to ~/.ssh, so set the permissions with chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys.

On multi-node installs, the installer tests these connections in its SSH test step (-k) before it makes any changes. On single-node installs, it skips this test.

SELinux

With SELinux enabled, sshd reads ~/.ssh/authorized_keys only if the file has the ssh_home_t label. Files under the standard home location, /home/<user name>, get this label automatically, so KX recommends using the standard location. If the application user's home directory is elsewhere, for example /data/home/kxs-dev, label that location the same way as /home, then reapply the labels:

sudo semanage fcontext -a -e /home /data/home
sudo restorecon -R -v /data/home

semanage is in the policycoreutils-python-utils package. To check the result, run ls -Zd ~/.ssh as the application user. The output should include ssh_home_t.

Network settings

KX Sensors uses both multicast and unicast. Make sure your network supports both. KX Sensors processes use the same port number for TCP and for listening to UDP data. Because multicast and unicast share the same transmission protocol (UDP), unicast ports must not overlap with multicast ports.

Multicast addresses are set in systemParams.yaml. The installer configures the address using the MULTICAST_GROUP_IP setting in install.profile. The address must be in the range 239.0.0.0 to 239.255.255.255, and it must be unique on the entire network. Installations on different hosts that use the same network still collide if they share the same multicast IP address.

Open the required ports between KX Sensors hosts, and between KX Sensors hosts and external SAPI client hosts. For the full list of ports, reserved offsets from KXS_BASE_PORT, and multicast guidance, see Network requirements.

For client-server communication, make sure that:

  • The server hosts accept TCP connections from SAPI clients on the range KXS_BASE_PORT to KXS_BASE_PORT + 1000.
  • Each SAPI client host accepts TCP connections from Response Processes (RPs) on the RP listening port set in the SAPI client configuration, and accepts UDP SDL acknowledgements on the client port set in the same configuration.
  • Each client uses a unique RP listening port.

External SAPI clients listen for connections that RPs initiate. When a client runs an API, the RPs aggregate the API results and return them to the client. Your firewalls must therefore allow inbound connections from the KX Sensors hosts to the SAPI client hosts on the ports configured for each client.

If you don't open the ports, or you choose a port range that other applications use, you might see errors or warnings during installation or startup.

sudo permissions

The application user needs sudo to install and set certain prerequisites. All steps that require sudo are in the prerequisites step, which you select with the -p flag. During this step, the application user (USERNAME) needs sudo on every target host, because the installer connects to each host as USERNAME and runs sudo as that user. You need to run this step only once. After that, you can run later installs without sudo, by deselecting the -p step or by setting SUDO="" in the install.profile of your deployment directory.

For each target host, the prerequisites step:

  • Installs missing host packages (see Host prerequisites).
  • Sets the inotify limits that RT requires. See inotify limits.
  • Enables systemd lingering for the application user, so that the user's services keep running after logout.

Passwordless sudo is a convenience, not a requirement. The installer checks whether the application user has (ALL) NOPASSWD: ALL permission and logs a warning if it doesn't. In that case, the prerequisites step can prompt for a password once per node.

# Run every prerequisite action that requires root:
./install -pD <deploy_dir>

# Then, in future, with sudo revoked or for a user without sudo access:
./install -apD <deploy_dir>

The flags are switches. Combining -a (all steps) with -p (the prerequisites step) turns the prerequisites step off, so -ap runs all steps except the one that needs sudo.

Host prerequisites

The installer checks that each host has the following commands and installs the missing ones with yum:

  • unzip
  • tar
  • systemctl
  • sysctl
  • tmux
  • rsync
  • ping
  • nc
  • fontconfig

systemctl and sysctl must already be present.

Third-party repository

If any of these commands are missing, the installer first installs the EPEL release RPM from dl.fedoraproject.org with dnf, then installs the missing packages with yum. This adds the third-party EPEL repository to the host. If your security policy doesn't allow this, install the missing packages yourself before you run the installer.

The installer installs the q binary for you. Don't install q on the target hosts beforehand, and don't set QHOME. If QHOME is set on a host, the installer asks you to confirm before it continues.

If a host has no internet access, see Air-gapped installation.

Installation bundle

  1. Get the release bundle from your KX representative. See Get the installation bundle and license.

  2. Extract the bundle, kxs-bundle-<client>-<version>.tgz. The contents look like this:

    kxs-bundle-<client>-<version>
    +-- 1-node-deploy          # A deployment directory
    +-- 1-node-tls-deploy      # A deployment directory
    +-- 3-node-deploy          # A deployment directory
    |   +-- install.profile    # Review and modify before installing
    |   +-- kxsenv_template    # Used by the installer to generate kxsenv
    |   +-- manifests          # Manifest files
    |   \-- packages           # Deployment-specific packages, such as env
    +-- 3-node-tls-deploy      # A deployment directory
    +-- Deployment Guide.md    # The installation guide for this bundle
    +-- deps                   # Dependencies, such as the etcd package and service templates
    +-- install                # The installer script
    +-- license                # Place your license here
    +-- packages               # Packages shared by all deployment directories
    \-- scripts                # Supporting scripts
    

    The deployment directories in your bundle depend on your configuration. Each one has the same structure.

License

Place your license in the license directory of the extracted bundle. KX provides the license separately from the bundle. The installer accepts any file with the .lic extension, and stops with an error if it can't find one. The file is usually k4.lic. If your license is kc.lic, use that file name wherever this guide says k4.lic. For the license formats and which versions they work with, see License formats. For the feature flags your deployment needs, see License requirements and management.

Next steps