WeOSApplication 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:
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:
- Open File Explorer → Right-click the external media → Format.
- File System: Select desired type.
- Allocation unit size: Default.
- 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:
- 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.
- 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.
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