NAME

Net::Cisco::ACS - Access Cisco ACS functionality through REST API

SYNOPSIS

	use Net::Cisco::ACS;
	my $acs = Net::Cisco::ACS->new(hostname => '10.0.0.1', username => 'acsadmin', password => 'testPassword');
	# Options:
	# hostname - IP or hostname of Cisco ACS 5.x server
	# username - Username of Administrator user
	# password - Password of user
	# ssl - SSL enabled (1 - default) or disabled (0)
		
	my %users = $acs->users;
	# Retrieve all users from ACS
	# Returns hash with username / Net::Cisco::ACS::User pairs
	
	print $acs->users->{"acsadmin"}->toXML;
	# Dump in XML format (used by ACS for API calls)
	
	my $user = $acs->users("name","acsadmin");
	# Faster call to request specific user information by name

	my $user = $acs->users("id","150");
	# Faster call to request specific user information by ID (assigned by ACS, present in Net::Cisco::ACS::User)

	my %identitygroups = $acs->identitygroups;
	# Retrieve all identitygroups from ACS
	# Returns hash with name / Net::Cisco::ACS::IdentityGroup pairs
	
	print $acs->identitygroups->{"All Groups"}->toXML;
	# Dump in XML format (used by ACS for API calls)
	
	my $identitygroup = $acs->identitygroups("name","All Groups");
	# Faster call to request specific identity group information by name

	my $identitygroup = $acs->identitygroups("id","150");
	# Faster call to request specific identity group information by ID (assigned by ACS, present in Net::Cisco::ACS::IdentityGroup)
	
	my %devices = $acs->devices;
	# Retrieve all devices from ACS
	# Returns hash with device name / Net::Cisco::ACS::Device pairs

	print $acs->devices->{"MAIN_Router"}->toXML;
	# Dump in XML format (used by ACS for API calls)
	
	my $device = $acs->devices("name","MAIN_Router");
	# Faster call to request specific device information by name

	my $device = $acs->devices("id","250");
	# Faster call to request specific device information by ID (assigned by ACS, present in Net::Cisco::ACS::Device)

	my %devicegroups = $acs->devicegroups;
	# Retrieve all device groups from ACS
	# Returns hash with device name / Net::Cisco::ACS::DeviceGroup pairs

	print $acs->devicegroups->{"All Locations"}->toXML;
	# Dump in XML format (used by ACS for API calls)
	
	my $device = $acs->devicegroups("name","All Locations");
	# Faster call to request specific device group information by name

	my $devicegroup = $acs->devicegroups("id","250");
	# Faster call to request specific device group information by ID (assigned by ACS, present in Net::Cisco::ACS::DeviceGroup)

	my %hosts = $acs->hosts;
	# Retrieve all hosts from ACS
	# Returns hash with host name / Net::Cisco::ACS::Host pairs

	print $acs->hosts->{"1234"}->toXML;
	# Dump in XML format (used by ACS for API calls)
	
	my $host = $acs->hosts("name","1234");
	# Faster call to request specific host information by name

	my $host = $acs->hosts("id","250");
	# Faster call to request specific hosts information by ID (assigned by ACS, present in Net::Cisco::ACS::Host)
	
	$user->id(0); # Required for new user!
	my $id = $acs->create($user);
	# Create new user based on Net::Cisco::ACS::User instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $id = $acs->create(@users); # Still requires nullified ID!
	# Create new users based on Net::Cisco::ACS::User instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure    
    
	$identitygroup->id(0); # Required for new record!
	my $id = $acs->create($identitygroup);
	# Create new identity group based on Net::Cisco::ACS::IdentityGroup instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $id = $acs->create(@identitygroups); # Still requires nullified ID!
	# Create new identitygroups based on Net::Cisco::ACS::IdentityGroup instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure    
		
	$device->id(0); # Required for new device!
	my $id = $acs->create($device);
	# Create new device based on Net::Cisco::ACS::Device instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

   	my $id = $acs->create(@devices); # Still requires nullified ID!
	# Create new devices based on Net::Cisco::ACS::Device instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure    

	$devicegroup->id(0); # Required for new device group!
	my $id = $acs->create($devicegroup);
	# Create new device group based on Net::Cisco::ACS::DeviceGroup instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $id = $acs->create(@devicegroups); # Still requires nullified ID!
	# Create new devicegroups based on Net::Cisco::ACS::DeviceGroup instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure        
    
	$host->id(0); # Required for new host!
	my $id = $acs->create($host);
	# Create new host based on Net::Cisco::ACS::Host instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $id = $acs->create(@hosts); # Still requires nullified ID!
	# Create new hosts based on Net::Cisco::ACS::Host instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure    
	
	my $id = $acs->update($user);
	# Update existing user based on Net::Cisco::ACS::User instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $id = $acs->update(@users);
	# Update existing users based on Net::Cisco::ACS::User instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure    
    
	my $id = $acs->update($identitygroup);
	# Update existing identitygroup based on Net::Cisco::ACS::IdentityGroup instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $id = $acs->update(@identitygroups);
	# Update existing identitygroups based on Net::Cisco::ACS::IdentityGroups instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure    
	
	my $id = $acs->update($device);
	# Update existing device based on Net::Cisco::ACS::Device instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $id = $acs->update(@devices);
	# Update existing devices based on Net::Cisco::ACS::Device instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure    
        
	my $id = $acs->update($devicegroup);
	# Update existing device based on Net::Cisco::ACS::DeviceGroup instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure
   
	my $id = $acs->update(@devicegroups);
	# Update existing devicegroups based on Net::Cisco::ACS::DeviceGroup instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure    
        
	my $id = $acs->update($host);
	# Update existing device based on Net::Cisco::ACS::Host instance
	# Return value is ID generated by ACS
	print "Record ID is $id" if $id;
	print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $id = $acs->update(@hosts);
	# Update existing hosts based on Net::Cisco::ACS::Host instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure    
        
	$acs->delete($user);
	# Delete existing user based on Net::Cisco::ACS::User instance

	$acs->delete($identitygroup);
	# Delete existing identity group based on Net::Cisco::ACS::IdentityGroup instance
	
	$acs->delete($device);
	# Delete existing device based on Net::Cisco::ACS::Device instance

	$acs->delete($devicegroup);
	# Delete existing device based on Net::Cisco::ACS::DeviceGroup instance

	$acs->delete($host);
	# Delete existing host based on Net::Cisco::ACS::Host instance
	
	$acs->version
	# Return version information for the connected server *HASHREF*

	$acs->serviceLocation
	# Return ACS instance that serves as primary and the ACS instance that provide Monitoring and Troubleshooting Viewer. *HASHREF*
	
	$acs->errorMessage
	# Return all ACS message codes and message texts that are used on the REST Interface. *HASHREF*

DESCRIPTION

Net::Cisco::ACS is an implementation of the Cisco Secure Access Control System (ACS) REST API. Cisco ACS is a application / appliance that can be used for network access policy control. In short, it allows configuration of access policies for specific users onto specific devices and applications (either using RADIUS or TACACS+ authentication). Net::Cisco::ACS currently supports Device, Device Group, Host, User, Identity Group and generic information.

USAGE

All calls are handled through an instance of the Net::Cisco::ACS class.

use Net::Cisco::ACS;
my $acs = Net::Cisco::ACS->new(hostname => '10.0.0.1', username => 'acsadmin', password => 'testPassword');

new

Class constructor. Returns object of Net::Cisco::ACS on succes. Required fields are:

hostname
username
password

Optional fields are

ssl
ssl_options

hostname

IP or hostname of Cisco ACS 5.x server. This is a required value in the constructor but can be redefined afterwards.

username

Username of Administrator user. This is a required value in the constructor but can be redefined afterwards.

password

Password of user. This is a required value in the constructor but can be redefined afterwards.

ssl

SSL enabled (1 - default) or disabled (0).

ssl_options

Value is passed directly to LWP::UserAGent as ssl_opt. Default value (hash-ref) is

{ 'SSL_verify_mode' => SSL_VERIFY_NONE, 'verify_hostname' => '0' }

From the class instance, call the different methods for retrieving values.

users

Returns hash or single instance, depending on context.

my %users = $acs->users(); # Slow
my $user = $acs->users()->{"acsadmin"};
print $user->name;

The returned hash contains instances of Net::Cisco::ACS::User, using name (typically the username) as the hash key. Using a call to users with no arguments will retrieve all users and can take quite a few seconds (depending on the size of your database). When you know the username or ID, use the users call with arguments as listed below.

my $user = $acs->users("name","acsadmin"); # Faster
# or
my $user = $acs->users("id","123"); # Faster
print $user->name;

The ID is typically generated by Cisco ACS when the entry is created. It can be retrieved by calling the C<id> method on the object.

print $user->id;

identitygroups

Returns hash or single instance, depending on context.

my %identitygroups = $acs->identitygroups(); # Slow
my $identitygroup = $acs->identitygroups()->{"All Groups"};
print $identitgroup->name;

The returned hash contains instances of Net::Cisco::ACS::IdentityGroup, using name (typically the username) as the hash key. Using a call to identitygroup with no arguments will retrieve all identitygroups and can take quite a few seconds (depending on the size of your database). When you know the group name or ID, use the identitygroups call with arguments as listed below.

my $identitygroup = $acs->identitygroups("name","All Groups"); # Faster
# or
my $identitygroup = $acs->identitygroups("id","123"); # Faster
print $identitygroup->name;

The ID is typically generated by Cisco ACS when the entry is created. It can be retrieved by calling the C<id> method on the object.

print $identitygroup->id;

devices

Returns hash or single instance, depending on context.

my %devices = $acs->devices(); # Slow
my $device = $acs->devices()->{"Main_Router"};
print $device->name;

The returned hash contains instances of Net::Cisco::ACS::Device, using name (typically the sysname) as the hash key. Using a call to device with no arguments will retrieve all devices and can take quite a few seconds (depending on the size of your database). When you know the hostname or ID, use the devices call with arguments as listed below.

my $device = $acs->device("name","Main_Router"); # Faster
# or
my $device = $acs->device("id","123"); # Faster
print $device->name;

The ID is typically generated by Cisco ACS when the entry is created. It can be retrieved by calling the C<id> method on the object.

print $device->id;

devicegroups

Returns hash or single instance, depending on context.

my %devicegroups = $acs->devicegroups(); # Slow
my $devicegroup = $acs->devicegroups()->{"All Locations:Main Site"};
print $devicegroup->name;

The returned hash contains instances of Net::Cisco::ACS::DeviceGroup, using name (typically the device group name) as the hash key. Using a call to devicegroups with no arguments will retrieve all device groups and can take quite a few seconds (depending on the size of your database). When you know the device group or ID, use the devicegroups call with arguments as listed below.

my $devicegroup = $acs->devicegroups("name","All Locations::Main Site"); # Faster
# or
my $devicegroup = $acs->devicegroups("id","123"); # Faster
print $devicegroup->name;

The ID is typically generated by Cisco ACS when the entry is created. It can be retrieved by calling the id method on the object.

print $devicegroup->id;

hosts

Returns hash or single instance, depending on context.

my %hosts = $acs->hosts(); # Slow
my $host = $acs->hosts()->{"12345"};
print $host->name;

The returned hash contains instances of Net::Cisco::ACS::Host, using name as the hash key. Using a call to hosts with no arguments will retrieve all hosts and can take quite a few seconds (depending on the size of your database). When you know the name or ID, use the hosts call with arguments as listed below.

my $host = $acs->host("name","12345"); # Faster
# or
my $host = $acs->device("id","123"); # Faster
print $host->name;

The ID is typically generated by Cisco ACS when the entry is created. It can be retrieved by calling the C<id> method on the object.

print $host->id;

version

This method returns version specific information about the Cisco ACS instance you're connected to. Values are returned in a hash reference.

use Data::Dumper;
# ... 
print Dumper $acs->version;

servicelocation

This method returns information about the ACS instance that serves as primary and the ACS instance that provide Monitoring and Troubleshooting Viewer. Values are returned in a hash reference.

use Data::Dumper;
# ... 
print Dumper $acs->servicelocation;

errormessage

This method returns all ACS message codes and message texts that are used on the REST Interface. Values are returned in a hash reference. See also $Net::Cisco::ACS::ERROR.

use Data::Dumper;
# ... 
print Dumper $acs->errormessage;

create

This method created a new entry in Cisco ACS, depending on the argument passed. Record type is detected automatically. For all record types, the ID value must be set to 0.

my $user = $acs->users("name","acsadmin");
$user->id(0); # Required for new user!
$user->name("altadmin"); # Required field
$user->password("TopSecret"); # Password policies will be enforced!
$user->description("Alternate Admin"); 
my $id = $acs->create($user); 
# Create new user based on Net::Cisco::ACS::User instance
# Return value is ID generated by ACS
print "Record ID is $id" if $id;
print $Net::Cisco::ACS::ERROR unless $id;
# $Net::Cisco::ACS::ERROR contains details about failure

my $device = $acs->devices("name","Main_Router");
$device->name("AltRouter"); # Required field
$device->description("Standby Router"); 
$device->ips([{netMask => "32", ipAddress=>"10.0.0.2"}]); # Change IP address! Overlap check is enforced!
$device->id(0); # Required for new device!
my $id = $acs->create($device);
# Create new device based on Net::Cisco::ACS::Device instance
# Return value is ID generated by ACS
print "Record ID is $id" if $id;
print $Net::Cisco::ACS::ERROR unless $id;
# $Net::Cisco::ACS::ERROR contains details about failure

Multiple instances can be passed as an argument. Objects will be created in bulk (one transaction). The returned ID is not guaranteed to be the IDs of the created objects.

	my $user = $acs->users("name","acsadmin");
	$user->id(0); # Required for new user!
	$user->name("altadmin"); # Required field
	$user->password("TopSecret"); # Password policies will be enforced!
	$user->description("Alternate Admin"); 

	my $user2 = $acs->users("name","acsadmin");
	$user2->id(0); # Required for new user!
	$user2->name("altadmin"); # Required field
	$user2->password("TopSecret"); # Password policies will be enforced!
	$user2->description("Alternate Admin"); 

	my $id = $acs->create($user,$user2); 
	# Create new users based on Net::Cisco::ACS::User instances in argument.
	# Return value is ID generated by ACS but not guaranteed.
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $device = $acs->devices("name","Main_Router");
	$device->name("MainRouter"); # Required field
	$device->description("Main Router"); 
	$device->ips([{netMask => "32", ipAddress=>"10.0.0.1"}]); # Change IP address! Overlap check is enforced!
	$device->id(0); # Required for new device!

	my $device2 = $acs->devices("name","Alt_Router");
	$device2->name("AltRouter"); # Required field
	$device2->description("Standby Router"); 
	$device2->ips([{netMask => "32", ipAddress=>"10.0.0.2"}]); # Change IP address! Overlap check is enforced!
	$device2->id(0); # Required for new device!
	
    my $id = $acs->create($device,$device2);
	# Create new device based on Net::Cisco::ACS::Device instance
	# Return value is ID generated by ACS but not guaranteed.
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

update

This method updates an existing entry in Cisco ACS, depending on the argument passed. Record type is detected automatically.

my $user = $acs->users("name","acsadmin");
$user->password("TopSecret"); # Change password. Password policies will be enforced!
my $id = $acs->update($user);
# Update user based on Net::Cisco::ACS::User instance
# Return value is ID generated by ACS
print "Record ID is $id" if $id;
print $Net::Cisco::ACS::ERROR unless $id;
# $Net::Cisco::ACS::ERROR contains details about failure

my $device = $acs->devices("name","Main_Router");
$user->description("To be ceased"); # Change description
$device->ips([{netMask => "32", ipAddress=>"10.0.0.2"}]); # or Change IP address. Overlap check is enforced!
my $id = $acs->update($device);
# Create new device based on Net::Cisco::ACS::Device instance
# Return value is ID generated by ACS
print "Record ID is $id" if $id;
print $Net::Cisco::ACS::ERROR unless $id;
# $Net::Cisco::ACS::ERROR contains details about failure

Multiple instances can be passed as an argument. Objects will be updated in bulk (one transaction). The returned ID is not guaranteed to be the IDs of the created objects.

	my $user = $acs->users("name","acsadmin");
	$user->id(0); # Required for new user!
	$user->password("TopSecret"); # Password policies will be enforced!

	my $user2 = $acs->users("name","acsadmin2");
	$user2->password("TopSecret"); # Password policies will be enforced!

	my $id = $acs->update($user,$user2); 
	# Update users based on Net::Cisco::ACS::User instances in arguments
	# Return value is ID generated by ACS but not guaranteed.
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

	my $device = $acs->devices("name","Main_Router");
	$device->description("Main Router"); 
	$device->ips([{netMask => "32", ipAddress=>"10.0.0.1"}]); # Change IP address! Overlap check is enforced!

	my $device2 = $acs->devices("name","Alt_Router");
	$device2->description("Standby Router"); 
	$device2->ips([{netMask => "32", ipAddress=>"10.0.0.2"}]); # Change IP address! Overlap check is enforced!
	
    my $id = $acs->create($device,$device2);
	# Update devices based on Net::Cisco::ACS::Device instances in arguments
	# Return value is ID generated by ACS but not guaranteed.
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ACS::ERROR unless $id;
	# $Net::Cisco::ACS::ERROR contains details about failure

delete

This method deletes an existing entry in Cisco ACS, depending on the argument passed. Record type is detected automatically.

my $user = $acs->users("name","acsadmin");
$acs->delete($user);

my $device = $acs->users("name","Main_Router");
$acs->delete($device);

$ERROR

This variable will contain detailed error information, based on the REST API answer. This value is reset during every call to users, devices and devicegroups.

REQUIREMENTS

For this library to work, you need an instance with Cisco ACS (obviously) or a simulator like Net::Cisco::ACS::Mock.

To enable the Cisco ACS REST API, you will need to run the command below from the Cisco ACS console:

acs config-web-interface rest enable

You will also need an administrator-role account, typically NOT associated with a device-access account. Configure the account through the GUI.

System Administration > Administrators > Accounts

You will need more than generic privileges (SuperAdmin is ideal, suspected that UserAdmin and NetworkDeviceAdmin are sufficient).

You will also need

Moose
IO::Socket::SSL
LWP::UserAgent
XML::Simple
MIME::Base64
URI::Escape

BUGS

None so far

SUPPORT

None so far :)

AUTHOR

Hendrik Van Belleghem
CPAN ID: BEATNIK
hendrik.vanbelleghem@gmail.com

COPYRIGHT

This program is free software licensed under the...

The General Public License (GPL)
Version 2, June 1991

The full text of the license can be found in the LICENSE file included with this module.

COMPATIBILITY

Certain API calls are not support from Cisco ACS 5.0 onwards. The current supported versions of Cisco ACS (by Cisco) are 5.6, 5.7 and 5.8 (Active).

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

USAGE

REQUIREMENTS

BUGS

SUPPORT

AUTHOR

COPYRIGHT

COMPATIBILITY

SEE ALSO

Module Install Instructions