Skip to content

NAME

ionwatch - ION daemon status monitor

SYNOPSIS

ionwatch [ -w interval ] [ -c count ] [ -r ] [ -l ] [ -q ] [ -h ]

DESCRIPTION

ionwatch monitors and displays the status of all ION daemon processes by reading their process IDs (PIDs) from the volatile database and checking whether those processes are actually running.

For each daemon, ionwatch displays the protocol name, daemon name, PID, current status, and a brief description. The status can be one of:

  • Running

    The daemon's PID is registered and the process exists.

  • Not Started

    The daemon has not been started (PID is -1 or unset).

  • STALE

    The daemon's PID is registered but the process no longer exists. This indicates the daemon terminated without properly clearing its PID from the volatile database, which should not occur in ION 4.1.5 and later with daemon self-cleanup.

ionwatch monitors daemons from all available protocols:

  • ICI

    Core ION infrastructure (rfxclock)

  • LTP

    Licklider Transmission Protocol (ltpclock, ltpdeliv)

  • BP

    Bundle Protocol v7 (bpclock, cpsd, bptransit)

  • CFDP

    CCSDS File Delivery Protocol (cfdpclock)

  • DTPC

    Delay-Tolerant Payload Conditioning (dtpcclock, dtpcd)

  • BSSP

    Bundle Streaming Service Protocol (bsspclock)

OPTIONS

  • -w, --watch interval

    Watch mode: continuously refresh the daemon status display every interval seconds. Press Ctrl-C to exit. Without this option, ionwatch displays the status once and exits.

  • -c, --count count

    Number of refresh cycles to perform in watch mode. After count updates, ionwatch will exit. Default is 1 (single display). Only meaningful when used with -w.

  • -r, --running-only

    Show only daemons that are currently running. Daemons with "Not Started" or "STALE" status will be hidden.

  • -l, --log

    Log mode: output to ion.log instead of stdout. All daemon status information is written to the ION log file with the [i] informational prefix, following ION logging conventions. This is useful for automated monitoring and creating audit trails of daemon status.

  • -q, --quiet, --changes-only

    Quiet mode: show full daemon status on the first iteration to establish a baseline, then remain silent unless daemon status changes are detected. On subsequent iterations, only output is produced when a daemon starts, stops, or changes state. When combined with -l, provides minimal-logging watchdog functionality ideal for long-running monitoring.

  • -h, --help

    Display usage information and exit.

EXAMPLES

  • ionwatch

    Display the status of all ION daemons once and exit.

  • ionwatch -w 5

    Continuously monitor daemon status, refreshing every 5 seconds.

  • ionwatch -w 2 -c 10

    Monitor daemon status, refreshing every 2 seconds for 10 iterations.

  • ionwatch -r

    Display only daemons that are currently running.

  • ionwatch -w 3 -r

    Continuously monitor only running daemons, refreshing every 3 seconds.

  • ionwatch -l

    Display daemon status once, logging output to ion.log instead of stdout.

  • ionwatch -w 10 -q -l

    Recommended watchdog mode: monitor daemons every 10 seconds, logging only status changes to ion.log. On the first iteration, logs the complete daemon inventory. Subsequent iterations are silent unless a daemon starts, stops, or changes state. This provides an audit trail of daemon lifecycle events without flooding the log.

  • ionwatch -w 5 -q

    Watch mode with change detection: display full daemon status initially, then only show output when daemon states change. Useful for interactive monitoring where you only care about events, not stable states.

  • ionwatch -q -c 5

    Run 5 status checks: show full status on first check, then only display when changes occur. Useful for periodic automated checks.

EXIT STATUS

  • 0

    ionwatch has terminated normally.

  • 1

    An error occurred (e.g., unable to attach to ION, invalid arguments).

FILES

No configuration files are needed.

ENVIRONMENT

No environment variables apply.

DIAGNOSTICS

The following diagnostics may be issued to the ion.log log file:

  • Can't attach to ION.

    ION system error. One possible cause is that ION has not yet been initialized on the local computer; run ionadmin(1) to correct this.

  • Can't display daemon status.

    ION system error. The volatile database may be corrupted or inaccessible.

NOTES

ionwatch requires ION to be running and properly initialized. It attaches to the ION volatile database to read daemon PIDs and uses the platform abstraction layer (sm_TaskExists) to verify process existence.

ionwatch uses a simplified, low-overhead approach that relies solely on ION's platform abstraction layer. It does not access OS-specific features like the /proc filesystem or execute ps commands, making it suitable for all platforms including embedded RTOS environments.

Starting with ION 4.1.5, all daemons implement self-cleanup, automatically clearing their PIDs from the volatile database upon termination. This ensures ionwatch displays accurate status information. If STALE entries appear, it indicates a daemon crashed or was forcibly killed (kill -9) before it could clean up.

ionwatch only displays daemons for protocols that were compiled into the ION build. Optional protocols (CFDP, DTPC, BSSP) will only appear if they were enabled during compilation.

BUGS

Report bugs to <https://github.com/nasa-jpl/ION-DTN/issues>

SEE ALSO

bpadmin(1), ionadmin(1), ltpadmin(1), psmwatch(1), sdrwatch(1)