Data and removal

An upgrade keeps your app’s data. An uninstall keeps it too, unless the user ticks one box in the uninstall wizard. Your handlers write to one data folder, and everything in it survives upgrades.

Set it up

Write data to the data folder

A native-go backend writes its data to /var/packages/<package>/var, which DSM stores at @appdata/<package> on the volume. Files you ship inside the SPK are replaced on every upgrade, so write anything that must survive to the data folder.

Location	Holds	Upgrade	Uninstall box ticked
`@appdata/<package>`	App data: what your handlers write. For a Compose app, the `${SYNOPKG_PKGVAR}` bind mounts.	Kept	Contents deleted
`@apphome/<package>`	The package home folder. For a Compose app, it includes generated secrets.	Kept	Contents deleted
`@appconf/<package>`	Saved package configuration. Native packages only.	Kept	Contents deleted
A Shared Folder	Files in a folder you selected or created at install.	Kept	Never deleted
A Docker named volume	State a container manages itself. Compose only.	Kept	Never deleted
The package account and group	DSM’s internal identity for the package.	Kept	Never deleted

Change your data format between versions

A native-go project uses the SDK package github.com/synopackageland/syno-pkg-land-sdk/datamigrate to apply numbered schema steps to the data folder. Add your steps to Migrations() in backend/internal/app/migrations.go:

{
  Version: 1,
  Name:    "example",
  Apply: func(ctx datamigrate.Context) error {
    // Read ctx.DataDir. Write a temporary file, then rename it.
    return nil
  },
},

Rule	Detail
Numbering	Versions start at 1. A version never changes meaning.
When it runs	The backend runs every pending step at the start of each request. A failed step fails that request.
Progress	Stored in `<data folder>/data-version`.
Idempotent	Every step must be safe to run twice. A crash before the version is recorded runs the step again.
Failure	The last successful version stays recorded, and the next request resumes from there. The helper never deletes or rewrites data itself.
Versions	`ctx.OldPkgVer` is the package version that was installed before the upgrade. `ctx.NewPkgVer` is the running version.

Use it

Back up

The CLI does not back anything up. The uninstall wizard says that Hyper Backup is not checked and that the platform cannot verify a recoverable backup exists. Include these in your own backup:

Include	When
`@appdata/<package>`	Always.
`@apphome/<package>` and `@appconf/<package>`	When your app uses them.
The Shared Folder	When the app uses one.
Docker named volumes	For a Compose app that declares them.

Approvals and delegations are not data. They are not restored by a backup. After a reinstall an administrator approves again and each user picks their destinations again.

Upgrade

An upgrade keeps the data folder and runs your schema steps. The install wizard checks whether @appdata/<package> already exists. If it does, it tells the administrator that the install reuses that data, and how to start empty.

Uninstall

The uninstall wizard has one checkbox, unchecked by default: “Also delete the app data listed above”. The wizard lists the folders it empties. It states that Shared Folders, the package account and other apps’ data are never deleted.

Choice	Result
Unchecked	Data stays. Reinstalling the same package name reuses it.
Checked	Empties `@appdata` and `@apphome` for the package, and `@appconf` for a native package. The folders themselves stay. A folder that does not resolve inside the package’s own area is skipped with a message.
An upgrade, with the box checked	Nothing is deleted.

DSM may keep empty @appdata/<package>, @appconf/<package>, @apphome/<package> and @appshare/<package> folders, the /usr/syno/etc/packages/<package> link and the package account. After an uninstall an administrator can review these, back up what they want, and remove only this package’s leftovers. synopkgland inspect and status print the same list.

DSM keeps an uninstalled app’s rules in Control Panel > Application Privileges, and a later install under the same package name applies them again. For a portal app, DSM removes the alias but its web server keeps serving the address until it reloads. Only root can clean up either one, so the result depends on the kind of app (see Capabilities):

Kind	Application Privileges rules	Login Portal address
Executor app (`delegate` or `root-ops`)	The executor deletes this app’s rules at uninstall, with or without the data box ticked.	The executor reloads the web server once DSM has removed the alias, so the address stops at once.
App without privileges	Kept. The uninstall wizard tells the administrator to remove them in Control Panel > Application Privileges.	None: it cannot declare `portal`.

The executor writes failures to the system log entry synopkgland-executor, and the uninstall continues. The uninstall wizard and the status/inspect cleanup list name the manual steps only as a fallback for that case.

What administrator approvals mean

Only packages with delegate or root-ops have an approval. See Capabilities.

Event	What happens to the approval
Install	`status` shows `needs-admin-approval` until a DSM administrator confirms their password once in the app window.
Stop	The executor pauses. Approval, grants and the selected scope stay.
Upgrade	The executor stops, then resumes after the upgrade when the approved policy still matches. A new executor needs no approval: root installs it only when its SHA-256 matches the `synopkgland_executor_sha256` key that Package Center wrote to the root-owned INFO. Otherwise it stays paused and `status` shows `needs-admin-approval`. When the approved policy is unchanged, the installed executor pins the new executor by itself and needs no new approval. An `install-selected` scope asks an administrator to confirm the Shared Folder once with their password. A new approval is needed when you change `entry`, the delegate scope, destinations, lifetime or operations, or any `root/*.sh`. A version bump, a UI change or a newer SDK with the same policy does not need one.
Scope change, `delegate.disable`, `delegate.enable`	All delegations are revoked. Each user picks their destinations again. Files already written stay.
Uninstall	The approval, the delegations, the scheduled tasks `<package> executor boot`, `<package> executor control` and `<package> executor selection`, and the app’s Application Privileges rules are removed. A reinstall needs a fresh approval.

Uninstall removes the tasks in the background, after it checks their names, owner and script. It does not wait for them, and a timeout does not stop the uninstall. A task that was changed or cannot be verified is kept. An administrator reviews it in Control Panel > Task Scheduler.

Remove leftovers by hand

An executor app whose cleanup failed at uninstall (the system log entry synopkgland-executor says why) can leave root tasks, Application Privileges rules and a Login Portal address behind. An administrator removes them by hand:

Leftover	Remove it
`<package> executor control` and `<package> executor selection`	Control Panel > Task Scheduler.
`<package> executor boot`	DSM refuses to delete it over HTTP (error 119). As root, run `/usr/syno/bin/synowebapi --exec api=SYNO.Core.EventScheduler method=delete version=1 task_name="<package> executor boot"`.
Application Privileges rules	Control Panel > Application Privileges.
A Login Portal address that still opens	Save any alias in Control Panel > Login Portal > Applications, which reloads the web server, or restart the NAS.

Limits

Limit	Value
Uninstall box	Deletes only package-private folders: `@appdata`, `@apphome` and, for native packages, `@appconf`.
Shared Folders, Docker named volumes, the package account	Never deleted by uninstall.
Backup	Not configured, and not verified by the CLI or the wizard.
Schema step helper	`native-go` only.

Troubleshooting

Symptom	Cause	Fix
A reinstall starts with the earlier settings	The earlier uninstall kept the data.	Uninstall again with “Also delete the app data listed above” ticked, then install.
Empty folders remain after uninstall with the box ticked	DSM keeps the folder roots. The box empties their contents.	Review and remove them as an administrator if you do not reinstall.
`needs-admin-approval` after an upgrade	The upgrade changed the policy, or the INFO executor anchor is missing or does not match.	A DSM administrator approves in the app window.
`blocked: executor_status_mismatch` while the tasks are approved	The panel names the cause. “the approved executor is not answering (`executor_not_listening`)”: the executor process is gone or paused. “the running executor reports other digests than this package pins”: the running executor is not the one this package was built with, for example after a hand-edited upgrade. “the executor status request failed”: the CGI could not ask the executor.	A DSM administrator selects Approve background access again. With the tasks approved, this restarts the executor without a password. For other digests, reinstall the package the executor came from. The executor log has the details.
A request fails after an upgrade	A schema step failed.	Fix the step. The next request resumes from the last recorded version.
An executor app’s Application Privileges rules or Login Portal address remain after uninstall	The executor’s cleanup failed. The system log entry `synopkgland-executor` says why.	Remove the rules in Control Panel > Application Privileges. Save any alias in Control Panel > Login Portal > Applications, or restart the NAS.