NAME

ltpwatch - Licklider Transmission Protocol (LTP) session status monitor

SYNOPSIS

ltpwatch [-t type] [-s session] [-e engineId] [interval [count]]

DESCRIPTION

ltpwatch displays the current status of LTP sessions for all configured spans (or a specific span if filtered). It shows both active sessions and recently completed sessions that are still in the "dead" lists awaiting cleanup.

For each session, ltpwatch displays the session number, current status, client service ID, data lengths, and retransmission count. Sessions are organized by span and separated into export (outbound) and import (inbound) categories.

ltpwatch can run in one-shot mode (default) or periodically refresh the display at a specified interval.

OPTIONS

• -t type

  Filter sessions by type. Valid values are:

  • export

    Show only export (outbound/sending) sessions.

  • import

    Show only import (inbound/receiving) sessions.

  If not specified, both export and import sessions are displayed.

• -s session

  Filter by a specific session number. Only sessions matching this number will be displayed. Useful for tracking a particular session across multiple spans.

• -e engineId

  Filter by span engine ID. Only the span with the specified remote engine ID will be displayed. If not specified, all configured spans are shown.

• -h

  Display usage information and exit.

ARGUMENTS

• interval

  Refresh interval in seconds. If set to 0 or omitted, ltpwatch runs in one-shot mode: it displays the current status and exits immediately.

  If a positive interval is specified, ltpwatch will refresh the display every interval seconds until interrupted (Ctrl+C) or the count is reached.

• count

  Number of iterations to perform. Only meaningful when interval is greater than 0.

  • If interval is 0 (or omitted), count defaults to 1 (one-shot mode).
  • If interval is greater than 0 and count is omitted, ltpwatch runs indefinitely until interrupted.
  • If both interval and count are specified, ltpwatch performs exactly count iterations with interval seconds between each.

OUTPUT

ltpwatch displays session information in a tabular format:

=== LTP Session Watch [2024-12-03 14:23:45] ===

--- Span 2 ---

EXPORT SESSIONS (Active: 3, Dead: 1)
  Session    Status             Client TotalLen   RedLen     Rexmit
  -------    ------             ------ ---------  ---------  ------
  10001      transmitting       1      65536      32768      0
  10002      buffering          1      131072     65536      0
  10004      completed          1      16384      16384      0

IMPORT SESSIONS (Active: 2, Dead: 1)
  Session    Status             Client RedLen     Received   Rexmit
  -------    ------             ------ ---------  ---------  ------
  20001      receiving          1      65536      45000      0
  20003      completed          1      16384      16384      0

Export Session Status Values

• buffering

  Session is aggregating data blocks; End-of-Block has not been sent yet.

• transmitting

  End-of-Block has been sent but final acknowledgment has not been received.

• awaiting-cleanup

  Final acknowledgment received; session is being cleaned up.

• green-only

  Session contains only green (unreliable) data with no red part.

• completed

  Session completed successfully (in dead exports list).

• canceled(user)

  Session was canceled by user request.

• canceled(unreachable)

  Session was canceled because client service was unreachable.

• canceled(rexmit)

  Session was canceled due to retransmission limit exceeded.

• canceled(miscolor)

  Session was canceled due to segment color mismatch.

• canceled(engine)

  Session was canceled by the LTP engine.

Import Session Status Values

• receiving

  Session is actively receiving data segments.

• complete-pending

  All data received; waiting for processing.

• awaiting-delivery

  Final report acknowledged; awaiting delivery to client.

• delivered

  Data has been delivered to the client application.

• completed

  Session completed successfully (in dead imports list).

• canceled(...)

  Same cancellation reasons as export sessions.

Column Descriptions

• Session

  The LTP session number.

• Status

  Current session state (see status values above).

• Client

  Client service ID that owns this session.

• TotalLen (export only)

  Total block size in bytes.

• RedLen

  Size of the red (reliable) portion in bytes.

• Received (import only)

  Number of red bytes received so far.

• Rexmit

  Retransmission/expiration count from the session timer.

EXIT STATUS

• "0"

  ltpwatch completed successfully.

• "1"

  ltpwatch was unable to attach to LTP or encountered an error.

EXAMPLES

• ltpwatch

  One-shot display of all sessions on all spans.

• ltpwatch 5

  Refresh display every 5 seconds until interrupted.

• ltpwatch 2 10

  Refresh every 2 seconds, for 10 iterations total.

• ltpwatch -t export

  Show only export sessions (one-shot).

• ltpwatch -t import -e 3

  Show only import sessions for span with engine ID 3.

• ltpwatch -s 12345

  Find and display session 12345 across all spans.

• ltpwatch -e 2 -t export 3

  Show export sessions for engine 2, refreshing every 3 seconds.

FILES

No configuration files are needed.

ENVIRONMENT

• ION_NODE_LIST_DIR

  For multi-node test configurations, this variable must be set to the directory containing the ion_nodes file.

DIAGNOSTICS

The following diagnostics may be issued:

• ltpwatch can't attach to LTP.

  ltpadmin has not yet initialized LTP protocol operations.

• LTP is not initialized.

  The LTP database has not been created. Run ltpadmin first.

• No spans configured.

  No LTP spans have been added via ltpadmin.

• No span found for engine ID N

  The specified engine ID does not match any configured span.

NOTES

• Recently completed sessions are only visible for a short time (typically around 30 seconds) while they remain in the "dead" session lists awaiting final cleanup. After cleanup, they will no longer appear in ltpwatch output.
• The Rexmit column shows the timer expiration count, which is only meaningful for sessions that have experienced retransmissions or cancellation attempts.

BUGS

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

SEE ALSO

ltpadmin(1), ltpstats(1), ltp(3), ltprc(5)