1.1 

Getting JUISE

JUISE is available as an open-source project via google code using the following URL:

http://juise.googlecode.com

Refer to the ./README file for building instructions.

Note that juise has a number of prerequisite software packages, including libxslt, libxml2, libpcre, libslax, and others.

2.1 

Syntax

The juise command line interface is as follows:

  Usage: juise [[user]@target] [options] [script] [param value]*
            

The juise command is normally invoked with the name of the script to be run, a set of options are used to tailor the execution of the script, and a set of name/value parameter pairs that are passed as parameters to the script, as they are for the JUNOS "op" command.

Section Contents:

• Section 2.1.1

    juise my-login@my-router ...
    juise @my-router ...
            

3.1 

Overview (Function and History)

Commit scripts were introduced in JUNOS-7.2 as a means of adding custom rules to the "commit check" process, allowing customers to define additional validation rules which the incoming configuration must satisfy. Commit scripts can find and report configuration statements that do not follow these rules.

Commit script can also change the configuration in two distinct ways. Normal changes are added to the candidate configuration before it is passed to the rest of the JUNOS subcomponents for validation. These changes are normal parts of the configuration data set.

In contrast, transient changes are not part of the normal configuration data set, since they are not visible in the candidate configuration nor are they saved in rollback data sets. But they are exposed to JUNOS subcomponents during validation, allowing the commit script to create second order configuration information based on the first order data in the candidate configuration.

The typical commit script relies heavily upon XPath to find errant configuration. They typically follow the pattern:

    if (xpath/to/find/bad/config) {
        report bad config;
    }
            

or:

    for-each (some/list/that/needs/to/be/checked) {
        if (xpath/to/find/bad/config) {
            report bad config;
        }
    }
            

Consider this example:

    version 1.1;

    import "../import/junos.xsl";

    match configuration {
        var $ldp = protocols/ldp;
        var $isis = protocols/isis;
        var $ospf = protocols/ospf;

        for-each ($isis/interface/name | $ospf/area/interface/name) {
            var $ifname = .;

            if (not($ldp/interface[name == $ifname])) {
                <xnm:error> {
                    call jcs:edit-path();
                    call jcs:statement();
                    <message> "ldp not enabled for this interface";
                }
            }
        }
    }
            

This script looks for interfaces listed under [protocols isis] and [protocols ospf] to find interfaces not listed under [protocols ldp]. When such interfaces are found, an error is generated. The UI sees this error and stops the configuration from being validated.

3.2 

Testing Commit Scripts

juise can be used to test commit scripts by using the "‑c" option. The target device can be given with either the --target (-T) option. If no target is given and the first argument contains an '@', then this is used as the target.

    % juise -c me@my-router my-script.slax
            

To execute the commit script, juise tries to reproduce the environment which the script would run under JUNOS. juise starts by downloading the configuration in the same format used by on-box commit scripts, with expanded inheritance and group and change attributes. This configuration is wrapped in an input document (the <op‑script‑input> element) to be passed to the script. The wrapper is identical to the JUNOS wrapper, complete with the <junos‑context> element.

The <op‑script‑input> element is passed as input to the script, which runs normally, inspecting the configuration and generating, <xnm:error>, <xnm:warning>, <syslog>, <change>, and <transient> elements as needed.

The results of the script are inspected, and any <change> and <transient> elements are uploaded to a "edit private" session. Any errors are reported to the user.

The results of these interactions with the device are displayed in XML to aid with debugging scripts.

If no errors have occurred, then any changes to the configuration can be retrieved and reported to the user, who can verify that the changes are those desired. Use the "--output-format <style>" option to retrieve the results in any of the following formats:

    % cat fix-domain.slax
    version 1.1;

    import "../import/junos.xsl";

    match configuration {
        <change> {
            <system> {
                <domain-name> "new.example.com";
            }
        }
    }
    % juise -c --output-format compare @dent fix-domain.slax

    Results from edit private:
    <xnm:warning>
    <message>
    uncommitted changes will be discarded on exit
    </message>
    </xnm:warning>

    Results from load change:
    <load-configuration-results>
    <load-success/>
    </load-configuration-results>

    Results from load change:
    <load-configuration-results>
    <load-success/>
    </load-configuration-results>

    Results from commit check:
    <commit-results>
    <load-success/>
    <routing-engine junos:style="normal">
    <name>re0</name>
    <commit-check-success/>
    </routing-engine>
    </commit-results>

    Results from script:
    <configuration-information>
    <configuration-output>
    [edit system]
    -  domain-name juniper.net;
    +  domain-name new.example.com;
    </configuration-output>
    </configuration-information>
            

3.3 

Debugging Commit Scripts

The libslax debugger (sdb) can be used to debug commit scripts. Use the "‑d" option to trigger the debugger.

    % juise -d -c me@my-router my-script.slax
    sdb: The SLAX Debugger (version 0.12.2)
    Type 'help' for help
    (sdb) help
    List of commands:
      break [loc]     Add a breakpoint at [file:]line or template
      callflow [val]  Enable call flow tracing
      continue [loc]  Continue running the script
      delete [num]    Delete all (or one) breakpoints
      finish          Finish the current template
      help            Show this help message
      info            Showing info about the script being debugged
      list [loc]      List contents of the current script
      next            Execute the next instruction, stepping over
      over            Execute the current instruction hierarchy
      print <xpath>   Print the value of an XPath expression
      profile [val]   Turn profiler on or off
      reload          Reload the script contents
      run             Restart the script
      step            Execute the next instruction, stepping into
      verbose         Turn on verbose (-v) output logging
      where           Show the backtrace of template calls
      quit            Quit debugger

    Command name abbreviations are allowed
    (sdb) 
            

4.1 

Overview (Function and History)

Op scripts were introduced in JUNOS-7.5 as a means of adding custom commands to the JUNOS CLI.

Op scripts are not passed a normal document as input. An <op‑script‑input> element is passed in which contains the <junos‑context> similar to operation of op scripts in JUNOS.

Command line parameters (if any) are passed as SLAX parameters. They are also recorded under the <arguments> element inside the <junos‑context>.

Op scripts can generate output using the "message" statements and "jcs:output" calls, as well as by the XML document which the script generates. The XML document is displayed only when script execution is complete.

4.2 

Running Op Scripts

The juise command can be used to execute op scripts:

    juise [options] [[user]@target] script-name [name value]*
            

The arguments to an op script are a name and a value, similar to the "op" command under JUNOS:

    op script-name [name value]*
            

The name is arbitrary but should correspond to global parameters declared inside the script using the "param" statement.

    juise @my-box my-script address 10.1.2.3 vlan fluffy
            

The script is run on the local machine, with jcs:open() able to connect to the device, and output is displayed on the user's terminal.

To invoke the debugger on a script, use the "‑d" option:

    juise -d @my-box my-script address 10.1.2.3 vlan fluffy
            

4.3 

Running Native Scripts

juise can also be used to develop scripts that are not intended to run under JUNOS. The off-box environment gives a number of distinct advantages for scripts that operate like "op" scripts. These scripts join the simplicity and flexibility of SLAX to the unix environment.

Section Contents:

• Section 4.3.1

    #!/usr/local/bin/slax
    match / { message "this works"; }
            

    % works
    this works
    %
            

    #!/usr/bin/slax -g --param check yes
            

6.1 

xml-mode

The alternative means of running NETCONF is to use the "xml‑mode" command over a normal ssh connection. This is non-standard, but allows the deploying of NETCONF with no configuration and much less impact.

juise will make a symbolic link from "juise" to "xml‑mode", so a client can open a normal ssh command with the "xml‑mode" command and get a NETCONF connection. We refer to this a "junos‑netconf" and the juise client supports it via the "‑P" option and the "junos‑netconf" <protocol> option for jcs:open().

6.2 

RPCs

juise puts few limit limitations on the RPCs invoked on the server. The RPC method name is used to locate a local script or binary which implements that RPC. The script or binary is executed with the RPC content as standard input, and any output from the script is passed back to the client.

The JUISE_SCRIPT_DIR environment variable and the "‑D" option are used to provide a set of search directories. The default path is the directory $prefix/share/juise/scripts/, or the value given for --with-script-dir=DIR to the "configure" script at build time.

For each directory in the search path, juise looks for a file with the name of the RPC method and a suitable extension. The list of extensions is "slax", "xsl", "xslt", "sh", "pl", and "" (none).

For example if a client sends an RPC like:

    <rpc>
        <get-some-information>
            <type>fish</type>
            <option>end-run</option>
        </get-some-information>
    </rpc>
            

The juise NETCONF server will look in for "get‑some‑information.slax" in $prefix/share/juise/scripts/ and will load and run that script.

In the following example, the "test.slax" script is accessed using the "test" RPC via the "xml‑mode" command.

    % cat /usr/local/share/juise/scripts/test.slax
    version 1.1;
    match / {
        <chassis-hardware> {
            <mumble> {
                <dink>;
            }
            <grumble> {
                <splat>;
            }
        }
    }
    % cat /tmp/foo.netconf
    <hello/>]]>]]>
    <rpc>
      <test/>
    </rpc>]]>]]>
    % ssh localhost xml-mode < /tmp/foo.netconf
    <?xml version="1.0"?>
    <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <capabilities>
    <capability>urn:ietf:params:netconf:base:1.0</capability>
    </capabilities></hello>]]>]]>
    <rpc-reply>
    <?xml version="1.0"?>
    <chassis-hardware>
    <mumble><dink/></mumble><grumble><splat/></grumble>
    </chassis-hardware>
    </rpc-reply>]]>]]>
    %
            

7.1 

"juise" Command Line Options

This section provides a complete listing of available juise options.

--agent OR -A

Enable forwarding of ssh-agent credentials, allowing remote ssh sessions to connect to the local ssh-agent process for authentication information. See "man ssh-agent(1)" for details.

--debug OR -d Start the libslax debugger, allowing the user to

interactively debug script execution. Refer to the debugger documentation in the libslax distribution for more information (libslax.googlecode.com).

--directory <dir> OR -D <dir>

Use the given directory as the location for server scripts. This directory can also be set using the JUISE_SCRIPT_DIR environment variable.

--include <dir> OR -I <dir>

Add the given directory to the search path for files that are referenced via the SLAX "include" or "import" statements.

--indent OR -g

Make indented output as if the script contained:

    output-method {
        indent "yes";
    }
            

(The "‑g" is for "good-looking output").

--input <file> OR -i <file>

Use given file for input.

--junoscript OR -J

Default to using the older JUNOScript XML API instead of the NETCONF API for jcs:open() connections.

--lib <dir> OR -L <dir>

Add the given directory to the list of directories searched for dynamic extension libraries. Refer to libslax for more information.

--no-randomize

Avoid initializing the random number generator so script execution can be predictable (e.g. during debugging).

--param <name> <value> OR -a <name> <value>

An alternative method of giving parameters to a script.

--protocol <name> OR -P <name>

Use the given protocol as the default protocol for jcs:open() connections.

--run-server OR -R

Run juise in server mode, where it accepts incoming RPCs and executes scripts given by the RPC name. See Section 6 section for details.

--script <name> OR -S <name>

An alternative method of giving the script name.

--target <name> OR -T <name>

An alternative method of giving the default target name.

--trace <file> OR -t <file>

Save trace data to the given file.

--user <name> OR -u <name>

An alternative method of giving the user name for API connections.

--verbose OR -v

Enable debugging output. Any calls to slaxLog() will be displayed.

--version OR -V

Display any version information, including the versions of libslax, libxslt, and libxml2. After displaying this information, juise will exit.

--wait <seconds>

After starting and parsing arguments, juise will wait for the specified number of seconds, allowing the user to attach to the process with "gdb" for additional debugging.

7.2 

Environment Variables and configure.ac Settings

The values of certain environment variables and the command line arguments to the "configure" script will affect the operation of JUISE. This section details these settings.

Section Contents:

• Section 7.2.1

    import "../import/junos.xsl";
            

7.3 

Finding Scripts

If a valid filename is not passed to juise, it will look in $prefix/share/juise/scripts/ for scripts.

8.1 

juise.cgi

When a file ending in ".slax" is requested, lighttpd will pass the request to mod_juise which will invoke juise using the "juise.cgi" driver. This driver will fetch the CGI-defined variables and make them available to the script as both global parameters and as elements inside the "$cgi" global parameter. Scripts are free to use either method to retrieve these values. The following table list the CGI parameter name and the $cgi element name.

The following lines are functionally equivalent:

    expr "User is " _ $REMOTE_USER;
    expr "User is " _ $cgi/remote-user;
            

In addition $cgi has an element named "parameters" which has the fields of $QUERY_STRING broken into individual elements. These are also available as global parameters. The following lines are functionally equivalent:

    expr "'from' parameter is " _ $cgi/parameters/from;
    expr "'from' parameter is " _ $from;
            

The full set of parameters can be accessed using this parameters element:

    for-each ($cgi/parameters) {
        expr "Parameter '" _ name() _ "' is '" _ . _ "'";
    }
            

8.2 

The <cgi> Element

When SLAX scripts are invoked via mod_juise, the script can choose to emit a top level element named <cgi>. This element is used to supply directions to the HTTP server.

8.3 

Attributes

Any non-namespace attributes given on the <cgi> element is converted into a header field in the HTTP reply message. The attribute name is the header field and the attribute value is the header value.

    <cgi Content-Type="text/html" X-Address=$REMOTE_ADDR>
        ...
    </cgi>
            

The above element would be turned into:

    Content-Type: text/html
    X-Address: 10.1.2.3
            

Additional attributes and elements may be defined under the <cgi> element. For future proofing, script should avoid attributes and elements whose names being with "junos", "cgi", or "juise".

11.1 

jcs

The "jcs" namespace is used for JUNOS-specific extension function, but many of the functions are no longer JUNOS specific. "jcs" was originally for "JUNOS Commit Scripts", but these functions can be used for other sorts of scripting as well.

In addition, many of the extension functions in the "slax" namespace were originally in the "jcs" namespace, and are now available in both namespaces. The following table lists these dual-homed functions.

Section Contents:

• Section 11.1.1
• Section 11.1.2
• Section 11.1.3
• Section 11.1.4

    SYNTAX::
        node-set jcs:open();
        node-set jcs:open(hostname);
        node-set jcs:open(hostname, info);
        node-set jcs:open(hostname, username, password);

    EXAMPLE::
        var $info = {
            <port> 5000;
            <timeout> 600;
        }
        var $conn = jcs:open($target, $info);
            

    SYNTAX::
        node-set jcs:execute(conn, method);
        node-set jcs:execute(conn, rpc);

    EXAMPLE::
        var $rpc = <get-interface-information> {
            <interface-name> "fe-0/0/0";
            <statistics>;
        }
        var $res = jcs:execute($conn, $rpc);
        var $sw = jcs:execute($conn, "get-software-information");
            

    SYNTAX::
        node-set jcs:invoke(method);
        node-set jcs:invoke(rpc);

    EXAMPLE::
        var $rpc = <get-interface-information> {
            <interface-name> "fe-0/0/0";
            <statistics>;
        }
        var $res = jcs:invoke($rpc);
        var $sw = jcs:invoke("get-software-information");
            

    SYNTAX::
        void jcs:close(conn);