A custom Nagios plugin is an executable check. On a Linux VPS, a Bash plugin reads one focused metric, prints a concise status line, optionally appends performance data after a pipe, and exits with Nagios’s status code: 0 for OK, 1 for WARNING, 2 for CRITICAL, or 3 for UNKNOWN. This guide shows how to design, code, test, install, and connect such a plugin to Nagios Core without assuming a particular Linux distribution or package layout.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
Understand the plugin contract before writing code
Nagios Core does not require a plugin to be written in a particular language. It executes a file, reads the process exit status, and displays the text written to standard output. The Nagios Core Plugin API states that a script or executable must, at minimum, return one of the permitted values and print at least one line to STDOUT.
As an Amazon Associate I earn from qualifying purchases.
The exit code is the machine-readable state used for scheduling, notifications, and escalation. The first output line is the human-readable explanation shown in the Nagios interface, notification messages, and logs. A plugin that prints a useful sentence but exits zero can hide an outage; a plugin that exits non-zero without explaining why is difficult to operate. Treat both outputs as part of the interface.
| Exit code | State | Use it when |
|---|---|---|
| 0 | OK | The checked condition is within its acceptable range. |
| 1 | WARNING | The condition crossed a warning threshold but is not yet a critical failure. |
| 2 | CRITICAL | The condition is outside the critical limit or the service is failing. |
| 3 | UNKNOWN | The plugin could not determine a reliable state, for example because an argument is invalid or a required command failed. |
Keep the first line short enough for a pager while retaining the value and reason: CRITICAL - queue depth 143 exceeds 100 is more actionable than CRITICAL alone. If you need several details, put the most important fact first and put additional metrics in performance data.
#1 Best Overall
- BLUE LIGHT BLOCKING GLASSES: Our blue light glasses for women boast UV400 protection, blocking harmful blue rays from computer screens. With these bluelight glasses women, you can enjoy gaming, reading, or watching TV with no worries of eye strain.
- EYE RELIEF: Our blue light glasses are engineered to reduce blurry vision or strain caused by prolonged screen time. These womens blue light glasses aid in better sleep by preventing blue light from disrupting your natural sleep cycle, helping you fall asleep faster and enjoy a more restful night's sleep, making them the perfect christmas present.
- COMFORTABLE: Crafted from durable material, our trendy blue light glasses for woman or blue light glasses men ensure long-lasting comfort. The high-transmittance lenses accessories, gamer gifts for men, help keep your eyes relaxed. Perfect stocking stuffers, gifts for gamers men, christmas gifts for men, halloween costumes.
- LIGHTWEIGHT: These clear blue light glasses feature a lightweight frame, meaning they’ll stay comfy for long-term wear. Perfect as blue blockers glasses for women or mens blue light glasses, these non-prescription fake glasses for men can be worn throughout the day. The blue light blocking glasses women feature polycarbonate HD lenses, which are anti-reflective and restore true color.
- WORRY-FREE PURCHASE: If you experience any issues, our support team is ready to assist you quickly. These are the perfect costume glasses for cosplay dressing up.
Choose a narrow check and define its policy
A reliable plugin answers one operational question. Examples include whether a process exists, whether a TCP port accepts connections, how old a backup file is, how many jobs are queued, or whether a local API returns an expected value. Combining unrelated tests in one script makes thresholds, alerts, and troubleshooting ambiguous.
- Define the metric and unit. Decide whether the value is seconds, bytes, a count, a percentage, or a dimensionless score.
- Define warning and critical behavior. State whether a value above a limit, below a limit, or inside a forbidden interval triggers an alert.
- Define unknown conditions. A missing file, malformed response, permission error, or timeout should have a deliberate result rather than accidentally becoming OK.
- Define the execution identity. A check run by the Nagios user may not see files or environment variables available to root.
- Define a maximum runtime. A hung network call or command substitution can consume a scheduler slot unless the script enforces its own timeout.
Write these rules down in the script’s help text or operational documentation. Nagios cannot infer whether a number is healthy; the plugin must encode that decision.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Build a Bash plugin step by step
1. Start with a stable interpreter and status constants
Use an environment-based Bash shebang when Bash may be installed in different locations, or replace it with the absolute path used by your VPS. Keep the four Nagios states as named constants so every exit path is obvious.
2. Parse and validate arguments
Expose options such as -w/--warning, -c/--critical, -t/--timeout, and -h/--help. Reject missing values, unknown switches, non-numeric limits, and contradictory thresholds before running the check. Returning UNKNOWN for an unusable invocation tells Nagios that the monitoring result itself is unavailable.
3. Use absolute command paths
The Nagios plugin guidelines recommend avoiding unsafe command lookup through PATH. Call external programs with paths such as /usr/bin/awk and /usr/bin/timeout, and confirm those locations on the target VPS. If a distribution stores a utility elsewhere, update the script rather than silently relying on an inherited environment.
Rank #2
- WINDEX GAMING WIPES: effortlessly clean all your gaming gear and gaming electronics in one easy step with our new Windex Gaming Wipes
- AMMONIA FREE: our ammonia-free formula is safe to use on all of your favorite gaming equipment like consoles, headsets, controllers, screens, keyboards, and more
- PRE-MOISTENED WIPES: each wipe instantly removes dust, dirt, and stubborn smudges and fingerprints leaving a streak-free shine
- ANTI-STATIC: great for cleaning and wiping down your gaming gear and electronics leaving behind no visible residue
- COMPACT RESEALABLE PACKAGE: store your pack of Windex Gaming Wipes anywhere in your home for whenever a quick and easy wipedown is needed
4. Capture the value and distinguish command failures
Run one focused command, save both its output and return status, and treat a non-zero status as a data-collection failure. Do not compare an empty string as if it were zero. A timeout, permission error, or parse failure should produce UNKNOWN or CRITICAL according to the policy you documented.
5. Compare the value, print one line, and exit
Evaluate CRITICAL before WARNING so a value that crosses both limits receives the more severe state. Print the state and explanation to STDOUT, append performance data after | when useful, and exit with the matching constant.
Illustrative load-check script
The following pattern checks the integer part of the one-minute load value in /proc/loadavg. It is an example, not a universal production check: adapt the metric, units, command locations, and threshold policy to your VPS.
#!/usr/bin/env bash
OK=0
WARNING=1
CRITICAL=2
UNKNOWN=3
warning=80
critical=90
timeout_s=10
usage() {
printf '%sn' 'Usage: check_vps_load.sh [-w warning] [-c critical] [-t seconds]'
}
while (($#)); do
case "$1" in
-w|--warning)
[[ $# -ge 2 ]] || { printf '%sn' 'UNKNOWN - missing warning value'; exit "$UNKNOWN"; }
warning=$2
shift 2
;;
-c|--critical)
[[ $# -ge 2 ]] || { printf '%sn' 'UNKNOWN - missing critical value'; exit "$UNKNOWN"; }
critical=$2
shift 2
;;
-t|--timeout)
[[ $# -ge 2 ]] || { printf '%sn' 'UNKNOWN - missing timeout value'; exit "$UNKNOWN"; }
timeout_s=$2
shift 2
;;
-h|--help)
usage
exit "$OK"
;;
*)
printf 'UNKNOWN - unknown option: %sn' "$1"
exit "$UNKNOWN"
;;
esac
done
if ! [[ $warning =~ ^[0-9]+$ && $critical =~ ^[0-9]+$ && $timeout_s =~ ^[1-9][0-9]*$ ]]; then
printf '%sn' 'UNKNOWN - thresholds and timeout must be positive integers'
exit "$UNKNOWN"
fi
if (( critical <= warning )); then
printf '%sn' 'UNKNOWN - critical must be greater than warning'
exit "$UNKNOWN"
fi
value=$(/usr/bin/timeout "$timeout_s" /usr/bin/awk '{print int($1)}' /proc/loadavg)
rc=$?
if (( rc != 0 )) || ! [[ $value =~ ^[0-9]+$ ]]; then
printf '%sn' 'UNKNOWN - cannot read load average'
exit "$UNKNOWN"
fi
if (( value >= critical )); then
printf 'CRITICAL - load value=%s | load=%s;%s;%s;0n' "$value" "$value" "$warning" "$critical"
exit "$CRITICAL"
elif (( value >= warning )); then
printf 'WARNING - load value=%s | load=%s;%s;%s;0n' "$value" "$value" "$warning" "$critical"
exit "$WARNING"
else
printf 'OK - load value=%s | load=%s;%s;%s;0n' "$value" "$value" "$warning" "$critical"
exit "$OK"
fiThe sample’s default values are intentionally simple and may not suit a real load check. A one-minute load average is normally fractional, so truncating it to an integer can hide meaningful changes. Preserve decimals, scale the metric, or use a different parser when that precision matters. The important pattern is the separation of collection, validation, comparison, output, and exit status.
Implement warning and critical thresholds correctly
Threshold syntax is not merely decoration; it defines when Nagios changes state. The Nagios Plugins Development Guidelines document range forms and performance-data conventions. A simple upper-limit interface commonly treats -w10 -c20 as WARNING above 10 and CRITICAL above 20. That behavior is a policy implemented by the plugin, so document it in --help and keep the comparison order explicit.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- Ergonomic & Adjustable Design: Fight "text neck" and improve your posture. Designed for comfort, it offers an adjustable height (7.1in-8.5in) (1.4in adjustable range) and angle (5°-85°) Please note: cell phone stand is only 9 inches tall—the length of a standard pencil
- Without blocking subtitles Perfect for office desk Tiktok Face Time Zoom video—this is the ultimate kitchen desk essential for phones! Perfect viewing experience while reducing neck back strain, A must-have for gamers streamers desk, and anyone who values both style and support!
- Sleek & Stable Design fits Otterbox Case: Say goodbye to bent cables, tangles, and tip-overs! LISEN’s stylish adjustable desk phone holder features a built-in charging hole and smart cable management, keeping your phone secure and your workspace clutter-free cool gadgets for men
- ANTI-SLIP DESIGN free hands: The under 10.00 items easy gadgets back and the bottom of this kitchen essentials for women are fully covered by anti-skid silicone, which LISEN stand up desk decor can provide maximum protection device from any scratches and slides
- Your Perfect Viewing Companion:If your product arrives damaged or breaks within 365 days, reach out to LISEN for a quick and hassle-free solution. Struggling with assembly, like tightening the screw? We’ve got your back! Your experience matters to us. (Product including: phone Holder stand*1, screw*1, hexagon screwdriver*1, specification*1)
For plugins that accept standard Nagios ranges, remember that a range describes the acceptable interval and an alert occurs outside it unless the range begins with @. Common forms are:
| Range | Acceptable interval | Alert condition | Typical meaning |
|---|---|---|---|
10: |
10 and above | Below 10 | Minimum requirement, such as at least 10 workers. |
~:10 |
Negative infinity through 10 | Above 10 | Upper-bound check, such as latency no higher than 10 seconds. |
@10:20 |
10 through 20 | Inside 10–20 | Forbidden-band check, such as a value that must stay outside a range. |
Do not mix a shorthand upper-limit parser with range syntax without stating which interpretation wins. If your Bash script only supports integers, reject a string such as @10:20 instead of silently accepting part of it. If you need ranges, write a parser that validates the complete form, handles infinity markers, and has tests for boundary values. Test exactly-at-threshold cases because deciding whether equality is warning or critical is a frequent source of flapping alerts.
Return performance data for graphs and history
Performance data follows a pipe on the first output line. The documented shape is label=value[UOM];[warn];[crit];[min];[max]. Labels are separated by spaces; units may include %, s, B, or c. For example:
OK - queue depth 7 | queue=7c;20;50;0Here, queue is the label, 7c is a count, 20 and 50 are warning and critical limits, and 0 is the minimum. Add a maximum when the metric has a meaningful fixed ceiling, such as 100 for a percentage. Keep labels free of spaces and characters that your graphing consumer cannot parse. Emit a numeric value even when the state is WARNING or CRITICAL so a graph shows the event’s magnitude.
Recommended Free Tools
Only put concise service text before the pipe. Additional narrative after the pipe can be misread as a metric, and multiline output may be truncated or rendered differently by older integrations. If collection fails, you may omit performance data and explain the failure in the status text.
Rank #4
- Easy Installation: Our gaming lights have been designed to enhance your entertainment experience. Simply position the led light bar next to your TV or game console to create a game room environment with ease. They come with USB power and a 60 inch cord for direct mounting and mobility
- Audio Syncing & Extensive Mode: The built-in high-sensitivity music sensor allows you to sync the TV led lights to your favorite music. Lights react and move to the beat of music, film and game audio, creating an incredible immersive sound and light experience – and all without the need for an additional hub. You can choose from 64+ patterns, including strobe, illusion, jump, energy, gradient, running, chasing, fluttering mode etc. Each mode can be applied to different scenes
- 64+ Chasing IC+RGB & W Effect: The independent control design of IC+RGB and white all-in-one multifunctional rgbw led bar lights monitor backlight allows you to easily switch the led lights for desk between IC+RGB and white to enjoy a variety of lighting effects, you can choose white lighting mode with high brightness for better illumination when working, etc. Choose IC+RGB lighting mode when you need to create an entertaining atmosphere for the light show, 16 million colours of Color changing rgb light bar let you dance to the beat and create a dynamic party atmosphere
- Dynamic and Dimmable Lights: 1%-full brightness free brightness adjustment gives you the flexibility to adjust dimmable led light bar for room decorations or a variety of occasions
- USB Powered: USB light bars for room can be powered by powernank, usb charger, TV, Monitor, laptop PC mainframe, making behind TV led lighting bar easy to install in any location.TV led lights are powered by the TV usb interface / PC mainframe, can be turned on/off synchronously with TV / PC
Test the plugin before Nagios runs it
Make the file executable and test every state from a shell. Use the same account Nagios will use; root-only success does not prove the check is deployable.
- Save the script, for example as
check_vps_load.sh, and runchmod 0755 check_vps_load.sh. - Run the help path:
./check_vps_load.sh --help. It should exit 0 and print usage. - Run normal thresholds and inspect both output and status:
./check_vps_load.sh -w 4 -c 8; printf 'exit=%sn' "$?". - Pass a missing argument, an unknown option, and a non-numeric value. Each should print an explanation and exit UNKNOWN.
- Force a warning and critical result with thresholds below the observed value, then test equality at each boundary.
- Temporarily make the input unreadable or unavailable and verify that the script does not report OK.
- Exercise the timeout path with a deliberately sleeping test command in a development copy. Confirm that the wrapper returns within the configured limit.
- Run as the monitoring account, for example
sudo -u nagios -- /usr/lib/nagios/plugins/check_vps_load.sh -w 4 -c 8, after installation.
Capture the numeric exit code in a test harness if the plugin becomes important. A few shell tests for valid arguments, boundary values, command failure, and timeout prevent later edits from changing alert semantics accidentally.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Install a custom plugin on a Linux VPS
Plugin and configuration paths depend on the Linux distribution and how Nagios was packaged. Treat the following locations as examples, not universal constants. Find the plugin directory in the active Nagios configuration, then use an administrator account to copy the file, set ownership, and set a non-writable mode for the monitoring user.
sudo install -o root -g nagios -m 0755 check_vps_load.sh
/usr/lib/nagios/plugins/check_vps_load.shSome installations use /usr/local/nagios/libexec, a distribution-specific libexec directory, or a custom path. The command definition must use the exact path visible to the Nagios process. Check that the script’s interpreter and every absolute utility path exist on the VPS.
Run the installed file manually as the Nagios execution user:
Best Value
- Compatible with Wide Screens - To ensure compatibility with the dual monitor mount, your each monitor must meet three conditions at the same time: First, computer screens size range: 13 to 32 inches. Second, screen weight range: 4.4 to 19.8 lbs. Third, the back of the monitor screen must have VESA mounting holes with a pitch of 75x75mm or 100x100mm.
- Regarding the compatibility with desks - Your desk must meet three conditions at the same time: First, desk material: Only wooden desks are recommended, plastic or glass desks cannot be used. Second, desk thickness range: 0.59" - 3.54". Third, the bottom of the desk should not have any cross beams or panels, as this will interfere with installation. We recommend carefully checking that your desk and monitors meets all above conditions before purchasing.
- Dual C-Clamp Hold - Worried your dual monitors might wobble or slip? Our upgraded base uses a larger platform plus a dual C-clamp structure to lock the dual monitor arm firmly to your desk. Each arm safely keeps your screens steady while you type, click and game—no shaking, no sliding, just a clean and secure setup you can trust every day. It also provides Grommet Mounting installation choice, both options ensure stable and secure fixation for your 0.59" - 3.54" desk.
- Full-Motion Adjustment For Comfortable View - Pull the screen closer when you’re deep in a spreadsheet, push it back to watch videos, or rotate to portrait for coding — moving everything smoothly with just one hand. The monitor stand offers +85°/-50° tilt, ±90° swivel and 360° rotation. Raise your monitor up to 15.75″ to support a healthy sitting posture. Whether you’re working from home, gaming through the night, or switching between video calls and documents, getting the screens to your natural line of sight helps relieve neck, shoulder and back strain so you can stay focused longer with less fatigue.
- Keep Your Desk Organized: By lifting both screens off the desktop, this dual monitor stand opens up valuable space for your keyboard, notebook, docking station or a simple, clutter-free work area. Built-in cable management guides wires along the arms, keeping cords out of sight and out of the way. Enjoy a tidy, modern workstation that looks as good as it feels to use.
sudo -u nagios -- /usr/lib/nagios/plugins/check_vps_load.sh -w 4 -c 8
printf 'exit=%sn' "$?"If the check reads a protected file, add the smallest required permission or group membership rather than running the entire plugin as root. Never print credentials, tokens, or full API responses in the status line or performance data.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Connect the script to a Nagios command and service
Define a reusable command
In the command-object file loaded by your installation, map Nagios arguments to the script’s options. The exact object directory varies, so place this definition wherever your nagios.cfg includes command files.
define command {
command_name check_vps_load
command_line /usr/lib/nagios/plugins/check_vps_load.sh -w $ARG1$ -c $ARG2$
}$ARG1$ and $ARG2$ are substituted from the service’s check_command line. Keep the command line literal: do not pass unvalidated shell fragments or use eval in the plugin. If you add a timeout argument, expose it as another explicitly validated argument.
Attach the command to a service
define service {
host_name my-vps
service_description One-minute load
check_command check_vps_load!4!8
check_interval 5
retry_interval 1
check_period 24x7
notification_interval 60
}The host name, contact settings, intervals, and notification policy are examples. Use the templates and macros already used by your installation. The exclamation marks separate command arguments; in this example warning is 4 and critical is 8.
Validate, reload, and schedule a check
- Validate the complete configuration with the Nagios binary and configuration file used by your package, commonly an invocation equivalent to
/usr/sbin/nagios -v /etc/nagios/nagios.cfg. Use the paths reported by your installation. - Fix every error before reloading. A successful syntax check does not guarantee that the script is executable or that its data source is readable.
- Reload the Nagios service using the service manager command supplied by your distribution, such as a reload action for the Nagios unit.
- In the Nagios interface, open the service and schedule an immediate check. Confirm the displayed state, output, and performance data.
- If the result is UNKNOWN, reproduce the command as the Nagios user and inspect permissions, working-directory assumptions, interpreter paths, and timeout behavior.
Do not assume a reload occurred just because the command returned successfully; check the daemon log and the service’s “last check” timestamp.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchReliability and security practices
- Quote variables. Use
"$variable"when passing values to commands and reject unexpected characters in options. - Set a predictable environment. Do not depend on a caller’s PATH, locale, current directory, aliases, or interactive shell startup files.
- Use safe temporary files. If a check needs scratch space, create it with a secure temporary-file utility, restrict permissions, and remove it with a trap. Avoid predictable names and follow symlinks only when intended.
- Enforce an internal timeout. A plugin that waits forever can block the scheduler. Wrap network calls and other potentially blocking commands, and map timeout to CRITICAL or UNKNOWN according to the documented service policy.
- Limit privileges. Read only the files and sockets required for the check. Do not make a plugin setuid.
- Keep output deterministic. Suppress incidental warnings from helper commands or redirect them to STDERR so Nagios receives one intentional status line.
- Handle locale and numeric formats. Force a predictable locale when parsing command output if decimal separators or translated text could change the result.
- Avoid secret leakage. Do not include passwords in command arguments, process listings, output, or performance labels.
- Prevent alert flapping. Use sensible intervals, exact boundary tests, and—when the metric warrants it—state handling in Nagios rather than adding undocumented sleeps to the plugin.
Troubleshoot common failures
| Symptom | Likely cause | What to check |
|---|---|---|
| Nagios reports “No output” | The script exited without writing STDOUT, or wrote only to STDERR. | Run it manually and ensure every path prints a line before exiting. |
| “Return code of 126” or permission denied | The file is not executable or a parent directory blocks traversal. | Check mode bits, ownership, directory permissions, and the interpreter path. |
| Works as root but is UNKNOWN as Nagios | The monitoring user cannot read the data source or environment. | Use sudo -u nagios and grant only the needed read or group access. |
| Every result is CRITICAL | Units or threshold direction are wrong. | Print the raw value during a manual test, verify scaling, and test values below, at, and above each limit. |
| Performance graphs are empty | The pipe format, label, unit, or numeric field is invalid. | Emit label=value;warn;crit;min;max on the first line and remove spaces from labels. |
| Checks hang or become stale | A child command or network operation has no timeout. | Use an absolute-path timeout wrapper, test the timeout branch, and inspect daemon logs for scheduler timeouts. |
| Configuration validation fails | The command object is not included, an argument macro is malformed, or a path is wrong. | Run the validator against the active configuration and confirm the include hierarchy and executable path. |
When Bash is the right implementation
| Criterion | Bash | Another language may be better when |
|---|---|---|
| Startup and runtime overhead | Excellent for short checks that invoke a few local Unix tools. | The check is long-running, highly concurrent, or sensitive to process-spawn overhead. |
| Available dependencies | Convenient when the VPS already provides standard tools such as awk, sed, grep, and timeout. | You need a library that is not reliably installed or would be difficult to package. |
| Numeric parsing | Fine for integers and simple comparisons. | You need precise decimal arithmetic, complex range parsing, binary protocols, or large structured payloads. |
| Error handling | Works when every command status is checked and variables are carefully quoted. | Many failure classes, retries, concurrency, or typed data would make shell control flow opaque. |
| Portability | Portable across Unix-like VPSs when you use Bash features and verify utility paths. | The target systems lack Bash or require a single self-contained executable. |
| Testing and maintenance | Small scripts are easy to inspect and deploy. | A growing plugin needs modules, automated tests, structured logging, or a team unfamiliar with shell. |
Choose Bash for a focused local check that composes existing commands and has straightforward thresholds. Move to another implementation when API authentication, substantial JSON or XML parsing, concurrency, or complex retry logic dominates the work. Regardless of language, preserve the same Nagios contract: clear STDOUT, a correct exit code, validated inputs, performance data where useful, and a bounded runtime.
Keep the plugin maintainable after deployment
Version the script and its command definition together. Record the metric’s unit, threshold direction, default values, required utilities, expected execution user, and the meaning of UNKNOWN. Review changes with a test matrix that covers normal, warning, critical, malformed-input, permission, empty-data, and timeout cases.
When the VPS is upgraded or the Nagios package changes, re-run the manual check as the service account and the configuration validator. Distribution updates can move utility paths, alter permissions, or change the daemon’s environment. Monitoring is only trustworthy when the executable, its dependencies, and the policy encoded in its thresholds continue to match the service you intend to measure.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
