openstack-manuals/doc/install-guide/section_neutron-controller-node.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  version="5.0"
  xml:id="neutron-controller-node">
  <title>Install and configure controller node</title>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To configure prerequisites</title>
    <para>Before you configure the OpenStack Networking (neutron) service,
      you must create a database, service credentials, and API
      endpoint.</para>
    <step>
      <para>To create the database, complete these steps:</para>
      <substeps>
        <step>
          <para>Use the database access client to connect to the database
            server as the <literal>root</literal> user:</para>
          <screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput></screen>
        </step>
        <step>
          <para>Create the <literal>neutron</literal> database:</para>
          <screen><userinput>CREATE DATABASE neutron;</userinput></screen>
        </step>
        <step>
          <para>Grant proper access to the <literal>neutron</literal>
            database:</para>
          <screen><userinput>GRANT ALL PRIVILEGES ON neutron.* TO 'neutron'@'localhost' \
  IDENTIFIED BY '<replaceable>NEUTRON_DBPASS</replaceable>';</userinput>
<userinput>GRANT ALL PRIVILEGES ON neutron.* TO 'neutron'@'%' \
  IDENTIFIED BY '<replaceable>NEUTRON_DBPASS</replaceable>';</userinput></screen>
          <para>Replace <replaceable>NEUTRON_DBPASS</replaceable> with a
            suitable password.</para>
        </step>
        <step>
          <para>Exit the database access client.</para>
        </step>
      </substeps>
    </step>
    <step>
      <para>Source the <literal>admin</literal> credentials to gain access to
        admin-only CLI commands:</para>
      <screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
    </step>
    <step>
      <para>To create the service credentials, complete these steps:</para>
      <substeps>
        <step>
          <para>Create the <literal>neutron</literal> user:</para>
          <screen><prompt>$</prompt> <userinput>openstack user create --password-prompt neutron</userinput>
<computeroutput>User Password:
Repeat User Password:
+----------+----------------------------------+
| Field    | Value                            |
+----------+----------------------------------+
| email    | None                             |
| enabled  | True                             |
| id       | ab67f043d9304017aaa73d692eeb4945 |
| name     | neutron                          |
| username | neutron                          |
+----------+----------------------------------+</computeroutput></screen>
        </step>
        <step>
          <para>Add the <literal>admin</literal> role to the
            <literal>neutron</literal> user:</para>
          <screen><prompt>$</prompt> <userinput>openstack role add --project service --user neutron admin</userinput>
<computeroutput>+-------+----------------------------------+
| Field | Value                            |
+-------+----------------------------------+
| id    | cd2cb9a39e874ea69e5d4b896eb16128 |
| name  | admin                            |
+-------+----------------------------------+</computeroutput></screen>
        </step>
        <step>
          <para>Create the <literal>neutron</literal> service entity:</para>
          <screen><prompt>$</prompt> <userinput>openstack service create --name neutron \
  --description "OpenStack Networking" network</userinput></screen>
<screen><computeroutput>+-------------+----------------------------------+
| Field       | Value                            |
+-------------+----------------------------------+
| description | OpenStack Networking             |
| enabled     | True                             |
| id          | f71529314dab4a4d8eca427e701d209e |
| name        | neutron                          |
| type        | network                          |
+-------------+----------------------------------+</computeroutput></screen>
        </step>
      </substeps>
    </step>
    <step>
      <para>Create the Networking service API endpoint:</para>
      <screen><prompt>$</prompt> <userinput>openstack endpoint create \
  --publicurl http://<replaceable>controller</replaceable>:9696 \
  --adminurl http://<replaceable>controller</replaceable>:9696 \
  --internalurl http://<replaceable>controller</replaceable>:9696 \
  --region RegionOne \
  network</userinput>
<computeroutput>+--------------+----------------------------------+
| Field        | Value                            |
+--------------+----------------------------------+
| adminurl     | http://controller:9696           |
| id           | 04a7d3c1de784099aaba83a8a74100b3 |
| internalurl  | http://controller:9696           |
| publicurl    | http://controller:9696           |
| region       | RegionOne                        |
| service_id   | f71529314dab4a4d8eca427e701d209e |
| service_name | neutron                          |
| service_type | network                          |
+--------------+----------------------------------+</computeroutput></screen>
    </step>
  </procedure>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To install the Networking components</title>
    <step>
      <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install neutron-server neutron-plugin-ml2 python-neutronclient</userinput></screen>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-neutron openstack-neutron-ml2 python-neutronclient which</userinput></screen>
      <screen os="sles;opensuse"><prompt>#</prompt> <userinput>zypper install openstack-neutron openstack-neutron-server</userinput></screen>
      <note os="sles;opensuse">
        <para>SUSE does not use a separate ML2 plug-in package.</para>
      </note>
    </step>
  </procedure>
  <procedure os="debian">
    <title>To install and configure the Networking components</title>
    <step>
      <screen><prompt>#</prompt> <userinput>apt-get install neutron-server</userinput></screen>
      <note>
        <para>Debian does not use a separate ML2 plug-in package.</para>
      </note>
    </step>
    <step>
      <para>Respond to prompts for
        <link linkend="debconf-dbconfig-common">database management</link>,
        <link linkend="debconf-keystone_authtoken">Identity service
        credentials</link>,
        <link linkend="debconf-api-endpoints">service endpoint
        registration</link>, and
        <link linkend="debconf-rabbitmq">message queue
        credentials</link>.</para>
    </step>
    <step>
       <para>Select the ML2 plug-in:</para>
       <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/neutron_1_plugin_selection.png"
            />
          </imageobject>
        </mediaobject>
      </informalfigure>
      <note>
        <para>Selecting the ML2 plug-in also populates the
          <option>service_plugins</option> and
          <option>allow_overlapping_ips</option> options in the
          <filename>/etc/neutron/neutron.conf</filename> file with the
          appropriate values.</para>
      </note>
    </step>
  </procedure>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To configure the Networking server component</title>
    <para>The Networking server component configuration includes the database,
      authentication mechanism, message queue, topology change notifications,
      and plug-in.</para>
    <note>
       <para>Default configuration files vary by distribution. You might need
         to add these sections and options rather than modifying existing
         sections and options. Also, an ellipsis (...) in the configuration
         snippets indicates potential default configuration options that you
         should retain.</para>
    </note>
    <step>
      <para>Edit the <filename>/etc/neutron/neutron.conf</filename> file
        and complete the following actions:</para>
      <substeps>
        <step>
          <para>In the <literal>[database]</literal> section, configure
            database access:</para>
          <programlisting language="ini">[database]
...
connection = mysql://neutron:<replaceable>NEUTRON_DBPASS</replaceable>@<replaceable>controller</replaceable>/neutron</programlisting>
          <para>Replace <replaceable>NEUTRON_DBPASS</replaceable> with the
            password you chose for the database.</para>
        </step>
        <step>
          <para>In the <literal>[DEFAULT]</literal> and
            <literal>[oslo_messaging_rabbit]</literal> sections, configure
            <application>RabbitMQ</application> message queue access:</para>
          <programlisting language="ini">[DEFAULT]
...
rpc_backend = rabbit

[oslo_messaging_rabbit]
...
rabbit_host = <replaceable>controller</replaceable>
rabbit_userid = openstack
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
          <para>Replace <replaceable>RABBIT_PASS</replaceable> with the
            password you chose for the <literal>openstack</literal> account
            in <application>RabbitMQ</application>.</para>
        </step>
        <step>
          <para>In the <literal>[DEFAULT]</literal> and
            <literal>[keystone_authtoken]</literal> sections,
            configure Identity service access:</para>
          <programlisting language="ini">[DEFAULT]
...
auth_strategy = keystone

[keystone_authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000
auth_url = http://<replaceable>controller</replaceable>:35357
auth_plugin = password
project_domain_id = default
user_domain_id = default
project_name = service
username = neutron
password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
          <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
            password you chose for the <literal>neutron</literal> user in the
            Identity service.</para>
          <note>
            <para>Comment out or remove any other options in the
              <literal>[keystone_authtoken]</literal> section.</para>
          </note>
        </step>
        <step>
          <para>In the <literal>[DEFAULT]</literal> section, enable the
            Modular Layer 2 (ML2) plug-in, router service, and overlapping
            IP addresses:</para>
          <programlisting language="ini">[DEFAULT]
...
core_plugin = ml2
service_plugins = router
allow_overlapping_ips = True</programlisting>
        </step>
        <step>
          <para>In the <literal>[DEFAULT]</literal> and
            <literal>[nova]</literal> sections, configure
            Networking to notify Compute of network topology changes:</para>
          <programlisting language="ini">[DEFAULT]
...
notify_nova_on_port_status_changes = True
notify_nova_on_port_data_changes = True
nova_url = http://<replaceable>controller</replaceable>:8774/v2

[nova]
...
auth_url = http://<replaceable>controller</replaceable>:35357
auth_plugin = password
project_domain_id = default
user_domain_id = default
region_name = RegionOne
project_name = service
username = nova
password = <replaceable>NOVA_PASS</replaceable></programlisting>
          <para>Replace <literal>NOVA_PASS</literal> with the password
            you chose for the <literal>nova</literal> user in the Identity
            service.</para>
        </step>
        <step>
          <para>(Optional) To assist with troubleshooting,
            enable verbose logging in the <literal>[DEFAULT]</literal>
            section:</para>
          <programlisting language="ini">[DEFAULT]
...
verbose = True</programlisting>
        </step>
      </substeps>
    </step>
  </procedure>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To configure the Modular Layer 2 (ML2) plug-in</title>
    <para>The ML2 plug-in uses the
      <glossterm baseform="Open vSwitch">Open vSwitch (OVS)</glossterm>
      mechanism (agent) to build the virtual networking framework for
      instances. However, the controller node does not need the OVS
      components because it does not handle instance network traffic.</para>
    <step>
      <para>Edit the
        <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>
        file and complete the following actions:</para>
      <substeps>
        <step>
          <para>In the <literal>[ml2]</literal> section, enable the
            <glossterm baseform="flat network">flat</glossterm>,
            <glossterm baseform="VLAN network">VLAN</glossterm>,
            <glossterm>generic routing encapsulation (GRE)</glossterm>, and
            <glossterm>virtual extensible LAN (VXLAN)</glossterm>
            network type drivers, GRE tenant networks, and the OVS
            mechanism driver:</para>
          <programlisting language="ini">[ml2]
...
type_drivers = flat,vlan,gre,vxlan
tenant_network_types = gre
mechanism_drivers = openvswitch</programlisting>
          <warning>
            <para>Once you configure the ML2 plug-in, changing values in
              the <literal>type_drivers</literal> option can lead to
              database inconsistency.</para>
          </warning>
        </step>
        <step>
          <para>In the <literal>[ml2_type_gre]</literal> section, configure
            the tunnel identifier (id) range:</para>
          <programlisting language="ini">[ml2_type_gre]
...
tunnel_id_ranges = 1:1000</programlisting>
        </step>
        <step>
          <para>In the <literal>[securitygroup]</literal> section, enable
            security groups, enable <glossterm>ipset</glossterm>, and
            configure the OVS <glossterm>iptables</glossterm> firewall
            driver:</para>
          <programlisting language="ini">[securitygroup]
...
enable_security_group = True
enable_ipset = True
firewall_driver = neutron.agent.linux.iptables_firewall.OVSHybridIptablesFirewallDriver</programlisting>
        </step>
      </substeps>
    </step>
  </procedure>
  <procedure>
    <title>To configure Compute to use Networking</title>
    <para>By default, distribution packages configure Compute to use legacy
      networking. You must reconfigure Compute to manage networks through
      Networking.</para>
    <step>
      <para>Edit the <filename>/etc/nova/nova.conf</filename> file on the controller
        node and complete the following actions:</para>
      <substeps>
        <step os="ubuntu;rhel;centos;fedora;sles;opensuse">
          <para>In the <literal>[DEFAULT]</literal> section, configure
            the <glossterm baseform="API">APIs</glossterm> and drivers:</para>
          <programlisting language="ini">[DEFAULT]
...
network_api_class = nova.network.neutronv2.api.API
security_group_api = neutron
linuxnet_interface_driver = nova.network.linux_net.LinuxOVSInterfaceDriver
firewall_driver = nova.virt.firewall.NoopFirewallDriver</programlisting>
          <note>
            <para>By default, Compute uses an internal firewall service.
              Since Networking includes a firewall service, you must
              disable the Compute firewall service by using the
              <literal>nova.virt.firewall.NoopFirewallDriver</literal>
              firewall driver.</para>
          </note>
        </step>
        <step>
          <para>In the <literal>[neutron]</literal> section, configure
            access parameters:</para>
          <programlisting language="ini">[neutron]
...
url = http://<replaceable>controller</replaceable>:9696
auth_strategy = keystone
admin_auth_url = http://<replaceable>controller</replaceable>:35357/v2.0
admin_tenant_name = service
admin_username = neutron
admin_password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
          <para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
            password you chose for the <literal>neutron</literal> user
            in the Identity service.</para>
        </step>
      </substeps>
    </step>
  </procedure>
  <procedure>
    <title>To finalize installation</title>
    <step os="rhel;centos;fedora">
      <para>The Networking service initialization scripts expect a
        symbolic link <filename>/etc/neutron/plugin.ini</filename>
        pointing to the ML2 plug-in configuration file,
        <filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>.
        If this symbolic link does not exist, create it using the
        following command:</para>
    <screen><prompt>#</prompt> <userinput>ln -s /etc/neutron/plugins/ml2/ml2_conf.ini /etc/neutron/plugin.ini</userinput></screen>
    </step>
    <step os="sles;opensuse">
      <para>The Networking service initialization scripts expect the
        variable <literal>NEUTRON_PLUGIN_CONF</literal> in the
        <filename>/etc/sysconfig/neutron</filename> file to
        reference the ML2 plug-in configuration file. Edit the
        <filename>/etc/sysconfig/neutron</filename> file and add the
        following:</para>
      <programlisting>NEUTRON_PLUGIN_CONF="/etc/neutron/plugins/ml2/ml2_conf.ini"</programlisting>
    </step>
    <step os="ubuntu;rhel;centos;fedora">
      <para>Populate the database:</para>
      <!-- FIXME: Change database version from 'head' to 'kilo' after
           release. -->
      <screen><prompt>#</prompt> <userinput>su -s /bin/sh -c "neutron-db-manage --config-file /etc/neutron/neutron.conf \
  --config-file /etc/neutron/plugins/ml2/ml2_conf.ini upgrade head" neutron</userinput></screen>
      <note>
        <para>Database population occurs later for Networking because the
          script requires complete server and plug-in configuration
          files.</para>
      </note>
    </step>
    <step>
      <para>Restart the Compute services:</para>
      <screen os="rhel;centos;fedora;opensuse;sles"><prompt>#</prompt> <userinput>systemctl restart openstack-nova-api.service openstack-nova-scheduler.service \
  openstack-nova-conductor.service</userinput></screen>
      <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>service nova-api restart</userinput></screen>
    </step>
    <step os="rhel;centos;fedora">
      <para>Start the Networking service and configure it to start when the
        system boots:</para>
      <screen><prompt>#</prompt> <userinput>systemctl enable neutron-server.service</userinput>
<prompt>#</prompt> <userinput>systemctl start neutron-server.service</userinput></screen>
    </step>
    <step os="sles;opensuse">
      <para>Start the Networking service and configure it to start when the
        system boots:</para>
      <screen><prompt>#</prompt> <userinput>systemctl enable openstack-neutron.service</userinput>
<prompt>#</prompt> <userinput>systemctl start openstack-neutron.service</userinput></screen>
    </step>
    <step os="ubuntu;debian">
      <para>Restart the Networking service:</para>
      <screen><prompt>#</prompt> <userinput>service neutron-server restart</userinput></screen>
    </step>
  </procedure>
  <procedure>
    <title>Verify operation</title>
    <note>
      <para>Perform these commands on the controller node.</para>
    </note>
    <step>
      <para>Source the <literal>admin</literal> credentials to gain access to
        admin-only CLI commands:</para>
      <screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
    </step>
    <step>
      <para>List loaded extensions to verify successful launch of the
        <literal>neutron-server</literal> process:</para>
      <screen><prompt>$</prompt> <userinput>neutron ext-list</userinput>
<computeroutput>+-----------------------+-----------------------------------------------+
| alias                 | name                                          |
+-----------------------+-----------------------------------------------+
| security-group        | security-group                                |
| l3_agent_scheduler    | L3 Agent Scheduler                            |
| ext-gw-mode           | Neutron L3 Configurable external gateway mode |
| binding               | Port Binding                                  |
| provider              | Provider Network                              |
| agent                 | agent                                         |
| quotas                | Quota management support                      |
| dhcp_agent_scheduler  | DHCP Agent Scheduler                          |
| l3-ha                 | HA Router extension                           |
| multi-provider        | Multi Provider Network                        |
| external-net          | Neutron external network                      |
| router                | Neutron L3 Router                             |
| allowed-address-pairs | Allowed Address Pairs                         |
| extraroute            | Neutron Extra Route                           |
| extra_dhcp_opt        | Neutron Extra DHCP opts                       |
| dvr                   | Distributed Virtual Router                    |
+-----------------------+-----------------------------------------------+</computeroutput></screen>
    </step>
  </procedure>
</section>