Note: NetMRI needs the ENABLE password to access configuration files on some devices and to run the Configuration Command Scripts and Perl/Python scripts. To ensure easier identification of NetMRI actions, we recommend creation of a username and password on your network equipment specifically for NetMRI.

Job scripting is a key capability for NetMRI and for the Automation Change Manager system. Job scripting allows use of two linguistic approaches to script job-based automation: a proprietary language, called CCS (Change Control Scripting), a standard-language Perl API, and a standard-language Python API. This chapter focuses on Perl/Python scripting.

Note: CCS is a ‘high-level’ scripting language, which walls off access to the internals of the operating system and prevents operations such as overwriting blocks of memory and other potentially harmful actions. CCS also does not use or access the NetMRI Sandbox, which is a separate VM-based resource for Perl/Python scripting. Perl/Python scripting offers low-level access to all NetMRI system internals and the ability to use any operating system function or API call to affect any aspect of system operation. To prevent serious mistakes when using Perl/Python scripts, a dedicated and isolated virtual machine environment is provided by NetMRI in which Perl/Python scripts are automatically executed on behalf of the user.

A separate document, the NetMRI CCS Scripting Guide (available in the Additional Documentation section of the NetMRI online help), describes CCS scripting syntax in detail with design patterns and example scripts.

Perl/Python Scripting

Note: When you save a Perl/Python script, NetMRI will test-compile the script. If the compile fails, the appliance will disallow saving of the script and display the compilation errors to the user.

As with CCS, you use Perl/Python for change automation and custom Issue analysis. Perl/Python scripting possesses far greater capabilities, providing access to all aspects of the Perl or Python programming language, including the Perl/Python API, at runtime. NetMRI’s Job Wizard also supports the use of Perl/Python scripts. You use your preferred text editor or IDE to write and debug the Perl or Python script before copying the text into the appropriate field in the Job Wizard. Infoblox strongly recommends testing all Perl/Python scripts before running them in the appliance.
Perl/Python scripting can be leveraged for use in custom issues, change scripts and analysis scripts.

The Job Management tab provides a collection of scripting-related functions:

• The Scripts tab provides creation, copying, editing, scheduling, and running of automation scripts;
• The Library tab provides a convenient location for storing and Perl/Python subroutines and modules;
• The Config Templates tab lists any configuration template files. Config templates are text files that contain CLI commands for a specific vendor, device type, equipment model or network operating system version. Config templates can serve as the basis for a job (described in this chapter);
• The Lists tab provides external lists of information to which jobs can refer when running scripts (Described in Defining Lists for ACM, Perl, Python, and CCS Script Reference;
• The Scheduled Jobs tab is where you create and schedule jobs, which run scripts against devices at a specified frequency. (Described in Creating and Scheduling Jobs);
• The Triggered Jobs tab enables you to specify events that will trigger associated jobs. (Described in Triggering Jobs Through Events);
• The Job History tab lists jobs that have been scheduled (or run immediately), and shows their status. (Described in Viewing the Job History and the Job Viewer);
• The Custom Issues tab enables you to create and edit custom issues referenced by scripts.

Creating New Scripts (CCS, Perl, and Python)

Create and manage scripts at Configuration Management –> Job Management tab –> Scripts tab.

Note: You must have the Scripts: Author and Scripts: Level 3 privileges in a system administrator account to create and save scripts.

1. To create a script: At the top right of the page, click New. The Add New Script dialog appears.
2. In the Add New Script dialog: type a Name for the script.
   • Specify a Run Level. Run Level controls who can run the script.
   • Specify an optional Category in which the script should be placed. (Use categories to organize scripts.
   • Type a Description of the script.
   • Select the Language of the script: CCS, Perl, or Python.
   • Type or paste in the script in the lowest field in the dialog.
3. Click Save & Close or Save.

Note: Users are assigned roles/privileges to edit and run scripts based on risk. A user with Scripts: Level 1 privilege, for example, can run scripts having a Run Level of Low, but not those having a Run Level of Medium or High. A user with Scripts: Level 2 can run scripts having a Run Level of Low or Medium, but not High, and so forth. An organization might assign Scripts: Level 1 privileges to tier one NOC operators. Further, the organization might designate some scripts that perform simple tasks (such as running a "show" command to collect more data) as Run Level Low. As a result, their tier one NOC team members can have limited access to some devices, but are prevented from making radical changes.

1. To copy a script: Copy.
2. In the Copy Script dialog, type a name for the script, then click OK .
   To edit a script: Edit.

1. To schedule a script for execution: Schedule. The Job Wizard opens.
2. In the Fill out Job Details screen, type a Job Name.
3. To allow a job to run: enable the Approved option. (A job cannot be scheduled unless it is approved.)
4. Type a Description of the job.
5. In the Scripts list, select a script. If required by the script, enter data and/or select options.
6. Click Next.
7. In the Select Device Groups o rDevices screen, click the Add icon to select specific device groups and/or devices to which this job applies.
8. Click Next.
9. In the Schedule when Job should run screen, specify the schedule for the job.
10. Click Next.
11. In the Review and save screen, review the job specifications. If changes are needed, click the < Previous button to return to an earlier screen.
12. Click Save.

Track scheduled jobs in the Job History tab.

Note: You can also schedule a script in the Scheduled Jobs tab.

1. To run a script: Run Now.
2. The Batch Status window displays the results of running the script.

To view batch details: Click a hyperlink in the Name column. The Job Viewer opens.

To view the entire script: Click a hyperlink in the Script column.
To delete a script: Delete, then confirm the deletion.

Note: Any single NetMRI instance can run a maximum of ten (10) active CLI sessions to network devices. This imposes a practical limit to the number of concurrent sessions that a script can run through CLI sessions to other devices in the network. This limit applies per NetMRI instance or per collector; for example, if you are running an Operations Center with three collectors, the Operations Center can run a script against up to 30 network devices at once.

Perl Scripting in NetMRI

Note: The Infoblox 1102-A and NT-4000 platforms support Perl scripting, as do all legacy appliances with 8 GB of RAM. Perl scripting is not available on other legacy platforms. The virtual machine version of NetMRI also supports Perl scripting and the Sandbox virtual environment. On platforms where Perl scripting is not available, all related features are hidden and/or disabled via the GUI and administrative shell.

Note: To achieve optimum performance on legacy NetMRI platforms, a BIOS change is necessary. If you have one of these platforms and the BIOS change has not been made, a message to that effect appears when attempting to save a Perl script. Contact Infoblox technical support to obtain the document describing the BIOS change process for these platforms.

Security and risk management are common concerns with Perl scripting, and precautions should be taken to ensure that a complex Perl script doesn't cause issues in the appliance. Risk levels, tied to CLI credentials, can be applied to scripts in NetMRI. This enables more granular permissions to be applied to specific scripts. A NetMRI user will need to provide a different set of end-user permissions to run specific jobs.
Other features in Perl support include the following:

• Access to the Perl exit function from within a script. If the Perl script exits with a zero exit code, the script ceases operation and NetMRI sets the job status to OK. If the Perl script exits with a non-zero exit code it causes the script to cease operation and NetMRI sets the job status to Error;
• Ability to mark problem commands and perform try/catch exception handling;
• A logging function, available in the infoblox_job.pl file;
• A LIbraries page (see Using Perl or Python Libraries for more information) containing blocks of Perl code to be referenced by other Perl scripts. The Libraries page supports creation, editing, deletion, and import and export of snippets of Perl code;
• Refer to lists of data to fill variables and find matches during job batch processing, extract information and parse the returned data (see the section Defining Lists for ACM, Perl, Python, and CCS Script Reference for more information);
• Use of standard NetMRI variables and data model objects in scripting logic. NetMRI automatically associates variables with target devices during runtime. Users can define input and internal variables that can be mapped to the NetMRI data model. The data model also provides access to device and interface attributes;
• Users can open multiple, simultaneous, device connections from within scripts, enabling change coordination between multiple devices in sequence or in parallel, based on common elements such as VLAN membership or neighbor topology. The feature is helpful in advanced use cases: for example, a script opens a connection to a network device, encounters a configuration element, and opens new connections to other, similar devices for comparison and determines the action to take on the current device;
• Regular expression processing, without restrictions on data structure types where regular expressions can be used, including script input variables, device output, data from external files, lists and NetMRI data model information.

Anatomy of a Perl Script

Note: Well-known variables for Perl and CCS scripting are listed in the topic Scripting Well-Known Variables (Perl, Python, and CCS).

Perl scripts use a script header similar to a CCS script, contained within a well-known comment block. The script header block influences a number of runtime behaviors, including:

Script-Timeout

Specifies the per-command timeout for the entire script in seconds.

• Type: Integer
• Required: No
• Default if not specified: 60 

Script-Login

Specifies whether the job engine should automatically establish a connection with the target device.

• Type: Boolean
• Required: No
• Default if not specified: true 

Script-Variables

Specifies inputs needed by the script.

• Type: Tuple (ordered list of elements)
• Required: No
• Default if not specified: None

Script-Filter

Specifies the device types processed by the script.

• Type: String
• Required: Yes

A Perl Script header block must be defined inside of Perl comments within a "well known" comment section (between BEGIN-SCRIPT-BLOCK and a # END-SCRIPT-BLOCK). The following example demonstrates the difference between a CCS and Perl Script header block that specifies a Script-Filter that applies to all Cisco IOS devices.

As a comparison, a CCS implementation is straightforward:

Script-Filter:$Vendor == "Cisco" and $sysDesc like /IOS/

You can filter by the network view:

Script-Filter:$network == "blue"

A comparable Perl implementation is as follows:

BEGIN-SCRIPT-BLOCK

Script-Filter:$Vendor == "Cisco" and $sysDesc like /IOS/

END-SCRIPT-BLOCK

Perl scripts run inside the sandbox, using the Perl API to communicate with the Device Interaction Server (DIS) on NetMRI. The DIS proxies CLI requests/responses to/from network devices on behalf of the Perl scripts. Before commands can be sent to a network device, a Perl script must first establish a DIS session (see v2 API object DisSession). After a session has been established, a CLI connection with the target device must be established for the given session (see v2 API object CliConnection). The majority of the time, a Perl script will follow this same initialization sequence. First, establish the API session, establish the DIS session, then establish a CLI connection with the target device. For this reason, Infoblox_Job.pm, a pre-installed Perl library, is provided in the appliance (see Configuration Management –> Job Management –> Library –> Infoblox_Job).

About NetMRI_Easy.pm

NetMRI_Easy.pm provides an interface to the NetMRI API from perl scripts run on the NetMRI appliance. NetMRI_Easy.pm offers all of the features of infoblox_jobs.pm, with some safeguards and object -oriented interfaces that are unavailable when infoblox_jobs.pm is used.
NetMRI_Easy.pm is designed to be imported as a library into NetMRI and used by Perl scripts executed in the Sandbox environment.
NetMRI_Easy.pm is also a compatibility layer, allowing writing of Perl scripts that function unaltered with the newer 2.5 NetMRI Perl API, using scripts originally developed for the NetMRI Perl Core API 1.1. The following subsections describe the Perl functions encompassed by NetMRI_Easy.pm:

Constructor

The new NetMRI_Easy constructor options include the following:

my $easy = new NetMRI_Easy(api_version => 2, nios_api => 1 );

The Constructor for NetMRI_Easy takes a hash reference for options.

api_version => $version

• Specifies which API version to use. See NetMRI::API for details.

nios_api => 1

Load the Infoblox API before connecting to the API. Using this option is the same as

use NetMRI::Util;

use_infoblox_api($main::nios_ipaddress);

• NetMRI_Easy ensures that the Infoblox API is loaded before LWP::UserAgent. This is necessary because the Infoblox API requires a different version of LWP::UserAgent, and will fail if modules are loaded in the wrong order.

nios_ipaddress => $ip_address

• IP address of the NIOS device to download the Infoblox API and connect to when using the nios_session method. This option is necessary when connecting to a NIOS that is not registered with NetMRI.

nios_username => $username

• Username to use when connecting to the NIOS device. This option is necessary when connecting to a NIOS appliance that is not registered with the NetMRI, or to connect with different credentials.

nios_password => $secret

• Password to use when connecting to the NIOS device. This option is necessary when connecting to a NIOS appliance that has not been registered with NetMRI, or to connect with different credentials.

NetMRI_Easy Attributes

$easy->job_id

Job ID of the Perl script running on the NetMRI appliance.

$easy->device_id

ID of the target device against which the script is running.

$easy->batch_id

Batch id of the Perl script running on the NetMRI appliance.

$easy->username

The NetMRI username.

$easy->dis_session_id

Returns the DIS session id used to interact with the target device. The DIS session is opened automatically when needed, and closes automatically when the NetMRI_Easy object goes out of scope (typically when the Perl script terminates on the NetMRI appliance).

$easy->device

Returns the NetMRI::API::Remote::Device (new Perl API) or NetMRI::API::Device (old Perl API) for the target device.
$easy->device is a shortcut for the following:

$easy->broker->device->show(DeviceID => $self->device_id )->device;

The device is cached and fetched only once.

NetMRI_Easy Methods

$easy->set_variable( $variable_name, $value )

Set a server-side variable. This is useful when retrieving a template via get_template and the template contains variables that are not defined by the Script-Variables for the current job. This is because template merging (i.e. variable substitution) is performed on the server-side.

Example

$easy->set_variable(Username => $some_username);

This method requires a CLI connection to the device. NetMRI must have credentials for the device against which the NetMRI_Easy script is running.

$easy->send_command( $command )

Send a command to the target device.

Example

my $output = $easy->send_command("show version");

This method requires a CLI connection to the device. NetMRI must have credentials for the device against which the NetMRI_Easy script is running.

$easy->send_command( $command, $new_prompt)

Send a command to the target device. You can use the new_prompt parameter to override the device prompt when the command executed in the $command parameter to change the prompt on the device.

Example

my $output = $easy->send_command("conf t", "mydevice(config-if)#");

This method requires a CLI connection to the device. NetMRI must have credentials for the device against which the NetMRI_Easy script is running.

$easy->get_template( $template_name )

Retrieve a template. For the given template, retrieve the content and perform any necessary variable substitutions.

Example

my $contents = $easy->get_template("Cisco Router");

This method requires a CLI connection to the device. NetMRI must have credentials for the device against which the NetMRI_Easy script is running.

$easy->get_list_value( $list_name, $key_column, $value_column, $default )

Look up a value in a list. For the given list name, finds the first row containing the given key value in the given key column and returns the value contained in the given value column. If the look up fails, the given default is returned.
$default is returned if no value is found. If $default is not specified, then empty string " " is used as the default.
This method requires a CLI connection to the device. NetMRI must have credentials for the device against which the NetMRI_Easy script is running.

$easy->generate_issue( $issue_type_id, $severity, %parameters )

Generate an issue. For the given issue type id, generate an issue of the given severity using the name/value pairs defined in the given parameters as the issue details.
$issue_type_id

String issue type id

$severity

severity is one of "error", "warning" or "info"

%parameters

hash reference containing the issue details.

Example

my $issue_id = $easy->generate_issue("Invalid Accounts", "warning", "IP Address" => '1.2.3.4',
"Username"=> 'admin',
);

$easy->log_message($severity, $message)

Log a message of the given severity (one of 'debug', 'error', 'warning' or 'info'). The message is written to the custom.log file.
This method requires a CLI connection to the device and that NetMRI have credentials for the device against which the NetMRI_Easy script is running.

$easy->broker->broker_name

Get the broker object of the corresponding API controller. Similar to device or cli_connection. Broker objects can be used to query and modify objects on the NetMRI appliance.

$easy->device_session( $device_id )

Create an instance of NetMRI_Easy associated with this job, but with a different device. Enables sending of commands to an additional device.

Example

my $easy2 = $easy->device_session( 25 );
my $command_out = $easy2->send_command('show version');
$easy2->log_message('info', 'send command show version');

This method may be called to create as many device sessions as needed.

$easy->write_payload( @list )

Encode a message in JSON format in the status log; the message can be retrieved using the read_payload method on NetMRI::API::Remote::Job once the job has completed.

$easy->nios_session

Open a session with NIOS. You must pass nios_api => 1 into the constructor to NetMRI_Easy to use this method, the Infoblox Perl API must be loaded before the Perl API.

NetMRI_Easy Globals

This module internally relies on global variables provided by NetMRI.

$main::http_username
$main::http_password
$main::api_url
$main::job_id
$main::device_id
$main::batch_id
$main::nios_ipaddress
$main::nios_username
$main::nios_password

Dependency on these variables is limited to the constructor for NetMRI_Easy. NetMRI_Easy provides attribute accessors for most of these values.

Diagnostics

Missing Credentials for Device

Several methods open a CLI connection with the device against which NetMRI_Easy runs, thus requiring CLI credentials for that device. If the NetMRI instance running the script is missing those credentials, you may see an error of the form

**Error / NetMRI dis-sessions/dis-error % No auth credentials found for device 18[ http://u.x.y.z/api/3.3/cli_connections/open.json

The URL stated is the URL for the NetMRI Core API method that failed. The cited IP address is the IP address of the NetMRI instance.

Note: Job_id in the Perl sandbox is the JobDetailID as used by the NetMRI API. Batch_id is the Job ID used by the NetMRI API.

Infoblox_job.pm and Associated Functions

Including Infoblox_Job.pm in a Perl script will manage the initialization sequence for the job manager. Infoblox_Job.pm abstracts many of the details of the NetMRI v2 PAPI for common Perl script tasks and exposes them through standard Perl functions. These functions are as follows:

#  Name                         : open_session

# Description                   : Open a session with the DIS (Device Interaction Server) for the current job. The DIS proxies CLI requests between clients (e.g. Perl scripts) and network devices. A single DIS session can handle connections to multiple network devices.

# Arguments                     : None

# Returns                       : None

#Example:                       : open_session();

#Name                           : close_session

#Description                    : Close the current DIS session.

#Arguments                      : None

#Returns                        : None

#Example:                       : close_session();

#Name                           : log_message

#Description                    : Log a message of the given severity. The message is written to the custom.log file.

#Arguments                      : severity (string, required - valids =

#                                       debug, error, warning, info)

#                                The severity.

#                                message (string, required)

#                                The message.

#Returns                        : None

#Example:                       : log_message(

#                                          "debug",

#                                           "Hello World!"

#                                );

# Name                           : open_connection

# Description                    : Open a connection with the target device via the DIS for the current DIS session.

# Arguments                      : None

# Returns                        : None

# Example:                       : open_connection();

# Name                           : close_connection

# Description                    : Close the connection with the target device for the current DIS session.

# Arguments                      : None

# Returns                        : None

# Example:                       : close_connection();

# Name                           : set_variable

# Description                    : Set a server-side variable. This is useful when retrieving a template via get_template and the template contains variables that are not defined by the Script-Variables for the current job. This is because template merging (i.e. variable substitution) is performed on the server-side.

# Arguments                      : command (string, required)

#                                 The set variable command.

# Returns                        : None

# Example:                       : set_variable("\$Username = \"$some_username\"");

# Name                           : send_command

# Description                    : Send a command to the target device.

# Arguments                      : command (string, required)

#                                 The command to be sent to the target device.

#

#                                 debug (boolean, optional - default = "off")

#                                 Debug mode. If enabled, the command will not be sent to the

#                                 target device, but what would have been sent will appear in the logs.

# Returns                       : (string)

#                                1. The output from the command (debug == "off").

#                                2. "" (debug == "on").

# Example:                      : my $output = send_command("show version");

# Name                          : get_template

# Description                   : Retrieve a template. For the given template, retrieve the content and perform any necessary variable substutions.

# Arguments                     : template (string, required)

#                                The name of the template to be retrieved.

#

#                                stage (boolean, optional - default = "off")

#                                Stage mode. If enabled, the template is staged on NetMRI in a location that is anonymously available via TFTP and HTTP. The staged file is removed when the script has exited.

# Returns                       : (string)

#                                1. The template contents (stage == "off").

#                                2. The path to the template contents (stage == "on").

# Example:                      : my $contents = get_template("Cisco Router");

# Name                          : get_list_value

# Description                   : Lookup a value in a list. For the given list name, finds the first row containing the given key value in the given key column and returns the value contained in the given value column. If the lookup fails, the given default is returned.

# Arguments                     : list_name (string, required)

#                                The list name.

#

#                                key_column (string, required)

#                                The key column.

#

#                                key_value (string, required)

#                                The key value.

#

#                                value_column (string, required)

#                                The value column.

#

#                                default (string, optional - default = "")

#                                The default.

#

# Returns                       : (string)

#                                The result of the lookup.

# Example:                      : my $enable_password = get_list_value(

#                                       "Enable Passwords",

#                                       "IP Address",

#                                       $ipaddress,

#                                       "Password",

#                                       "NOT FOUND"

#                                 );

# Name                            : generate_issue

# Description                     : Generate an issue. For the given issue type id, generate an issue of the given severity using the name/value pairs defined in the given params as the issue details.

# Arguments                       : issue_type_id (string, required)

#                                  The issue type id.

#

#                                  severity (string, required - valids = error, warning, info)

#                                  The severity.

#

#                                  params (hash reference, required)

#                                  The issue details.

# Returns                         : (number)

#                                 The assigned issue id.

# Example:                        : my $issue_id = generate_issue(

#                                       "Invalid Accounts",

#                                        "warning", {

#                                        "IP Address"=> $ipaddress,

#                                        "Username"=> $some_username

#                                  });

When including Infoblox_Job.pm in your Perl scripts, you do not have to explicitly call log_message(), open_session(), open_connection(), close_session() or close_connection(). Infoblox_Job.pm contains code that executes upon being included. Therefore, the second line of your Perl script can begin to access the other functions defined in Infoblox_Jon.pm. As an example:

require "Infoblox_Job.pm";
my $output = send_command("show version");

More About Infoblox_Job.pm

Although the majority of Perl scripts will include Infoblox_Job.pm, a Perl script may do other tasks beyond communicating with the target device. For example, a Perl script can transmit acquired target device information (which is available via well-known variables in the script) with a trouble ticketing system that resides elsewhere on the network. In this case, though including Infoblox_Job.pm is permitted, doing s o would be unnecessary (why establish a CLI connection with the target device when no CLI actions are taken?).
The standard Infoblox_Job.pm initialization sequence and functions establish a DIS session and a CLI connection with the target device. A DIS session can support multiple CLI connections. You may develop more advanced use cases in which Perl scripts establish simultaneous connections to multiple network devices in addition to the target device. In this scenario, the Perl script must obtain the DeviceIDs for the non-target network devices and directly use the v2 API functionality to communicate with them (i.e. basically do the equivalent of open_connection(), send_command(), and so on).

Python Scripting in NetMRI

Note: The Infoblox 1102-A and NT-4000 platforms support Python scripting, as do all legacy appliances with 8 GB of RAM. Python scripting is not available on other legacy platforms. The virtual machine version of NetMRI also supports Python scripting and the Sandbox virtual environment. On platforms where Python scripting is not available, all related features are hidden and/or disabled via the GUI and administrative shell. To achieve optimum performance on legacy NetMRI platforms, a BIOS change is necessary. If you have one of these platforms and the BIOS change has not been made, a message to that effect appears when attempting to save a Python script. Contact Infoblox technical support to obtain the document describing the BIOS change process for these platforms.

Security and risk management are common concerns with Python scripting, and precautions should be taken to ensure that a complex Python script doesn’t cause issues in the appliance. Risk levels, tied to CLI credentials, can be applied to scripts in NetMRI. This enables more granular permissions to be applied to specific scripts. A NetMRI user will need to provide a different set of end-user permissions to run specific jobs.

Other features in Python support include the following:

• Access to the Python exit function from within a script. If the Python script exits with a zero exit code, the script ceases operation and NetMRI sets the job status to OK. If the Python script exits with a non-zero exit code it causes the script to cease operation and NetMRI sets the job status to Error;
• Ability to mark problem commands and perform try/catch exception handling;
• A logging function, available in the infoblox_job.pl file;
• A Libraries page (see Using Perl or Python Libraries for more information) containing blocks of Python code to be referenced by other Python scripts. The Libraries page supports creation, editing, deletion, and import and export of snippets of Python code;
• Refer to lists of data to fill variables and find matches during job batch processing, extract information and parse the returned data (see the section Defining Lists for ACM, Perl, Python, and CCS Script Reference for more information);
• Use of standard NetMRI variables and data model objects in scripting logic. NetMRI automatically associates variables with target devices during runtime. Users can define input and internal variables that can be mapped to the NetMRI data model. The data model also provides access to device and interface attributes;
• Users can open multiple, simultaneous, device connections from within scripts, enabling change coordination between multiple devices in sequence or in parallel, based on common elements such as VLAN membership or neighbor topology. The feature is helpful in advanced use cases: for example, a script opens a connection to a network device, encounters a configuration element, and opens new connections to other, similar devices for comparison and determines the action to take on the current device;
• Regular expression processing, without restrictions on data structure types where regular expressions can be used, including script input variables, device output, data from external files, lists and NetMRI data model information.

Anatomy of a Python Script

Note: Well-known variables for Python scripting are listed in the topic Scripting Well-Known Variables (Perl, Python, and CCS).

Python scripts use a script header similar to a CCS script, contained within a well-known comment block.

The script header block influences a number of runtime behaviors, including:

Script-Timeout

Specifies the per-command timeout for the entire script in seconds.

• Type: Integer
• Required: No
• Default if not specified: 60

Script-Login

Specifies whether the job engine should automatically establish a connection with the target device.

• Type: Boolean
• Required: No
• Default if not specified: true

Script-Variables

• Specifies inputs needed by the script.
• Type: Tuple (ordered list of elements)
• Required: No
• Default if not specified: None

Script-Filter

Specifies the device types processed by the script.

• Type: String
• Required: Yes

A Python Script header block must be defined inside of comments within a "well known" comment section (between # BEGIN-SCRIPT-BLOCK and a # END-SCRIPT-BLOCK). The following example demonstrates the difference between a CCS and Python Script header block that specifies a Script-Filter that applies to all Cisco IOS devices.

As a comparison, a CCS implementation is straightforward:

Script-Filter: $Vendor == "Cisco" and $sysDesc like /IOS/

You can filter by the network view:

Script-Filter: $network == "blue"

A comparable Python implementation is as follows:

# BEGIN-SCRIPT-BLOCK

# Script-Filter: $Vendor == "Cisco" and $sysDesc like /IOS/

# END-SCRIPT-BLOCK

Python scripts run inside the sandbox, using the Pyrthon API to communicate with the Device Interaction Server (DIS) on NetMRI. The DIS proxies CLI requests/responses to/from network devices on behalf of the Python scripts. Before commands can be sent to a network device, a Python script must first establish a DIS session (see v2 API object DisSession). After a session has been established, a CLI connection with the target device must be established for the given session (see v2 API object CliConnection). The majority of the time, a Python script will follow this same initialization sequence. First, establish the API session, establish the DIS session, then establish a CLI connection with the target device. For this reason, netmri_easy.py, a pre-installed Python library, is provided in the appliance (see Configuration Management –> Job Management –> Library –> netmri_easy).

About netmri_easy.py

The netmri_easy.py provides an interface to the NetMRI API from python scripts run on the NetMRI appliance.

netmri_easy.py is designed to be imported as a library into NetMRI and used by Python scripts executed in the Sandbox environment.

The following subsections describe the Python functions encompassed by netmri_easy.py:.

Constructor

The NetMRIEasy  constructor options include the following:

easy = NetMRIEasy( **params );

The Constructor for NetMRI_Easy takes a kwargs for options:

host - api host. Provided by NetMRI

username  - host username. Provided by NetMRI

password - host password. Provided by NetMRI

job_id - Job id. Provided by NetMRI

bacth_id - bacth id. Provided by NetMRI

device_id - device id. Provided by NetMRI

Methods

easy.set_variable( variable_name, variable_value )

Set a server-side variable. This is useful when retrieving a template via get_template and the template contains variables that are not defined by the Script-Variables for the current job. This is because template merging (i.e. variable substitution) is performed on the server-side.

Example

easy.set_variable('username', 'test_username')

This method requires a CLI connection to the device, NetMRI must have credentials for the device the NetMRIEasy script is run against.

easy.send_command( command )

Send a command to the target device.

Example

output = easy.send_command("show version")

This method requires a CLI connection to the device and that the NetMRI have credentials for the device the NetMRIEasy script is run against.

easy->get_template( $template_name )

Retrieve a template. For the given template, retrieve the content and perform any necessary variable substitutions.

Example

contents = easy.get_template("Cisco Router")

This method requires a CLI connection to the device and that the NetMRI have credentials for the device the NetMRIEasy script is run against.

easy.get_list_value(list_name, key_column, key_value, value_column, default)

Look up a value in a list. For the given list name, finds the first row containing the given key value in the given key column and returns the value contained in the given value column. If the look up fails, the given default is returned.

The default is returned if no value is found. If default is not specified, then empty string " " is used as the default. This method requires a CLI connection to the device, NetMRI must have credentials for the device the NetMRIEasy script is run against.

easy.generate_issue(severity, issue_type_id, **kwargs)

Generate an issue. For the given issue type id, generate an issue of the given severity using the name/value pairs defined in the given parameters as the issue details.

severity

severity is one of "error", "warning" or "info"

issue_type_id

String issue type id

kwargs

arguments containing the issue details.

Example

issue_id = easy.generate_issue("info", "IOSBanLoginUpdateSuccess", **{

     "Name":'Sample Name',

     "Host":'1.2.3.4'

})

easy.log_message(severity, message)

Log a message of the given severity (one of 'debug', 'error', 'warning' or 'info'). The message is written to the custom.log file.

This method requires a CLI connection to the device and that NetMRI have credentials for the device the NetMRIEasy script is run against.

easy.broker(broker_name)

Get the broker object of the corresponding API controller. Similar to device or cli_connection. Broker objects can be used to query and modify objects on the NetMRI appliance.

Using the NetMRI Sandbox

Note: You use the admin shell interact with the sandbox VM in NetMRI. The sandbox is rigorously isolated from the rest of the system, but allows root access to its internals, utilities and services. A shared disk partition is also created for use between the sandbox VM and the broader system.

As previously noted in this chapter, NetMRI provides a dedicated virtual machine environment, called the Sandbox, where Perl scripts are automatically run on behalf of the user. Perl also provides access to operating system internals, interacting with appliance services, performing data I/O operations, and reading from and writing to blocks of appliance memory.
The sandbox runs an instance of the same operating system kernel as the NetMRI appliance, which is a standard Unix variant, with the normal operating system utilities and file system. You can install Perl modules from CPAN into the sandbox environment and use them for scripting. You can install any Perl distributions, executables and modules into the sandbox environment. The NetMRI sandbox environment provides a Perl interpreter and supporting modules to support script execution.
The NetMRI Sandbox is available in two forms. Physical appliances with 8 GB of RAM or more automatically run the sandbox as a virtual machine inside of NetMRI. In this configuration, the sandbox is referred to as a local sandbox. All other platforms, including virtual platforms, cannot run a local sandbox. To take advantage of Perl scripting functionality, these platforms support a separate sandbox VM configuration, which must be set up and registered with NetMRI. In this configuration, this is referred to as a remote sandbox.
NetMRI appliances with 8GB or more of RAM can also use a remote sandbox to increase available resources to the local sandbox (e.g. CPU, memory, disk, etc) to solve more complex use cases. In those cases, the sandbox resources are governed by the hypervisor.
You download the Sandbox VM image from Infoblox Support.
Platforms supporting a local sandbox automatically perform the necessary setup and configuration steps; platforms that need a remote sandbox require a manual setup and configuration process. The topic Setting up a RemoteSandbox describes remote sandbox setup and configuration.

Note: A remote sandbox VM is not automatically upgraded when NetMRI is upgraded. If you deploy a remote sandbox and later upgrade NetMRI, the remote sandbox continues to report and run its originally deployed version. Though it is typically unnecessary to upgrade the remote sandbox when you upgrade your appliance (unless you are upgrading between major versions, for example from 6.4 to 6.5), you do so by downloading a corresponding new Sandbox VM downloadable file from Infoblox and then redeploying the remote sandbox. Backup any customizations made to the remote sandbox (installed Perl scripts, libraries, configuration, etc...) before redeployment.

To access the Sandbox for a NetMRI appliance or VM instance, do the following:

1. Access the administrative shell using an admin account, following the instructions in the Administrative Shell topic.
2. Enter the sandboxlogin command at the shell prompt.

Type exit and press Enter at any time to close the sandbox and return to the Administrative prompt.

Sandbox Commands

The sandbox command has seven arguments. All commands are not always available in the NetMRI administrative shell. Commands that appear in the shell depend on current configuration. The following table describes each command and its availability for each platform:

sandbox [configure|login|register|deregister|restart|reset|show]

Given the power and flexibility of the Perl language, Infoblox recommends treating this functionality with the caution and expertise it deserves. Knowledgeable Perl users may install and use different Perl software modules, database management software and other utilities and write scripts that consume unacceptable amounts of appliance CPU cycles and available memory. If any Perl script runs out of control, the only file system affected is that within the sandbox instance; the NetMRI appliance remains unaffected. You may need to run a sandbox restart or even a sandbox reset command to halt an errant Perl script on a local sandbox.
The NetMRI appliance strictly limits system disk and memory resource allocations for its local Sandbox instance, and those resources are not extensible from within the Sandbox. If the Sandbox is set up as a remote VM instance, the hypervisor determines memory and other resource allocations.

Note: Type exit and press <enter> to close the Sandbox and return to the administrative prompt.

Setting up a Remote Sandbox

Note: The instructions in this section are for the VMware VSphere® platform.

To configure the Remote Sandbox, do the following:

1. Open the administrative shell.
2. Download the Sandbox VM file from Infoblox using any scp program (such as WinSCP).
   If you chose the OVF file type, the downloaded file contains an OVF file, a VMDK file, an MF file, a README file and a LICENSE file. The OVF file is what you will need to import into your VMware hypervisor. The MF file contains checksums of the OVF and VMDK files to verify that the exported files are correct before importing. The README file contains detailed instructions for deployment of the remote sandbox.
   The standard VMX and VMDK files along with a README file and a LICENSE file, may also be deployed into VMware Workstation. You import the VMX file into the VMware hypervisor. The README file contains detailed instructions for deployment of the remote sandbox.
3. Load the files into the hypervisor.
   For example, In VSphere, choose File –> Deploy OVF Template and select the file from the correct folder.
   After the file loads, give the virtual machine a new name, choose where the VM is deployed, and choose its datastore.

Note: The remote sandbox (VM) uses DHCP upon initial startup to acquire its IP configuration. You may change this value to static IP subnet and mask values through the Setup utility (see Step 7 below). Change the remote sandbox network configuration using the VMware console; avoid changing the sandbox configuration directly through an SSH connection. This prevents dropped SSH connections when the default DHCP configuration is changed to a potentially different static address in the Setup program.

4. After the Sandbox VM is installed, boot it up through the ESX hypervisor. The Sandbox VM will display its command prompt.

5. After initial startup, log in to the remote sandbox using the sbuser account with the default password sbuser. These changes should be performed through the VMware console.

6. Enter the following in the Sandbox command line through the VMware console:

./Setup

7. Follow the steps in the Setup script to perform initial configuration of the Sandbox VM.

1. • Define the network configuration for the Sandbox;
   • Set up a management port;
   • Define a more secure password for the admin sbuser account.

By default, when you log in you are placed in the /sbuser folder.

When you finish running the Setup script, return to the administrative shell in the NetMRI instance.

8. In the NetMRI administrative shell, run the following command:

sandbox register

This establishes the Sandbox VM's network connectivity with NetMRI.

9. Enter the IP address just configured in Steps 7–8 for the Sandbox VM and press Enter. Setup is complete.

Note: In a NetMRI Operations Center environment with multiple VM-based NetMRI collectors running in hypervisors, you can download a single copy of the Sandbox VM from Infoblox and populate the OC and each of the collectors with a new Sandbox VM from that copy. In a "pure" VM Operations Center environment, in which the Operations Center and all Collectors are VMs, one remote sandbox must be deployed and configured for each Collector virtual appliance.

VMware Workstation Installation

To install the Sandbox VM into a VMware Workstation hypervisor, do the following (these instruction may differ based on the VMware Workstation version):

1. Start VMware Workstation.
2. Choose File –> Import or Export... The Import Virtual Appliance Wizard appears.
3. Click Next and then click Next again in the wizard.
4. Choose Virtual Appliance from the dropdown and click Next.
5. Click on the File System radio button and click 'Browse...'.
6. Select the .vmx file that was previously unpacked from the exported ZIP file, and click Open.
7. Click Next and then click Next again in the wizard.
8. Choose Other Virtual Machine and click Next.
9. Enter a name and location for the Virtual Machine and click Next.
10. Click Next.
11. Click Next again (the network must be bridged for the VM-based NetMRI Sandbox).
12. Click Next.
13. Verify that your settings are correct and click Finish.
    After 20-30 minutes (depending on your hardware and network speed), the NetMRI Sandbox Virtual Appliance will complete import to the VMware host.
14. Select the NetMRI Sandbox Virtual Appliance you imported and instruct it to Power On.
15. Open the console for the Sandbox VM.
16. Enter the following in the Sandbox command line:

./Setup

17. Follow the steps in the Setup script to perform initial configuration of the Sandbox VM.

1. • Defining the network configuration for the Sandbox;
   • Setting up a management port;
   • Define a more secure password for the admin sbuser account. (The default password is sbuser.)

By default, when you log in you are placed in the /sbuser folder.

When you finish running the Setup script, return to the shell in the NetMRI instance.

18. In the virtual NetMRI's administrative shell, run the following command:

sandbox register

As noted, this establishes the Sandbox VM's network connectivity with the NetMRI VM.

19. Enter the IP address just configured in Step 17 for the Sandbox VM and press Enter. Setup is complete.

Installing Custom Perl Modules

Note: The Administrative Shell's /Backup/Sandbox directory provides the common location through which the NetMRI file system and the Sandbox operating system share files. Data files placed on the common location are shared between the Sandbox and NetMRI using the Samba protocol.

Custom Perl script modules can be installed into the NetMRI sandbox environment for use by Perl scripts. This can be accomplished in a number of ways; recommended procedures include the following:

• The standard Perl module installation: unpack the tarball, and run a sequence of make commands;
• Using the cpan command-line utility. (Note: a full discussion of cpan usage is beyond the scope of this document.)

To install a Perl module using standard Perl module installation procedures, do the following:
Upload the Perl module in Tarball form to the sandbox environment by using SCP to send the file into the administrator shell's /Backup/Sandbox directory (below is an example):

scp SomePerlModule.tar.gz admin@172.23.28.2:/Backup/Sandbox

In the administrative shell, the /Backup/Sandbox directory maps to the /mnt/host/data/userdata directory inside the sandbox. After the file has been successfully uploaded to the sandbox, login to the sandbox via the administrative shell.

sandbox login

Once inside the sandbox, use the standard Perl module installation procedure to install the Perl module located at
/mnt/host/data/userdata. As an example:

cd /mnt/host/data/userdata

tar xzf SomePerlModule.tar.gz

make

make test

make install

To install a Perl module, log in to the sandbox using the sandbox login command from the administrative shell as noted above. You use the cpan command-line utility, which is part of the sandbox operating system, to install the desired Perl module. Explanation of the features and capabilities of the cpan utility is beyond the scope of this document; find more information by reading the man page inside the sandbox (run man cpan in the shell).

Installing Custom Python Modules

You can run Python custom scripts under Python 3. To install custom Python modules, first install pip into the sandbox:

#wget https://bootstrap.pypa.io/get-pip.py

#python3 get-pip.py

After that, use the standard pip utility:

#pip install package_name

If there is no Internet connection on the sandbox, use SCP to send the file into the /Backup/Sandbox directory in the administrative shell:

scp get-pip.py admin@172.23.28.2:/Backup/Sandbox

In the administrative shell, the /Backup/Sandbox directory maps to the /mnt/host/data/userdata directory inside the sandbox. After the file is successfully uploaded to the sandbox, log in to the sandbox via the administrative shell:

sandbox login

Once inside the sandbox, use the standard installation procedure to install the script or modules located at /mnt/host/data/userdata:

#cd /mnt/host/data/userdata

#python3 get-pip.py

#pip install package_name

Setting Job Execution Credentials

NetMRI admins can determine whether creators of configuration management jobs can self-approve their Perl/CCS script jobs, or require a NetMRI super admin to approve jobs execution. For a quick refresher on administrator accounts and the Roles they inhabit, see Understanding Users and Roles, as user accounts have a close relationship to job execution.
You can define the minimum script run level at which the appliance requires user-provided CLI credentials when scheduling or running a job.

Note: Through job execution credentials, the user-provided CLI credentials are used to log in to the network devices that are part of the job (in lieu of the CLI credentials associated with the network devices at discovery).

NetMRI provides Configuration Management settings (under Settings icon –> General Settings –> Advanced Settings) to enforce organization policies for securely executing script jobs:

• Job Self Approval — Controls the ability of the script creator to approve the jobs they create and execute in the appliance. This setting is global to all users and can be set to True or False;
• Job Requires User Credentials — Defines the global minimum script "risk level" at which user-provided CLI credentials are required to execute a script job. Risk levels are stated as None (the default), Low, Medium and High.

Correlation between NetMRI account types, their Roles and privileges, and script execution privileges is as follows:

Note: By default, execution privileges are set to None. If the Job Requires User Credentials advanced setting is changed from "None" to a higher setting, you must update scheduled jobs to take advantage of this feature.

If the Job Requires User Credentials run level is greater than or equal to the run level of the target script, the admin user scheduling and/or running the job is prompted to provide CLI credentials from the following options:

• Use the requester's stored CLI credentials;
• Use the approver's stored CLI credentials;
• Manually specify new CLI credentials.

If the Job Requires User Credentials run level is less than the run level of the target script, the admin user scheduling and/or running the job is not prompted to provide CLI credentials; the job uses the CLI credentials associated with the network devices at Discovery.

Note: See Creating User Accounts for more information on setting up admins with properly defined user names, passwords and Enable passwords.

To set job approval settings for all NetMRI admin accounts, do the following:

1. On the Settings icon –> General Settings –> Advanced Settings page, under the Configuration Management category, click the Edit icon for Job Self Approval.
2. To allow all user accounts to self-approve running automated jobs that use CCS and Perl scripts, choose True. Otherwise, choose False.
3. Click OK to commit the setting.

To require NetMRI admin accounts to use CLI credentials when executing scripts of a specific risk level, do the following:

1. On the Settings icon –> General Settings –> Advanced Settings page, under the Configuration Management category, click the Edit icon for Job Requires User Credentials.

Scripting Well-Known Variables (Perl, Python, and CCS)

$assurance = "99";
$community = "mysnmp";
$contextname = "";
$id = "21";
$ipaddress = "10.10.110.5";
$model = "871";
$name = "QAlabrtr11";
$syscontact = "QAEast's lab; Floor 2";
$sysdescr = "Cisco IOS Software, C870 Software (C870-ADVIPSERVICESK9-M), Version 12.3(8)YI2, RELEASE SOFTWARE (fc1)Synched to technology version 12.3(10.3)T2 Technical Support: http://www.cisco.com/techsupport Copyright (c) 1986-2005 by Cisco Systems, Inc. Compil";
$syslocation = "QA lab right bottom soho router";
$sysname = "QAlabrtr11.example.com";
$type = "Router";
$vendor = "Cisco";
$version = "12.3(8)YI2";

Variables for Perl job support (Also available to CCS)

$api_url = "http://192.168.1.1";
$device_id = "21";
$http_password = "adminpass";
$http_username = "admin";
$job_id = "197";
$script_login = "true";
$script_timeout = "300";

Variables for Python job support 

api_url = "http://192.168.1.1"
device_id = "21"
http_password = "adminpass"
http_username = "admin"
job_id = "197"
script_login = "true"
script_timeout = "300"

Variables for Templates

$NetMRI_ipaddress = "192.168.1.1";

Device Model Attributes

$device_datasourceid = "0";
$device_deviceaddlinfo = "";
$device_deviceassurance = "99";
$device_deviceccscollection = "on";
$device_devicechangedcols = "DeviceRunningConfigLastChange,DeviceSavedConfigLastChange";
$device_devicecommunity = "mysnmp";
$device_deviceconfiglastchecked = "2011-03-28 13:07:49";
$device_deviceconfiglocked = "0";
$device_deviceconfiglocklastchange = "";
$device_deviceconfiglocklastchangeby = "";
$device_deviceconfigpolling = "on";
$device_deviceconfigtimestamp = "2011-03-17 11:01:15";
$device_devicecontextname = "";
$device_devicednsname = "";
$device_deviceendtime = "";
$device_devicefingerprint = "off";
$device_devicefirstoccurrence = "2011-03-10 11:58:27";
$device_deviceid = "21";
$device_deviceipdotted = "10.10.110.5";
$device_deviceipnumeric = "3691671045";
$device_devicelicensed = "1";
$device_devicemac = "00:15:C6:53:AB:07";
$device_devicemanagedind = "true";
$device_devicemodel = "871";
$device_devicename = "centlabrtr11";
$device_devicepolicyschedulemode = "change";
$device_deviceportscanning = "off";
$device_devicerank = "90";
$device_devicereboottime = "2010-07-20 11:14:39";
$device_devicerunningconfiglastchange = "";
$device_devicesaaversion = "2.2.0 Round Trip Time MIB";
$device_devicesavedconfiglastchange = "";
$device_devicesnmpanalysis = "on";
$device_devicesnmppolling = "on";
$device_devicestandardscompliance = "";
$device_devicestarttime = "2011-03-28 13:31:32";
$device_devicesyscontact = "QAEast's lab; Floor 2";
$device_devicesysdescr = "Cisco IOS Software, C870 Software (C870-ADVIPSERVICESK9-M), Version 12.3(8)YI2, RELEASE SOFTWARE (fc1)Synched to technology version 12.3(10.3)T2 Technical Support: http://www.cisco.com/techsupport Copyright (c) 1986-2005 by Cisco Systems, Inc. Compil";
$device_devicesyslocation = "Central lab right bottom soho router";
$device_devicesysname = "centlabrtr11.example.com";
$device_devicetimestamp = "2011-03-28 13:31:32";
$device_devicetype = "Router";
$device_devicevendor = "Cisco";
$device_devicevendordefaultcollection = "off";
$device_deviceversion = "12.3(8)YI2";
$device_networkdeviceind = "true";
$device_routingind = "true";
$device_switchingind = "false";
$device_virtualind = "false";

Job Specification Model Attributes

$job_specification_approved_by = "1";

$job_specification_approved_by_name = "admin";

$job_specification_approved_timestamp = "2011-03-28 13:35:18";

$job_specification_config_template_id = "";

$job_specification_created_at = "2011-03-28 13:35:19";

$job_specification_created_by = "admin";

$job_specification_description = "Run now job";

$job_specification_id = "181";

$job_specification_job_type = "script";

$job_specification_name = "Run Now [my script]";

$job_specification_schedule = "";

$job_specification_script_id = "64";

$job_specification_updated_at = "2011-03-28 13:35:19";