Application Hosting - Configuration

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 applications are able to use. All applications will share the allocated resource and can not be set independently per application.

[no] cpu [LIMIT]

Description

Percentage of CPU power to be shared amongst all applications.

Options

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

[no] ram [LIMIT]

Description

Percentage of RAM to be shared amongst all applications.

Options

Option	Description
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>

Description

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 media listed under external are available for application hosting.

Options

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

[no] path [PATH]

Description

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.

Options

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

show

Description

Show the current storage settings

App Creation and Configuration

To create an application, or configure an existing application, use the app command. This will create a new app and open a new configuration context to configure the newly created application, if no app with the specified name exists. If the app exists, you will enter the configuration context of an existing app.

[no|show] app <NAME>

Description

Configuration of applications.

Options

Option	Description
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

Description

Enable the application.

Options

Option	Description
no	Disable the application.

[no] autostart

Description

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

Options

Option	Description
no	Disable autostart of the application.

[no] description [DESCRIPTION]

Description

Set a description for the application.

Options

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

[no] capability [CAPABILITY]

Description

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

note

With AppArmor strict configured, you will not be able to set all capabilities for the application.

Options

Option	Description
CAPABILITY	Set capabilities for an application. By default no capabilities are set and a good practice is to only set the capabilities needed 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]

Description

Initialisation command for the application.

Options

Option	Description
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]

Description

Shell to use when attaching to the application.

Options

Option	Description
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>

Description

The network namespace to assign an application to.

Options

Option	Description
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] apparmor <strict|relaxed> [complain-mode]

Description

Select AppArmor profile

note

With the strict profile, you will not be able to configure port and veth shares with none IP address option for the application. You will also not be able to set all capabilities for the application.

Options

Option	Description
strict	Offers high security and low flexibility.
relaxed	Offers low security and high flexibility, only configurable for administrators.
complain-mode	Allows applications to perform privileged operations that would normally be denied by the defined profile. Instead, these operations are allowed with an apparmor="ALLOWED" message to the syslog through the kernel audit subsystem. This is useful for debugging during application development, not recommended for production use. If the "complain mode" parameter is omitted, the profile runs in "enforce mode": violations are both logged and blocked.

The complete profiles are available at Application Hosting Appendix.

Options

Option	Description
no	Restores to default setting: strict

[no] seccomp <strict|relaxed>

Description

Select seccomp profile

note

With the strict profile, you will not be able to configure port and veth shares with none IP address option for the application.

Options

Option	Description
strict	Offers high security and low flexibility.
relaxed	Offers low security and high flexibility, only configurable for administrators.

The complete profiles are available at Application Hosting Appendix.

Options

Option	Description
no	Restores to default setting: strict

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

Description

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

• Paths won't automatically be removed if the share is later removed.
• Because of restrictions in strict Seccomp and AppArmor profiles, port and veth shares with none IP address option are limited to applications with relaxed profiles.

Options

Option	Description
RES-TYPE	Type of resource to share: port, 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.
OPTS	Share specific options, read-only and create for media shares and IP configuration for veth and port shares
no	Remove configured shares.

Examples:

Virtual Ethernet port for VLANs or iface. The application side of the vEth pair will be set to use DHCP for IP address assignment.

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

Move physical port eth12 to an application. The static IP address of 1.2.3.4/24 will be assigned to the port within the application.

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

Move physical port dsl3 to an application as eth1. No IP address will be assigned the port within the application.

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

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]

Description

Set environment variables for the application environment.

Options

Option	Description
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>

Description

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

Options

Option	Description
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

Description

Show the configuration for the current application.