improve pvlan usage section (#83)
diff --git a/source/_imagesource/pvlans.drawio b/source/_imagesource/pvlans.drawio
new file mode 100644
index 0000000..984953a
--- /dev/null
+++ b/source/_imagesource/pvlans.drawio
@@ -0,0 +1 @@
+<mxfile host="Chrome" modified="2019-10-09T13:28:47.165Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36" version="12.1.0" etag="FKAbdMejNJbJpPzL8ecu" type="device" pages="1"><diagram id="cEOUKJeksBoM-9QyOMCy" name="Page-1">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</diagram></mxfile>
\ No newline at end of file
diff --git a/source/_static/images/pvlans.png b/source/_static/images/pvlans.png
new file mode 100644
index 0000000..8095a7a
--- /dev/null
+++ b/source/_static/images/pvlans.png
Binary files differ
diff --git a/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst b/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst
index 61a4e57..33fda6f 100644
--- a/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst
+++ b/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst
@@ -14,72 +14,16 @@
under the License.
-Isolation in Advanced Zone Using Private VLAN
----------------------------------------------
+Isolation in Advanced Zone Using Private VLANs
+-----------------------------------------------
-Isolation of guest traffic in shared networks can be achieved by using
-Private VLANs (PVLAN). PVLANs provide Layer 2 isolation between ports
-within the same VLAN. In a PVLAN-enabled shared network, a user VM
-cannot reach other user VM though they can reach the DHCP server and
-gateway, this would in turn allow users to control traffic within a
-network and help them deploy multiple applications without communication
-between application as well as prevent communication with other users'
-VMs.
+About PVLANs (Secondary VLANs)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Isolate VMs in a shared networks by using Private VLANs.
+The clasic use-case for PVLANs is a shared backup network, where you wish all users'
+hosts to be able to communicate with a backup host, but not with each other.
-- Supported on KVM, XenServer, and VMware hypervisors
-
-- PVLAN-enabled shared network can be a part of multiple networks of a
- guest VM.
-
-
-About Private VLAN
-~~~~~~~~~~~~~~~~~~
-
-In an Ethernet switch, a VLAN is a broadcast domain where hosts can
-establish direct communication with each another at Layer 2. Private
-VLAN is designed as an extension of VLAN standard to add further
-segmentation of the logical broadcast domain. A regular VLAN is a single
-broadcast domain, whereas a private VLAN partitions a larger VLAN
-broadcast domain into smaller sub-domains. A sub-domain is represented
-by a pair of VLANs: a Primary VLAN and a Secondary VLAN. The original
-VLAN that is being divided into smaller groups is called Primary, which
-implies that all VLAN pairs in a private VLAN share the same Primary
-VLAN. All the secondary VLANs exist only inside the Primary. Each
-Secondary VLAN has a specific VLAN ID associated to it, which
-differentiates one sub-domain from another.
-
-Three types of ports exist in a private VLAN domain, which essentially
-determine the behaviour of the participating hosts. Each ports will have
-its own unique set of rules, which regulate a connected host's ability
-to communicate with other connected host within the same private VLAN
-domain. Configure each host that is part of a PVLAN pair can be by using
-one of these three port designation:
-
-- **Promiscuous**: A promiscuous port can communicate with all the
- interfaces, including the community and isolated host ports that
- belong to the secondary VLANs. In Promiscuous mode, hosts are
- connected to promiscuous ports and are able to communicate directly
- with resources on both primary and secondary VLAN. Routers, DHCP
- servers, and other trusted devices are typically attached to
- promiscuous ports.
-
-- **Isolated VLANs**: The ports within an isolated VLAN cannot
- communicate with each other at the layer-2 level. The hosts that are
- connected to Isolated ports can directly communicate only with the
- Promiscuous resources. If your customer device needs to have access
- only to a gateway router, attach it to an isolated port.
-
-- **Community VLANs**: The ports within a community VLAN can
- communicate with each other and with the promiscuous ports, but they
- cannot communicate with the ports in other communities at the layer-2
- level. In a Community mode, direct communication is permitted only
- with the hosts in the same community and those that are connected to
- the Primary PVLAN in promiscuous mode. If your customer has two
- devices that need to be isolated from other customers' devices, but
- to be able to communicate among themselves, deploy them in community
- ports.
+ |pvlans.png|
For further reading:
@@ -92,6 +36,19 @@
- `Private VLAN (PVLAN) on vNetwork Distributed Switch - Concept
Overview (1010691) <http://kb.vmware.com>`_
+Supported Secondary VLAN types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Of the three types of Private VLAN (promiscuous, community and isolated),
+CloudStack supports **one promiscuous** PVLAN and **one isolated** PVLAN **per
+primary VLAN**. Ergo, community PVLANs are not currently supported.
+PVLANs are only currently supported on shared networks.
+The PVLAN concept is supported on KVM (when using OVS), XenServer (when using OVS), and VMware hypervisors
+
+ .. note::
+ OVS on XenServer and KVM does not support PVLAN natively. Therefore,
+ CloudStack managed to simulate PVLAN on OVS for XenServer and KVM by
+ modifying the flow table.
Prerequisites
~~~~~~~~~~~~~
@@ -119,84 +76,24 @@
- Before you use PVLAN on XenServer and KVM, enable Open vSwitch (OVS).
- .. note::
- OVS on XenServer and KVM does not support PVLAN natively. Therefore,
- CloudStack managed to simulate PVLAN on OVS for XenServer and KVM by
- modifying the flow table.
+
+Creating a PVLAN-Enabled Shared Network
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For a general description of how to create a shared netowrk see `"configuring a shared guest network" <#configuring-a-shared-guest-network>`_.
+
+On top of the parameters required to create a *normal* shared network, the following
+parameters must be set:
+
+- **VLAN ID**: The unique ID of the primary VLAN that you want to use.
+
+- **Secondary Isolated VLAN ID**:
+
+ - For a **promiscuous** PVLAN, set this to the same VLAN ID as the primary VLAN
+ that the promiscuous PVLAN will be inside.
+ - For an **isolated** PVLAN, set this to the PVLAN ID which you wish to use
+ inside the primary VLAN.
-Creating a PVLAN-Enabled Guest Network
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-#. Log in to the CloudStack UI as administrator.
-
-#. In the left navigation, choose Infrastructure.
-
-#. On Zones, click View More.
-
-#. Click the zone to which you want to add a guest network.
-
-#. Click the Physical Network tab.
-
-#. Click the physical network you want to work with.
-
-#. On the Guest node of the diagram, click Configure.
-
-#. Click the Network tab.
-
-#. Click Add guest network.
-
- The Add guest network window is displayed.
-
-#. Specify the following:
-
- - **Name**: The name of the network. This will be visible to the
- user.
-
- - **Description**: The short description of the network that can be
- displayed to users.
-
- - **VLAN ID**: The unique ID of the VLAN.
-
- - **Secondary Isolated VLAN ID**: The unique ID of the Secondary
- Isolated VLAN.
-
- For the description on Secondary Isolated VLAN, see
- `About Private VLAN" <#about-private-vlan>`_.
-
- - **Scope**: The available scopes are Domain, Account, Project, and
- All.
-
- - **Domain**: Selecting Domain limits the scope of this guest
- network to the domain you specify. The network will not be
- available for other domains. If you select Subdomain Access,
- the guest network is available to all the sub domains within
- the selected domain.
-
- - **Account**: The account for which the guest network is being
- created for. You must specify the domain the account belongs
- to.
-
- - **Project**: The project for which the guest network is being
- created for. You must specify the domain the project belongs
- to.
-
- - **All**: The guest network is available for all the domains,
- account, projects within the selected zone.
-
- - **Network Offering**: If the administrator has configured multiple
- network offerings, select the one you want to use for this
- network.
-
- - **Gateway**: The gateway that the guests should use.
-
- - **Netmask**: The netmask in use on the subnet the guests will use.
-
- - **IP Range**: A range of IP addresses that are accessible from the
- Internet and are assigned to the guest VMs.
-
- - **Network Domain**: A custom DNS suffix at the level of a network.
- If you want to assign a special domain name to the guest VM
- network, specify a DNS suffix.
-
-#. Click OK to confirm.
+.. |pvlans.png| image:: /_static/images/pvlans.png
+ :alt: Diagram of PVLAN communications
