Administration Reference Guide

1. Command Reference Manual

This section details all the commands available and how to use them, starting with the install command.

1.1. lxinst

This is the install program:

usage: lxinst [-h] [-v] [-D] [-s] [-m] [-n] [-f cfgfile] [-d dist] [-k key]
              [-K awspem] [-u location] [-c] [-i]
              [where ...]

leanXcale installer

positional arguments:
  where        [aws|docker|stats] dir, host, or host:dir

options:
  -h, --help   show this help message and exit
  -v           verbose
  -D           enable debug diags
  -s           small install
  -m           medium install
  -n           dry run
  -f cfgfile   use this configuration file
  -d dist      distrib file, dir, or url
  -k key       key to download the distribution.
  -K awspem    AWS pem file name w/o .pem
  -u location  update inst at location
  -c           clean. download everything
  -i           ignore system limits

Given arguments specify where to install the DB. They may be paths for directories in the local host, or host names, or host and directory names using the syntax host:dir.

Instead of arguments, a configuration file may be given using the -f flag. The configuration file has been described before in this document.

Flag -k may be used to specify the key to download the distribution.

Flag '-K' must be used when installing on AWS to supply the path (without file name extension) to the pem/pub key files.

By default, the distribution is retrieved from the leanXcale artifactory. However, it is possible to supply one or more times the -d flag giving it the name for a .tgz file, a directory, or a URL. The special argument leanxcale stands for the official repository for the distribution.

Distribution packages will be retrieved by looking at those distribution sources. By convention, the first source is usally the ./lxdist directory, used to keep the distribution when downloaded.

For example, this installs just what is downloaded at ./lxdist, without downloading anything else:

unix$ lxinst -d ./lxdist -f lxinst.conf

Once downloaded, files are not downloaded again. Flag ''-c'' cleans the ''./lxdist'' directory to force a download of everything. If a different directory is specified by the user, it is not cleaned, although packages not found will be still downloaded there. To force a download of particular packages, remove the packages desired from the ''./lxdist'' directory (or the directory specified in the arguments).

For example, this downloads a fresh copy of the distribution and installs it:

unix$ lxinst -c -f lxinst.conf

And this tries first the ../lxdist directory and then the standard leanxcale repository:

unix$ lxinst -d ./lxdist -d leanxcale -f lxinst.conf

This is actually the default when no distribution source is specified. Also, if no directory source is specified as a first option, lxdist is used as a directory to download components (other than files found on the local host).

The database has users (different from UNIX users). The user lxadmin is the administrator for the whole system. During the install you will be asked to type a password for lxadmin. To specify the password without being asked, you can set the password in the LXPASS environment variable:

unix$ export LXKEY=nemo:APA...uQy
unix$ export LXPASS=fds92f3c
unix$ lxinst /usr/local/leanxcale
...

When the users file ./lxowner exists, that file is used as the file describing the lxadmin user and its secret, instead of creating one using the user supplied password for lxadmin.

Do not use a existing file unless you know what you are doing. The reason is that this file must define lxadmin as the first user and that such user must have access to all resources, as configured.

Flag -i makes lxinst ignore system limits, to install on places with reduced disk or memory and in a hurry.

By default, the install performs a large install, trying to use all the machine resources for the service. Flag -s selects a small instead, and flag -m selects a medium install.

The install size affects components and sizes not specified by the user in command line arguments or in the configuration file. In a small install, at most 4 kdvs are added per host, and component memory is limited to 1GiB. In a medium install, at most 8 kvds components are added, and component memory is left with default values.

Flag -u is used to update a previous install. Still WIP, do not use it for now.

1.2. lx

Shell for running LeanXcale control programs. This simply fixes the environment for the installed host and runs the command given as an argument:

usage: lx [-d] cmd...

When flag -d is used, the current working directory is set to the install directory at the host before running the given command.

Most commands follow the same conventions regarding options and arguments. We describe them here for convenience:

positional arguments:
  what        host|comp...

options:
  -h, --help  show this help message and exit
  -l          local run only
  -D          enable debug diags

Flag -l is used when executing the command locally. This is used by the lx command framework, and should not be used in general by the end user.

Flag -D enables verbose diagnostics

Arguments specify what to operate (e.g., what to start, stop, etc.) may be empty to rely on the defaults (whole DB) or may specify a particular host and/or component name:

  • when only component names are given, and only those components will be involved (e.g., lxqe101).

  • when a component type name is given, components for that type are selected. (e.g., lxqe).

  • when a host name is given, any component following is narrowed to that host. If no components follow the host name, all components from the host are selected.

This may be repeated to specify different hosts and/or components.

The special host names db, repl, and repl2 may be used and stand for hosts without the nodb attribute, hosts for the first replica, and hosts for the second replica (hosts that are a mirror of other ones).

1.3. lx addlib

Add the given file(s) to the lib directory of the installed hosts, to add or update a library or jar in the installation:

usage: addlib [-h] [-l] [-v] [-D] [-a host] [-x] [files [files ...]]

add libs to installed lx

positional arguments:
  files       files to add

optional arguments:
  -h, --help  show this help message and exit
  -l          local run only
  -v          verbose
  -D          enable debug diags
  -a host     copy to this installed host(s)
  -x          internal use only

1.4. lx backup

Create, list, and restore backups from a installed host:

usage: backup [-h] [-l] [-n] [-v] [-D] [-i] [-d dir] [-r dir] [-p] [-z]
              [what [what ...]]

backup

positional arguments:
  what        host|comp

optional arguments:
  -h, --help  show this help message and exit
  -l          local run only
  -n          dry run
  -v          verbose
  -D          enable debug diags
  -i          incremental
  -d dir      root backup dir
  -r dir      backup dir to restore
  -p          print backup dirs
  -z          gzip backup files

This command copies disk contents to a backup directory or restores them. See lxbackup for backups/restores on external hosts.

By default, the backup is $LXDIR/dump at the host used to issue backup commands. The convention is to use the first host to keep backups.

This directory can be a mount point or a link to a remote directory to keep backups at a different machine.

Directories under dump/ are named using the date, with .1, .2, etc. appended if more than one backup is created on the same date. If the backup is incremental, a final + is added to the directory name.

For example, create a full, cold, backup when leanXcale is not running:

unix$ lx backup
backup...
host atlantis...
backup: /usr/local/leanxcale/dump/230720
unix$

The printed path is the path for the directory keeping the backup, as used when restoring it.

Create an incremental (cold) backup:

unix$ lx backup -i

It is possible to backup just one or a few components, supplying arguments that address them like in other commands, as described before. In this case, it is advisable to perform always backups for the same set of components. This command does not know if the last full backup is for the whole database or just for a few components. The last full backup is considered the full backup for the whole thing.

In general, the system should not be running while doing a backup. To perform a hot backup, backup just the query engine files as an incremental dump:

unix$ lx backup -i lxqe
backup...
host atlantis...

Incremental backups can be mixed for different components, as they overwrite some of the files saved in the full backup.

Create a full backup for just kvds100:

unix$ lx backup kvds100
backup...
host atlantis...
backup: /usr/local/leanxcale/dump/230720.3
unix$

Create an incremental backup adding just kvds200:

unix$ lx backup -i kvds200
backup...
host atlantis...
backup: /usr/local/leanxcale/dump/230720.3+
unix$

List the backups known:

unix$ lx backup -p
backup...
/usr/local/leanxcale/dump/230720
/usr/local/leanxcale/dump/230720.1
...

List the backups known for any kvds:

unix$ lx backup -p kvds

Restore the backup with the given name:

unix$ lx backup -r /usr/local/leanxcale/dump/230720.2

Here, if the name refers to an incremental backup, the restore recovers also the files found in previous incremental backups and in the total backup made before them.

Also, target directories to restore are identified by the current configuration of the system. That is, if kvds100 changed its location to a different host, the restore process will restore its disk at the new location, not at the location used to create the backup.

Restore just the files for kvds components from the given backup:

unix$ lx backup -r /usr/local/leanxcale/dump/230720.2  kvds

To restore a backup, it is usually desirable to format the disk for the involved components before using backup to restore their disks. The restore process copies restored files back, but does not remove anything else found on the disk for the component. For example:

unix$ lx fmt kvds
...
unix$ lx backup -r /usr/local/leanxcale/dump/230720.2  kvds

To remove a backup, it suffices to remove its directory. For example:

unix$ lx -d rm -rf dump/230720.2

Here we used the flag “-d” for lx to change to $LXDIR before executing the remove command, which makes it easy to name the directory used for the dump.

An important note is that file modification times are preserved in backup files. They are used to learn if a file must be copied or not in an incremental backup. If a backup is relocated to a different place, and later copied back into the standard location, preserve file modification times in the process.

Using flag -z makes the tool gzip backup files, preserving modification times despite compression.

1.5. lxbackup

Create, list, and restore backups from an external host:

usage: lxbackup [-h] [-n] [-v] [-D] [-i] [-d dir] [-r dir] [-p] [-f cfgfile] [-z]
                [what [what ...]]

lxbackup

positional arguments:
  what        host|comp

optional arguments:
  -h, --help  show this help message and exit
  -n          dry run
  -v          verbose
  -D          enable debug diags
  -i          incremental
  -d dir      root backup dir
  -r dir      backup dir to restore
  -p          print backup dirs
  -f cfgfile  config for the install
  -z          gzip backup files

This command can be copied along with the installed configuration to an external host, to perform external backups/restores. The external host must have ssh access to the installed hosts.

See lx backup for backups/restores on installed hosts.

Using lxbackup is exactly like using lx backup with a few differences:

  • Flag -f is mandatory and must be used to provide the installed configuration file.

  • The default backup directory is not $LXDIR/dump, but ./lxdump.

For example, create a full backup for just kvds100:

unix$ lxbackup -f lxinst.conf kvds100
backup...
host atlantis...
backup: lxdump/230720.3
unix$

The lxbackup command can be found at the installed $LXDIR/bin directory on any installed host. If you are not sure regarding the $LXDIR value, use this command to find it:

unix$ lx -d pwd
/usr/local/leanxcale
unix$

Flag -d for lx makes it change to the $LXDIR directory before running the given command.

The detailed configuration file to be used is created at lxinst.conf when installing. The configuration can be retrieved also by the lx config command. For example:

unix$ lx config -o lxinst.conf
saved lxinst.conf

Therefore, in the running example, we can setup an external host named orion to perform backups in this way:

unix$ lx -d pwd
/usr/local/leanxcale
unix$ lx config -o lxinst.conf
saved lxinst.conf
unix$ scp /usr/local/leanxcale/bin/lxbackup lxinst.conf orion:~

And then just:

orion$ lxbackup -f lxinst.conf
backup...
host atlantis...
backup: lxdump/230720
...
orion$

This was for a full (cold) system backup. To perform a hot backup create an incremental backup with the query engine files:

orion$ lxbackup -f lxinst.conf -i lxqe

Using flag -z in calls to lxbackup makes the tool gzip backup files, preserving modification times despite compression.

1.6. lx config

Inspect or update the configuration:

usage: config [-h] [-v] [-D] [-s value] [-d] [-n] [-o fname]
              [what [what ...]]

Inspect the configuration

positional arguments:
  what        kvaddr|grafana|cons|[host] [comp|prop...]

optional arguments:
  -h, --help  show this help message and exit
  -v          verbose
  -D          enable debug diags
  -s          set property values
  -d          delete
  -n          dry run
  -o fname    write the output to fname

By default, lx config prints the whole configuration, or that for elements given as arguments.

The arguments follow the conventional syntax used by most commands, but knows property names also:

  • Giving a host name narrows the rest of the arguments to that host, until another host name is given

  • Giving a component kind (e.g., lxqe) selects those components.

  • Giving a component name with included id (e.g., lxqe101) selects just that component

  • Giving a property name (not a host and not a component) selects just that property.

For example,

unix$ lx config

prints all configuration.

unix$ lx config atlantis mariner

prints the configuration for hosts atlantis and mariner (assuming those are configured host names).

unix$ lx config atlantis kvms mariner lxqe

prints the configuration for kvms components found at atlantis and lxqe components found at mariner

unix$ lxconfig kvms kvds101

prints the configuration for any kvms component and the kvds101 one.

unix$ lxconfig kvms addr

prints the addr attribute for any kvms component.

unix$ lxconfig awsdisk

prints the awsdisk property from the (global) configuration.

Use flag -o to save the configuration (or the parts selected) to the given file.

Use flag -d to remove the selected configuration entries. Do not remove hosts or components, and use this with caution.

Use flag -s to update the selected properties with new values. In this case, the argument for a property includes both its name and the new value (e.g., mem=50m)

For example:

unix$ lx config -s lxqe mem=500m kvds mem=500m

1.7. lx fmt

Format the whole DB or the indicated hosts or components:

usage: fmt [-h] [-D] [what ...]

fmt the store

positional arguments:
  what        host|comp...

options:
  -h, --help  show this help message and exit
  -D          enable debug diags

For example, format the kvds101 disk:

unix$ lx fmt kvds101

1.8. lx help

Ask for help:

usage: help [cmd]

Print usage information

Prints the list of known commands with quick usage information, or detailed usage information about the given command.

1.9. lx kvcon

This command provides access to the kv console:

unix$ lx kvcon usrs
owner: lxadmin
usr:    lxadmin *
    auth: <1e05 da1f 5696 d143 f9...c7d8 6de0 4cda 19f0 e3>
unix$

1.10. lx license

Checks the license status or installs a new license:

usage: license [-h] [-v] [-D] [-f file]

inspect or update license files.

optional arguments:
  -h, --help  show this help message and exit
  -v          verbose
  -D          enable debug diags
  -f file     license file to install

For example, ask for the current status:

unix$ lx license
    license expires: Mon Dec 30 00:00:00 2024

or install a new file lxlicense with the desired license:

unix$ lx license lxlicense

1.11. lx logs

List and inspect logs for installed components:

usage: logs [-h] [-D] [-g rexp] [-a] [-p] [-c dst] [-s start]
            [-e end] [what ...]

list logs

positional arguments:
  what        host|comp...

options:
  -h, --help  show this help message and exit
  -D          enable debug diags
  -g rexp     grep rexp
  -a          all logs, not the last one
  -p          print the last log (all if -a)
  -c dst      copy the last logs to this dir (all if -a)
  -s start    start fname time (yymmdd.hhmm or prefix)
  -e end      end fname time (yymmdd.hhmm or prefix)

For example, list the logs for kvds at atlantis, but only those after the time 230518.0551 (yymmdd.hhmm, or a prefix of this, can be used):

unix$ lx logs  -s 230518.0551 atlantis kvds

Print the last log for kvds101:

unix$ lx logs  -p kvds101

Grep all the logs for lines with fatal:

unix$ lx logs  -g fatal

Copy all (not just the last one) kvds101 logs to /tmp:

unix$ lx -a -c /tmp kvds101

1.12. lx printlog

Print the transaction log contents:

usage: printlog [-vh] [-s ts] [-e endts] dir|addr [qe]

The command prints the log contents for the given log directory (or file). With flag -v, it prints the logged kv message, otherwise it prints just the first line of each logged message.

With flag -h (or -v) it prints the header information too.

It is suggested not to use this on a running log, just in case the program modifies the logger (although that should not happen).

1.13. lx procs

List the processes for the DB:

usage: procs [-h] [-v] [-D] [-p] [what ...]

list processes

positional arguments:
  what        host|comp...

options:
  -h, --help  show this help message and exit
  -v          verbose
  -D          enable debug diags
  -p          report ports in use

For example, list the processes at host blade123:

unix$ lx procs blade123
procs...
blade123 [
	lxmeta100	pid 813750	alive running
	kvds100	pid 813734	alive running
	kvms100	pid 813729	alive
	kvds103	pid 813746	alive running
	kvds101	pid 813738	alive running
	spread	pid 813725	alive
	kvds102	pid 813742	alive running
	lxqe100	pid 813773	alive running
]

Or to see the port ustage status:

unix$ lx procs -p blade123
blade123 [
		spread	14444	busy
		kvms100	14400	busy
		lxmeta100	14410	idle
		lxqe100	14420	busy
		kvds100	14500	busy
		kvds101	14504	busy
		kvds102	14508	busy
		kvds103	14512	busy
]

1.14. lx report

Report system status and debug information.

usage: report [-h]

report system information for debugging

positional arguments:
  what        host|comp...

options:
  -h, --help  show this help message and exit
  -D          enable debug diags

This program collects information from the system and builds an archive to be sent to support.

unix$ lx report
report: lxreport.231009...
version...
procs...
logs...
stacks...
stack lxmeta100...
stack kvds103...
stack kvms100...
stack spread...
stack kvds102...
stack kvds100...
stack kvds101...
stack lxqe100...

# send this file to support.
-rw-rw-r-- 1 leandata leandata 54861 Oct  9 14:58 lxreport.231009.tgz

As printed by the command output, the resulting tar file should be sent to support.

The archive includes:

  • installed version numbers

  • underlying OS names are versions

  • complete disk usage for the installed systems

  • complete process list for the installed systems

  • memory usage for the installed systems

  • lx process list

  • logs for components (last log file only, for each one)

  • stacks for each component

  • stacks for each core file found

When kvms is still running, the archive includes also:

  • statistics for the sytem

  • long list of kv resources

  • process list for each kvds

  • file list for each kvds

1.15. lx run

Run a command on the selected installed hosts, using the lx environment to run it:

usage: run [-h] [-D] ...

run a command on the installed host(s).

positional arguments:
  what       host|comp... cmd...

options:
  -h, --help  show this help message and exit
  -D          enable debug diags

Arguments specify hosts where to run (as usual in the rest of commands), perhaps none (to imply all DB hosts), and then the keyword cmd must be given, followed by the command and arguments to run on each host.

For example, discover where this thing is installed:

unix$ lx run cmd pwd

Or, as an exceptional measure, kill all processes running:

unix$ lx run cmd killprocs

Or, kill just those at blade123:

unix$ lx run blade123 cmd killprocs

Or kill -9 any kvds at blade123:

unix$ lx run blade123 cmd killprocs -9 kvds

1.16. lx stack

Dump process stacks

usage: stack [-h] [-v] [-D] [-l] [what [what ...]]

print stacks

positional arguments:
  what        host|comp...

optional arguments:
  -h, --help  show this help message and exit
  -v          verbose
  -D          enable debug diags
  -l          local run only

The command understands the conventional syntax to select hosts and/or components. For example, to dump the stack of kvms components:

unix$ lx stack kvms
localhost [
	stack kvms100: [
		Thread 12 (Thread 0x7f8fc57fa700 (LWP 9272)):
		#0  __libc_read (nbytes=40, buf=0x7f8fa8000bd8, fd=13) at linux/read.c:26
		#1  __libc_read (fd=13, buf=0x7f8fa8000bd8, nbytes=40) at linux/read.c:24
		...
	]
]

With flag -v, local variables are printed too.

For java processes, both the native stack and the java stacks are printed.

1.17. lx start

Starts the DB for operation:

usage: start [-h] [-D] [-w] [what ...]

start the service

positional arguments:
  what        host|comp...

options:
  -h, --help  show this help message and exit
  -l          local run only
  -w          start watch

For example, to start the kvds components at host atlantis and leave the rest of the installation alone:

unix$ lx start atlantis kvds

With flag -w, start will run the watch service. This pings the DB to make sure it can answer queries, and, when that is not the case, try to stop and restart the system. See the Section 1.21 section for details.

1.18. lx status

Prints the status for the system or waits for a given status:

usage: status [-h] [-v] [-D] [-w status] [-t tout]

show or wait for a DB status

optional arguments:
  -h, --help  show this help message and exit
  -v          verbose
  -D          enable debug diags
  -w status   wait for the given status
  -t tout     timeout for -w (secs)

For example, to learn the status:

unix$ lx status
status: waiting
	kvds100: recovering files
	kvds101: recovering files

Or, to wait until the status is running:

unix$ lx status -v -w running
status: waiting
	kvds100: recovering files
	kvds101: recovering files
status: running
unix$

The status can be any of:

  • stopped: no process is running.

  • failed: some processes did fail.

  • waiting: processes are running but there is no SQL service.

  • running: processes are running and SQL connections are available.

1.19. lx stop

Halts the DB or stops individual hosts or components:

usage: stop [-h] [-D] [-w] [what ...]

stop the service

positional arguments:
  what        host|comp...

options:
  -h, --help  show this help message and exit
  -D          enable debug diags
  -w          do not stop watch

For example, halt the DB:

unix$ lx stop

Stop just the kvds servers:

unix$ lx stop kvds

If the watch service is running, make sure to stop it before stopping individual components. Otherwise it might decide to wait for lxmeta to stop and then restart the system.

Without arguments, stop will first stop the watch service and there is no extra caution needed.

Under flag -w, stop will not stop the watch process.

1.20. lx version

Print the installed version:

usage: version [-h]

print installed version

optional arguments:
  -h, --help  show this help message and exit

The program reports the leanXcale version name, along with detailed version information for distribution packages installed:

unix$ lx version
leanXcale v2.1
    kv         v2.1.2023-09-29.115f5fba70e3af8dc203953399088902c4534389
    QE         v2.1.2023-09-30.1e5933900582.16a7a5c3420cd3d5d589d1fa6cc
    libs       v2.1.2023-09-29.67535752acf19e092a6eaf17b11ad17597897956
    avatica    v2.1.2023-09-27.0b0a786b36e8bc7381fb2bb01bc8b3ed56f49172
    TM         v2.1.2023-09-29.9a9b22cfdc9b924dbc3430e613cddab4ed667a57
    lxlbins    v2.1.2023-09-29.79e7e04fb16b38d08c2d5df1fe08e103d49cb22a
    lxinst     v2.1.2023-10-02.b341e6545913aee8e0b0daf255362.173b33ea6d
    calcite    v2.1.2023-09-27.d3dfcf24285d38add3f4e29a9c2e9eacbcd0b913
    lxodata    v2.1.2023-09-23.b84fa4c7d2ca3e778edd9de29389b2aa6e1a9fb8

1.21. lx watch

Watch out the system and restart it if needed:

usage: watch [-h] [-v] [-D]

watch out the db and stop/start it if needed

optional arguments:
  -h, --help  show this help message and exit
  -v          verbose
  -D          enable debug diags

This program is started by lx start when the flag -w is given to it. It is usually a bad idea to execute this command explicitly.

It waits until the DB is running, doing nothing until that point. From that point on, if the DB ceases to be running, the program will wait for lxmeta to stop, and, then try to stop and start the whole system, and finally exit.

When restarting the system, the flag -w is used, to start a new watcher for the new system.

The implications are that a failure to start will not restart the system more times, and that stopping individual components requires to stop this program first, or it might take actions on its own.

1.22. killprocs

This is a command for local use only:

usage: killprocs [-h] [-9] [-a] [procs]

kill processes

Use lx run to run it at any/all of the installed hosts.

Without any flag, locates the DB process pids looking at the files reporting them, and then kills them.

With flag -a, locates any process in the system by process name (all the ones started by the DB use bin/…​ as a name), and all java processes starting with LX, and kills them.

A TERM signal is sent, and then a KILL signal after a few seconds.

Flag -9 can be used to send only a KILL signal.

If process/component names are given (eg, kvds, or lxqe100), only those processes are killed.

For example, send a kill signal to any kvds at blade123:

unix$ lx run blade123 cmd killprocs -9 kvds

2. Command Reference Manual at LeanXcale

This section details other the commands available and how to use them.

2.1. lxaws

The program lxaws is used to list or remove AWS installs, and to setup peering connections.

This program is not built as such. To create it, copy lxinst to lxaws and use it.

usage: lxaws [-h] [-e] [-v] [-d] [-D] [-r region] [-n] [-askpeer] [-yespeer]
             [-netpeer] [-delpeer]
             [tag [tag ...]]

lx AWS cmds

positional arguments:
  tag         aws tag|peer command args

optional arguments:
  -h, --help  show this help message and exit
  -e          define env vars
  -v          verbose
  -d          remove resources
  -D          enable debug diags
  -r region   AWS region
  -n          dry run
  -askpeer    ask peer: tag owner reg vpc
  -yespeer    accept peer:tag pcxid
  -netpeer    set peer net: tag pcxid cidr sec
  -delpeer    del peer: pcxid

For a detailed description with examples, refer to the section on AWS installs.

2.2. lx addcmd

Add the given file(s) to the bin directory of the installed hosts, to add or update a command in the installation:

usage: addcmd [-h] [-D] [-a host] [files ...]

add cmds to installed lx

positional arguments:
  files       files to add

options:
  -h, --help  show this help message and exit
  -D          enable debug diags
  -a host     copy to this installed host(s)

For example, update the stop command:

unix$ lx addcmd stop

2.3. lx web

This command is a web interface for the set of commands:

usage: web [-h] [-a addr] [-D] [usr pass]

leanXcale web interface

positional arguments:
  usr         [usr pass|usr del]

optional arguments:
  -h, --help  show this help message and exit
  -a addr     listen address
  -D          enable debug diags

When given two arguments, it adds the given user/passwd to the set of web users. To remove a user, use del as the passwd.

The web server is started by default on the port 5000 for the first host of the install.

Initially the user lxadmin with password lxadmin is defined, until users are added. Note that this user is just for web access, and it is not a DB user.

After supplying the user and password, access to a web page as shown in the figure is granted.

You can type commands in the input box and execute them by using Enter. The command output is shown in the yellow box.

Type help for help.

The set of available commands is the set of commands described in this document, although some are forbidden by the web interface itself. For example, on a terminal you may run:

unix$ lx procs

and therefore you may run procs as a command in the web interface.

image

Within the web interface, the command passwd usr pass can be used to define, or change, or remove a user (use del as the password).

The boxes on the right of the page show the components started. They are shown in blue if running correctly and red when they failed.

Log out of the page by pressing the button on the top-left of the page.

3. Configuration Reference Manual

This section provides a reference for the leanXcale configuration file.

Any property may be used as a global property (before any host declaration), as a host property (within a host declaration and before any component), or as a component property (within a component declaration).

Here, we describe properties grouped by their usual scope, for your convenience. But, note that instead of using mem or any other property within a component, it can be used globally to apply to all components, or within a host, to apply to such host.

3.1. Global properties

  • aws: Used as a global property, means that this is to install and start an AWS instance using the (only) configured host name (or lx1 by default).

  • awsdisk N: Used as a global property, fixes the disk size for the AWS AMI. 30 GiB by default.

  • awsregion name: Used as a global property, fixes the AWS used to create the installed AMIs.

  • awstype type: Used as a global property, defines the instance type, by default, m5.large.

  • cache: When specified, the query engine is enabled to handle in-memory table replicas. By default, it is disabled. E.g.:

    host blade124
        lxqe
            cache
  • docker: Used as a global property, makes the install adapt to docker install. In this case, starts and stops are handled by starting/stopping docker containers.

  • lxdir path: Directory used by the install. Components and hosts may override its value. Defaults to /usr/local/leanxcale. E.g.:

    lxdir $HOME/leanxcale
  • size [small|medium|large]: When used as global property selects heuristics to perform a small, medium, or large install. A large install is the default, using the whole machine. A small install tries to use few resources, and a medium install sits in the middle. Using flags -s and -m for lxinst adds this property with the corresponding size.

  • stats [only]: When used as a host property (in one host only), configures hosts to supply statistics and runs prometheus and grafana on this node to gather stats and report them. If the value is only, the host is used just for statistics and DB components use other configured hosts.

  • tls: When used as a global property, makes the installed system use TLS for network exchanges between clients and the installed system.

  • user name: User used by the install Eg:

    user nemo
  • LXLDAP uri: URI used to reach the LDAP server for authentication. System users must still be created for LDAP users to be granted access. Defining this property changes the authentication method only. User lxadmin is never authenticated using LDAP.

    LXLDAP	ldap://ldapsrv:389|simple|ou=People,dc=leanxcale,dc=com

3.2. Host properties

  • lxdir path: Directory used by the install in the host. E.g.:

    lxdir $HOME/xamplelx
  • addr address: Network address used (without port).

3.3. Component properties

  • addr address: Network address used. E.g.:

    host atlantis
        kvms
            addr atlantis!14000
  • disk N: Size for the disk used by the component, using M or G as units or assuming GiB by default. E.g.:

    host atlantis
        kvds
            disk 50
        lxqe
            disk 500m
  • mem N: Size for the memory used by the component, using M or G as units or assuming MiB by default. E.g.:

    host atlantis
        kvds
            mem 500
        lxqe
            mem 1g

3.4. Other properties

Properties with upper-case names are exported as environment variables for the process(es) executing the component involved. This includes both global properties and host properties as well. For example, to enable debug flags DOM for the kv datastore:

KVDEBUG DOM

These are other properties not described before.

  • mirror name: Defines a host as a mirror of the named host. Either all hosts must have mirrors or none of them can. (For command line arguments, the syntax is blade124+blade145). E.g.:

    host blade124
    host blade125
        mirror blade124
  • nodb: When specified as a host property, makes this host include just the lx command, but no DB component. E.g.:

    host atlantis
        nodb
  • scp template: Template for the scp command used to remotely copy files to a host. Use '{user}' and '{host}' where the user and host address should be included, and {src} ` and ` {dst} where the source and destination file names should be placed. E.g.:

    scp scp {src} {user}@{host}:{dst}
  • scpi template: Template for the (internal) scp command an installed host should use to reach other installed hosts. Use the same syntax described above. E.g.:

    scpi scp {src} {user}@{host}:{dst}
  • spread no|port: Port used by the spread process. Use no to disable it. E.g.:

    spread 4444
  • ssh template: Template for the ssh command used to execute remote commands on the host. Use {user}' and `{host} where the user and host names should be used. Eg.:

    ssh ssh -o StrictHostKeyChecking=no {user}@{host}
  • sshi template: Template for the (internal) ssh command an installed host should use to reach other installed hosts. Use the same syntax describe above. Eg.:

    sshi ssh -o StrictHostKeyChecking=no {user}@{host}
  • web [addr]: Run a web server as an interface for running Lx commands.