Skip to content

Install KX Sensors

This page explains how to edit install.profile, review manifest files, enable authentication, and run the installer.

Before you start, complete the steps in Prepare for installation.

Edit install.profile

Your bundle contains one or more deployment directories, such as 1-node-deploy or 3-node-deploy. Choose the one that matches your target topology. In the steps that follow, <deploy-dir> stands for the deployment directory you chose.

Each deployment directory contains an install.profile file at kxs-bundle-<client>-<version>/<deploy-dir>/install.profile. The installer reads this file to get important installation settings, such as the addresses of the target hosts. Review the file, and edit the values for your installation. The file includes comments for each setting.

At a minimum, review the following settings. For all settings, see install.profile reference.

Setting Description
USERNAME The application user that KX Sensors runs as.
KXS_ROOT The installation directory. By default, the installer creates the database, EMS, and log directories under it.
KXS_BASE_PORT The base TCP/UDP port. KX Sensors uses the range KXS_BASE_PORT to KXS_BASE_PORT + 1000.
MULTICAST_GROUP_IP The multicast group IP address for the cluster. It must be unique on the entire network.
KXS_BASE_TASKSET The CPU taskset. Adjust it to match your license restrictions. For multi-node installs, use a comma-separated list that matches HOSTS. See Tasksets.
KXS_LOAD_DIRS The packages to load, as a semicolon-separated list. kxs-core must be first, and later packages overlay earlier ones. Include the correct package versions. Each entry is the package file name without its extension, which matches the top-level directory name of the extracted package. The last entry must be the env package, unpacked under <deploy-dir>/packages/. The installer edits its config/systemParams.yaml to set the multicast addresses and the database and EMS paths. If the last entry isn't the env package, the installer fails with an error.
HOSTS The host names to install on, as a comma-separated list.
HOSTS_PRIVATE The host names on the internal network, in the same order as HOSTS. Each name should match the output of hostname on that server.
NODENAMES The node names, in the same order as HOSTS. They must match your manifest file names.
DESCS The node specification for each node: e installs etcd on the node, and x means no further installations on the node. The bundle prefills this value for your topology, so you can usually leave it unchanged.
KXS_MASTER_KEY, KXS_SEED_USER, KXS_SEED_PASS The master encryption key and initial admin credentials. Set the seed user and password yourself, because the installer falls back to default credentials. See Enable authentication.

Review manifest files

Manifest files specify which processes run on each KX Sensors node, and how many. Your bundle contains prefilled manifests for each deployment directory. You typically make only minor changes, if any.

If you change the number of nodes, make sure there is a manifest for each node in kxs-bundle-<client>-<version>/<deploy-dir>/manifests/. Name each file manifest-<node name>.yaml. The node names must match the NODENAMES value in install.profile. For how to create a manifest file, see Configure service classes in manifest.yaml.

For a 3-node deployment, the manifests folder looks like this:

kxs-bundle-<client>-<version>
\-- <deploy-dir>
    \-- manifests
        +-- manifest-A.yaml
        +-- manifest-B.yaml
        \-- manifest-C.yaml

Enable authentication

To authenticate connections to qetcd or to kxsctl-agent, edit the following settings in install.profile:

Setting Effect when enabled
QETCD_AUTH Authenticates connections to qetcd, for example from a SAPI client.
KXSCTL_AGENT_AUTH Authenticates connections from a remote kxsctl-client.

Whether or not you enable authentication, the installation needs KXS_MASTER_KEY, KXS_SEED_USER, and KXS_SEED_PASS. KXS_MASTER_KEY must be a string of 16, 24, or 32 characters. To avoid storing these values in install.profile, you can supply them on the command line with the -Z and -x options. See Installer reference.

If you run the installer interactively and leave these values empty, the installer prompts you for them. This is the most secure option, because the values stay out of both install.profile and your shell history.

Default credentials

At the interactive prompts, if you leave the seed user or seed password blank, the installer silently uses Administrator and password. Always enter your own values. In non-interactive runs, the install fails if the seed values are missing.

If you leave the master key blank at the prompt, the installer generates a random 32-character key. In non-interactive runs, the installer always generates the key unless you supply one. You can't change the master key after the first install. When you upgrade with -U, the installer reads the key from the target's kxsenv, and rejects -Z combined with -U.

To enable authentication for individual processes, add auth: true to the relevant manifest entries. The following example enables authentication for all KX Sensors processes. Make this change in each manifest file in the manifests directory of your deployment directory:

.default_service: &default_service
    enabled: true
    portOffset: 100
    num: 1
    threads: 0
    prefix: ""
    auth: true

After the installation completes, manage users with kxsctl user on any node, or with kxsctl-client user from a remote server. For more information, see User authentication.

Run the installer

From the kxs-bundle-<client>-<version> directory, run:

./install -aD <deploy-dir>

The -a flag runs all installation steps, and -D specifies your deployment directory, for example 3-node-deploy.

The installer logs all output to install-<deploy-directory>-<timestamp>.log. If anything fails, the log contains the error details. The installer exits immediately if it encounters an error.

For all installer options, run ./install -h, or see Installer reference.

Next steps