Application Hosting

Introduction

What is Application Hosting?

Application Hosting is a feature that allows users to deploy and run containerized applications directly within WeOS. It provides an isolated environment for applications while leveraging system resources such as networking, storage, and computing power. This approach ensures flexibility, security, and scalability for running third-party or custom applications alongside core system services.

What is an Application Image?

An application image is a packaged representation of an application, including:

The executable binaries.
Required libraries and dependencies.
Configuration files and metadata.

Images follow the OCI (Open Container Initiative) specification, ensuring compatibility with standard container runtimes. They serve as the source for creating application containers.

What is an Application?

An application in this context refers to the running instance of an application image inside a container. It operates in an isolated environment with its own:

Network namespace (dedicated interfaces and virtual Ethernet pairs). Alternatively it can share network namespace with the host operating system.
Filesystem paths (including access to external media for persistent storage).
Resource limits (CPU, memory, etc.).

Applications can be managed through CLI or Web interface, allowing configuration, lifecycle control, and monitoring.

Underlying Technology

The Application Hosting feature is built on the OCI container model, which defines:

Standard image format for portability.
Runtime specification for consistent container execution.
Namespace and cgroup isolation for security and resource control.

What Can You Do with Applications? (Use Cases)

Network Services Host custom network services (e.g., DHCP, DNS, monitoring agents) within isolated containers.
Data Processing Run analytics or processing tools without interfering with the base OS.
Third-Party Integrations Deploy vendor-provided applications or tools in a controlled environment.

Environment

Applications in WeOS run in an isolated environment whilst leveraging system resources from the device, such as file storage, networking, and computing power.

Filesystem

     Application Instance
     ^ ^ ^ ^ ^ ^  ^ ^ ^ ^
     | | | | | |  | | | |        Filesystem Operations (open/read/write)
     v v v v v v  v v v v
.---------.
|  Share  |                      Host Operating System Path (ro/rw)
:---------'---------.
|      Overlay      |            Non-Persistent Storage (rw)
:-------------------'---------.
|      Application Image      |  SquashFS File (ro)
'-----------------------------'

Since applications run in an isolated environment it will only see the files from its own file system. Files not backed by persistent storage are writable for applications, but wont persist over reboots since they are only backed by non-persistent RAM. In order to provide persistent storage to applications, even though the image is read-only, directories on external media can be shared from WeOS to an application. A bind mount is used to import the path to the application, as such the path can be mounted under a different path inside the application. E.g. a directory on a USB stick, /media/external/instance1/, can be mounted as /etc/ in the application.

Network

Applications may be connected to different layers of the WeOS networking stack. In a system with no applications running, a typical configuration may look something like this:

     .-------.  .-------.
     | vlan1 |  | vlan2 |       L3
     '---+---'  '---+---'
         '-.      .-'
       .---+------+---.
       |      br0     |         L2
       '-+---+--+---+-'
   .-----' .-'  '-. '-----.
.--+-.  .--+-.  .-+--.  .-+--.
|eth1|  |eth2|  |eth3|  |ssl1|  Port
'----'  '----'  '----'  '----'

At the bottom we see the physical and virtual ports, loosely this is any single port that can transport Ethernet, e.g. a 1000-baseT port or an OpenVPN tunnel in L2 mode. These are then typically connected to the bridge (br0) to enable L2 forwarding (switching). On top of the bridge sit the VLAN interfaces. This is usually where we enter the IP stack and thus it is between these interfaces that L3 forwarding (routing) takes place. Applications can be configured to integrate with the operating system on all three layers.

L3 Interface

WeOS                                     # Application Instance
     .-------.  .-------.    .-------.   #   .------.
     | vlan1 |  | vlan2 |    | myapp |   #   | host |
     '---+---'  '---+---'    '---+---'   #   '--+---'
         '-.      .-'            |       #      |
       .---+------+---.          |       #      |
       |      br0     |          |       #      |
       '-+---+--+---+-'          |       #      |
   .-----' .-'  '-. '-----.      |       #      |
.--+-.  .--+-.  .-+--.  .-+--.   |       #      |
|eth1|  |eth2|  |eth3|  |ssl1|   |       #      |
'----'  '----'  '----'  '----'   |       #      |
                                 '--------------'

In this configuration, the application is connected to the host by creating a virtual Ethernet pair (vEth pair) where one end (myapp) is attached to WeOS’s network namespace and the other one (host) is connected to the application’s ditto.

Depending on the WeOS configuration, access can be limited via the firewall, traffic can be masqueraded to appear to originate from the WeOS itself (NAPT), the internal subnet can be exported using a dynamic routing protocol like OSPF.

L2 Interface

WeOS                                       # Application Instance
     .-------.  .-------.                  #
     | vlan1 |  | vlan2 |                  #
     '---+---'  '---+---'                  #
         '-.      .-'                      #
       .---+------+---.                    #   .------.
       |      br0     +-------------.      #   | host |
       '-+---+--+---+-'             |      #   '--+---'
   .-----' .-'  '-. '-----.         |      #      |
.--+-.  .--+-.  .-+--.  .-+--.  .---+---.  #      |
|eth1|  |eth2|  |eth3|  |ssl1|  | myapp |  #      |
'----'  '----'  '----'  '----'  '---+---'  #      |
                                    '-------------'

Just like with an L3 Interface, communication between the host operating system and the guest application is through a vEth pair. The difference being that instead of using myapp as an L3 interface, it is attached to the bridge.

WeOS still has control over which networks the application can reach through the VLAN configuration. As the interface now works as a port, it can be a member of one or more VLANs.

In this setup, the application can be attached to the same broadcast domain as devices connected to the physical ports (eth1..eth4). I.e. it can resolve neighbors using ARP, send IP broadcasts etc. From WeOS’s perspective it is perceived as an additional port.

Exclusive Port Access

WeOS                       # Application Instance
     .-------.  .-------.  #
     | vlan1 |  | vlan2 |  #
     '---+---'  '---+---'  #
         '-.      .-'      #
       .---+------+---.    #
       |      br0     |    #
       '-+---+--+-----'    #
   .-----' .-'  '-.        #
.--+-.  .--+-.  .-+--.     #  .----.
|eth1|  |eth2|  |ssl1|     #  |eth3|
'----'  '----'  '----'     #  '----'

In this mode, an existing physical port is transferred to the application’s namespace. WeOS will not be able to use the port for any services. The application is free to send and receive any packets, setup netfilter and tc rules etc., just as with any standard NIC.

This mode is most often used in combination with either an L3 Interface or an L2 Interface. Imagine a firewall and routing application which is used to connect to, and filter traffic from, an ISP. It uses a physical port on one side to connect to the ISP (eth4). Once traffic has been filtered, routed, and possibly address translated, it is sent to WeOS via an L2 Interface (fw0/host):

WeOS                                  # Firewall Application
     .-------.  .-------.             # .-------.  .-------.
     | vlan1 |  | vlan2 |             # | vlan1 |  | vlan2 |
     '---+---'  '---+---'             # '---+---'  '---+---'
         '-.      .-'                 #     '---.  .---'
       .---+------+---.               #       .-+--+-.
       |      br0     +-------.       #       | host |
       '-+---+--+-----'       |       #       '--+---'
   .-----' .-'  '-.           |       #          |
.--+-.  .--+-.  .-+--.    .---+---.   #          |             .----.
|eth1|  |eth2|  |ssl1|    |  fw0  |   #          |             |eth3|
'----'  '----'  '----'    '---+---'   #          |             '----'
                              '------------------'

The application has full control over which traffic flows that are allowed to ingress the system, but WeOS can still be used to provide local services such as DHCP.

External Media

External media is a core component of the Application Hosting feature, serving as the primary storage location for application images and related data. This design ensures flexibility, scalability, and isolation between the operating system and hosted applications.

Image Storage

All application images are stored on external media. This approach decouples application content from the system root filesystem, reducing risk and simplifying updates.

Application Data

Applications can save their runtime files, logs, and persistent data on external media. This guarantees that application state and user data remain intact across system upgrades or application restarts. To enable an application to save persistent data, a media share has to be configured for the application.

Enabling Application Hosting

By default, Application Hosting is disabled in the operating system. This entails that no feature functionality is exposed until the license package is installed. To enable this feature, a dedicated license package must be installed, followed by a reboot. To obtain installation package, contact Westermo Network Technologies AB.

Enabling Application Hosting via CLI

Enabling Application Hosting via the CLI is done through the package context in WeOS.

example:/package/#> install proto tftp 198.19.10.1 app-hosting-license-signed.wmopkg

It is possible to install the license file using the following file transfer protocols: FTP, TFTP, SCP, SFTP, HTTP, or HTTPS. Refer to the Packages Support page for more information regarding installation of packages.

Enabling Application Hosting via WebGUI

Enabling Application Hosting via the WebGUI is done by navigating to the Maintenance tab and then selecting the Package page. Selecting Install Package will allow you the select the license file on your computer and upload it to the device.

Import of application images

To configure and run an application in WeOS, an application images needs to be imported to a a configured directory on external media. This can be done by placing the image directly in the external media directory before inserting it to the device or by importing it using built-in methods in WeOS. If you want to import an image in WeOS via CLI it is possible to navigate to file/app-hosting context and use the supported file transfer commands. See App-Hosting HowTo - Import Images for an example of how this can be done.

Alternatively this can done via the WebGUI in WeOS. Navigate to the Maintenance tab and enter the App Hosting page. Once entered press the Install Image button and follow the instructions which will allow you to upload an image from your computer.

Configuration of application hosting

Configuration of application hosting is done from the app-hosting configuration context in the CLI.

example:/#> configure
example:/config/#> app-hosting
example:/config/app-hosting/#>

Hardware Resource Allocation

With the application hosting feature it is possible to restrict how much of the hosts’ CPU and RAM the application are allowed to use. All applications will share the allocated resource and can not be set independently per application.

[no] cpu [LIMIT]

Percentage of CPU power to be shared amongst all applications.

LIMIT: The percentage of CPU power to be shared. Valid range: [10-50]
no: Restore to default value of 25%.

[no] ram [LIMIT]

Percentage of RAM to be shared amongst all applications.

LIMIT: The percentage of RAM to be shared. Valid range: [10-50]
no: Restore to default value of 25%.

Storage

The storage context includes two commands for specifying which external media on your device to search for application images and what path they are located at.

example:/config/app-hosting/#> storage
example:/config/app-hosting/storage/#>

[no] media <MEDIA>

Storage media for application image files.

Specify the name of the media as listed in the media boot context. To list all available media from current context use do show media. Only medias listed under external are available for application hosting.

MEDIA: Specify the external media for storage of application images.
no: Restore to default media, external.

[no] path [PATH]

Storage path to the application images.

Specify the path to the application images. The path is relative to the external media selected with the media command.

PATH: Specify the storage path for application images relative to the media.
no: Restore to default media, app/images/.

show

Show the current storage settings

Creation of an application

To create an application use the app command which will create a new app and open a new configuration context to configure the newly created application.

[no|show] app <NAME>

Configuration of applications.

NAME: Name of existing application. If the name does not exist a new application will be created.
no: Remove existing application.
show: Show configuration of existing application.

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

Upon entering the application configuration context it is possible to edit and configure the application.

[no] enable

Enable the application.

no: Disable the application.

[no] autostart

Enable autostart of the application. With autostart enabled the application will automatically start upon boot and reconfiguration of the system.

no: Disable autostart of the application.

[no] description [DESCRIPTION]

Set a description for the application.

DESCRIPTION: Description of the application, limited to a maximum of 255 characters.
no: Remove the description for the application.

[no] capability [CAPABILITY]

Set a capabilities for the application. For a full list of capabilities refer to the Linux man pages.

CAPABILITY

Set capabilities for an application. By default no capabilities are set and a good practice is to only set the capabilities needed for by the application since granting unnecessary capabilities can lead to security risks.

CAP_SYS_NICE: Real-time scheduling, CPU affinity, I/O scheduling, etc.
CAP_NET_RAW: Needed for raw sockets.
CAP_NET_ADMIN: Firewall, tunnels, sockets, protocols, TC, routing, etc.
CAP_NET_BIND_SERVICE: Allow binding to privileged ports.
CAP_FOWNER: Allows chmod, chown, etc.
CAP_MKNOD: Allows creation of device files.

no

Remove configured capabilities for an application.

[no] cmd [PATH]

Initialisation command for the application.

PATH

Path to initialisation command for the application.

Example: cmd /bin/sh - Useful to debug the bootstrap process.

no

Restores to default command: /sbin/init

[no] shell [SHELL]

Shell to use when attaching to the application.

SHELL

Shell to use when attaching to the application.

Example:
shell bash - used in Ubuntu-based images.
shell sh - used in Alpine-based images.

no

Restores to default shell: sh

[no] netns <user-ns|host-os>

The network namespace to assign an application to.

user-ns: The application will get its own, unique, network namespace.
host-os: The application will share network namespace with the host OS. This removes the possibility to reserve ports to the application.
no: Restores to default setting: user-ns

[no] share <RES-TYPE> <RES-NAME> [<as> <NAME>]

Manage shared resources to the application: ports, vEth-pairs, and external media directories. This command can be used to assign physical ports, manage virtual ethernet pairs, and share files/folders between the host OS and the app.

Note that the path won’t automatically be removed if the share is later removed.

RES-TYPE: Type of resource to share: ports, veth, or media
RES-NAME: Name of the resource to be shared, e.g. eth3, lan0, or external app/data
NAME: Name of the resource within the application.
no: Remove configured shares.

Examples:

Virtual Ethernet port for VLANs or iface.

example:/config/app-hosting/app-example/#> share veth fw0 as lan0

Move physical port eth12 to an application.

example:/config/app-hosting/app-example/#> share port eth12

Move physical port dsl3 to an application as eth1.

example:/config/app-hosting/app-example/#> share port dsl3 as eth1

Share host directory app/data on media external as /mnt in the application.

example:/config/app-hosting/app-example/#> share media external app/data as /mnt

[no] environment [NAME] [VALUE]

Set environment variables for the application environment.

NAME: The name of the variable within the application.
VALUE: The value of the variable within the application.
no: Removes configured environment variables.

Examples:

Set the value foo for variable FOO

example:/config/app-hosting/app-example/#> environment FOO foo

Set the value foo bar for variable FOOBAR

example:/config/app-hosting/app-example/#> environment FOOBAR “foo bar”

Empties the value of variable BAR

example:/config/app-hosting/app-example/#> environment BAR

[no] image <LABEL>

Specify the image an application should use. An application will not start if there is no image associated with it.

LABEL

The label of an image. Images are identified by their labels, to allow seamless switching between them, e.g. when upgrading an image.

In practice this means that whenever an image is upgraded, application does not have to be reconfigured to point to this new image, as it uses image label, which already points to the new image.

Multiple applications may use the same image, by specifying the same label.

Run do show app image to list available images and their labels.

no

Removes the configured image for an application.

show

Show the configuration for the current application.

Management and status commands for created applications

Management and status of images and created applications can be found under app-hosting context under admin exec mode.

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

[no] label <IMAGE> <LABEL>

Set/change the label of an image. Labels are used to identify images when configuring apps.

IMPORTANT: the effect of changing a label is only applied after issuing a reload [LABEL] command.

If the label already exists on another image, it will be moved. After moving the label to a new image, the reload [LABEL] command should be used to update and restart any running apps.

IMAGE: The image to set a new label for. Needs to be an existing image on the system.
LABEL: The name of the label. Maximum 15 characters.
no: Removes the configured label for an image.

reload [LABEL]

Update applications whose images match the label, and restart them. If no label is specified, all applications are updated and restarted. The effect of changing a label is only applied after a reload or reconfiguration. Useful if you have updated an existing image that you want to deploy to all applications using the old image.

LABEL: The label of an image you want to reload. All applications configured with this label are restarted.

attach <APP>

Attach to running application. Run exit or press ctrl-d to detach.

APP: Name of the application you want to attach to.

start <APP>

Start a stopped application.

APP: Name of the application you want to start.

stop <APP>

Stop a running application.

APP: Name of the application you want to stop.

restart <APP>

Restart a running application.

APP: Name of the application you want to restart.

show log <APP>

Show generated logs for an application.

APP: Name of the application you want to view logs for.

follow log <APP>

Follow generated logs for an application.

APP: Name of the application you want to follow logs for.

show [app [APP]]

Show a summary of application hosting.

app [APP]: Show summary of all enabled applications or the details of one application.

WeOS upgrade

It is strongly recommended to stop all applications before launching upgrade of WeOS. This is to allow smooth upgrade of the system and avoid out-of-memory issues, since applications altogether might consume up to 50% of system RAM.

HowTo Guide

For detailed instructions on how to enable the feature, import images, and run applications, refer to:

HowTo Application Hosting