Manual installation¶

Overview¶

This page explains how to install SaltStack Enterprise manually as an alternative to either the Single-node installation or the Multi-node installation scenarios. The manual installation method supports installation on the following operating systems:

RedHat or CentOS (recommended)
SUSE 12
SUSE 15

Danger

Manual installation is not recommended. These steps are included for your reference if you would like to understand every procedure that is taken when using the installer or running an installation scenario using one of the standard installation scenarios.

These instructions are intended for advanced users who need granular control over the installation process, and who are familiar with PostgreSQL and Redis database configuration. You are strongly encouraged to use one of the standard installation scenarios instead.

The steps below are confirmed for a standalone deployment of SaltStack Enterprise (where all related services reside on a single host). Advanced users will likely adapt these instructions to their deployment. If you are not an advanced user, use the standard installation scenarios instead or consider using consulting services. To begin the standard installation process, see Installation overview.

Note

SaltStack Enterprise supports SLES 12. However, be aware that as of June 2020, SLES 12 SP4 has reached end of General Support from SUSE. Consider upgrading to SLES 15, contacting your database administrator, or contacting SUSE support for further assistance. For more information about supported distributions, see SUSE Product Support Lifecycle.

Download manual installation files¶

To download the files for upgrading:

On the Downloads page, go to the SaltStack Enterprise: Manual installation section.
Download all files listed needed for your specific operating system.
Verify the files. For specific instructions, see Verify the installation files.

After you’ve downloaded the files, proceed to the next section.

Import key files¶

To import the .asc keyfiles in the .zip file into the RPM packaging system on the machines where you intend to install SaltStack Enterprise components, run:

rpmkeys --import *.asc

After the key files have been imported, proceed to the next section.

PostgreSQL database installation and configuration¶

To install and configure the PostgreSQL database:

Install PostgreSQL using the following commands:

sudo wget https://download.postgresql.org/pub/repos/yum/12/redhat/rhel-7.12-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo yum install pgdg-*.noarch.rpm
sudo yum update
sudo yum -y install postgresql12-server postgresql12-contrib
/usr/pgsql-12/bin/postgresql-12-setup initdb

As of June 2020, the package to install PostgreSQL for SLES 12 SP4 is no longer available at the Open SUSE downloads center. Consider upgrading to SLES 15, contacting your database administrator, or contacting SUSE support for further assistance.

zypper addrepo https://download.opensuse.org/repositories/server:/database:/postgresql/SLE_15_SP1/server:database:postgresql.repo
zypper refresh
# install PostgreSQL 12
zypper install postgresql12-server
zypper install postgresql12-contrib
# init the db by starting and stopping the postgresql service
systemctl start postgresql
systemctl stop postgresql

Update the pg_hba.conf file as needed to enable connections from your Enterprise API (RaaS) node. Optionally, enable SSL.

Start PostgreSQL and create a database account for the Enterprise API (RaaS) node. For example:

systemctl enable postgresql-12
systemctl start postgresql-12
sudo su - postgres -c 'createuser -s -P salt_eapi'
# This account has Superuser privileges so that
# various extensions my be installed.
# After initial deployment the Superuser privilege
# may be removed.

systemctl start postgresql
su - postgres -c 'createuser -d -P -s root'

systemctl start postgresql
su - postgres -c 'createuser -d -P -s root'

After installing and configuring PostgreSQL, proceed to the next section.

Redis installation and configuration¶

To install and configure the Redis database:

Install Redis using the following commands:

Install the Redis and jemalloc installation packages you downloaded from the Downloads page. Use the following commands, replacing the exact file names:

sudo yum install redis-filename.rpm jemalloc-filename.rpm

zypper addrepo https://download.opensuse.org/repositories/server:/database/SLE_12_SP4/server:database.repo
zypper refresh
zypper install redis

zypper addrepo https://download.opensuse.org/repositories/server:/database/SLE_15/server:database.repo
zypper refresh
zypper in redis

Start the Redis service, using the following commands:

sudo systemctl enable redis
sudo systemctl start redis

# Start the Redis service
$ redis-server
# Start Redis in the background
$ redis-server --daemonize yes

You can use the following optional commands to ensure Redis is running as intended:

# Check if Redis is already running; will return PONG if running
redis-cli ping
# Stop the Redis service
redis-cli shutdown

# Start the Redis service
$ redis-server
# Start Redis in the background
$ redis-server --daemonize yes

You can use the following optional commands to ensure Redis is running as intended:

# Check if Redis is already running; will return PONG if running
redis-cli ping
# Stop the Redis service
redis-cli shutdown

OPTIONAL: If you are setting up Redis on a host that is separate from the Enterprise API (RaaS) node, you need to configure Redis to accept remote connections and to limit access using a password. To do this, update the /etc/redis.conf file, specifying the bind parameter and setting the password that your Enterprise API (RaaS) nodes should use to authenticate.
```
bind 0.0.0.0
requirepass {{ your_redis_password }}
```

After installing and configuring Redis, proceed to the next section.

Enterprise API (RaaS) installation and configuration¶

To install and configure the Enterprise API (RaaS) node:

FOR SLES 15 INSTALLATIONS ONLY: Install the xmlsec1 package. Without this dependency, a SLES 15 installation may fail. To download the package and read installation documentation, see xmlsec1.
Install the packages or RPM signing keys needed by your operating system:
RHEL

SLES 12

SLES 15
Download and install the Python3.5 and libpython3.5 installation packages for RH/CentOS that are provided in the Downloads page. Use the following command, replacing the exact file names:
sudo yum install python35u-libs-filename.rpm python35u-filename.rpm
Import the RPM signing key using the following command:
rpm --import http://repo.saltstack.com/py3/redhat/7.7/x86_64/latest/SALTSTACK-GPG-KEY.pub
Import the RPM signing key using the following command:
rpm --import http://repo.saltstack.com/py3/redhat/7.7/x86_64/latest/SALTSTACK-GPG-KEY.pub
Download and install the RPM for your operating system:
RHEL

SLES 12

SLES 15
Download and install the Red Hat/CentOS SaltStack Enterprise RPM, replacing the exact file name:
sudo yum install raas-<version>-0.el7.x86_64.rpm
Download and install the SLES 12 RPM, replacing the exact file name:
zypper install raas-<version>-0.sles12.x86_64.rpm
Download and install the SLES 15 RPM, replacing the exact file name:
zypper in raas-<version>-0.sles15.x86_64.rpm
In the RaaS service configuration file /etc/raas/raas, update the sql configuration to provide the host and port created in the previous section. If you plan to use SSL, set ssl to True and see the next step for additional details.
```
sql:
  dialect: postgresql
  host: localhost
  port: 5432
  driver: psycopg2
  ssl: false
```

If you set ssl to True in the previous step, you’ve enabled an SSL connection, but additional information is required to verify the server’s SSL certificate. To configure certificate verification, in /etc/raas/raas, add a new ssl_opts key and provide values as follows:

Option	Description
`sslmode`	Choose the mode for your SSL connection from one of the following: `disable` - Use only cleartext connections. This value is used when `ssl` is set to False. `prefer` - Use SSL but fallback to cleartext if SSL is not available. `require` - Use an SSL connection but do not attempt to verify the server’s certificate. `verify-ca` - Use the contents of `sslrootcert`, if present, to validate the server’s SSL certificate. Or if `sslrootcert` is not present, use the system certificate store to validate the server’s SSL certificate. `verify-full` - Use the contents of `sslrootcert`, if present, to validate the server’s SSL certificate. Or if `sslrootcert` is not present, use the system certificate store to validate the server’s SSL certificate. `verify-full` requires that the hostname in the certificate match the hostname SaltStack Enterprise uses when connecting. For more on these settings, see the PostgreSQL documentation.
`sslrootcert`	Location on the Enterprise API (RaaS) filesystem of the CA certificate to use if a self-signed certificate is in place on the PostgreSQL server
`sslcert`	Location of the client certificate on the Enterprise API (RaaS) server to use instead of username and password to connect to PostgreSQL
`sslkey`	Location of the key file that goes along with the client certificate referenced in `sslcert`

For more in-depth information about these options, see the PostgreSQL documentation: Client Verification of Server Certificates, as well as the following example configurations.

Example 1

The first example shows a configuration set to full verification. This means that the certificate PostgreSQL presents to SaltStack Enterprise is validated against the Certificate Authority certificate specified in the file path/to/CA_Certificate. Furthermore, the Common Name in the SaltStack Enterprise certificate must match the hostname SaltStack Enterprise is using for PostgreSQL.

sql:
  ssl: True
  ssl_opts:
    sslmode: verify-full
    sslrootcert: path/to/CA_certificate

Example 2

The second example enables SSL communication without certificate validation, and authenticates the user that the Enterprise API (RaaS) uses to connect to PostgreSQL via client SSL certificate.

sql:
  ssl: True
  ssl_opts:
    sslmode: require
    sslcert: path/to/Client_Certificate
    sslkey: path/to/Key_for_Client_Certificate

In the RaaS service configuration file /etc/raas/raas, define options for background workers:
```
background_workers:
  combined_process: True
  max_tasks: 100000
  max_memory: 1048576
```
Note

SaltStack Enterprise includes a range of different background worker settings to improve performance for various deployment scenarios. For more information, see Improve system performance.
In the RaaS service configuration file /etc/raas/raas, configure the location of your Redis server:
```
redis:
  url: redis://<Redis_IP>:6379
```
To store database credentials for both PostgreSQL and Redis in an encrypted file, run the following command:
```
su - raas -c 'raas save_creds'
```
Follow the prompts to set up your username and password for Redis and PostgreSQL. If you would prefer to leave those values blank, press the Enter key when prompted. The credentials are stored in /etc/raas/raas.secconf.

Note

If credentials appear in both /etc/raas/raas and /etc/raas/raas.secconf, the settings in the plaintext /etc/raas/raas take precedence.

For more on securing credentials, see Securing credentials in your SaltStack Enterprise configuration.
Enable the RaaS service at system startup and launch the service using the following commands:

sudo systemctl enable raas
sudo systemctl start raas

The manual installation process is now complete.

Next steps¶

Once the manual installation process is complete, you must complete several post-installation steps:

Install the license key
Log in for the first time and change default credentials
Set up SSL certificates
SaltStack Comply configuration (optional)
SaltStack Protect configuration (optional)
Set up Single Sign-On (SSO) (optional)

The first post-installation step is to install the license key. To begin the next post-installation step, see Install the license key.