  NETCONF Perl client README

   Version 12.1R5

   Contents
     * Abstract
     * Documents
     * Supported Platforms
     * Downloads
     * Installation
     * Running the Examples
     * Installation of Perl
     * Installation of Perl Modules Required by Examples
     * Dependencies
     * Support

   --------------------------------------------------------------------------

   Abstract

   Each Juniper Networks routing platform running JUNOS Internet software
   release 7.5B1 or later supports the NETCONF API. The NETCONF API provides
   mechanisms to install, manipulate, and delete the configuration of network
   devices. The NETCONF API uses an Extensible markup Language (XML) based
   data encoding for the configuration data as well as operations and
   messages defined in the API.

   Because NETCONF uses XML based data encoding, 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 the Comprehensive Perl Archival Network (CPAN,
   http://www.cpan.org) and other Perl source repositories that provide ways
   to manipulate XML data (for example, the XML::Parser, and XML::DOM
   modules).

   The Net::Netconf::Manager module provides an object-oriented interface for
   communicating with the NETCONF server so you can start using the NETCONF
   API quickly and easily. There are several modules in this library but
   client applications directly invoke the Manager object only. When the
   client application creates a Net::Netconf::Manager 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 Net::Netconf::Manager
   object to request information from a Juniper Networks routing platform.
   This example invokes the query called get_chassis_inventory.

 # Step 1: set up the query

 my $query = "get_chassis_inventory";
 my %queryargs = ( detail => 1 );


 # Step 2: Create a Netconf Manager object and connect to the Juniper
 Networks routing platform

 my %deviceinfo = (
  access => "ssh",
  login => "johndoe",
  password => "secret",
  hostname => "router11"
  );
  my $jnx = new Net::Netconf::Manager(%deviceinfo);

  unless ( ref $jnx ) {
         croak "ERROR: $deviceinfo{hostname}: failed to connect.\n";
  }


  # Step 3: send the query and receive a reply

  my $res = $jnx->$query( %queryargs );


 # Step 4: check for error

  if ($jnx->has_error) {
      croak "ERROR: in processing request \n $jnx->{request} \n";
  } else {


 # Step 5: do something with the result
  }

 # Step 6: always disconnect from the server when you're done
 $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.

     * NETCONF API Guide
     * JUNOS XML API Configuration Reference
     * JUNOS XML API Operational Reference

   The following classes provide perldoc to describe their interfaces. Run
   man <class> after the installation is complete.

     * Net::Netconf::Manager
     * Net::Netconf::Transform
     * Net::Netconf::Trace
    Back to Top  

   Supported Platforms

   The current version of this module has been tested on the following
   platforms. Later releases may support additional platforms.

     * FreeBSD 4.10
        Back to Top  

       Downloads

       Client Perl applications can communicate with the NETCONF server via
       SSH only. The NETCONF Perl client needs a SSH client program (like
       OpenSSH) installed on the system.

       To download the publicly available version of the NETCONF Perl Client,
       perform the following steps:

         1. Access the Juniper Networks Web site at
            http://www.juniper.net/beta (for beta software) or
            http://www.juniper.net/support (for final release software).
         1. Click on the link labeled "NETCONF API Software" on the left.
         2. Click on the link labeled "NETCONF API Client" to download the
            Net::Netconf::Manager distribution in gzip format.
         3. Click on the link "NETCONF API Client Prerequisites" to download
            the distribution containing the C libraries and Perl modules
            required by Net::Netconf::Manager and its samples.
        Back to Top  

       Installation
        Instructions for UNIX Systems

         1. Make sure Perl is installed. If necessary, see Installation of
            Perl.

            % which perl
            % perl -v

            The NETCONF Perl Client requires version 5.6.1 or later of the
            perl executable. Verify that you are running that version of the
            perl executable. If not, check your PATH or install the latest
            release of perl.

         1. Download the NETCONF gzip archive from the Juniper Networks
            website. The archive is named netconf-perl-n.n.tar.gz, where n.n
            is a release code such as 7.5. For instructions, see Download.
             
         2. Unzip and untar the archive.

            On FreeBSD systems:
            % tar zxf netconf-perl-n.n.tar.gz

         3. Change to the NETCONF directory.
            % cd netconf-perl-n.n
             
         4. Download the gzip archive of the prerequisite library and modules
            from the Juniper Networks Web site in a directory called prereqs,
            which must be directly under the netconf-n.n directory. The
            archive is named netconf-perl-prereqs-n.n.tar.gz where n.n is a
            release code such as 7.5. For instructions, see Download.
             
         5. Unzip and untar the archive.

            On FreeBSD systems:
            [/my/netconf-perl-n.n]% tar zxf netconf-perl-prereqs-n.n.tar.gz

         6. Install the required C binaries and Perl modules. If you wish to
            install the required files in your private directory instead of
            the standard directory, you can use the -install_directory option
            to specify your private installation directory. The standard
            directory is the installation directory configured in the perl
            executable. Usually, the standard directory is /usr/lib or
            /usr/local/lib, and you'll need root privilege to install modules
            in these directories.

            If installing modules under the standard directory (normally
            /usr/local/lib and you'll need root privilege):
            [/my/netconf-perl-n.n]% perl install-prereqs.pl -force

            Installing modules under your own private directory (see notes
            below):
            [/my/netconf-perl-n.n]% setenv PERL5LIB /my/private/directory/lib
            [/my/netconf-perl-n.n]% setenv MANPATH
            "$MANPATH/:$PERL5LIB/../man"
            [/my/netconf-perl-n.n]% setenv PATH "$PATH/:$PERL5LIB/../bin"
            [/my/netconf-perl-n.n]% perl install-prereqs.pl
            -install_directory $PERL5LIB -force

            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.
             
         7. Create Net::Netconf makefile.

            If installing Net::Netconf::Manager under the standard directory
            (it's normally /usr/local/lib):
            [/my/netconf-perl-n.n]% perl Makefile.PL

            If installing Net::Netconf::Manager under your own private
            directory:
            [/my/netconf-perl-n.n]% perl Makefile.PL LIB=$PERL5LIB
            INSTALLMAN3DIR=$PERL5LIB/../man/man3
             
         8. Install the Net::Netconf module.

            [/my/netconf-perl-n.n]% make
            [/my/netconf-perl-n.n]% make install
             

            Notes for private directory installation:

               * If you are installing the NETCONF modules in a private
                 directory, remember to set the PERL5LIB, MANPATH, and PATH
                 environment variables before installing the Perl modules and
                 running the examples. If the PERL5LIB variable is set, perl
                 will first look for Perl modules in the specified directory
                 before looking in the standard directory. (If you're using
                 sh, ksh or bash, use EXPORT instead of setenv.)

                 % setenv MANPATH "$MANPATH/:$PERL5LIB/../man"
                 % man Net::Netconf::Manager
                 % setenv PATH "$PATH/:$PERL5LIB/../bin"
                 % which xsltproc
                  
             Back to Top  

            Running the Sample Scripts

            The NETCONF Perl distribution includes sample scripts that
            demonstrate how to use NETCONF to retrieve and change the
            configuration of a Juniper Networks routing platform. The samples
            reside in the netconf-perl-n.n/examples directory.

            Reading configuration: Chassis Inventory
            This example sends a <get-chassis-information> request to the
            Juniper Networks routing platform and displays the result to the
            standard output. It uses XSLT to display the result in plain
            text. The purpose of this example is to show the power and
            flexibility of combining the NETCONF and XSLT.

              1. Change directory to examples/get_chassis_inventory.
                 [/my/netconf-perl-n.n]% cd examples/get_chassis_inventory
                  
              1. Run the script get_chassis_inventory.pl.
                 [/my/netconf-perl-n.n/examples/get_chassis_inventory]% perl
                 get_chassis_inventory.pl
                 [-d <level>]
                 [-o <outputfile>]
                 [-x <xslfile>]
                 [-m <access>]
                 [-l <login>]
                 [-p <password>]
                 <router>

            Example:
            [/my/netconf-perl-n.n/examples/get_chassis_inventory]% perl
            get_chassis_inventory.pl router11
            login: johndoe
            password:

            Where:
            -d <level>
            Optional. The default is debug level 4 (warning).

            -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.xsl is used by default.  If <outputfile> is
            specified, the transformation is put into <outputfile>. If
            <outputfile> is not specified, the result will be displayed on
            the standard output. 

            -m <access>
            Optional. The only supported value is ssh. It specifies which
            transport protocol to use to communicate with the Juniper
            Networks routing platforn.

            -l <login>
            -p <password>
            The login identity and password to use when accessing the Juniper
            Networks routing platform. The login identity must already exist
            in the router configuration and must have at least read privilege
            on the routing platform. (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 hostname or IP address of the routing platform.

            Changing configuration: Edit Configuration
            This example accepts an XML configuration to load. An example
            configuration to load is provided in config.xml. It is an XML
            file containing the RPC requests. You can put your own
            configuration file in the same directory and have
            edit_configuration load it in the target routing platform for
            you. The purpose of this example is to show you how simple it is
            to change your routing platform configuration using NETCONF. See
            the "NETCONF API Guide" for a detailed description of the syntax
            to use for the configuration data you are loading via NETCONF.

              1. Change directory to examples/edit_configuration
                 [/my/netconf-perl-n.n]% cd examples/edit_configuration
                  
              1. Run the edit_configuration.pl script
                 [/my/netconf-perl-n.n/examples/edit_configuration]% perl
                 edit_configuration.pl
                 [-d <level>]
                 [-m <access>]
                 [-l <login>]
                 [-p <password>]
                 <request>
                 <router>

            Example:
            [/my/netconf-perl-n.n/examples/edit_configuration]% perl
            edit_configuration.pl config.xml router11
            login: johndoe
            password:

            Where:
            -d <level>
            Optional. The default level is 4 (warning).

            -m <access>
            Optional. The only allowed value is ssh. It specifies which
            transport protocol to use to communicate with the Juniper
            Networks routing platform.

            -l <login>
            -p <password>
            The login identity and password to use when accessing the Juniper
            Networks routng platform. The login identity must already exist
            in the routing platform configuration and must have at least read
            privilege on the routing platform. (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 file included with the example is config.xml. 

            Example of configuration file content in xml format:

                  <configuration>
                      <system>
                          <host-name>foo</host-name>
                      </system>
                  </configuration>


 <router>
 The hostname or IP address of the routing platform.



 Router Diagnostics: Diagnose BGP
 This example retrieves the BGP summary from a Juniper Networks routing platform and displays key information on the unestablished
 peers. It shows how useful diagnostic tools can be written using NETCONF.



 You can render the output in plain text using XSLT. 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.


 * Change directory to examples/diagnose_bgp.
 [/my/netconf-perl-n.n]% cd examples/diagnose_bgp
  

 * Run the diagnose_bgp.pl script.
  [/my/netconf-perl-n.n/examples/diagnose_bgp]% perl diagnose_bgp.pl
                                                           [-d <level>]
                                                           [-m <access>]
                                                           [-l <login>]
                                                           [-p <password>]
                                                           -x <xslfile>
                                                           -o <outputfile>
                                                           <router>


 Example:

 [/my/netconf-perl-n.n/examples/diagnose_bgp]% perl diagnose_bgp.pl
                                                               -x xsl/bgp.xsl
                                                               -o router11.html
  login: johndoe
  password:



 Where:

 -d<level>
 Optional. The default is debug level 4 (warning).



 -m <access>
 Optional. The only allowed value is ssh.
 It specifies which transport protocol to use to communicate with the Juniper Networks routing platform.



 -l <login>
 -p <password>
 The login identity and password to use when accessing the Juniper Networks routing platform. The login identity must already exist in
 the routing platform configuration and must have at least read privilege on the routing platform. (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/bgp.xsl is used by default.  You can use this XSL file or create your own. 
 If <outputfile> is specified, the transformation is put into <outputfile>. If <outputfile> is not
 specified, the result will be displayed on the standard output. 



 <router>
 The hostname or IP address of the routing platform.



  Back to Top
  


 Installation of Perl Modules Required by Examples


 You can tell install-prereqs.pl to install only the modules required by Net::Netconf::Manager or by a specific example. By
 default install-prereqs.pl install all required modules for Net::Netconf::Manager, get_chassis_inventory.pl,
 edit_configuration.pl and diagnose_bgp.pl. This section shows you how to specify which set of modules to install.

        
 UNIX
        
 * Go to the netconf directory.
         % cd netconf-perl-n.n
  
        
 * Install the Perl modules required by the specific example. If you wish to install the
         required files in your private directory instead of the standard directory, you can use the -install_directory option
         to specify your private installation directory. The standard directory is the installation directory configured in
         the perl executable. 
         Installing modules under the standard directory (it's normally /usr/local/lib and you'll need root
         privilege):
 
         [/my/netconf-perl-n.n]% perl install-prereqs.pl
                                            -used_by <example>
                                            -force
        

         Installing modules under your own private directory
         (see notes below):
         [/my/netconf-perl-n.n]% setenv PERL5LIB /my/private/directory/lib
         [/my/netconf-perl-n.n]% perl install-prereqs.pl
                                        -used_by <example> 
                                        -install_directory $PERL5LIB\
                                        -force
        
        

         Where <example> is get_chassis_inventory, edit_configuration, diagnose_bgp, or Net::Netconf::Manager. If the
         -used_by option is not used, the default is to install all required modules. 

 
         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:


 * Remember to set the PERL5LIB environment variable before installing the Perl modules and running the examples.
 PERL5LIB is an environment variable, it can be set to a colon-separated list of directories. If set, perl will first look for
 Perl modules in the PERL5LIB directories before looking in the standard directory. The instruction above uses the csh syntax
 for setting environment variable. For sh, ksh and bash, use EXPORT PERL5LIB=/my/private/directory/lib.
  



  Back to Top
  


 Dependencies


 When you run the install script, you'll see the list of C libraries, executables, and Perl modules required by
 Net::Netconf::Manager and its examples. 

 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
  


 Support


 If you have problems with this Net::Netconf 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) 2005, Juniper Networks, Inc. All Rights Reserved.
