diff --git a/doc/install-guide-rst/source/basic_environment.rst b/doc/install-guide-rst/source/basic_environment.rst index d3c3d288d4..a13e391995 100644 --- a/doc/install-guide-rst/source/basic_environment.rst +++ b/doc/install-guide-rst/source/basic_environment.rst @@ -37,9 +37,10 @@ and three-node architecture with OpenStack Networking when the service uses SysV Init scripts instead of native systemd files. This warning can be ignored. - .. include:: basics-prerequisites.rst .. include:: basics-security.rst +.. include:: basics-networking.rst +.. include:: basics-ntp.rst .. include:: basics-packages.rst .. include:: basics-database.rst .. include:: basics-queue.rst @@ -50,11 +51,8 @@ and three-node architecture with OpenStack Networking basics-prerequisites.rst basics-security.rst + basics-networking.rst + basics-ntp.rst basics-packages.rst basics-database.rst basics-queue.rst - - -.. TODO(karenb) - section_basics-networking.xml - section_basics-ntp.xml diff --git a/doc/install-guide-rst/source/basics-networking-neutron.rst b/doc/install-guide-rst/source/basics-networking-neutron.rst new file mode 100644 index 0000000000..b700ee10bb --- /dev/null +++ b/doc/install-guide-rst/source/basics-networking-neutron.rst @@ -0,0 +1,409 @@ +OpenStack Networking (neutron) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The example architecture with OpenStack Networking (neutron) requires +one controller node, one network node, and at least one compute node. +The controller node contains one network interface on the +:term:`management network`. The network node contains one network interface +on the management network, one on the :term:`instance tunnels network`, +and one on the :term:`external network`. The compute node contains one +network interface on the management network and one on the instance +tunnels network. + +The example architecture assumes use of the following networks: + +- Management on 10.0.0.0/24 with gateway 10.0.0.1 + + .. note:: + + This network requires a gateway to provide Internet access to all + nodes for administrative purposes such as package installation, + security updates, :term:`DNS`, and :term:`Network Time Protocol (NTP)`. + +- Instance tunnels on 10.0.1.0/24 without a gateway + + .. note:: + + This network does not require a gateway because communication + only occurs among network and compute nodes in your OpenStack + environment. + +- External on 203.0.113.0/24 with gateway 203.0.113.1 + + .. note:: + + This network requires a gateway to provide Internet access to + instances in your OpenStack environment. + +You can modify these ranges and gateways to work with your particular +network infrastructure. + +.. note:: + + Network interface names vary by distribution. Traditionally, + interfaces use "eth" followed by a sequential number. To cover all + variations, this guide simply refers to the first interface as the + interface with the lowest number, the second interface as the + interface with the middle number, and the third interface as the + interface with the highest number. + +| + +:ref:`figure-neutron-networks` + +| + +Unless you intend to use the exact configuration provided in this +example architecture, you must modify the networks in this procedure to +match your environment. Also, each node must resolve the other nodes by +name in addition to IP address. For example, the ``controller`` name must +resolve to ``10.0.0.11``, the IP address of the management interface on +the controller node. + +.. warning:: + + Reconfiguring network interfaces will interrupt network + connectivity. We recommend using a local terminal session for these + procedures. + +| + +Controller node +--------------- + +**To configure networking:** + +#. Configure the first interface as the management interface: + + IP address: 10.0.0.11 + + Network mask: 255.255.255.0 (or /24) + + Default gateway: 10.0.0.1 + +#. Reboot the system to activate the changes. + +| + +**To configure name resolution:** + +#. Set the hostname of the node to ``controller``. + +#. Edit the :file:`/etc/hosts:` file to contain the following: + + .. code-block:: ini + + # controller + 10.0.0.11 controller + + # network + 10.0.0.21 network + + # compute1 + 10.0.0.31 compute1 + + .. warning:: + + Some distributions add an extraneous entry in the :file:`/etc/hosts` + file that resolves the actual hostname to another loopback IP + address such as ``127.0.1.1``. You must comment out or remove this + entry to prevent name resolution problems. + +| + +Network node +------------ + +**To configure networking:** + +#. Configure the first interface as the management interface: + + IP address: 10.0.0.21 + + Network mask: 255.255.255.0 (or /24) + + Default gateway: 10.0.0.1 + +#. Configure the second interface as the instance tunnels interface: + + IP address: 10.0.1.21 + + Network mask: 255.255.255.0 (or /24) + +#. The external interface uses a special configuration without an IP + address assigned to it. Configure the third interface as the external + interface: + + Replace ``INTERFACE_NAME`` with the actual interface name. For example, + *eth2* or *ens256*. + + .. only:: ubuntu or debian + + a. Edit the :file:`/etc/network/interfaces` file to contain the following: + + .. code-block:: ini + + # The external network interface + auto INTERFACE_NAME + iface INTERFACE_NAME inet manual + up ip link set dev $IFACE up + down ip link set dev $IFACE down + + .. only:: rdo + + a. Edit the :file:`/etc/sysconfig/network-scripts/ifcfg-INTERFACE_NAME` file + to contain the following: + + Do not change the ``HWADDR`` and ``UUID`` keys. + + .. code-block:: ini + + DEVICE= INTERFACE_NAME + TYPE=Ethernet + ONBOOT="yes" + BOOTPROTO="none" + + .. only:: obs + + a. Edit the :file:`/etc/sysconfig/network/ifcfg-INTERFACE_NAME` file + to contain the following: + + .. code-block:: ini + + STARTMODE='auto' + BOOTPROTO='static' + +4. Reboot the system to activate the changes. + +| + +**To configure name resolution:** + +#. Set the hostname of the node to ``network``. + +#. Edit the :file:`/etc/hosts` file to contain the following: + + .. code-block:: ini + + # network + 10.0.0.21 network + + # controller + 10.0.0.11 controller + + # compute1 + 10.0.0.31 compute1 + + .. warning:: + + Some distributions add an extraneous entry in the :file:`/etc/hosts` + file that resolves the actual hostname to another loopback IP + address such as ``127.0.1.1``. You must comment out or remove this + entry to prevent name resolution problems. + +| + +Compute node +------------ + +**To configure networking:** + +#. Configure the first interface as the management interface: + + IP address: 10.0.0.31 + + Network mask: 255.255.255.0 (or /24) + + Default gateway: 10.0.0.1 + + .. note:: + + Additional compute nodes should use 10.0.0.32, 10.0.0.33, and so on. + +#. Configure the second interface as the instance tunnels interface: + + IP address: 10.0.1.31 + + Network mask: 255.255.255.0 (or /24) + + .. note:: + + Additional compute nodes should use 10.0.1.32, 10.0.1.33, and so on. + +#. Reboot the system to activate the changes. + +| + +**To configure name resolution:** + +#. Set the hostname of the node to ``compute1``. + +#. Edit the :file:`/etc/hosts` file to contain the following: + + .. code-block:: ini + + # compute1 + 10.0.0.31 compute1 + + # controller + 10.0.0.11 controller + + # network + 10.0.0.21 network + + .. warning:: + + Some distributions add an extraneous entry in the :file:`/etc/hosts` + file that resolves the actual hostname to another loopback IP + address such as ``127.0.1.1``. You must comment out or remove this + entry to prevent name resolution problems. + +| + +Verify connectivity +------------------- + +We recommend that you verify network connectivity to the Internet and +among the nodes before proceeding further. + +#. From the *controller* node, :command:`ping` a site on the Internet: + + .. code-block:: console + + # ping -c 4 openstack.org + PING openstack.org (174.143.194.225) 56(84) bytes of data. + 64 bytes from 174.143.194.225: icmp_seq=1 ttl=54 time=18.3 ms + 64 bytes from 174.143.194.225: icmp_seq=2 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=3 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=4 ttl=54 time=17.4 ms + + --- openstack.org ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3022ms + rtt min/avg/max/mdev = 17.489/17.715/18.346/0.364 ms + +#. From the *controller* node, :command:`ping` the management interface + on the *network* node: + + .. code-block:: console + + # ping -c 4 network + PING network (10.0.0.21) 56(84) bytes of data. + 64 bytes from network (10.0.0.21): icmp_seq=1 ttl=64 time=0.263 ms + 64 bytes from network (10.0.0.21): icmp_seq=2 ttl=64 time=0.202 ms + 64 bytes from network (10.0.0.21): icmp_seq=3 ttl=64 time=0.203 ms + 64 bytes from network (10.0.0.21): icmp_seq=4 ttl=64 time=0.202 ms + + --- network ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3000ms + rtt min/avg/max/mdev = 0.202/0.217/0.263/0.030 ms + +#. From the *controller* node, :command:`ping` the management interface on the + *compute* node: + + .. code-block:: console + + # ping -c 4 compute1 + PING compute1 (10.0.0.31) 56(84) bytes of data. + 64 bytes from compute1 (10.0.0.31): icmp_seq=1 ttl=64 time=0.263 ms + 64 bytes from compute1 (10.0.0.31): icmp_seq=2 ttl=64 time=0.202 ms + 64 bytes from compute1 (10.0.0.31): icmp_seq=3 ttl=64 time=0.203 ms + 64 bytes from compute1 (10.0.0.31): icmp_seq=4 ttl=64 time=0.202 ms + + --- network ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3000ms + rtt min/avg/max/mdev = 0.202/0.217/0.263/0.030 ms + +#. From the *network* node, :command:`ping` a site on the Internet: + + .. code-block:: console + + # ping -c 4 openstack.org + PING openstack.org (174.143.194.225) 56(84) bytes of data. + 64 bytes from 174.143.194.225: icmp_seq=1 ttl=54 time=18.3 ms + 64 bytes from 174.143.194.225: icmp_seq=2 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=3 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=4 ttl=54 time=17.4 ms + + --- openstack.org ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3022ms + rtt min/avg/max/mdev = 17.489/17.715/18.346/0.364 ms + +#. From the *network* node, :command:`ping` the management interface on the + *controller* node: + + .. code-block:: console + + # ping -c 4 controller + PING controller (10.0.0.11) 56(84) bytes of data. + 64 bytes from controller (10.0.0.11): icmp_seq=1 ttl=64 time=0.263 ms + 64 bytes from controller (10.0.0.11): icmp_seq=2 ttl=64 time=0.202 ms + 64 bytes from controller (10.0.0.11): icmp_seq=3 ttl=64 time=0.203 ms + 64 bytes from controller (10.0.0.11): icmp_seq=4 ttl=64 time=0.202 ms + + --- controller ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3000ms + rtt min/avg/max/mdev = 0.202/0.217/0.263/0.030 ms + + +#. From the *network* node, :command:`ping` the instance tunnels interface + on the *compute* node: + + .. code-block:: console + + # ping -c 4 10.0.1.31 + PING 10.0.1.31 (10.0.1.31) 56(84) bytes of data. + 64 bytes from 10.0.1.31 (10.0.1.31): icmp_seq=1 ttl=64 time=0.263 ms + 64 bytes from 10.0.1.31 (10.0.1.31): icmp_seq=2 ttl=64 time=0.202 ms + 64 bytes from 10.0.1.31 (10.0.1.31): icmp_seq=3 ttl=64 time=0.203 ms + 64 bytes from 10.0.1.31 (10.0.1.31): icmp_seq=4 ttl=64 time=0.202 ms + + --- 10.0.1.31 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3000ms + rtt min/avg/max/mdev = 0.202/0.217/0.263/0.030 ms + +#. From the *compute* node, :command:`ping` a site on the Internet: + + .. code-block:: console + + # ping -c 4 openstack.org + PING openstack.org (174.143.194.225) 56(84) bytes of data. + 64 bytes from 174.143.194.225: icmp_seq=1 ttl=54 time=18.3 ms + 64 bytes from 174.143.194.225: icmp_seq=2 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=3 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=4 ttl=54 time=17.4 ms + + --- openstack.org ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3022ms + rtt min/avg/max/mdev = 17.489/17.715/18.346/0.364 ms + +#. From the *compute* node, :command:`ping` the management interface on the + *controller* node: + + .. code-block:: console + + # ping -c 4 controller + PING controller (10.0.0.11) 56(84) bytes of data. + 64 bytes from controller (10.0.0.11): icmp_seq=1 ttl=64 time=0.263 ms + 64 bytes from controller (10.0.0.11): icmp_seq=2 ttl=64 time=0.202 ms + 64 bytes from controller (10.0.0.11): icmp_seq=3 ttl=64 time=0.203 ms + 64 bytes from controller (10.0.0.11): icmp_seq=4 ttl=64 time=0.202 ms + + --- controller ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3000ms + rtt min/avg/max/mdev = 0.202/0.217/0.263/0.030 ms + +#. From the *compute* node, :command:`ping` the instance tunnels interface + on the *network* node: + + .. code-block:: console + + # ping -c 4 10.0.1.21 + PING 10.0.1.21 (10.0.1.21) 56(84) bytes of data. + 64 bytes from 10.0.1.21 (10.0.1.21): icmp_seq=1 ttl=64 time=0.263 ms + 64 bytes from 10.0.1.21 (10.0.1.21): icmp_seq=2 ttl=64 time=0.202 ms + 64 bytes from 10.0.1.21 (10.0.1.21): icmp_seq=3 ttl=64 time=0.203 ms + 64 bytes from 10.0.1.21 (10.0.1.21): icmp_seq=4 ttl=64 time=0.202 ms + + --- 10.0.1.21 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3000ms + rtt min/avg/max/mdev = 0.202/0.217/0.263/0.030 ms diff --git a/doc/install-guide-rst/source/basics-networking-nova.rst b/doc/install-guide-rst/source/basics-networking-nova.rst new file mode 100644 index 0000000000..4628e457aa --- /dev/null +++ b/doc/install-guide-rst/source/basics-networking-nova.rst @@ -0,0 +1,252 @@ +Legacy networking (nova-network) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The example architecture with legacy networking (nova-network) requires +a controller node and at least one compute node. The controller node +contains one network interface on the :term:`management network`. The +compute node contains one network interface on the management network +and one on the :term:`external network`. + +The example architecture assumes use of the following networks: + +- Management on 10.0.0.0/24 with gateway 10.0.0.1 + + .. note:: + + This network requires a gateway to provide Internet access to all + nodes for administrative purposes such as package installation, + security updates, :term:`DNS`, and :term:`Network Time Protocol (NTP)`. + +- External on 203.0.113.0/24 with gateway 203.0.113.1 + + .. note:: + + This network requires a gateway to provide Internet access to + instances in your OpenStack environment. + +You can modify these ranges and gateways to work with your particular +network infrastructure. + +.. note:: + + Network interface names vary by distribution. Traditionally, + interfaces use "eth" followed by a sequential number. To cover all + variations, this guide simply refers to the first interface as the + interface with the lowest number and the second interface as the + interface with the highest number. + +| + +:ref:`figure-nova-networks` + +| + +Unless you intend to use the exact configuration provided in this +example architecture, you must modify the networks in this procedure to +match your environment. Also, each node must resolve the other nodes by +name in addition to IP address. For example, the ``controller`` name must +resolve to ``10.0.0.11``, the IP address of the management interface on +the controller node. + +.. warning:: + + Reconfiguring network interfaces will interrupt network + connectivity. We recommend using a local terminal session for these + procedures. + +| + +Controller node +--------------- + +**To configure networking:** + +#. Configure the first interface as the management interface: + + IP address: 10.0.0.11 + + Network mask: 255.255.255.0 (or /24) + + Default gateway: 10.0.0.1 + +#. Reboot the system to activate the changes. + +| + +**To configure name resolution:** + +#. Set the hostname of the node to ``controller``. + +#. Edit the :file:`/etc/hosts` file to contain the following: + + .. code-block:: ini + + # controller + 10.0.0.11 controller + + # compute1 + 10.0.0.31 compute1 + + .. warning:: + + Some distributions add an extraneous entry in the :file:`/etc/hosts` + file that resolves the actual hostname to another loopback IP + address such as ``127.0.1.1``. You must comment out or remove this + entry to prevent name resolution problems. + +| + +Compute node +------------ + +**To configure networking:** + +#. Configure the first interface as the management interface: + + IP address: 10.0.0.31 + + Network mask: 255.255.255.0 (or /24) + + Default gateway: 10.0.0.1 + + .. note:: + + Additional compute nodes should use 10.0.0.32, 10.0.0.33, and so on. + +#. The external interface uses a special configuration without an IP + address assigned to it. Configure the second interface as the external + interface: + + Replace ``INTERFACE_NAME`` with the actual interface name. For example, + *eth1* or *ens224*. + + .. only:: ubuntu or debian + + a. Edit the :file:`/etc/network/interfaces` file to contain the following: + + .. code-block:: ini + + # The external network interface + auto INTERFACE_NAME + iface INTERFACE_NAME inet manual + up ip link set dev $IFACE up + down ip link set dev $IFACE down + + .. only:: rdo + + a. Edit the :file:`/etc/sysconfig/network-scripts/ifcfg-INTERFACE_NAME` file + to contain the following: + + Do not change the ``HWADDR`` and ``UUID`` keys. + + .. code-block:: ini + + DEVICE=INTERFACE_NAME + TYPE=Ethernet + ONBOOT="yes" + BOOTPROTO="none" + + .. only:: obs + + a. Edit the :file:`/etc/sysconfig/network/ifcfg-INTERFACE_NAME` file to + contain the following: + + .. code-block:: ini + + STARTMODE='auto' + BOOTPROTO='static' + +#. Reboot the system to activate the changes. + +| + +**To configure name resolution:** + +#. Set the hostname of the node to ``compute1``. + +#. Edit the :file:`/etc/hosts` file to contain the following: + + .. code-block:: ini + + # compute1 + 10.0.0.31 compute1 + + # controller + 10.0.0.11 controller + + .. warning:: + + Some distributions add an extraneous entry in the :file:`/etc/hosts` + file that resolves the actual hostname to another loopback IP + address such as ``127.0.1.1``. You must comment out or remove this + entry to prevent name resolution problems. + +| + +Verify connectivity +------------------- + +We recommend that you verify network connectivity to the Internet and +among the nodes before proceeding further. + +#. From the *controller* node, :command:`ping` a site on the Internet: + + .. code-block:: console + + # ping -c 4 openstack.org + PING openstack.org (174.143.194.225) 56(84) bytes of data. + 64 bytes from 174.143.194.225: icmp_seq=1 ttl=54 time=18.3 ms + 64 bytes from 174.143.194.225: icmp_seq=2 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=3 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=4 ttl=54 time=17.4 ms + + --- openstack.org ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3022ms + rtt min/avg/max/mdev = 17.489/17.715/18.346/0.364 ms + +#. From the *controller* node, :command:`ping` the management interface + on the *compute* node: + + .. code-block:: console + + # ping -c 4 compute1 + PING compute1 (10.0.0.31) 56(84) bytes of data. + 64 bytes from compute1 (10.0.0.31): icmp_seq=1 ttl=64 time=0.263 ms + 64 bytes from compute1 (10.0.0.31): icmp_seq=2 ttl=64 time=0.202 ms + 64 bytes from compute1 (10.0.0.31): icmp_seq=3 ttl=64 time=0.203 ms + 64 bytes from compute1 (10.0.0.31): icmp_seq=4 ttl=64 time=0.202 ms + + --- compute1 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3000ms + rtt min/avg/max/mdev = 0.202/0.217/0.263/0.030 ms + +#. From the *compute* node, ``ping`` a site on the Internet: + + .. code-block:: console + + # ping -c 4 openstack.org + PING openstack.org (174.143.194.225) 56(84) bytes of data. + 64 bytes from 174.143.194.225: icmp_seq=1 ttl=54 time=18.3 ms + 64 bytes from 174.143.194.225: icmp_seq=2 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=3 ttl=54 time=17.5 ms + 64 bytes from 174.143.194.225: icmp_seq=4 ttl=54 time=17.4 ms + + --- openstack.org ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3022ms + rtt min/avg/max/mdev = 17.489/17.715/18.346/0.364 ms + +#. From the *compute* node, :command:`ping` the management interface on the + *controller* node: + + .. code-block:: console + + # ping -c 4 controller + PING controller (10.0.0.11) 56(84) bytes of data. + 64 bytes from controller (10.0.0.11): icmp_seq=1 ttl=64 time=0.263 ms + 64 bytes from controller (10.0.0.11): icmp_seq=2 ttl=64 time=0.202 ms + 64 bytes from controller (10.0.0.11): icmp_seq=3 ttl=64 time=0.203 ms + 64 bytes from controller (10.0.0.11): icmp_seq=4 ttl=64 time=0.202 ms + + --- controller ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3000ms + rtt min/avg/max/mdev = 0.202/0.217/0.263/0.030 ms diff --git a/doc/install-guide-rst/source/basics-networking.rst b/doc/install-guide-rst/source/basics-networking.rst new file mode 100644 index 0000000000..4fd7873d82 --- /dev/null +++ b/doc/install-guide-rst/source/basics-networking.rst @@ -0,0 +1,83 @@ +Networking +~~~~~~~~~~ + +After installing the operating system on each node for the architecture +that you choose to deploy, you must configure the network interfaces. We +recommend that you disable any automated network management tools and +manually edit the appropriate configuration files for your distribution. +For more information on how to configure networking on your +distribution, see the + +.. only:: ubuntu + + `documentation. `__ + +.. only:: debian + + `documentation. `__ + +.. only:: rdo + + `documentation. `__ + +.. only:: obs + + `SLES 12 `__ + or `openSUSE `__ documentation. + +All nodes require Internet access for administrative purposes such as +package installation, security updates, :term:`DNS`, and +:term:`Network Time Protocol (NTP)`. In most cases, +nodes should obtain Internet access through the management network +interface. To highlight the importance of network separation, the +example architectures use `private address +space `__ for the management +network and assume that network infrastructure provides Internet access +via :term:`Network Address Translation (NAT)`. To illustrate the flexibility +of :term:`IaaS`, the example architectures use public IP address space +for the external network and assume that network infrastructure provides +direct Internet access to instances in your OpenStack environment. +In environments with only one block of public IP address space, +both the management and external networks must ultimately obtain Internet +access using it. For simplicity, the diagrams in this guide only show +Internet access for OpenStack services. + +.. only:: obs + + **To disable Network Manager** + + * Use the YaST network module: + + .. code-block:: console + + # yast2 network + + For more information, see the + `SLES `__ + or the `openSUSE `__ documentation. + +.. note:: + + .. only:: rdo or obs + + Your distribution enables a restrictive :term:`firewall` by + default. During the installation process, certain steps will + fail unless you alter or disable the firewall. For more + information about securing your environment, refer to the + `OpenStack Security Guide `__. + + .. only:: ubuntu or debian + + Your distribution does not enable a restrictive :term:`firewall` + by default. For more information about securing your environment, + refer to the + `OpenStack Security Guide `__. + +.. include:: basics-networking-neutron.rst +.. include:: basics-networking-nova.rst + +.. toctree:: + :hidden: + + basics-networking-neutron.rst + basics-networking-nova.rst diff --git a/doc/install-guide-rst/source/basics-ntp.rst b/doc/install-guide-rst/source/basics-ntp.rst new file mode 100644 index 0000000000..61b2bd130c --- /dev/null +++ b/doc/install-guide-rst/source/basics-ntp.rst @@ -0,0 +1,218 @@ +.. highlight:: ini + :linenothreshold: 1 + + +Network Time Protocol (NTP) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must install :term:`Network Time Protocol (NTP)` to properly +synchronize services among nodes. We recommend that you configure +the controller node to reference more accurate (lower stratum) +servers and other nodes to reference the controller node. + + +Controller node +--------------- + +**To install the NTP service** + +.. only:: ubuntu or debian + + .. code-block:: console + + # apt-get install ntp + +.. only:: rdo + + .. code-block:: console + + # yum install ntp + +.. only:: obs + + .. code-block:: console + + # zypper install ntp + +| + +**To configure the NTP service** + +By default, the controller node synchronizes the time via a pool of +public servers. However, you can optionally edit the :file:`/etc/ntp.conf` +file to configure alternative servers such as those provided by your +organization. + +1. Edit the :file:`/etc/ntp.conf` file and add, change, or remove the following + keys as necessary for your environment: + + .. code:: ini + + server NTP_SERVER iburst + restrict -4 default kod notrap nomodify + restrict -6 default kod notrap nomodify + + Replace ``NTP_SERVER`` with the hostname or IP address of a suitable more + accurate (lower stratum) NTP server. The configuration supports multiple + ``server`` keys. + + .. note:: + + For the ``restrict`` keys, you essentially remove the ``nopeer`` + and ``noquery`` options. + + .. only:: ubuntu or debian + + .. note:: + + Remove the :file:`/var/lib/ntp/ntp.conf.dhcp` file if it exists. + +.. only:: ubuntu or debian + + 2. Restart the NTP service: + + .. code-block:: console + + # service ntp restart + +.. only:: rdo or obs + + 2. Start the NTP service and configure it to start when the system boots: + + .. code-block:: console + + # systemctl enable ntpd.service + # systemctl start ntpd.service + +| + +Other nodes +----------- + +**To install the NTP service** + +.. only:: ubuntu or debian + + .. code-block:: console + + # apt-get install ntp + +.. only:: rdo + + .. code-block:: console + + # yum install ntp + +.. only:: obs + + .. code-block:: console + + # zypper install ntp + +| + +**To configure the NTP service** + +Configure the network and compute nodes to reference the controller +node. + +1. Edit the :file:`/etc/ntp.conf` file: + + Comment out or remove all but one ``server`` key and change it to + reference the controller node. + + .. code:: ini + + server controller iburst + + .. only:: ubuntu or debian + + .. note:: + + Remove the :file:`/var/lib/ntp/ntp.conf.dhcp` file if it exists. + +.. only:: ubuntu or debian + + 2. Restart the NTP service: + + .. code-block:: console + + # service ntp restart + +.. only:: rdo or obs + + 2. Start the NTP service and configure it to start when the system + boots: + + .. code-block:: console + + # systemctl enable ntpd.service + # systemctl start ntpd.service + +| + +Verify operation +---------------- + +We recommend that you verify NTP synchronization before proceeding +further. Some nodes, particularly those that reference the controller +node, can take several minutes to synchronize. + +#. Run this command on the *controller* node: + + .. code-block:: console + + # ntpq -c peers + remote refid st t when poll reach delay offset jitter + =========================================================================== + *ntp-server1 192.0.2.11 2 u 169 1024 377 1.901 -0.611 5.483 + +ntp-server2 192.0.2.12 2 u 887 1024 377 0.922 -0.246 2.864 + + Contents in the *remote* column should indicate the hostname or IP + address of one or more NTP servers. + + .. note:: + + Contents in the *refid* column typically reference IP addresses of + upstream servers. + +#. Run this command on the *controller* node: + + .. code-block:: console + + # ntpq -c assoc + ind assid status conf reach auth condition last_event cnt + =========================================================== + 1 20487 961a yes yes none sys.peer sys_peer 1 + 2 20488 941a yes yes none candidate sys_peer 1 + + Contents in the *condition* column should indicate ``sys.peer`` for at + least one server. + +#. Run this command on *all other* nodes: + + .. code-block:: console + + # ntpq -c peers + remote refid st t when poll reach delay offset jitter + ========================================================================= + *controller 192.0.2.21 3 u 47 64 37 0.308 -0.251 0.079 + + Contents in the *remote* column should indicate the hostname of the + controller node. + + .. note:: + + Contents in the *refid* column typically reference IP addresses of + upstream servers. + +#. Run this command on *all other* nodes: + + .. code-block:: console + + # ntpq -c assoc + ind assid status conf reach auth condition last_event cnt + =========================================================== + 1 21181 963a yes yes none sys.peer sys_peer 3 + + Contents in the *condition* column should indicate ``sys.peer``. diff --git a/doc/install-guide-rst/source/overview.rst b/doc/install-guide-rst/source/overview.rst index 51a68bad90..d51a823551 100644 --- a/doc/install-guide-rst/source/overview.rst +++ b/doc/install-guide-rst/source/overview.rst @@ -202,6 +202,8 @@ optional services. This guide uses the following example architectures: | +.. _figure-neutron-networks: + .. figure:: figures/installguidearch-neutron-networks.png :alt: Minimal architecture example with OpenStack Networking (neutron)—Network layout @@ -285,6 +287,8 @@ optional services. This guide uses the following example architectures: | +.. _figure-nova-networks: + .. figure:: figures/installguidearch-nova-networks.png :alt: Minimal architecture example with legacy networking (nova-network)—Network layout