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
andjemalloc
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:
Download and install the
Python3.5
andlibpython3.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:
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 thesql
configuration to provide the host and port created in the previous section. If you plan to use SSL, setssl
toTrue
and see the next step for additional details.sql: dialect: postgresql host: localhost port: 5432 driver: psycopg2 ssl: false
If you set
ssl
toTrue
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 newssl_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 whenssl
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 ofsslrootcert
, if present, to validate the server’s SSL certificate. Or ifsslrootcert
is not present, use the system certificate store to validate the server’s SSL certificate.verify-full
- Use the contents ofsslrootcert
, if present, to validate the server’s SSL certificate. Or ifsslrootcert
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.