en-US/multiple-ip-nic.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="multiple-ip-nic">
  <title>Configuring Multiple IP Addresses on a Single NIC</title>
  <para>&PRODUCT; provides you the ability to associate multiple private IP addresses per guest VM
    NIC. In addition to the primary IP, you can assign additional IPs to the guest VM NIC. This
    feature is supported on all the network configurations&mdash;Basic, Advanced, and VPC. Security
    Groups, Static NAT and Port forwarding services are supported on these additional IPs. </para>
  <para>As always, you can specify an IP from the guest subnet; if not specified, an IP is
    automatically picked up from the guest VM subnet. You can view the IPs associated with for each
    guest VM NICs on the UI. You can apply NAT on these additional guest IPs by using network
    configuration option in the &PRODUCT; UI. You must specify the NIC to which the IP should be
    associated.</para>
  <para>This feature is supported on XenServer, KVM, and VMware hypervisors. Note that Basic zone
    security groups are not supported on VMware.</para>
  <section id="usecases-mip">
    <title>Use Cases</title>
    <para>Some of the use cases are described below:</para>
    <itemizedlist>
      <listitem>
        <para>Network devices, such as firewalls and load balancers, generally work best when they
          have access to multiple IP addresses on the network interface.</para>
      </listitem>
      <listitem>
        <para>Moving private IP addresses between interfaces or instances. Applications that are
          bound to specific IP addresses can be moved between instances. </para>
      </listitem>
      <listitem>
        <para>Hosting multiple SSL Websites on a single instance. You can install multiple SSL
          certificates on a single instance, each associated with a distinct IP address.</para>
      </listitem>
    </itemizedlist>
  </section>
  <section id="guideline-nic">
    <title>Guidelines</title>
    <para>To prevent IP conflict, configure different subnets when multiple networks are connected
      to the same VM.</para>
  </section>
  <section id="workflow-rn">
    <title>Assigning Additional IPs to a VM</title>
    <orderedlist>
      <listitem>
        <para>Log in to the &PRODUCT; UI.</para>
      </listitem>
      <listitem>
        <para>In the left navigation bar, click Instances.</para>
      </listitem>
      <listitem>
        <para>Click the name of the instance you want to work with.</para>
      </listitem>
      <listitem>
        <para>In the Details tab, click NICs.</para>
      </listitem>
      <listitem>
        <para>Click View Secondary IPs.</para>
      </listitem>
      <listitem>
        <para>Click Acquire New Secondary IP, and click Yes in the confirmation dialog.</para>
        <para>You need to configure the IP on the guest VM NIC manually. &PRODUCT; will not
          automatically configure the acquired IP address on the VM. Ensure that the IP address
          configuration persist on VM reboot.</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 StaticNAT rules.</para>
      </listitem>
    </orderedlist>
  </section>
  <section id="caveats">
    <title>Port Forwarding and StaticNAT Services Changes</title>
    <para>Because multiple IPs can be associated per NIC, you are allowed to select a desired IP for
      the Port Forwarding and StaticNAT services. The default is the primary IP. To enable this
      functionality, an extra optional parameter 'vmguestip' is added to the Port forwarding and
      StaticNAT APIs (enableStaticNat, createIpForwardingRule) to indicate on what IP address NAT
      need to be configured. If vmguestip is passed, NAT is configured on the specified private IP
      of the VM. if not passed, NAT is configured on the primary IP of the VM.</para>
  </section>
</section>