JUNOS::Device - Implements a remote JUNOScript device


NAME

JUNOS::Device - Implements a remote JUNOScript device


SYNOPSIS

Here is example that makes a telnet connection to router11, then updates the router11's configuration with the configuration from $xmlfile. It also deals with error conditions and gracefully shuts down the telnet session.

    use JUNOS::Device;
    sub graceful_shutdown
    {
        my ($jnx, $req, $state, $success) = @_;
    
        if ($state >= STATE_CONFIG_LOADED) {
            print "Rolling back configuration ...\n";
            $jnx->load_configuration(rollback => 0);
        }
        if ($state >= STATE_LOCKED) {
            print "Unlocking configuration database ...\n";
            $jnx->unlock_configuration();
        }
 
        if ($state >= STATE_CONNECTED) {
            print "Disconnecting from the router ...\n";
            $jnx->request_end_session();
            $jnx->disconnect();
        }
        if ($success) {
            die "REQUEST $req SUCCEEDED\n";
        } else {
            die "REQUEST $req FAILED\n";
        }
    }
    $jnx = new JUNOS::Device(hostname => "router11",
                             login => "johndoe",
                             password => "secret",
                             access => "telnet");
    unless ( ref $jnx ) {
        die "ERROR: can't connect to $deviceinfo{hostname}.\n";
    }
    print "Locking configuration database ...\n";
    my $res = $jnx->lock_configuration();
    my $err = $res->getFirstError();
    if ($err) {
        print "ERROR: $deviceinfo{hostname}: can't lock configuration.  Reason: $err->{message}.\n";
        graceful_shutdown($jnx, $xmlfile, STATE_CONNECTED, REPORT_FAILURE);
    }
    #
    # Load the configuration
    #
    print "Loading configuration from $xmlfile ...\n";
    if (! -f $xmlfile) {
        print "ERROR: Cannot load configuration in $xmlfile\n";
        graceful_shutdown($jnx, $xmlfile, STATE_LOCKED, REPORT_FAILURE);
    }
    my $parser = new XML::DOM::Parser;
    my $doc = $parser->parsefile($xmlfile);
    unless ( ref $doc ) {
        print "ERROR: Cannot parse $xmlfile, check to make sure the XML data is well-formed\n";
        graceful_shutdown($jnx, $xmlfile, STATE_LOCKED, REPORT_FAILURE);
    }
    $res = $jnx->load_configuration(configuration => $doc);
    unless ( ref $res ) {
        print "ERROR: can't load the configuration from $xmlfile\n";
        graceful_shutdown($jnx, $xmlfile, STATE_LOCKED, REPORT_FAILURE);
    }
    $err = $res->getFirstError();
    if ($err) {
        print "ERROR: can't load the configuration from $xmlfile.  Reason: $err->{message}\n";
        graceful_shutdown($jnx, $xmlfile, STATE_CONFIG_LOADED, REPORT_FAILURE);
    }

Here is another example. It retrieves 'show chassis hardware' information and transforms the input with XSLT.

    # connect TO the JUNOScript server
    $jnx = new JUNOS::Device(hostname => "router11",
                             login => "johndoe",
                             password => "secret",
                             access => "telnet");
    unless ( ref $jnx ) {
        die "ERROR: $deviceinfo{hostname}: can't connect.\n";
    }
    # send the command and receive a XML::DOM object
    my $res = $jnx->get_chassis_inventory(detail => 1);
    unless ( ref $res ) { 
        die "ERROR: $deviceinfo{hostname}: can't execute command $query.\n";   
    }
    # Check and see if there were any errors in executing the command.
    # If all is well, output the response using XSLT.
    my $err = $res->getFirstError();
    if ($err) {
        print STDERR "ERROR: $deviceinfo{'hostname'} - ", $err->{message}, "\n";
    } else {
        # 
        # Now do the transformation using XSLT.
        #
        my $xmlfile = "$deviceinfo{hostname}.xml";
        $res->printToFile($xmlfile);
        my $nm = $res->translateXSLtoRelease('xmlns:lc', $xslfile, "$xslfile.tmp");
        if ($nm) {
            my $command = "xsltproc $nm $deviceinfo{hostname}.xml";
            system($command);
        } else {
            print STDERR "ERROR: Invalid XSL File $xslfile\n";
        }
    }
    
    # always close the connection
    $jnx->request_end_session();
    $jnx->disconnect();


DESCRIPTION

This module implements an object oriented interface to the JUNOScript (tm) XML-based API supported by Juniper Networks. Objects of this class represent the local side of connection to a Juniper Networks device running JUNOS, over which the JUNOScript protocol will be spoken. JUNOScript is described in detail in the JUNOScript API Guide and Reference.


CONSTRUCTOR

new(%ARGS)

The constructor accepts a hash table %ARGS containing the following keys:

    hostname
        Name of Juniper box to connect to.
    login
        Username to log into box as.
    password
        Password for login username.
    access
        Access method - can be 'telnet' or 'ssh' or 'ssl'.
    Do_Not_Connect
        if set to true a connection to a Juniper box
        will not be establish upon object creation.  You then
        must call the 'connect' function to explicitly create the
        connection
    namespace-action
        if you don't want to deal with namespace, just set this
        to either 'remove-namespace' or 'update-namespace'. This is 
        handy when you don't want to care about declaring the XML namespace
        in your XSL file(s).  'remove-namespace' means removing all 
        namespace declarations and schemaLocation from the the responses.  
        'update-namespace' means remove all namespaces and replace 
        schemaLocation with noNamespaceSchemaLocation.

Additional keys specific to the access method are processed by the access method object (e.g. JUNOS::Access::telnet). See the perldoc of the access method class for the definition of these additional keys.


METHODS

command($COMMAND)

Send the raw command string from $COMMAND to the remote Juniper box. This is a 'mostly unsupported' way of getting to any JUNOS command that is currently unsupported in JUNOScript. Caveat Coder.

connect()

typically called by the constructor. If you set 'Do_Not_Connect' to be true you must call this function yourself.

disconnect()

Disconnects from a JUNOScript server & performs other clean-up related to this conneciton. This function will also be called if your JUNOS::Device object goes out of scope or is undef'ed.

getErrors() getFirstError()

getErrors() and getFirstError() are available for the application to retrieve all of the errors occured within the last JUNOS::Device method invocation. The application may wish to print these error messages in log file or display on a different error window. getErrors() returns a reference to all the errors and getFirstError() returns the earliest error that triggered the failure. These methods can be called after a JUNOS::Device method has failed.

Note: These errors normally go to the standard output unless the Always category is in JUNOS::Trace is disabled. Unless you want the errors to go someplace other than the standard output, you don't need to call these methods.

An example of using getFirstError:

unless($jnx->connect()) { my $error = $jnx->getFirstError(); print ERRORLOG (``ERROR: $error\n''); }

An example of using getErrors:

unless($jnx->connect()) { my @errors = @{$jnx->getErrors()}; for my $error (@errors) { print ERRORLOG (``ERROR: $error\n''); } }

request($REQUEST)

You should call <JUNOScript command> functions - which eventually utilize this function - you should not call this directly!


Sends a request in $REQUEST to a Juniper box and returns the result.
In a scalar context a JUNOS::Response object is returned.
In an array context an array consisting of the 
XML::DOM::Document object and the raw JUNOS::Response 
object containing the enclosing <rpc-reply> tags.
The parameter is the name of the JUNOScript function to be
called on the remote Juniper box.

<JUNOScript command>

You may call any JUNOScript command via the JUNOS::Device Handle. See 'request' function for return values.


These methods are available when connecting to a JUNOS 5.1 router.
they can take two types of arguments or zero arguments:

1. 'toggle' - argument is present or not. For example the 'extensive' argument to the 'get_interface_information' method: get_interface_information(extensive => 1);

2. 'string' - a string argument For example the 'slot' argument to the 'get_pic_information' method: get_pic_information(slot => ``2'');

    method is followed by a list of accepted arguments and their types
    if it has any.
    get_accounting_profile_information
        profile => STRING
    get_accounting_record_information
        profile => STRING
        since => STRING
        utc_timestamp => TOGGLE
    get_chassis_inventory
        detail => TOGGLE
        extensive => TOGGLE
    get_environment_information
    get_feb_information
    get_firmware_information
    get_fpc_information
    get_interface_information
        brief => TOGGLE
        destination_class => STRING
        detail => TOGGLE
        extensive => TOGGLE
        interface_name => STRING
        media => TOGGLE
        queue => TOGGLE
        snmp_index => STRING
        statistics => TOGGLE
        terse => TOGGLE
    get_pic_information
        slot => STRING
    get_route_engine_information
        slot => STRING
    get_scb_information
    get_sfm_information
    get_snmp_information
    get_ssb_information
        slot => STRING
    request_halt
        at => STRING
        in => STRING
        media => STRING
        message => STRING
    request_reboot
        at => STRING
        in => STRING
        media => STRING
        message => STRING
    get_bgp_group_information
        group_name => STRING
    get_bgp_neighbor_information
        neighbor_address => STRING
    get_bgp_summary_information
    get_instance_information
        name => STRING
    get_instance_summary_information
    get_isis_adjacency_information
        brief => STRING
        detail => STRING
        instance => STRING
        system_id => STRING
    get_isis_database_information
        brief => STRING
        detail => STRING
        extensive => STRING
        instance => STRING
        system_id => STRING
    get_isis_interface_information
        brief => STRING
        detail => STRING
        instance => STRING
        interface_name => STRING
    get_isis_route_information
        instance => STRING
    get_isis_spf_information
    get_isis_statistics_information
        instance => STRING
    get_l2vpn_connection_information
        brief => STRING
        down => STRING
        extensive => STRING
        history => STRING
        instance => STRING
        local_site => STRING
        remote_site => STRING
        status => STRING
        up => STRING
        up_down => STRING
    get_mpls_admin_group_information
    get_mpls_cspf_information
    get_mpls_interface_information
    get_mpls_lsp_information
        brief => STRING
        detail => STRING
        down => STRING
        egress => STRING
        extensive => STRING
        ingress => STRING
        name => STRING
        statistics => STRING
        terse => STRING
        transit => STRING
        up => STRING
    get_mpls_path_information
        path => STRING
    get_ospf_database_information
        advertising_router => STRING
        area => STRING
        asbrsummary => STRING
        brief => STRING
        detail => STRING
        extensive => STRING
        extern => STRING
        instance => STRING
        lsa_id => STRING
        netsummary => STRING
        network => STRING
        nssa => STRING
        router => STRING
        summary => STRING
    get_ospf_interface_information
        brief => STRING
        detail => STRING
        extensive => STRING
        instance => STRING
        interface_name => STRING
    get_ospf_io_statistics_information
    get_ospf_log_information
        instance => STRING
    get_ospf_neighbor_information
        brief => STRING
        detail => STRING
        extensive => STRING
        instance => STRING
        neighbor => STRING
    get_ospf_route_information
        abr => STRING
        asbr => STRING
        detail => STRING
        extern => STRING
        instance => STRING
        inter => STRING
        intra => STRING
    get_ospf_statistics_information
        instance => STRING
    get_rsvp_interface_information
        brief => STRING
        detail => STRING
    get_rsvp_neighbor_information
    get_rsvp_session_information
        brief => STRING
        detail => STRING
        down => STRING
        egress => STRING
        ingress => STRING
        interface => STRING
        lsp => STRING
        name => STRING
        nolsp => STRING
        terse => STRING
        transit => STRING
        up => STRING
    get_rsvp_statistics_information
    get_rsvp_version_information
    get_ted_database_information
        brief => STRING
        detail => STRING
        extensive => STRING
        system_id => STRING
    get_ted_link_information
        brief => STRING
        detail => STRING
    get_ted_protocol_information
        brief => STRING
        detail => STRING
    request_end_session
    request_package_add
        delay_restart => TOGGLE
        force => TOGGLE
        no_copy => TOGGLE
        package_name => STRING
        reboot => TOGGLE
    request_package_delete
        force => TOGGLE
        package_name => STRING


SEE ALSO


    JUNOS::Response
    XML::DOM
    JUNOS::Trace
    JUNOScript API Guide (available at www.juniper.net)
    JUNOScript API Reference (available at www.juniper.net)


AUTHOR

Juniper Junoscript Perl Team, send bug reports, hints, tips, and suggestions to support@juniper.net.


COPYRIGHT

Copyright (c) 2001-2002 Juniper Networks, Inc. All rights reserved.

 JUNOS::Device - Implements a remote JUNOScript device