From Thecus Wiki

Contents 1 General 2 Linux 3 Module Contents and Structure 4 Creating the Module 5 Testing the Module 6 Publishing 7 Unpacking Modules 8 Getting binaries for your modules 9 Installing a Daemon (Server) with a Module 10 Remarks

General

This page describes the structure of modules written for the N5200 and how to create them.

Starting with firmware version 1.00.06.5 Thecus have implemented a module framework for the N5200 which is basically the same as that of the N2100.

For all firmware versions up to and including 1.00.05 another method was created in order to upload something like modules. That method (mis-)uses the firmware upgrade method and for this reason these modules are called pseudo-modules.

A description of their structure and how to create pseudo-modules can be found here: Pseudo-Modules for the N5200 with firmware <= 1.00.05

The rest of this page describes the "official" module framework introduced with firmware 1.00.06.5.

Initially you might want to take a look at this PDF document that describes how to create modules.

Linux

As the operating system running on he N5200 is Linux, creating modules for the N5200 is most easily done on a Linux system, even though it is possible to create modules on other operating systems too.

For the following descriptions it is assumed you are working on a Linux or some other kind of UNIX operating system.

Module Contents and Structure

Note! This is a work in progress and it's likely that some of this information is incorrect until such time as this notice is deleted.

A module file is a compressed TAR file. Modules distributed here have an extension of .bin, rather than .tar.gz. The tar file contains one root directory with the same name as the module which is always composed of just upper-case characters. In this directory there are:

• Two mandatory sub directories:
  • /Configure - Contains basic information about this module in two files:
    • install.rdf - An XML file which contains the module name, description, version, author and homepage, and states which version of firmware the module was designed for.
    • license.txt - The license terms for the module.
    • The information in both files is displayed when a user clicks on the module's description on the Module Management page of the N5200's web interface.
  • /Shell - This directory contains hook scripts which are invoked by the N500 when a user installs, uninstalls, enables, disables or checks for updates on the module. The following shell scripts must be present:
    • install.sh - Invoked when the module has been uploaded. This script sets up the module environment but should not do anything to enable it.
    • uninstall.sh - Invoked when a user uninstalls a module.
    • enable.sh - Invoked to enable or disable a module.
    • update.sh - Invoked to check for module updates. (The N5200 does not actually invoke any script when the user presses the "updates" button up to and including firmware 1.00.07 and this is a known bug.)
• A small 16 byte binary file named Thecus. The content is the same for all modules and a module won't install without it. This file contains the string "www.thecus.com", encrypted against a DES key, which identifies the module as a module. (A description of how to create this file is here.

The N5200 actually only expects install.rdf and install.sh to be present in the module, but it's convenient to package up the other scripts in the same directory as install.sh anyway.

On installation:

• The content of the module's single root directory is unpacked to /raid/data/tmp/module.
• The install.sh script is invoked. This script runs with root privileges and can do any setup that it needs to do. It must output either pass or fail to stdout to indicate whether it was able to correctly initialise.
• If the script outputs a pass then data is extracted from install.rdf and added to two tables in a database of modules in /raid/data/module/cfg/module.db. This causes the module to appear as installed on the web interface.

Two important jobs that install.sh should do:

• Copy the uninstall.sh, enable.sh and update.sh scripts to /raid/data/module/MYMOD/shell, where MYMOD is the actual module name. Before doing this it must create both the MYMOD and shell sub directories. Note that while install.sh runs from a directory named Shell (with a capital S) the other scripts must be copied into a directory shell (lower case S).
• Copy a software license to a file named COPY in the MYMOD directory. Modules written so far do this by simply copying from license.txt.

Creating the Module

To start very quickly you can get the N5200_HelloWorld_1.00.01.zip file that I've created and modified it.

It uses the base util scripts created by Andreas Vogel to manage in a better way the installation process (send email, logs and more...)

So what you have to do is get the file unzip go inside the dir HelloWorld and modify the file like explained in the previous part. I just summarize here:

 - cd Configure
  - vi install.rdf
 - cd ../Shell
  - vi install.sh
  - vi module.rc
  - vi uninstall.sh
 - cd ../www
  - vi index.htm 
 - cd ../../
  - make

So if everything is configured correctly you will create a file HelloWorld.mod that is the new test module.

Testing the Module

Warning! All module scripts run as root on the N5200! This gives them ample opportunity to destroy the internal integrity of both the firmware and your data files. Do as much testing as you can on a non-critical alternative Linux box or VM before you upload a module to the N5200 for the first time.

Some prerequisits for testing:

• You should have installed already SSHD and SYSUSER module for console access to the N5200
• You should be familiar with linux basics
• You should now how to use vi - the only available editor
• if something on the installation and enabling of Your module fails, the You can to a manual remove of the module

rm -R /raid/data/module/YOURMODULE
rm /raid/data/module/cfg/module.rc/YOURMODULE.rc
/opt/bin/sqlite /raid/data/module/cfg/module.db "delete from module where name = 'YOURMODULE'"
/opt/bin/sqlite /raid/data/module/cfg/module.db "delete from mod where module = 'YOURMODULE'"

Publishing

Upload the module to your website. If you don't have a website you may contact the ThecusWiki Admins and they can place it on this site.

Afterwards publish the new module using the Module Template and afterwards place a link on the Module List.

Unpacking Modules

To be done.

Getting binaries for your modules

It is not clear what Linux distribution Thecus uses to build N5200 binaries. However, due to the fact that the N5200 is using an Intel Celeron processor and PC-compatible hardware, almost every 32 bit Linux executable using a standard set of compatible shared libraries can be used. It seems that while a number of new linux distributions are not compatible (IE RHEL5/CentOS5) older versions are.

The Wiki owner has compiled the actual BusyBox package on his laptop running SuSE Linux 10.0 and runs on the Thecus NAS without any problems. Other users have reported success building binaries on RHEL4/CentOS4/SL4. These distributions seem to be library/binary compatible with the latest (V2.00.15) firmware.

Installing a Daemon (Server) with a Module

To be done.

Remarks

• secure all module directories from direct web access

Since the modules installation directory can be accessed directly through a web browser by design, module deveopers should place either place .htaccess files into all directories directly below the module base directory (except for www)

Order allow,deny
Deny  from all

Alternatively place a single .htaccess file into the modules base directory and use the <Location> directive to limit access to the www directory.

• check for a valid admin session

Add the following (or similar) to all pages:

if ( ! ( isset($_SESSION['admin_auth']) && $_SESSION['admin_auth'] === 1 ) ) {
    die("no access");
}

You may need to add a call to session_start() if the pages are not called through the module framework

• do not fail if during "Enable Module" the startup of a daemon failed.

If the enable script returns an error because for example it was not able to start a daemon the module wioll stay in state disabled and you will not be able to access the module configuration to actually fix the issues that caused it to fail. Best is to only let the enable function fail if the module installation is corrupted

• force all files within the installation package to be owned by root:root

Use the following syntax to make all files/directories in the module package file owned by root

tar -cf MYMODULE.mod --owner 0 --group 0 MYMODULE/

• make use of the escapeshellarg and escapeshellcmd PHP functions

If your module needs to run shell commands all arguments should be escaped using the above functions