Note

The documentation you're currently reading is for version 2.3.2. Click here to view documentation for the latest stable version.

RHEL 6 / CentOS 6

If you’re just looking for a quick “one-liner” installation, check the top-level install guide. If you need a customised installation, use this guide for step-by step instructions for installing BWC on a single RHEL 6/CentOS 6 64 bit system as per the Reference deployment.

Note

Use the Source, Luke! We strive to keep the documentation current, but the best way to find out what really happens is to look at the code of the installer script.

Minimal Installation

Install libffi-devel Package

RHEL 6 may not ship with libffi-devel which is a dependency for BWC. If that is the case, set up the server-optional repository, following instructions at https://access.redhat.com/solutions/265523. Or, find a version of libffi-devel compatible with libffi on the box, and install this version of libffi-devel`. For example:

[ec2-user@ip-172-30-0-79 ~]$ rpm -qa libffi
libffi-3.0.5-3.2.el6.x86_64

sudo yum localinstall -y ftp://fr2.rpmfind.net/linux/centos/6/os/x86_64/Packages/libffi-devel-3.0.5-3.2.el6.x86_64.rpm

Adjust SELinux Policies

If your RHEL/CentOS box has SELinux in Enforcing mode, please follow these instructions to adjust SELinux policies. This is needed for successful installation. If you are not happy with these policies, you may want to tweak them according to your security practices.

  • Check if SELinux is enforcing:

    getenforce
    
  • If previous command returns ‘Enforcing’, then run the following commands to adjust SELinux policies:

    # SELINUX management tools, not available for some minimal installations
    sudo yum install -y policycoreutils-python
    
    # Allow network access for nginx
    sudo setsebool -P httpd_can_network_connect 1
    

    Note

    If you see messages like “SELinux: Could not downgrade policy file”, it means you are trying to adjust policy configurations when SELinux is disabled. You can ignore this error.

Install Dependencies

Note

The currently preferred and supported version of MongoDB is 3.2. This is the version installed by the installer script. MongoDB 3.4 is supported in StackStorm v2.2.0 and above. Older versions of StackStorm (prior to v1.6.0) only supported MongoDB 2.x.

Install MongoDB, RabbitMQ, and PostgreSQL.

sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm

# Add key and repo for the latest stable MongoDB (3.2)
sudo rpm --import https://www.mongodb.org/static/pgp/server-3.2.asc
sudo sh -c "cat <<EOT > /etc/yum.repos.d/mongodb-org-3.2.repo
[mongodb-org-3.2]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/6Server/mongodb-org/3.2/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-3.2.asc
EOT"

sudo yum -y install mongodb-org
sudo yum -y install rabbitmq-server
sudo service mongod start
sudo service rabbitmq-server start
sudo chkconfig mongod on
sudo chkconfig rabbitmq-server on

# Install and configure postgres 9.4. Based on the OS type, install the ``redhat`` one or ``centos`` one.
# RHEL:
if grep -q "Red Hat" /etc/redhat-release; then sudo yum -y localinstall http://yum.postgresql.org/9.4/redhat/rhel-6-x86_64/pgdg-redhat94-9.4-2.noarch.rpm; fi

# CentOS:
if grep -q "CentOS" /etc/redhat-release; then sudo yum -y localinstall http://yum.postgresql.org/9.4/redhat/rhel-6-x86_64/pgdg-centos94-9.4-2.noarch.rpm; fi

sudo yum -y install postgresql94-server postgresql94-contrib postgresql94-devel

# Setup postgresql for the first time
sudo service postgresql-9.4 initdb

# Make localhost connections to use an MD5-encrypted password for authentication
sudo sed -i "s/\(host.*all.*all.*127.0.0.1\/32.*\)ident/\1md5/" /var/lib/pgsql/9.4/data/pg_hba.conf
sudo sed -i "s/\(host.*all.*all.*::1\/128.*\)ident/\1md5/" /var/lib/pgsql/9.4/data/pg_hba.conf

# Start PostgreSQL service
sudo service postgresql-9.4 start
sudo chkconfig postgresql-9.4 on

Setup Repositories

The following script will detect your platform and architecture and setup the repo accordingly. It’ll also install the GPG key for repo signing.

curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.rpm.sh | sudo bash

Install BWC Components

sudo yum install -y st2 st2mistral

If you are not running RabbitMQ, MongoDB or PostgreSQL on the same box, or changed defaults, please adjust the settings:

  • RabbitMQ connection at /etc/st2/st2.conf and /etc/mistral/mistral.conf
  • MongoDB at /etc/st2/st2.conf
  • PostgreSQL at /etc/mistral/mistral.conf

Setup Datastore Encryption

The Key-value store allows users to store encrypted values (secrets). These are stored using symmetric encryption (AES256). To generate a crypto key, run:

DATASTORE_ENCRYPTION_KEYS_DIRECTORY="/etc/st2/keys"
DATASTORE_ENCRYPTION_KEY_PATH="${DATASTORE_ENCRYPTION_KEYS_DIRECTORY}/datastore_key.json"

sudo mkdir -p ${DATASTORE_ENCRYPTION_KEYS_DIRECTORY}
sudo st2-generate-symmetric-crypto-key --key-path ${DATASTORE_ENCRYPTION_KEY_PATH}

# Make sure only st2 user can read the file
sudo usermod -a -G st2 st2
sudo chgrp st2 ${DATASTORE_ENCRYPTION_KEYS_DIRECTORY}
sudo chmod o-r ${DATASTORE_ENCRYPTION_KEYS_DIRECTORY}
sudo chgrp st2 ${DATASTORE_ENCRYPTION_KEY_PATH}
sudo chmod o-r ${DATASTORE_ENCRYPTION_KEY_PATH}

# set path to the key file in the config
sudo crudini --set /etc/st2/st2.conf keyvalue encryption_key_path ${DATASTORE_ENCRYPTION_KEY_PATH}

sudo st2ctl restart-component st2api

Setup Mistral Database

# Create Mistral DB in PostgreSQL
cat << EHD | sudo -u postgres psql
CREATE ROLE mistral WITH CREATEDB LOGIN ENCRYPTED PASSWORD 'StackStorm';
CREATE DATABASE mistral OWNER mistral;
EHD

# Setup Mistral DB tables, etc.
/opt/stackstorm/mistral/bin/mistral-db-manage --config-file /etc/mistral/mistral.conf upgrade head
# Register mistral actions
/opt/stackstorm/mistral/bin/mistral-db-manage --config-file /etc/mistral/mistral.conf populate

Configure SSH and SUDO

To run local and remote shell actions, BWC uses a special system user (default stanley). For remote Linux actions, SSH is used. It is advised to configure identity file based SSH access on all remote hosts. We also recommend configuring SSH access to localhost for running examples and testing.

  • Create BWC system user, enable passwordless sudo, and set up ssh access to “localhost” so that SSH-based action can be tried and tested locally. You will need elevated privileges to do this.
# Create an SSH system user (default `stanley` user may already exist)
sudo useradd stanley
sudo mkdir -p /home/stanley/.ssh
sudo chmod 0700 /home/stanley/.ssh

# Generate ssh keys
sudo ssh-keygen -f /home/stanley/.ssh/stanley_rsa -P ""

# Authorize key-based access
sudo sh -c 'cat /home/stanley/.ssh/stanley_rsa.pub >> /home/stanley/.ssh/authorized_keys'
sudo chown -R stanley:stanley /home/stanley/.ssh

# Enable passwordless sudo
sudo sh -c 'echo "stanley    ALL=(ALL)       NOPASSWD: SETENV: ALL" >> /etc/sudoers.d/st2'
sudo chmod 0440 /etc/sudoers.d/st2

# Make sure `Defaults requiretty` is disabled in `/etc/sudoers`
sudo sed -i -r "s/^Defaults\s+\+?requiretty/# Defaults +requiretty/g" /etc/sudoers
  • Configure SSH access and enable passwordless sudo on the remote hosts which BWC would control over SSH. Use the public key generated in the previous step; follow instructions at Configure SSH. To control Windows boxes, configure access for Windows runners.
  • Adjust configuration in /etc/st2/st2.conf if you are using a different user or path to the key:
[system_user]
user = stanley
ssh_key_file = /home/stanley/.ssh/stanley_rsa

Start Services

  • Start services

    sudo st2ctl start
    
  • Register sensors, rules and actions

    sudo st2ctl reload
    

Verify

st2 --version

st2 -h

# List the actions from a 'core' pack
st2 action list --pack=core

# Run a local shell command
st2 run core.local -- date -R

# See the execution results
st2 execution list

# Fire a remote comand via SSH (Requires passwordless SSH)
st2 run core.remote hosts='localhost' -- uname -a

# Install a pack
st2 run packs.install packs=st2

Use the supervisor script to manage BWC services:

st2ctl start|stop|status|restart|restart-component|reload|clean

At this point you have a minimal working installation, and can happily play with BWC: follow Quick Start tutorial, deploy examples, explore and install packs from StackStorm Exchange.

But there is no joy without WebUI, no security without SSL termination, no fun without ChatOps, and no money without Brocade Workflow Composer. Read on, move on!


Configure Authentication

The reference deployment uses File Based auth provider for simplicity. Refer to Authentication to configure and use PAM or LDAP authentication backends.

Note

When using pam authentication backend you need to make sure that the st2auth process runs as root system user otherwise the authentication will fail. For security reasons st2auth process runs under st2 user by default. If you want to use pam auth backend and change it to run as root, you can do that by editing the service manager file for the st2 auth service.

To set up authentication with File Based provider:

  • Create a user with a password:

    # Install htpasswd utility if you don't have it
    sudo yum -y install httpd-tools
    # Create a user record in a password file.
    sudo htpasswd -bs /etc/st2/htpasswd st2admin 'Ch@ngeMe'
    
  • Enable and configure auth in /etc/st2/st2.conf:

    [auth]
    # ...
    enabled = True
    backend = flat_file
    backend_kwargs = {"file_path": "/etc/st2/htpasswd"}
    # ...
    
  • Restart the st2api service:

    sudo st2ctl restart-component st2api
    
  • Authenticate, export the token for st2 CLI, and check that it works:

    # Get an auth token and use in CLI or API
    st2 auth st2admin
    
    # A shortcut to authenticate and export the token
    export ST2_AUTH_TOKEN=$(st2 auth st2admin -p 'Ch@ngeMe' -t)
    
    # Check that it works
    st2 action list
    

Check out CLI Reference to learn convenient ways to authenticate via CLI.

Install WebUI and Setup SSL Termination

NGINX is used to serve WebUI static files, redirect HTTP to HTTPS, provide SSL termination for HTTPS, and reverse-proxy st2auth and st2api API endpoints. To set it up: install st2web and nginx, generate certificates or place your existing certificates under /etc/ssl/st2, and configure nginx with BWC‘s supplied site config file st2.conf.

BWC depends on Nginx version >=1.7.5; since RHEL6 has an older version in the package repositories at the time of writing, you will have to include the official Nginx repository into the list:

# Add key and repo for the latest stable nginx
sudo rpm --import http://nginx.org/keys/nginx_signing.key
sudo sh -c "cat <<EOT > /etc/yum.repos.d/nginx.repo
[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/rhel/6/x86_64/
gpgcheck=1
enabled=1
EOT"

# Install st2web and nginx
sudo yum -y install st2web nginx

# Generate self-signed certificate or place your existing certificate under /etc/ssl/st2
sudo mkdir -p /etc/ssl/st2

sudo openssl req -x509 -newkey rsa:2048 -keyout /etc/ssl/st2/st2.key -out /etc/ssl/st2/st2.crt \
-days 365 -nodes -subj "/C=US/ST=California/L=Palo Alto/O=StackStorm/OU=Information \
Technology/CN=$(hostname)"

# Copy and enable the supplied nginx config file
sudo cp /usr/share/doc/st2/conf/nginx/st2.conf /etc/nginx/conf.d/

# Disable default_server configuration in existing /etc/nginx/nginx.conf
sudo sed -i 's/default_server//g' /etc/nginx/conf.d/default.conf

sudo service nginx restart
sudo chkconfig nginx on

If you modify ports, or url paths in the nginx configuration, make the corresponding changes in st2web configuration at /opt/stackstorm/static/webui/config.js.

Use your browser to connect to https://${ST2_HOSTNAME} and login to the WebUI.

If you are trying to access the API from outside the box and you have configured nginx according to these instructions, use https://${EXTERNAL_IP}/api/v1/${REST_ENDPOINT}.

For example:

curl -X GET -H  'Connection: keep-alive' -H  'User-Agent: manual/curl' -H  'Accept-Encoding: gzip, deflate' -H  'Accept: */*' -H  'X-Auth-Token: <YOUR_TOKEN>' https://1.2.3.4/api/v1/actions

Similarly, you can connect to auth REST endpoints with https://${EXTERNAL_IP}/auth/v1/${AUTH_ENDPOINT}.

You can see the actual REST endpoint for a resource in BWC by adding a --debug option to the CLI command for the appropriate resource.

For example, to see the endpoint for getting actions, invoke

st2 --debug action list

Setup ChatOps

If you already run a Hubot instance, you only have to install the hubot-stackstorm plugin and configure BWC env variables, as described below. Otherwise, the easiest way to enable StackStorm ChatOps is to use the st2chatops package.

  • Validate that chatops pack is installed, and a notification rule is enabled:

    # Ensure chatops pack is in place
    ls /opt/stackstorm/packs/chatops
    # Create notification rule if not yet enabled
    st2 rule get chatops.notify || st2 rule create /opt/stackstorm/packs/chatops/rules/notify_hubot.yaml
    
  • Add NodeJS v4 repository:

    curl -sL https://rpm.nodesource.com/setup_4.x | sudo -E bash -
    
  • Install st2chatops package:

    sudo yum install -y st2chatops
    
  • Review and edit the /opt/stackstorm/chatops/st2chatops.env configuration file to point it to your BWC installation and Chat Service you are using. At a minimum, you should generate an API key <authentication-apikeys> and set the ST2_API_KEY variable. By default st2api and st2auth are expected to be on the same host. If that is not the case, please update the ST2_API and ST2_AUTH_URL variables or just point to the correct host with ST2_HOSTNAME.

    The example configuration uses Slack. To set this up, go to the Slack web admin interface, create a Bot, and copy the authentication token into HUBOT_SLACK_TOKEN.

    If you are using a different Chat Service, set corresponding environment variables under Chat service adapter settings: Slack, HipChat, Yammer, Flowdock, IRC , XMPP.

  • Start the service:

    sudo service st2chatops start
    
    # Starting st2chatops on boot
    sudo chkconfig st2chatops on
    
  • Reload st2 packs to make sure chatops.notify rule is registered:

    sudo st2ctl reload --register-all
    
  • That’s it! Go to your Chat room and begin ChatOps-ing. Read more in the ChatOps section.

A Note on Security

By default when dependent services such as MongoDB, RabbitMQ and PostgreSQL are installed, they have authentication disabled or use a default static password. As such, after you install those services you should configure them and enable authentication with strong randomly generated passwords.

Configuring authorization and passwords for those services is out of the scope for this documentation. For more information refer to the links below:

After you enable authentication for those components, you will also need to configure StackStorm services so they can talk to them.

This means editing the following configuration options:

  1. StackStorm config - /etc/st2/st2.conf
  • database.username - MongoDB database username.
  • database.password - MongoDB database password.
  • messaging.url - RabbitMQ transport url (amqp://<username>:<password>@<hostname>:5672)
  1. Mistral config - /etc/mistral/mistral.conf
  • database.connection - PostgreSQL database connection string (postgresql://<username>:<password>@<hostname>/mistral)
  • transport_url - RabbitMQ transport url (rabbit://<username>:<password>@<hostname>:5672)

In addition, you are strongly encouraged to follow these best practices for running network services:

  • Ensure communication between services is encrypted. Enable SSL / TLS for all the services - MongoDB, RabbitMQ, PostgreSQL.
  • Configure services to only listen on localhost, and where needed, internal IP addresses. There is usually no need for most services which are used by BWC (MongoDB, RabbitMQ, PostgreSQL) to be available to the public and listen on an external (public) IP address.
  • Configure a firewall and set up a whitelist. You should set up a firewall and only allow services and users which need access to the services to be able to access them. API and auth service usually need to be accessible to your users, but other dependent services such as MongoDB, RabbitMQ and PostgreSQL aren’t. These should not be directly accessible by users, and only StackStorm components should be allowed to talk to them.
  • Where possible and available, you should also utilize additional network-based isolation and security features such as DMZs.

The steps mentioned above are especially important for distributed production deployments where BWC components are running on multiple servers.

Upgrade to Brocade Workflow Composer

Brocade Workflow Composer is deployed as an addition on top of StackStorm. You will need an active Brocade Workflow Composer subscription, and a license key to access Brocade Workflow Composer repositories. To add your license key, replace ${BWC_LICENSE_KEY} in the command below with the key you received when registering or purchasing.

# Set up Brocade Workflow Composer repository access
curl -s https://${BWC_LICENSE_KEY}:@packagecloud.io/install/repositories/StackStorm/enterprise/script.rpm.sh | sudo bash
# Install Brocade Workflow Composer
sudo yum install -y bwc-enterprise

To learn more about Brocade Workflow Composer, request a quote, or get an evaluation license go to stackstorm.com/product.