JUNOScript API README
Version 6.4I0
Contents
Abstract
Each Juniper Networks router running JUNOS Internet software release 4.3B2 or later supports the JUNOScript API. The JUNOScript API is an XML application that Juniper Networks routers use to exchange information with client applications.
Because JUNOScript is an XML application, you can leverage the myriad Perl modules in the public domain to ease the development of client applications that monitor and configure Juniper Networks routers. There are many modules in CPAN (http://www.cpan.org) and other Perl source repositories that provide ways to manipulate XML data (for example, XML::Parser, and XML::DOM modules).
The JUNOS::Device module provides an object-oriented interface for communicating with the JUNOScript server so you can start using the JUNOScript API quickly and easily. There are several modules in this library but client applications directly invoke the Device object only. When the client application creates a JUNOS::Device object, it specifies a router name and the login name to use when accessing the router (which determines the client application's access level).
The following code segment shows how to use the JUNOS::Device object to request information from a Juniper Networks router. This example invokes the query called get_chassis_inventory. For a list of valid queries and the corresponding arguments, invoke the command man JUNOS::Device after completing the installation.
# Step 1: set up the query
my $query = "get_chassis_inventory";
my %queryargs = ( detail => 1 );
# Step 2: Create a JUNOScript Device object
my %deviceinfo = (
access => "telnet",
login => "johndoe",
password => "secret",
hostname => "router11"
);
my $jnx = new JUNOS::Device(%deviceinfo);
unless ( ref $jnx ) {
die "ERROR: Failed to create device\n"; }
# Step 3: connect to the Juniper Networks router
unless ( $jnx->connect() ) {
die "ERROR: Failed to connect\n"; }
# Step 4: send the query and receive a XML::DOM object
my $res = $jnx->$query( %queryargs );
unless ( ref $res ) {
die "ERROR: Failed to execute command\n"; }
# Step 5: check for error
my $err = $res->getFirstError();
if ($err) {
print STDERR "ERROR: $deviceinfo{'hostname'} - ", $err->{message}, "\n"; } else {
# Step 6: do something with the result, just traverse through # the $res (an XML::DOM object) and do what you need to do. }
# Step 7: always close the session & connection when you're done
$jnx->request_end_session();
$jnx->disconnect();
Back to Top
Documents
The following documents are available at http://www.juniper.net/beta for the beta release and http://www.juniper.net/support for final release of each version of the JUNOS Internet software.
The following classes provide perldoc to describe their interfaces. Run man <class> after the installation is complete.
Supported Platforms
The current version of this module has been tested on the following platforms. Later releases may support additional platforms.
Downloads
Client Perl applications can communicate with the JUNOScript server either via Telnet, SSH or SSL. SSH and SSL available only in the domestic distribution.
To download the publicly available Telnet-only version of the JUNOScript Perl Client, perform the following steps:
To download the domestic version of the JUNOScript Perl Client (which supports both Telnet, SSH and SSL), perform the following steps:
Installation
Instructions for UNIX Systems
% which perl % perl -v
The JUNOScript Perl Client requires perl version 5.0004 or later. Verify that you are running that version of the perl executable. If not, check your PATH or install the latest release of perl.
On FreeBSD and Linux systems: % tar zxf junoscript-n.n-type.tar.gz
On Solaris systems: % gzip -dc junoscript-n.n-type.tar.gz | tar xf -
On FreeBSD and Linux systems: [/my/junoscript-n.n]% tar zxf junoscript-prereqs-n.n-type.tar.gz
On Solaris systems: [/my/junoscript-n.n]% gzip -dc junoscript-prereqs-n.n-type.tar.gz | tar xf -
If installing modules under the standard directory (normally /usr/local/lib and you'll need root privilege): [/my/junoscript-n.n]% perl install-prereqs.pl -force
Installing modules under your own private directory (see notes below): [/my/junoscript-n.n]% setenv PERL5LIB /my/private/directory/lib [/my/junoscript-n.n]% setenv MANPATH "$MANPATH/:$PERL5LIB/../man" [/my/junoscript-n.n]% setenv PATH "$PATH/:$PERL5LIB/../bin" [/my/junoscript-n.n]% perl install-prereqs.pl -install_directory $PERL5LIB -force
As the install-prereqs.pl script installs the last few modules, it prompts you for input. Simply following the instructions and accept default responses whenever they are offered. The only exception is during installation of the SSH module: here you must choose one of the cipher packages supported by the JUNOScript server-- DES, DES3 or Blowfish.
The option -force forces install-prereqs.pl to install a module even if an older version already exists or make test fails. For more information on the install-prereqs.pl options, type perl install-prereqs.pl -help.
If installing JUNOS::Device under the standard directory (it's normally /usr/local/lib): [/my/junoscript-n.n]% perl Makefile.PL
If installing JUNOS::Device under your own private directory: [/my/junoscript-n.n]% perl Makefile.PL LIB=$PERL5LIB INSTALLMAN3DIR=$PERL5LIB/../man/man3
[/my/junoscript-n.n]% make [/my/junoscript-n.n]% make test [/my/junoscript-n.n]% make install
Notes for private directory installation:
% setenv MANPATH "$MANPATH/:$PERL5LIB/../man" % man JUNOS::Device % setenv PATH "$PATH/:$PERL5LIB/../bin" % which xsltproc
Back to Top
Running the Sample Scripts
The JUNOScript Perl distribution includes sample scripts that demonstrate how to use JUNOScript to retrieve and change the configuration of a Juniper Networks router. The samples reside in the junoscript-n.n/examples directory.
Reading configuration: Chassis Inventory This example sends a <get-chassis-information> request to the Juniper Networks router and displays the result to the standard output. Depending on the command line option, it uses XSLT to display the result in plain text, HTML, or raw XML. The purpose of this example is to show the power and flexibility of combining the JUNOScript and XSLT.
-x <xslfile>
-o <outputfile>
Optional. If <xslfile> is specified, the <xslfile> is used for rendering
the output. If <xslfile> is not specified, xsl/chassis_inventory_csv.xsl
is used by default. You can use any of the three XSL files (csv, html,
and xml) or create your own. If <outputfile> is specified, the
transformation will be put into <outputfile>. If <outputfile> is not
specified, the result will be displayed on the standard output.
-m <access>
Optional. The default value is telnet. It specifies which transport should
be used to communicate with the Juniper Networks router. The valid values
are ssh, ssl, clear-text, and telnet.
-l <login>
-p <password>
The login identity and password to use when accessing the Juniper Networks
router. The login identity must already exist in the router configuration
and must have at least read privilege on the router. (Configure the login
account by using the CLI command set system login user.) If these
arguments are not provided on the command line, the user will be prompted
to enter the information.
<router>
The host name or IP address of the router.
Changing configuration: Load Configuration This example simply selects one of set_login_user_foo.xml or set_login_class_bar.xmlas the example configuration to load. They are included in the requests directory. There you will see the XML files containing the RPC requests. You can put your own configuration file in the requests directory and have load_configuration load it in the target router for you. The purpose of this example is to show you how simple it is to change your router configuration using JUNOScript. See JUNOScript API Reference for the detail description of the configuration you can submit via JUNOScript.
-t
Optional. The default value is xml. If specified, the configuration in the
request file is text, not xml.
-a <action>
Optional. The default value is merge. It specifies which load action to
take. The valid values are merge, override, and replace.
-m <access>
Optional. The default value is telnet. It specifies which transport should
be used to communicate with the Juniper Networks router. The valid values
are ssh, ssl, clear-text, and telnet.
-l <login>
-p <password>
The login identity and password to use when accessing the Juniper Networks
router. The login identity must already exist in the router configuration
and must have at least read privilege on the router. (Configure the login
account by using the CLI command set system login user.) If these
arguments are not provided on the command line, the user will be prompted
to enter the information.
<request>
Specify the name of the configuration file to be loaded. The configuration
files included with the example are set_login_user_foo.xml and
set_login_class_bar.xml, both of which reside in the requests directory.
If -t is specified, the configuration in this file should be in text
format.
Example of configuration file content in xml format:
<configuration>
<system>
<host-name>my-host-name</host-name>
</system>
</configuration>
Example of configuration file content in text format:
<configuration-text>
system {
host-name my-host-name;
}
</configuration-text>
<router>
The host name or IP address of the router.
Router Diagnostics: Diagnose BGP
This example retrieves the BGP summary from a Juniper Networks router and
displays key information on the unestablished peers. It shows how useful
diagnostic tools can be written using JUNOScript.
You also have an option to render the output in plain text or DHTML (it allows you to dynamically sort any column) using XSL. The output is saved in a file named <router>.xml which is the concatenation of the <get-bgp-summary-information> responses on all of the BGP peers for the target router. Take a look at this XML file if you wish to write your own XSL file to render the output.
-m <access>
Optional. The default value is telnet. It specifies which transport should
be used to communicate with the Juniper Networks router. The valid values
are ssh, ssl, clear-text, and telnet.
-l <login>
-p <password>
The login identity and password to use when accessing the Juniper Networks
router. The login identity must already exist in the router configuration
and must have at least read privilege on the router. (Configure the login
account by using the CLI command set system login user.) If these
arguments are not provided on the command line, the user will be prompted
to enter the information.
-x <xslfile>
-o <outputfile>
Optional. If <xslfile> is specified, the <xslfile> is used for rendering
the output. If <xslfile> is not specified, xsl/text.xsl is used by
default. You can use any of the three XSL files (text, html, and dhtml)
or create your own. If <outputfile> is specified, the transformation will
be put into <outputfile>. If <outputfile> is not specified, the result
will be displayed on the standard output.
<router>
The host name or IP address of the router.
XML <-> RDB scrambler/descrambler
Additional Dependencies:
The installation section above does not install modules required by this
example. It is mainly because a Relational Database must be installed
before the required Perl modules can be installed successfully. We keep
this installation separate so you can run the other examples without
having to worry about installing and running the RDB.
This example uses MySQL as its relational database, hence you must first install the MySQL database. The version we have tested this example with is 3.23. Simply go to http://mysql.com/downloads/mysql-3.23.html to download the stable release of the MySQL database. Then follow the installation instructions in Docs/manual.html after you ungzip and untar the MySQL archive.
Check whether all the Perl modules required by this example are installed.
[/my/junoscript-n.n]% perl required-mod.pl RDB
If any of the following Perl modules is not installed, you must install it before running this example. See Installation of Perl Modules Required by Examples.
Before running the example, edit the $DSN value in common.pm to reflect your configuration.
The scripts perform the following functions:
Perform the following steps:
Here's a concrete example:
This will store that router's configuration as XML in the current directory as a file called myrouter.acme.com.xmlconfig.
[/my/junoscript-n.n/examples/RDB]% perl pop_tables.pl myrouter.acme.com.xmlconfig
pop_tables.pl displays the exact command to type for step 7, it includes the primary key to identify the configuration.
Installation of PERL
UNIX
FreeBSD and Linux: % tar zxf stable.tar.gz
Follow instruction in perl-5.6.1/INSTALL to install perl. You can make
your private directory the standard directory for installation, then
the perl executables and any Perl modules you install will
automatically go to the directory you specified. Otherwise, take the
defaults and the executables and modules will be installed under
/usr/local.
Back to Top
Installation of Perl Modules Required by Examples
You can tell install-prereqs.pl to install only the modules required by JUNOS::Device or by a specific example. By default install-prereqs.pl install all required modules for JUNOS::Device, get_chassis_inventory.pl, load_configuration.pl and diagnose_bgp.pl. The RDB installation is kept separate because it required the installation of a RDB. This section shows you how to specify which set of modules to install.
UNIX
Installing modules under the standard directory (it's normally /usr/local/lib and you'll need root privilege): [/my/junoscript-n.n]% perl install-prereqs.pl -used_by <example> -force
Installing modules under your own private directory (see notes below): [/my/junoscript-n.n]% setenv PERL5LIB /my/private/directory/lib [/my/junoscript-n.n]% perl install-prereqs.pl -used_by <example> -install_directory $PERL5LIB -force
Where <example> is get_chassis_inventory, load_configuration, RDB, diagnose_bgp, or JUNOS::Device. If the -used_by option is not used, the default is to install all required modules except those required by RDB. The reason required modules for RDB is not part of the default installation is because it requires an RDB being installed first.
When install-prereqs.pl is installing Term::ReadKey, it will prompt user for inputs.
The option -force forces install-prereqs.pl to install the module even if an older version already exists or 'make test' fails. For more information on the install-prereqs.pl options, type 'perl install-prereqs.pl -help'.
Notes for private directory installation:
Back to Top
Dependencies
When you run the install script, you'll see the list of C libraries, executables, and Perl modules required by JUNOS::Device and its examples. The only module that the install script does not address is the mysql distribution. To run the RDB example, you must first install mysql before running the installation for RDB.
If you wish to find out what are missing dependencies on your system without running the install script, you can run the following commands.
perl required-mod.pl
Back to Top
FAQ
Installation
Check the versions of your gcc and as, using 'as -V' and 'gcc -v'. We recommend that you use gcc version 2.8.1 or higher and as 5.0 or higher.
Also make sure your PATH is set correctly so the /usr/ccs/bin/as is used not /usr/local/bin/as.
Run 'perl -V' to find out what are the compiler and linker options your perl executable was built with. The c compiler configured in perl is 'cc' and you only have 'gcc' installed on your system, you'll need to reinstall your perl (See Installation of perl) with the correct c compiler. This can happen if perl was installed on a different system and got copied over.
If you have the same c compiler as what's configured in perl then check your PATH envioronment variable, maybe you don't have the path to the c compiler there.
Try installing JUNOScript on FreeBSD 4.3 with the stock X11, there may be conflicts between X11R6.5.1 and the prerequisite modules.
Runtime
Make sure you can access the Javascript sorttable.js, it should be under the js directory one level below the dynamic html file. For example, let's say you have run 'perl diagnose_bgp.pl -x xsl/dhtml.xsl -o diagnose_bgp_dhtml.html router11'. If you copy the output file to some other directory, make sure you also copy the js directory.
% ls -R
diagnose_bgp_dhtml.html js/
./js:
sorttable.js
If sorttable.js is not the problem, remove the following line from the
DHTML file. Some versions of browsers do not like the <meta> info
generated by the XSLT processor.
- <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
JUNOScript responses use default namespace, something XSLT 1.0 does not deal with very well. The XSL file must declare the default namespace explicitly if it is used in the XML data that it transforms. All of the XSL files provided with the examples contain the declaration so you should use them as examples for your own XSL files. This problem is addressed by XSLT 2.0.
This topic is discussed in http://www.vbxml.com/people/bosley/defaultns.asp.
$res = get_chassis_inventory(detail => 0);
The syntax error is returned because 0 is an invalid input for the argument. The safest way is to omit the argument. For example:
$res = get_chassis_inventory();
Back to Top
Support
If you have problems with this JUNOS package, please e-mail support@juniper.net. We are looking forward to hearing from you.
Juniper Networks is registered in the U.S. Patent and Trademark Office and in other countries as a trademark of Juniper Networks, Inc. Internet Processor, Internet Processor II, JUNOS, JUNOScript, M5, M10, M20, M40, M160, and its corporate, product, and service logos are trademarks of Juniper Networks, Inc. All other trademarks, service marks, registered trademarks, or registered service marks are the property of their respective owners. Use of any Juniper Networks trademarks in a manner that is likely to cause confusion among its customers or disparages/discredits Juniper Networks is strictly prohibited.
Copyright (c) 2001, Juniper Networks, Inc. All Rights Reserved.