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:

  1. On the Downloads page, go to the SaltStack Enterprise: Manual installation section.
  2. Download all files listed needed for your specific operating system.
  3. 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:

  1. 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
    
  2. Update the pg_hba.conf file as needed to enable connections from your Enterprise API (RaaS) node. Optionally, enable SSL.

  3. 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:

  1. 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
    
  2. 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
    
  3. 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:

  1. 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.

  2. Install the packages or RPM signing keys needed by your operating system:

    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
    
  3. 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
    
  4. 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
    
  5. 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
    
  6. 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.

  7. In the RaaS service configuration file /etc/raas/raas, configure the location of your Redis server:

    redis:
      url: redis://<Redis_IP>:6379
    
  8. To store database credentials for both PostgreSQL and Redis in an encrypted file, run the following command:

    su - raas -c 'raas save_creds'
    
  9. 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.

  10. 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:

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