How to monitor particular kit with Oversight: which sensor to use, where on the device to set up access, which user function and extraction rows read the response, and how to write the rules that turn it into an alarm. Search for a vendor, a product or an error message, or ask a question in your own words.
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:
- Open Package Center, then Settings, and the Package Sources tab.
- Choose Add, and enter
Oversightas the name and this as the location:The command or address for this step is for signed-in customers. Sign in to see it.Figure 1. Adding the package source. - 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.
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.
The wizard then asks three things:
| Question | What to put |
|---|---|
| Listen on | The address and port the probe connects to. 0.0.0.0:29731, the default, listens on every interface. |
| Token | A long random string, at least 16 characters. The same token goes in a Linux agent credential in Oversight. |
| Allow from | Optional. 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 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:
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.2 | DSM 7 | |
|---|---|---|
| Runs as | nobody | the 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 see | What it is |
|---|---|
| Oversight Agent is not in Package Center | Package 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 reverse | The 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 start | View 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 running | DSM's firewall is not letting the probe in. Allow TCP 29731 from the probe's address. |
| HTTP status 401 or 403 | The 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 update | Expected: the agent is stopped while it is replaced, and the sensor recovers once it is back. |