PAMAP - Network Host Reachability Monitor

PAMAP Analyzes, Monitors, and Probes is a POSIX-compliant shell script designed to monitor the reachability of a network host, log state changes with timestamps, and provide interactive status updates. It uses ping to check host availability, logs when a host becomes reachable or unreachable, and calculates the duration of each state. The script runs continuously until exited, offering a simple command-line interface for real-time monitoring.

Purpose

PAMAP is ideal for:

• Monitoring network reliability for servers, routers, or other hosts.
• Debugging network connectivity issues by logging state changes.
• Tracking uptime or downtime durations for a specific host.
• Providing a lightweight, terminal-based monitoring tool for system administrators, especially when needing to monitor a single host without the complexity of installing a full Network Management System (NMS).

Features

• Real-time Monitoring: Checks host reachability at user-specified intervals (default: 1 second) using ping.
• State Change Logging: Records when a host becomes reachable or unreachable with timestamps.
• Duration Tracking: Logs the duration of each state (reachable or unreachable).
• Retry Policy: Reduces false alerts by requiring multiple ping failures and a timeout period before declaring a host unreachable (default: 5 attempts, 10-second timeout).
• Interactive Commands:
  • h: Display help menu.
  • s: Show current status with timestamp and state duration.
  • i: Update the check interval with optional time units.
  • r: Update the retry policy (attempts and timeout).
  • q: Quit the script and log final state.
• POSIX Compliance: Fully POSIX-compliant except for the ping utility, which is widely available.
• Lightweight: Minimal dependencies, suitable for any Unix-like system.

Requirements

• Shell: Any POSIX-compliant shell (e.g., sh, dash, bash).
• Utilities:
  • ping (non-POSIX but commonly available).
  • date (POSIX-compliant).
  • stty (POSIX-compliant).
  • dd (POSIX-compliant).
  • sed (POSIX-compliant).
  • sleep (POSIX-compliant).
• Environment: A Unix-like system (e.g., Linux, BSD, macOS).

Installation

1. Clone the repository:

   git clone https://github.com/seancrites/pamap.git
   cd pamap

2. Ensure the script is executable:

   chmod +x pamap.sh

Usage

Run the script with a hostname or IP address, optional check interval, and retry policy:

./pamap.sh [-h] [-i interval] [-r attempts,timeout] <hostname>

Examples

• Monitor Google's DNS server with default settings (1-second interval, 5 attempts, 10-second timeout):

  ./pamap.sh 8.8.8.8

  Output:

  Monitoring host 8.8.8.8 with 1-second interval.
  Retry policy: 5 attempts, 10-second timeout.
  Press 'h' for help.
  [2025-06-29 20:47:10] Host 8.8.8.8 is now reachable

• Monitor a local server with a 5-minute check interval and custom retry policy (3 attempts, 30-second timeout):

  ./pamap.sh -i 5m -r 3,30s myserver.local

  Output:

  Monitoring host myserver.local with 300-second interval.
  Retry policy: 3 attempts, 30-second timeout.
  Press 'h' for help.
  [2025-06-29 20:47:10] Host myserver.local is now reachable

• Monitor a host with a 1-fortnight check interval and default retry policy:

  ./pamap.sh -i 1f 8.8.8.8

  Output:

  Monitoring host 8.8.8.8 with 1209600-second interval.
  Retry policy: 5 attempts, 10-second timeout.
  Press 'h' for help.
  [2025-06-29 20:47:10] Host 8.8.8.8 is now reachable

Interactive Commands

While the script runs, press:

• h: Show the help menu with usage and commands.
• s: Display the current status, including timestamp and state duration (e.g., "Host is reachable. Duration: 2h 15m 30s").
• i: Prompt to enter a new check interval with optional time units (e.g., 5m, 1f, 30s, or number for seconds).
• r: Prompt to enter new retry settings (e.g., 3,30s for 3 attempts and 30-second timeout).
• q: Exit the script, logging the final state and duration.
• Any other key: Displays the help menu.

Options

• -h: Display help and exit.

  ./pamap.sh -h

• -i <interval>: Set the check interval (default: 1 second). Specify a number with an optional unit: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months), y (years), D (decades), C (centuries), Y (millennia), f (fortnights). Without a unit, assumes seconds.

  ./pamap.sh -i 10h 8.8.8.8

• -r <attempts,timeout>: Set the retry policy for declaring a host unreachable (default: 5 attempts, 10 seconds). Specify attempts as a number and timeout with an optional unit (same as -i).

  ./pamap.sh -r 3,30s 8.8.8.8

Notes

• Non-POSIX Dependency: The ping utility is not strictly POSIX but is available on most Unix-like systems. All other components (date, stty, dd, sed, sleep) are POSIX-compliant.

• Terminal Settings: The script modifies terminal settings for keypress detection and restores them on exit (including Ctrl+C).

• Logging: State changes and durations are printed to stdout. Redirect output to a file for persistent logging:

  ./pamap.sh -i 5m -r 3,30s 8.8.8.8 > monitor.log

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/<your-feature>
3. Commit changes: git commit -m "Add <your-feature>"
4. Push to the branch: git push origin feature/<your-feature>
5. Open a pull request.

Please ensure:

• Code is POSIX-compliant or clearly documents non-POSIX dependencies.
• Changes are well-documented with comments.
• Tests are performed in a POSIX shell (e.g., dash).

License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.

Author

• Sean Crites (sean.crites@gmail.com)

Version

• 1.2.0 (2025-06-29)
• 1.1.0 (2025-06-22)