1397c31240
Closes-Bug: #1283712 Change-Id: Iea9a63251b7702a33fcdb54c71bfc638774d0418 author: diane fleming
245 lines
11 KiB
XML
245 lines
11 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section[
|
|
<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY ndash "–">
|
|
<!ENTITY mdash "—">
|
|
<!ENTITY hellip "…">
|
|
<!ENTITY plusmn "±">
|
|
|
|
<!-- Useful for describing APIs -->
|
|
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
|
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
|
|
|
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
|
<imageobject>
|
|
<imagedata fileref="figures/Check_mark_23x20_02.svg"
|
|
format="SVG" scale="60"/>
|
|
</imageobject>
|
|
</inlinemediaobject>'>
|
|
|
|
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
|
<imageobject>
|
|
<imagedata fileref="figures/Arrow_east.svg"
|
|
format="SVG" scale="60"/>
|
|
</imageobject>
|
|
</inlinemediaobject>'>
|
|
]>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:html="http://www.w3.org/1999/xhtml"
|
|
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
|
|
status="final" xml:id="extgwmodes-ext">
|
|
<title>Configurable external gateway modes extension</title>
|
|
<para>By default, when a gateway is attached to a router using the
|
|
Neutron L3 extension, Network Address Translation (NAT) is
|
|
enabled for traffic generated by subnets attached to the
|
|
router. With this extension, the user will have the option of
|
|
choosing whether SNAT should be enabled or not on a router
|
|
basis.</para>
|
|
<para>This is achieved simply by specifying a boolean attribute,
|
|
<literal>enable_snat</literal>, in the
|
|
<literal>external_gateway_info</literal> attribute of the
|
|
<literal>router</literal> resource.</para>
|
|
<para>This extension redefines the external_gateway_info attribute
|
|
as depicted in the following table.</para>
|
|
<table rules="all">
|
|
<caption>external_gateway_info attributes</caption>
|
|
<col width="20%"/>
|
|
<col width="8%"/>
|
|
<col width="10%"/>
|
|
<col width="15%"/>
|
|
<col width="15%"/>
|
|
<col width="32%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Type</th>
|
|
<th>Required</th>
|
|
<th>Default Value</th>
|
|
<th>Validation Constraints</th>
|
|
<th>Notes</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>network_id</td>
|
|
<td>UUID</td>
|
|
<td>Yes</td>
|
|
<td>N/A</td>
|
|
<td>Must be a valid uuid representative of an external
|
|
network.</td>
|
|
<td/>
|
|
</tr>
|
|
<tr>
|
|
<td>enable_snat</td>
|
|
<td>Boolean</td>
|
|
<td>No</td>
|
|
<td>True</td>
|
|
<td>{True|False}</td>
|
|
<td>The default setting is <literal>True</literal> to
|
|
ensure backward compatibility for plugins
|
|
supporting this extension.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<para>SNAT can be enabled or disabled at any time on a Neutron
|
|
router regardless of the current status of floating IPs.
|
|
Floating IPs will continue working even when SNAT is
|
|
disabled.</para>
|
|
<section xml:id="list_routers_extgwmodes">
|
|
<title>List Routers</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&GET;</td>
|
|
<td>/routers</td>
|
|
<td>Retrieve Neutron routers</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<simpara>Success and error response codes are not changed with
|
|
regards to the operation as introduced by the L3 API
|
|
extension.</simpara>
|
|
<simpara>When this extension is enabled, this operation will
|
|
also return the current Source NAT status for configured
|
|
routers, as shown in the sample below.</simpara>
|
|
<simpara>The response for the <emphasis>show router</emphasis>
|
|
operation is the same, with the obvious exception that a
|
|
single router is returned.</simpara>
|
|
<example>
|
|
<title>Router list with configurable external gateway
|
|
modes enabled</title>
|
|
<programlisting language="json"><xi:include href="samples/routers-get-enablesnat-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="create_router_extgwmodes">
|
|
<title>Create Router with external gateway</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&POST;</td>
|
|
<td>/routers</td>
|
|
<td>Create a new Neutron router</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Success and error response codes are not changed with
|
|
regards to the operation as introduced by the L3 API
|
|
extension.</para>
|
|
<para>Neutron API users can specify whether SNAT should be
|
|
performed on the network specified as the router's
|
|
external gateway by setting <literal>enable_snat</literal>
|
|
in <literal>external_gateway_info</literal> to either
|
|
<literal>True</literal> or <literal>False</literal>;
|
|
the default value is <literal>True</literal>.</para>
|
|
<example>
|
|
<title>Create router with SNAT disabled</title>
|
|
<programlisting><xi:include href="samples/router-create-enablesnat-json-http.txt" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="update_router_extgwmodes">
|
|
<title>Update Router's external gateway info</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&PUT;</td>
|
|
<td>/routers/<literal>router_id</literal></td>
|
|
<td>Create a new Neutron router</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Success and error response codes are not changed with
|
|
regards to the operation as introduced by the L3 API
|
|
extension.</para>
|
|
<para>Neutron API users can enable or disable SNAT on a router
|
|
specifying the <literal>enable_snat</literal> attribute in
|
|
the <literal>external_gateway_info</literal> attribute for
|
|
the router resource. This operation can be either used for
|
|
updating the SNAT status only, the external network, or
|
|
both attributes at the same time. In any case, if the
|
|
<literal>enable_snat</literal> attribute is not
|
|
specified, it will default to <literal>True</literal>. For
|
|
instance, if the current SNAT status is disabled, and the
|
|
router's gateway is updated to a different external
|
|
network without specifying <literal>enable_snat</literal>,
|
|
SNAT will be enabled for the new network.</para>
|
|
<para>It is important to note that whenever updating a
|
|
router's external gateway information, the
|
|
<literal>network_id</literal>parameter must be
|
|
specified always, even if the final goal is just to enable
|
|
or disable SNAT for the router on the same external
|
|
network.</para>
|
|
<para>The rest of this section provides some samples for
|
|
updating a router's external gateway info with SNAT
|
|
mode.</para>
|
|
<para>
|
|
<example>
|
|
<title>Disable SNAT for the current external
|
|
network</title>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-1.json" parse="text"/></programlisting>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-1b.json" parse="text"/></programlisting>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-1c.json" parse="text"/></programlisting>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-1d.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Change external network and enable SNAT</title>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-2.json" parse="text"/></programlisting>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-2b.json" parse="text"/></programlisting>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-2c.json" parse="text"/></programlisting>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-2d.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Change external network and keep SNAT
|
|
disabled</title>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-3.json" parse="text"/></programlisting>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-3b.json" parse="text"/></programlisting>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-3c.json" parse="text"/></programlisting>
|
|
<programlisting><xi:include href="samples/router-update-enablesnat-3d.json" parse="text"/></programlisting>
|
|
</example>
|
|
</para>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
|
|
</section>
|