You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by pd...@apache.org on 2015/03/07 17:36:10 UTC
[7/8] cloudstack-docs-install git commit: rename installation.rst,
update install link to split files
rename installation.rst, update install link to split files
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/commit/673b4c2d
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/tree/673b4c2d
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/diff/673b4c2d
Branch: refs/heads/master
Commit: 673b4c2d545c29426d543d29a97b1207b740af6e
Parents: ba4e01e
Author: Pierre-Luc Dion <pd...@apache.org>
Authored: Sat Mar 7 11:27:48 2015 -0500
Committer: Pierre-Luc Dion <pd...@apache.org>
Committed: Sat Mar 7 11:27:48 2015 -0500
----------------------------------------------------------------------
source/index.rst | 12 +-
source/installation.rst | 1236 ------------------------------------------
2 files changed, 7 insertions(+), 1241 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/blob/673b4c2d/source/index.rst
----------------------------------------------------------------------
diff --git a/source/index.rst b/source/index.rst
index 854807f..718987e 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -72,8 +72,8 @@ Quick Installation Guide
qig
-.. _steps:
+.. _steps:
Source Installation
-------------------
@@ -82,18 +82,19 @@ Source Installation
building_from_source
-.. _installation:
+.. _installation:
General Installation
--------------------
.. toctree::
:maxdepth: 2
- installation
+ overview/index
+ management-server/index
-.. _configuration:
+.. _configuration:
Configuration
-------------
@@ -102,8 +103,8 @@ Configuration
configuration
-.. _hypervisors:
+.. _hypervisors:
Hypervisor Setup
----------------
@@ -140,5 +141,6 @@ Optional Installation
:maxdepth: 2
optional_installation
+ encryption
.. include:: _global.rst
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/blob/673b4c2d/source/installation.rst
----------------------------------------------------------------------
diff --git a/source/installation.rst b/source/installation.rst
deleted file mode 100644
index bd75cd2..0000000
--- a/source/installation.rst
+++ /dev/null
@@ -1,1236 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information#
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
- http://www.apache.org/licenses/LICENSE-2.0
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-
-Installation
-============
-
-Who Should Read This
---------------------
-
-For those who have already gone through a design phase and planned a
-more sophisticated deployment, or those who are ready to start scaling
-up a trial installation. With the following procedures, you can start
-using the more powerful features of CloudStack, such as advanced VLAN
-networking, high availability, additional network elements such as load
-balancers and firewalls, and support for multiple hypervisors including
-Citrix XenServer, KVM, and VMware vSphere.
-
-
-Overview of Installation Steps
-------------------------------
-
-For anything more than a simple trial installation, you will need
-guidance for a variety of configuration choices. It is strongly
-recommended that you read the following:
-
-- Choosing a Deployment Architecture
-
-- Choosing a Hypervisor: Supported Features
-
-- Network Setup
-
-- Storage Setup
-
-- Best Practices
-
-#. Make sure you have the required hardware ready.
- See :ref:`minimum-system-requirements`
-
-#. Install the Management Server (choose single-node or multi-node).
- See :ref:`adding-a-zone`
-
-#. Log in to the UI. See `*User Interface*
- <http://docs.cloudstack.apache.org/projects/cloudstack-administration/en/latest/ui.html#log-in-to-the-ui>`_
-
-#. Add a zone. Includes the first pod, cluster, and host.
- See :ref:`adding-a-host`
-
-#. Add more pods (optional). See :ref:`adding-a-pod`
-
-#. Add more clusters (optional). See :ref:`adding-a-cluster`
-
-#. Add more hosts (optional). See :ref:`adding-a-host`
-
-#. Add more primary storage (optional). See :ref:`add-primary-storage`
-
-#. Add more secondary storage (optional). See :ref:`add-secondary-storage`
-
-#. Try using the cloud. See :ref:`initialize-and-test`
-
-
-.. _minimum-system-requirements:
-
-Minimum System Requirements
----------------------------
-
-Management Server, Database, and Storage System Requirements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The machines that will run the Management Server and MySQL database must
-meet the following requirements. The same machines can also be used to
-provide primary and secondary storage, such as via localdisk or NFS. The
-Management Server may be placed on a virtual machine.
-
-- Operating system:
-
- - Preferred: CentOS/RHEL 6.3+ or Ubuntu 12.04(.1)
-
-- 64-bit x86 CPU (more cores results in better performance)
-
-- 4 GB of memory
-
-- 250 GB of local disk (more results in better capability; 500 GB
- recommended)
-
-- At least 1 NIC
-
-- Statically allocated IP address
-
-- Fully qualified domain name as returned by the hostname command
-
-
-Host/Hypervisor System Requirements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The host is where the cloud services run in the form of guest virtual
-machines. Each host is one machine that meets the following
-requirements:
-
-- Must support HVM (Intel-VT or AMD-V enabled).
-
-- 64-bit x86 CPU (more cores results in better performance)
-
-- Hardware virtualization support required
-
-- 4 GB of memory
-
-- 36 GB of local disk
-
-- At least 1 NIC
-
-- Latest hotfixes applied to hypervisor software
-
-- When you deploy CloudStack, the hypervisor host must not have any VMs
- already running
-
-- All hosts within a cluster must be homogeneous. The CPUs must be of
- the same type, count, and feature flags.
-
-Hosts have additional requirements depending on the hypervisor. See the
-requirements listed at the top of the Installation section for your
-chosen hypervisor:
-
-.. warning::
- Be sure you fulfill the additional hypervisor requirements and installation
- steps provided in this Guide. Hypervisor hosts must be properly prepared to
- work with CloudStack. For example, the requirements for XenServer are
- listed under Citrix XenServer Installation.
-
-
-Configure package repository
-----------------------------
-
-CloudStack is only distributed from source from the official mirrors.
-However, members of the CloudStack community may build convenience
-binaries so that users can install Apache CloudStack without needing to
-build from source.
-
-If you didn't follow the steps to build your own packages from source in
-the sections for `“Building RPMs from Source”
-<building_from_source.html#building-rpms-from-source>`_ or
-`“Building DEB packages” <building_from_source.html#building-deb-packages>`_
-you may find pre-built DEB and RPM packages for your convenience linked from
-the `downloads <http://cloudstack.apache.org/downloads.html>`_ page.
-
-.. note::
- These repositories contain both the Management Server and KVM Hypervisor
- packages.
-
-
-DEB package repository
-~~~~~~~~~~~~~~~~~~~~~~
-
-You can add a DEB package repository to your apt sources with the
-following commands. Please note that only packages for Ubuntu 12.04 LTS
-(precise) are being built at this time.
-
-Use your preferred editor and open (or create)
-``/etc/apt/sources.list.d/cloudstack.list``. Add the community provided
-repository to the file:
-
-.. sourcecode:: bash
-
- $ deb http://cloudstack.apt-get.eu/ubuntu precise 4.4
-
-We now have to add the public key to the trusted keys.
-
-.. sourcecode:: bash
-
- $ wget -O - http://cloudstack.apt-get.eu/release.asc|apt-key add -
-
-Now update your local apt cache.
-
-.. sourcecode:: bash
-
- $ apt-get update
-
-Your DEB package repository should now be configured and ready for use.
-
-
-RPM package repository
-~~~~~~~~~~~~~~~~~~~~~~
-
-There is a RPM package repository for CloudStack so you can easily
-install on RHEL based platforms.
-
-If you're using an RPM-based system, you'll want to add the Yum
-repository so that you can install CloudStack with Yum.
-
-Yum repository information is found under ``/etc/yum.repos.d``. You'll
-see several ``.repo`` files in this directory, each one denoting a
-specific repository.
-
-To add the CloudStack repository, create
-``/etc/yum.repos.d/cloudstack.repo`` and insert the following
-information.
-
-.. sourcecode:: bash
-
- [cloudstack]
- name=cloudstack
- baseurl=http://cloudstack.apt-get.eu/rhel/4.4/
- enabled=1
- gpgcheck=0
-
-Now you should be able to install CloudStack using Yum.
-
-
-Management Server Installation
-------------------------------
-
-Management Server Installation Overview
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This section describes installing the Management Server. There are two
-slightly different installation flows, depending on how many Management
-Server nodes will be in your cloud:
-
-- A single Management Server node, with MySQL on the same node.
-
-- Multiple Management Server nodes, with MySQL on a node separate from
- the Management Servers.
-
-In either case, each machine must meet the system requirements described
-in System Requirements.
-
-.. warning::
- For the sake of security, be sure the public Internet can not access port
- 8096 or port 8250 on the Management Server.
-
-The procedure for installing the Management Server is:
-
-#. Prepare the Operating System
-
-#. (XenServer only) Download and install vhd-util.
-
-#. Install the First Management Server
-
-#. Install and Configure the MySQL database
-
-#. Prepare NFS Shares
-
-#. Prepare and Start Additional Management Servers (optional)
-
-#. Prepare the System VM Template
-
-
-Prepare the Operating System
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The OS must be prepared to host the Management Server using the
-following steps. These steps must be performed on each Management Server
-node.
-
-#. Log in to your OS as root.
-
-#. Check for a fully qualified hostname.
-
- .. sourcecode:: bash
-
- hostname --fqdn
-
- This should return a fully qualified hostname such as
- "management1.lab.example.org". If it does not, edit /etc/hosts so
- that it does.
-
-#. Make sure that the machine can reach the Internet.
-
- .. sourcecode:: bash
-
- ping www.cloudstack.org
-
-#. Turn on NTP for time synchronization.
-
- .. note::
- NTP is required to synchronize the clocks of the servers in your cloud.
-
- Install NTP.
-
- .. sourcecode:: bash
-
- yum install ntp
-
- .. sourcecode:: bash
-
- apt-get install openntpd
-
-#. Repeat all of these steps on every host where the Management Server
- will be installed.
-
-
-Install the Management Server on the First Host
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The first step in installation, whether you are installing the
-Management Server on one host or many, is to install the software on a
-single node.
-
-.. note::
- If you are planning to install the Management Server on multiple nodes for
- high availability, do not proceed to the additional nodes yet. That step
- will come later.
-
-The CloudStack Management server can be installed using either RPM or
-DEB packages. These packages will depend on everything you need to run
-the Management server.
-
-
-Install on CentOS/RHEL
-^^^^^^^^^^^^^^^^^^^^^^
-
-We start by installing the required packages:
-
-.. sourcecode:: bash
-
- yum install cloudstack-management
-
-
-Install on Ubuntu
-^^^^^^^^^^^^^^^^^
-
-.. sourcecode:: bash
-
- apt-get install cloudstack-management
-
-.. warning::
-
- There is a known bug in the 4.3.0 release. You need to install an additional package by hand:
-
- .. sourcecode:: bash
-
- apt-get install libmysql-java
-
- This bug has been fixed in 4.4 release and will also be fixed in bug fix releases 4.3.1
-
-
-Downloading vhd-util
-^^^^^^^^^^^^^^^^^^^^
-
-This procedure is required only for installations where XenServer is
-installed on the hypervisor hosts.
-
-Before setting up the Management Server, download vhd-util from
-`vhd-util <http://download.cloud.com.s3.amazonaws.com/tools/vhd-util>`_.
-
-If the Management Server is RHEL or CentOS, copy vhd-util to
-`/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver`
-
-If the Management Server is Ubuntu, copy vhd-util to
-`/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver`
-
-
-Install the database server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The CloudStack management server uses a MySQL database server to store
-its data. When you are installing the management server on a single
-node, you can install the MySQL server locally. For an installation that
-has multiple management server nodes, we assume the MySQL database also
-runs on a separate node.
-
-CloudStack has been tested with MySQL 5.1 and 5.5. These versions are
-included in RHEL/CentOS and Ubuntu.
-
-
-Install the Database on the Management Server Node
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This section describes how to install MySQL on the same machine with the
-Management Server. This technique is intended for a simple deployment
-that has a single Management Server node. If you have a multi-node
-Management Server deployment, you will typically use a separate node for
-MySQL. See :ref:`install-database-on-separate-node`.
-
-#. Install MySQL from the package repository of your distribution:
-
- .. sourcecode:: bash
-
- yum install mysql-server
-
- .. sourcecode:: bash
-
- apt-get install mysql-server
-
-#. Open the MySQL configuration file. The configuration file is
- ``/etc/my.cnf`` or ``/etc/mysql/my.cnf``, depending on your OS.
-
-#. Insert the following lines in the [mysqld] section.
-
- You can put these lines below the datadir line. The max\_connections
- parameter should be set to 350 multiplied by the number of Management
- Servers you are deploying. This example assumes one Management
- Server.
-
- .. note::
- On Ubuntu, you can also create a file `/etc/mysql/conf.d/cloudstack.cnf`
- and add these directives there. Don't forget to add [mysqld] on the
- first line of the file.
-
- .. sourcecode:: bash
-
- innodb_rollback_on_timeout=1
- innodb_lock_wait_timeout=600
- max_connections=350
- log-bin=mysql-bin
- binlog-format = 'ROW'
-
-#. Start or restart MySQL to put the new configuration into effect.
-
- On RHEL/CentOS, MySQL doesn't automatically start after installation.
- Start it manually.
-
- .. sourcecode:: bash
-
- service mysqld start
-
- On Ubuntu, restart MySQL.
-
- .. sourcecode:: bash
-
- service mysql restart
-
-#. (CentOS and RHEL only; not required on Ubuntu)
-
- .. warning::
- On RHEL and CentOS, MySQL does not set a root password by default. It is
- very strongly recommended that you set a root password as a security
- precaution.
-
- Run the following command to secure your installation. You can answer "Y"
- to all questions.
-
- .. sourcecode:: bash
-
- mysql_secure_installation
-
-#. CloudStack can be blocked by security mechanisms, such as SELinux.
- Disable SELinux to ensure + that the Agent has all the required
- permissions.
-
- Configure SELinux (RHEL and CentOS):
-
- #. Check whether SELinux is installed on your machine. If not, you
- can skip this section.
-
- In RHEL or CentOS, SELinux is installed and enabled by default.
- You can verify this with:
-
- .. sourcecode:: bash
-
- $ rpm -qa | grep selinux
-
- #. Set the SELINUX variable in ``/etc/selinux/config`` to
- "permissive". This ensures that the permissive setting will be
- maintained after a system reboot.
-
- In RHEL or CentOS:
-
- .. sourcecode:: bash
-
- vi /etc/selinux/config
-
- Change the following line
-
- .. sourcecode:: bash
-
- SELINUX=enforcing
-
- to this:
-
- .. sourcecode:: bash
-
- SELINUX=permissive
-
- #. Set SELinux to permissive starting immediately, without requiring
- a system reboot.
-
- .. sourcecode:: bash
-
- $ setenforce permissive
-
-#. Set up the database. The following command creates the "cloud" user
- on the database.
-
- - In dbpassword, specify the password to be assigned to the "cloud"
- user. You can choose to provide no password although that is not
- recommended.
-
- - In deploy-as, specify the username and password of the user
- deploying the database. In the following command, it is assumed
- the root user is deploying the database and creating the "cloud"
- user.
-
- - (Optional) For encryption\_type, use file or web to indicate the
- technique used to pass in the database encryption password.
- Default: file. See :ref:`about-password-key-encryption`.
-
- - (Optional) For management\_server\_key, substitute the default key
- that is used to encrypt confidential parameters in the CloudStack
- properties file. Default: password. It is highly recommended that
- you replace this with a more secure value. See
- :ref:`about-password-key-encryption`.
-
- - (Optional) For database\_key, substitute the default key that is
- used to encrypt confidential parameters in the CloudStack
- database. Default: password. It is highly recommended that you
- replace this with a more secure value. See
- :ref:`about-password-key-encryption`.
-
- - (Optional) For management\_server\_ip, you may explicitly specify
- cluster management server node IP. If not specified, the local IP
- address will be used.
-
- .. sourcecode:: bash
-
- cloudstack-setup-databases cloud:<dbpassword>@localhost \
- --deploy-as=root:<password> \
- -e <encryption_type> \
- -m <management_server_key> \
- -k <database_key> \
- -i <management_server_ip>
-
- When this script is finished, you should see a message like
- “Successfully initialized the database.”
-
- .. note::
- If the script is unable to connect to the MySQL database, check the
- "localhost" loopback address in ``/etc/hosts``. It should be pointing to
- the IPv4 loopback address "127.0.0.1" and not the IPv6 loopback address
- ``::1``. Alternatively, reconfigure MySQL to bind to the IPv6 loopback
- interface.
-
-#. If you are running the KVM hypervisor on the same machine with the
- Management Server, edit /etc/sudoers and add the following line:
-
- .. sourcecode:: bash
-
- Defaults:cloud !requiretty
-
-#. Now that the database is set up, you can finish configuring the OS
- for the Management Server. This command will set up iptables,
- sudoers, and start the Management Server.
-
- .. sourcecode:: bash
-
- # cloudstack-setup-management
-
- You should see the message “CloudStack Management Server setup is
- done.”
-
-
-.. _install-database-on-separate-node:
-
-Install the Database on a Separate Node
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This section describes how to install MySQL on a standalone machine,
-separate from the Management Server. This technique is intended for a
-deployment that includes several Management Server nodes. If you have a
-single-node Management Server deployment, you will typically use the
-same node for MySQL. See `“Install the Database on the Management Server Node”
-<#install-the-database-on-the-management-server-node>`_.
-
-.. note::
- The management server doesn't require a specific distribution for the MySQL
- node. You can use a distribution or Operating System of your choice. Using
- the same distribution as the management server is recommended, but not
- required. See `“Management Server, Database, and Storage System Requirements”
- <#management-server-database-and-storage-system-requirements>`_.
-
-#. Install MySQL from the package repository from your distribution:
-
- .. sourcecode:: bash
-
- yum install mysql-server
-
- .. sourcecode:: bash
-
- apt-get install mysql-server
-
-#. Edit the MySQL configuration (/etc/my.cnf or /etc/mysql/my.cnf,
- depending on your OS) and insert the following lines in the [mysqld]
- section. You can put these lines below the datadir line. The
- max\_connections parameter should be set to 350 multiplied by the
- number of Management Servers you are deploying. This example assumes
- two Management Servers.
-
- .. note::
- On Ubuntu, you can also create /etc/mysql/conf.d/cloudstack.cnf file and
- add these directives there. Don't forget to add [mysqld] on the first
- line of the file.
-
- .. sourcecode:: bash
-
- innodb_rollback_on_timeout=1
- innodb_lock_wait_timeout=600
- max_connections=700
- log-bin=mysql-bin
- binlog-format = 'ROW'
- bind-address = 0.0.0.0
-
-#. Start or restart MySQL to put the new configuration into effect.
-
- On RHEL/CentOS, MySQL doesn't automatically start after installation.
- Start it manually.
-
- .. sourcecode:: bash
-
- service mysqld start
-
- On Ubuntu, restart MySQL.
-
- .. sourcecode:: bash
-
- service mysql restart
-
-#. (CentOS and RHEL only; not required on Ubuntu)
-
- .. warning::
- On RHEL and CentOS, MySQL does not set a root password by default. It is
- very strongly recommended that you set a root password as a security
- precaution. Run the following command to secure your installation. You
- can answer "Y" to all questions except "Disallow root login remotely?".
- Remote root login is required to set up the databases.
-
- .. sourcecode:: bash
-
- mysql_secure_installation
-
-#. If a firewall is present on the system, open TCP port 3306 so
- external MySQL connections can be established.
-
- On Ubuntu, UFW is the default firewall. Open the port with this
- command:
-
- .. sourcecode:: bash
-
- ufw allow mysql
-
- On RHEL/CentOS:
-
- #. Edit the /etc/sysconfig/iptables file and add the following line
- at the beginning of the INPUT chain.
-
- .. sourcecode:: bash
-
- -A INPUT -p tcp --dport 3306 -j ACCEPT
-
- #. Now reload the iptables rules.
-
- .. sourcecode:: bash
-
- service iptables restart
-
-#. Return to the root shell on your first Management Server.
-
-#. Set up the database. The following command creates the cloud user on
- the database.
-
- - In dbpassword, specify the password to be assigned to the cloud
- user. You can choose to provide no password.
-
- - In deploy-as, specify the username and password of the user
- deploying the database. In the following command, it is assumed
- the root user is deploying the database and creating the cloud
- user.
-
- - (Optional) For encryption\_type, use file or web to indicate the
- technique used to pass in the database encryption password.
- Default: file. See :ref:`about-password-key-encryption`.
-
- - (Optional) For management\_server\_key, substitute the default key
- that is used to encrypt confidential parameters in the CloudStack
- properties file. Default: password. It is highly recommended that
- you replace this with a more secure value. See About Password and
- Key Encryption.
-
- - (Optional) For database\_key, substitute the default key that is
- used to encrypt confidential parameters in the CloudStack
- database. Default: password. It is highly recommended that you
- replace this with a more secure value. See
- :ref:`about-password-key-encryption`.
-
- - (Optional) For management\_server\_ip, you may explicitly specify
- cluster management server node IP. If not specified, the local IP
- address will be used.
-
- .. sourcecode:: bash
-
- cloudstack-setup-databases cloud:<dbpassword>@<ip address mysql server> \
- --deploy-as=root:<password> \
- -e <encryption_type> \
- -m <management_server_key> \
- -k <database_key> \
- -i <management_server_ip>
-
- When this script is finished, you should see a message like
- “Successfully initialized the database.”
-
-
-.. _about-password-key-encryption:
-
-About Password and Key Encryption
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-CloudStack stores several sensitive passwords and secret keys that are
-used to provide security. These values are always automatically
-encrypted:
-
-- Database secret key
-
-- Database password
-
-- SSH keys
-
-- Compute node root password
-
-- VPN password
-
-- User API secret key
-
-- VNC password
-
-CloudStack uses the Java Simplified Encryption (JASYPT) library. The
-data values are encrypted and decrypted using a database secret key,
-which is stored in one of CloudStack’s internal properties files along
-with the database password. The other encrypted values listed above,
-such as SSH keys, are in the CloudStack internal database.
-
-Of course, the database secret key itself can not be stored in the open
-– it must be encrypted. How then does CloudStack read it? A second
-secret key must be provided from an external source during Management
-Server startup. This key can be provided in one of two ways: loaded from
-a file or provided by the CloudStack administrator. The CloudStack
-database has a configuration setting that lets it know which of these
-methods will be used. If the encryption type is set to "file," the key
-must be in a file in a known location. If the encryption type is set to
-"web," the administrator runs the utility
-com.cloud.utils.crypt.EncryptionSecretKeySender, which relays the key to
-the Management Server over a known port.
-
-The encryption type, database secret key, and Management Server secret
-key are set during CloudStack installation. They are all parameters to
-the CloudStack database setup script (cloudstack-setup-databases). The
-default values are file, password, and password. It is, of course,
-highly recommended that you change these to more secure keys.
-
-
-Changing the Default Password Encryption
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Passwords are encoded when creating or updating users. CloudStack allows
-you to determine the default encoding and authentication mechanism for
-admin and user logins. Two new configurable lists have been
-introduced—userPasswordEncoders and userAuthenticators.
-userPasswordEncoders allows you to configure the order of preference for
-encoding passwords, whereas userAuthenticators allows you to configure
-the order in which authentication schemes are invoked to validate user
-passwords.
-
-Additionally, the plain text user authenticator has been modified not to
-convert supplied passwords to their md5 sums before checking them with
-the database entries. It performs a simple string comparison between
-retrieved and supplied login passwords instead of comparing the
-retrieved md5 hash of the stored password against the supplied md5 hash
-of the password because clients no longer hash the password. The
-following method determines what encoding scheme is used to encode the
-password supplied during user creation or modification.
-
-When a new user is created, the user password is encoded by using the
-first valid encoder loaded as per the sequence specified in the
-``UserPasswordEncoders`` property in the ``ComponentContext.xml`` or
-``nonossComponentContext.xml`` files. The order of authentication
-schemes is determined by the ``UserAuthenticators`` property in the same
-files. If Non-OSS components, such as VMware environments, are to be
-deployed, modify the ``UserPasswordEncoders`` and ``UserAuthenticators``
-lists in the ``nonossComponentContext.xml`` file, for OSS environments,
-such as XenServer or KVM, modify the ``ComponentContext.xml`` file. It
-is recommended to make uniform changes across both the files. When a new
-authenticator or encoder is added, you can add them to this list. While
-doing so, ensure that the new authenticator or encoder is specified as a
-bean in both these files. The administrator can change the ordering of
-both these properties as preferred to change the order of schemes.
-Modify the following list properties available in
-``client/tomcatconf/nonossComponentContext.xml.in`` or
-``client/tomcatconf/componentContext.xml.in`` as applicable, to the
-desired order:
-
-.. sourcecode:: xml
-
- <property name="UserAuthenticators">
- <list>
- <ref bean="SHA256SaltedUserAuthenticator"/>
- <ref bean="MD5UserAuthenticator"/>
- <ref bean="LDAPUserAuthenticator"/>
- <ref bean="PlainTextUserAuthenticator"/>
- </list>
- </property>
- <property name="UserPasswordEncoders">
- <list>
- <ref bean="SHA256SaltedUserAuthenticator"/>
- <ref bean="MD5UserAuthenticator"/>
- <ref bean="LDAPUserAuthenticator"/>
- <ref bean="PlainTextUserAuthenticator"/>
- </list>
- </property>
-
-In the above default ordering, SHA256Salt is used first for
-``UserPasswordEncoders``. If the module is found and encoding returns a
-valid value, the encoded password is stored in the user table's password
-column. If it fails for any reason, the MD5UserAuthenticator will be
-tried next, and the order continues. For ``UserAuthenticators``,
-SHA256Salt authentication is tried first. If it succeeds, the user is
-logged into the Management server. If it fails, md5 is tried next, and
-attempts continues until any of them succeeds and the user logs in . If
-none of them works, the user is returned an invalid credential message.
-
-
-Prepare NFS Shares
-~~~~~~~~~~~~~~~~~~
-
-CloudStack needs a place to keep primary and secondary storage (see
-Cloud Infrastructure Overview). Both of these can be NFS shares. This
-section tells how to set up the NFS shares before adding the storage to
-CloudStack.
-
-.. note::
- NFS is not the only option for primary or secondary storage. For example,
- you may use Ceph RBD, GlusterFS, iSCSI, and others. The choice of storage
- system will depend on the choice of hypervisor and whether you are dealing
- with primary or secondary storage.
-
-The requirements for primary and secondary storage are described in:
-
-- `“About Primary Storage”
- <http://docs.cloudstack.apache.org/en/latest/concepts.html#about-primary-storage>`_
-
-- `“About Secondary Storage”
- <http://docs.cloudstack.apache.org/en/latest/concepts.html#about-secondary-storage>`_
-
-A production installation typically uses a separate NFS server.
-See :ref:`using-a-separage-nfs-server`.
-
-You can also use the Management Server node as the NFS server. This is
-more typical of a trial installation, but is technically possible in a
-larger deployment. See :ref:`using-the-management-server-as-the-nfs-server`.
-
-
-.. _using-a-separage-nfs-server:
-
-Using a Separate NFS Server
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This section tells how to set up NFS shares for secondary and
-(optionally) primary storage on an NFS server running on a separate node
-from the Management Server.
-
-The exact commands for the following steps may vary depending on your
-operating system version.
-
-.. warning::
- (KVM only) Ensure that no volume is already mounted at your NFS mount point.
-
-#. On the storage server, create an NFS share for secondary storage and,
- if you are using NFS for primary storage as well, create a second NFS
- share. For example:
-
- .. sourcecode:: bash
-
- # mkdir -p /export/primary
- # mkdir -p /export/secondary
-
-#. To configure the new directories as NFS exports, edit /etc/exports.
- Export the NFS share(s) with
- rw,async,no\_root\_squash,no\_subtree\_check. For example:
-
- .. sourcecode:: bash
-
- # vi /etc/exports
-
- Insert the following line.
-
- .. sourcecode:: bash
-
- /export *(rw,async,no_root_squash,no_subtree_check)
-
-#. Export the /export directory.
-
- .. sourcecode:: bash
-
- # exportfs -a
-
-#. On the management server, create a mount point for secondary storage.
- For example:
-
- .. sourcecode:: bash
-
- # mkdir -p /mnt/secondary
-
-#. Mount the secondary storage on your Management Server. Replace the
- example NFS server name and NFS share paths below with your own.
-
- .. sourcecode:: bash
-
- # mount -t nfs nfsservername:/nfs/share/secondary /mnt/secondary
-
-
-.. _using-the-management-server-as-the-nfs-server:
-
-Using the Management Server as the NFS Server
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This section tells how to set up NFS shares for primary and secondary
-storage on the same node with the Management Server. This is more
-typical of a trial installation, but is technically possible in a larger
-deployment. It is assumed that you will have less than 16TB of storage
-on the host.
-
-The exact commands for the following steps may vary depending on your
-operating system version.
-
-#. On RHEL/CentOS systems, you'll need to install the nfs-utils package:
-
- .. sourcecode:: bash
-
- $ sudo yum install nfs-utils
-
-#. On the Management Server host, create two directories that you will
- use for primary and secondary storage. For example:
-
- .. sourcecode:: bash
-
- # mkdir -p /export/primary
- # mkdir -p /export/secondary
-
-#. To configure the new directories as NFS exports, edit /etc/exports.
- Export the NFS share(s) with
- rw,async,no\_root\_squash,no\_subtree\_check. For example:
-
- .. sourcecode:: bash
-
- # vi /etc/exports
-
- Insert the following line.
-
- .. sourcecode:: bash
-
- /export *(rw,async,no_root_squash,no_subtree_check)
-
-#. Export the /export directory.
-
- .. sourcecode:: bash
-
- # exportfs -a
-
-#. Edit the /etc/sysconfig/nfs file.
-
- .. sourcecode:: bash
-
- # vi /etc/sysconfig/nfs
-
- Uncomment the following lines:
-
- .. sourcecode:: bash
-
- LOCKD_TCPPORT=32803
- LOCKD_UDPPORT=32769
- MOUNTD_PORT=892
- RQUOTAD_PORT=875
- STATD_PORT=662
- STATD_OUTGOING_PORT=2020
-
-#. Edit the /etc/sysconfig/iptables file.
-
- .. sourcecode:: bash
-
- # vi /etc/sysconfig/iptables
-
- Add the following lines at the beginning of the INPUT chain, where
- <NETWORK> is the network that you'll be using:
-
- .. sourcecode:: bash
-
- -A INPUT -s <NETWORK> -m state --state NEW -p udp --dport 111 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p tcp --dport 111 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p tcp --dport 2049 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p tcp --dport 32803 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p udp --dport 32769 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p tcp --dport 892 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p udp --dport 892 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p tcp --dport 875 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p udp --dport 875 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p tcp --dport 662 -j ACCEPT
- -A INPUT -s <NETWORK> -m state --state NEW -p udp --dport 662 -j ACCEPT
-
-#. Run the following commands:
-
- .. sourcecode:: bash
-
- # service iptables restart
- # service iptables save
-
-#. If NFS v4 communication is used between client and server, add your
- domain to /etc/idmapd.conf on both the hypervisor host and Management
- Server.
-
- .. sourcecode:: bash
-
- # vi /etc/idmapd.conf
-
- Remove the character # from the beginning of the Domain line in
- idmapd.conf and replace the value in the file with your own domain.
- In the example below, the domain is company.com.
-
- .. sourcecode:: bash
-
- Domain = company.com
-
-#. Reboot the Management Server host.
-
- Two NFS shares called /export/primary and /export/secondary are now
- set up.
-
-#. It is recommended that you test to be sure the previous steps have
- been successful.
-
- #. Log in to the hypervisor host.
-
- #. Be sure NFS and rpcbind are running. The commands might be
- different depending on your OS. For example:
-
- .. sourcecode:: bash
-
- # service rpcbind start
- # service nfs start
- # chkconfig nfs on
- # chkconfig rpcbind on
- # reboot
-
- #. Log back in to the hypervisor host and try to mount the /export
- directories. For example, substitute your own management server
- name:
-
- .. sourcecode:: bash
-
- # mkdir /primary
- # mount -t nfs <management-server-name>:/export/primary
- # umount /primary
- # mkdir /secondary
- # mount -t nfs <management-server-name>:/export/secondary
- # umount /secondary
-
-
-Prepare and Start Additional Management Servers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For your second and subsequent Management Servers, you will install the
-Management Server software, connect it to the database, and set up the
-OS for the Management Server.
-
-#. Perform the steps in `“Prepare the Operating System”
- <#prepare-the-operating-system>`_ and `“Building RPMs from Source”
- <building_from_source.html#building-rpms-from-source>`_ or
- `“Building DEB packages”
- <building_from_source.html#building-deb-packages>`_ as appropriate.
-
-#. This step is required only for installations where XenServer is
- installed on the hypervisor hosts.
-
- Download vhd-util from
- `vhd-util <http://download.cloud.com.s3.amazonaws.com/tools/vhd-util>`_
-
- Copy vhd-util to
- /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver.
-
-#. Ensure that necessary services are started and set to start on boot.
-
- .. sourcecode:: bash
-
- # service rpcbind start
- # service nfs start
- # chkconfig nfs on
- # chkconfig rpcbind on
-
-#. Configure the database client. Note the absence of the --deploy-as
- argument in this case. (For more details about the arguments to this
- command, see :ref:`install-database-on-separate-node`.)
-
- .. sourcecode:: bash
-
- # cloudstack-setup-databases cloud:dbpassword@dbhost -e encryption_type -m management_server_key -k database_key -i management_server_ip
-
-#. Configure the OS and start the Management Server:
-
- .. sourcecode:: bash
-
- # cloudstack-setup-management
-
- The Management Server on this node should now be running.
-
-#. Repeat these steps on each additional Management Server.
-
-#. Be sure to configure a load balancer for the Management Servers. See
- `“Management Server Load Balancing”
- <http://docs.cloudstack.apache.org/en/latest/administration_guide.html?highlight=management%20server%20load#management-server-load-balancing>`_.
-
-
-Prepare the System VM Template
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Secondary storage must be seeded with a template that is used for
-CloudStack system VMs.
-
-.. note::
- When copying and pasting a command, be sure the command has pasted as a
- single line before executing. Some document viewers may introduce unwanted
- line breaks in copied text.
-
-#. On the Management Server, run one or more of the following
- cloud-install-sys-tmplt commands to retrieve and decompress the
- system VM template. Run the command for each hypervisor type that you
- expect end users to run in this Zone.
-
- If your secondary storage mount point is not named /mnt/secondary,
- substitute your own mount point name.
-
- If you set the CloudStack database encryption type to "web" when you
- set up the database, you must now add the parameter -s
- <management-server-secret-key>. See :ref:`about-password-key-encryption`.
-
- This process will require approximately 5 GB of free space on the
- local file system and up to 30 minutes each time it runs.
-
- * For Hyper-V
-
- .. sourcecode:: bash
-
- /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt \
- -m /mnt/secondary \
- -u http://cloudstack.apt-get.eu/systemvm/4.4/systemvm64template-4.4.1-7-hyperv.vhd \
- -h hyperv \
- -s <optional-management-server-secret-key> \
- -F
-
- * For XenServer:
-
- .. sourcecode:: bash
-
- /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt \
- -m /mnt/secondary \
- -u http://cloudstack.apt-get.eu/systemvm/4.4/systemvm64template-4.4.1-7-xen.vhd.bz2 \
- -h xenserver \
- -s <optional-management-server-secret-key> \
- -F
-
- * For vSphere:
-
- .. sourcecode:: bash
-
- /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt \
- -m /mnt/secondary \
- -u http://cloudstack.apt-get.eu/systemvm/4.4/systemvm64template-4.4.1-7-vmware.ova \
- -h vmware \
- -s <optional-management-server-secret-key> \
- -F
-
- * For KVM:
-
- .. sourcecode:: bash
-
- /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt \
- -m /mnt/secondary \
- -u http://cloudstack.apt-get.eu/systemvm/4.4/systemvm64template-4.4.1-7-kvm.qcow2.bz2 \
- -h kvm \
- -s <optional-management-server-secret-key> \
- -F
-
- * For LXC:
-
- .. sourcecode:: bash
-
- /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt \
- -m /mnt/secondary \
- -u http://cloudstack.apt-get.eu/systemvm/4.4/systemvm64template-4.4.1-7-kvm.qcow2.bz2 \
- -h lxc \
- -s <optional-management-server-secret-key> \
- -F
-
-#. If you are using a separate NFS server, perform this step. If you are
- using the Management Server as the NFS server, you MUST NOT perform
- this step.
-
- When the script has finished, unmount secondary storage and remove
- the created directory.
-
- .. sourcecode:: bash
-
- # umount /mnt/secondary
- # rmdir /mnt/secondary
-
-#. Repeat these steps for each secondary storage server.
-
-
-Installation Complete! Next Steps
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Congratulations! You have now installed CloudStack Management Server and
-the database it uses to persist system data.
-
-|installation-complete.png: Finished installs with single Management
-Server and multiple Management Servers|
-
-What should you do next?
-
-- Even without adding any cloud infrastructure, you can run the UI to
- get a feel for what's offered and how you will interact with
- CloudStack on an ongoing basis. See Log In to the UI.
-
-- When you're ready, add the cloud infrastructure and try running some
- virtual machines on it, so you can watch how CloudStack manages the
- infrastructure. See Provision Your Cloud Infrastructure.
-
-
-.. |installation-complete.png: Finished installs with single Management Server and multiple Management Servers| image:: ./_static/images/installation-complete.png