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.
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.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:
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:
- 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'
- To install your application on the DSM Desktop, create a desktop.cfg file.
- place that file along with program files, images, cgi scripts and all in package.tgz
- 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
- Make sure start-stop-status script will always return '0' (or '1' for status info, since nothing is running all the time)
- 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
- 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.
- 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.
- 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.
- 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
- 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.
- Make sure the read-write-execute rights are in place. Use the 'chown' and 'chmod' commands in the scripts to make sure they are.
- 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.
- 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.
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.