Installation Guide

Before installing, it is important to know that LeanXcale has a distributed architecture and it consists of several components:

There are other components used by the system, that are not relevant for the user and are not described here. For example, spread is a communication bus used by LeanXcale components.

The components listen on the following network ports:

Never install or run leanXcale as root.

To install, you need:

The install program itself requires a unix system with python 3.7 (or later).

Your sales representative will provide you with a valid license file. In case you have any issues with it, please send an email to sales@leanxcale.com.

The LeanXcale zip distribution can be found at:

There is a zip file per version. Download the latest version.

If needed, install the required software dependencies on your system:

Here, and in what follows, unix$ is the system prompt used in commands and examples.

Working on the directory where the distribution has been downloaded, unzip the LeanXcale zipped distribution:

Here, you type the command after the unix$ prompt, and the following lines are an example of the expected output.

Verify that the process completed successfully and there is a directory lxdist (with the distribution packages) and the lxinst program:

To install, run the lxinst program and, as an option, supply the name of the installation directory (/usr/local/leanxcale by default):

The command takes the zipped LeanXcale distribution from ./lxdist, and installs it at the target folder.

The detailed configuration file built by the install process is saved at lxinst.conf, as a reference.

The database has users. The user lxadmin is the administrator for the whole system and during the install you are asked to provide its password.

To complete the install, a license must be added, as explained in the next section.

As another example, this installs at the given partition /dev/sdc2, with both encryption and compression, mounting the installed system at /usr/local/leanxcale:

The final messages printed by the install program will remind you of how to list or remove the installed file systems.

The installation creates the lx command. Use it to execute commands to operate the installed system.

At the end of the installation, the install program prints suggestions for adjusting the PATH variable so that lx will be available as any other command. For example, as done with:

when the install directory is /usr/local/leanxcale.

The lx command can be found at the bin directory in the install directory. For example, at /usr/local/leanxcale/bin/lx when installing at /usr/local/leanxcale.

In what follows, we assume that lx can be found using the system PATH.

The first command used is usually the one to install a license file:

It is also possible to put the license file at ~/.lxlicense, and the install process will find it and install it on the target system(s).

To install at multiple hosts, you may indicate target host names and install paths in the command line, like in the following example:

or simply provide the target hostnames:

When using a configuration file, simply define multiple hosts:

and use such file to install:

To specify a number of components we can still use the command line, like in:

or

…​ # xample.conf host atlantis kvds x 2 host mariner kvds x 2 …​

For high availability (HA), it is possible to install using replicated components. As a convenience, replication is configured using mirror hosts where a host can be installed as a mirror of another to replicate its components. Either all hosts must have mirrors, or none of them.

To install using mirrors, for high availability, combine host names in the command line using “+”, like in:

or in

This configures mariner as a mirror for atlantis. Either all hosts must have mirrors, or none of them.

When using a configuration file, use the mirror property to specify that a host is a mirror for another. In our example:

…​ # xample.conf host atlantis kvds x 2 host mariner mirror atlantis …​

The mirror host should not specify anything other than its mirror property. It takes its configuration from the mirrored host.

When a preinstalled leanXcale docker image is available, disregard this section and proceed as described in the next one.

This section explains how to create containers from leanXcale images and how to install licenses and change the lxadmin password for them.

Provided the leanXcale image named lx:2, and the docker network lxnet, this command runs a leanXcale docker container:

In this command, the container name is lx1, the network used lxnext, and the image used lx:2. The port redirection -p…​ exports the SQL port to the underlying host.

It is important to know that:

The container name (lx1) can be used to issue commands. For example, this removes the container after stopping it:

The installed container includes the lx command. Use it to execute commands to operate the installed DB system.

It is possible to attach to the container and use the ''lx'' command as it can be done on a bare metal host install:

Here, we type docker attach lx1 on the host, and lx version on the docker container prompt.

Note that if you terminate the shell reached when attaching the docker container, it will stop. Usually, this is not desired.

It is possible to execute commands directly on the executed container. For example:

executes lx version on the container.

AWS installs creates a systemd system service for leanXcale. The service is installed as a disabled service.

This is meant to be used only for single host installs.

When multiple instances are used, instances must be started before using lx start to start the system, and lx stop must be used to stop the system before stopping the instances.

This section is here as a reference, and also because it might be useful on single-host installs.

For example:

In this case, and the rest of this section, we use commands running on the installed AWS instance.

To enable the service, we can:

To disable it again:

To start the service by hand:

And now we can see its status:

The DB status should now be as follows:

When more than a single instance is installed, the service must be enabled, disabled, started, and/or stopped on all instances involved.

Note that enabling the service makes the DB start when the instance starts, and stop before the instance stops.

This is done by each instance on its own. At start time, the instance runs

and at stop time, the instance runs

The last start and stop output is saved at /usr/local/leanxcale/log/start.log, for inspection.

It might be more convenient to leave the service disabled and, after starting the instances for the install, use lx start command to start the system.

The program lxaws is used to list or remove AWS installs, and to start and stop instances and find their status.

Given a region, without any tags, it lists the tags installed:

Given a tag, it lists the tag resources as found on AWS:

It is also possible to supply just the base tag without the domain, as in

With flag -e prints commands to set environment variables with resources found, as an aid to run other scripts.

When more than one tag is asked for, or more than one instance/volume is found, variable names are made unique adding a number to the name, for example:

With flag -d, it removes the resources for the tags given. In this case, tags must be given explicitly in the command line.

To list, open, and close ports exported by the AWS install to the rest of the world, use lxaws flags -p (print ports), -o (open ports), and -c (close ports).

In all cases, the first argument is the tag for the install. The tag can be just the AWS install tag name, without .aws.leanxcale.com.

For example, this command lists the open ports:

Here, the protocol and port (or port range) is printed for each set of open ports. The CIDR printed shows the IP address range that can access the ports, and is 0.0.0.0/0 when anyone can access them.

Before with each port range, the name for the open port range is printed. This name is set by the default install, and can be set when opening ports as shown next.

To open a port range, use -o and give as arguments the tag for the install, the protocol, first and last port in range, the CIDR (or any if open to everyone), and a name to identify why this port range is open (no spaces). For example:

The new port will be shown as open if we ask for ports:

As another example:

To close a port, use -c and give as arguments the tag for the install, the protocol, a port within the range of interest, and the CIDR used to export the port. Note that any can be used here too instead of the CIDR 0.0.0.0/0 For example:

Here, we used the -v flag (verbose) to see what is going on.

As another example, this can be used to close the open port range 8888-10000 from the example above:

To find out the instance statuses for a given AWS tag, use the -status flag for lxaws:

With just a tag name, it lists the instances for the given tag name.

Supplying extra arguments with a host name, IP, or instance ID, lists just the status for the given instances.

Flags -start and -stop in lxaws can be used to start/stop instances. Their use is similar to that of the -status flag. Given a tag, all instances are started/stopped. Given a tag and a host (or more hosts), matching instances are started/stopped.

For example:

Note that this does not start/stop the DB in the instances. The command just starts/stops the instances.

Once instances are started, connect to one of them and use lx start to start the DB.

before stopping, connect to one of the instances and use lx stop to stop the DB before stopping the instances.

Peering connections can be used to bridge two VPCs at AWS.

One peer asks the other peer to accept a peering connection, the peer accepts the connection, and network routes and security group rules for access are configured.

Peering connections are handled using lxaws with the peering connection flags. If you do not have lxaws, copy lxinst to a file named lxaws and give it execution permissions.

These are the flags for peering connections:

To request a peering connection, supply as arguments

For example:

Here, we could have used xample.aws.leanxcale.com instead. The command prints the peering connection identifier, to be used for setting up networking and asking the peer administrator to accept the peering request.

To accept a peer request, supply as an argument the peering connection id, as in:

In either case, once the dialed peer accepts the request, networking must be set supplying as arguments

For example:

Our local CIDR block is 10.0.120.0/24. This must be given to the peer, so the peer system can setup routing for this block to our network, along with the VPC id and our security group id.

This information can be retrieved using lxaws as described in the previous section. For example:

Should it be necessary, the CIDR block used by the install can be set when installing the system (but not later), using the property awsnet, as in

Note that only the network address bytes used are given, instead of using 10.0.120.0/24.

Once done with a peering connection, it can be dismantled supplying both the tag and the peering connection identifier. The identifier is always given because, when accepting a peering request, the peering connection does not belong to us. But, using the command above you can retrieve such identifier easily.

When peering is no longer desired, the peering connection can be removed.

Removing the peering connection also removes the routing entries for it and the security group access rules added when it was setup.

By default, lxinst installs components to exploit the machine(s) used for the install.

It is possible to perform small installs using flag -s like in

And, it is possible to perform medium size installs using flag -m, as in

A small install limits the number of kvds to 4, and per-component memory to 1GiB.

A medium install limits the number of kvds to 8, but does not limit per-component memory and tries to use the default allocation policy.

Installs are configured using a file that describes the hosts and components installed. The file may include properties for the whole installation, or for individual hosts and components.

To perform custom installations, use a configuration file. You can fine-tune your installation in order to adapt the default installation to your needs, resources, and requirements.

The configuration file describes hosts and components installed.

To install using a configuration file, use the lxinst flag -f to use it, as in:

The configuration file has an initial section describing global properties, then a series of hosts each one including a series of properties and a series of components with properties.

The file consists of plain text lines. The character # can be used to add comments (the rest of the line is ignored). Each line declares a property, perhaps with a value, or starts a host or component declaration.

Lines declaring hosts start with host, those declaring components start with a component type name. All other lines declare properties.

A host configuration starts using the host keyword and the name for the host (which usually is the host name used to reach the host on the network). It is recommended to use the host name instead of using localhost.

A property is declared with a single line with the property name, then blanks, and then the property value. If the property has no value, it is considered as a boolean and it is set to true.

Properties declared before the first host declaration are global, and may be overridden later by properties defined within a host or component.

All declarations after a host declaration are defined for that host, until another host declaration is found.

All properties defined a component declaration, before another one is declared, are defined for that component.

Those required components and properties not specified by the user are added by the install program with default values.

Variables HOME and USER may be used when defining properties. The variable LXDIR may be used as well and refers to the install (or disk) directory for the host or component.

A component may be repeated adding the option x N to specify how many instances are wanted. When not used, each component declared stands for a single component, but many of the same type can be added for components like kvds.

For docker installs, specify docker before the first host.

For example, when installing at the host named atlantis, this can be a configuration file:

In this file, the property lxdir (leanXcale install directory) is defined as a global property, and applies to all hosts defined.

Then, a single host (atlantis) is defined. When no host is configured, localhost is used as the default.

For the configured host, two of the required components are configured:

Note that components required (e.g. lxmeta) but not specified are added by the install program itself.

For a docker installation, specify docker and try not to specify specific paths or hostnames for the installed system. For example:

The installer has a default memory split allocation among components. To specify the memory size for the lxqe and kvds components we can include them in the configuration file and include the mem attribute for them, as done here:

It is suggested not to use more memory in total than the physical memory available on the system (minus the one used by the operating system and leaving a small amount unused for safety).

We suggest to give half the memory to the lxqe component and the other half to all the kvds components (evenly distributed).

Note that by default the install tries to use available memory, unless a small or medium install was selected.

To specify the maximum disk size for the disk usage, specify it for the components using a significant space on disk (most notably kvds for table storage, and lxqe for the transactional log). For example:

LeanXcale provides TLS 1.3. By default, communication between client processes and the DB service are not encrypted, for speed. This may be reasonable when the machine(s) involved are controlled by the installer and the network used is secure (e.g., an VPN already encrypting the packets exchanged).

For installs where the queries are performed from the internet or from an insecure network, leanXcale can be installed to use always TLS in communications between the query engine(s) and the DB client processes.

Just set the global tls property when installing.

Note this can be done also without using a configuration file. For example, like in

The SQL console for the installed system will use TLS in its connections. Other clients must use the tls=yes property in the connection to ask the client driver to use TLS.

Users defined in the DB correspond to schemas and must be created before they can be used.

When not using LDAP, authentication is performed using the credentials given when users are created.

To authenticate users using LDAP, define the LXLDAP property in the configuration file. This can be done globally or as a host property. For example,

arranges for the system to authenticate user (other than lxadmin) using the given LDAP server and properties.

Note that before LDAP users can use leanXcale, a DB user must be created for them, with the LDAP uid as their name.

To use UNIX PAM as authentication, define the LXPAM property as yes. This authenticates the DB users using PAM.

Recent Linux systems should include unix_chkpwd(8) to allow applications to check UNIX passwords without access to the /etc/shadow file. Otherwise, the user running the system must be a member of the shadow group or be able to read /etc/shadow.

Note that running as root is not an option. In fact, most systems would check the user id and prevent this from working, if implemented correctly.

If MFA is to be used with PAM, the Google authenticator PAM module must be installed on the system running the DB:

The database uses PAM service lxmfa to verify authenticator codes. Add a new PAM configuration file /etc/pam.d/lxmfa, with the following contents

Finally, define the LXUSEMFA property as yes:

Each user must then create an authenticator key (if not already done) as described in the LeanXcale User’s Guide.

LeanXcale uses AES256 GCM for encrypting the storage. To compress and/or encrypt the disk data, define the compress and/or the crypt properties as yes or no. Or define them without a value, meaning yes.

To use this, bare-metal installs require using a partition for installing. It will be setup with a ZFS file system using the compression and encryption settings required.

For AWS installs, it suffices to define the compress and/or the crypt properties, and it is neither needed nor permitted to specify a disk partition for the install. Also, the default in AWS is to compress but not encrypt, unlike in bare metal installs, where the default is neither to compress nor to encrypt.

For example, this configuration installs using /dev/sdc2 with both compression and encryption, mounting the installed partition at /usr/local/leanxcale (the default lxdir):

Note that compress and crypt properties might be defined for each host instead of being set globally for all the installation.

It is possible to achieve the same effect from the command line without creating a configuration file:

The final messages printed by the install program remind you of how to list or remove the installed file systems. For example, this can be used to list the file systems created and their settings:

Beware that destroying the installed file systems also removes all the data.

The network address (including port) used by the query engine to listen for client connections is 14420. To use another port, specify the network address for the lxqe component:

But it may be easier to move the base port address used to a range other than 14000. This can be done defining the global (or host) property baseport, as done here:

Refer to the [LeanXcale Components and Ports] section for more details regarding network port usage.

To install optional components, specify them in the configuration file. It is customary to add them on the first host installed. For example:

adds both stats and odata to the installation. As they are optional components, they are never installed by default.

The OpenDATA port is usually 14004 unless configured otherwise.

The default user and password for the stats web page is lxadmin.

Here we provide more details on configuration files.

This property defines the directory used by the install, and relies on the HOME environment variable on each host involved:

To use a host just for stats, without any DB component, use only as the value for the stats property:

To include a web interface in your install, add web as a property for the host. The server port is 5000. For example:

In some cases it is desirable to install one host with just the lx command, to operate the rest of the hosts installed (perhaps just during the install process). For example, when installing from a laptop and wanting to have the lx command installed at the laptop to operate a set of hosts being installed.

This can be done adding the nodb attribute to a host. For example:

Specific ssh and scp commands may be given to reach the installed hosts. Should the installed hosts use different ssh and scp command to reach each other, properties sshi and scpi can be used to given them.

This is an example:

In all configurations, when installing multiple lxqe components, each lxqe keeps a mirror for the transaction log of another one.

The default configuration assigns mirrors from different hosts, and, when not possible, from the same host.

If the number of lxqe components is odd, one of them will not have a mirror, and this is not often the wanted configuration.

This applies only when host replication is not used. This is described next.

Hosts may be replicated, but either all hosts must have replicas or none of them. To define a replica for a host, add another host and define mirror for it using the replicated host name as the property value. For example:

configures a system with two replicated hosts. That is, four hosts where two ones are a mirror of the other two ones.

In replicated configurations, the set of initial hosts is designated as the first replica (or replica-1) and the mirror hosts are known as the second replica.

Component names in this case include a final .r1 or .r2 to reflect the replica they belong to. For example, kvds100.r1 is likely to be a component in this configuration.

When using a configuration file, just define the property aws before anything. You can specify the region, instance type, disk size, and AWS tag. The disk size is in GiB. The tag is a string and should not include blanks.

For example, using this file:

you can run:

This can be done also using the command line:

The partition mounted at /usr/local/leanxcale for the DB storage is 30GiB by default. You can change this using the aswdisk property. It is formatted using a compressed ZFS.

In the installed system, the user running the DB is lx, and LeanXcale is added to the UNIX system as a standard (disabled) systemd service. The instance is left running. You can stop it on your own if that is not desired.

To install multiple instances, install using multiple host names:

By default, private IP addresses for hosts are in 10.0.120.0/24. To use a different network, keep 10.0 and pick your own 3rd byte as in

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:

These are other properties not described before.