NoTouch provides mechanisms to customize the image by adding 3rd party tools, like cloud or browser security components
NoTouch OS allows custom 3rd-party client modules to be distributed via NoTouch Center. These custom modules can extend NoTouch functionality in various ways. This articles explains
- what makes a custom "module"
- how to create a custom module
- how to trigger custom program execution
- how to add parameters to the configuration system
- how to distribute it via NoTouch Center
We encourage you to first read the Installing 3rd party apps article. It explains several basic concepts. The module development approach herein provides a mechanism to provide "enterprise-grade", multipliable functionality additions to NoTouch OS while maintaining both OS and package consistency.
Contents
- 1 Overall module structure
- 2 Filesystem creation
- 3 Event scripts
- 4 Custom parameters and values
- 5 First Time Wizard
- 6 Overwriting or modifying templates
- 7 Rolling out your custom module
Overall module structure
The module is defined as a filesystem tree that will be laid over the base image. This overlay will happen at runtime, "virtually", to ensure integrity of both base image and module.
The module must be in squashfs format. If you have not heard about squashfs consider it to be similar to ISO (CD/DVD filesystem), with the exception that it handles Linux/UNIX specialties and compresses its data very well. You are free to lay out the filesystem as you want, however we suggest to follow common Linux conventions, e.g. to
- put whole packages under /opt
- put binaries in /usr/bin
- etc.
Filesystem creation
For this step you need a Linux machine with the mksquashfs command. This command may be part of the "squashfs-tools" package, check your Linux distribution's manuals and documentation how to install the package and get a working mksquasfs.
Ideally, your filesystem tree resides in your development directory and resembles the final hierarchy perfectly. Thus, it may start with a directory named opt, and a subdirectory MyPackage in there, containing all your file.
In this directory you would call
mksquashfs opt mypackage.img
Awesome! This package can already be used and distributed, more about that later.
Event scripts
The operating system defines certain events that trigger custom code execution. This custom code can not only be supplied via configuration parameters - see Eventscripts for more information - but also by placing files into "magic" folders via your module. The root path for all these is /opt/etc/eventscripts. In this folder there needs to be a folder for any event you want your code to be executed on, as well as the actual scripts. The event names are:
- startup0
- startup1
- startup2
- startup3
- startup4
- xserverrc1
- xserverrc2
- xinitrc1
- xinitrc2
All events from startup3 on should have networking (provided the device has a connection). Thus, you would generally put hardware initialization related stuff into startup0, startup1 and startup2. Running a custom daemon that talks on the network should be placed in startup4. The xserverrc and xinitrc events mark the beginning and ending of execution of xserverrc and xinitrc, respectively. Please check generally available Linux documentation about these scripts.
Thus, if you want to run some custom functionality at system boot, after network initialization, you'd create a file named opt/etc/eventscripts/startup3/10_mystartup.sh
Note: The file must be executable (chmod a+x filename) and must, if it is a script, start with proper #!/bin/sh sequence. Otherwise it will NOT be executed.
The naming of the file is up to you. We recommend to follow the "number_name" notation so that an order of execution can be maintained.
Custom parameters and values
NoTouch is administered primarily via its parameters. The parameters make its way from the central management software to the client where they are used for Templates to generate configuration files. You can take advantage of this mechanism by:
- overriding default values of existing parameters
- add your own parameters
Default values
In many case simply changing a parameter default is enough customization to make the system do what you want. All you need to do is place a file or multiple files in a specific syntax into one of a set of magic directories.
The directories /config/cdefaults, /opt/etc/cdefaults, /etc/cdefaults are defined as the master directories for these custom default value sets. Each custom parameter set is a JSON file in a NoTouch-specific syntax as outlined down below. In other words - place a file in the correct syntax into one of these directories and see the parameter structure change. The actual file name is irrelevant.
{ "net.hostnamePrefix": "XYZ" }
Adding custom parameters
The directories /config/cparam, /opt/etc/cparam, /etc/cparam are defined as the master directories for these custom parameter sets. Each custom parameter set is a JSON file in a NoTouch-specific syntax as outlined down below. In other words - place a file in the correct syntax into one of these directories and see the parameter structure change. The actual file name is irrelevant.
Note: When creating your own module, will most likely want to place your file into /opt/etc/cparam.
{ "parameters": [
{ "code":"net.testparam", "dataType": "c", "defaultValue": "", "description": {"en":"Test parameter", "de":"Testparameter"}},
{ "code":"net.testoption", "dataType":"oo", "defaultValue":"on","description": {"en":"Test option", "de":"Testoption" }},
{ "code":"net.testoption2", "dataType":"o", "defaultValue":"1","description": {"en":"Test option 2", "de":"Testoption 2" },
"options": [{ "value": "1", "description": {"de":"Option Nummer 1", "en": "Option Number 1"}},
{ "value": "2", "description": {"de":"Option Nummer 2", "en": "Option Number 2"}}] }
],
"addOptions": [
{ "code": "connection.#.mode", "options": [{ "value": "hello", "description": {"de":"Hallo Welt", "en": "Hello World"}}]}
]
}
The available data types are:
- c. Character string.
- o. Options. Option list must be supplied, see above for format. Values are strings.
- oo. On/off. It is technically an option list, but you do not have to supply the list as the system knows the options are "on" and "off".
Parameters defined herein will be automatically added to both the local configuration GUI and NoTouch Center as soon as the client can talk to it and announce the availability of these new parameters. Furthermore, they can be used in all NoTouch templates under the $fc ("full config") hierarchy - more about the template mechanism here: Templates
First Time Wizard
By default, NoTouch will launch the First Time Wizard, unless it can connect to NoTouch Center immediately via the tcmgr host name and Autoassign is enabled. Depending on your use case this may not be desired. To switch it off, set general.showWizard to a defaultValue of "off" using the custom parameter definition as explained above.
Overwriting or modifying templates
As most of NoTouch is controlled via Templates, you may want to change the functionality therein. You are free to supply your own templates. As we constantly develop the system further, we highly recommend to check and compare with each new published version to make sure you don't build upon outdated functionality or miss a new feature.
As explained in Templates, the system reads from both /config/templates and /etc/templates. We also suggest to make it part of your startup event procedure to make sure you have the right templates in place.
Rolling out your custom module
Rollout is as easy as following these two steps:
- Make the module (the squashfs image) available via HTTP(S). If you don't have a webserver nearby use NoTouch Center. Hosting files (VA)
- Type in the URL to the module into the Extension->Module URL parameter. Save, and reboot the client.
Note: For startup events to trigger, this will need another reboot, because on the first reboot the module has not been present on the system yet.