openstack/openstack-manuals
Code Issues Proposed changes
cda14042c8
openstack-manuals/doc/admin-guide-cloud/section_networking_adv_features.xml
nerminamiller eefd494d0b Move Networking scenarios section from Configuration Reference to Cloud Admin Guide 
Moved networking-config-identity, networking-scenarios,
networking-adv-config, networking-multi-dhcp-agents from Config Ref to
Networking ch of Cloud Admin Guide

Change-Id: I1c14e9b7017fee976c2c80b6f0c8c7bcb15eb046
backport: none
Closes-Bug: #1255295
author: nermina miller
2014-01-03 15:49:46 -05:00

2194 lines
108 KiB
XML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?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="section_networking-adv-features">
<title>Advanced features through API extensions</title>
<para>Several plug-ins implement API extensions that provide
capabilities similar to what was available in nova-network:
These plug-ins are likely to be of interest to the OpenStack
community.</para>
<section xml:id="section_provider_networks">
<title>Provider networks</title>
<para>Provider networks enable cloud administrators to create
Networking networks that map directly to the physical
networks in the data center. This is commonly used to give
tenants direct access to a public network that can be used
to reach the Internet. It might also be used to integrate
with VLANs in the network that already have a defined
meaning (for example, enable a VM from the "marketing"
department to be placed on the same VLAN as bare-metal
marketing hosts in the same data center).</para>
<para>The provider extension allows administrators to
explicitly manage the relationship between Networking
virtual networks and underlying physical mechanisms such
as VLANs and tunnels. When this extension is supported,
Networking client users with administrative privileges see
additional provider attributes on all virtual networks,
and are able to specify these attributes in order to
create provider networks.</para>
<para>The provider extension is supported by the Open vSwitch
and Linux Bridge plug-ins. Configuration of these plug-ins
requires familiarity with this extension.</para>
<section xml:id="provider_terminology">
<title>Terminology</title>
<para>A number of terms are used in the provider extension
and in the configuration of plug-ins supporting the
provider extension:</para>
<table rules="all">
<caption>Provider extension terminology</caption>
<col width="20%"/>
<col width="80%"/>
<thead>
<tr>
<th>Term</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><emphasis role="bold">virtual
network</emphasis></td>
<td>An Networking L2 network (identified by a
UUID and optional name) whose ports can be
attached as vNICs to Compute instances and
to various Networking agents. The Open
vSwitch and Linux Bridge plug-ins each
support several different mechanisms to
realize virtual networks.</td>
</tr>
<tr>
<td><emphasis role="bold">physical
network</emphasis></td>
<td>A network connecting virtualization hosts
(such as, Compute nodes) with each other
and with other network resources. Each
physical network might support multiple
virtual networks. The provider extension
and the plug-in configurations identify
physical networks using simple string
names.</td>
</tr>
<tr>
<td><emphasis role="bold">tenant
network</emphasis></td>
<td>A virtual network that a tenant or an
administrator creates. The physical
details of the network are not exposed to
the tenant.</td>
</tr>
<tr>
<td><emphasis role="bold">provider
network</emphasis></td>
<td>A virtual network administratively created
to map to a specific network in the data
center, typically to enable direct access
to non-OpenStack resources on that
network. Tenants can be given access to
provider networks.</td>
</tr>
<tr>
<td><emphasis role="bold">VLAN
network</emphasis></td>
<td>A virtual network implemented as packets
on a specific physical network containing
IEEE 802.1Q headers with a specific VID
field value. VLAN networks sharing the
same physical network are isolated from
each other at L2, and can even have
overlapping IP address spaces. Each
distinct physical network supporting VLAN
networks is treated as a separate VLAN
trunk, with a distinct space of VID
values. Valid VID values are 1 through
4094.</td>
</tr>
<tr>
<td><emphasis role="bold">flat
network</emphasis></td>
<td>A virtual network implemented as packets
on a specific physical network containing
no IEEE 802.1Q header. Each physical
network can realize at most one flat
network.</td>
</tr>
<tr>
<td><emphasis role="bold">local
network</emphasis></td>
<td>A virtual network that allows
communication within each host, but not
across a network. Local networks are
intended mainly for single-node test
scenarios, but can have other uses.</td>
</tr>
<tr>
<td><emphasis role="bold">GRE
network</emphasis></td>
<td>A virtual network implemented as network
packets encapsulated using GRE. GRE
networks are also referred to as <emphasis
role="italic">tunnels</emphasis>. GRE
tunnel packets are routed by the IP
routing table for the host, so GRE
networks are not associated by Networking
with specific physical networks.</td>
</tr>
<tr>
<td><emphasis role="bold">Virtual Extensible
LAN (VXLAN) network</emphasis></td>
<td>VXLAN is a proposed encapsulation protocol
for running an overlay network on existing
Layer 3 infrastructure. An overlay network
is a virtual network that is built on top
of existing network Layer 2 and Layer 3
technologies to support elastic compute
architectures.</td>
</tr>
</tbody>
</table>
<para>The ML2, Open vSwitch, and Linux Bridge plug-ins
support VLAN networks, flat networks, and local
networks. Only the ML2 and Open vSwitch plug-ins
currently support GRE and VXLAN networks, provided
that the required features exist in the hosts Linux
kernel, Open vSwitch, and iproute2 packages.</para>
</section>
<section xml:id="provider_attributes">
<title>Provider attributes</title>
<para>The provider extension extends the Networking
network resource with these attributes:</para>
<table rules="all">
<caption>Provider network attributes</caption>
<col width="25%"/>
<col width="10%"/>
<col width="25%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>provider:network_type</td>
<td>String</td>
<td>N/A</td>
<td>The physical mechanism by which the
virtual network is implemented. Possible
values are <literal>flat</literal>,
<literal>vlan</literal>,
<literal>local</literal>, and
<literal>gre</literal>, corresponding
to flat networks, VLAN networks, local
networks, and GRE networks as defined
above. All types of provider networks can
be created by administrators, while tenant
networks can be implemented as
<literal>vlan</literal>,
<literal>gre</literal>, or
<literal>local</literal> network types
depending on plug-in configuration.</td>
</tr>
<tr>
<td>provider:physical_network</td>
<td>String</td>
<td>If a physical network named "default" has
been configured, and if
provider:network_type is
<literal>flat</literal> or
<literal>vlan</literal>, then
"default" is used.</td>
<td>The name of the physical network over
which the virtual network is implemented
for flat and VLAN networks. Not applicable
to the <literal>local</literal> or
<literal>gre</literal> network
types.</td>
</tr>
<tr>
<td>provider:segmentation_id</td>
<td>Integer</td>
<td>N/A</td>
<td>For VLAN networks, the VLAN VID on the
physical network that realizes the virtual
network. Valid VLAN VIDs are 1 through
4094. For GRE networks, the tunnel ID.
Valid tunnel IDs are any 32 bit unsigned
integer. Not applicable to the
<literal>flat</literal> or
<literal>local</literal> network
types.</td>
</tr>
</tbody>
</table>
<para>To view or set provider extended attributes, a
client must be authorized for the
<code>extension:provider_network:view</code> and
<code>extension:provider_network:set</code>
actions in the Networking policy configuration. The
default Networking configuration authorizes both
actions for users with the admin role. An authorized
client or an administrative user can view and set the
provider extended attributes through Networking API
calls. See <xref linkend="section_networking_auth"/> for details
on policy configuration.</para>
</section>
<section xml:id="provider_api_workflow">
<title>Provider extension API operations</title>
<para>To use the provider extension with the default
policy settings, you must have the administrative
role.</para>
<para>This table shows example neutron commands that
enable you to complete basic provider extension API
operations:</para>
<table rules="all">
<caption>Basic provider extension API
operations</caption>
<col width="40%"/>
<col width="60%"/>
<thead>
<tr>
<th>Operation</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>Shows all attributes of a network,
including provider
attributes.</para></td>
<td>
<screen><prompt>$</prompt> <userinput>neutron net-show &lt;name or net-id&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Creates a local provider
network.</para></td>
<td>
<screen><prompt>$</prompt> <userinput>neutron net-create &lt;name&gt; --tenant_id &lt;tenant-id&gt; --provider:network_type local</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Creates a flat provider network.
When you create flat networks,
&lt;phys-net-name&gt; must be known to
the plug-in. See the <citetitle
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml"
>OpenStack Configuration
Reference</citetitle> for
details.</para></td>
<td>
<screen><prompt>$</prompt> <userinput>neutron net-create &lt;name&gt; --tenant_id &lt;tenant-id&gt; --provider:network_type flat --provider:physical_network &lt;phys-net-name&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Creates a VLAN provider network.
When you create VLAN networks,
&lt;phys-net-name&gt; must be known to
the plug-in. See the <citetitle
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml"
>OpenStack Configuration
Reference</citetitle> for details
on configuring network_vlan_ranges to
identify all physical networks. When
you create VLAN networks, &lt;VID&gt;
can fall either within or outside any
configured ranges of VLAN IDs from
which tenant networks are
allocated.</para></td>
<td>
<screen><prompt>$</prompt> <userinput>neutron net-create &lt;name&gt; --tenant_id &lt;tenant-id&gt; --provider:network_type vlan --provider:physical_network &lt;phys-net-name&gt; --provider:segmentation_id &lt;VID&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Creates a GRE provider network. When
you create GRE networks,
&lt;tunnel-id&gt; can be either inside
or outside any tunnel ID ranges from
which tenant networks are
allocated.</para>
<para>After you create provider networks,
you can allocate subnets, which you
can use in the same way as other
virtual networks, subject to
authorization policy based on the
specified
&lt;tenant_id&gt;.</para></td>
<td>
<screen><prompt>$</prompt> <userinput>neutron net-create &lt;name&gt; --tenant_id &lt;tenant-id&gt; --provider:network_type gre --provider:segmentation_id &lt;tunnel-id&gt;</userinput></screen>
</td>
</tr>
</tbody>
</table>
</section>
</section>
<section xml:id="section_l3_router_and_nat">
<title>L3 routing and NAT</title>
<para>The Networking API provides abstract L2 network segments
that are decoupled from the technology used to implement
the L2 network. Networking includes an API extension that
provides abstract L3 routers that API users can
dynamically provision and configure. These Networking
routers can connect multiple L2 Networking networks, and
can also provide a gateway that connects one or more
private L2 networks to a shared external network. For
example, a public network for access to the Internet. See
the <citetitle xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml">OpenStack
Configuration Reference</citetitle> for details on
common models of deploying Networking L3 routers.</para>
<para>The L3 router provides basic NAT capabilities on gateway
ports that uplink the router to external networks. This
router SNATs all traffic by default, and supports floating
IPs, which creates a static one-to-one mapping from a
public IP on the external network to a private IP on one
of the other subnets attached to the router. This allows a
tenant to selectively expose VMs on private networks to
other hosts on the external network (and often to all
hosts on the Internet). You can allocate and map floating
IPs from one port to another, as needed.</para>
<?hard-pagebreak?>
<section xml:id="l3_api_abstractions">
<title>L3 API abstractions</title>
<table rules="all">
<caption>Router</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the router.</td>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>None</td>
<td>Human-readable name for the router. Might
not be unique.</td>
</tr>
<tr>
<td>admin_state_up</td>
<td>Bool</td>
<td>True</td>
<td>The administrative state of router. If
false (down), the router does not forward
packets.</td>
</tr>
<tr>
<td>status</td>
<td>String</td>
<td>N/A</td>
<td><para>Indicates whether router is
currently operational.</para></td>
</tr>
<tr>
<td>tenant_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>Owner of the router. Only admin users can
specify a tenant_id other than its
own.</td>
</tr>
<tr>
<td>external_gateway_info</td>
<td>dict contain 'network_id' key-value
pair</td>
<td>Null</td>
<td>External network that this router connects
to for gateway services (for example,
NAT)</td>
</tr>
</tbody>
</table>
<table rules="all">
<caption>Floating IP</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the floating IP.</td>
</tr>
<tr>
<td>floating_ip_address</td>
<td>string (IP address)</td>
<td>allocated by Networking</td>
<td>The external network IP address available
to be mapped to an internal IP
address.</td>
</tr>
<tr>
<td>floating_network_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td><para>The network indicating the set of
subnets from which the floating IP
should be allocated</para></td>
</tr>
<tr>
<td>router_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>Read-only value indicating the router that
connects the external network to the
associated internal port, if a port is
associated.</td>
</tr>
<tr>
<td>port_id</td>
<td>uuid-str</td>
<td>Null</td>
<td>Indicates the internal Networking port
associated with the external floating
IP.</td>
</tr>
<tr>
<td>fixed_ip_address</td>
<td>string (IP address)</td>
<td>Null</td>
<td>Indicates the IP address on the internal
port that is mapped to by the floating IP
(since an Networking port might have more
than one IP address).</td>
</tr>
<tr>
<td>tenant_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>Owner of the Floating IP. Only admin users
can specify a tenant_id other than its
own.</td>
</tr>
</tbody>
</table>
</section>
<?hard-pagebreak?>
<section xml:id="l3_workflow">
<title>Basic L3 operations</title>
<para>External networks are visible to all users. However,
the default policy settings enable only administrative
users to create, update, and delete external
networks.</para>
<para>This table shows example neutron commands that
enable you to complete basic L3 operations:</para>
<table rules="all">
<caption>Basic L3 operations</caption>
<col width="40%"/>
<col width="60%"/>
<thead>
<tr>
<th>Operation</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>Creates external
networks.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron net-create public --router:external=True</userinput>
<prompt>#</prompt> <userinput>neutron subnet-create public 172.16.1.0/24</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Lists external networks.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron net-list -- --router:external=True</userinput></screen>
</td>
</tr>
<tr>
<td><para>Creates an internal-only router that
connects to multiple L2 networks
privately.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron net-create net1</userinput>
<prompt>#</prompt> <userinput>neutron subnet-create net1 10.0.0.0/24</userinput>
<prompt>#</prompt> <userinput>neutron net-create net2</userinput>
<prompt>#</prompt> <userinput>neutron subnet-create net2 10.0.1.0/24</userinput>
<prompt>#</prompt> <userinput>neutron router-create router1</userinput>
<prompt>#</prompt> <userinput>neutron router-interface-add router1 &lt;subnet1-uuid&gt;</userinput>
<prompt>#</prompt> <userinput>neutron router-interface-add router1 &lt;subnet2-uuid&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Connects a router to an external
network, which enables that router to
act as a NAT gateway for external
connectivity.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron router-gateway-set router1 &lt;ext-net-id&gt;</userinput></screen>
<para>The router obtains an interface with
the gateway_ip address of the subnet,
and this interface is attached to a
port on the L2 Networking network
associated with the subnet. The router
also gets a gateway interface to the
specified external network. This
provides SNAT connectivity to the
external network as well as support
for floating IPs allocated on that
external networks. Commonly an
external network maps to a network in
the provider</para>
</td>
</tr>
<tr>
<td>
<para>Lists routers.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron router-list</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Shows information for a specified
router.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron router-show &lt;router_id&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Shows all internal interfaces for a
router.</para>
</td>
</tr>
<tr>
<td>
<para>Identifies the
<literal>port-id</literal> that
represents the VM NIC to which the
floating IP should map.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron port-list -c id -c fixed_ips -- --device_id=&lt;instance_id&gt;</userinput></screen>
<para>This port must be on an Networking
subnet that is attached to a router
uplinked to the external network used
to create the floating IP. 
Conceptually, this is because the
router must be able to perform the
Destination NAT (DNAT) rewriting of
packets from the Floating IP address
(chosen from a subnet on the external
network) to the internal Fixed IP
(chosen from a private subnet that is
behind the router).</para>
</td>
</tr>
<tr>
<td>
<para>Creates a floating IP address and
associates it with a port.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron floatingip-create &lt;ext-net-id&gt;</userinput>
<prompt>#</prompt> <userinput>neutron floatingip-associate &lt;floatingip-id&gt; &lt;internal VM port-id&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Creates a floating IP address and
associates it with a port, in a single
step.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron floatingip-create --port_id &lt;internal VM port-id&gt; &lt;ext-net-id&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Lists floating IPs.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron floatingip-list</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Finds floating IP for a specified VM
port.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron floatingip-list -- --port_id=ZZZ</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Disassociates a floating IP
address.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron floatingip-disassociate &lt;floatingip-id&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Deletes the floating IP
address.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron floatingip-delete &lt;floatingip-id&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Clears the gateway.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron router-gateway-clear router1</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Removes the interfaces from the
router.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron router-interface-delete router1 &lt;subnet-id&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Deletes the router.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron router-delete router1</userinput></screen>
</td>
</tr>
</tbody>
</table>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="section_securitygroups">
<title>Security groups</title>
<para>Security groups and security group rules allows
administrators and tenants the ability to specify the type
of traffic and direction (ingress/egress) that is allowed
to pass through a port. A security group is a container
for security group rules.</para>
<para>When a port is created in Networking it is associated
with a security group. If a security group is not
specified the port is associated with a 'default' security
group. By default, this group drops all ingress traffic
and allows all egress. Rules can be added to this group in
order to change the behaviour.</para>
<para>To use the Compute security group APIs or use Compute to
orchestrate the creation of ports for instances on
specific security groups, you must complete additional
configuration. You must configure the
<filename>/etc/nova/nova.conf</filename> file and set
the <code>security_group_api=neutron</code> option on
every node that runs <systemitem class="service"
>nova-compute</systemitem> and <systemitem
class="service">nova-api</systemitem>. After you make
this change, restart <systemitem class="service"
>nova-api</systemitem> and <systemitem class="service"
>nova-compute</systemitem> to pick up this change.
Then, you can use both the Compute and OpenStack Network
security group APIs at the same time.</para>
<note>
<itemizedlist>
<listitem>
<para>To use the Compute security group API with
Networking, the Networking plug-in must
implement the security group API. The
following plug-ins currently implement this:
ML2, Nicira NVP, Open vSwitch, Linux Bridge,
NEC, and Ryu.</para>
</listitem>
<listitem>
<para>You must configure the correct firewall
driver in the <literal>securitygroup</literal>
section of the plug-in/agent configuration
file. Some plug-ins and agents, such as Linux
Bridge Agent and Open vSwitch Agent, use the
no-operation driver as the default, which
results in non-working security groups.</para>
</listitem>
<listitem>
<para>When using the security group API through
Compute, security groups are applied to all
ports on an instance. The reason for this is
that Compute security group APIs are instances
based and not port based as Networking.</para>
</listitem>
</itemizedlist>
</note>
<section xml:id="securitygroup_api_abstractions">
<title>Security group API abstractions</title>
<table rules="all">
<caption>Security group attributes</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the security group.</td>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>None</td>
<td>Human-readable name for the security
group. Might not be unique. Cannot be
named default as that is automatically
created for a tenant.</td>
</tr>
<tr>
<td>description</td>
<td>String</td>
<td>None</td>
<td>Human-readable description of a security
group.</td>
</tr>
<tr>
<td>tenant_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>Owner of the security group. Only admin
users can specify a tenant_id other than
their own.</td>
</tr>
</tbody>
</table>
<table rules="all">
<caption>Security group rules</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the security group rule.</td>
</tr>
<tr>
<td>security_group_id</td>
<td>uuid-str or Integer</td>
<td>allocated by Networking</td>
<td>The security group to associate rule
with.</td>
</tr>
<tr>
<td>direction</td>
<td>String</td>
<td>N/A</td>
<td>The direction the traffic is allow
(ingress/egress) from a VM.</td>
</tr>
<tr>
<td>protocol</td>
<td>String</td>
<td>None</td>
<td>IP Protocol (icmp, tcp, udp, and so
on).</td>
</tr>
<tr>
<td>port_range_min</td>
<td>Integer</td>
<td>None</td>
<td>Port at start of range</td>
</tr>
<tr>
<td>port_range_max</td>
<td>Integer</td>
<td>None</td>
<td>Port at end of range</td>
</tr>
<tr>
<td>ethertype</td>
<td>String</td>
<td>None</td>
<td>ethertype in L2 packet (IPv4, IPv6, and so
on)</td>
</tr>
<tr>
<td>remote_ip_prefix</td>
<td>string (IP cidr)</td>
<td>None</td>
<td>CIDR for address range</td>
</tr>
<tr>
<td>remote_group_id</td>
<td>uuid-str or Integer</td>
<td>allocated by Networking or Compute</td>
<td>Source security group to apply to
rule.</td>
</tr>
<tr>
<td>tenant_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>Owner of the security group rule. Only
admin users can specify a tenant_id other
than its own.</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="securitygroup_workflow">
<title>Basic security group operations</title>
<para>This table shows example neutron commands that
enable you to complete basic security group
operations:</para>
<table rules="all">
<caption>Basic security group operations</caption>
<col width="40%"/>
<col width="60%"/>
<thead>
<tr>
<th>Operation</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>Creates a security group for our web
servers.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron security-group-create webservers --description "security group for webservers"</userinput></screen></td>
</tr>
<tr>
<td><para>Lists security groups.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron security-group-list</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Creates a security group rule to
allow port 80 ingress.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron security-group-rule-create --direction ingress --protocol tcp --port_range_min 80 --port_range_max 80 &lt;security_group_uuid&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Lists security group
rules.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron security-group-rule-list</userinput></screen>
</td>
</tr>
<tr>
<td><para>Deletes a security group
rule.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron security-group-rule-delete &lt;security_group_rule_uuid&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Deletes a security
group.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron security-group-delete &lt;security_group_uuid&gt;</userinput></screen>
</td>
</tr>
<tr>
<td><para>Creates a port and associates two
security groups.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron port-create --security-group &lt;security_group_id1&gt; --security-group &lt;security_group_id2&gt; &lt;network_id&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Removes security groups from a
port.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron port-update --no-security-groups &lt;port_id&gt;</userinput></screen>
</td>
</tr>
</tbody>
</table>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="lbaas_workflow">
<title>Basic Load-Balancer-as-a-Service operations</title>
<note>
<para>The Load-Balancer-as-a-Service (LBaaS) API
provisions and configures load balancers. The Havana
release offers a reference implementation that is
based on the HAProxy software load balancer.</para>
</note>
<para>This table shows example neutron commands that enable
you to complete basic LBaaS operations:</para>
<table rules="all">
<caption>Basic LBaaS operations</caption>
<col width="40%"/>
<col width="60%"/>
<thead>
<tr>
<th>Operation</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>Creates a load balancer pool by using
specific provider.</para>
<para><parameter>--provider</parameter> is an
optional argument. If not used, the pool
is created with default provider for LBaaS
service. You should configure the default
provider in the
<literal>[service_providers]</literal>
section of
<filename>neutron.conf</filename>
file. If no default provider is specified
for LBaaS, the
<parameter>--provider</parameter>
option is required for pool
creation.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron lb-pool-create --lb-method ROUND_ROBIN --name mypool --protocol HTTP --subnet-id &lt;subnet-uuid&gt; <parameter>--provider &lt;provider_name&gt;</parameter></userinput></screen></td>
</tr>
<tr>
<td>
<para>Associates two web servers with
pool.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron lb-member-create --address &lt;webserver one IP&gt; --protocol-port 80 mypool</userinput>
<prompt>#</prompt> <userinput>neutron lb-member-create --address &lt;webserver two IP&gt; --protocol-port 80 mypool</userinput></screen></td>
</tr>
<tr>
<td>
<para>Creates a health monitor which checks to
make sure our instances are still running
on the specified
protocol-port.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron lb-healthmonitor-create --delay 3 --type HTTP --max-retries 3 --timeout 3</userinput></screen>
</td>
</tr>
<tr>
<td><para>Associates a health monitor with
pool.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron lb-healthmonitor-associate &lt;healthmonitor-uuid&gt; mypool</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Creates a virtual IP (VIP) address that,
when accessed through the load balancer,
directs the requests to one of the pool
members.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron lb-vip-create --name myvip --protocol-port 80 --protocol HTTP --subnet-id &lt;subnet-uuid&gt; mypool</userinput></screen>
</td>
</tr>
</tbody>
</table>
</section>
<?hard-pagebreak?>
<section xml:id="fwaas">
<title>Firewall-as-a-Service</title>
<para>The Firewall-as-a-Service (FWaaS) API is an experimental
API that enables early adopters and vendors to test their
networking implementations.</para>
<para>The FWaaS is backed by a <emphasis role="bold">reference
implementation</emphasis> that works with the
Networking OVS plug-in and provides perimeter firewall
functionality. It leverages the footprint of the
Networking OVS L3 agent and an IPTables driver to apply
the firewall rules contained in a particular firewall
policy. This reference implementation supports one
firewall policy and consequently one logical firewall
instance for each tenant. This is not a constraint of the
resource model, but of the current reference
implementation. The firewall is present on a Networking
virtual router. If a tenant has multiple routers, the
firewall is present on all the routers. If a tenant does
not have any router, the firewall is in
<code>PENDING_CREATE</code> state until a router is
created and the first interface is added to the router. At
that point the firewall policy is immediately applied to
the router and the firewall changes to <code>ACTIVE</code>
state.</para>
<note>
<para>Because this is the first iteration of this
implementation, it should probably not be run in
production environments without adequate
testing.</para>
</note>
<section xml:id="fwaas_api_abstractions">
<title>Firewall-as-a-Service API abstractions</title>
<table rules="all">
<caption>Firewall rules</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the firewall rule.</td>
</tr>
<tr>
<td>tenant_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>Owner of the firewall rule. Only admin
users can specify a tenant_id other than
its own.</td>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>None</td>
<td>Human readable name for the firewall rule
(255 characters limit).</td>
</tr>
<tr>
<td>description</td>
<td>String</td>
<td>None</td>
<td>Human readable description for the
firewall rule (1024 characters
limit).</td>
</tr>
<tr>
<td>firewall_policy_id</td>
<td>uuid-str or None</td>
<td>allocated by Networking</td>
<td>This is a read-only attribute that gets
populated with the uuid of the firewall
policy when this firewall rule is
associated with a firewall policy. A
firewall rule can be associated with only
one firewall policy at a time. However,
the association can be changed to a
different firewall policy.</td>
</tr>
<tr>
<td>shared</td>
<td>Boolean</td>
<td>False</td>
<td>When set to True makes this firewall rule
visible to tenants other than its owner,
and it can be used in firewall policies
not owned by its tenant.</td>
</tr>
<tr>
<td>protocol</td>
<td>String</td>
<td>None</td>
<td>IP Protocol (icmp, tcp, udp, None).</td>
</tr>
<tr>
<td>ip_version</td>
<td>Integer or String</td>
<td>4</td>
<td>IP Version (4, 6).</td>
</tr>
<tr>
<td>source_ip_address</td>
<td>String (IP address or CIDR)</td>
<td>None</td>
<td>Source IP address or CIDR.</td>
</tr>
<tr>
<td>destination_ip_address</td>
<td>String (IP address or CIDR)</td>
<td>None</td>
<td>Destination IP address or CIDR.</td>
</tr>
<tr>
<td>source_port</td>
<td>Integer or String (either as a single port
number or in the format of a ':' separated
range)</td>
<td>None</td>
<td>Source port number or a range.</td>
</tr>
<tr>
<td>destination_port</td>
<td>Integer or String (either as a single port
number or in the format of a ':' separated
range)</td>
<td>None</td>
<td>Destination port number or a range.</td>
</tr>
<tr>
<td>position</td>
<td>Integer</td>
<td>None</td>
<td>This is a read-only attribute that gets
assigned to this rule when the rule is
associated with a firewall policy. It
indicates the position of this rule in
that firewall policy.</td>
</tr>
<tr>
<td>action</td>
<td>String</td>
<td>deny</td>
<td>Action to be performed on the traffic
matching the rule (allow, deny).</td>
</tr>
<tr>
<td>enabled</td>
<td>Boolean</td>
<td>True</td>
<td>When set to False, disables this rule in
the firewall policy. Facilitates
selectively turning off rules without
having to disassociate the rule from the
firewall policy.</td>
</tr>
</tbody>
</table>
<table rules="all">
<caption>Firewall policies</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the firewall policy.</td>
</tr>
<tr>
<td>tenant_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>Owner of the firewall policy. Only admin
users can specify a tenant_id other their
own.</td>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>None</td>
<td>Human readable name for the firewall
policy (255 characters limit).</td>
</tr>
<tr>
<td>description</td>
<td>String</td>
<td>None</td>
<td>Human readable description for the
firewall policy (1024 characters
limit).</td>
</tr>
<tr>
<td>shared</td>
<td>Boolean</td>
<td>False</td>
<td>When set to True makes this firewall
policy visible to tenants other than its
owner, and can be used to associate with
firewalls not owned by its tenant.</td>
</tr>
<tr>
<td>firewall_rules</td>
<td>List of uuid-str or None</td>
<td>None</td>
<td>This is an ordered list of firewall rule
uuids. The firewall applies the rules in
the order in which they appear in this
list.</td>
</tr>
<tr>
<td>audited</td>
<td>Boolean</td>
<td>False</td>
<td>When set to True by the policy owner
indicates that the firewall policy has
been audited. This attribute is meant to
aid in the firewall policy audit
workflows. Each time the firewall policy
or the associated firewall rules are
changed, this attribute is set to False
and must be explicitly set to True through
an update operation.</td>
</tr>
</tbody>
</table>
<table rules="all">
<caption>Firewalls</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the firewall.</td>
</tr>
<tr>
<td>tenant_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>Owner of the firewall. Only admin users
can specify a tenant_id other than its
own.</td>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>None</td>
<td>Human readable name for the firewall (255
characters limit).</td>
</tr>
<tr>
<td>description</td>
<td>String</td>
<td>None</td>
<td>Human readable description for the
firewall (1024 characters limit).</td>
</tr>
<tr>
<td>admin_state_up</td>
<td>Boolean</td>
<td>True</td>
<td>The administrative state of the firewall.
If False (down), the firewall does not
forward any packets.</td>
</tr>
<tr>
<td>status</td>
<td>String</td>
<td>N/A</td>
<td><para>Indicates whether the firewall is
currently operational. Possible values
include:</para>
<itemizedlist>
<listitem>
<para>ACTIVE</para>
</listitem>
<listitem>
<para>DOWN</para>
</listitem>
<listitem>
<para>PENDING_CREATE</para>
</listitem>
<listitem>
<para>PENDING_UPDATE</para>
</listitem>
<listitem>
<para>PENDING_DELETE</para>
</listitem>
<listitem>
<para>ERROR</para>
</listitem>
</itemizedlist>
</td>
</tr>
<tr>
<td>firewall_policy_id</td>
<td>uuid-str or None</td>
<td>None</td>
<td>The firewall policy uuid that this
firewall is associated with. This firewall
implements the rules contained in the
firewall policy represented by this uuid.
</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="fwaas_workflow">
<title>Basic Firewall-as-a-Service operations</title>
<itemizedlist>
<listitem>
<para>Create a firewall rule:</para>
<screen><prompt>#</prompt> <userinput>neutron firewall-rule-create --protocol &lt;tcp|udp|icmp|any&gt; --destination-port &lt;port-range&gt; --action &lt;allow|deny&gt;</userinput></screen>
<para>The CLI requires that a protocol value be
provided. If the rule is protocol agnostic,
the 'any' value can be used.</para>
<para>In addition to the protocol attribute, other
attributes can be specified in the firewall
rule. See the previous section for the
supported attributes.</para>
</listitem>
<listitem>
<para>Create a firewall policy:</para>
<screen><prompt>#</prompt> <userinput>neutron firewall-policy-create --firewall-rules "&lt;firewall-rule ids or names separated by space&gt;" myfirewallpolicy</userinput></screen>
<para>The order of the rules specified above is
important. A firewall policy can be created
without any rules and rules can be added later
either via the update operation (if adding
multiple rules) or via the insert-rule
operation (if adding a single rule). Please
check the CLI help for more details on these
operations.</para>
<note>
<para>The reference implementation always adds
a default deny all rule at the end of each
policy. This implies that if a firewall
policy is created without any rules and is
associated with a firewall, that firewall
blocks all traffic.</para>
</note>
</listitem>
<listitem>
<para>Create a firewall:</para>
<screen><prompt>#</prompt> <userinput>neutron firewall-create &lt;firewall-policy-uuid&gt;</userinput></screen>
</listitem>
</itemizedlist>
<note>
<para>The FWaaS features and the above workflow can
also be accessed from the Horizon user interface.
This support is disabled by default, but can be
enabled by configuring
<filename>#HORIZON_DIR/openstack_dashboard/local/local_settings.py
</filename> and setting:</para>
<programlisting language="ini">'enable_firewall' = True</programlisting>
</note>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="section_allowed_address_pairs">
<title>Allowed-address-pairs</title>
<para>Allowed-address-pairs is an API extension that extends
the port attribute. This extension allows one to specify
arbitrary mac_address/ip_address(cidr) pairs that are
allowed to pass through a port regardless of subnet. The
main use case for this is to enable the ability to use
protocols such as VRRP which floats an ip address between
two instances to enable fast data plane failover.</para>
<note>
<para>The allowed-address-pairs extension is currently
only supported by these plug-ins: ML2, Nicira NVP, and
Open vSwitch.</para>
</note>
<section xml:id="section_allowed_address_pairs_workflow">
<title>Basic allowed address pairs operations</title>
<itemizedlist>
<listitem>
<para>Create a port with a specific
allowed-address-pairs:</para>
<screen><prompt>#</prompt> <userinput>neutron port-create net1 --allowed-address-pairs type=dict list=true mac_address=&lt;mac_address&gt;,ip_address=&lt;ip_cidr&gt;</userinput></screen>
</listitem>
<listitem>
<para>Update a port adding
allowed-address-pairs:</para>
<screen><prompt>#</prompt> <userinput>neutron port-update &lt;subnet-uuid&gt; --allowed-address-pairs type=dict list=true mac_address=&lt;mac_address&gt;,ip_address=&lt;ip_cidr&gt;</userinput></screen>
</listitem>
</itemizedlist>
<note>
<para>Setting an allowed-address-pair that matches the
mac_address and ip_address of a port is prevented.
This is because that would have no effect since
traffic matching the mac_address and ip_address is
already allowed to pass through the port.</para>
</note>
<note>
<para>If your plug-in implements the port-security
extension port-security-enabled must be set to
True on the port in order to have
allowed-address-pairs on a port. The reason for
this is because if port-security-enabled is set to
False this allows all traffic to be passed through
the port thus having allowed-address-pairs would
have no effect.</para>
</note>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="section_plugin_specific_extensions">
<title>Plug-in specific extensions</title>
<?dbhtml stop-chunking?>
<para>Each vendor can choose to implement additional API
extensions to the core API. This section describes the
extensions for each plug-in.</para>
<section xml:id="section_nicira_extensions">
<title>Nicira NVP extensions</title>
<para>These sections explain Nicira NVP plug-in
extensions.</para>
<section xml:id="section_nicira_nvp_plugin_qos_extension">
<title>Nicira NVP QoS extension</title>
<para>The Nicira NVP QoS extension rate-limits network
ports to guarantee a specific amount of bandwidth
for each port. This extension, by default, is only
accessible by a tenant with an admin role but is
configurable through the
<filename>policy.json</filename> file. To use
this extension, create a queue and specify the
min/max bandwidth rates (kbps) and optionally set
the QoS Marking and DSCP value (if your network
fabric uses these values to make forwarding
decisions). Once created, you can associate a
queue with a network. Then, when ports are created
on that network they are automatically created and
associated with the specific queue size that was
associated with the network. Because one size
queue for a every port on a network might not be
optimal, a scaling factor from the Nova flavor
'rxtx_factor' is passed in from Compute when
creating the port to scale the queue.</para>
<para>Lastly, if you want to set a specific baseline
QoS policy for the amount of bandwidth a single
port can use (unless a network queue is specified
with the network a port is created on) a default
queue can be created in Networking which then
causes ports created to be associated with a queue
of that size times the rxtx scaling factor. Note
that after a network or default queue is
specified, queues are added to ports that are
subsequently created but are not added to existing
ports.</para>
<section
xml:id="section_nicira_nvp_qos_api_abstractions">
<title>Nicira NVP QoS API abstractions</title>
<table rules="all">
<caption>Nicira NVP QoS attributes</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the QoS queue.</td>
</tr>
<tr>
<td>default</td>
<td>Boolean</td>
<td>False by default</td>
<td>If True, ports are created with
this queue size unless the network
port is created or associated with
a queue at port creation time.</td>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>None</td>
<td>Name for QoS queue.</td>
</tr>
<tr>
<td>min</td>
<td>Integer</td>
<td>0</td>
<td>Minimum Bandwidth Rate (kbps).
</td>
</tr>
<tr>
<td>max</td>
<td>Integer</td>
<td>N/A</td>
<td>Maximum Bandwidth Rate (kbps).
</td>
</tr>
<tr>
<td>qos_marking</td>
<td>String</td>
<td>untrusted by default</td>
<td>Whether QoS marking should be
trusted or untrusted.</td>
</tr>
<tr>
<td>dscp</td>
<td>Integer</td>
<td>0</td>
<td>DSCP Marking value.</td>
</tr>
<tr>
<td>tenant_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>The owner of the QoS queue.</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="nicira_nvp_qos_walk_through">
<title>Basic Nicira NVP QoS operations</title>
<para>This table shows example neutron commands
that enable you to complete basic queue
operations:</para>
<table rules="all">
<caption>Basic Nicira NVP QoS
operations</caption>
<col width="40%"/>
<col width="60%"/>
<thead>
<tr>
<th>Operation</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>Creates QoS Queue
(admin-only).</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron queue-create--min 10 --max 1000 myqueue</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Associates a queue with a
network.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron net-create network --queue_id=&lt;queue_id&gt;</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Creates a default system
queue.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron queue-create --default True --min 10 --max 2000 default</userinput></screen>
</td>
</tr>
<tr>
<td><para>Lists QoS
queues.</para></td>
<td><screen><prompt>#</prompt> <userinput>neutron queue-list</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Deletes a QoS
queue.</para></td>
<td>
<screen><prompt>#</prompt> <userinput>neutron queue-delete &lt;queue_id or name&gt;'</userinput></screen>
</td>
</tr>
</tbody>
</table>
</section>
</section>
<section xml:id="section_nicira_nvp_provider_extension">
<title>Nicira NVP provider networks extension</title>
<para>Provider networks can be implemented in
different ways by the underlying NVP
platform.</para>
<para>The <emphasis>FLAT</emphasis> and
<emphasis>VLAN</emphasis> network types use
bridged transport connectors. These network types
enable the attachment of large number of ports. To
handle the increased scale, the NVP plug-in can
back a single Openstack Network with a chain of
NVP logical switches. You can specify the maximum
number of ports on each logical switch in this
chain on the
<literal>max_lp_per_bridged_ls</literal>
parameter, which has a default value of
5,000.</para>
<para>The recommended value for this parameter varies
with the NVP version running in the back-end, as
shown in the following table.</para>
<table rules="all">
<caption>Recommended values for
max_lp_per_bridged_ls</caption>
<col width="50%"/>
<col width="50%"/>
<thead>
<tr>
<td>NVP version</td>
<td>Recommended Value</td>
</tr>
</thead>
<tbody>
<tr>
<td>2.x</td>
<td>64</td>
</tr>
<tr>
<td>3.0.x</td>
<td>5,000</td>
</tr>
<tr>
<td>3.1.x</td>
<td>5,000</td>
</tr>
<tr>
<td>3.2.x</td>
<td>10,000</td>
</tr>
</tbody>
</table>
<para>In addition to these network types, the NVP
plug-in also supports a special
<emphasis>l3_ext</emphasis> network type,
which maps external networks to specific NVP
gateway services as discussed in the next
section.</para>
</section>
<section xml:id="section_nicira_nvp_plugin_l3_extension">
<title>Nicira NVP L3 extension</title>
<para>NVP exposes its L3 capabilities through gateway
services which are usually configured out of band
from OpenStack. To use NVP with L3 capabilities,
first create a L3 gateway service in the NVP
Manager. Next, in <filename>
/etc/neutron/plugins/nicira/nvp.ini</filename>
set <literal>default_l3_gw_service_uuid</literal>
to this value. By default, routers are mapped to
this gateway service.</para>
<section xml:id="section_nicira_l3_walk_through">
<title>Nicira NVP L3 extension operations</title>
<para>Create external network and map it to a
specific NVP gateway service:</para>
<screen><prompt>#</prompt> <userinput>neutron net-create public --router:external=True --provider:network_type l3_ext \
--provider:physical_network &lt;L3-Gateway-Service-UUID&gt;</userinput></screen>
<para>Terminate traffic on a specific VLAN from a
NVP gateway service:</para>
<screen><prompt>#</prompt> <userinput>neutron net-create public --router:external=True --provider:network_type l3_ext \
--provider:physical_network &lt;L3-Gateway-Service-UUID&gt; -provider:segmentation_id &lt;VLAN_ID&gt;</userinput></screen>
</section>
</section>
<section xml:id="section_nicira_nvp_plugin_status_sync">
<title>Operational status synchronization in the
Nicira NVP plug-in</title>
<para>Starting with the Havana release, the Nicira NVP
plug-in provides an asynchronous mechanism for
retrieving the operational status for neutron
resources from the NVP back-end; this applies to
<emphasis>network</emphasis>,
<emphasis>port</emphasis>, and
<emphasis>router</emphasis> resources.</para>
<para>The back-end is polled periodically, and the
status for every resource is retrieved; then the
status in the Networking database is updated only
for the resources for which a status change occurred.
As operational status is now retrieved
asynchronously, performance for
<literal>GET</literal> operations is
consistently improved.</para>
<para>Data to retrieve from the back-end are divided
in chunks in order to avoid expensive API
requests; this is achieved leveraging NVP APIs
response paging capabilities. The minimum chunk
size can be specified using a configuration
option; the actual chunk size is then determined
dynamically according to: total number of
resources to retrieve, interval between two
synchronization task runs, minimum delay between
two subsequent requests to the NVP
back-end.</para>
<para>The operational status synchronization can be
tuned or disabled using the configuration options
reported in this table; it is however worth noting
that the default values work fine in most
cases.</para>
<table rules="all">
<caption>Configuration options for tuning
operational status synchronization in the NVP
plug-in</caption>
<col width="12%"/>
<col width="8%"/>
<col width="10%"/>
<col width="20%"/>
<col width="50%"/>
<thead>
<tr>
<th>Option name</th>
<th>Group</th>
<th>Default value</th>
<th>Type and constraints</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><literal>state_sync_interval</literal></td>
<td><literal>nvp_sync</literal></td>
<td>120 seconds</td>
<td>Integer; no constraint.</td>
<td>Interval in seconds between two run of
the synchronization task. If the
synchronization task takes more than
<literal>state_sync_interval</literal>
seconds to execute, a new instance of
the task is started as soon as the
other is completed. Setting the value
for this option to 0 will disable the
synchronization task.</td>
</tr>
<tr>
<td><literal>max_random_sync_delay</literal></td>
<td><literal>nvp_sync</literal></td>
<td>0 seconds</td>
<td>Integer. Must not exceed
<literal>min_sync_req_delay</literal></td>
<td>When different from zero, a random
delay between 0 and
<literal>max_random_sync_delay</literal>
will be added before processing the
next chunk.</td>
</tr>
<tr>
<td><literal>min_sync_req_delay</literal></td>
<td><literal>nvp_sync</literal></td>
<td>10 seconds</td>
<td>Integer. Must not exceed
<literal>state_sync_interval</literal>.</td>
<td>The value of this option can be tuned
according to the observed load on the
NVP controllers. Lower values will
result in faster synchronization, but
might increase the load on the
controller cluster.</td>
</tr>
<tr>
<td><literal>min_chunk_size</literal></td>
<td><literal>nvp_sync</literal></td>
<td>500 resources</td>
<td>Integer; no constraint.</td>
<td>Minimum number of resources to
retrieve from the back-end for each
synchronization chunk. The expected
number of synchronization chunks is
given by the ratio between
<literal>state_sync_interval</literal>
and
<literal>min_sync_req_delay</literal>.
This size of a chunk might increase if
the total number of resources is such
that more than
<literal>min_chunk_size</literal>
resources must be fetched in one chunk
with the current number of
chunks.</td>
</tr>
<tr>
<td><literal>always_read_status</literal></td>
<td><literal>nvp_sync</literal></td>
<td>False</td>
<td>Boolean; no constraint.</td>
<td>When this option is enabled, the
operational status will always be
retrieved from the NVP back-end ad
every <literal>GET</literal> request.
In this case it is advisable to
disable the synchronization task.</td>
</tr>
</tbody>
</table>
<para>When running multiple OpenStack Networking server
instances, the status synchronization task should
not run on every node; doing so sends unnecessary
traffic to the NVP back-end and performs unnecessary
DB operations. Set the
<option>state_sync_interval</option>
configuration option to a non-zero value
exclusively on a node designated for back-end
status synchronization.</para>
<para>Explicitly specifying the <emphasis
role="italic">status</emphasis> attribute in
Neutron API requests (e.g.: <literal>GET
/v2.0/networks/&lt;net-id>?fields=status&amp;fields=name</literal>)
always triggers an explicit query to the NVP
back-end, even when asynchronous state
synchronization is enabled.</para>
</section>
</section>
<section xml:id="section_bigswitch_extensions">
<title>Big Switch plug-in extensions</title>
<para>This section explains the Big Switch Neutron
plug-in-specific extension.</para>
<section xml:id="section_bigswitch_extension_routerrules">
<title>Big Switch router rules</title>
<para>Big Switch allows router rules to be added to
each tenant router. These rules can be used to
enforce routing policies such as denying traffic
between subnets or traffic to external networks.
By enforcing these at the router level, network
segmentation policies can be enforced across many
VMs that have differing security groups.</para>
<section xml:id="section_bigswitch_routerrule_fields">
<title>Router rule attributes</title>
<para>Each tenant router has a set of router rules
associated with it. Each router rule has the
attributes in this table. Router rules and
their attributes can be set using the
<command>neutron router-update</command>
command, through the Horizon interface or the
Neutron API.</para>
<table rules="all">
<caption>Big Switch Router rule
attributes</caption>
<col width="20%"/>
<col width="15%"/>
<col width="25%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Required</th>
<th>Input Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>source</td>
<td>Yes</td>
<td>A valid CIDR or one of the
keywords 'any' or 'external'</td>
<td>The network that a packet's source
IP must match for the rule to be
applied</td>
</tr>
<tr>
<td>destination</td>
<td>Yes</td>
<td>A valid CIDR or one of the
keywords 'any' or 'external'</td>
<td>The network that a packet's
destination IP must match for the
rule to be applied</td>
</tr>
<tr>
<td>action</td>
<td>Yes</td>
<td>'permit' or 'deny'</td>
<td>Determines whether or not the
matched packets will allowed to
cross the router</td>
</tr>
<tr>
<td>nexthop</td>
<td>No</td>
<td>A plus-separated (+) list of
next-hop IP addresses (e.g.
'1.1.1.1+1.1.1.2')</td>
<td>Overrides the default virtual
router used to handle traffic for
packets that match the rule</td>
</tr>
</tbody>
</table>
</section>
<section
xml:id="section_bigswitch_routerrule_processorder">
<title>Order of rule processing</title>
<para>The order of router rules has no effect.
Overlapping rules are evaluated using longest
prefix matching on the source and destination
fields. The source field is matched first so
it always takes higher precedence over the
destination field. In other words, longest
prefix matching is used on the destination
field only if there are multiple matching
rules with the same source.</para>
</section>
<section
xml:id="section_bigswitch_routerrule_walkthrough">
<title>Big Switch router rules operations</title>
<para>Router rules are configured with a router
update operation in OpenStack Networking. The
update overrides any previous rules so all
rules must be provided at the same time.</para>
<para>Update a router with rules to permit traffic
by default but block traffic from external
networks to the 10.10.10.0/24 subnet:</para>
<screen><prompt>#</prompt> <userinput>neutron router-update <replaceable>Router-UUID</replaceable> --router_rules type=dict list=true\
source=any,destination=any,action=permit \
source=external,destination=10.10.10.0/24,action=deny</userinput></screen>
<para>Specify alternate next-hop addresses for a
specific subnet:</para>
<screen><prompt>#</prompt> <userinput>neutron router-update <replaceable>Router-UUID</replaceable> --router_rules type=dict list=true\
source=any,destination=any,action=permit \
source=10.10.10.0/24,destination=any,action=permit,nexthops=10.10.10.254+10.10.10.253</userinput></screen>
<para>Block traffic between two subnets while
allowing everything else:</para>
<screen><prompt>#</prompt> <userinput>neutron router-update <replaceable>Router-UUID</replaceable> --router_rules type=dict list=true\
source=any,destination=any,action=permit \
source=10.10.10.0/24,destination=10.20.20.20/24,action=deny</userinput></screen>
</section>
</section>
</section>
</section>
<section xml:id="metering">
<title>L3 metering</title>
<para>The L3 metering API extension enables administrators to
configure IP ranges and assign a specified label to them
to be able to measure traffic that goes through a virtual
router.</para>
<para>The L3 metering extension is decoupled from the
technology that implements the measurement. Two
abstractions have been added: One is the metering label
that can contain metering rules. Because a metering label
is associated with a tenant, all virtual routers in this
tenant are associated with this label.</para>
<section xml:id="metering_abstraction">
<title>L3 metering API abstractions</title>
<table rules="all">
<caption>Label</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the metering label.</td>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>None</td>
<td>Human-readable name for the metering
label. Might not be unique.</td>
</tr>
<tr>
<td>description</td>
<td>String</td>
<td>None</td>
<td>The optional description for the metering
label.</td>
</tr>
<tr>
<td>tenant_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>Owner of the metering label.</td>
</tr>
</tbody>
</table>
<table rules="all">
<caption>Rules</caption>
<col width="20%"/>
<col width="20%"/>
<col width="20%"/>
<col width="40%"/>
<thead>
<tr>
<th>Attribute name</th>
<th>Type</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>uuid-str</td>
<td>generated</td>
<td>UUID for the metering rule.</td>
</tr>
<tr>
<td>direction</td>
<td>String (Either ingress or egress)</td>
<td>ingress</td>
<td>The direction in which metering rule is
applied, either ingress or egress.</td>
</tr>
<tr>
<td>metering_label_id</td>
<td>uuid-str</td>
<td>N/A</td>
<td>
<para>The metering label ID to associate
with this metering rule.</para>
</td>
</tr>
<tr>
<td>excluded</td>
<td>Boolean</td>
<td>False</td>
<td>Specify whether the remote_ip_prefix will
be excluded or not from traffic counters
of the metering label, For example to not
count the traffic of a specific IP address
of a range.</td>
</tr>
<tr>
<td>remote_ip_prefix</td>
<td>String (CIDR)</td>
<td>N/A</td>
<td>Indicates remote IP prefix to be
associated with this metering rule.</td>
</tr>
</tbody>
</table>
</section>
<?hard-pagebreak?>
<section xml:id="metering_operations">
<title>Basic L3 metering operations</title>
<para>Only administrators can manage the L3
metering labels and rules.</para>
<para>This table shows example <command>neutron</command> commands
that enable you to complete basic L3 metering
operations:</para>
<table rules="all">
<caption>Basic L3 operations</caption>
<col width="40%"/>
<col width="60%"/>
<thead>
<tr>
<th>Operation</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>Creates a metering label.</para>
</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron meter-label-create <replaceable>label1</replaceable> --description <replaceable>"description of label1"</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Lists metering labels.</para>
</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron meter-label-list</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Shows information for a specified
label.</para>
</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron meter-label-show <replaceable>label-uuid</replaceable></userinput>
<prompt>$</prompt> <userinput>neutron meter-label-show <replaceable>label1</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Deletes a metering label.</para>
</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron meter-label-delete <replaceable>label-uuid</replaceable></userinput>
<prompt>$</prompt> <userinput>neutron meter-label-delete <replaceable>label1</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Creates a metering rule.</para>
</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron meter-label-rule-create <replaceable>label-uuid</replaceable> <replaceable>cidr</replaceable> --direction <replaceable>direction</replaceable> --excluded</userinput>
<prompt>$</prompt> <userinput>neutron meter-label-rule-create <replaceable>label1</replaceable> <replaceable>10.0.0.0/24</replaceable> --direction <replaceable>ingress</replaceable></userinput>
<prompt>$</prompt> <userinput>neutron meter-label-rule-create <replaceable>label1</replaceable> <replaceable>20.0.0.0/24</replaceable> --excluded</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Lists metering all label
rules.</para>
</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron meter-label-rule-list</userinput></screen>
</td>
</tr>
<tr>
<td>
<para>Shows information for a specified
label rule.</para>
</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron meter-label-rule-show <replaceable>rule-uuid</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Deletes a metering label rule.</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron meter-label-rule-delete <replaceable>rule-uuid</replaceable></userinput></screen>
</td>
</tr>
</tbody>
</table>
</section>
</section>
</section>
<!---->
View Git Blame Copy Permalink