Chapter 2 - JUNOS UI Applications and Development Tools

UI Infrastructure Programmer's Guide

Chapter 2 - JUNOS UI Applications and Development Tools

2.1. JUNOS User Interfaces

Users manage and interact with JUNOS devices using 2 methods: the text-based JUNOS CLI or through an XML session (JUNOScript, jweb, JUNOScope, commit script, etc.).

2.1.1. JUNOS CLI

The JUNOS CLI is a text-based user interface. The CLI takes whatever the user enters and passes it to mgd. mgd responds and tells the CLI what to show the CLI user next. The actual parsing of commands, parsing of configuration statements, autocompletion and on-line help is all done by mgd based on the compiled DDL (schema.db). For instance, when the user types '?', the CLI asks mgd to provide help and the list of options available for the current command-line segment. mgd responds with a list of options that the CLI displays to the CLI user without question. Indeed, the brains of the JUNOS UI is mgd.

The only intelligent content processing the CLI does is the translation of the XML the CLI receives from mgd as a response to the CLI user excecuting an operational mode command. The system component handling the command responds with an XML document that mgd passes onto the CLI. The CLI renders this XML as user-friendly formatted text based on the format definition in ODL. The CLI is using a compiled version of the ODL specification at runtime to do this rendering.

Location of JUNOS UI Infrastrucutre items of interest on the JUNOS device itself:

    /usr/sbin/cli            - CLI application binary
    /usr/sbin/mgd            - mgd application binary
    /usr/lib/render          - location of compiled ODL CLI uses to format operational commmand ouput
    /usr/lib/dd              - location of compiled DDL mgd uses to build schema.db
    /var/run/db/schema.db    - schema mgd uses when parsing operational commands and configuration statements
    /var/run/db/juniper.db   - candidate database
    /var/run/db/juniper.data - committed database

When users first enter the JUNOS CLI, it is in the operational mode. Operational commands allow users to query the system for various runtime information.

Each operational command is entered on a single line, and pressing the Enter key executes the command. The CLI provides command help (when users type '?') and command completion (when users press the space, Tab, or Enter keys).

The operational mode can be recognized with the '> ' prompt, which is preceded by a string that defaults to the name of the user and the name of the JUNOS device.

Operational Mode prompt:

        user@host>

To switch from the operational mode to the configuration mode, users type 'configure' in the operational mode. In the configuration mode, system configuration can be entered and users need to enter 'commit' to realize all the changes.

The configuration mode can be recognized with the '[edit]...# ' prompt.

Configuration Mode prompt:

        [edit]
        user@host#

Detailed information on the JUNOS CLI can be found in the JUNOS CLI User Guide.

2.1.2. XML Sessions

For JUNOS users managing JUNOS devices utilizing a network management station, rather than logging onto the devices directly, the network management station establishes XML sessions directly to mgd on the JUNOS devices.

When a user sends a request to mgd in XML, mgd normalizes the XML request by looking up the UI schema, similar to processing a CLI request, and either sets the configuration or executes the operational command. The output, in XML form, will then be forwarded back to network management station for interpretation (instead of interpreted by the JUNOS CLI).

2.2. Testing New UI Commands

You can test new UI commands and DDL changes.

2.2.1. run-mgd-bsd and run-cli-bsd

In addition to building the whole JUNOS package and loading it on a real JUNOS device, there exist UI tools for testing new UI commands on the build machine,

/volume/buildtools/bin/run-mgd-bsd: runs mgd emulation in the freebsd environment
/volume/buildtools/bin/run-cli-bsd: starts the cli simulator in the freebsd environment

These are shell scripts that call a version of mgd and the CLI built to run on the build machine. The only requirement is that these scripts be invoked from a directory in the build environment because that is where the script will find:

• the mgd and CLI executables built for that build machine
• the -dd.so files compiled from the DDL you are working on; mgd needs these shared libraries in order to build schema.db
• the -render.so compiled from the ODL you are working on; the CLI needs these shared libraries in to know how to render the XML

jnx-exampled serves as an example JUNOS daemon. In the context of the JUNOS UI Infrastructure, it shows how a JUNOS daemon reads configuration with dax_ (schema specified with *.cnf.dd) and handles operational commands (commands specified with *.cmd.dd and output specified with *.odl). jnx-exampled cannot be compiled to run on the build machine; it requires the JUNOS operating system. It is part of the jexample package and is loaded onto a JUNOS device when jexample is installed on that device.

2.2.2. DDL Testing

To test DDL changes, the easiest way is to use 3 shells (make sure that $PATH contains /volume/buildtools/bin).

1. shell1 is used for compiling DDL input changes.

        user@freebsd:...src/junos/lib/ddl$ mk
        ===> compiler
        HOSTPROG=yes /volume/fwtools/bmake/20060511/bin/bmake -f Makefile all
        ===> feature
        ===> lib
        ===> access
        ===> bsd
        ===> ffp-actions
        ===> ffp-util
        ===> helpers
        ===> junos
        ===> util
        ===> junos-actions
        ===> memory
        ===> gram
        user@freebsd:...src/junos/lib/ddl$

2. Start mgd-bsd in shell2.

        freebsd$ run-mgd-bsd&
        [1] 61354
        user@freebsd:...src/junos$ Running  /tmp/run/8.1/test/mgd-bsd
        mgd: commit complete

3. Start cli-bsd in shell3.

        user@freebsd:...src/junos$ run-cli-bsd
        Running  /tmp/run/8.1/test/usr/sbin/cli

        user@freebsd> 

The '>' prompt shows that the user is in operational mode.

To enter configuration mode in the CLI:

        user@freebsd> configure
        Entering configuration mode

        [edit]
        user@freebsd#

In the configuration mode, the user prompt is preceded by the banner ([edit] line) and the prompt ends with '#'.

2.3. Hello World Example

The purpose of the example is to demonstrate how to:

• add configuration statements
• add operational commands
• use run-mgd-bsd and run-cli-bsd to prototype UI

We will create a top-level node 'newbie' in order to give us a playpen that is separate from other configuration nodes defined in JUNOS.

2.3.1. Adding Configuration Statement

In this section, the configuration statement 'jnx-example newbie hello' is added and it takes a string-type value.

        /*                                                               
           exampled.cnf.dd - example process configuration               
                                                                        
           March 2005                             
                                                                        
           Copyright (c) 2005-2006, Juniper Networks, Inc.               
           All rights reserved.                                          
                                                                         */

        #define DNAME_JNX_EXAMPLED "jnx-exampled"

        object jnx-example {
             help "Example service configuration";
             flag remove-empty;
             notify jnx-exampled;
             define DDLAID_JNX_EXAMPLE;
             require jnx-example;

            object newbie {
                help "Newbie section";

                attribute hello {
                    help "String value";
                    type string;
                }
            }
        }

Here in the jnx-exampled ddl input file (jnx-example.cnf.dd), the object 'newbie' is added, which contains a child attribute 'hello', which takes a string value.

At this point we must:

• compile the DDL (do 'mk' in .../src/junos/lib/ddl from shell1)
• restart mgd (do run-mgd-bsd& from shell2)

mgd at this point will build a new schema.db out of the DDL we compiled.

When we go to the CLI, it will ask you to reconnect since the mgd it was connected to was just killed. After reconnecting to the new mgd, we are ready to try out our hello attribute, which should be ready to take any string value, which may as well be "world."

        user@freebsd> configure
                Entering configuration mode

        [edit]
        user@freebsd# set ?
        ....
        newbie  Newbie section
        ....

        [edit]
        user@freebsd# set newbie ?
        Possible completions:
          <[Enter]>            Execute this command
          hello                String value
          |                    Pipe through a command
        [edit]
        user@freebsd# set newbie hello world

Committing the new configuration makes the configuration active. Now let's see what we have done:

        user@freebsd# show jnx-example
        newbie {
            hello world;
        }

        [edit]
        user@freebsd#

Newbie has said hello to the world!! Mission accomplished!!

If you wish to save your changes for a future CLI session, commit:

          [edit]
          user@freebsd# commit 
          commit complete

If you do not commit and try exiting configuration mode with uncommitted changes, you will be asked to state your intention:

          [edit]
          user@freebsd# set newbie hello universe

          [edit]
          user@freebsd# show
          version "8.1I0 [user]";
          newbie {
              hello universe;
          }

          [edit]
          user@freebsd# exit
          The configuration has been changed but not committed
          Exit with uncommitted changes? [yes,no] (yes) no

          Exit aborted

To see what you changed, pipe 'show' to 'compare':

          [edit]
          user@freebsd# show | compare 
          [edit newbie]
          -  hello world;
          +  hello universe;

You can roll back to go to previous version:

          [edit]
          user@freebsd# rollback

          user@freebsd# show
          version "8.1I0 [user]";
          newbie {
              hello world;
          }

          [edit]
          user@freebsd# exit

          user@freebsd>

2.3.2 ODL Testing

Getting format statements in ODL right the first time is difficult. Indeed, usually a few iterations are necessary for those new to ODL. You can use run-mgd-bsd and run-cli-bsd to test out ODL.

First, construct the XML output:

        freebsd$ cat > tmp/sh_ver.tst
        <rpc-reply xmlns:junos="http://xml.juniper.net/junos/8.2I0/junos">
            <software-information>
                <host-name>freebsd</host-name>
                <product-name>unittest</product-name>
            </software-information>
            <cli>
                <banner></banner>
            </cli>
        </rpc-reply>
        
        freebsd$

Then use 'file render' on run-cli-bsd to view the CLI output:

        user@freebsd> file render tmp/sh_ver.tst
        Hostname: freebsd
        Model: unittest

---