Assign checks with config packages

With a config package, you assign monitoring checks to many devices: configure the checks once and use rules to determine which devices receive them. This guide shows you how to build a package and select the right devices, from one server to every Windows server across your customers.

Two ways to assign a check

The two approaches work together: a device can carry directly-assigned checks and match several rule-based packages at the same time, and all of those checks run on it. This guide covers the rule-based package, because that is how you monitor a fleet without editing devices one by one.

Prerequisites

• The Monitoring Check Management permission, granted through groups under Administration → Groups — see How Users, Groups & Permissions Work. This permission lets you create and edit config packages. If you do not see Configuration → Config Packages, ask an administrator to grant it.
• For tag-based rules, the devices you want to target should already carry the tags you will match on — see Configure Tag Rules.

A shared package can still be Read-only with this permission if you cannot access every affected customer. You can inspect it but cannot edit or clone it; see Shared configurations.

Create a rule-based package

Config packages live under Configuration → Config Packages, split into Rule-based Packages and Device Direct Packages.

1. Go to Configuration → Config Packages and make sure the Rule-based Packages tab is selected.
2. Click Create Package.
3. Enter a Name (for example, Standard Server Checks) and an optional Description so the next administrator understands what the package is for. To start from an existing package, pick one under Clone from; otherwise leave it on Empty package.
4. Select Customers for an empty package. This is required without global customer access. Cloning inherits the source package's customer scope.
5. Under Modules, select at least Checks for this guide. You can also include Software, Agent settings, Maintenance and Automations. Rules is always included.
6. Click Create. The detail page shows your selected modules as tabs; open Agent settings through Agent.

You can also click Start from Template and choose a built-in package. Review modules when cloning or using templates too: only selected contents are retained.

Manage modules and the software schedule

Open Edit modules, select the modules you need and click Apply. When removing a configured module, confirm Discard settings only if you intend to delete its configuration. Then save the package.

In the package list, Modules shows the contents; combine Filter by module... with text search. Software deployment schedule shows the software-deployment schedule and stays blank when none is configured. It is independent of automation schedules.

Add checks to the package

1. On the package's Checks tab, find the Included Checks section and click Add Check.
2. Choose a check type and set its thresholds. Find instructions, fields, and defaults for each individual check under Checks in the sidebar.
3. Repeat for every check this package should carry. A package can bundle as many checks as you need; they are all assigned together when the package matches a device.

Checks with device-specific fields (host, credentials)

A package carries one configuration for every matched device. On registered network devices, supported checks receive the device's host/IP and SNMP connection settings automatically. This does not include every credential: the OPNsense check still needs its own API key and secret, and the ESXi check needs its own credentials, even when they are already stored on the device.

• For a handful of appliances with individual credentials, add the checks directly on each device.
• If you assign them through a package, enter the device-specific credentials on each device via Override for this device on its Monitoring Checks panel. The override also decouples the other check fields, including thresholds, from future package edits — the overrides badge on the package's Checks tab keeps them findable.

Set fleet-wide agent settings (optional)

Beyond checks and software, a package can also apply agent settings to every device it matches. Open the package's Agent tab and turn on the settings you want. A device's effective value combines all of its packages, and you can override any of them per device from the device page.

Only allow during remote desktop is off by default. While it is enabled, MCP file operations are unavailable because they cannot be attached to an interactive remote desktop session.

Target the right devices with assignment rules

Assignment rules decide which devices the package applies to. Open the package's Rules tab.

1. Under Customers, choose the customers this package should apply to. Only with global customer access can you leave this empty to apply the package to every customer.
2. Under Device rules, build a condition in the form Apply to devices where <field> <operator> <value> — for example, Device Class is Windows Server.
3. Click Add Condition to add another condition to the same rule. Conditions in one rule are joined with and (every condition must be true).
4. To express or (a device matches if it satisfies any rule), add a second rule, or start a new block with or alternatively…. A device is included as soon as one rule matches.
5. Click Save. octoja re-evaluates the rule and assigns — or removes — the package's checks on matching devices automatically.

Complete or remove incomplete conditions and empty groups before saving. Stored invalid rules match no devices, even if another alternative would match. Always inspect the matching-device list.

This is the same rule engine used by tag rules. The simple sentence builder handles and/or conditions; for nested groups, octoja switches to the Advanced editor, where you write the rule in octoja Query Language (OQL) directly.

Rule fields

Available operators depend on the field: text fields offer equals, does not equal, contains, does not contain, starts with, and does not start with; Device Class, Membership, and Has Battery use is and is not; Tags and Customer Tags use contains, does not contain, matches text, and does not match text. The first two let you pick an existing tag from a list; the last two take free text and match on part of a tag name, so one condition catches every tag containing a word.

The Device Class values are Windows Server, Windows Workstation, Linux Server, Linux Desktop, macOS, Switch, Router, Firewall, Access Point, Printer, NAS, UPS, ESXi, vCenter, and IP Camera.

Confirm the rule matches the right devices

While you edit the rules, octoja shows a live count of how many devices currently match — for example, "12 devices matched" — above a searchable list of exactly those devices, showing each one's device class, operating system, and customer. This is your check that the package will actually land somewhere.

• If you see "No devices match these rules.", the package is valid but will run on zero devices — it sits quietly and monitors nothing. This is not an error and you will not be warned about it later, so always read the match count before you rely on a package. A common cause is a tag in the rule that no device carries yet.
• If you have global customer access and save with no customers selected, octoja warns with "No customers selected" and reminds you that the rules will then apply to devices of all customers — confirm only if that is what you intend. Without global access, you must select customers.

You can also confirm from the device's side. Open a device, open its actions menu, and choose Config Packages: the dialog lists every rule-based package that reaches that device, with its description and its Contents — checks, software deployments, automations, or agent settings — and clicking a row opens the package. If no package matches, the dialog says so and points you to the device's Checks tab, where directly assigned checks live.

Reuse one package across customers

A rule-based package is not tied to a single customer. With global customer access, leave the Customers field empty and the package applies across every customer in your instance — so a rule like Device Class is Windows Server covers all Windows servers you manage from one package. Build the standard once, and every new matching device picks it up automatically the next time it reports in.

Find devices that override a package check

A single device can be taken off the shared configuration from its own Monitoring Checks panel — Disable on this device, Override for this device, or its own alarm configuration (see Set up alerts for a check). That device then keeps its own settings and stops picking up the edits you make in the package — easy to lose track of across a fleet. The package's Checks tab shows you where it has happened.

In Included Checks, every check that at least one device has departed from carries a badge — 3 overrides, or 1 override for a single device. Click it to open Device overrides for that check: a list of every affected device with its customer, site, and device class, each tagged with what it changed.

Hover over the device name for a device preview. Click the name to open the device and investigate the override alongside its checks.

Click Changes on a row to see exactly what differs: every changed setting with the package's value struck through and the device's value beside it, and the same comparison for the alarm configuration (Off when the device has alarms turned off).

To put a device back on the shared configuration, click Undo on its row — this clears all three kinds at once, so a check that was disabled there starts running again too. Undo all resets every device in the list after a confirmation prompt. Either way octoja notifies the affected agents straight away, so the package's configuration takes effect without waiting for the next check-in.

Tips

• Directly-assigned checks and rule-based packages add up on a device — use direct assignment for exceptions and packages for the standard.
• Alert rules live on the check inside the package, so a package can carry both the check and how you are notified when it fails — see Set up alerts for a check.
• Use the live match count as a quick check after every rule change — an unexpected drop to zero usually means a condition is now too strict, or a tag is missing.
• Start from a built-in template when you want a sensible default set of checks rather than a blank package.
• Use the Automations tab to attach scheduled automations to a rule-based package — they then run on every device the package matches.

FAQ

How do I remove a single check from a device?

Open the device and its Checks tab. You need the Monitoring Check Management permission. The right action depends on how the check was assigned:

Assignment	What to do
Directly on the device	Click the check's trash icon and confirm Remove. This also deletes its result history on this device.
Through a rule-based config package	Use Disable on this device on the check. It stops running on this device; its assignment and existing history remain. Use Enable on this device to turn it back on.

For an exception on just one device, you do not need to uninstall the agent or delete the device. Only change the check or rules in the shared package if the change should also apply to the other affected devices.

Can I rerun a check on several devices at once?

The manual rerun action belongs to the check on each device; there is no fleet-wide rerun button in the package. Saving changed check inputs notifies the affected agents, and a check whose effective inputs change runs again after receiving the configuration. Offline devices must reconnect first, and device overrides can keep their effective inputs unchanged. Do not alter thresholds or other settings merely to force a rerun.

Can one package contain checks for several operating systems?

Yes. Assignment follows the package rules; the agent does not run a check that has no executable for its platform. This does not validate every prerequisite: a supported check can still fail when required software is missing, for example.

Use shared packages for common basics and targeted device-class or operating-system rules for platform-specific requirements. Check each check's platform support and prerequisites; assignment alone does not confirm that it runs on the device.