LEAFOS modules are containers for the files which are necessary to extend the functionality of the base system. LEAFOS supports two module types: packaged application modules and system extension modules.

After collecting all the 3rd party application related items (i.e. application binary, application dependencies, application launcher) as described in the 'Considerations before starting LEAFOS modules preparation' section in the KB article here, you will need to put them into a SquashFS image. The directory structure in the SquashFS image needs to reflect the structure of the LEAFOS root file system. The contents of the packaged application module is laid over the LEAFOS root file system when the packaged application is launched.

We have prepared several reference examples on how to package different standard Linux applications (Google Chrome browser, Microsoft Edge browser, Firefox browser, Zoiper and Linphone softphones).

<Insert link>

You will find the build script for each reference application and its corresponding packaged application module, which can be deployed to LEAFOS.

In the root folder of the SquashFS image containing packaged application module, there must be a file with named ‘package.json’. This file is mandatory and contains the meta-information describing the packaged application module. LEAFOS requires the information from that file to properly present the packaged application on the local application list, to launch the application and to manage its configuration settings.

The ‘package.json’ file must contain the ‘packaged application meta-information’ JSON object.

‘packaged application meta-information’ JSON object specification

Property	Data type	Description
type	string	The type of the module. For packaged application modules it must be “application”.
name	string	Application name to be presented to the user on the list of local applications.
icon	string	Path to a PNG file containing the application icon. The picture contained in this file will be presented to the user on the list of local applications. If no path will be specified, LEAFOS GUI will use a generic icon.
executable	string	Command to be executed by LEAFOS when launching the packaged application. This can be the command for starting the application launcher described above.
params	string	Semicolon-separated list of command line parameters for the executed command.
settings	JSON object	‘settings’ JSON object, which will keep the paths (separately for files and folders) where the application stores its configuration. See below.
app id	string	The Application ID of the packaged application. This value will have to be used by custom application launcher to identify the application when asking for the value of a named parameter.
architecture	string	Binary architecture of the executable and library files contained in the module. For LEAFOS(X86) this property must be set to “x86_64”.

‘settings’ JSON object specification

Property	Data type	Description
files	string	This can be a semicolon-separated list of device configuration file paths. In Guest Mode, the files will be removed upon termination of the local application session. In User Mode (Guest Mode not enabled), the files will be linked to a persistent storage location when starting a local application session and no removal will take place on session termination.
folders	string	This can be a semicolon-separated list of device configuration folder paths. In Guest Mode, the folders will be removed upon termination of the local application session. In User Mode (Guest Mode not enabled), the folders will be linked to persistent storage location when starting a local application session and no removal will take place on session termination.

‘packaged application meta-information’ JSON object example

{

       "type": "application",

       "name": "Firefox",

       "executable": "firefox-launcher",

       "icon": "/usr/lib/firefox/browser/chrome/icons/default/default32.png",

       "params": "",

       "settings": {

                    "files": "",

                    "folders": "~/.mozilla/firefox"

        },

       "app id": "firefox",

       "architecture": "x86_64"

}

 

When all files required by the packaged application module are collected, the module can be built using the Linux ‘mksquashfs’ command.

Creating System Extension modules

After collecting the items necessary for your system extension module, you will need to put them into a SquashFS image. The directory structure in the SquashFS image needs to reflect the structure of LEAFOS root file system. The contents of the system extension module is laid over the LEAFOS root file system at an early stage of the LEAFOS bootup process. The contents of the system extension module can complement or replace existing LEAFOS system components.

Each system extension module needs to contain a meta-information file in the 'etc/custom-modules' directory of SquashFS file system. Each system extension module should only contain one file in this directory. Although the file name is not important we suggest to use a name corresponding to the module’s purpose or contents and the ‘.json’ extension. This file must contain the ‘system extension meta-information’ JSON object describing the system extension module, especially its binary architecture.

‘system extension meta-information’ JSON object specification

Property	Data type	Description
type	string	The type of the custom module. For system extension modules it must be “extension”.
name	string	Optional. Name of the system extension custom module (for informational purposes only).
architecture	string	Architecture of the binaries in the custom module. Possible values: “x86_64” or “all”. “all” should be used if the module only contains files (like shell scripts), which are compatible with all architectures.

‘system extension meta-information’ JSON object example

{

    "type": "extension",

    "name": "Some custom module",

    "architecture": "x86_64"

}

 

 When all files required by the system extension module are collected, the module can be built using the Linux ‘mksquashfs’ command.

Passing custom application configuration parameters to application launcher

If your custom application requires configuration parameters, it will require a launcher, which (prior to launching the actual application) will need to take the configuration parameters from the device configuration and apply in application-specific way (usually write into some files). The parameters can be provided in custom application configuration as ‘parameter name’ – ‘parameter value’ pairs.

Meaning of Application ID

Each custom application which requires configuration parameters needs to have a unique identifier. This identifier (referred to as Application ID) can be any character string. It will be used by the application launcher when requesting the values of the configuration parameters stored for the custom application in device configuration. For packaged applications the Application ID value will be taken from the “app id” property of the packaged application meta-information JSON object described in the previous section. When defining the configuration parameters for custom applications of system extension type, the Application ID needs to be provided alongside the actual parameter names and their values. This Application ID will allow LEAFOS to identify the custom application when the application launcher requests the values for named parameters.

Requesting the values of named parameters

Custom application launchers can use the ‘rx-get-custom-app-param’ utility for requesting the values of named parameters. The syntax of ‘rx-get-custom-app-param’ utility is:

rx-get-custom-app-param APP_TYPE APP_ID PARAM_NAME

APP_TYPE is the type of custom application. It must be “package” for packaged applications or “system” for system applications.

APP_ID is the Application ID.

PARAM_NAME is the name of the requested configuration parameter.

For example: let’s assume there is a custom application which can show itself in a window with a configurable title. The person preparing the LEAFOS module for that custom application wants to give the administrator deploying it to LEAFOS devices the ability to freely define this window title. Module author created for the custom application a launcher app which requests the value of “WinTitle” parameter. This parameter can be defined for the custom application locally in the LEAFOS device Setup GUI or can be pushed to the device from PMC Endpoint Manager. Packaged application module has been created for that custom application and the “app id” property of the meta-information JSON object has been set to “my_custom_app”. Application launcher will receive the “WinTitle” parameter value configured for the custom application when the ‘rx-get-custom-app-param’ utility will be called as following:

rx-get-custom-app-param package my_custom_app WinTitle

The launcher can use retrieved string to configure the actual application to display its window with the desired title.

Requesting names of generic files uploaded to LEAFOS devices

There is yet another utility which the launchers of custom applications can use. It is useful when the custom application needs to process a file (e.g. containing application configuration). The ‘rx-get-file-md5-hash’ returns the MD5 hash value of first generic file found which has been uploaded to LEAFOS device with the name given as ‘rx-get-file-md5-hash’ parameter. The returned MD5 hash value also represents the real name of the generic file physically stored on the LEAFOS device in /NC/configuration/files folder.

Reference packaged application prepared by NComputing

We have provided several reference examples on how to package different standard Linux applications (Google Chrome browser, Microsoft Edge, Firefox, Zoiper and Linphone softphones). You can find them here:

<Insert link below>

You will find the build script for each reference application and its corresponding packaged application module which can be deployed to LEAFOS.

The launcher of the Google Chrome browser included in the Chrome’s packaged application module accepts a set of configuration parameters, which the administrator can use to customize the Chrome browser behavior:

Parameter name	Parameter value description	Parameter value example
urls	Semicolon-separated list of URLs of the web pages to be opened on Chrome’s cards.	https://ncomputing.com; https://google.com
incognito	Controls the incognito mode of Chrome browser. Possible values: yes, no.	yes
window size	Size of Chrome browser window. Possible values: ·      <width>x<height> ·      default ·      fullscreen ·      maximized ·      kiosk	1500x900
accepted languages	Comma-separated list of country/language codes: <2-letter-lang-code>-<2-letter-country-code> or <2-letter-lang-code>, …	de,en-US
offer translations	Controls Chrome’s built-in we page translator. Possible values: yes, no.	no
custom parameters	Semicolon-separated list of Chrome browser command line parameters. Refer to: https://support.google.com/chrome/thread/ 119899385/list-of-command-line-switches-for-google-chrome https://www.ghacks.net/2013/10/06/list-useful-google-chrome-command-line-switches/	--no-referrers;--disable-gpu

Once the 'Packaged Application' module is created, click here to learn how to 'deploy' these modules to LEAFOS devices.