About kxsctl¶

This page introduces kxsctl, the command-line interface for administering a KX Sensors deployment.

kxsctl is the command-line interface by which you administer a Sensors instance, whether it be a single-node or multi-node deployment. Operations that you can perform include adding nodes, starting and stopping nodes and processes, and retrieving status information about processes and service classes.

You can look up kxsctl help by means of the following command:

kxsctl -h

[root@kxsa /]# kxsctl -h
KxSensors cli: cc552ff

Usage:
  kxsctl [command]

Available Commands:
  add          Add a node
  completion   Generate the autocompletion script for the specified shell
  disable      Disable node or service class
  enable       Enable node or service class
  exec         Execute q code on target processes
  help         Help about any command
  history      Show previously run kxsctl commands
  init         TEMP: Initialize (q)etcd
  log          View process log files
  manifest     Show, export, import or edit a node manifest
  mc           Start an interactive maint console
  refresh      Regenerate systemd unit files
  restart      Restart a list of targets
  show         Show information about a process, node or service class
  start        Start a list of targets
  status       View system status
  stop         Stop a list of targets

Flags:
      --endpoints strings   Etcd endpoint(s) (default [localhost:20379])
  -h, --help                 help for kxsctl
  -q, --quiet                Skips confirmation prompts
  -v, --verbose count        Display verbose logging and execution information

Use "kxsctl [command] --help" for more information about a command.
[root@kxsa /]#

The following flags are supported for all kxsctl commands:

Flag	Description
`-h`	(help) Shows additional help information. This includes semantic descriptions of each command, each argument of each command and other context-dependent details.
`-q`	(quiet) Skips confirmation prompts.
`-v`	(verbose) Displays verbose logging and execution information.

You look up the help for a specific kxsctl command as follows:

kxsctl help [command]

Changes in v3.3

kxsctl manifest replaces the kxsctl export and kxsctl import commands, and kxsctl log replaces kxsctl show log. The kxsctl history and kxsctl refresh commands are new. For a summary of the v3.3 CLI changes, see the release notes.

Exit status¶

The start, stop, enable, disable and refresh commands exit non-zero when a target never reaches the requested state, when the operation times out, or when a node reports that it cannot act. Use the exit status rather than the command output to detect failures in scripts.

Regenerate systemd unit files¶

A release can change the systemd unit files that KX Sensors processes run under. kxsctl refresh regenerates the unit files for the targets you name, from the current templates and manifest.

Syntax	`kxsctl refresh [targets] [flags]`
Flags	`--prune` Also stops processes that are no longer in the manifest and removes their unit files.

Timers are armed only for enabled targets, so a reboot doesn't start a disabled process. For more information about the unit files themselves, see About systemd.

Look up command history¶

kxsctl history shows the commands previously run through kxsctl on the current node, with the timestamp, the account that ran each command, and the command itself. History is recorded in $KXS_LOG_DIR/.kxsctl_history.

Syntax	`kxsctl history [flags]`
Flags	`-c` (count) Number of entries to show (default = 20). Use `-c 0` to show all entries.

Remote administration with kxsctl-client¶

kxsctl-client administers a KX Sensors deployment from a machine that isn't part of it. It connects over gRPC to the kxsctl-agent process on a node, which authenticates the request and runs the command against the deployment.

From v3.2.6, kxsctl-client supports calling any native kxsctl command remotely. Earlier versions support only a subset.

Because commands run through kxsctl-agent, kxsctl-client requires KX Sensors credentials. It sends the username and password as gRPC request metadata, and kxsctl-agent validates them. The role assigned to the user determines which commands are permitted. For more information, see User authentication.

You look up help and the client version as follows:

kxsctl-client -h
kxsctl-client version

When you upload a directory, kxsctl-agent unpacks any .qpk archives it finds under a deps directory, so packaged dependencies are ready to use on the node.

Password flags

The -p and -n shorthands have been removed from kxsctl user and kxsctl-client user. Use --password and --new-password instead. Update any scripts that use the short forms.