API Key Generation
==================

The **panxapi.py** **-k** option performs the
``type=keygen`` API request to generate the API key for an administrator account.
The **-h** and **-l** (ell) options specify the hostname
or IP address of the firewall and username and password arguments for
the API request.

Example: Generate API Key
-------------------------
::

  $ panxapi.py -h 10.30.11.101 -l admin:admin -k
  keygen: success
  API key:  "LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09"

.. note:: For brevity, the labs use the superuser administrator
   account ``admin``; creating API
   administrator accounts using a custom admin role with the least
   privilege set of XML API types required for your usage,
   is recommended.

A
`.panrc <https://github.com/kevinsteves/pan-python/blob/master/doc/panrc.rst>`_
file contains hostname and API key variables optionally
referenced by a *tagname* using the **panxapi.py** **-t** option. The `.panrc`
file is a convenient way to store API keys for all your firewalls in
a file, then reference those keys by tag when executing API calls. You'll
create a .panrc file in 'Lab 2' at the bottom of this page and use it
for all following API calls.

When **-t** is combined with **-h**, **-l** and **-k**, **panxapi.py**
writes ``.panrc`` format lines with the ``hostname`` and ``api_key``
variables to *stdout*.

Example: Generate .panrc Format Without *tagname*
-------------------------------------------------

Use a null string for the *tagname* to create tagless variables;
these are matched when **-t** is not specified.

::

  $ panxapi.py -t '' -h 10.30.11.101 -l admin:admin -k
  keygen: success
  # panxapi.py generated: 2017/04/08 09:05:42
  hostname=10.30.11.101
  api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09


Example: Generate .panrc Format With *tagname*
----------------------------------------------
::

  $ panxapi.py -t xapilab -h 10.30.11.101 -l admin -k
  Password:
  keygen: success
  # panxapi.py generated: 2017/04/08 09:08:47
  hostname%xapilab=10.30.11.101
  api_key%xapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

.. note::

   When the password is not specified on the command line the user is
   prompted for it.  This is useful to avoid leaving the password in
   the shell history.

Example: Create .panrc File Using Shell Output Redirection
----------------------------------------------------------

Shell output redirection can be used to create your ``.panrc`` file.

::

  $ panxapi.py -t xapilab -h 10.30.11.101 -l admin -k >> ~/.panrc
  Password:
  keygen: success

  $ chmod 600 ~/.panrc

.. note::

   The ``.panrc`` file contains authentication material; it
   should have strict file permissions (read/write for the owner, and
   not accessible by group or other).

The ``.panrc`` file entries with your *tagname* are verified
by performing an operational command API request with **-o** *cmd*.

Example: Verify .panrc File
---------------------------
::

  $ panxapi.py -t xapilab -Xxo 'show clock'
  op: success
  <response status="success"><result>Sat Apr  8 09:14:44 PDT 2017
  </result></response>

.. note:: **-X** converts a CLI command to XML which is
   required for the API request: ``show clock`` is converted
   to ``<show><clock></clock></show>``.

   **-x** prints the XML response to *stdout*.

Lab 2
-----

#. Create a ``.panrc`` file in your account's **$HOME** directory
   containing entries for your lab firewall **api_key** and
   **hostname**.

   .. hint:: Use the shell redirection method shown above.

	     Create the ``.panrc`` entries without a *tagname*
	     because the lab examples do not specify a **-t** option.

   .. note:: Your lab environment administrator password may not be
             ``admin``.  An invalid password for a ``type=keygen``
	     request will result in ``403 Forbidden``.

#. Perform an operational command API request to verify your ``.panrc``
   file **api_key** and **hostname** entries.

.. admonition:: Solution
   :class: toggle

   ::

     $ panxapi.py -t '' -h 10.30.11.101 -l admin:admin -k >> ~/.panrc
     keygen: success

     $ panxapi.py -Xxo 'show clock'
     op: success
     <response status="success"><result>Sat Apr  8 09:29:36 PDT 2017
     </result></response>