NAME

ltprc - Licklider Transmission Protocol management commands file

DESCRIPTION

LTP management commands are passed to ltpadmin either in a file of text lines or interactively at ltpadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the LTP management commands are described below.

Automatic Default Initialization: When spans are created (via the a span command), they are automatically initialized with global default values for retransmission parameters, even if no manage commands have been issued. The default values are: maxRetries=5 and maxSegmentLossRate=0.01 (1% packet loss rate) in unified mode, or the corresponding split-mode defaults (maxRetriesXmit=5, maxRetriesRecv=5, maxSegLossRateXmit=0.01, maxSegLossRateRecv=0.01) if split mode is enabled globally. An informational message is logged showing the applied defaults, for example:

[i] Span 2 initialized with global unified mode defaults:
    maxRetries=5, maxSegmentLossRate=0.0100

This ensures that spans remain functional even without explicit configuration. The manage commands described below can be used to override these defaults either globally or on a per-span basis.

COMMANDS

?

The help command. This will display a listing of the commands and their formats. It is the same as the h command.
#

Comment line. Lines beginning with # are not interpreted.
e { 1 | 0 }

Echo control. Setting echo to 1 causes all output printed by ltpadmin to be logged as well as sent to stdout. Setting echo to 0 disables this behavior.
v

Version number. Prints out the version of ION currently installed. HINT: combine with e 1 command to log the version number at startup.
1 est_max_export_sessions

The initialize command. Until this command is executed, LTP is not in operation on the local ION node and most ltpadmin commands will fail.

The command uses est_max_export_sessions to configure the hashtable it will use to manage access to export transmission sessions that are currently in progress. For optimum performance, est_max_export_sessions should normally equal or exceed the summation of max_export_sessions over all spans as discussed below.

Appropriate values for the parameters configuring each "span" of potential LTP data exchange between the local LTP and neighboring engines are non-trivial to determine. See the ION LTP configuration spreadsheet and accompanying documentation for details.
a span peer_engine_nbr max_export_sessions max_import_sessions max_segment_size aggregation_size_threshold aggregation_time_limit 'LSO_command' [queuing_latency]

The add span command. This command declares that a span of potential LTP data interchange exists between the local LTP engine and the indicated (neighboring) LTP engine.

The max_segment_size and aggregation_size_threshold are expressed as numbers of bytes of data. max_segment_size limits the size of each of the segments into which each outbound data block will be divided; typically this limit will be the maximum number of bytes that can be encapsulated within a single transmission frame of the underlying link service.

aggregation_size_threshold limits the number of LTP service data units (e.g., bundles) that can be aggregated into a single block: when the sum of the sizes of all service data units aggregated into a block exceeds this threshold, aggregation into this block must cease and the block must be segmented and transmitted.

aggregation_time_limit alternatively limits the number of seconds that any single export session block for this span will await aggregation before it is segmented and transmitted regardless of size. The aggregation time limit prevents undue delay before the transmission of data during periods of low activity.

max_export_sessions constitutes, in effect, the local LTP engine's retransmission "window" for this span. The retransmission windows of the spans impose flow control on LTP transmission, reducing the chance of allocation of all available space in the ION node's data store to LTP transmission sessions.

max_import_sessions is simply the neighoring engine's own value for the corresponding export session parameter; it is the neighboring engine's retransmission window size for this span. It reduces the chance of allocation of all available space in the ION node's data store to LTP reception sessions.

LSO_command is script text that will be executed when LTP is started on this node, to initiate operation of a link service output task for this span. Note that " peer_engine_nbr" will automatically be appended to LSO_command by ltpadmin before the command is executed, so only the link-service-specific portion of the command should be provided in the LSO_command string itself.

queuing_latency is the estimated number of seconds that we expect to lapse between reception of a segment at this node and transmission of an acknowledging segment, due to processing delay in the node. (See the 'm ownqtime' command below.) The default value is 1.

If queuing latency a negative number, the absolute value of this number is used as the actual queuing latency and session purging is enabled; otherwise session purging is disabled. If session purging is enabled for a span then at the end of any period of transmission over this span all of the span's export sessions that are currently in progress are automatically canceled. Notionally this forces re-forwarding of the DTN bundles in each session's block, to avoid having to wait for the restart of transmission on this span before those bundles can be successfully transmitted.
a seat 'LSI_command'

The add seat command. This command declares that the local LTP engine can receive LTP segments via the link service input daemon that begins running when 'LSI_command' is executed. When there are multiple incoming LTP data streams (serviced by link service daemon such as udplsi), each stream can be added as separate seat.

When all incoming LTP segments are handled by a single stream (for example, in the case of udplsi, whereby all LTP segments are received at the same IP address:port, then one can use 's' command followed by a single 'LSI_command' as a short hand.
c span peer_engine_nbr max_export_sessions max_import_sessions max_segment_size aggregation_size_threshold aggregation_time_limit 'LSO_command' [queuing_latency]

The change span command. This command sets the indicated span's configuration parameters to the values provided as arguments.
d span peer_engine_nbr

The delete span command. This command deletes the span identified by peer_engine_nbr. The command will fail if any outbound segments for this span are pending transmission or any inbound blocks from the peer engine are incomplete.
d seat 'LSI_command'

The delete seat command. This command deletes the seat identified by 'LSI_command'.
i span peer_engine_nbr

This command will print information (all configuration parameters) about the span identified by peer_engine_nbr.
i seat 'LSI_command'

This command will print all information (i.e., process ID number) about the seat identified by 'LSI_command'.
l span

This command lists all declared LTP data interchange spans.
l seat

This command lists all declared LTP data acquisition seats.
s ['LSI_command']

The start command. This command starts link service input tasks for all LTP seats and output tasks for all LTP spans (to remote engines) from the local LTP engine. 'LSI_command' is deprecated but is supported for backward compatibility; if provided, the effect is the same as entering the command "a seat 'LSI_command'" prior to starting all daemon tasks.
m heapmax max_database_heap_per_block

The manage heap for block acquisition command. This command declares the maximum number of bytes of SDR heap space that will be occupied by the acquisition of any single LTP block. All data acquired in excess of this limit will be written to a temporary file pending extraction and dispatching of the acquired block. Default is the minimum allowed value (560 bytes), which is the approximate size of a ZCO file reference object; this is the minimum SDR heap space occupancy in the event that all acquisition is into a file. It is recommended that users properly configure this value - if not using the default - and keep it constant for the duration of ION operation. Although it can be enlarged during run-time, it is not recommended because it will use more working memory. If heapmax is increased from initial value during run-time, reducing it later will not reduce the working memory.
m screening { y | n }

The manage screening command.

The manage screening command. This command disables or enables the screening of received LTP segments per the periods of scheduled reception in the node's contact graph.

By default, screening is enabled - that is, LTP segments from a given remote LTP engine (ION node) will be silently discarded when they arrive during an interval when the contact graph says the data rate from that engine to the local LTP engine is zero. The reason for this is that without a known nominal reception rate we cannot enforce reception rate control, which is needed in order to prevent resource exhaustion at the receiving node.

Note, though, that the enabling of screening implies that the ranges declared in the contact graph must be accurate and clocks must be synchronized; otherwise, segments will be arriving at times other than the scheduled contact intervals and will be discarded.

For some research purposes this constraint may be difficult to satisfy. For such purposes ONLY, where resource exhaustion at the receiving node is not at issue, screening may be disabled.
m ownqtime own_queuing_latency

The manage own queuing time command. This command sets the number of seconds of predicted additional latency attributable to processing delay within the local engine itself that should be included whenever LTP computes the nominal round-trip time for an exchange of data with any remote engine. The default value is 1.
m maxber max_expected_bit_error_rate

The manage max bit error rate command. This command sets the expected maximum bit error rate that LTP should provide for in computing the maximum number of transmission efforts to initiate in the transmission of a given block. (Note that this computation is also sensitive to data segment size and to the size of the block that is to be transmitted.) The default value is .000001 (10^-6).

NOTE: This command is deprecated. Use m maxretries and m maxseglossrate instead for explicit configuration of retransmission parameters.

CRITICAL ORDERING REQUIREMENT: The m maxber command applies only to spans that already exist when the command is executed. It does NOT affect spans created afterward. For correct operation, all a span commands MUST be issued BEFORE m maxber, or those spans will use default values instead.

This ordering restriction is one reason why this command is deprecated. The modern m maxretries and m maxseglossrate commands can be issued in any order and will correctly apply to all existing spans without per-span overrides.
m maxretries max_retransmission_attempts

The manage max retries command. This command sets the global default maximum number of retransmission attempts for control segments (reports and checkpoints) in unified mode (symmetric configuration for both transmit and receive directions). The value must be at least 3. The default value is 5.

This command applies globally to all spans that have not been configured with per-span overrides. It switches spans to explicit unified configuration mode.

NOTE: Even if this command is never issued, spans will automatically be initialized with the default value of 5 retries upon creation. This command is only needed if you wish to change the global default to a different value.

IMPORTANT: For proper explicit configuration, both m maxretries and m maxseglossrate should be specified together. If only one is set, the other will remain at its default value (5 retries or 0.01 loss rate). If you specify neither command, spans will use both defaults automatically.
m maxseglossrate max_segment_loss_rate

The manage max segment loss rate command. This command sets the global default expected maximum segment loss rate (packet loss rate) in unified mode. The value must be in the range [0.0, 0.99]. The default value is 0.01 (1%).

This command applies globally to all spans that have not been configured with per-span overrides. It switches spans to explicit unified configuration mode.

NOTE: Even if this command is never issued, spans will automatically be initialized with the default value of 0.01 (1% loss rate) upon creation. This command is only needed if you wish to change the global default to a different value.

IMPORTANT: For proper explicit configuration, both m maxretries and m maxseglossrate should be specified together. See m maxretries above.
m maxretriesxmit max_retransmission_attempts_transmit

The manage max retries transmit command. This command sets the global default maximum number of retransmission attempts for control segments in the transmit direction only (split mode). The value must be at least 3. The default value is 5.

This command applies globally to all spans that have not been configured with per-span overrides. It switches spans to explicit split configuration mode for asymmetric links.

NOTE: Even if split mode commands are never issued, spans will automatically be initialized with default values (5 retries, 0.01 loss rate in both directions) upon creation. These commands are only needed if you wish to use split mode (asymmetric configuration) or change the defaults.

IMPORTANT: For proper split mode configuration, all four parameters (m maxretriesxmit, m maxretriesrecv, m maxseglossratexmit, m maxseglossraterecv) should be specified together. If any are missing, they will use their default values (5 retries or 0.01 loss rate).
m maxretriesrecv max_retransmission_attempts_receive

The manage max retries receive command. This command sets the maximum number of retransmission attempts for control segments in the receive direction only (split mode). The value must be at least 3. The default value is 5.

This command applies globally to all spans that have not been configured with per-span overrides. It switches spans to explicit split configuration mode for asymmetric links.
m maxseglossratexmit max_segment_loss_rate_transmit

The manage max segment loss rate transmit command. This command sets the expected maximum segment loss rate in the transmit direction only (split mode). The value must be in the range [0.0, 0.99]. The default value is 0.01 (1%).

This command applies globally to all spans that have not been configured with per-span overrides. It switches spans to explicit split configuration mode for asymmetric links.
m maxseglossraterecv max_segment_loss_rate_receive

The manage max segment loss rate receive command. This command sets the expected maximum segment loss rate in the receive direction only (split mode). The value must be in the range [0.0, 0.99]. The default value is 0.01 (1%).

This command applies globally to all spans that have not been configured with per-span overrides. It switches spans to explicit split configuration mode for asymmetric links.
m span peer_engine_nbr maxretries max_retransmission_attempts

The manage span max retries command. This command sets the maximum number of retransmission attempts for the specified span in unified mode. The value must be at least 3. This creates a per-span override that takes precedence over global configuration.
m span peer_engine_nbr maxseglossrate max_segment_loss_rate

The manage span max segment loss rate command. This command sets the expected maximum segment loss rate for the specified span in unified mode. The value must be in the range [0.0, 0.99]. This creates a per-span override that takes precedence over global configuration.
m span peer_engine_nbr maxretriesxmit max_retransmission_attempts_transmit

The manage span max retries transmit command. This command sets the maximum number of retransmission attempts for the specified span in the transmit direction only (split mode). The value must be at least 3. This creates a per-span override for asymmetric link configuration.
m span peer_engine_nbr maxretriesrecv max_retransmission_attempts_receive

The manage span max retries receive command. This command sets the maximum number of retransmission attempts for the specified span in the receive direction only (split mode). The value must be at least 3. This creates a per-span override for asymmetric link configuration.
m span peer_engine_nbr maxseglossratexmit max_segment_loss_rate_transmit

The manage span max segment loss rate transmit command. This command sets the expected maximum segment loss rate for the specified span in the transmit direction only (split mode). The value must be in the range [0.0, 0.99]. This creates a per-span override for asymmetric link configuration.
m span peer_engine_nbr maxseglossraterecv max_segment_loss_rate_receive

The manage span max segment loss rate receive command. This command sets the expected maximum segment loss rate for the specified span in the receive direction only (split mode). The value must be in the range [0.0, 0.99]. This creates a per-span override for asymmetric link configuration.
m span peer_engine_nbr inactivity seconds

The manage span inactivity timeout command. This command sets the session inactivity limit for import sessions from the specified span. When an import session receives no data segments for this number of seconds, it is automatically canceled to prevent indefinite resource consumption.

A value of 0 (the default) disables inactivity timeout for the span. Any positive value enables the timeout. Each time a data segment is received for an import session, the timer is reset.

This feature protects against stale import sessions that can occur when the sending peer loses connectivity before completing transmission (i.e., before sending checkpoint/EORP/EOB segments). Without this timeout, such sessions would remain in the database indefinitely, consuming buffer slots and eventually causing "can't start new session" errors.

NOTE: This setting is stored in volatile memory only and must be reconfigured after each restart of the LTP engine. It does not affect the public span API.
m maxbacklog max_delivery_backlog

The manage max delivery backlog command. This command sets the limit on the number of blocks (service data units) that may be queued up for delivery to clients. While the queue is at this limit, red segments are discarded as it is not possible to deliver the blocks to which they pertain. The intent here is to prevent resource exhaustion by limiting the rate at which new blocks can be acquired and inserted into ZCO space. The default value is 10.
x

The stop command. This command stops all link service input and output tasks for the local LTP engine.
w { 0 | 1 | <activity_spec> }

The LTP watch command. This command enables and disables production of a continuous stream of user-selected LTP activity indication characters. A watch parameter of "1" selects all LTP activity indication characters; "0" de-selects all LTP activity indication characters; any other activity_spec such as "df{]" selects all activity indication characters in the string, de-selecting all others. LTP will print each selected activity indication character to stdout every time a processing event of the associated type occurs:

d bundle appended to block for next session

e segment of block is queued for transmission

f block has been fully segmented for transmission

g segment popped from transmission queue

h positive ACK received for block, session ended

s segment received

t block has been fully received

@ negative ACK received for block, segments retransmitted

= unacknowledged checkpoint was retransmitted

+ unacknowledged report segment was retransmitted

{ export session canceled locally (by sender)

} import session canceled by remote sender

[ import session canceled locally (by receiver)

] export session canceled by remote receiver
h

The help command. This will display a listing of the commands and their formats. It is the same as the ? command.

EXAMPLES

a span 19 20 5 1024 32768 2 'udplso node19.ohio.edu:5001'

Declares a data interchange span between the local LTP engine and the remote engine (ION node) numbered 19. There can be at most 20 concurrent sessions of export activity to this node. Conversely, node 19 can have at most 5 concurrent sessions of export activity to the local node. Maximum segment size for this span is set to 1024 bytes, aggregation size threshold is 32768 bytes, aggregation time limit is 2 seconds, and the link service output task that is initiated when LTP is started on the local ION node will execute the udplso program as indicated.
m screening n

Disables strict enforcement of the contact schedule.

NAME

DESCRIPTION

COMMANDS

EXAMPLES

SEE ALSO