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", "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.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 unix sh shell scripts:

• postinst
• postuninst
• preinst
• preuninst
• preupgrade
• postupgrade
• start-stop-status

all *inst scripts are used during installation and uninstallation of the package. Returning anything other then '0' as result will break the installation or uninstallation. preinst will be called before anything is installed (this is the place to check if all installation requirements are met, for example), postinst after (to set the file rights of the installed files, for example).

Same fore the *uninst but then when using the 'uninstall' button on the package manager page.

If a package is installed via the "upgrade" functionality of the package manager, two scripts will be called: preupgrade and postupgrade. The *upgrade scripts used are the one from the new version of the package. It is worth to note here that nothing is checking the version of the package that is upgraded. Packages can be downgraded and reinstalled using the "upgrade" button of the package manager.

The start-stop-status script will be used by the package manager to start, stop, and get the running status 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, stop result in stop. When (re-)loading the package manager page, it will also call the script for a status update. Finally, there is the possibility to show the log file via the info window. In all cases, returning '0' means 'all ok' and '1' means 'error occurred' or 'not running' (when checking status). When given the 'log' argument in the start-stop-status script, you are able to echo the filename of the logfile to STDOUT and the content of that file will be displayed under the 'log' tab of the info window.

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.