Synology package files

Synology Packaging Files

Since firmware 722, a new 'package management' option has been added to the disk station manager which provides a simple way for non-experienced users to 'update' their disk stations with other programs and possibilities. This update can be done via a special kind of package baring the extension ".spk", especially made for Synology disk stations.

Package Structure

An .spk file is nothing more then a tar file, containing a standard structure and files. It is not related to any existing .spk packaging formats that are known and it looks like this .spk structure is designed/defined by Synology themselves and in no way compatible with any other packaging methods. You can 'unpack' any spk file simply by untarring (tar -xvf filename) the file. Every package will contain the following files/directories (mind the capitals!):

INFO	This is a file containing information that will be displayed and used during installation. It consists of multiple key="value" lines. The following keys are used: package The - unique! - name of the package, as will be displayed during install, in package manager overview and will be used as directory name under which the whole package will reside. version guess what... maintainer Who is the 'owner' of the package. Only used for information purposes description A small description of the package. Only used for information purposes arch CPU Architecture. "noarch" if it will fit all DiskStations. Other "arch" values can be "x86", "88f6281", "88f6282", "88f5281", "ppc853x" or "ppc854x", depending on the CPU. For models with the PPC 8241 CPU there are two different values for "arch" depending on the Linux version. It is "powerpc" for Linux 2.4 and "ppc824x" for Linux 2.6. Calling "uname -r" on a shell shows the Linux version. adminport optional. If the program is installed and has it own "administration" webpage, this will be the port number the server listens to. adminurl optional. If the program is installed and has it own "administration" webpage, this will be the rest of the url. (URL becomes http://own-name-of-nas:adminport/adminurl) firmware optional. Minimum version of DSM firmware that is required to run the package. reloadui optional. Set to "yes" if there is a need to refresh the complete browser screen after starting (like adding/enabling icons in left pane). package_icon optional. Base64 encoded icon of the package, used by DSM 3.2 and up. The size is free, but the display size is 72x72, regardless of the aspect ratio.
package.tgz	This is a compressed (gzip) tar file containing all the files that are needed. The installer will automatically unpack this package. The file has to have this name exactly, otherwise installation will end with an error "invalid file format".
scripts	This is a directory containing multiple shell scripts: preinst This script is run before installing the package. It is the good place to check if the installation requirements are met. Returning anything other than 0 will stop the installation. postinst This script is run after the installation of the package. It is the good place to ensure that all file permissions and ownership are right. Returning anything other than 0 will stop the installation. preuninst This script is run before removing the package. It shall do the reverse action of the postinst script. Returning anything other than 0 will stop the uninstallation. postuninst This script is run after the package has been removed from the system. Returning anything other than 0 will stop the uninstallation. preupgrade (optional) This script is run when a package is upgraded through the "upgrade" functionality of the package manager, before doing the uninstallation of the old version (before its preuninst). Returning anything other than 0 will stop the upgrade. postupgrade (optional) This script is run when once package has been upgraded, after the new version has been installed (after its postinst). Returning anything other than 0 will stop the upgrade, but it is too late to roll back. start-stop-status This script is used by the package manager to start, stop, and get the running status and log file location of the package once installed. It will be copied in the directory /usr/local/etc/rc.d/<packageName>.sh and run from this place. It will always be given an argument via the package manager. Hitting "run" in packagemanager will start this script with the start argument Hitting "stop" result in stop When (re-)loading the package manager page, it will also call the script for a status update. When accessing the log tab of the package info page, the argument will be log, The package manager expects the filename of the logfile to be printed out to STDOUT. It will then read the content of that file and display it. In all cases, returning '0' means 'all ok' and '1' means 'error occurred' or 'not running' (when checking status).

Installation process

When uploading a .spk file, the file will be uploaded to a temporary directory (can be found in the environment variable 'SYNOPKG_PKGINST_TEMP_DIR, during the running of the 'preinst' script). Normally, this will be in a '@tmp' dir on the root of volume1. It will be unpacked (not the package.tgz yet) and script 'preinst' will be called. After that, the user has to select a volume to install to.Under the root of this volume, a '@appstore will be created, if this directory not exists already. In this directory, a directory using the name given in the INFO file as value of key 'package' will be created (this name can also be found in the SYNOPKG_PKGNAME environment variable). The 'package.tgz' will be uncompressed and unpacked under that directory (which can be found in environment variable 'SYNOPKG_PKGDEST'. After this, in the directory /var/packages will be a directory created by the name of the package. In this directory there will be the scripts dir and INFO file of the package. Also a link called 'target' which will point to the unpacked directory under your @appstore dir in the destination volume. The directories under /var/packages/ will be used by the packagemanager. Finally, the script 'postinst' will be called and all temporary files will be removed.

Note that the 'adminport' option under INFO is a bit strange. It will only be used when displaying management page URL if the program status returns 'running' . The packagemanager will automaticly create the url out of 'http://' +hostname+':'+adminport. There is no way to change that url other then the port number.

Adding a 3rdparty program into a package

Even before the firmware 722, it was possible to create a '3rdparty' option in the disk station manager. Using the package installer, this will become much easier to do. It's quite simple:

1. To install your application on the DSM Management Menu, create an application.cfg file and image directory as described in '3rd party apps integration guide'
2. To install your application on the DSM Desktop, create a desktop.cfg file.
3. place that file along with program files, images, cgi scripts and all in package.tgz
4. Create a softlink (ln -s ) from /usr/syno/synoman/3rdparty/webman/$SYNOPKG_PKGNAME to $SYNOPKG_PKGDEST in your postinst script and make sure link is removed in the postuninst
5. Make sure start-stop-status script will always return '0' (or '1' for status info, since nothing is running all the time)
6. Create other files (scripts, INFO) and pack them (tar -cvf whatevername.spk *) into a .spk .

That's it. By installing it, it will also create a 3rdparty directory. If you press 'reload' you will see the package can also be found in the navigation tree. Uninstallation removes all the files of the package, including the softlink.

Tips for creating packages

1. Since most keywords and values might be parsed by unix programs and shell scripts during the installation process, it is recommended not to use any special characters (like '"';-[!@]\ ....) in script and package names, just stick with regular ASCII.
2. Installation is done under 'root' rights. THIS CAN BE EXTREMELY DANGEROUS. Be sure in what you are doing. Stay away from any 'normal' directories like /sbin /usr/bin /usr/syno/bin, unless you know what you are doing. Dont install .spk unless you trust the sender or checked the installation scripts.
3. Installing and using .spk files is at your own risk. Don't blame Synology -or others- for not working correctly or not giving the right answers.
4. Creating softlinks from /usr/syno/synoman/webman/3rdparty/ to the package on a volume is a better idea then to place all under /usr/syno... directory itself. Doing this way, you prevent that disk doesn't run out of space
5. You can add your 'own' key="value" pairs to the INFO file. These will be ignored by the installer, but can be used for 'global configuration keys' during your post/preinstall scripts.
6. Make sure the read-write-execute rights are in place. Use the 'chown' and 'chmod' commands in the scripts to make sure they are.
7. 3rdparty options always points to webpages. If you are using the same webserver/port as the disk station manager, '.nph' files will not work (without altering configuration), but ".cgi" files will. They will be treated the 'old cgi way', which means the webserver just executes them and the cgi program makes sure they spit out the relevant HTML code.
8. Because the installation process is called via the webmanager interface, it is possible to retrieve more information via the environment variables that might be needed during the installation process. You can think of "USERNAME" => logged in user or "DOCUMENT_ROOT" => handy to know where to install .html or .cgi files for use under the webmanager interface.

Example

You can find a example .spk file 'curcon' at http://www.mertymade.com/syno/. After installing this package, you will notice a 3rdpary entry in the navigation tree on the left with the name 'Current Connections'. When clicking on it, it will show all network and windows filesharing connections from/to the diskstation. It isn't that spectacular, but a good working example how to use packages and 3rdparty option.