Lesson 5 - Panorama.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "# Lesson 5 - Panorama"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "## Connect via Panorama\n",
    "\n",
    "Panorama makes connecting to firewalls and sharing configuration between firewalls much easier. In all previous lessons you connected directly to a live firewall. In this lesson, you'll make changes on the firewall just like you did in previous lessons, but without ever needing the firewall's IP, username, or password, because Panorama will facilitate the connection the firewall for you. Device Framework makes this easy by simply acting according to the structure of the configuration tree.\n",
    "\n",
    "When Device Framework is told to operate on a resource on a live firewall, Device Framework will make a connection to the nearest device in the configuration tree with a hostname/IP set. In all previous lessons, this was a Firewall object at the root of the tree. But let's look at an example where the root object is not a Firewall, and the Firewall has no login information:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "# This time, import the 'panorama' module, too\n",
    "from pandevice import panorama, firewall, objects"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "# Create a config tree with Panorama at the root\n",
    "pano = panorama.Panorama('10.30.11.5', 'admin', 'Ignite18')\n",
    "fw = firewall.Firewall(serial='015351000001577')\n",
    "obj = objects.AddressObject('Server5', '5.5.5.5', description='Created on FW via Panorama')\n",
    "pano.add(fw)\n",
    "fw.add(obj)\n",
    "pano.tree()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "Notice in this case the Firewall object has no login information. No IP, username, or password. We created it with a serial number instead, so that Panorama knows which firewall this Firewall object represents.\n",
    "\n",
    "Now, create the address object on the firewall."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "obj.create()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "Use the firewall GUI to verify the address object was created. In order to create the address object on the firewall, Device Framework connected to Panorama, and Panorama connected to the firewall. When `obj.create()` was called, the Panorama object was the closes device to `obj` in the tree that had a hostname, so Device Framework made a connection to Panorama, not the firewall. If you added a hostname and credentials to the Firewall object, then the connection would be made to the firewall.\n",
    "\n",
    "The net effect of this technique is the same as if Device Framework connected to the firewall directly, but this way you don't have to store the credentials of every firewall. As long as you know the credentials of Panorama and the serial of the firewall you are targeting, you can connect through Panorama but act as if you're directly connected to the firewall."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "## Connection vs Scope\n",
    "\n",
    "In the last section you connected to Panorama to create an address object, but the **scope** of the address object was still the Firewall, not Panorama. The address object was not created on Panorama, because Panorama only facilitated the connection. This decoupling of connection point and scope is very powerful. You define where to connect, and the scope of the object, with the structure of the configuration tree.\n",
    "\n",
    "Next, we'll explore another possible object scope: Device Groups"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "## Device Groups\n",
    "\n",
    "Device Groups are specific to Panorama and are a collection of policies and objects that are shared across multiple firewalls. In previous lessons, you placed policies and objects under a Firewall object in the configuration tree, but you can place them under a DeviceGroup object instead. Any policies and objects under a DeviceGroup object will be shared across any Firewall objects also under that DeviceGroup object.\n",
    "\n",
    "Let's look at an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "# Import the needed modules and create a fresh Panorama object\n",
    "from pandevice import panorama, firewall, objects\n",
    "pano = panorama.Panorama('10.30.11.5', 'admin', 'Ignite18')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "# Use a special method to refresh all firewalls and device-groups on Panorama at once\n",
    "pano.refresh_devices(add=True)\n",
    "pano.tree()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "**WAIT**, that cell might take a few seconds to finish. Hold here until the config tree appears."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "# Put the firewall and device group into variables so we can move them around\n",
    "fw = pano.find('015351000001577', firewall.Firewall)\n",
    "dg = pano.find('FW01-Group')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "# Remove the firewall from Panorama, and add it to the Device Group\n",
    "pano.remove(fw)\n",
    "dg.add(fw)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "pano.tree()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "# Now create some AddressObjects\n",
    "obj1 = fw.add(objects.AddressObject('Firewall-scope-object', '1.1.1.1'))\n",
    "obj2 = dg.add(objects.AddressObject('DeviceGroup-scope-object', '2.2.2.2'))\n",
    "pano.tree()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "# Apply all the changed objects\n",
    "fw.create()\n",
    "obj1.create()\n",
    "obj2.create()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "Notice we had to call `create()` on the `fw` Firewall object. That's because it also changed, it was moved into a device group. So essentially this is creating the firewall inside the device group. To move it to another device group, you would first `delete()` it from this device group, then `create()` it in another.\n",
    "\n",
    "Verify everything worked by checking the Panorama and Firewall GUI's.  Under **Objects -> Addresses** you should see the **Firewall-scope-object** on the firewall and the **DeviceGroup-scope-object** on the Panorama inside the FW01-Group device group."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "## Scope Example\n",
    "\n",
    "There are many scopes that an object can have, here are a few examples of places you can put objects:\n",
    "\n",
    "- Firewall - shared\n",
    "- Firewall - in a specific vsys\n",
    "- Panorama - shared\n",
    "- Panorama - in a specific device group\n",
    "- Panorama - in a specific template\n",
    "\n",
    "Each one of these scopes can be represented in the configuration tree by placement of an object in a specific place in the config tree that represents that scope.\n",
    "\n",
    "This example demonstrates placing an object in each one of the above scopes using a single configuration tree:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "from pandevice import panorama, firewall, network, objects, device\n",
    "# Create scopes: Panorama, Firewall, Device Group, Vsys, and Template\n",
    "pano = panorama.Panorama('10.30.11.5', 'admin', 'Ignite18')\n",
    "dg = panorama.DeviceGroup('MyDeviceGroup')\n",
    "fw = firewall.Firewall(serial='015351000001577')\n",
    "vsys = device.Vsys('vsys2', 'MyVsys')\n",
    "template = panorama.Template('MyTemplate')\n",
    "\n",
    "# Create objects to place in different scopes\n",
    "obj1 = objects.AddressObject('Firewall-shared', '1.1.1.1')\n",
    "obj2 = objects.AddressObject('Firewall-in a specific vsys', '1.1.1.1')\n",
    "obj3 = objects.AddressObject('Panorama-shared', '1.1.1.1')\n",
    "obj4 = objects.AddressObject('Panorama-in a specific device group', '1.1.1.1')\n",
    "obj5 = network.Zone('Panorama-in a specific template')\n",
    "\n",
    "# Build configuration tree\n",
    "pano.add(dg)\n",
    "pano.add(template)\n",
    "dg.add(fw)\n",
    "fw.add(vsys)\n",
    "\n",
    "# Add objects to different scopes in configuration tree\n",
    "fw.add(obj1)\n",
    "vsys.add(obj2)\n",
    "pano.add(obj3)\n",
    "dg.add(obj4)\n",
    "template.add(obj5)\n",
    "\n",
    "# Show the configuraiton tree\n",
    "pano.tree()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "This is a complex example and not really functional, so don't worry if you don't fully understand it. Consider this as a reference and an example of the possibilities."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "## Commit and Push\n",
    "\n",
    "In Lesson 3 you learned how to perform a commit on a firewall. Commit to firewalls from Panorama is a 2 step process. First, you commit the changes to Panorama itself. Then, push the changes to the firewalls. This second step is called a 'push' in the Panorama GUI, but it's called a 'commit-all' in the API. Different terms, but same action.\n",
    "\n",
    "Let's commit the changes to the device group and firewall. This cell is performing 2 commits so **it might take a while**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false
   },
   "outputs": [],
   "source": [
    "commit_result = pano.commit(sync=True)\n",
    "commitall_result = pano.commit_all(sync=True, devicegroup='FW01-Group')\n",
    "\n",
    "# Print the results of the commits\n",
    "from pprint import pformat\n",
    "print(\"Commit result: {}\".format(pformat( commit_result )))\n",
    "print(\"Commit-all result: {}\".format(pformat( commitall_result )))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "Examine the return values of the commit commands. The first commit is on Panorama only, so it has one result field. The second commit is actually a push to all the devices in the FW01-Group device group, so you get a result for the commit as a whole which indicates the commit initiated, and you get a result, errors, and warnings for each individual device by serial number. This is useful for programatically tracking down commit failures on specific devices and responding with a remediation or rollback."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "## Next steps\n",
    "\n",
    "There is a lot more power and possibility in using Panorama with Device Framework than is covered in this lesson, but the tools you learned here will help you explore the Device Framework API reference to learn other powerful techniques for configuration management across multiple firewalls.\n",
    "\n",
    "Next, you'll learn how to check the state and health of a firewall in [Lesson 6 - Operational Commands](Lesson 6 - Operational Commands.ipynb)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.4"
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}