# pan.licapi

## Python interface to the PAN-OS Licensing API

# NAME

> pan.licapi - Python interface to the PAN-OS Licensing API

# SYNOPSIS

    import pan.licapi

    try:
        licapi = pan.licapi.PanLicapi(panrc_tag='license')
    except pan.licapi.PanLicapiError as e:
        print('pan.licapi.PanLicapi:', e, file=sys.stderr)
        sys.exit(1)

    try:
        r = licapi.get(authcode='I3546330')
    except pan.licapi.PanLicapiError as e:
        print('get:', e, file=sys.stderr)
        sys.exit(1)

    try:
        r.raise_for_status()
    except pan.licapi.PanLicapiError as e:
        print('get:', e, file=sys.stderr)
        sys.exit(1)

    print(r.json)

# DESCRIPTION

> The pan.licapi module defines the PanLicapi class, which provides an interface to the PAN-OS Licensing API.

> PanLicapi provides an interface to all Licensing API requests:

> Request | PanLicapi Method | API Resource URI
> --- | --- | ---
> activate VM license | activate() | /api/license/activate
> deactivate VM license | deactivate() | /api/license/deactivate
> get quantity of VM provisioned | get() | /api/license/get

## pan.licapi Constants

> __version__
>   pan package version string.
> DEBUG1, DEBUG2, DEBUG3
>   Python `logging` module debug levels (see Debugging and Logging below).
> DEFAULT_API_VERSION
>   Default API version.

## pan.licapi Constructor, Response object and Exception Class

### class pan.licapi.PanLicapi()

>     class pan.licapi.PanLicapi(api_version=None,
>                                panrc_tag=None,
>                                hostname=None,
>                                api_key=None,
>                                timeout=None,
>                                verify_cert=True)

> api_version

>   API version as a string in the form vversion or version (e.g., v1). The API version is used to determine the PanLicapi class implementation to use.

>   The default API version is DEFAULT_API_VERSION.

>   api_version is verified and the class attribute is set to an instance of the _ApiVersion class (defined below).

> panrc_tag
>   .panrc tagname.
> hostname

>   URI hostname used in API requests. This can also be specified in a .panrc file using the `hostname` varname.

>   The default is `api.paloaltonetworks.com`.

> api_key
>   `apikey` HTTP request header argument used in API requests. This can also be specified in a .panrc file using the `api_key` varname.
> timeout
>   The HTTP connect `timeout` in seconds.
> verify_cert

>   Specify if SSL server certificate verification is performed.

>   The default is to verify the server certificate.

### exception pan.licapi.PanLicapiError

> Exception raised by the PanLicapi class when an error occurs. The string representation of an instance of this exception will contain a user-friendly error message.

### class pan.licapi.PanLicapiRequest()

> The results of a request are returned in a PanLicapiRequest object.

### pan.licapi.PanLicapiRequest Class Attributes and Methods

> Attribute | Description
> --- | ---
> name | Method name for the request
> wall_time | Wall time of API request in seconds (floating point number)
> http_code | HTTP response status code
> http_reason | HTTP response status reason
> http_headers | HTTP headers. This is an email.message.Message object.
> http_encoding | Charset (set using `email.message.Message.get_content_charset()`)
> http_content_type | Content type (set using `email.message.Message.get_content_type()`)
> http_content | HTTP response body (bytes)
> http_text | HTTP response body (Unicode)
> json | HTTP response body (JSON)

### raise_for_status()

> The `raise_for_status()` method will raise PanLicapiError when the http_code attribute is not a 2XX success class status code.

> A non-2XX status code will not by default cause an exception to be raised.

## pan.licapi.PanLicapi Methods

### activate(authcode=None, uuid=None, cpuid=None, serialnumber=None)

> The `activate()` method performs the `/api/license/activate` API request to activate a VM license.

> authcode
>   License Auth Code.
> uuid
>   VM-Series vm-uuid.
> cpuid
>   VM-Series vm-cpuid.
> serialnumber
>   Previously activated device serial number.

> There are 3 calling sequences depending upon the arguments passed:

> Arguments | Description
> --- | ---
> authcode, uuid, cpuid | Activate new license and return licenses
> uuid, cpuid | Get previously activated licenses
> serialnumber | Get previously activated licenses

### deactivate(encryptedtoken=None)

> The `deactivate()` method performs the `/api/license/deactivate` API request to deactivate a VM license.

> encryptedtoken

>   The contents of the license-token-file from PAN-OS which is obtained using the operational command `request license deactivate VM-Capacity mode manual`.

>   The token file is exported from the device using `scp export license-token-file` or `tftp export license-token-file`.

>   Starting with PAN-OS 8.0 you can display the token file using `show license-token-files name`. This can be used to export the token file using the PAN-OS XML API.

### get(authcode=None)

> The `get()` method performs the `/api/license/get` API request to get the quantity of VM provisioned for an Auth Code.

> authcode
>   License Auth Code.

## pan.licapi._ApiVersion class Attributes and Methods

> The _ApiVersion class provides an interface to the API version of the PanLicapi class instance.

> Attribute | Description
> --- | ---
> version | version as an integer

### __str__()

> version as a string in the format vversion. (e.g., v1).

### __int__()

> version as an integer with the following layout:

> Bits (MSB 0 order) | Description
> --- | ---
> 0-7 | unused
> 8-15 | version
> 16-31 | reserved for future use

### Sample Usage

    import pan.licapi

    try:
        licapi = pan.licapi.PanLicapi(panrc_tag='license')
    except pan.licapi.PanLicapiError as e:
        print('pan.licapi.PanLicapi:', e, file=sys.stderr)
        sys.exit(1)

    print('api_version: %s, 0x%04x' %
          (licapi.api_version, licapi.api_version))

## Debugging and Logging

> The Python standard library `logging` module is used to log debug output; by default no debug output is logged.

> In order to obtain debug output the `logging` module must be configured: the logging level must be set to one of DEBUG1, DEBUG2, or DEBUG3 and a handler must be configured. DEBUG1 enables basic debugging output and DEBUG2 and DEBUG3 specify increasing levels of debug output.

> For example, to configure debug output to stderr:

>     import logging

>     if options['debug']:
>         logger = logging.getLogger()
>         if options['debug'] == 3:
>             logger.setLevel(pan.licapi.DEBUG3)
>         elif options['debug'] == 2:
>             logger.setLevel(pan.licapi.DEBUG2)
>         elif options['debug'] == 1:
>             logger.setLevel(pan.licapi.DEBUG1)

>         handler = logging.StreamHandler()
>         logger.addHandler(handler)

# FILES

> `.panrc`
>   .panrc file

# EXAMPLES

> The panlicapi.py command line program calls each available PanLicapi method and can be reviewed for sample usage.

# SEE ALSO

> panlicapi.py

> Licensing API
>   https://docs.paloaltonetworks.com/vm-series/10-2/vm-series-deployment/license-the-vm-series-firewall/licensing-api.html

# AUTHORS

> Palo Alto Networks, Inc. <techbizdev@paloaltonetworks.com>