Service Support

Generic service support in spksrc

Context

A third party application packaged for Synology often provide a web user interface and users expect to get simple access to it thanks to a service shortcut.

A packager may consider running such a user interface as root is a non-affordable security risk and will push effort to get it run as non-privileged user.

As maintainer facing a large upgrade, work on packages created with copy-paste pattern of many similar files are both time consumming and error prone; so generated files from generic support appear as a requirement.

Concept

Thanks to a small set of spk Makefile variables, a package designer can benefit from generic installer and start-stop-status scripts, with possibility to adapt default behavior thanks to hooks as shell functions.

Provided support

• User creation (SERVICE_USER) and removal to run backgroup service process
• Share folder creation based on wizard variable (SERVICE_WIZARD_SHARE)
• Group creation for managing access to share folder (SERVICE_WIZARD_GROUP)
• Service port (SERVICE_PORT) configuration for firewall and DSM shortcut
• Logging support in both installer and start-stop-status script
• Hooks in package specific script (SERVICE_SETUP)
• A specific start-stop-status script is provided for package with STARTABLE=no

Support is enabled as far as a SERVICE_ variable is set in spk Makefile.

Example

Package spk/demoservice is provided as non-arch example of how to design your package and wizard screens.

Replacement of defaults

If INSTALLER_SCRIPT is set with a installer script, it replaces generic one.

If SSS_SCRIPT is set with a specific start-stop script, it replaces generic one.

In any case, scripts/service-setup is generated from package variables and SERVICE_SETUP if provided.

Reference documentation

Configuration

DSM UI integration

An application shortcut is available when both SPK_ICON and SERVICE_PORT are set in Makefile.

A single URL link is built from:

• DISPLAY_NAME
• DESCRIPTION
• SERVICE_PORT
• SERVICE_PORT_PROTOCOL, defaults to http
• SERVICE_URL, defaults to /
• SERVICE_PORT_ALL_USERS, defaults to true

Generated ${DSM_UI_DIR}/config and icons are included in package.tgz. If not set in Makefile, DSM_UI_DIR default value is app.

Setting NO_SERVICE_SHORTCUT prevents this file generation, typically when SERVICE_PORT is not intended to be browsed.

For information, ADMIN_PORT, ADMIN_PROTOCOL and ADMIN_URL are also available to generate administration link visible from Package Center entry.

DSM 6 privilege

conf/privilege is generated with username=SPK_NAME if SERVICE_USER variable is set to auto.

In rare case package requires an alternate service account name, SERVICE_USER value other than auto is used to run

For DSM 5 compatibility, installer script will create a system account and start-stop-status invokes su to start SERVICE_COMMAND as non-priviliged user.

Worker: service configuration for port

conf/resource/SPK_NAME.sc is generated except if FWPORTS_FILE is provide in Makefile. By defaults, it configure SERVICE_PORT as tcp with port forwarding enabled.

[SPK_NAME]
title="(SERVICE_PORT_TITLE:SPK_NAME)"
desc="(DISPLAY_NAME:SPK_NAME)"
port_forward="yes"
dst.ports="SERVICE_PORT/tcp"

If that default behaviour do not suit your need (for instance to declare two ports), provide a package specific file relative path as FWPORTS_FILE variable. File is then copied as conf/resource/SPK_NAME.sc and handled by installer script as standard one.

Scripts

Both generic installer and start-stop-status scripts source service-setup script which is generated aggregating following variables and SERVICE_SETUP script if set in spk Makefile

GROUP and SHARE_PATH are set from wizard variable names declared in Makefile variables SERVICE_WIZARD_GROUP and SERVICE_WIZARD_SHARE

# Service USER to run background process
USER="demoservice"
# Group name from UI if provided
if [ -n "${wizard_group}" ]; then GROUP="${wizard_group}"; fi
# Share download location from UI if provided
if [ -n "${wizard_download_dir}" ]; then SHARE_PATH="${wizard_download_dir}"; fi
# Service port
SERVICE_PORT=8888
# start-stop-status script redirect stdout/stderr to LOG_FILE
LOG_FILE="${SYNOPKG_PKGDEST}/var/${SYNOPKG_PKGNAME}.log"
# Service command has to deliver its pid into PID_FILE
PID_FILE="${SYNOPKG_PKGDEST}/var/${SYNOPKG_PKGNAME}.pid"
# Service command to execute (either with shell or as is)
SERVICE_COMMAND="${SYNOPKG_PKGDEST}/bin/demoservice.sh ${SERVICE_PORT} ${PID_FILE}"

Installer

SERVICE_SETUP script can provide shell function invoked as hook when installer steps are run by DSM: service_preinst, service_postinst, service_preuninst, service_postuninst, service_preupgrade, service_save, service_restore, service_postupgrade.

For DSM 5 compatibility, scripts have to be designed to run with busybox.

installer script logs to /tmp/${SPK_NAME}_install.log and if successfully installed file is copied as /var/packages/${SPK_NAME}/target/var/${SPK_NAME}_install.log and also available at /usr/local/${SPK_NAME}/var/${SPK_NAME}_install.log

By defaults on DSM 5, only var folder is writable by service account. If required, add required commands in service_postinst shell function in package specific SERVICE_SETUP script.

Wizard variables are stored in /var/packages/${SPK_NAME}/etc/installer-variables so that they can be retreived and used in uninstall or upgrade.

Service startup

start-stop-status generic script starts SERVICE_COMMAND as non-privileged user, account name defaults to package name SPK_NAME except if SERVICE_USER is different from auto.

Package status feedback relies on pid file /var/packages/${SPK_NAME}/target/var/${SPK_NAME}.pid available as PID_FILE shell variable.

Service is expected to provides this file containing its own main process PID. Two means are available to do so:

• if application supports such PID file generation, service_postinst shell function should configure service from PID_FILE variable

• PID_FILE variable has to be provided as command argument in SERVICE_COMMAND so that process writes down its own PID there, at least from shell special variable $!

Process standard output and error streams are aggregated into log file /var/packages/${SPK_NAME}/target/var/${SPK_NAME}.log which is readable thanks to Package Center "View Log" package action.

Script is verbose by default. This behavior can be switched off setting variables in SERVICE_SETUP script:

• SVC_NO_REDIRECT=y prevents process streams to be collected in package log
• SVC_QUIET=y prevents logging start/stop date and action
• SVC_KEEP_LOG=y prevent log content to be cleared before each startup
• SERVICE_SHELL can be used to replace default /bin/sh on DSM 5 only