Merge "Install guide Basic Env. to RST"

doc/install-guide-rst/source/basic_environment.rst

@@ -4,10 +4,10 @@ Basic environment
 
 .. note::
 
-    The draft version of this guide focuses on the future Liberty
+   The draft version of this guide focuses on the future Liberty
-    release and will not work for the current Kilo release. If you want
+   release and will not work for the current Kilo release. If you want
-    to install Kilo, you must use the `Kilo
+   to install Kilo, you must use the `Kilo
-    version <http://docs.openstack.org>`__ of this guide instead.
+   version <http://docs.openstack.org>`__ of this guide instead.
 
 This chapter explains how to configure each node in the
 :ref:`overview-example-architectures`,
@@ -18,30 +18,40 @@ and three-node architecture with OpenStack Networking
 
 .. note::
 
-    Although most environments include Identity, Image service, Compute,
+   Although most environments include Identity, Image service, Compute,
-    at least one networking service, and the dashboard, the Object
+   at least one networking service, and the dashboard, the Object
-    Storage service can operate independently. If your use case only
+   Storage service can operate independently. If your use case only
-    involves Object Storage, you can skip to :ref:`swift` after
+   involves Object Storage, you can skip to :ref:`swift` after
-    configuring the appropriate nodes for it. However, the dashboard requires at
+   configuring the appropriate nodes for it. However, the dashboard requires at
-    least the Image service and Compute.
+   least the Image service and Compute.
 
 .. note::
 
-    You must use an account with administrative privileges to configure
+   You must use an account with administrative privileges to configure
-    each node. Either run the commands as the ``root`` user or configure
+   each node. Either run the commands as the ``root`` user or configure
-    the ``sudo`` utility.
+   the ``sudo`` utility.
 
 .. note::
 
-    The :command:`systemctl enable` call on openSUSE outputs a warning message
+   The :command:`systemctl enable` call on openSUSE outputs a warning message
-    when the service uses SysV Init scripts instead of native systemd
+   when the service uses SysV Init scripts instead of native systemd
-    files. This warning can be ignored.
+   files. This warning can be ignored.
 
-    .. TODO(karenb)
+
-       section_basics-prerequisites.xml
+.. include:: basics-security.rst
-       section_basics-security.xml
+.. include:: basics-database.rst
-       section_basics-networking.xml
+.. include:: basics-queue.rst
-       section_basics-ntp.xml
+
-       section_basics-packages.xml
+.. toctree::
-       section_basics-database.xml
+   :hidden:
-       section_basics-queue.xml
+
+   basics-security.rst
+   basics-database.rst
+   basics-queue.rst
+
+
+.. TODO(karenb)
+   section_basics-prerequisites.xml
+   section_basics-networking.xml
+   section_basics-ntp.xml
+   section_basics-packages.xml

doc/install-guide-rst/source/basics-database.rst

@@ -0,0 +1,150 @@
+.. highlight:: ini
+   :linenothreshold: 1
+
+
+SQL database
+~~~~~~~~~~~~
+
+Most OpenStack services use an SQL database to store information. The
+database typically runs on the controller node. The procedures in this
+guide use MariaDB or MySQL depending on the distribution. OpenStack
+services also support other SQL databases including
+`PostgreSQL <http://www.postgresql.org/>`__.
+
+
+**To install and configure the database server**
+
+1. Install the packages:
+
+   .. only:: rdo or ubuntu or obs
+
+      .. note::
+
+         The Python MySQL library is compatible with MariaDB.
+
+   .. only:: ubuntu
+
+      .. code-block:: console
+
+         # apt-get install mariadb-server python-mysqldb
+
+   .. only:: debian
+
+      .. code-block:: console
+
+         # apt-get install mysql-server python-mysqldb
+
+   .. only:: rdo
+
+      .. code-block:: console
+
+         # yum install mariadb mariadb-server MySQL-python
+
+   .. only:: obs
+
+      .. code-block:: console
+
+         # zypper install mariadb-client mariadb python-mysql
+
+.. only:: ubuntu or debian
+
+   2. Choose a suitable password for the database root account.
+
+   3. Create and edit the :file:`/etc/mysql/conf.d/mysqld_openstack.cnf` file
+      and complete the following actions:
+
+      - In the ``[mysqld]`` section, set the
+        ``bind-address`` key to the management IP
+        address of the controller node to enable access by other
+        nodes via the management network:
+
+        .. code:: ini
+
+           [mysqld]
+           ...
+           bind-address = 10.0.0.11
+
+      - In the ``[mysqld]`` section, set the following keys to enable
+        useful options and the UTF-8 character set:
+
+        .. code:: ini
+
+           [mysqld]
+           ...
+           default-storage-engine = innodb
+           innodb_file_per_table
+           collation-server = utf8_general_ci
+           init-connect = 'SET NAMES utf8'
+           character-set-server = utf8
+
+
+.. only:: obs or rdo
+
+   2. Create and edit the :file:`/etc/my.cnf.d/mariadb_openstack.cnf` file
+      and complete the following actions:
+
+      - In the ``[mysqld]`` section, set the
+        ``bind-address`` key to the management IP
+        address of the controller node to enable access by other
+        nodes via the management network:
+
+        .. code:: ini
+
+           [mysqld]
+           ...
+           bind-address = 10.0.0.11
+
+      - In the ``[mysqld]`` section, set the following keys to enable
+        useful options and the UTF-8 character set:
+
+        .. code:: ini
+
+           [mysqld]
+           ...
+           default-storage-engine = innodb
+           innodb_file_per_table
+           collation-server = utf8_general_ci
+           init-connect = 'SET NAMES utf8'
+           character-set-server = utf8
+
+**To finalize installation**
+
+.. only:: ubuntu or debian
+
+   1. Restart the database service:
+
+      .. code-block:: console
+
+         # service mysql restart
+
+.. only:: rdo or obs
+
+   1. Start the database service and configure it to start when the system
+      boots:
+
+      .. only:: rdo
+
+         .. code-block:: console
+
+            # systemctl enable mariadb.service
+            # systemctl start mariadb.service
+
+      .. only:: obs
+
+         .. code-block:: console
+
+            # systemctl enable mysql.service
+            # systemctl start mysql.service
+
+.. only:: ubuntu or debian
+
+   2. Secure the database service:
+
+      .. literalinclude:: mariadb_output.txt
+
+.. only:: rdo or obs
+
+   2. Secure the database service including choosing a suitable
+      password for the root account:
+
+      .. literalinclude:: mariadb_output.txt

doc/install-guide-rst/source/basics-queue.rst

@@ -0,0 +1,67 @@
+Message queue
+~~~~~~~~~~~~~
+
+OpenStack uses a message queue to coordinate operations and status
+information among services. The message queue service typically runs on
+the controller node. OpenStack supports several message queue services
+including `RabbitMQ <http://www.rabbitmq.com>`__,
+`Qpid <http://qpid.apache.org>`__, and `ZeroMQ <http://zeromq.org>`__.
+However, most distributions that package OpenStack support a particular
+message queue service. This guide implements the RabbitMQ message queue
+service because most distributions support it. If you prefer to
+implement a different message queue service, consult the documentation
+associated with it.
+
+**To install the message queue service**
+
+* Install the package:
+
+  .. only:: ubuntu or debian
+
+     .. code-block:: console
+
+        # apt-get install rabbitmq-server
+
+  .. only:: rdo
+
+     .. code-block:: console
+
+        # yum install rabbitmq-server
+
+  .. only:: obs
+
+     .. code-block:: console
+
+        # zypper install rabbitmq-server
+
+
+**To configure the message queue service**
+
+#. Start the message queue service and configure it to start when the
+   system boots:
+
+   .. only:: rdo or obs
+
+      .. code-block:: console
+
+         # systemctl enable rabbitmq-server.service
+         # systemctl start rabbitmq-server.service
+
+#. Add the ``openstack`` user:
+
+   .. code-block:: console
+
+      # rabbitmqctl add_user openstack `RABBIT_PASS`
+        Creating user "openstack" ...
+        ...done.
+
+   Replace `RABBIT_PASS` with a suitable password.
+
+#. Permit configuration, write, and read access for the
+   ``openstack`` user:
+
+   .. code-block:: console
+
+      # rabbitmqctl set_permissions openstack ".*" ".*" ".*"
+        Setting permissions for user "openstack" in vhost "/" ...
+        ...done.

doc/install-guide-rst/source/basics-security.rst

@@ -0,0 +1,94 @@
+Security
+~~~~~~~~
+
+OpenStack services support various security methods including password,
+policy, and encryption. Additionally, supporting services including the
+database server and message broker support at least password security.
+
+To ease the installation process, this guide only covers password
+security where applicable. You can create secure passwords manually,
+generate them using a tool such as
+`pwgen <http://sourceforge.net/projects/pwgen/>`__, or by running the
+following command:
+
+.. code-block:: console
+
+   $ openssl rand -hex 10
+
+For OpenStack services, this guide uses `SERVICE_PASS` to reference
+service account passwords and `SERVICE_DBPASS` to reference database
+passwords.
+
+The following table provides a list of services that require passwords
+and their associated references in the guide:
+
+.. list-table:: **Passwords**
+   :widths: 50 60
+   :header-rows: 1
+
+   * - Password name
+     - Description
+   * - Database password (no variable used)
+     - Root password for the database
+   * - `ADMIN_PASS`
+     - Password of user ``admin``
+   * - `CEILOMETER_DBPASS`
+     - Database password for the Telemetry service
+   * - `CEILOMETER_PASS`
+     - Password of Telemetry service user ``ceilometer``
+   * - `CINDER_DBPASS`
+     - Database password for the Block Storage service
+   * - `CINDER_PASS`
+     - Password of Block Storage service user ``cinder``
+   * - `DASH_DBPASS`
+     - Database password for the dashboard
+   * - `DEMO_PASS`
+     - Password of user ``demo``
+   * - `GLANCE_DBPASS`
+     - Database password for Image service
+   * - `GLANCE_PASS`
+     - Password of Image service user ``glance``
+   * - `HEAT_DBPASS`
+     - Database password for the Orchestration service
+   * - `HEAT_DOMAIN_PASS`
+     - Password of Orchestration domain
+   * - `HEAT_PASS`
+     - Password of Orchestration service user ``heat``
+   * - `KEYSTONE_DBPASS`
+     - Database password of Identity service
+   * - `NEUTRON_DBPASS`
+     - Database password for the Networking service
+   * - `NEUTRON_PASS`
+     - Password of Networking service user ``neutron``
+   * - `NOVA_DBPASS`
+     - Database password for Compute service
+   * - `NOVA_PASS`
+     - Password of Compute service user ``nova``
+   * - `RABBIT_PASS`
+     - Password of user guest of RabbitMQ
+   * - `SAHARA_DBPASS`
+     - Database password of Data processing service
+   * - `SWIFT_PASS`
+     - Password of Object Storage service user ``swift``
+   * - `TROVE_DBPASS`
+     - Database password of Database service
+   * - `TROVE_PASS`
+     - Password of Database service user ``trove``
+
+|
+
+OpenStack and supporting services require administrative privileges
+during installation and operation. In some cases, services perform
+modifications to the host that can interfere with deployment automation
+tools such as Ansible, Chef, and Puppet. For example, some OpenStack
+services add a root wrapper to ``sudo`` that can interfere with security
+policies. See the `Cloud Administrator
+Guide <http://docs.openstack.org/admin-guide-cloud/content/root-wrap-reference.html>`__
+for more information.
+
+Also, the Networking service assumes default
+values for kernel network parameters and modifies firewall rules. To
+avoid most issues during your initial installation, we recommend using a
+stock deployment of a supported distribution on your hosts. However, if
+you choose to automate deployment of your hosts, review the
+configuration and policies applied to them before proceeding further.

doc/install-guide-rst/source/mariadb_output.txt

@@ -0,0 +1,64 @@
+   # mysql_secure_installation
+   NOTE: RUNNING ALL PARTS OF THIS SCRIPT IS RECOMMENDED FOR ALL
+         MariaDB SERVERS IN PRODUCTION USE!
+         PLEASE READ EACH STEP CAREFULLY!
+
+   In order to log into MariaDB to secure it, we'll need the
+   current password for the root user.  If you've just installed
+   MariaDB, and you haven't set the root password yet, the
+   password will be blank, so you should just press enter here.
+
+   Enter current password for root (enter for none):
+   OK, successfully used password, moving on...
+
+   Setting the root password ensures that nobody can log into the
+   MariaDB root user without the proper authorisation.
+
+   Set root password? [Y/n] Y
+   New password:
+   Re-enter new password:
+   Password updated successfully!
+   Reloading privilege tables..
+   ... Success!
+
+
+   By default, a MariaDB installation has an anonymous user,
+   allowing anyone to log into MariaDB without having to have a
+   user account created for them.  This is intended only for
+   testing, and to make the installation go a bit smoother.
+   You should remove them before moving into a production
+   environment.
+
+   Remove anonymous users? [Y/n] Y
+   ... Success!
+
+   Normally, root should only be allowed to connect from
+   'localhost'. This ensures that someone cannot guess at the
+   root password from the network.
+
+   Disallow root login remotely? [Y/n] Y
+   ... Success!
+
+   By default, MariaDB comes with a database named 'test' that
+   anyone can access.  This is also intended only for testing,
+   and should be removed before moving into a production
+   environment.
+
+   Remove test database and access to it? [Y/n] Y
+   - Dropping test database...
+     ... Success!
+   - Removing privileges on test database...
+     ... Success!
+
+   Reloading the privilege tables will ensure that all changes
+   made so far will take effect immediately.
+
+   Reload privilege tables now? [Y/n] Y
+   ... Success!
+
+   Cleaning up...
+
+   All done!  If you've completed all of the above steps, your
+   MariaDB installation should now be secure.
+
+   Thanks for using MariaDB!