en-US/portable-ip.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    http://www.apache.org/licenses/LICENSE-2.0
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
-->
<section id="portable-ip">
  <title>Portable IPs</title>
  <section id="about-pip">
    <title>About Portable IP</title>
    <para>Portable IPs in &PRODUCT; are region-level pool of IPs, which are elastic in nature, that
      can be transferred across geographically separated zones. As an administrator, you can
      provision a pool of portable public IPs at region level and are available for user
      consumption. The users can acquire portable IPs if admin has provisioned portable IPs at the
      region level they are part of. These IPs can be use for any service within an advanced zone.
      You can also use portable IPs for EIP services in basic zones. </para>
    <para>The salient features of Portable IP are as follows:<itemizedlist>
        <listitem>
          <para>IP is statically allocated </para>
        </listitem>
        <listitem>
          <para>IP need not be associated with a network </para>
        </listitem>
        <listitem>
          <para>IP association is transferable across networks </para>
        </listitem>
        <listitem>
          <para>IP is transferable across both Basic and Advanced zones </para>
        </listitem>
        <listitem>
          <para>IP is transferable across VPC, non-VPC isolated and shared networks </para>
        </listitem>
        <listitem>
          <para>Portable IP transfer is available only for static NAT. </para>
        </listitem>
      </itemizedlist></para>
    <formalpara>
      <title>Guidelines</title>
      <para>Before transferring to another network, ensure that no network rules (Firewall, Static
        NAT, Port Forwarding, and so on) exist on that portable IP.</para>
    </formalpara>
  </section>
  <section id="config-pip">
    <title>Configuring Portable IPs</title>
    <orderedlist>
      <listitem>
        <para>Log in to the &PRODUCT; UI as an administrator or end user.</para>
      </listitem>
      <listitem>
        <para>In the left navigation, click Regions.</para>
      </listitem>
      <listitem>
        <para>Choose the Regions that you want to work with.</para>
      </listitem>
      <listitem>
        <para>Click View Portable IP.</para>
      </listitem>
      <listitem>
        <para>Click Portable IP Range.</para>
        <para>The Add Portable IP Range window is displayed.</para>
      </listitem>
      <listitem>
        <para>Specify the following:</para>
        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Start IP/ End IP</emphasis>: A range of IP addresses that
              are accessible from the Internet and will be allocated to guest VMs. Enter the first
              and last IP addresses that define a range that &PRODUCT; can assign to guest
              VMs.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Gateway</emphasis>: The gateway in use for the Portable IP
              addresses you are configuring.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Netmask</emphasis>: The netmask associated with the Portable
              IP range.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">VLAN</emphasis>: The VLAN that will be used for public
              traffic.</para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>Click OK.</para>
      </listitem>
    </orderedlist>
  </section>
  <section id="acquire-pip">
    <title>Acquiring a Portable IP</title>
    <orderedlist>
      <listitem>
        <para>Log in to the &PRODUCT; UI as an administrator or end user. </para>
      </listitem>
      <listitem>
        <para>In the left navigation, choose Network.</para>
      </listitem>
      <listitem>
        <para>Click the name of the network where you want to work with.</para>
      </listitem>
      <listitem>
        <para>Click View IP Addresses.</para>
      </listitem>
      <listitem>
        <para>Click Acquire New IP.</para>
        <para>The Acquire New IP window is displayed.</para>
      </listitem>
      <listitem>
        <para>Specify whether you want cross-zone IP or not.</para>
      </listitem>
      <listitem>
        <para>Click Yes in the confirmation dialog.</para>
        <para>Within a few moments, the new IP address should appear with the state Allocated. You
          can now use the IP address in port forwarding or static NAT rules.</para>
      </listitem>
    </orderedlist>
  </section>
  <section id="transfer-pip">
    <title>Transferring Portable IP</title>
    <para>An IP can be transferred from one network to another only if Static NAT is enabled.
      However, when a portable IP is associated with a network, you can use it for any service in
      the network. </para>
    <para>To transfer a portable IP across the networks, execute the following API:</para>
    <programlisting>http://localhost:8096/client/api?command=enableStaticNat&amp;response=json&amp;ipaddressid=a4bc37b2-4b4e-461d-9a62-b66414618e36&amp;virtualmachineid=a242c476-ef37-441e-9c7b-b303e2a9cb4f&amp;networkid=6e7cd8d1-d1ba-4c35-bdaf-333354cbd49810 </programlisting>
    <para>Replace the UUID with appropriate UUID. For example, if you want to transfer a portable IP
      to network X and VM Y in a network, execute the following:</para>
    <programlisting>http://localhost:8096/client/api?command=enableStaticNat&amp;response=json&amp;ipaddressid=a4bc37b2-4b4e-461d-9a62-b66414618e36&amp;virtualmachineid=Y&amp;networkid=X
      </programlisting>
  </section>
</section>