Permissions Reference¶

This page provides technical reference for the permission system used by spksrc packages on DSM. For user-facing instructions, see User Guide: Permission Management.

Service Accounts¶

DSM 7 Service Accounts¶

In DSM 7, each package runs under a dedicated system internal user account:

sc-<pkgname>

For example: - sc-transmission for Transmission - sc-jellyfin for Jellyfin - sc-homeassistant for Home Assistant

These accounts: - Are created automatically during installation - Cannot be managed via DSM Control Panel - Are not members of the users group - Are deleted when the package is uninstalled

DSM 6 Service Accounts¶

DSM 6 allows configurable service users. spksrc packages use:

Package Type	User	Group(s)
Download clients	Package-specific	`sc-download`
Media servers	Package-specific	`sc-media`
Web apps	`http`	`http`
CLI tools	`root`	`root`

Privilege Configuration¶

Service user configuration is defined in src/conf/privilege (JSON):

{
    "defaults": {
        "run-as": "package"
    }
}

Value	Description
`package`	Use `sc-<pkgname>` user
`root`	Run as root (not recommended)

For DSM 7, the Makefile variable SERVICE_USER specifies the service account name (typically sc-$SYNOPKG_PKGNAME).

Framework Variables¶

Makefile Variables¶

Variable	Description	Example
`SERVICE_USER`	Service account name	`sc-transmission`
`STARTABLE`	Whether package has a service	`yes`
`SERVICE_WIZARD_SHARENAME`	Wizard variable for share name	`wizard_data_share`

Script Variables¶

Variables available in service-setup.sh:

Variable	Description
`EFF_USER`	Effective user running the service
`SHARE_PATH`	Full path to configured share (via wizard)
`SHARE_NAME`	Name of configured share
`SYNOPKG_PKGDEST`	Package installation directory
`SYNOPKG_PKGVAR`	Package variable directory

ACL System¶

ACL Modes¶

DSM uses POSIX ACLs extended by Synology:

Mode	POSIX	Description
Read	`r--`	Read file contents
Write	`-w-`	Modify file contents
Execute	`--x`	Execute file/traverse directory
Append	Custom	Append to file
Delete	Custom	Delete file
Custom	Varies	Combined permission sets

synoacltool¶

The synoacltool command manages ACLs:

# Get ACL for a path
synoacltool -get /volume1/data

# Add ACL entry
synoacltool -add /volume1/data user:sc-transmission:allow:rwxpd---:fd--

# Delete ACL entry
synoacltool -del /volume1/data user:sc-transmission

ACL Entry Format¶

<type>:<name>:<allow|deny>:<perms>:<flags>

Field	Values
type	`user`, `group`
name	Username or group name
allow/deny	`allow`, `deny`
perms	`rwxpdDaARWcCos`
flags	`fdin` (file, directory, inherit, no-propagate)

Permission Characters¶

Char	Permission
`r`	Read data
`w`	Write data
`x`	Execute/Traverse
`p`	Append data
`d`	Delete
`D`	Delete child
`a`	Read attributes
`A`	Write attributes
`R`	Read xattr
`W`	Write xattr
`c`	Read ACL
`C`	Write ACL
`o`	Chown
`s`	Sync

Framework Functions¶

fix_shared_folders_rights¶

The fix_shared_folders_rights function (from spksrc.service.installer.functions) sets appropriate permissions:

fix_shared_folders_rights "${SHARE_PATH}" "${SYNOPKG_PKGNAME}"

This function: 1. Detects DSM version 2. Sets appropriate owner/group 3. Applies ACL entries for the service account

Permission Helper Functions¶

Function	Description
`set_unix_permissions`	Set traditional Unix perms
`fix_shared_folders_rights`	Full ACL setup for shared folders
`setup_new_share`	Create and configure new share

Resource File Permissions¶

In resource files (src/conf/resource):

{
    "data-share": {
        "shares": [
            {
                "name": "{{wizard_data_share}}",
                "permission": {
                    "rw": ["sc-{{SYNOPKG_PKGNAME}}"]
                }
            }
        ]
    }
}

Permission Types¶

Key	Permission Level
`rw`	Read/Write
`ro`	Read Only
`na`	No Access

Best Practices¶

Principle of Least Privilege¶

Request only necessary permissions
Use read-only access when write is not required
Limit access to specific folders, not entire volumes

Shared Folder Access¶

# Good: Use wizard-defined share
SHARE_PATH="/volume1/${wizard_data_share}"

# Bad: Hardcode paths
SHARE_PATH="/volume1/downloads"

DSM 7 Considerations¶

Service accounts are automatically created
Cannot add service accounts to custom groups
Use resource files for share permissions
Test with fresh installs, not just upgrades

Troubleshooting¶

Checking Effective Permissions¶

# As root, check ACL
synoacltool -get /volume1/data

# Check file ownership
ls -la /volume1/data

# Check effective user for running service
ps aux | grep <servicename>

Common Permission Errors¶

Error	Cause	Solution
"Permission denied"	Missing ACL	Add via synoacltool or resource file
"Operation not permitted"	Wrong user	Check SERVICE_USER
Cannot create directory	No write permission	Grant rw in resource file