Launching a Guest Virtual Machine (VM) to Run a Third Party Application on Junos OS Release 13.2X51-D20 and Later

Understanding Guest VMs

You can use a guest virtual machine (VM) to run third party software applications. Guest VMs provide a native environment in which third party applications can be executed, and eliminate the need for porting or adapting third party applications to work on the host OS. You can use the Junos SDK Virtual Build Environment in the JunosV App Engine to package the guest VM images. Once the guest VMs are packaged, you can launch them from the Junos OS CLI.

Note: Only one guest VM is supported at this time. Only QFX5100 switches support guest VMs.

Troubleshooting Tips

Copying the Third Party Application to the Switch

1. Copy the third party application to the switch using any file transfer protocol:

   For example:

   root% scp //hostname/pathname/third-party-app.img.gz /var/tmp

Install the Third Party Application on the Switch

1. Install the third party application package on the switch.

   This might take a few minutes.

   For example:

   {master:0}

   root> request system software add virtual-machine-package /var/tmp/third-party-app.img.gz

   
   Installing virtual-machine package..
   Copying virtual-machine package..
   Uncompressing virtual-machine package..
   Finished virtual-machine package installation.
   

2. Issue the show version command to verify that the installation was successful.

   For example:

   {master:0}

   root> show version

   Apr 02 09:12:13
   fpc0:
   --------------------------------------------------------------------------
   Hostname: host
   Model: qfx5100-96s-8q
   JUNOS Base OS Software Suite [13.2-20140401_x_132_x51_vjunos.0]
   JUNOS Base OS boot [13.2-20140401_x_132_x51_vjunos.0]
   JUNOS Crypto Software Suite [13.2-20140401_x_132_x51_vjunos.0]
   JUNOS Online Documentation [13.2-20140401_x_132_x51_vjunos.0]
   JUNOS Kernel Software Suite [13.2-20140401_x_132_x51_vjunos.0]
   JUNOS Packet Forwarding Engine Support (qfx-ex-x86-32) [13.2-20140401_x_132_x51_vjunos.0]
   JUNOS Routing Software Suite [13.2-20140401_x_132_x51_vjunos.0]
   JUNOS Enterprise Software Suite [13.2-20140401_x_132_x51_vjunos.0]
   JUNOS py-base-i386 [13.2-20140401_x_132_x51_vjunos.0]
   third-party-app-ve Virtual Engine package [13.1I20130918_2234]                   
   JUNOS Host Software [13.2-20140401_x_132_x51_vjunos.0]

   The CLI output shows that the application named third-party-app was installed.

Configure the Guest VM Options to Lauch the Guest VM on the Host

1. Configure the following options for guest VM support in the Junos OS CLI at the [edit] hierarchy.
   • Compute cluster name
   • Compute node name
   • Virtual machine instance name
   • Dedicated management interface for guest VM
   • Third party package name
   • Internal IP address of the guest VM
2. Configure the name of the compute cluster and compute node.

   The name of the compute cluster must be default-cluster, and the name of the name of the compute node must be default-node, otherwise launching the guest VM fails.

   For example:

   {master:0}

   root# set services app-engine compute-cluster default-cluster compute-node default-node hypervisor
3. Configure the name of the virtual machine instance and the name of the third party application.

   Note: The package names in the show app-engine virtual-machine-package and show version commands should match.

   {master:0}

   root# set services app-engine virtual-machines instance instance-name package package-name

   For example:

   {master:0}

   root# set services app-engine virtual-machines instance test package third-party-app ve
4. Associate the virtual machine instance with the configured compute cluster and compute node.

   Note: The name of the compute cluster must be default-cluster, and the name of the compute node must be default-node, otherwise launching the guest VM fails.

   {master:0}

   root# set services app-engine virtual-machines instance instance-name compute-cluster name compute-node name

   For example:

   {master:0}

   root# set services app-engine virtual-machines instance test compute-cluster default-cluster compute-node default-node
5. Configure the local management IP address.

   This IP address is used for the internal bridging interface. The host uses this IP address to check the availability of the guest VM. The IP address must be 192.168.1.X, where X is from 100 to 200.

   {master:0}

   root# set services app-engine virtual-machines instance instance-name local-management family inet address 192.168.1.X

   For example:

   {master:0}

   root# set services app-engine virtual-machines instance test local-management family inet address 192.168.1.100
6. Configure the management interface for the guest VM.

   This management interface is separate from the one used for Junos OS.

   Note: The management interface name must be either em0 or em1. The configuration will fail if you do not configure a management interface and then commit the configuration.

   For example:

   {master:0}

   root # set services app-engine virtual-machines instance test management-interface em1

   The new management interface is provisioned for the guest VM.

7. Commit the configuration.

   For example:

   {master:0}

   root# commit

   Here are the results of the configuration:

   services {

   app-engine {

   compute-cluster default-cluster {

   compute-node default-node {

   hypervisor;

   }

   }

   virtual-machines {

   instance test {

   package third-party-app;

   local-management {

   family inet {

   address 192.168.1.100;

   }

   }

   compute-cluster default-cluster {

   compute-node default-node;

   }

   management-interface em1;

   }

   }

   }

   }
8. Configure the internal IP address of the guest VM.
   • (Preferred method) Log into the guest VM. The maximum length for the guest VM name is 255 characters. Make sure you are logged in as root when you enter this command.
     root> request app-engine virtual-machine-shell guest-VM-name

     For example:

     root> request app-engine virtual-machine-shell third-party-app
   • (Alternate method) Log into the host shell by specifying the internal management IP address:

     For example:

     shell% ssh -JU __juniper_private4__ 192.168.1.1

     Issue the virsh list command to see which VMs are running. From the output, you can see that the guest VM (named test in this example) is running:

     {master:0}

     shell# virsh list

     Id    Name                           State
     ----------------------------------------------------
     3     vjunos1                        running
     4     test                           running
     

     Log into the guest VM console (named 4 in this example).

     For example:

     shell# virsh console 4

     Connected to domain test
     Escape character is ^]
     CentOS release 6.4 (Final)
     Kernel 2.6.32-358.el6.x86_64 on an x86_64
     
     [root@localhost ~]

     From the output, you can see that you are connected to the guest VM console (root@localhost)

     Enter a valid username and password combination for the guest VM.

9. Configure the internal IP address of the guest VM on the Ethernet interface.
   • Issue the ifconfig -a command to see the name of the management interface that is used to access the guest VM from outside of the network, and the name of the management interface that is used for internal use.

     The interface names are either eth6 or eth7, or eth7 or eth8. You can associate one of the interfaces to the guest VM by issuing the set services app-engine virtual-machines instance name management-interface interface-name. command. Use the same IP address as the one you configured using the set services app-engine virtual-machines instance test local-management family inet address 192.168.1.100. The MAC addresses associated with these interfaces are used for internal bridging.

     For example:

     root@localhost ifconfig -a

     eth6      Link encap:Ethernet  HWaddr 52:54:00:5D:DB:01
               UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
               RX packets:982 errors:0 dropped:0 overruns:0 frame:0
               TX packets:970 errors:0 dropped:0 overruns:0 carrier:0
               collisions:0 txqueuelen:1000
               RX bytes:92188 (90.0 KiB)  TX bytes:91468 (89.3 KiB)
     eth7      Link encap:Ethernet  HWaddr 52:54:00:5D:DB:02
               UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
               RX packets:982 errors:0 dropped:0 overruns:0 frame:0
               TX packets:970 errors:0 dropped:0 overruns:0 carrier:0
               collisions:0 txqueuelen:1000
               RX bytes:92188 (90.0 KiB)  TX bytes:91468 (89.3 KiB)

     In this example, eth6 is a management interface that is used to access the guest VM, and eth7 is a management interface that is used for internal use.

   • Issue the ifconfig command to configure the internal IP address on the Ethernet interface. This is the same IP address you configured in the Junos OS CLI.

     For example:

     root@localhost ifconfig eth7 192.168.1.100 netmask 255.255.255.0
10. Issue the following show commands to verify that everything is working correctly:

    For example:

    • root# show app-engine status

       Compute cluster: default-cluster
                        Compute node      Status
                        default-node      Online     

      The status should be Online.

    • root# show app-engine virtual-machine instance

      VM name                  Compute cluster           VM status
                      test               default-cluster           ACTIVE 

      The VM status should be active.

    • root# show app-engine virtual-machine instanceshow app-engine virtual-machine package

      VM package: cust-vm-ve
                      VM disk image: third-party-app-ve/20140409_015447/third-party-app.img.gz
                        Compute cluster                   Package download status
                        default-cluster                   DOWNLOADED   
      

      The package downloaded status should be either download in progress or downloaded.

    • root# show interfaces terse management-interface

      error: device em1 not found

      This interface should be detached from Junos OS.

11. To remove the guest VM, delete the configuration statements and uninstall the third party software package.

    For example, to remove the app-engine statement:

    root # delete services app-engine

    Commit the configuration.

    For example:

    root# commit

    Issue the show version command to see what the name of the third party application package is.

    For example:

    {master:0}

    root> show version

    fpc0:
    --------------------------------------------------------------------------
    Hostname: host
    Model: qfx5100-96s-8q
    JUNOS Base OS Software Suite [13.2-20140406_x_132_x51_vjunos.0]
    JUNOS Base OS boot [13.2-20140406_x_132_x51_vjunos.0]
    JUNOS Crypto Software Suite [13.2-20140406_x_132_x51_vjunos.0]
    JUNOS Online Documentation [13.2-20140406_x_132_x51_vjunos.0]
    JUNOS Kernel Software Suite [13.2-20140406_x_132_x51_vjunos.0]
    JUNOS Packet Forwarding Engine Support (qfx-ex-x86-32) [13.2-20140406_x_132_x51_vjunos.0]
    JUNOS Routing Software Suite [13.2-20140406_x_132_x51_vjunos.0]
    JUNOS Enterprise Software Suite [13.2-20140406_x_132_x51_vjunos.0]
    JUNOS py-base-i386 [13.2-20140406_x_132_x51_vjunos.0]
     third-party-app-ve Virtual Engine package [20140409_015447]
    JUNOS Host Software [13.2-20140406_x_132_x51_vjunos.0]

    Issue the request system software delete virtual-machine-package <package-name> command to uninstall the third party application:

    For example:

    root> request system software delete virtual-machine-package third-party-app-ve

    fpc0:
    --------------------------------------------------------------------------
    Deleted virtual-machine package cust-vm-ve ...