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:
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:/#> rebootPrepare 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/#> leaveMake 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/imagesfolder 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-hostingcontext in WeOS and import the image usingimportcommand, 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/#> leaveFor 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