Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation
Guide That Contains This Content
[+] Expand All
[-] Collapse All

    Quick Start Guide: JunosV App Engine

    This Quick Start Guide will guide you through the development of an application built using remote APIs and deployment of the application on the JunosV App Engine platform. This document offers you step-by-step instruction on how to create your own application development environment; build and package an application; install the application on a Juniper Networks M Series, MX Series, or T Series router; and deploy the application in a virtual machine (VM) on the VSE device.

    Before You Begin…

    In order to install and use the JunosV App Engine platform, please make sure you have the following items:

    1. Hardware and Software Platform Components: To deploy a remote application—an application written using the JunosV App Engine development environment—you must first set up the JunosV App Engine platform. You will need the following hardware and software platform components.

      • Device running Junos: For the 12.3R1 release this is an M Series, an MX Series, or a T Series router.
      • VSE device: This could be either a VSE1100 or VSE 2100 device.
      • DHCP server: A dedicated DHCP server is optional—you can also use a Junos router as the DHCP server.
      • Console server: This device is optional and used mainly for debugging purposes.
      • (Not required for Section I ) A development system running Linux CentOS 6.2 (this is the supported guest operating system [OS] for JunosV App Engine 12.3 release): The development system is required if you are developing your own application.

        The machine must have a later model, 64-bit processor that is capable of full hardware virtualization. To check whether your processor is compatible, follow the instructions in the KVM HowTo, located on the CentOS website. You can also use .iso images to install CentOS and the necessary packages.

    2. Software Packages: You also need access to the following software ready to install:

      • Junos OS: jinstall-release-version.tgz
      • JunosV App Engine Host Base OS: jvae-release-version.tgz
      • Remote application development and packaging tools: junos-sdk-remote-devtools-release-version.tgz, which contains the JDAF library, the JSDL compiler, example client-and-server code (this package also downloads protobuf compilers)

        You will install the remote development tools on your machine to create the App Engine development system.

      • Deployment VM, also known as the sample guest OS VM (sample Linux VM), to be used to deploy applications and create final .img files
      • Sample guest OS packaged with the sample remote-helloworld application, and required for Section 1 of this guide
      When you download the packages, verify that the MD5 and SHA1 checksums of the downloaded files match those of the corresponding files on the developer website.
    3. Development Certificate: The development certificate is not required for Section I. If you have not already received a development certificate, please contact JunosV App Engine development support team at sdk-cert@juniper.net. You will need the certificate when you begin packaging your custom application.

    The document is divided into two sections. Section I guides you through the deployment of a sample application that has already been developed, built, and packaged for you. If this is your first interaction with JunosV App Engine, it is highly recommended that you read and follow the instructions in this section. By the end of it, you will have your first remote application running on the JunosV App Engine.

    Section II shows you the steps on how to create your own custom remote application that influences network behavior. Please follow this section step by step. By the end of this section, you will have developed your own custom remote application and deployed it on JunosV App Engine.

    To understand the architecture, go through the detailed online documentation Login required.

    Section I: Deploying a Sample Application

    This section is recommended for all first-time users of JunosV App Engine. Once you complete the steps in this section, you will have a sample application deployed and running on the JunosV App Engine platform. In order to install and use the application, you must have in place the required hardware and have downloaded the required software packages. Refer to the section Before You Begin… if you have not already done so.

    Note: The sample application is already packaged in the sample guest OS, so you do not need to download it separately.

    To deploy the sample application:

    1. Connect the router running Junos OS and the VSE device:

      1. Choose any one of the VSE device interfaces as the management interface. Make sure there is a physical or Layer 2 connection from this interface to the router.
      2. (Optional, but required for remote power cycling). Connect the console port on the left side of the VSE device to a console server.
      3. Write down the MAC address of the interface you have connected the router to.

        The MAC address of the management interface is required for completing installation section detailed below. When the appliance powers on and attempts to PXE boot, MAC addresses of onboard interfaces are displayed. Eventually there will be labels on the back of the VSE device.

    2. Configure the TFTP server and the DHCP server for PXE boot.

      BIOS is enabled for PXE boot at the time of manufacture for all VSE device interfaces. For how to enable PXE boot of the VSE device, see the configuration topic “Configuring the DHCP Server and TFTP Server for Compute Nodes” in the JunosV App Engine Administration Guide. PDF Document

      Note: If TFTP is configured before the app-engine statement, an error message is displayed. This is incorrect behavior and will be fixed. [PR 808652]

    3. Authorize the sample application on the router and VSE device.

      As the operator, you will need to authorize installation of the application package on your router and VSE device.

      1. Go to the configuration mode of Junos CLI and then go to the [edit system extensions] hierarchy level.
      2. Configure and commit the provider name, the license type, and the deployment scope associated with the application package. This information is supplied by the application package provider.
        [edit system extensions] user@router# set providers name license-type license deployment-scope deployment

        For example, to install the sample application provided as part of this exercise, configure and commit the following authorization settings:

        [edit system extensions] user@router# set providers juniper license-type juniper deployment-scope commercial

        If you do not authorize the application in this way, you will get this error message:

        ERROR: validate-config: Packages from juniper are not allowed WARNING: Current configuration not compatible with /var/tmp/package-name
    4. Install the software packages on the router and VSE device.

      This step entails installing the Junos OS, JunosV App Engine Host Base OS, and the sample application packages. Exit to the operational mode of the CLI to issue the following commands.

      1. Install the Junos OS package on the router:
        user@router> request system software add jinstall-release-version.tgz
      2. Install the JunosV App Engine Host Base OS package on the router:
        user@router> request system software add jvae-release-version.tgz

        This software contains the boot file and the boot server. This information is deployed from the router tethered to the VSE device.

      3. Install the sample application package on the router:
        user@router> request system software add sample-jvae-app-bundle-release-version.tgz

        This software is deployed on top of JunosV App Engine platform as a guest VM.

    5. Configure the platform layer.
      1. Configure the physical connection between the router running Junos OS and the VSE device. You do this at the [edit services app-engine compute-cluster] hierarchy level. For details on options, see the “compute-cluster (App Engine)” configuration statement section in the JunosV App Engine Administration Guide PDF Document. Links to child configuration statements are provided in the Syntax section of the configuration statement sections.

        Here is an example of the configuration you must set:

        [edit services app-engine]user@router# showcompute-cluster cc1 {local-management {family inet {address 199.99.99.20; # The IP address of the interface on the router # tethered to the VSE device}}compute-node cn1 {mac-address 00:e0:81:cb:bc:57;interfaces {bridge br0 {management;family inet {address 199.99.99.11/24; #You can ssh to this address or use the # console to monitor the VSE device}interface eth0;}}}}

        The IP address under the [edit services app-engine compute-cluster ccl local-management family inet address] hierarchy level is the interface that is used to manage the entire compute cluster.

        You can use the FreeBSD shell to check the VSE connection at the interface address 199.99.99.11/24. Type ssh root@199.99.99.11 and enter password for the password when prompted. You can also use the console to monitor the VSE device.

      2. Verify the status of your connection using the show app-engine status command.
        user@router> show app-engine status
        Compute cluster: cc1
         Compute node    Status
         cn0             Online
        

        This is the status of the App Engine. Online indicates that the node is booted and ready to accept virtual machines.

    6. Configure and provision the virtual machines (VMs).

      The VMs are where the applications run. Each application runs on its own guest OS. Configure and provision the VMs at the [edit services app-engine virtual-machines] hierarchy level. For details on options, see the “vm-instance” configuration statement section in the JunosV App Engine Administration Guide PDF Document. Links to child configuration statements are provided in the Syntax section of the configuration statement sections.

      Here is an example of the configuration you must set:

      [edit services app-engine]user@router# showvirtual-machines {vm-instance helloworld-vm {package sample-jvae-app-ve;compute-cluster cc1 {compute-node cn1;}interface eth0 {bridge br0;family inet {address 199.99.99.12/24;}}}}

      Tip: If the control traffic to and from the VMs and router is not too much, you should make the VM IP address be part of the same subnet as the compute node management IP address. This strategy uses fewer physical ports than is required to form a separate VM network.

    7. Commit the configuration and exit. When you commit your configuration, the system transfers the package to the VSE device, brings up the host OS, and installs and boots up the guest OS.
      1. Commit the changes to the configuration.
        [edit] user@router# commit commit complete
      2. Exit the configuration mode.
        [edit] user@router# exit Exiting configuration mode

        At this point, the installation of the required components is complete.

      3. Verify the configuration with show commands.
        1. Use the show app-engine virtual-machine package command to show the status of the download of the package.
          user@router> show app-engine virtual-machine package
          VM package: sample 
          VM disk image: sample.img.gz 
            Compute cluster               Package download status 
            cc1                           DOWNLOADED                
        2. Use the show app-engine virtual-machine vm-instance command to show the status of the VM. If the host manager is able to bring up the VM, the status is Active.
          user@router> show app-engine virtual-machine vm-instance
          VM name                  Compute cluster           VM status 
          sample                   cc1                       Active  

          The detail version of this command gives the following additional information:

          user@router> show app-engine virtual-machine vm-instance detail
          VM name: sample 
            VM status: ACTIVE 
            Compute cluster name: cc1 
            Compute node name: cn1 
            VM UUID: cfe28222-f142-11e1-ba37-00e081cbbc57 
            VM disk image: sample.img 
            Number of CPUs: 1 
            Memory (GB): 1 
            Console: 199.99.99.11 15001 
            VM PID: 6824 
            eth0: 199.99.99.12 
            hda: 8 GB

          The VM has a virtual console with the connectivity information as displayed (see the Console field above). You can log on to the VM console from the Juniper Networks device’s FreeBSD shell. You can drop to the FreeBSD shell by typing start shell. From there you can log on to the VM console by typing telnet 199.99.99.11 15001, for example. Use root for username and password for the password.

          You can also (using root as username and password as the password) ssh to the IP address of the management interface of the VM (see the eth0 field above) if ssh has been enabled inside the VM.

    8. Run the sample application.

      This step illustrates that the VSE device and the router are communicating with each other. You will set a display message using the Junos CLI on the router, then go into the VSE device and change the message, and finally display the message again using the CLI.

      The remote-helloworld application should already be running on the guest OS, as it has been configured to start upon bootup. You can also invoke it by its binary. The binary is located at /usr/local/bin and the source code is at /usr/local/src/examples/remote-helloworld.

      1. Configure helloworld.
        1. Check that the guest OS is running by issuing the following command on the router:
          user@router> show app-engine virtual-machine vm-instance
           VM name                  Compute cluster           VM status
           helloworld-vm            cc1                       Active

          The VM status should show as Active.

        2. Issue the following command to configure a custom string on the router and commit:
          user@router# set remote helloworld message "Hello!! From Remote App"
          [edit] 
          user@router# commit
          commit complete

          Upon commit, a config change notification is sent to the application running in the guest OS on the VM on the compute node.

      2. Run the operational command for this application, and verify that the configured custom string is displayed.
        user@router> show remote helloworld message
         Current Remote Hello World Application Message: 
          VSE App Message:  Hello!! From Remote App  

        This custom string is actually being relayed back from the remote application, running in the guest OS. After completing the next few steps, you will be able to confirm this is the case.

        The remote-helloworld application registers interest in any configuration changes under the [edit remote-helloworld] hierarchy level. So, when you commit the configuration in the previous step, the remote-helloworld application is notified and the configured string is passed to the application. The application, in turn, writes this string into the file /etc/helloworld.conf.

      3. Verify the file contents in the file /etc/helloworld.conf:
        1. Log in as root to the guest OS. The password you type in is password.
          % ssh root@199.99.99.12's password: password
          root@199.99.99.12 Last login: Fri Jul 27 02:32:46 2012

        2. Check the contents of the file /etc/helloworld.conf to make sure they match the custom string you have configured on the router.
      4. Modify the file contents on the guest OS. Edit the contents of the file /etc/helloworld.conf to Hello!! From Modified Remote App and save it.
      5. Display the modified custom string on the router: Repeat Step 8b above. Run the operational command for this application and verify that the modified string is now displayed in the output of the operational command.
        user@router> show remote helloworld message
         Current Remote Hello World Application Message: 
          VSE App Message:  Hello!! From Modified Remote App  

        Because the modified message was changed only in the binary, you know this message is from the binary and not something happening just on the router.

    Congratulations! You have successfully run your first remote application.

    Section II: Customizing and Deploying the Remote-Helloworld Sample Application

    This section illustrates how to set up the JunosV App Engine development environment, write an application, and build and package your application. The process to deploy the application is covered in Section I. Once you have completed the application development, follow the instructions in Section I to deploy the application. For simplicity, we provide you with the source code for the sample application you deployed in Section I and let you modify it. You should apply the same steps to creating your own remote application.

    Building and packaging a remote application requires the use of a physical machine. You can use the same environment used to create an application to test it.

    Introductory Disscussion

    The remote-helloworld application demonstrates integrating an application on the VSE device with the router’s management plane. The application runs in the guest OS on the VSE device and extends the Junos configuration and operational commands.

    In this section, you focus on understanding how to exercise simple remote route service APIs. Remote service APIs are enabled by the Juniper Distributed Application Framework (JDAF). You will enable an option at the [edit remote-helloworld] hierarchy level. The file helloworld_parse.c is notified of this configuration change, and you will then add code to install a discard route in the routing table. For your convenience in doing this exerside, the configuration statement add-discard-route is already implemented in the DDL. You must revise the sample application code to use this DDL.

    At a high level, the following remote APIs are needed in the order given to initialize the route, connect to the route service, and perform the route addition from the remote-helloworld sample application:

    1. Jnpr__Route_init() – To Initialize the route service.
    2. Jnpr__Route_tcp_address() – To get the TCP address where the route service is hosted.
    3. Jnpr__Route_connect() – To connect to the route service from your sample application.
    4. Jnpr__Route_send_RouteAddReq() – To send a Route Add request.
    5. Jnpr__Route_rcvd_RouteAddRsp() – To receive a response to a Route Add request.

    For reference, a sample of this simple route service example is included in /usr/local/sources/simple-route.c. (This file also exists in the junos-sdk-remote-devtools package.) The code in this file shows a route table lookup. However, you will now revise this code to implement the add-discard-route option that was added to the DDL.

    Procedure for Customizing the Remote-Helloworld Sample Application

    The following procedure outlines the steps you take to customize and deploy the sample remote-helloworld application:

    1. Set up the development environment.

      To set up the development environment, you need to install CentOS, download the development tools, and set up the development directory. For these steps, see the Creating the CentOS Development System for JunosV App Engine page in the Junos SDK Installation Guide. Once this step is complete, the system for developing remote applications is ready to use.

    2. Extend the remote-helloworld application.
      1. Populate the Route Add request

        When the add-discard-route option is set in the configuration on the router, the application sets a Boolean enable_add_discard_route variable in the file remote-helloworld_parse.c.

        Once the route initialization and connection is set up, you can construct the Route Add request. The fields in generated requests and responses are documented on the Protocol Definition tab in the reference for each service in the Remote Routing and System API Reference documentation. In this case, the service the definitions are found in is the Routing Table service.

        Your code will populate the following fields in the Route Add request. The fields will contain the values you supply. You must add DISCARD for the Next-hop type field.

        • Prefix
        • Address family
        • Prefix length
        • Route table ID
        • Next-hop type: DISCARD
      2. Your code then invokes the Jnpr__Route_send_RouteAddReq() function (for where to put this code, see Where to Put the Code Addition for Section II).

        For example, your code might look like the following:

        #define HELLOWORLD_IPV4ADDR_PREFIX "120.120.120.0"
        #define HELLOWORLD_IPV4ADDR_PREFIX_LENGTH 24
        static void
        helloworld_route_add_discard_route(jdaf_channel_t *channel, uint32_t route_table_id)
        {
            jdaf_status_t status;
            uint32_t prefix_inet_addr;
          
            /* Jnpr__Route_Message is a generated macro that declares message
            variables of type RouteAddReq (and next, Prefix),  names the variables
            add_req and prefix, and initializes each one. Your code can then
            populate the fields using the variables.*/
            Jnpr__Route_Message(RouteAddReq, add_req);
            Jnpr__Route_Message(Prefix, prefix);
        
            /* Construct the Route Add message */
            prefix.address_family = JNPR__ROUTE__ADDRESS_FAMILY__IPV4;
            prefix.length = HELLOWORLD_IPV4ADDR_PREFIX_LENGTH;
            prefix.prefix.len = 4;
            inet_pton(AF_INET, HELLOWORLD_IPV4ADDR_PREFIX, &prefix_inet_addr);
            prefix.prefix.data = (uint8_t *) &prefix_inet_addr
            add_req.prefix = &prefix
            add_req.table_id = route_table_id;
            add_req.has_next_hop_type = 1;
        
            /* The DISCARD constant is constructed according to Protocol Buffer
            syntax rules.The rules are summarized in the Application Development
            Setup topic in the Developer’s Guide topics for the remote routing
            and system APIs.You can also see the Google Protocol Buffer
            documentation for details.*/
            add_req.next_hop_type = 
                 JNPR__ROUTE__ROUTE_ADD_REQ__ROUTE_NEXT_HOP_TYPE__DISCARD;
        
            /* Send a Route Add Request */
            status = Jnpr__Route_send_RouteAddReq(channel, &add_req, COOKIE);
                if (status != JDAF_STATUS_OK) {
                    EPRINT(" Sending Add route request for prefix(%s) failed ",
                            HELLOWORLD_IPV4ADDR_PREFIX);
        }
        
      3. Upon adding the relevant sections of the code as outlined above, recompile your application. For the purposes of this exercise, simply update the binary running on the guest OS hosted on the VSE device tethered to the router.
      4. Verify the changes.

        When the add-discard-route option is set on the router at the [edit remote helloworld] hierarchy level followed by a commit, you can see the discard route added to the routing table:

        user@router# set remote helloworld message add-discard-route
        [edit]
        user@router# commit
        user@router# run show route 120.120.120.0
        inet.0: 38 destinations, 38 routes (38 active, 0 holddown, 0 hidden) + = Active Route, - = Last Active, * = Both    120.120.120.0/32   *[Static/5] 00:00:05                         Discard
    3. Build and package an installable application.

      After programming your application, you need to build and package it to make it installable by users. For instructions on building and packaging your application, see the Packaging and Deploying Remote Applications Login required page in the Junos SDK Developers Guide.

    4. Install the software packages and the application.

      For deployment of Junos, JunosV App Engine, and the new application package, follow steps 1 through 7 in Section 1, Section I: Deploying a Sample Application. Make sure you authorize the provider of the application on the router using the correct provider, license-type, and deployment-scope values.

    5. Configure application-specific settings and run the application.

      In this case, you need to make sure that the add-discard-route object is configured under the [edit remote helloworld] hierarchy level. Make sure you commit the configuration.

    Where to Put the Code Addition for Section II

    You add the new code in the Jnpr__Cnf_rcvd_GetCnfRsp() callback in the remote-helloworld_config.c file. (The #defines should be added at the beginning of the file). Your code should execute after the configuration parse code has determined that the Boolean has been enabled:

    void
    Jnpr__Cnf_rcvd_GetCnfRsp (jdaf_channel_t *channel,
                        const Jnpr__Cnf__GetCnfRsp *rsp,
                        const jdaf_msg_info_t *jdaf_msg_info)
    {
        jdaf_status_t status;
        uint64_t rcvd_msg_cookie;
    
        IPRINT("Got a get config message response");
    
        status = jdaf_msg_info_get_cookie(jdaf_msg_info, &rcvd_msg_cookie);
        /* error handling deleted for clarity */
       
        
        /* Parse the configuration data received:
        if (rsp->err_code == JNPR__CNF__ERR_CODE__OK) {
            IPRINT("Config channel response was received as  %s ", rsp->cnf_buf);
            helloworld_config_parse(rsp->cnf_buf);
    
            /* Now add your code: */
            if (enable_add_discard_route) {
                IPRINT("Adding Discard route \n");
                /** Call your Add Discard route function here **/
            }
    

    Revision History

    6 August 2012

    Final draft for JunosV App Engine 12.3B1.

    20 September 2012

    Revised draft for xml publication.

    12 November 2012

    Revised with comments from reviewers.

    Published: 2012-11-12