.. 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.


Setup a Palo Alto Networks Firewall
-----------------------------------


Functionality Provided
~~~~~~~~~~~~~~~~~~~~~~

This implementation enables the orchestration of a Palo Alto Networks Firewall 
from within CloudStack UI and API.  

**The following features are supported**:

-  List/Add/Delete Palo Alto Networks service provider

-  List/Add/Delete Palo Alto Networks network service offering

-  List/Add/Delete Palo Alto Networks network using the above service offering

-  Add an instance to a Palo Alto Networks network

-  Source NAT management on network create and delete

-  List/Add/Delete Ingress Firewall rule

-  List/Add/Delete Egress Firewall rule (both 'Allow' and 'Deny' default rules 
   supported)

-  List/Add/Delete Port Forwarding rule

-  List/Add/Delete Static NAT rule

-  Apply a Threat Profile to all firewall rules (more details in the 
   Additional Features section)

-  Apply a Log Forwarding profile to all firewall rules (more details in the 
   Additional Features section)


Initial Palo Alto Networks Firewall Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Anatomy of the Palo Alto Networks Firewall
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  In **'Network > Interfaces'** there is a list of physical interfaces as 
   well as aggregated physical interfaces which are used for managing traffic 
   in and out of the Palo Alto Networks Firewall device.

-  In **'Network > Zones'** there is a list of the different configuration 
   zones.  This implementation will use two zones; a public (defaults to 
   'untrust') and private (defaults to 'trust') zone.

-  In **'Network > Virtual Routers'** there is a list of VRs which handle 
   traffic routing for the Palo Alto Firewall.  We only use a single Virtual 
   Router on the firewall and it is used to handle all the routing to the next 
   network hop.

-  In **'Objects > Security Profile Groups'** there is a list of profiles 
   which can be applied to firewall rules.  These profiles are used to better 
   understand the types of traffic that is flowing through your network.  
   Configured when you add the firewall provider to CloudStack.

-  In **'Objects > Log Forwarding'** there is a list of profiles which can be 
   applied to firewall rules.  These profiles are used to better track the 
   logs generated by the firewall.  Configured when you add the firewall 
   provider to CloudStack.

-  In **'Policies > Security'** there is a list of firewall rules that are 
   currently configured.  You will not need to modify this section because it 
   will be completely automated by CloudStack, but you can review the firewall 
   rules which have been created here.

-  In **'Policies > NAT'** there is a list of the different NAT rules.  You 
   will not need to modify this section because it will be completely 
   automated by CloudStack, but you can review the different NAT rules that 
   have been created here.  Source NAT, Static NAT and Destination NAT (Port 
   Forwarding) rules will show up in this list.


Configure the Public / Private Zones on the firewall
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

No manual configuration is required to setup these zones because CloudStack 
will configure them automatically when you add the Palo Alto Networks firewall 
device to CloudStack as a service provider.  This implementation depends on 
two zones, one for the public side and one for the private side of the 
firewall.  

-  The public zone (defaults to 'untrust') will contain all of the public 
   interfaces and public IPs.

-  The private zone (defaults to 'trust') will contain all of the private 
   interfaces and guest network gateways.

The NAT and firewall rules will be configured between these zones.


Configure the Public / Private Interfaces on the firewall
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This implementation supports standard physical interfaces as well as grouped 
physical interfaces called aggregated interfaces.  Both standard interfaces 
and aggregated interfaces are treated the same, so they can be used 
interchangeably. For this document, we will assume that we are using 
'ethernet1/1' as the public interface and 'ethernet1/2' as the private 
interface.  If aggregated interfaces where used, you would use something 
like 'ae1' and 'ae2' as the interfaces.

This implementation requires that the 'Interface Type' be set to 'Layer3' for 
both the public and private interfaces.  If you want to be able to use the 
'Untagged' VLAN tag for public traffic in CloudStack, you will need to enable 
support for it in the public 'ethernet1/1' interface (details below).  

**Steps to configure the Public Interface**:

#. Log into Palo Alto Networks Firewall

#. Navigate to 'Network > Interfaces'

#. Click on 'ethernet1/1' (for aggregated ethernet, it will probably be called 
   'ae1')

#. Select 'Layer3' from the 'Interface Type' list

#. Click 'Advanced'

#. Check the 'Untagged Subinterface' check-box

#. Click 'OK'

**Steps to configure the Private Interface**:

#. Click on 'ethernet1/2' (for aggregated ethernet, it will probably be called 
   'ae2')

#. Select 'Layer3' from the 'Interface Type' list

#. Click 'OK'


Configure a Virtual Router on the firewall
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Virtual Router on the Palo Alto Networks Firewall is not to be confused 
with the Virtual Routers that CloudStack provisions.  For this implementation, 
the Virtual Router on the Palo Alto Networks Firewall will ONLY handle the 
upstream routing from the Firewall to the next hop.

**Steps to configure the Virtual Router**:

#. Log into Palo Alto Networks Firewall

#. Navigate to 'Network > Virtual Routers'

#. Select the 'default' Virtual Router or Add a new Virtual Router if there 
   are none in the list

   - If you added a new Virtual Router, you will need to give it a 'Name'

#. Navigate to 'Static Routes > IPv4'

#. 'Add' a new static route

   -  **Name**: next_hop (you can name it anything you want)
   
   -  **Destination**: 0.0.0.0/0 (send all traffic to this route)
   
   -  **Interface**: ethernet1/1 (or whatever you set your public interface 
      as)
   
   -  **Next Hop**: (specify the gateway IP for the next hop in your network)
   
   -  Click 'OK'

#. Click 'OK'


Configure the default Public Subinterface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The current implementation of the Palo Alto Networks firewall integration uses 
CIDRs in the form of 'w.x.y.z/32' for the public IP addresses that CloudStack 
provisions.  Because no broadcast or gateway IPs are in this single IP range, 
there is no way for the firewall to route the traffic for these IPs.  To route 
the traffic for these IPs, we create a single subinterface on the public 
interface with an IP and a CIDR which encapsulates the CloudStack public IP 
range.  This IP will need to be inside the subnet defined by the CloudStack 
public range netmask, but outside the CloudStack public IP range.  The CIDR 
should reflect the same subnet defined by the CloudStack public range netmask.  
The name of the subinterface is determined by the VLAN configured for the 
public range in CloudStack.

To clarify this concept, we will use the following example.

**Example CloudStack Public Range Configuration**:

-  **Gateway**: 172.30.0.1

-  **Netmask**: 255.255.255.0

-  **IP Range**: 172.30.0.100 - 172.30.0.199

-  **VLAN**: Untagged

**Configure the Public Subinterface**:

#. Log into Palo Alto Networks Firewall

#. Navigate to 'Network > Interfaces'

#. Select the 'ethernet1/1' line (not clicking on the name)

#. Click 'Add Subinterface' at the bottom of the window

#. Enter 'Interface Name': 'ethernet1/1' . '9999' 

   -  9999 is used if the CloudStack public range VLAN is 'Untagged'
   
   -  If the CloudStack public range VLAN is tagged (eg: 333), then the name 
      will reflect that tag

#. The 'Tag' is the VLAN tag that the traffic is sent to the next hop with, so 
   set it accordingly.  If you are passing 'Untagged' traffic from CloudStack 
   to your next hop, leave it blank.  If you want to pass tagged traffic from 
   CloudStack, specify the tag.

#. Select 'default' from the 'Config > Virtual Router' drop-down (assuming 
   that is what your virtual router is called)

#. Click the 'IPv4' tab

#. Select 'Static' from the 'Type' radio options

#. Click 'Add' in the 'IP' section

#. Enter '172.30.0.254/24' in the new line

   -  The IP can be any IP outside the CloudStack public IP range, but inside 
      the CloudStack public range netmask (it can NOT be the gateway IP)
   
   -  The subnet defined by the CIDR should match the CloudStack public range 
      netmask
   
#. Click 'OK'


Commit configuration on the Palo Alto Networks Firewall
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order for all the changes we just made to take effect, we need to commit 
the changes.

#. Click the 'Commit' link in the top right corner of the window

#. Click 'OK' in the commit window overlay

#. Click 'Close' to the resulting commit status window after the commit 
   finishes


Setup the Palo Alto Networks Firewall in CloudStack
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Add the Palo Alto Networks Firewall as a Service Provider
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Navigate to 'Infrastructure > Zones > ZONE_NAME > Physical Network > 
   NETWORK_NAME (guest) > Configure; Network Service Providers'

#. Click on 'Palo Alto' in the list

#. Click 'View Devices'

#. Click 'Add Palo Alto Device'

#. Enter your configuration in the overlay.  This example will reflect the 
   details previously used in this guide.

   -  **IP Address**: (the IP of the Palo Alto Networks Firewall)
   
   -  **Username**: (the admin username for the firewall)
   
   -  **Password**: (the admin password for the firewall)
   
   -  **Type**: Palo Alto Firewall
   
   -  **Public Interface**: ethernet1/1 (use what you setup earlier as the 
      public interface if it is different from my examples)
   
   -  **Private Interface**: ethernet1/2 (use what you setup earlier as the 
      private interface if it is different from my examples)
   
   -  **Number of Retries**: 2 (the default is fine)
   
   -  **Timeout**: 300 (the default is fine) 
   
   -  **Public Network**: untrust (this is the public zone on the firewall and 
      did not need to be configured)
   
   -  **Private Network**: trust (this is the private zone on the firewall and 
      did not need to be configured)
   
   -  **Virtual Router**: default (this is the name of the Virtual Router we 
      setup on the firewall)
   
   -  **Palo Alto Threat Profile**: (not required.  name of the 'Security 
      Profile Groups' to apply.  more details in the 'Additional Features' 
      section)
   
   -  **Palo Alto Log Profile**: (not required.  name of the 'Log Forwarding' 
      profile to apply.  more details in the 'Additional Features' section)
   
   -  **Capacity**: (not required) 
   
   -  **Dedicated**: (not required)

#. Click 'OK'

#. Click on 'Palo Alto' in the breadcrumbs to go back one screen.

#. Click on 'Enable Provider' |EnableDisableFeature.png|


Add a Network Service Offering to use the new Provider
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are 6 'Supported Services' that need to be configured in the network 
service offering for this functionality.  They are DHCP, DNS, Firewall, Source 
NAT, Static NAT and Port Forwarding.  For the other settings, there are 
probably additional configurations which will work, but I will just document a 
common case.

#. Navigate to 'Service Offerings'

#. In the drop-down at the top, select 'Network Offerings'

#. Click 'Add Network Offering'

   -  **Name**: (name it whatever you want)

   -  **Description**: (again, can be whatever you want)

   -  **Guest Type**: Isolated

   -  **Supported Services**:

      -  **DHCP**: Provided by 'VirtualRouter'

      -  **DNS**: Provided by 'VirtualRouter'

      -  **Firewall**: Provided by 'PaloAlto'

      -  **Source NAT**: Provided by 'PaloAlto'

      -  **Static NAT**: Provided by 'PaloAlto'

      -  **Port Forwarding**: Provided by 'PaloAlto'

   -  **System Offering for Router**: System Offering For Software Router

   -  **Supported Source NAT Type**: Per account (this is the only supported 
      option)

   -  **Default egress policy**: (both 'Allow' and 'Deny' are supported)

#. Click 'OK'

#. Click on the newly created service offering

#. Click 'Enable network offering' |EnableDisableFeature.png|

When adding networks in CloudStack, select this network offering to use the 
Palo Alto Networks firewall.


Additional Features
~~~~~~~~~~~~~~~~~~~

In addition to the standard functionality exposed by CloudStack, we have added 
a couple additional features to this implementation.  We did not add any new 
screens to CloudStack, but we have added a couple fields to the 'Add Palo Alto 
Service Provider' screen which will add functionality globally for the device.


Palo Alto Networks Threat Profile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This feature allows you to specify a 'Security Profile Group' to be applied to 
all of the firewall rules which are created on the Palo Alto Networks firewall 
device.

To create a 'Security Profile Group' on the Palo Alto Networks firewall, do 
the following: 

#. Log into the Palo Alto Networks firewall

#. Navigate to 'Objects > Security Profile Groups'

#. Click 'Add' at the bottom of the page to add a new group

#. Give the group a Name and specify the profiles you would like to include in 
   the group

#. Click 'OK'

#. Click the 'Commit' link in the top right of the screen and follow the on 
   screen instructions

Once you have created a profile, you can reference it by Name in the 'Palo 
Alto Threat Profile' field in the 'Add the Palo Alto Networks Firewall as a 
Service Provider' step.


Palo Alto Networks Log Forwarding Profile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This feature allows you to specify a 'Log Forwarding' profile to better manage 
where the firewall logs are sent to.  This is helpful for keeping track of 
issues that can arise on the firewall.

To create a 'Log Forwarding' profile on the Palo Alto Networks Firewall, do 
the following: 

#. Log into the Palo Alto Networks firewall

#. Navigate to 'Objects > Log Forwarding'

#. Click 'Add' at the bottom of the page to add a new profile

#. Give the profile a Name and specify the details you want for the traffic 
   and threat settings

#. Click 'OK'

#. Click the 'Commit' link in the top right of the screen and follow the on 
   screen instructions

Once you have created a profile, you can reference it by Name in the 'Palo 
Alto Log Profile' field in the 'Add the Palo Alto Networks Firewall as a 
Service Provider' step.


Limitations
~~~~~~~~~~~

-  The implementation currently only supports a single public IP range in 
   CloudStack
   
-  Usage tracking is not yet implemented

.. |EnableDisableFeature.png| image:: /_static/images/enable-disable-autoscale.png
   :alt: button to enable or disable feature.