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:
yesruns thekxsctl deploycommand automatically.nodoesn't run it.promptshows you thekxsctl deploycommand 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_PORTvalues.
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.