diff --git a/doc/install-guide-rst/source/basic_environment.rst b/doc/install-guide-rst/source/basic_environment.rst index f25c1a389e..499bee3ead 100644 --- a/doc/install-guide-rst/source/basic_environment.rst +++ b/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 - release and will not work for the current Kilo release. If you want - to install Kilo, you must use the `Kilo - version `__ of this guide instead. + The draft version of this guide focuses on the future Liberty + release and will not work for the current Kilo release. If you want + to install Kilo, you must use the `Kilo + version `__ 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, - at least one networking service, and the dashboard, the Object - Storage service can operate independently. If your use case only - involves Object Storage, you can skip to :ref:`swift` after - configuring the appropriate nodes for it. However, the dashboard requires at - least the Image service and Compute. + Although most environments include Identity, Image service, Compute, + at least one networking service, and the dashboard, the Object + Storage service can operate independently. If your use case only + involves Object Storage, you can skip to :ref:`swift` after + configuring the appropriate nodes for it. However, the dashboard requires at + least the Image service and Compute. .. note:: - You must use an account with administrative privileges to configure - each node. Either run the commands as the ``root`` user or configure - the ``sudo`` utility. + You must use an account with administrative privileges to configure + each node. Either run the commands as the ``root`` user or configure + the ``sudo`` utility. .. note:: - The :command:`systemctl enable` call on openSUSE outputs a warning message - when the service uses SysV Init scripts instead of native systemd - files. This warning can be ignored. + The :command:`systemctl enable` call on openSUSE outputs a warning message + when the service uses SysV Init scripts instead of native systemd + files. This warning can be ignored. - .. TODO(karenb) - section_basics-prerequisites.xml - section_basics-security.xml - section_basics-networking.xml - section_basics-ntp.xml - section_basics-packages.xml - section_basics-database.xml - section_basics-queue.xml + +.. include:: basics-security.rst +.. include:: basics-database.rst +.. include:: basics-queue.rst + +.. toctree:: + :hidden: + + 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 diff --git a/doc/install-guide-rst/source/basics-database.rst b/doc/install-guide-rst/source/basics-database.rst new file mode 100644 index 0000000000..6393eced61 --- /dev/null +++ b/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 `__. + + +**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 diff --git a/doc/install-guide-rst/source/basics-queue.rst b/doc/install-guide-rst/source/basics-queue.rst new file mode 100644 index 0000000000..587260394b --- /dev/null +++ b/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 `__, +`Qpid `__, and `ZeroMQ `__. +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. diff --git a/doc/install-guide-rst/source/basics-security.rst b/doc/install-guide-rst/source/basics-security.rst new file mode 100644 index 0000000000..f7a954c5c1 --- /dev/null +++ b/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 `__, 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 `__ +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. diff --git a/doc/install-guide-rst/source/mariadb_output.txt b/doc/install-guide-rst/source/mariadb_output.txt new file mode 100644 index 0000000000..cf829a07d0 --- /dev/null +++ b/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!