view release on metacpan or  search on metacpan

lib/Device/Firewall/PaloAlto.pm  view on Meta::CPAN

       protocol => 6, port => 443
    );

    ok( $flow, 'Flow was allowed' );
    say "Flow hit rule: ".$flow->rulename;

    # Add and remove user ID information on the firewall
    $fw->user_id->add_ip_mapping('192.0.2.1', 'localdomain\greg.foletta');

    # If the module is used in a one liner, fw() sub is exported to make
    # it easier to use, and to_json() automatically prints to STDOUT.
    bash% perl -MDevice::Firewall::PaloAlto -E 'fw()->op->arp_table->to_json'

=head1 DESCRIPTION

This module provides an interface to the Palo Alto firewall API.

=head1 FUNCTIONS 

=head2 fw()

This is exported automatically into the main:: namespace if the module is
loaded within a one-liner - i.e. the calling script name is '-e'. If the module is
loaded within a normal script, this sub is not exported into main (though is of course accessible
using C<Device::Firewall::PaloAlto::fw()>.)

The purpose of this sub is to reduce the amount of code needed in one liners. As an example

    # Long way
    % perl -MDevice::Firewall::PaloAlto -E 'Device::Firewall::PaloAlto::new(vefify_hostname => 0)->auth->op->system_info->to_json'
    
    # Shorter way
    % perl -MDevice::Firewall::PaloAlto -E 'fw()->op->system_info->to_json'

The sub takes C<($user, $pass, $verify)> arguments. If C<$user> and C<$pass> arguments are not specified,
their undefinedness is passed through to C<new()> and either environment variables are used or they default
to 'admin'. 

If C<$verify> is not specified, C<new()> is called with C<verify_hostname => 0>, and thus the TLS certificate is
not verified. This is opposite to the default behaviour of C<new()> where the verification is performed.

=head1 METHODS

=head2 new

    my $fw = Device::Firewall::PaloAlto(
        uri => 'https://pa.localdomain',
        username => 'user',
        password => 'pass',
        verify_hostname => 1
    );

The C<new()> method creates a new Device::Firewall::PaloAlto object. The uri, username and password can be
passed in using the environment variables 'PA_FW_URI', PA_FW_USERNAME and PA_FW_PASSWORD. If no environment
variables are set, the username and password both default to 'admin'.

=head2 auth

    my $fw = $fw->auth;

This function authenticates the credentials passed to new against the firewall.

If successful, it returns the object itself to all method calls to be chains. If unsuccessful, it returns a L<Class::Error> object.

=head2 debug

    $fw->debug->op->interfaces();

Enables the debugging of HTTP requests and responses to the firewall.

=head2 undebug 

Disables debugging.

=head2 op

Returns a L<Device::Firewall::PaloAlto::Op> object. This object has methods to perform operational tasks on the firewall.

    my $fw_op = $fw->auth->op();
   
    # Return the firewall's interfaces
    my $interfaces = $fw_op->interfaces();

    # Return the ARP table
    my $arp_table = $fw->op->arp_table();

    # Returns the routes in the guest_vr virtual router
    my $routes = $fw->op->virtual_router('guest_vr');

=head2 user_id

Provides access to the L<Device::Firewall::PaloAlto::UserID> module. This module contains subroutines to add and remove dynamic IP to user mappings:

    # Add a mapping
    $fw->user_id->add_ip_mapping('192.0.2.1', 'localdomain\greg.foletta');

    # Remove a mapping
    $fw->user_id->rm_ip_mapping('192.0.2.1', 'localdomain\greg.foletta');

Refer to the module documentation for more information.

=head2 test

Provides access to the L<Device::Firewall::PaloAlto::Test> module. This module allows you to test the current state of a firewall.

    use Test::More;
    $test = $fw->test;
    ok( $test->interfaces('ethernet1/1', 'ethernet1/2'), 'Interfaces up' );

=head1 ERRORS

Errors are handled differently depending on whether the script is running from a file, or from a 'one-liner'.

=head2 File Errors

In the event of an error, a L<Class::Error> object is returned. The module's documentation provides the best information, but essentially it slurps up any method calls, evaluates to false in a boolean context, and contains an error string and code.

This allows you to chain together method calls and the error is propagated all the way through. A suggested way of checking for errors would be:

    my $state = $fw->auth->op->interfaces->interface('ethernet1/1')->state or die $state->error();