WeOSBuilding a Netbox Application Container
Introduction
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