Application Hosting - 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.