===================================
Configurable external gateway modes
===================================

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.

This is achieved simply by specifying a boolean attribute,
``enable_snat``, in the ``external_gateway_info`` attribute of the
``router`` resource.

This extension redefines the external\_gateway\_info attribute:

**Table external\_gateway\_info attributes**

============  =======  ========  =============  ================================
Attribute     Type     Required  Default Value  Validation Constraints and Notes
============  =======  ========  =============  ================================
network\_id   UUID     Yes       N/A            Must be a valid uuid representative
                                                of an external network.
enable\_snat  Boolean  No        True           {True\|False}
                                                The default setting is ``True`` to
                                                ensure backward compatibility for
                                                plugins supporting this extension.
============  =======  ========  =============  ================================

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.

List routers
~~~~~~~~~~~~

**GET** /routers

Lists neutron routers.

Success and error response codes are not changed with regards to the
operation as introduced by the L3 API extension.

When this extension is enabled, this operation also returns the current
Source NAT status for configured routers, as follows.

The response for the *show router* operation is the same, with the
obvious exception that a single router is returned.

**Example Router list with configurable external gateway modes
enabled**

.. code::

    {
       "routers":
       [{
           "status": "ACTIVE",
           "external_gateway_info":
           {"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
            "enable_snat": true},
           "name": "second_router",
           "admin_state_up": true,
           "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
           "id": "7177abc4-5ae9-4bb7-b0d4-89e94a4abf3b"
        },
        {
           "status": "ACTIVE",
           "external_gateway_info":
           {"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
            "enable_snat": false},
           "name": "router1",
           "admin_state_up": true,
           "tenant_id": "33a40233088643acb66ff6eb0ebea679",
           "id": "a9254bdb-2613-4a13-ac4c-adc581fba50d"
         }]
    }



Create router with external gateway
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**POST** /routers

Create a new Neutron router

Success and error response codes are not changed with regards to the
operation as introduced by the L3 API extension.

Neutron API users can specify whether SNAT should be performed on the
network specified as the router's external gateway by setting
``enable_snat`` in ``external_gateway_info`` to either ``True`` or
``False``; the default value is ``True``.

**Example Create router with SNAT disabled**

.. code::

    POST /v2.0/routers
    Accept: application/json
    {
        "router":
        {
            "name": "another_router",
            "admin_state_up": true,
            "external_gateway_info": {
                "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
                "enable_snat": false}
        }
    }

    HTTP/1.1 201 OK
    Content-Type: application/json; charset=UTF-8
    {
        "router":
        {
            "status": "ACTIVE",
            "external_gateway_info": {
                "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
                "enable_snat": false}
            "name": "another_router",
            "admin_state_up": true,
            "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
            "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
         }
    }



Update external gateway information for router
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**PUT** /routers/``router_id``

Creates a neutron router.

Success and error response codes are not changed with regards to the
operation as introduced by the L3 API extension.

Neutron API users can enable or disable SNAT on a router specifying the
``enable_snat`` attribute in the ``external_gateway_info`` 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 ``enable_snat`` attribute is not specified, it
will default to ``True``. For instance, if the current SNAT status is
disabled, and the router's gateway is updated to a different external
network without specifying ``enable_snat``, SNAT will be enabled for the
new network.

It is important to note that whenever updating a router's external
gateway information, the ``network_id``\ 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.

The rest of this section provides some samples for updating a router's
external gateway info with SNAT mode.

**Example Disable SNAT for the current external network**

.. code::

    {
        "router":
        {
            "name": "another_router",
            "admin_state_up": true,
            "external_gateway_info": {
                "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8"}
        }
    }

.. code::

    {
       "router":{
          "status":"ACTIVE",
          "external_gateway_info":{
             "network_id":"3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
             "enable_snat":true
          },
          "name":"another_router",
          "admin_state_up":true,
          "tenant_id":"6b96ff0cb17a4b859e1e575d221683d3",
          "id":"8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
       }
    }

.. code::

    {
       "router":{
          "status":"ACTIVE",
          "external_gateway_info":{
             "network_id":"3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
             "enable_snat":false
          },
          "name":"another_router",
          "admin_state_up":true,
          "tenant_id":"6b96ff0cb17a4b859e1e575d221683d3",
          "id":"8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
       }
    }

.. code::

    {
       "router":{
          "external_gateway_info":{
             "network_id":"3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
             "enable_snat":false
          }
       }
    }



**Example Change external network and enable SNAT**

.. code::

    {
        "router":
        {
            "name": "another_router",
            "admin_state_up": true,
            "external_gateway_info": {
                "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
                "enable_snat": false}
        }
    }

.. code::

    {
        "router":
        {
            "status": "ACTIVE",
            "external_gateway_info": {
                "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
                "enable_snat": false},
            "name": "another_router",
            "admin_state_up": true,
            "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
            "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
         }
    }

.. code::

    {
        "router":
        {
            "external_gateway_info": {
                "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5"}
        }
    }

.. code::

    {
        "router":
        {
            "status": "ACTIVE",
            "external_gateway_info": {
                "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5",
                "enable_snat": true},
            "name": "another_router",
            "admin_state_up": true,
            "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
            "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
         }
    }



**Example Change external network and external-gateway SNAT
disabled**

.. code::

    {
        "router":
        {
            "name": "another_router",
            "admin_state_up": true,
            "external_gateway_info": {
                "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
                "enable_snat": false}
        }
    }

.. code::

    {
        "router":
        {
            "status": "ACTIVE",
            "external_gateway_info": {
                "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
                "enable_snat": false},
            "name": "another_router",
            "admin_state_up": true,
            "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
            "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
         }
    }

.. code::

    {
        "router":
        {
            "external_gateway_info": {
                "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5",
                "enable_snat": false}
        }
    }

.. code::

    {
        "router":
        {
            "status": "ACTIVE",
            "external_gateway_info": {
                "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5",
                "enable_snat": false},
            "name": "another_router",
            "admin_state_up": true,
            "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
            "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
         }
    }



