WeOS
5.29.0

# Application Hosting HowTo

This document outlines some practical examples of how to:

- Enable the feature in WeOS
- How to prepare the device
- How to import application images
- How to configure application hosting and applications
- How to control applications & monitor status

For a general overview of the feature, refer to:

- Application Hosting

## Enable Application Hosting

To enable Application Hosting feature in WeOS, a special license package must be obtained and installed.

To obtain installation package, contact Westermo Network Technologies AB.

Having obtained the package, install it in WeOS. After successful installation, reboot the system for the effect to take place.

    example:/package/#> install proto tftp 198.19.10.1 app-hosting-license-signed.wmopkg
    Attempting to download file app-hosting-license-signed.wmopkg, using TFTP

    Connecting to 198.19.10.1 (198.19.10.1:69)
    app-hosting-license-signed.wmopkg:

    0%       25%       50%       75%       100%
    |---------+---------+---------+---------|
    |=======================================|
        PKG: Signed
    Installed... Changes are applied after reboot.
    example:/package/#> show
    ╒ Packages ════════════════════════════════════════════════════════════════════╕
    │NAME                        VERSION  PERSISTENT  VERIFICATION  DESCRIPTION    │
    │app-hosting-license-signed  0.1      False       Signed        App-hosting    │
    └──────────────────────────────────────────────────────────────────────────────┘

    example:/package/#> leave
    example:/#> reboot

## Prepare the Device

Application Hosting is dependent on external media storage for storing application images and files associated with hosted application.

Applications have access to external media for storing their configuration files, logs, etc. The external media can be setup with specific partitions for different storage. The suggestion is to not mix the app-image storage with the shares.

First and foremost, external media device needs to be formatted to `vfat`, `ext2`, `ext3` or `ext4` filesystem type. This can be done using multiple tools in Linux, Windows, and even WeOS.

In Linux, a GUI tool called ‘GParted’ could be used.

In Windows, a build-in feature can be used:

1. Open File Explorer → Right-click the external media → Format.
2. File System: Select desired type.
3. Allocation unit size: Default.
4. Click Start.

To format and partition external media in WeOS, do the following:

    example:/#> show media
    MEDIA       DEVICE      LABEL          FORMAT   RW     SIZE  USED  DESCRIPTION
    Active
    internal    mtd:Config  -              jffs2    Yes   14.0M    6%  config,cert
    Inactive
    external    -           -              -        -         -     -
    Available
    -           mmcblk1     -              -        -     29.7G     -

    example:/media/#> partition mmcblk1
    Entering partitioning mode with dev mmcblk1 as target...

    No changes will be performed until the start-partition command is
    invoked. When invoked the entire device mmcblk1 will be fully re-partitioned
    and reformatted, any files on the device will be LOST/REMOVED, keep
    this in mind before proceeding.

    example:/media/partition-mmcblk1/#> add part-numb 1 label app_images size 10G format ext4
    example:/media/partition-mmcblk1/#> show
    Partition table for dev: mmcblk1
    #  DEV-NAME      PART-NUMB  LABEL                          SIZE      FS
    1  /dev/mmcblk1p1 1         app_images                     10G       ext4
    example:/media/partition-mmcblk1/#> start-partitioning

    Understand that the content on the device will be lost during the
    partitioning and formatting of the device. Make sure that the device
    does not contain any files that needs to be saved elsewhere.

    Start partitioning and formatting of the device (y/N)? y

    Attempt to partition device /dev/mmcblk1 in the following manner:
      1: /dev/mmcblk1p1 [Partition numb: 1], [Size: 10G]
    Command (m for help): Partition type
       p   primary partition (1-4)
       e   extended
    Command (m for help):
    Initiate formatting of the partitions, this may take a while:
      1: /dev/mmcblk1p1 [Partition numb: 1] [Label: app_images], format with ext4 FS...
    Formatting: 100% \ [============================================================]

    Device mmcblk1 successfully partitioned and formatted!
    example:/media/#> show
    MEDIA       DEVICE      LABEL          FORMAT   RW     SIZE  USED  DESCRIPTION
    Active
    internal    mtd:Config  -              jffs2    Yes   14.0M    6%  config,cert
    Inactive
    external    -           -              -        -         -     -
    Available
    -           mmcblk1p1   app_images     ext4     -     10.0G     -

    example:/media/#> exit
    example:#>

After this, for the partitions to be mounted to named Medias the device boot settings needs to be modified. These changes are read at boot time.

    example:/#>
    example:/#> boot
    example:/boot/#> no media external
    example:/boot/#> media images
    Creating new media definition...
    example:/boot/media-images/#> match label app_images
    example:/boot/media-images/#> exit
    example:/boot/#> exit
    Saving bootloader configuration to FLASH
    100% / [====================================================================]
    example:/#>

Restart the device and check that you have been provided with the correct medias and names.

    example:/#> show media
    MEDIA       DEVICE      LABEL          FORMAT   RW     SIZE  USED  DESCRIPTION
    Active
    internal    mtd:Config  -              jffs2    Yes   14.0M    6%  config,cert
    images      mmcblk1p1   app_images     ext4     Yes    9.7G    0%
    Inactive
    Available
    example:/#>

Now it is time to place application image onto the formatted drive. By default, WeOS expects to find application images in `/app/images` folder. Create this folder structure and copy images there.

Alternatively, any folder structure can be used, but make sure to change external storage settings in WeOS and set the correct path (see example below). The path set is relative to the root folder of the external media.

Enter the storage config context for application hosting and set the selected media to our formatted `images` media and, optionally, set a path within the external media for storage of application images. This example will continue using the default path `app/images`.

    example:/#> config app-hosting
    example:/config/app-hosting/#> storage
    example:/config/app-hosting/storage/#> media images
    example:/config/app-hosting/storage/#> path my/custom/folder/structure/
    example:/config/app-hosting/storage/#> leave

Make sure you connect external media to your device before you proceed.

When the external drive is connected, WeOS will either look for images in the default catalogue (`app/images`) or any other configured folder.

## Importing Application Images

Images can be imported in two ways:

1. Manual

Place application image directly onto the external media. Note that by default, WeOS expects images to be placed in `app/images` folder on external media, unless configured otherwise.

1. Import from a remote server

Place application image into the folder used by remote file server, head to `/file/app-hosting` context in WeOS and import the image using `import` command, as shown below:

    example:/#> file app-hosting
    example:/file/app/#> import proto tftp 192.0.2.1 /tftpboot/zeroimage-1.0.wmopkg
    example:/file/app/#> show
    /media/images/app/images/     MOD. DATE/LINK    SIZE      MD5
    coronetimage-1.0.wmopkg       2025-11-27 22:35  2704786
    zeroimage-1.0.wmopkg          2025-11-27 22:35  2872718

    Free: 1013.9 MiB | Total: 1021.10 MiB
    example:/file/app/#>

Imported application images will be placed into `app/images` folder on external media. As previously mentioned this path can be configured in application hosting context.

## Label the Image

For images to be usable by applications, labels need to be set. Head to application hosting admin exec and configure labels:

    example:/#> app-hosting
    example:/app-hosting/#> label zeroimage-1.0 zero
    example:/app-hosting/#> show

    Applications
    No applications found.

    Application Images
    NAME                                 LABEL            VALID  VERIFIED  VERSION
    zeroimage-1.0                        zero             Yes    Yes       1.0
    coronetimage-1.0                     coronet          Yes    Yes       1.0

    Image storage
    Storage media    : images
    Storage path     : app/images/
    example:/app-hosting/#>

## Configure and Applications and System Resource Allocation

Several options can be configured for the overarching application hosting context, including storage which was configured previously:

- CPU & RAM - a percentage of the total CPU power and RAM capacity can be specified. All applications will share the allocated amount of CPU and RAM.

    example:/#> config app-hosting
    example:/config/app-hosting/#> cpu 25
    example:/config/app-hosting/#> ram 25
    example:/config/app-hosting/#> show

    Allocated Hardware Resources
    CPU(%)           RAM(%)
    25               25

    Image storage
    Storage media    : images
    Storage path     : app/images/

Now that application hosting is ready, create and configure hosting application:

    example:/#> config app-hosting
    example:/config/app-hosting/#> app app1
    ╒ Configuration Errors: 1 ═══════════════════════════════════════════════════╕
    │#   ERROR  Description                                                      │
    │1   0860   Missing image label                                              │
    └────────────────────────────────────────────────────────────────────────────┘
    example:/config/app-hosting/app-app1/#> image zero
    example:/config/app-hosting/app-app1/#> share port eth4
    example:/config/app-hosting/app-app1/#> share veth lan0 as wan0
    example:/config/app-hosting/app-app1/#> capability CAP_NET_ADMIN
    example:/config/app-hosting/app-app1/#> show
    Name           : app1
    Status         : Enabled
    Autostart      : Yes
    Description    :
    Image label    : zero
    Command        : /sbin/init
    Shell          : sh
    Net. Namespace : user-ns
    UID            : 0
    GID            : 0

    Shared Resources
    TYPE  HOST                              GUEST               OPTS
    port  eth4                              eth4
    veth  lan0                              wan0

    Environment Variables
    NAME                    VALUE

    Capabilities
    NAME
    CAP_NET_ADMIN
    example:/config/app-hosting/app-app1/#> leave

For application to run successfully, an application image must be specified. Applications may utilise system resources, such as physical ports, and create virtual ethernet pairs (vEth). In the case above, app1 takes ownership of port eth4. Essentially, this means that eth4 will be moved to app1’s network namespace, and WeOS will lose access to this port. app1 also creates a vEth, in the example above. The nature of vEth is that it has two ends: in our case, wan0 is the name of the interface seen and owned by app1, while lan0 is the other end, seen and owned by WeOS. The diagram below shows relationships of ports and vEth.

We can see that eth4 now belongs to app1 and resides in its private network namespace. wan0 belongs to app1, while lan0 belongs to WeOS. Additionally, lan0 interface can be added to a VLAN available in WeOS, in this case VLAN v1. This is not a necessity, but a convenience. lan0 interface can simply stay as a standalone interface in WeOS.

    +--------------------------------------------------------------------------+
    | WeOS                                         +-----------------+         |
    |                                              |       app1      |         |
    |                                              +---------+-------+         |
    |                                                        |                 |
    |     +-------------------------------+        +---------+-------+         |
    |     |                               |        |                 |         |
    |     |       Host-OS netns           |        |    app1-netns   |         |
    |     |                               |        |                 |         |
    |     +--+-------------------+--------+        +-+--------+------+         |
    |        |                   |                   |        |                |
    |        |                   |                   |        |                |
    |        |                +--+-+                 |        |                |
    |        |         +------+ v1 +-------+         |        |                |
    |        |         |      +--+-+       |         |        |                |
    |        |         |         |         |         |        |                |
    |        |         |         |         |         |        |                |
    |     +--+-+    +--+-+    +--+-+    +--+-+    +--+-+   +--+-+              |
    |     |    |    |    |    |    |    |    +----+    |   |    |              |
    |     +----+    +----+    +----+    +----+    +----+   +----+              |
    |      Eth1      Eth2      Eth3      Lan0      Wan0     Eth4               |
    +--------------------------------------------------------------------------+

## Control Applications and Monitor Status

Applications can be controlled and monitored from the application hosting admin exec context.

To see the status of applications, run the following command:

    example:/#> app-hosting
    example:/app-hosting/#> show

    Applications
    NAME             STATUS           NET.NAMESPACE    IMG.LABEL
    app1             Running          app1             zero

    Application Images
    NAME                                 LABEL            VALID  VERIFIED  VERSION
    zeroimage-1.0                        zero             Yes    Yes       1.0
    coronetimage-1.0                     coronet          Yes    Yes       1.0

    Image storage
    Storage media    : images
    Storage path     : app/images
    example:/app-hosting/#>

Use the following commands for starting, stopping restarting or attaching to the application:

    example:/app-hosting/#> stop app1
    example:/app-hosting/#> start app1
    example:/app-hosting/#> restart app1
    example:/app-hosting/#> attach app1
    / # exit
    example:/app-hosting/#>

If application image label ever needs to be changed, use the following commands:

    example:/app-hosting/#> label zeroimage-1.0 ze
    example:/app-hosting/#> reload ze
    example:/app-hosting/#>

When image label is changed, applications using the old label need to be restarted for the new changes to take place. `reload` command does that.

To monitor application logs, use the following commands:

    example:/app-hosting/#> show log app1
    example:/app-hosting/#> follow log app1

« Previous Next »