WeOS
5.20.1

# Building a Netbox Application Container

## Introduction

ⓘ Note

This feature is only available in certain products and to selected customers.

This document describes how to build the NetBox application container. NetBox is a GNU/Linux created with the Buildroot tool that simplifies and automates the process of building a complete Linux system for an embedded system, using cross-compilation.

    +-- WeOS5------------------ --------+
    |                                   |
    |                                   |
    |       +-- container -----------+  |
    |       |     +--------------+   |  |
    |   tap1-eth1 |              |   |  |
    |       |     |    Netbox    |   |  |
    |       |     |              |   |  |
    |       |     | ------------ |   |  |
    |       |     |              |   |  |
    |       |     |   Buildroot  |   |  |
    |       |     |              |   |  |
    |       |     +--------------+   |  |
    |       +------------------------+  |
    |                                   |
    +-----------------------------------+

We will start with creating a clone of the Netbox project and then configure settings for cross-compilation before building the Netbox container image.

We will then install the image on a WeOS 5 device.

To complete this howto you will need:

- A device running WeOS 5 with support for Application Hosting.
- Build tools, mandatory packages
- Make sure to have m4 installed on your host e.g. apt-get install m4
- External media like USB flash memory to store applications on.

If adding your own app on top of Netbox please refer to the App-demo project for a starting point.

## Cloning Netbox repository

Before we clone the Netbox repository we create a directory to keep our code in.

    example:/#> mkdir ~/src
    example:/#> cd src

Standing in the created working directory we can clone the Netbox repository.

    example:~/src/#> git clone https://github.com/westermo/netbox.git
    example:~/src/#> cd netbox

Netbox is based on the Buildroot project so buildroot is added as a sub-module to Netbox. In order to be able to build the Netbox system, all sub-modules must be updated first. It is important that this update is done before anything else.

    example:~/src/netbox/#> git submodule update --init --recursive

## Configure and build

To cross-compile and build Netbox for a device, there are predefined build configurations to choose from. These configuration files are located in netbox/configs directory and ends with the .m4 extension.

    example:~/src/netbox/#> ls configs
    include
    netbox_app_dagger_defconfig.m4
    netbox_os_basis_defconfig.m4
    netbox_os_envoy_defconfig.m4
    netbox_app_basis_defconfig.m4
    netbox_app_envoy_defconfig.m4
    netbox_os_coronet_defconfig.m4
    netbox_os_zero_defconfig.m4
    netbox_app_coronet_defconfig.m4
    netbox_app_zero_defconfig.m4
    netbox_os_dagger_defconfig.m4

To use one of the pre-built configuration files remove the file extension .m4 when calling make.

In this example we choose to build for the Coronet platform and therefore we run:

    example:~/src/netbox/#> make netbox_app_coronet_defconfig

Build environment is set up for the coronet platform and configuration options are copied to the projects .config file. After this we can build the Netbox image.

    example:~/src/netbox/#> make

Since we are building the image for the first time code have to be downloaded for libraries and all object files must be built.

After build is done we can find the resulting image netbox-app-coronet.img in the output/images folder with some other files:

    example:~/src/netbox/#> ls -l output/images/
    -rw-r--r-- netbox-app-coronet.img
    -rw-r--r-- ...
    -rw-r--r-- ...

## Transfer the image

Application images are stored on external storage like an USB flash memory. Set up an external storage for the device by formatting a USB memory. Storage is recommended to use a Journaling Filesystem like ext3 or ext4.

    example:/#> media
    example:/media/#> show
    MEDIA        NAME         TYPE         SIZE         USED         USE%
    External     usb          vfat         1.9G         20.0K        0%
    example:/media/#> format external ext3

    Warning: Formatting this media removes all files stored on it!
             This process cannot be reversed, do a backup first.

    Do you still want to proceed (y/N)?y

    Formatting: 100% \ [================================================]

    Format successful!
    example:/media/#> show
    MEDIA        NAME         TYPE         SIZE         USED         USE%
    External     usb          ext3         1.7G         32.0K        0%

It is now time to transfer the image from the host PC to the WeOS device. Begin by copying the netbox-app-coronet.img to your hosts TFTP folder. In WeOS, setup a connection between the device and the host to be able to reach the hosts TFTP server, ping to check connection. In WeOS, import the Netbox container image using the built in command:

    dut:/#> app image import tftp://[HOST-IP]/netbox-app-coronet.img
    downloading  100% |********************| 5180k

## Configure the Netbox app

To show what images are available in WeOS for creating an app, use the command:

    dut:/#> show app image
    NAME              VERSION           DESCRIPTION
    netbox            2020.02-r0        NetBox - The Networking Toolbox

Create an app nb0 using the Netbox image as template:

    example:/#> configure app nb0 netbox
    example:/config/app-nb0/#> leave

CPU and memory restrictions:

Note

To ensure WeOS has enought cpu and memory to run smooth the apps are restricted to not allocate more than 25% of the cpu periods and not more than 50% of the total RAM memory together. Memory and cpu is divided equally among the container apps.

The app is created and started. To see status of the app we can run:

    example:/#> app show
    NAME STATE   AUTOSTART GROUPS IPV4 IPV6 UNPRIVILEGED
    nb0  STARTED 1         -      -    -    false

Common commands used in WeOS 5 when working with app’s:

    example:/#> sh app image # show template images
    example:/#> app show # show created app's
    example:/#> app start [APP-NAME] # start an app
    example:/#> app attach [APP-NAME] # attaches a terminal to the app

## Container logging

If having problems creating or starting the app, it is possible to activate the container log and get information from the Kernel written to syslog when interacting with the app.

Activate logging by changing Loglevel from 5 to 1.

    example:/#> config app nb0
    etbn1:/config/app-nb0/#> show
    Status       : Enabled
    Name         : nb0
    Description  :
    Image        : netbox
    Init cmd     : /sbin/init
    Loglevel     : 1