Command line interface

The KX Refinery command line interface (CLI) allows you to administer Refinery from the Unix command line.

command Description since
application Core application level start/stop/status commands 0.1.3
configuration Configuration parameter management 0.1.3
datacopy HDB data-copy between Refinery instances 0.8.0
failover Application failover management 0.5.0
install Refinery package download and installation 0.5.0
logs Log file viewing and management 0.2.0
monitoring Monitoring components, data capture and alert management 0.1.3
pipeline Pipeline start / stop / status commands 0.6.0
process-manager Process Manager start / stop / status commands 0.6.0
process Individual process management 0.5.0
service-class Service class start / stop / status commands 0.6.0
udf User-defined function management 0.1.3
user User management 0.1.3
workflow Workflow start/stop/status commands 0.1.3

Information about each command can be found after the CLI has been installed:

man refinery
man refinery command

Prerequisites

bash     version 4.2 or later
openssl  version 1.0.2 or later
wget     version 1.14 or later

Version map

The CLI is an independent component from Refinery and has a separate release history.

Refinery Version CLI Version
4.3.x 0.2.0
4.4.x 0.3.1
4.5.x 0.5.0
5.0.x 0.6.0
5.1.x 0.7.0
5.2.x 0.8.0
5.3.x 0.8.1
5.4.x 0.8.2
5.5.x 0.10.2
5.7.x 0.10.4
5.8.x 0.11.1
5.9.1 0.11.2
5.9.2 0.11.3
5.9.3 0.12.0
5.9.4 0.12.1
5.10.1 0.12.2

Installation and configuration

Installation

To install the CLI via RPM:

rpm -iv kx-refinery-cli-version-release.oem.x86_64.rpm

To upgrade the CLI via RPM, use -U:

rpm -Uv kx-refinery-cli-version-release.oem.x86_64.rpm

The RPM also includes a changelog of all changes:

rpm --query --changelog -p kx-refinery-cli-version-release.oem.x86_64.rpm

Changelog

The RPM also includes a changelog of all changes. To view this:

rpm --query --changelog -p kx-refinery-cli-*version*-*release*.oem.x86_64.rpm

First run

Once installed, the CLI is called with refinery. This is installed in /usr/bin and made available to all users on the server. Simply running refinery with no arguments will print its usage information.

Without further configuration, the CLI will not be able to access the Refinery installation.

The CLI and all the commands within the CLI have 'man' pages available that show how they work. Run man refinery or man refinery *command* for more information.

Mandatory configuration

Three mandatory configuration options must be set for the CLI to run correctly. The configuration can be set in either of two ways:

  • passing the arguments via the command line
  • a configuration file at $HOME/.refinery/cli-config

The required command line arguments are:

--install-root=root-install-path
--install-user=admin-username
--install-pass=admin-password

Define the configuration file as follows:

[refinery]
KX_REF_CLI_INSTALL_ROOT=root-install-path
KX_REF_CLI_INSTALL_USER=admin-username
KX_REF_CLI_INSTALL_PASS=admin-password

You may omit the password from the file and on the command line; the CLI will prompt you for a password on invocation.

Each profile is identified by the name within the square brackets. By default, with a single KX Refinery installation to manage, this value should be [refinery]. Additional profiles can be specified within this file and then referenced with the --profile= global command line option.

Alternate failover location

Using the cli-config configuration file above, you can assign an alternate file location for the failover.csv. This file has the host and port of your Refinery Delta Control process. You can implement this by adding the code below to the cli-config file:

KX_REF_CLI_INSTALL_FAILOVER=file/location/path

This will override the pre-existing failover file found here: [KX_REF_CLI_INSTALL_ROOT]/delta-bin/config/failover.csv.

This will allow you to share your failover.csv across multiple installs.

Encrypting your password configuration

The CLI also supports encryption of the Refinery super-user password in the configuration file. To store the password in encrypted form, an encryption / decryption passphrase must be entered on every invocation of the CLI.

To generate the encrypted password configuration, use refinery --install-pass-encrypt.

The CLI will prompt for the super-user password to be encrypted and then the encryption / decryption passphrase. The configuration will then be printed out to be copied into the configuration file.

Syntax

refinery [global-options] command [command-options]

Global options control the CLI as a whole; command options are passed to the command itself. They are specified differently:

  • Global options as --argument=value
  • Command options as --argument value

If a value has a space in it, enclose it in double quotes.

Global options

--debug                      --kdb-no-validate            --list
--help                       --kdb-taskset                --no-color
--install-pass*              --kdb-tls-ca-src             --profile*
--install-pass-encrypt       --kdb-use-tls                --quiet
--install-root*                                           --version
--install-user*
--help

Show usage summary information for all global options.

--list

Print all the available commands within the Refinery CLI.

--profile=config-profile (mandatory)

Run the CLI with one of the profiles with the Refinery CLI configuration file.

--install-root=root-install-path (mandatory)

The root folder of the KX Refinery installation.

--install-user=admin-username (mandatory)

The KX Refinery super-user username.

--install-pass=admin-password (mandatory)

The KX Refinery super-user password.

--install-pass-encrypt

Generates an encrypted version of the Refinery super-user password that can be stored in the CLI configuration file.

A separate encryption password needs to be supplied interactively to encrypt during creation and to decrypt on every CLI invocation.

The CLI configuration will be printed to standard out and should be copied to the CLI configuration file.

--debug

Enables debug logging within the CLI.

--no-color

Disables color logging

--quiet

Reduces the amount of logging the CLI prints to the console. Command-specific output is unaffected.

--kdb-no-validate

Do not perform any validation of kdb+ prior to running any commands or global features. This option simply defers the error until kdb+ is required for a specific command.

This can be useful on servers that do not have Refinery installed.

--kdb-taskset=taskset-cpu-list

CPU core binding (with taskset -c) for any kdb+ process that executes within the CLI

--kdb-use-tls

Connect to all Refinery kdb+ processes via TLS.

For TLS to work:

  • Specify a CA certificate file or path with --kdb-tls-ca-src=
  • Define $KX_SSL_CA_CERT_FILE or $KX_SSL_CA_CERT_PATH in your environment
--kdb-tls-ca-src=ca-file-or-folder-path

If --kdb-use-tls has been specified, specifies the CA certificate file or folder.

Not required if either $KX_SSL_CA_CERT_FILE or $KX_SSL_CA_CERT_PATH is defined in your environment.

--version

Print Refinery CLI and kdb+ version information