Merge pull request #363 from StackStorm/installer_changes

Add some security best practices notes to the docs

Author: Kami

docs/source/install/__installer_passwords.rst

@@ -0,0 +1,8 @@
+.. note::
+
+  For security reasons, installer script enables authentication and generates random passwords
+  for dependent services such as MongoDB and PostgreSQL.
+
+  If for some reason (e.g. debugging), you need to access those services directly you can find
+  passwords in the config files - ``/etc/st2/st2.conf`` for MongoDB and RabbitMQ password and
+  ``/etc/mistral/mistral.conf`` for PostgreSQL password.

docs/source/install/common/security_notes.rst

@@ -0,0 +1,46 @@
+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:
+
+* MongoDB - https://docs.mongodb.com/manual/tutorial/enable-authentication/, https://docs.mongodb.com/manual/core/authorization/
+* RabbitMQ - https://www.rabbitmq.com/authentication.html
+* PostgreSQL - https://www.postgresql.org/docs/9.4/static/auth-methods.html
+
+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``)
+
+2. 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 |st2| (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 |st2|
+components are running on multiple servers.

docs/source/install/deb.rst

@@ -12,6 +12,7 @@ the :doc:`Reference deployment </install/overview>`.
 
 System Requirements
 -------------------
+
 Please check :doc:`supported versions and system requirements <system_requirements>`.
 
 Minimal installation
@@ -58,7 +59,7 @@ The following script will detect your platform and architecture and setup the re
     curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.deb.sh | sudo bash
 
 Install |st2| components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~
 
   .. code-block:: bash
 
@@ -171,6 +172,7 @@ Check out :doc:`/reference/cli` to learn convenient ways to authenticate via CLI
 
 Install WebUI and setup SSL termination
 ---------------------------------------
+
 `NGINX <http://nginx.org/>`_ 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
@@ -279,8 +281,14 @@ If you already run a Hubot instance, you only have to install the `hubot-stackst
 
 * That's it! Go to your Chat room and begin ChatOpsing. Read more in the :doc:`/chatops/index` section.
 
+A Note on Security
+------------------
+
+.. include:: common/security_notes.rst
+
 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

docs/source/install/index.rst

@@ -42,6 +42,8 @@ Once it completes successfully, you will see the following output:
   Thanks for installing StackStorm! Come visit us in our Slack Channel
   and tell us how it's going. We'd love to hear from you!
 
+.. include:: __installer_passwords.rst
+
 .. rubric:: Installations
 
 .. toctree::
@@ -55,4 +57,3 @@ Once it completes successfully, you will see the following output:
     Brocade Workflow Composer <bwc>
     config/index
     upgrades
-

docs/source/install/rhel6.rst

@@ -12,6 +12,7 @@ the :doc:`Reference deployment </install/overview>`.
 
 System Requirements
 -------------------
+
 Please check :doc:`supported versions and system requirements <system_requirements>`.
 
 Minimal installation
@@ -111,7 +112,7 @@ Install MongoDB, RabbitMQ, and PostgreSQL.
 
 
 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.
 
@@ -120,7 +121,7 @@ The following script will detect your platform and architecture and setup the re
     curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.rpm.sh | sudo bash
 
 Install |st2| components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~
 
   .. code-block:: bash
 
@@ -227,10 +228,11 @@ To set up authentication with File Based provider:
     # Check that it works
     st2 action list
 
-Check out :doc:`/reference/cli` to learn convinient ways to authenticate via CLI.
+Check out :doc:`/reference/cli` to learn convenient ways to authenticate via CLI.
 
 Install WebUI and setup SSL termination
 ---------------------------------------
+
 `NGINX <http://nginx.org/>`_ 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
@@ -296,7 +298,6 @@ For example, to see the endpoint for getting actions, invoke
 
     st2 --debug action list
 
-
 Setup ChatOps
 -------------
 
@@ -351,8 +352,14 @@ If you already run Hubot instance, you only have to install the `hubot-stackstor
 
 * That's it! Go to your Chat room and begin ChatOps-ing. Read more in the :doc:`/chatops/index` section.
 
+A Note on Security
+------------------
+
+.. include:: common/security_notes.rst
+
 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

docs/source/install/rhel7.rst

@@ -12,6 +12,7 @@ the :doc:`Reference deployment </install/overview>`.
 
 System Requirements
 -------------------
+
 Please check :doc:`supported versions and system requirements <system_requirements>`.
 
 Minimal installation
@@ -91,7 +92,7 @@ Install MongoDB, RabbitMQ, and PostgreSQL.
     sudo systemctl enable postgresql
 
 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.
 
@@ -100,7 +101,7 @@ The following script will detect your platform and architecture and setup the re
     curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.rpm.sh | sudo bash
 
 Install |st2| components
-~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~
 
   .. code-block:: bash
 
@@ -120,6 +121,7 @@ Setup Mistral Database
 
 Configure SSH and SUDO
 ~~~~~~~~~~~~~~~~~~~~~~
+
 To run local and remote shell actions, |st2| 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.
 
@@ -202,10 +204,11 @@ To set up authentication with File Based provider:
     # Check that it works
     st2 action list
 
-Check out :doc:`/reference/cli` to learn convinient ways to authenticate via CLI.
+Check out :doc:`/reference/cli` to learn convenient ways to authenticate via CLI.
 
 Install WebUI and setup SSL termination
 ---------------------------------------
+
 `NGINX <http://nginx.org/>`_ 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
@@ -270,7 +273,6 @@ For example, to see the endpoint for getting actions, invoke
 
     st2 --debug action list
 
-
 Setup ChatOps
 -------------
 
@@ -324,8 +326,14 @@ If you already run Hubot instance, you only have to install the `hubot-stackstor
 
 * That's it! Go to your Chat room and begin ChatOps-ing. Read more in the :doc:`/chatops/index` section.
 
+A Note on Security
+------------------
+
+.. include:: common/security_notes.rst
+
 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