Submit a Request to the NETCONF Server in Perl Client Applications

All operational commands that have Junos XML counterparts are listed in the Junos XML API Operational Developer Reference. You can also display the Junos XML request tag elements for any operational mode command that has a Junos XML counterpart on the CLI. Once you obtain the request tag, you can map it to the corresponding Perl method name.

To display the Junos XML request tags for a command in the CLI, include the | display xml rpc option after the command. The following example displays the request tag for the show route command:

user@host> show route | display xml rpc 
<rpc-reply xmlns:junos="http://xml.juniper.net/junos/15.1R1/junos">
    <rpc>
        <get-route-information>
        </get-route-information>
    </rpc>
</rpc-reply>

You can map the request tag for an operational command to a Perl method name. To derive the method name, replace any hyphens in the request tag with underscores, and remove the enclosing angle brackets. For example, the <get-route-information> request tag maps to the get_route_information method name.

Similarly, NETCONF protocol operations map to Perl method names in the same manner. For example, the <edit-config> operation maps to the edit_config method name.

Perl methods can have one or more options. The following section describes the notation that an application uses to define a method’s options in a NETCONF Perl client application.

• A method without options is defined as $NO_ARGS, as in the following entry for the get_autoinstallation_status_information method:

  content_copy zoom_out_map

  ## Method : get_autoinstallation_status_information
  ## Returns: <autoinstallation-status-information>
  ## Command: "show system autoinstallation status"
  get_autoinstallation_status_information => $NO_ARGS,

  To invoke a method without options, the client application follows the method name with an empty set of parentheses, as in the following example:

  content_copy zoom_out_map

  $jnx->get_autoinstallation_status_information();

• A fixed-form option is defined as type $TOGGLE. In the following example, the get_ancp_neighbor_information method has two fixed-form options, brief and detail:

  content_copy zoom_out_map

  ## Method : get_ancp_neighbor_information
  ## Returns: <ancp-neighbor-information>
  ## Command: "show ancp neighbor"
  get_ancp_neighbor_information => {
      brief => $TOGGLE,
      detail => $TOGGLE,
  }

  To include a fixed-form option when invoking a method, set the option equal to the string 'True', as in the following example:

  content_copy zoom_out_map

  $jnx->get_ancp_neighbor_information(brief => 'True');

  Note:

  When using the release-dependent NETCONF Perl distribution, to include a fixed-form option when invoking a method, set the option equal to the value 1 (one).

• An option with a variable value is defined as type $STRING. In the following example, the get_cos_drop_profile_information method takes the profile_name argument:

  content_copy zoom_out_map

  ## Method : get_cos_drop_profile_information
  ## Returns: <cos-drop-profile-information>
  ## Command: "show class-of-service drop-profile"
  get_cos_drop_profile_information => {
      profile_name => $STRING,
  },

  To include a variable value when invoking a method, enclose the value in single quotes, as in the following example:

  content_copy zoom_out_map

  $jnx->get_cos_drop_profile_information(profile_name => 'user-drop-profile');

• A set of configuration statements or corresponding tag elements is defined as type $DOM. In the following example, the get_config method takes a set of configuration statements (along with two attributes):

  content_copy zoom_out_map

  'get_config' => {
       'source' => $DOM_STRING,
       'source_url' => $URL_STRING,
       'filter' => $DOM
  },

  A DOM object is XML code:

  content_copy zoom_out_map

  my $xml_string = "
  <filter type=\"subtree\">
  <configuration>
    <protocols>
      <bgp></bgp>
    </protocols>
  </configuration>
  </filter>
  "; 
  
  my %queryargs = (
     'source' => "running",
     'filter' => $xml_string,
  );

  This generates the following RPC request:

  content_copy zoom_out_map

  <rpc message-id='1'> 
  <get-config> 
     <source> <running/> </source>
     <filter type="subtree">
        <configuration>
           <protocols>
              <bgp></bgp>
           </protocols>
        </configuration>
     </filter>
  </get-config>
  </rpc>

A method can have a combination of fixed-form options, options with variable values, and a set of configuration statements. For example, the get_forwarding_table_information method has four fixed-form options and five options with variable values:

## Method : get_forwarding_table_information
## Returns: <forwarding-table-information>
## Command: "show route forwarding-table"
get_forwarding_table_information => {
    detail => $TOGGLE,
    extensive => $TOGGLE,
    multicast => $TOGGLE,
    family => $STRING,
    vpn => $STRING,
    summary => $TOGGLE,
    matching => $STRING,
    destination => $STRING,
    label => $STRING,
},

The following code illustrates the recommended way to send a configuration request to the NETCONF server and shows how to handle error conditions. The $jnx variable is defined to be a NET::Netconf::Manager object. The sample code, which is taken from the edit_configuration.pl sample script, locks the candidate configuration, loads the configuration changes, commits the changes, and then unlocks the configuration database and disconnects from the NETCONF server. You can view the complete edit_configuration.pl script in the examples/edit_configuration directory in the NETCONF Perl GitHub repository at https://github.com/Juniper/netconf-perl.

my $res; # Netconf server response

# connect to the Netconf server
my $jnx = new Net::Netconf::Manager(%deviceinfo);
unless (ref $jnx) {
    croak "ERROR: $deviceinfo{hostname}: failed to connect.\n";
}

# Lock the configuration database before making any changes
print "Locking configuration database ...\n";
my %queryargs = ( 'target' => 'candidate' );
$res = $jnx->lock_config(%queryargs);

# See if you got an error
if ($jnx->has_error) {
    print "ERROR: in processing request \n $jnx->{'request'} \n";
    graceful_shutdown($jnx, STATE_CONNECTED, REPORT_FAILURE);
}

# Load the configuration from the given XML file
print "Loading configuration from $xmlfile \n";
if (! -f $xmlfile) {
    print "ERROR: Cannot load configuration in $xmlfile\n";
    graceful_shutdown($jnx, STATE_LOCKED, REPORT_FAILURE);    
}

# Read in the XML file
my $config = read_xml_file($xmlfile);
print "\n\n$config \n\n";

%queryargs = ( 
        'target' => 'candidate'
     );

# If we are in text mode, use config-text arg with wrapped
# configuration-text, otherwise use config arg with raw
# XML
if ($opt{t}) {
  $queryargs{'config-text'} = '<configuration-text>' . $config
    . '</configuration-text>';
} else {
  $queryargs{'config'} = $config;
}

$res = $jnx->edit_config(%queryargs);

# See if you got an error
if ($jnx->has_error) {
    print "ERROR: in processing request \n $jnx->{'request'} \n";
    # Get the error
    my $error = $jnx->get_first_error();
    get_error_info(%$error);
    # Disconnect
    graceful_shutdown($jnx, STATE_LOCKED, REPORT_FAILURE);
}

# Commit the changes
print "Committing the <edit-config> changes ...\n";
$jnx->commit();
if ($jnx->has_error) {
    print "ERROR: Failed to commit the configuration.\n";
    graceful_shutdown($jnx, STATE_CONFIG_LOADED, REPORT_FAILURE);
}

# Unlock the configuration database and 
# disconnect from the Netconf server
print "Disconnecting from the Netconf server ...\n";
graceful_shutdown($jnx, STATE_LOCKED, REPORT_SUCCESS);