Skip to content

KX Sensors installer reference

This page is a reference for the KX Sensors installer: its options, the install.profile settings, post-install commands, uninstall and upgrade staging, and etcd and inotify settings.

For the installation procedure, see Install KX Sensors.

Installer options

Run ./install -h to list all options. The options are switches. For the installation steps, -a selects all steps, and the other step flags toggle individual steps on or off, except -S, which only turns the setup steps on.

General options

Option Description
-h Displays the help message.
-D <dir> Specifies the deployment directory, such as 3-node-deploy.
-y Accepts all prompts automatically.
-n, --no-unpack Doesn't unpack in the copy step.
-X, --no-overwrite Doesn't overwrite existing packages in the copy step.
-E, --no-edit-env Doesn't edit the env package.
-L, --keep-external-ips Keeps external IP addresses in KXS_DISC_ENDPOINTS.
-x, --seed-credentials <username:password> Supplies the seed user and password, in the format username:password.
-Z, --master-key <key> Supplies the value of KXS_MASTER_KEY.

Installation steps

Option Description
-a Performs all installation steps, including the KX Developer and kxsctl-agent steps. To skip a step, combine -a with its option. For example, -aI skips the KX Developer step.
-k Toggles the SSH test step.
-p Toggles the prerequisites step, which is the only step that needs sudo.
-c Toggles the copy step.
-C Toggles the credential step.
-e Toggles the etcd step.
-q Toggles the qetcd step.
-S Performs the setup steps.
-I Toggles the KX Developer step.
-A Toggles the kxsctl-agent step.

Optional steps

The -a option doesn't include these steps. Add them explicitly.

Option Description
-u Toggles the uninstall step.
-N Toggles the nc test step, which tests UDP connectivity between hosts.

Examples

./install -aD myDeployment    # Perform all installation steps using myDeployment
./install -aN                 # Perform all installation steps, plus the optional nc test
./install -apD myDeployment   # Perform all steps except the prerequisites step, using myDeployment
./install -qS                 # Run only the qetcd and setup steps
./install -ua                 # Uninstall and reinstall. Deletes $KXS_ROOT and its data first

install.profile reference

The following tables describe the settings in install.profile. The sample file in the bundle also documents each setting in comments.

Directories and users

Setting Description
USERNAME The application user.
KXS_ROOT The installation directory. Default: /home/$USERNAME/kxs.
KXS_DB_DIR The database directory. Default: $KXS_ROOT/db.
KXS_EMS_DIR The EMS directory. Default: $KXS_ROOT/ems.
KXS_LOG_DIR The log directory. Default: $KXS_ROOT/logs.
KXS_LOG_RET The log retention period, in days. Default: 30.
KXS_LOG_UNCOMPRESSED_RET The retention period for uncompressed logs, in days. Default: 7.
KXS_IDB_NAME, KXS_HDB_NAME The directory names for the IDB and HDB. Change them only if you need a non-standard or legacy name.

Network and tasksets

Setting Description
KXS_BASE_PORT The base TCP/UDP port. Open the range KXS_BASE_PORT to KXS_BASE_PORT + 1000 in your firewall for multi-node installations.
MULTICAST_GROUP_IP The multicast group IP address, in the range 239.0.0.0 to 239.255.255.255. It must be unique on the entire network.
KXS_BASE_TASKSET The taskset for KX Sensors. Adjust it to match your license restrictions. For multi-node installations, use a comma-separated list that matches HOSTS and HOSTS_PRIVATE.

Packages, hosts, and nodes

Setting Description
KXS_LOAD_DIRS The packages to load. kxs-core must be first, and the last package listed overlays the preceding ones. 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. You can add, remove, or reorder packages after installation.
HOSTS The target host names, comma-separated.
HOSTS_PRIVATE The target host names on the internal network. Must be the same length and order as HOSTS, and should match hostname on each server.
NODENAMES The node names, comma-separated.
DESCS The node specification for each node: e installs etcd on the node, and x means no further installations on the node.

etcd and qetcd

Setting Description
ETCD_DIR The etcd installation directory. Default: $KXS_ROOT/bin/etcd.
ETCD_DATA_DIR The etcd data directory. Default: $KXS_ROOT/etcd.
SYSTEMD_SERVICE_DIR The systemd unit directory. Default: /home/$USERNAME/.config/systemd/user.
ETCD_LOG_LEVEL, QETCD_LOG_LEVEL The log levels for etcd and qetcd. Default: info.
QETCD_AUTH Authenticates connections to qetcd. Default: false.

TLS

For more information, see In-transit TLS encryption.

Setting Description
KX_SSL_CERT_FILE, KX_SSL_CA_CERT_FILE, KX_SSL_KEY_FILE, KX_SSL_CN The certificate, CA certificate, key, and common name that KX Sensors uses.
KX_SSL_VERIFY_CLIENT, KX_SSL_VERIFY_SERVER Whether to verify the client and server certificates.
ETCD_SSL_PEER Enables TLS encryption for peer-to-peer etcd traffic. Default: false.
ETCD_SSL_CLIENT Enables TLS encryption for client-to-server etcd traffic. Default: false.
ETCD_SSL_VERIFY_CLIENT Enables authentication (mTLS) of the clients that connect to etcd: etcdctl, kxsctl, and qetcd. Default: false.
ETCD_SSL_CLIENT_CERT_FILE, ETCD_SSL_CLIENT_KEY_FILE The certificate and key paths that clients use to identify themselves to etcd servers. Required if ETCD_SSL_VERIFY_CLIENT is true.
KXSCTL_AGENT_TLS Enables TLS for kxsctl-agent. Default: false.
KXSCTL_AGENT_AUTH Authenticates connections from a remote kxsctl-client. Default: false.

Credentials

Setting Description
KXS_CREDENTIAL_FILE The authorization credentials for inbound and outbound connections. Default: $KXS_ROOT/misc/cred.
KXS_MASTER_KEY The master key for encryption. Must be 16, 24, or 32 characters long. If blank, the installer generates a 32-character key. You can't change it after the first install. See Enable authentication.
KXS_SEED_USER, KXS_SEED_PASS The initial admin user credentials. If you leave them blank at the interactive prompts, the installer uses Administrator and password. In non-interactive runs, missing values fail the install.

Logging

Setting Description
KXS_LOG_TS The timestamp format in application logs: 0 for UTC (the default), 1 for UTC with the local time offset, 2 for local time, and 3 for local time with the local time offset.
KXS_LOG_ROLLOVER_MODE The log rollover frequency: 0 for daily (the default) or 1 for hourly. Hourly rollover changes the log file names from PROC-YYYY.MM.DD.log to PROC-YYYY.MM.DD-HH.log.

Miscellaneous settings

You typically don't change these settings.

Setting Description
SUDO The sudo command to use for commands such as yum. Set to "" to run the installer without sudo.
SSH_OPTIONS The SSH options the installer uses.
TMP_DIR The temporary directory the installer uses.
BASHRC The configuration file used to source kxsenv and alter PATH.

Single-host and hybrid HA

Use these settings when the host name associated with a node is virtual.

Setting Description
KXS_HOSTNAME The virtual host name for the pacemaker nodes, for example virtual.example.com.
KXS_SIHA_DIR The location of the pacemaker state file. Default: $KXS_ROOT/pacemaker.
SIHA_FAILOVER_HOST The host that takes over on pacemaker failover, for example server2.example.com.
SIHA_POST_URL The HTTP POST URL for external failover notifications.

Post-install options

After installation, use the following options:

Option Description
./install -Y Copies application logs.
./install -T Stops KX Sensors without deleting any data. It also removes the kxs*.service systemd user units: the process units, kxs-etcd, kxs-qetcd, and kxsctl-agent. Run -P, then -B, to bring them back.
./install -K Stops KX Sensors and deletes all data created by the application. Run -P to prepare the environment again.
./install -P Prepares KX Sensors to be initialized.
./install -B Enables and starts KX Sensors on the remote hosts.
./install -U <yes\|no\|prompt> Stages an upgrade using the specified deploy directory. See Stage an upgrade.

For example, to reset KX Sensors using the deployed packages, run ./install -KPB.

Uninstall

Uninstalling deletes data

After a confirmation prompt, the uninstall step stops, disables, and removes all kxs* systemd units, and removes the KX Sensors block from .bashrc. It then runs rm -rf $KXS_ROOT $TMP_DIR. With the default paths, this deletes the database, EMS, log, and etcd data. Data directories outside $KXS_ROOT are kept. Back up anything you need before you continue.

To uninstall KX Sensors, run:

./install -uD <deploy-dir>

Stage an upgrade

You can use the installer to stage, and optionally apply, a dynamic upgrade. Use -D to specify the deploy directory that contains the upgraded packages. The installer copies the upgraded packages to the hosts without deleting any existing packages.

The argument to -U controls what happens after staging:

  • yes runs the kxsctl deploy command automatically.
  • no doesn't run it.
  • prompt shows you the kxsctl deploy command and lets you confirm or cancel it.

Use yes and no in automated scripts. Choose the argument carefully, because some changes require an offline upgrade or a system restart, which you must do separately. The -y ("yes to all") option doesn't apply to the kxsctl deploy step.

./install -U "prompt" -D 3-node-deploy  # Stage an upgrade, and prompt before issuing the DU command
./install -U "yes" -D 3-node-deploy     # Stage an upgrade, and issue the DU command without prompting
./install -U "no" -D 3-node-deploy      # Stage an upgrade, and don't issue the DU command

For the full upgrade procedure, see Before you begin and Dynamic upgrades using the KX Sensors CLI.

Manual and custom installations

The installer's scripts install etcd based on fixed conventions. The following sections describe how KX Sensors uses etcd and the inotify limits, in case you install etcd manually or customize how you deploy it.

etcd

KX Sensors uses etcd to store system state and the data that processes use to discover each other. The basic requirement is that etcd version 3.5.2 is accessible to etcd clients at the configured KXS_BASE_PORT.

  • You can use a single-node etcd cluster for single-node KX Sensors deployments.
  • KX strongly recommends at least a 3-node etcd cluster for deployments that require high availability. You can add nodes for more redundancy, at the cost of performance.
  • You can't share an etcd cluster between multiple KX Sensors deployments. You can run multiple distinct etcd clusters on shared servers if you configure them with different KXS_BASE_PORT values.

The installer generates the etcd configuration from deps/etcd-conf-template.yml and writes it to $ETCD_DIR/etcd-conf.yml on each host. The kxs-etcd.service file that the installer creates runs etcd --config-file with that file. To change the configuration used to start etcd, edit the template before you install, or review the generated etcd-conf.yml on each host.

inotify limits

RT requires higher inotify limits. During the prerequisites step, the installer writes the following values to /etc/sysctl.d/kxs-sysctl.conf and loads them with sysctl --system:

fs.inotify.max_queued_events=5000000
fs.inotify.max_user_instances=5000000
fs.inotify.max_user_watches=500000

If your hosts already set conflicting values in another sysctl file, the installer fails and reports the key. For other recommended OS settings, see OS settings.

Next steps