Online help

Container

  1. General Information
  2. Container functionality
  3. Available resources
  4. Generated containers
  5. Container storage
  6. Exchanging files with a container
  7. Creating own containers

General Information

Linux containers (LXC) can be installed and executed on the router. A container is a virtualisation of an independent system, it "feels" like an independent computer with own

  • process management
  • User management
  • network environment
  • file and directory environment

The containers use the Linux kernel and drivers of the firmware. Direct access to hardware is not permitted so that the functionality of the router cannot be compromised.

Theoretically, an unlimited number of containers can be stored and started on the router. The number is limited by finite RAM and flash memory (refer to Resources).

The content of containers is treated like firmware images. The root file systems of containers is stored in the flash memory and listed in the web interface. Each container requires
  • a designator (e.g. "container_DEMO") that is stored in the root file system so that the root file system of the container can be identified.
  • an assignment of an instance name (e.g. "container1") in the profile of the router so that the container can be addressed via events and actions.
The designator can be selected freely, it will be stored in the profile of the router as well as in the root file system of the container ("/usr/share/image_name"). The instance name will be assigned fix. The assignment of designator and instance name can be selected freely.

Container functionality

Each container can be uploaded to the router via the web interface. If a container that has the same designator as an already existing container is loaded to the router, this will overwrite the old container. If one container shall exist in several instances on the router, for example a second instance of the icom Data Suite, the designator of the first container must be changed before uploading the second container.

Each container can be deleted from the router. In this case, all data that has been generated in the container, like log files for example, will also be deleted. The container will be removed from the profile of the router.

Each container can be activated or deactivated in the configuration. All active containers will be started up independently during system start. Active containers can be started or stopped using events and actions.

Each container can be downloaded from the router again in form of an update packet. Optionally, a container can be blocked for download by deleting the file "/usr/share/downloadable". This allows to realise a simple copy protection.

Each container has an own network interface that must be configured via the web interface. It will be connected to one of the IP nets of the router via a bridge. Connections can be treated like an independent device in the network using the netfilter rules. Routes must be created in the container if a communication with machines in other networks is desired.

Each container can receive and send messages via MCIP. This generates an interface to the firmware functionality (events and actions).

Each container gets a directory ("/data") mounted, in which own data can be stored that outlast an update of the container (configuration, logs). This directory will only be deleted if the whole container is deleted.

Each container has the configuration option to consider the special subdirectory "/data/etc" as configuration for container applications. Then, this configuration will be added to the update packet as an attachment when downloading a profile, so that the router and the settings of the application can be stored together in a container. The designator of the container is also specified in the manifest so that the profile can be assigned again to this container with the upload without being dependent on the internal container name (e.g. container1). The configuration file of the container may have any format, so it can be a database or only a simple ASCII file for example.

Each container gets the enabled hardware resources entered as device nodes, irrespective of which services use these device nodes already. Resources are serial interfaces for example.

Each container can write its console output in a log. This allows to identify the possible reason for a container that does not start.

Each container can optionally be assigned a licence stored on the router that can be used by the application in the container to unlock functionality.

Available resources and applications

The firmware of the router reserves itself 64 MByte RAM. The remainder will be apportioned equally among the container instances to be started.

Half of the CPU computing time is guaranteed to the router firmware. The remaining computing time get the container instances proportionately. However, the computing time shares are only limited if they are actually requested by the individual beneficiaries. If the firmware and all started container instances do not perform any computations, the full computing time is available.

Flash memory is not limited. The firmware and all container instances must share the available memory. There is no quota since an apportionment like for the volatile resources RAM or CPU computing time cannot be changed later in case another container will be added.

Generated containers

Containers that have been generated by the firmware provide a minimum environment that can be used as a starting point for own applications. A user "root” with the password "root" exists in the containers. The password shall be changed immediately upon generating the container due to reasons of security. Any new users and groups can be created.

A container created by the firmware contains:

  • the init system "finit"
  • the tool collection "busybox"
  • an SSH server "dropbear” that waits for connections on port 22
  • the log daemon "metalog"
  • the authentication system "PAM"
  • basic libraries (libc, libm, libpam, etc.)
  • the Lua interpreter and the associated library
  • a mounted TMPFS
  • the MCIP server and the libmcip
  • the tool collections "mcip-tool", "get-input" and "get-pulses" for receiving events from the router firmware.
  • the tool collection "sms-tool" for sending and receiving SMS
  • the tool collection "cli-cmd" for easy access to the CLI (Command Line Interface) of the router

A container contains the following directories and files:

  • /bin/mcip-tool
  • /bin/sms-tool (sending or receiving SMS)
  • /bin/get-input (reading digital inputs)
  • /bin/get-pulses (receiving pulses at digital inputs)
  • /bin/set-output (switching digital outputs)
  • /bin/cli-cmd (sending CLI commands to the router)
  • /bin/container (starting, stopping or restarting containers)

These tools have a help text that is displayed using the parameter "-h". The tools assist for receiving SMS (sms-tool), events at the inputs ("get-input" for level changes and "get-pulses" for pulses at the inputs). "mcip-tool" can be used to send and receive messages via MCIP what allows to exchange messages between processes within one or different containers. "set-output" can be used to switch outputs, if access to the CLI of the router is allowed in the container without authentication. "cli-cmd" can be used to read out and change the configuration of the router. Status information of the router can be queried. "container" can be used to start, stop or restart containers, if access to the CLI of the router is allowed in the container without authentication.

  • /data
    Additional flash memory will be mounted in this directory when starting the container. The data stored here will not be overwritten by a re-import of the container. The directory is suitable for data that shall outlast a container update. It will only be deleted if the whole container is deleted.

  • /data/etc
    This directory can optionally be downloaded bundled with the profile. If the profile of the router is downloaded as a binary file and this option is enabled for a container, the content /data/etc will be packed as a tar archive and added to the update packet with the profile of the router. The designator of the container will be stored in the manifest of the update packet so that the tar archive can be assigned to the right container again when re-uploading the update packet.

  • /data/log
    This directory can be used as permanent storage that outlasts container and configuration updates. Optionally, the directory /var/log contained in the container can be deleted and be replaced by a symlink to /data/log. The applications that usually write their log files to /var/log, do not have to be reconfigured in this case.

  • /devices
    Device nodes will be created in this directory that are made available to the users in the container by the firmware of the router. If a plug-in card with serial interfaces exists for example, a device node X_serialY will be created. X indicates the slot number in which the card is plugged in. Y indicates the instance of the serial interface.

  • /devices/mcip.socket
    This is the socket file for the MCIP socket that can be used to send messages to the router firmware or other containers.

  • /devices/cli.socket
    This is the socket file for the (Unix-Domain-Socket) to the CLI (Command Line Interface) of the router. This constitutes an interface to the router configuration without being dependent on an IP configuration in the router. This interface is suitable to generate alternative configuration interfaces in the container. Tools like "socat -u /devices/cli.socket -" can be used to operate the CLI from the shell without having to establish an IP connection to the CLI.

  • /devices/cli_no_auth/cli.socket
    This is also a socket file for the (Unix-Domain-Socket) to the CLI (Command Line Interface) of the router. I contrast to /devices/cli.socket, this CLI access does not require an authentication. Therefore, the container does not have to know the access data. Whether access to the CLI is permitted and which rights are granted (status requests, read access only, full read/write access) must be configured in advance in the container configuration of the router.

  • /devices/wakeup
    For routers that support "Suspend to RAM", this file contains the number of seconds the router has spent in "Suspend to RAM". It will be pre-initialised with 0 upon startup of the router. This permits to detect that a "Suspend to RAM" has not yet occurred. inotify can be used by the user to get informed in the container, if this file has changed and thus detect that a "Suspend to RAM" cycle has occurred and has been ended.

  • /devices/device_info.json
    The file contains device information such as serial number and hardware revision. The information is displayed in JSON format and corresponds to the information in the reply from the REST endpoint /api/v2_0/status/device_info.

  • /etc/finit.conf
    "finit" is used as init system; this is the configuration file of the init system. Lines preceded by "run" start programs once upon system start. Lines preceded by "service" start programs that shall be restarted again automatically if they close. These programs are not allowed to put themselves into the background.

  • /licence
    The licence stored on the router and assigned to the container during container configuration will be made available to the container in this directory.

  • /shared
    A TMPFS (temporary file system) with a size of 20 MByte is mounted in this directory. Each container has access to this file system. This allows to exchange files between containers easily, realise simple inter-process communication with "pipes" or realise shared memory across containers. All files contained will be deleted after a restart. The size of the TMPFS cannot be changed.

  • /usr/share/content.html
    The file usually contains a short description of the container content or information about how to use the container content, e.g. SSH login data, server ports, etc. This information is displayed in a new browser window upon a click on the icon, even if the container has not yet been started or configured. Therefore, it is recommended to format the content using HTML.

  • /usr/share/created
    The file contains the firmware version that has been used to generate this container by the router.

  • /usr/share/downloadable
    If this file exists, the container can be downloaded from the router in form of an update packet. The content of the file is not important; it may also be empty.

  • /usr/share/mount_allow
    If the container is not-downloadable, the folders and (automatically) their sub-folders, in which a container storage may be included, are permitted in this file. The format is one folder per line.

  • /usr/share/image_name
    This file contains the designator of the container. This file must never be modified manually since the designator connects the configuration of the container with the container image. The designator must always be changed via the firmware (web interface or CLI).

  • /usr/share/version
    This file is a proposal for storing the versioning of a container.

  • /tmp
    This directory contains a TMPFS. The size can be configured in /etc/finit.conf. Some symlinks that typically only contain temporary data point to this directory: /run, /var/lock, /var/run

Container storage

The container storage permits to upload files to the router in form of an update packet. Individual paths of the container storage can then be made available to each container in a configurable path with read or read and write permissions. The paths in the container must explictly be permitted in non-downloadable containers using the (white-list) file /usr/share/mount_allow explained above. The two udate packet file types differ in their behaviour for folders that exist in both, the container storage and the update packet. The folders and their content will be deleted first for "Full Storage". The content of the folders is merged for "Incremental Storage", existing files that are not in the update packet will remain. The file authorisations stored in the update packet will be taken over.
All containers will be restarted following each upload or deletion and are available again after a few seconds. This requires a new login to the containers.

Exchanging files with a container

In order to copy files from the container or to the container disregarding container storage, "scp" seems to be appropriate since an SSH server is already installed in generated containers. An SSH client like "openssh" or "putty" is necessary. A possible call is: "scp root@192.168.1.1:/root/readme.txt ./".

wget is also installed in the container so that files can be retrieved from web servers into the container. To do this, login to the container via ssh and call wget: "wget http://webserver_domain_or_IP/applikation". If the downloaded file is a binary and is to be executed, the "execute" permission must also be set: "chmod 755 application".

The busybox applets are also available in the container:

  • "ftpget" and "ftpput" for contacting an external FTP server
  • "tftp" for contacting an external TFTP server
  • an FTP server "ftpd"
  • an TFTP server "tftpd"
  • an HTTP server "httpd"

Creating own containers

A container created by the firmware can be used as starting point. After downloading as update packet, this package must be unpacked with "tar -xf <filename"> into a new directory. The manifest and the actual container are now on hand. The container is also a tar archive.

In order to be able to unpack and modify a container locally, it is compulsory for the tar archive to

  • unpack it to a file system that contains the Linux permissions (e.g. ext3, ext4, btrfs, but not VFAT or NTFS)
  • unpack it as "root" that contained device nodes can be created.
  • unpack it with the tar parameter "--preserve-permissions"

Upon modifying the files, the root file system must be packed as tar archive again (tar cvf ../<filename.tar>). The new MD5 checksum of the new tar archive must be entered into the manifest. If the file name has changed, this must also be adjusted in the manifest. The manifest and the new tar file form in a new, common tar archive the new update packet.

Back to overview