Connect to the Junos XML Protocol Server Using Perl Client Applications
The following sections explain how to use the JUNOS::Device
object in a Perl client application to
connect to the Junos XML protocol server on a device running Junos
OS:
Satisfying Protocol Prerequisites
The Junos XML protocol server supports several access protocols. For each connection to the Junos XML protocol server on a device running Junos OS, the application must specify the protocol it is using. Using SSH or Secure Sockets Layer (SSL) is recommended because they provide greater security by encrypting all information before transmission across the network.
Before your application can run, you must satisfy the prerequisites for the access protocol it uses. For some protocols this involves activating configuration statements on the device, creating encryption keys, or installing additional software on the device running Junos OS or the machine where the application runs. For instructions, see Satisfying the Prerequisites for Establishing a Connection to the Junos XML Protocol Server.
Grouping Requests
Establishing a connection to the Junos XML protocol server on
a device running Junos OS is one of the more time-intensive and resource-intensive
functions performed by an application. If the application sends multiple
requests to a routing platform, it makes sense to send all of them
within the context of one connection. If your application sends the
same requests to multiple devices, you can structure the script to
iterate through either the set of devices or the set of requests.
Keep in mind, however, that your application can effectively send
only one request to one Junos XML protocol server at a time. This
is because the JUNOS::Device
object does
not return control to the application until it receives the closing </rpc-reply>
tag that represents the end of the
Junos XML protocol server’s response to the current request.
Obtaining and Recording Parameters Required by the JUNOS::Device Object
The JUNOS::Device
object takes
the following parameters, specified as keys in a Perl hash:
access
—(Required) The access protocol to use when communicating with the Junos XML protocol server. Acceptable values are "telnet", "ssh", "clear-text", and "ssl". Before the application runs, satisfy any protocol-specific prerequisites.hostname
—(Required) The name of the device to which to connect. For best results, specify either a fully qualified hostname or an IP address.login
—(Required) The username under which to establish the connection to the Junos XML protocol server and issue requests. The username must already exist on the specified device and have the permission bits necessary for making the requests invoked by the application.password
—(Required) The password corresponding to the username.junos_key
—(Optional) When requesting configuration data using the get_configuration() method, set the value of the parameter to 1 to include thejunos:key="key"
attribute in the output of XML-formatted configuration data. The default value of the parameter is 0. Thejunos:key="key"
attribute indicates that a child configuration tag element is the identifier for its parent tag element. The attribute does not appear in formatted ASCII output.
The sample scripts record the parameters in a Perl hash
called %deviceinfo
, declared as follows:
my %deviceinfo = ( access => $access, login => $login, password => $password, hostname => $hostname, junos_key => $junos_key, );
The sample scripts included in the Junos XML Protocol Perl client distribution obtain the parameters from options entered on the command line by a user. For more information about collecting parameter values interactively, see Collecting Parameters Interactively in Junos XML Protocol Perl Client Applications. Your application can also obtain values for the parameters from a file or database, or you can hardcode one or more of the parameters into the application code if they are constant.
Obtaining Application-Specific Parameters
In addition to the parameters required by the JUNOS::Device
object, applications might need to define other parameters, such
as the name of the file to which to write the data returned by the
Junos XML protocol server in response to a request, or the name of
the Extensible Stylesheet Transformation Language (XSLT) file to use
for transforming the data.
As with the parameters required by the JUNOS::Device
object, the client application can hardcode the values in the application
code, obtain them from a file, or obtain them interactively. The sample
scripts obtain values for these parameters from command-line options
in the same manner as they obtain the parameters required by the JUNOS::Device
object (discussed in Obtaining and Recording Parameters Required by the JUNOS::Device Object). Several examples follow.
The following line enables a debugging trace if the user
includes the -d
command-line option. It invokes the JUNOS::Trace::init
routine defined in the JUNOS::Trace
module, which is imported with the JUNOS::Device
object.
JUNOS::Trace::init(1) if $opt{d};
The following line sets the $outputfile
variable to the value specified by the -o
command-line
option. It names the local file to which the Junos XML protocol server’s
response is written. If the -o
option is not provided,
the variable is set to the empty string.
my $outputfile = $opt{o} || " " ;
The following code from the diagnose_bgp.pl script defines which XSLT file to use to transform the Junos XML
protocol server’s response. The first line sets the $xslfile
variable to the value specified by the -x
command-line option. If the option is not provided, the
script uses the text.xsl file supplied
with the script, which transforms the data to ASCII text. The if
statement verifies that the specified XSLT file exists;
the script terminates if it does not.
# Retrieve the XSLT file, default is parsed by perl my $xslfile = $opt{x} || "xsl/text.xsl"; if ($xslfile && ! -f $xslfile) { die "ERROR: XSLT file $xslfile does not exist"; }
The following code from the load_configuration.pl script defines whether to merge, replace, update, or overwrite the
new configuration data into the configuration database. The first
two lines set the $load_action
variable
to the value of the -a
command-line option, or to the default
value merge
if the option is not provided.
If the specified value does not match one of the valid actions defined
by the VALID_ACTIONS
constant, the script
invokes the output_usage
subroutine to
print the usage message.
# The default action for load_configuration is 'merge' my $load_action = "merge"; $load_action = $opt{a} if $opt{a}; use constant VALID_ACTIONS => "merge|replace|override"; output_usage() unless (VALID_ACTIONS =~ /$load_action/);
Establishing the Connection
After obtaining values for the parameters required for
the JUNOS::Device
object, each sample script
records them in the %deviceinfo
hash.
my %deviceinfo = ( access => $access, login => $login, password => $password, hostname => $hostname, junos_key => $junos_key, );
The script then invokes the Junos XML protocol-specific new
subroutine to create a JUNOS::Device
object and establish a connection to the specified routing, switching,
or security platform. If the connection attempt fails (as tested by
the ref
operator), the script exits.
my $jnx = new JUNOS::Device(%deviceinfo); unless ( ref $jnx ) { die "ERROR: $deviceinfo{hostname}: failed to connect.\n";