Articles setup, updated 2026-11-16

Synology agent: installing from Package Center

On a Synology, the Linux agent installs as a package from Oversight's own package source, and from then on it is installed, updated, stopped and removed in Package Center like any other package. It works on DSM 6.2 and DSM 7, on Intel, AMD and ARM models, and survives DSM updates. The packages are signed by GEN.

What the agent watches, and how its verdict becomes an alarm, is the same as on any other Linux host: see Linux agent: a verdict from the host itself. This article covers getting it onto the NAS.

Adding Oversight's package source

Once per NAS, signed in to DSM as an administrator:

  1. Open Package Center, then Settings, and the Package Sources tab.
  2. Choose Add, and enter Oversight as the name and this as the location:
    The command or address for this step is for signed-in customers. Sign in to see it.
    Package Center, Settings, Package Sources: the Add dialog with Name set to Oversight and Location set to the package source address
    Figure 1. Adding the package source.
  3. On DSM 6, on the General tab of the same Settings, set Trust Level to Synology Inc. and trusted publishers. Adding the source makes GEN a trusted publisher, so the package then installs without a warning. DSM 7 has no such setting.

Package Center remembers what a source offered until you sign out of DSM. If the agent does not appear, or an update is not offered, sign out and back in.

Installing it

The agent appears in Package Center under Community as Oversight Agent. Choose Install.

Package Center searched for oversight, showing Oversight Agent by GEN under Community with an Install button
Figure 2. The agent under Community, found here by searching for oversight.

On DSM 7, Package Center first shows a notice that the package comes from a third party. It shows this for every package not made by Synology. Choose Agree to carry on.

DSM's notice that the package is provided by third-party developers and not verified by Synology, with Cancel and Agree buttons
Figure 3. The third-party notice on DSM 7.

The wizard then asks three things:

QuestionWhat to put
Listen onThe address and port the probe connects to. 0.0.0.0:29731, the default, listens on every interface.
TokenA long random string, at least 16 characters. The same token goes in a Linux agent credential in Oversight.
Allow fromOptional. The probe's address, or several addresses and ranges separated by commas, such as 10.1.1.25, 100.64.0.0/10. Left empty, any address holding the token is answered.
The Oversight Agent install wizard with Listen on set to 0.0.0.0:29731, the token masked, and Allow from set to 100.64.0.0/10
Figure 4. The wizard filled in, with the token masked in this picture. Allow from here is the address range of a mesh VPN, for a probe that reaches the NAS over one.

The package picks the right build for the NAS, starts the agent, and restarts it within a few seconds if it ever stops.

DSM's firewall needs a rule if it is turned on: in Control Panel, Security, Firewall, allow TCP 29731 in from the probe. Check it from the probe's side before going near Oversight, with a request for /v1/status on port 29731, carrying the token as a bearer header:

The command or address for this step is for signed-in customers. Sign in to see it.

A reply with "alarm": "green" means it is working.

Adding the sensor

Exactly as for any Linux host: on the device that is this NAS, add a sensor of type Linux agent, and a Linux agent credential holding the token, on the device or a group above it. The sensor is ready as soon as it is saved. See Linux agent: a verdict from the host itself for the endpoints and what each one reports.

Updates

When a new version is published, Package Center offers it as an update for the Oversight Agent, and DSM can install it automatically if automatic package updates are turned on. An update asks nothing and keeps the settings. The agent is stopped while it is replaced, so the sensor can show CRIT for a poll or two and then recover by itself.

How it runs

DSM 6.2DSM 7
Runs asnobodythe package's own user, oversight-agent, which DSM creates
Settings/usr/syno/etc/packages/oversight-agent/agent.json/var/packages/oversight-agent/var/agent.json

The settings live outside the package, so updating, or removing and installing again, keeps them. Its output is under View Log on the package in Package Center.

To change a setting later, such as adding a second token so the old one can be retired without a gap, sign in over SSH as an administrator and run the agent against its settings file, then Stop and Run the package in Package Center. On DSM 6:

sudo /var/packages/oversight-agent/target/bin/agent --config /usr/syno/etc/packages/oversight-agent/agent.json --token A-NEW-TOKEN

On DSM 7, the same with --config /var/packages/oversight-agent/var/agent.json. --listen and --allow work the same way.

Moving from the command-line install

A NAS that already has the agent from the command-line install can move to the package and keep its token, so the sensor in Oversight carries on unchanged.

  • DSM 6: just install the package. It takes over the existing settings and removes the old service and program, so the two never compete for the port. The wizard's answers are added to the settings it carried over.
  • DSM 7: DSM does not let a package touch the old install, so remove it first, as root: /opt/oversight/agent --uninstall. Then install the package, giving the wizard the same token, which is in /etc/oversight/agent.json, so the sensor in Oversight needs no change.

Removing it

Uninstall in Package Center stops and removes the agent. The settings file is left behind, so installing again picks up where it left off. Delete it by hand to remove every trace.

If it does not work

What you seeWhat it is
Oversight Agent is not in Package CenterPackage Center is still showing what it fetched before the source was added. Sign out of DSM and back in.
"This package requires DSM 7.0-40000 onwards" on DSM 6, or the reverseThe same: an out-of-date listing. Sign out and back in, and it fetches the package for this DSM version.
A warning that the package is not signed, or is from an unknown publisher (DSM 6)Trust Level is set to Synology only. Set it to Synology Inc. and trusted publishers, as above.
A notice that the package is from a third party (DSM 7)DSM 7 shows this for every package not made by Synology. Accept it to carry on.
The package will not startView Log on the package says why: usually a Listen on that is not a valid address and port.
Nothing at all from the probe, but the package is runningDSM's firewall is not letting the probe in. Allow TCP 29731 from the probe's address.
HTTP status 401 or 403The token does not match, or the probe's address is not in Allow from. See the Linux agent article.
The sensor went CRIT briefly during an updateExpected: the agent is stopped while it is replaced, and the sensor recovers once it is back.