root. This sometimes leads to build and test errors when one switches back to the host's development and testing environment. Therefore, we recommend that you execute the make clean and git stash command to remove all build and testing artifacts from ION 's source directory before exiting the container.Interplanetary Overlay Network (ION) is an implementation of the DTN architecture, as described in Internet RFC 4838 (version 6) and RFC 9171 (version 7), that is intended to be usable in both embedded environments including spacecraft flight computers as well as ground systems. It includes modular software packages implementing Bundle Protocol version 6 (BPv6) and version 7 (BPv7), Licklider Transmission Protocol (LTP), Bundle Streaming Service (BSS), DTN-based CCSDS File Delivery Protocol (CFDP), Asynchronous Message Service (AMS), and several other DTN services and prototypes. ION is currently the baseline implementation for science instruments on the International Space Station (ISS) and the gateway node (ION Gateway) that provides relay services for command/telemetry and science data download.
Here you will find videos of the Interplanetary Overlay Network courses and presentation materials.
DTN Development/Deployment Kit is an ISO image of an Ubuntu virtual machine, pre-configured with ION and a GUI virtualization environment. It contains a number of pre-built scenarios (network topologies) to demonstrate various features of ION software. ( currently the DevKit is undergoing upgrade to BPv7, release date is TBD.)
"},{"location":"#application-domains-of-dtn-and-ion","title":"\ud83d\udce1 Application Domains of DTN and ION","text":"git clone https://github.com/nasa-jpl/ION-DTN.git\nION is licensed under the MIT License. Please see the LICENSE file for details.
"},{"location":"#important-papers-on-ion-and-dtn","title":"\ud83d\udcda Important Papers on ION and DTN","text":"For a list of key DTN and ION-related publications, please refer to the List-of-Papers page.
"},{"location":"AMS-Programmer-Guide/","title":"AMS Programmer's Guide","text":"Version 3.0
Sky DeBaun, Jet Propulsion Laboratory, California Institute of Technology
Document Change Log
Ver No. Date Affected Description Comments 2.2 Sept 2010 3.0 June 2023 All Updates and Corrections"},{"location":"AMS-Programmer-Guide/#purpose-and-scope","title":"Purpose and Scope","text":"The Consultative Committee for Space Data Systems' (CCSDS) Asynchronous Message Service (AMS) is a communication architecture for data systems. It is designed to allow mission system modules to operate as if they were isolated, each producing and consuming mission information without explicit knowledge of the other active modules. This self-configuring communication relationship minimizes complexity in the development and operation of modular data systems.
AMS is the foundation of a system that can be described as a 'society' of largely autonomous, interoperating modules. These modules can adapt over time in response to changing mission objectives, functional upgrades of modules, and recovery from individual module failures. The primary objective of AMS is to reduce mission cost and risk by providing a standard, reusable infrastructure for information exchange among data system modules. This infrastructure is designed to be user-friendly, highly automated, flexible, robust, scalable, and efficient.
Notably, AMS provides a publication and subscription service for both terrestrial and extraterrestrial communications, utilizing the Interplanetary Overlay Network (ION). This service ensures a seamless and efficient communication system that can adapt dynamically to various missions.
"},{"location":"AMS-Programmer-Guide/#definitions","title":"Definitions","text":"Within the context of this document the following definitions apply:
A continuum is a closed set of entities that utilize AMS for purposes of communication among themselves. Each continuum is identified by a continuum name and corresponding non-negative continuum number. The continuum name that is the character string of length zero indicates \"all known continua\" or \"any known continuum\", whichever is less restrictive in the context in which this continuum name is used; the reserved continuum number zero corresponds to this continuum name.
An application is a data system implementation, typically taking the form of a set of source code text files, that relies on AMS procedures to accomplish its purposes. Each application is identified by an application name.
An authority is an administrative entity or persona that may have responsibility for the configuration and operation of an application. Each authority is identified by an authority name.
A venture is an instance of an application, i.e., a functioning projection of the application -- for which some authority is responsible -- onto a set of one or more running computers.
A message is an octet array of known size which, when copied from the memory of one module of a venture to that of another (exchanged), conveys information that can further the purposes of that venture.
The content of a message is the array of zero or more octets embedded in the message containing the specific information that the message conveys.
A role is some part of the functionality of an application. Each role is identified by a role name and corresponding non-negative role number. The role name that is the character string of length zero indicates 'all roles' or 'any role', whichever is less restrictive in the context in which the role name is used; the reserved role number zero corresponds to this role name. The role name \"RAMS '' identifies Remote AMS (RAMS) gateway functionality as discussed below; the reserved role number 1 corresponds to this role name.
A module (of some mission data system) is a communicating entity that implements some part of the functionality of some AMS venture -- that is, performs some application role -- by, among other activities, exchanging messages with other modules. Associated with each module is the name of the role it performs within the application. [Note that multiple modules may perform the same role in an application, so the role name of a module need not uniquely identify the module within its message space.] In order to accomplish AMS message exchange a module generates AMS service requests and consumes AMS service indications; the module that is the origin of a given AMS service request or the destination of a given AMS service indication is termed the operative module.
A message space is the set of all of the modules of one AMS venture that are members of a single AMS continuum; that is, a message space is the intersection of a venture and a continuum. Each message space is uniquely identified within that continuum by the combination of the name of the application and the name of the authority that is responsible for the venture, and by a corresponding venture number greater than zero. [Note that unique naming of continua enables multiple message spaces that are in different continua but are identified by the same application and authority names to be concatenated via Remote AMS (discussed below) into a single venture.]
A unit (i.e., a unit of organization) is an identified subset of the organizational hierarchy of the modules of one AMS venture, declared during venture configuration as specified by the responsible authority for that venture. Each unit is uniquely identified within the venture by unit name and corresponding non-negative unit number. The root unit of a venture is the unit that is coterminous with the venture itself; its unit name is the character string that is of length zero, and the reserved unit number zero corresponds to this unit name. A unit whose name is identical to the first N bytes -- where N is greater than or equal to zero -- of the name of another unit of the same message space is said to contain that other unit. The membership of a unit that is contained by another unit is a subset of the membership of the containing unit.
A cell is the set of all modules that are members of one unit of a given venture and are also members of a given continuum; that is, it is the intersection of a unit and a continuum. Since each unit is a subset of a venture, each cell is necessarily a subset of the message space for that venture in that continuum. Each cell is uniquely identified within its message space by its unit's name and number. The root cell of a message space is coterminous with the message space itself. A cell contains some other cell only if its unit contains that other cell's unit. A cell may be an empty set; that is, in a given continuum there may be no modules that are members of the cell's unit. The registered membership of a cell is the set of all modules in the cell that are not members of any other cell which does not contain that cell^1^. [Note that the root cell contains every other cell in the message space, and every module in the message space is therefore a member -- though not necessarily a registered member -- of the root cell.]
The domain of an AMS service request is the set of modules to which the request pertains. It comprises all of the modules that are members of the venture in which the operative module is itself a member, with the following exceptions:
The subject number (or subject) of a message is an integer embedded in the message that indicates the general nature of the information the message conveys, in the context of the AMS venture within which the message is exchanged. A subject name is a text string that serves as the symbolic representation of some subject number.
To send a message is to cause it to be copied to the memory of a specified module. To publish a message on a specified subject is to cause it to be sent to one or more implicitly specified modules, namely, all those that have requested copies of all messages on the specified subject. To announce a message is to cause it to be sent to one or more implicitly specified modules, namely, all those modules that are located within a specified continuum (or all continua), are members of a specified unit (possibly the root unit) and that perform a specified role in the application (possibly \"any role\").
A subscription is a statement requesting that one copy of every message published on some specified subject by any module in the subscription's domain be sent to the subscribing module; the domain of a subscription is the domain of the AMS service request that established the subscription.
^1^ For example, if cell A contains cells B and C, and cell C contains cells D and E, any nodes in C that are not in either D or E are in the registered membership of cell C. Those nodes are also members of cell A, but because they are in cell C -- which does not contain cell A -- they are not in cell A's registered membership.
An invitation is a statement of the manner in which messages on some specified subject may be sent to the inviting module by modules in the domain of the invitation; the invitation's domain is the domain of the AMS service request that established the invitation.
"},{"location":"AMS-Programmer-Guide/#overview","title":"Overview","text":""},{"location":"AMS-Programmer-Guide/#general","title":"General","text":"A data system based on AMS has the following characteristics:
a. Any module may be introduced into the system at any time. That is, the order in which system modules commence operation is immaterial; a module never needs to establish an explicit a priori communication \"connection\" or \"channel\" to any other module in order to pass messages to it or receive messages from it.
b. Any module may be removed from the system at any time without inhibiting the ability of any other module to continue sending and receiving messages. That is, the termination of any module, whether planned or unplanned, only causes the termination of other modules that have been specifically designed to terminate in this event.
c. When a module must be upgraded to an improved version, it may be terminated and its replacement may be started at any time; there is no need to interrupt operations of the system as a whole.
d. When the system as a whole must terminate, the order in which the system's modules cease operation is immaterial.
AMS-based systems are highly robust, lacking any innate single point of failure and tolerant of unplanned module termination. At the same time, communication within an AMS-based system can be rapid and efficient:
e. Messages are exchanged directly between modules rather than through any central message dispatching nexus.
f. Messages are automatically conveyed using the \"best\" (typically -- though not necessarily -- the fastest) underlying transport service to which the sending and receiving modules both have access. For example, messages between two ground system modules running in different computers on a common LAN would likely be conveyed via TCP/IP, while messages between modules running on two flight processors connected to a common bus memory board might be conveyed via a shared-memory message queue.
g. Finally, AMS is designed to be highly scalable: partitioning message spaces into units enables a venture to comprise hundreds or thousands of cooperating modules without significant impact on application performance.
AMS message exchange is fundamentally asynchronous, akin to a \"postal\" system. An AMS module, after sending a message, can continue its functions without waiting for a reply.
While message exchange is asynchronous, AMS provides a mechanism for linking reply messages to their original context. This is achieved by including a context number in the original message. The reply message automatically echoes this context number, allowing the original sender to link the reply to the application activity that triggered the initial message. This creates a pseudo-synchronous communication flow. The specific mechanism for establishing this link is implementation-dependent.
In some cases, true message synchrony may be necessary, requiring a module to suspend operations until a reply is received. AMS supports this communication model when required.
The majority of message exchange in an AMS-based system follows a \"publish-subscribe\" model. A module announces its subscription to a specific subject using AMS procedures. From that point, any published message on that subject is automatically delivered to all subscribing modules. This model simplifies application development and integration, allowing each module to plug into a data \"grid\" and exchange data without detailed knowledge of other modules.
However, there may be instances where a module needs to send a message privately to a specific module, such as in reply to a published message. AMS also supports this communication model when necessary.
"},{"location":"AMS-Programmer-Guide/#architectural-elements","title":"Architectural Elements","text":"The architectural elements involved in the asynchronous message service protocol are depicted as below:
Figure 1: Architectural Elements of AMS
All AMS communication is conducted among three types of communicating entities: modules (defined earlier), registrars, and configuration servers.
A registrar is a communicating entity that catalogs information regarding the registered membership of a single unit of a message space. It responds to queries for this information, and it updates this information as changes are announced.
A configuration server is a communicating entity that catalogs information regarding the message spaces established within some AMS continuum, specifically the locations of the registrars of all units of all message spaces. It responds to queries for this information, and it updates this information as changes are announced.
"},{"location":"AMS-Programmer-Guide/#overview-of-interactions","title":"Overview of Interactions","text":"AMS, best characterized as a messaging \"middleware\" protocol, operates between the Transport and Application layers of the OSI protocol stack model. It relies on underlying Transport-layer protocols for actual message copying from sender to receiver and for transmitting meta-AMS (or MAMS) messages for dynamic self-configuration of AMS message spaces.
In any AMS continuum, a common transport service, termed the Primary Transport Service (PTS), is used for MAMS traffic by all entities involved in the operations of all message spaces. The PTS, being universally available, can also be used for application message exchange among all modules in a continuum. However, in some cases, performance can be improved by using Supplementary Transport Services (STSs), especially when modules share access to a convenient communication medium like a shared-memory message queue.
Supplementary Transport Services (STSs) are performance-optimizing transport services used in the Asynchronous Message Service (AMS) for message exchange between modules that share access to a particularly convenient communication medium, such as a shared-memory message queue. While the Primary Transport Service (PTS) is universally available for message exchange, STSs can be employed to enhance application performance in certain scenarios (see CCSDS Blue Book Recommended Standard 735.1-B-1 \"Asynchronous Message Service\" for additional information).
A module's network location for receiving messages via a given transport service is its delivery point for that service. A module may have multiple delivery points, each characterized by the same service mode. For a given service mode, the list of all delivery points providing that mode to a module, ranked in descending order of preference (typically network performance), is termed the delivery vector for that service mode, for that module.
See \"Primary Transport Services\" below for additional information.
Every message space in AMS always includes at least one unit, the root unit, and each module is registered within a unit. In the simplest case, all modules reside in the root unit. Each unit is served by a single registrar, which monitors the health of all registered modules and propagates six types of message space configuration changes.
Registrars themselves register with the configuration server for the continuum containing the message space. A list of all potential network locations for the configuration server, ranked in descending order of preference, must be well-known and included in the AMS management information bases (MIBs) accessible to all registrars. Each continuum must always have an operational configuration server at one of these locations to enable registration of registrars and modules.
All registrars and modules of the same message space must register through the same configuration server.
Each module has a single meta-AMS delivery point (MAPD) for receiving MAMS messages. A new module joins a message space by registering within a unit, announcing its role name and MAPD to the unit's registrar. However, the module cannot have hard-coded information about the registrar's communication details, as these can change.
Therefore, the first step in registering a new module is contacting the configuration server at one of its known network locations. These locations, listed in descending order of preference, are included in the AMS Management Information Bases (MIBs) accessible to all application modules. The configuration server then provides the new module with the contact details for its registrar.
The module obtains a unique module number from the registrar and completes registration. The registrar ensures that all other modules in the message space learn the new module's role name, module number, and MAPD. These modules, in turn, announce their own details to the new module.
Maintaining accurate knowledge of a message space configuration is crucial for application purposes and resource efficiency. Each registrar must promptly detect the termination of modules in its unit's registered membership. While a module under application control notifies its registrar upon termination, a module that crashes or is powered off does not. To address this, each module sends a \"heartbeat\" message to its registrar every few seconds (see comment #3 at top of amscommon.h for additional details). The registrar interprets three consecutive missing heartbeats as a module termination.
Upon detecting a module's termination, either overt or imputed from heartbeat failure, the registrar informs all other modules in the unit's registered membership and, through other registrars, all modules in the message space.
When termination is imputed from a heartbeat failure, the registrar attempts to notify the presumed terminated module. If the module is still running, it terminates immediately upon receiving this message, minimizing system confusion due to other application behavior triggered by the imputed termination.
Each registrar not only monitors the heartbeats of all modules in its unit's registered membership but also issues its own heartbeats to those modules. If a module detects three consecutive missing registrar heartbeats, it assumes the registrar has crashed. The module then re-queries the configuration server to determine the new network location of the registrar and resumes exchanging heartbeats.
This assumption is reasonable because the configuration server also monitors registrar heartbeats on a slightly shorter cycle. If the configuration server detects three consecutive missing registrar heartbeats, it takes action to restart the registrar, possibly on a different host. Therefore, by the time the registrar's modules detect its crash, it should already be running again.
Since the module heartbeat interval is two seconds (see N4 in amscommon.h), the registrar will receive heartbeat messages from every running module in the unit's registered membership within the first six seconds after restart. This allows the registrar to accurately know the unit's configuration. This accurate configuration information must be delivered to new modules at startup, enabling them to orient a newly-restarted registrar if it crashes. Therefore, during the first six seconds after the registrar starts, it only accepts MAMS messages from modules already registered in the unit. This prevents the risk of delivering incorrect information to a new module.
A configuration server, like any other component, can also fail or be rebooted. Each registrar interprets three consecutive missing configuration server heartbeats as an indication of a crash. Upon detecting such a crash, the registrar cycles through all the known network locations for the continuum's configuration server, attempting to re-establish communication after the server's restart, possibly at an alternate network location. New modules attempting to register will also cycle through network locations seeking a restarted configuration server and will be unable to contact their registrars, and therefore unable to register, until they find one. However, application message exchange and subscription management activity among existing modules and registrars are not affected by this infrastructure failure.
Upon the configuration server's restart at one of its known network locations, all registrars will eventually find it and re-announce themselves, enabling newly registering application modules to successfully register.
In certain failure scenarios, multiple configuration servers may operate concurrently for a brief period, such as when a perceived failure is caused by a transient network connectivity issue rather than an actual server crash. To resolve this, each running configuration server periodically sends an \"I am running\" MAMS message to every lower-ranking configuration server network location in the known list of configuration server locations. If a configuration server receives such a message, it immediately terminates. All registrars and modules communicating with it will detect its disappearance and search again for the highest-ranking reachable configuration server, eventually restoring orderly operations in the continuum.
Finally, every registrar can optionally be configured to re-advertise to the entire message space the detailed configuration of its unit's registered membership (all active modules, all subscriptions and invitations) at some user-specified frequency, e.g., once per minute. This capability is referred to as configuration resync. Configuration resync of course generates additional message traffic, and it may be unnecessary in extremely simple or extremely stable operating environments. But it does ensure that every change in application message space configuration will eventually be propagated to every module in the message space, even if some MAMS messages are lost and even if an arbitrary number of registrars had crashed at the time the change occurred.
Taken together, these measures make AMS applications relatively fault tolerant:
a. When a module crashes, its registrar detects the loss of heartbeat within three heartbeat intervals and notifies the rest of the message space. Application message transmission everywhere is unaffected.When a registrar crashes, its configuration server detects the loss of heartbeat within three heartbeat intervals and takes action to restart the registrar. During the time that the unit has no registrar, transmission of application messages among modules of the message space is unaffected, but the heartbeat failures of crashed modules are not detected and reconfiguration messages originating in the unit's registered membership (registrations, terminations, subscription and invitation assertions, and subscription and invitation cancellations) are not propagated to any modules. However, after the registrar is restarted it will eventually detect the losses of heartbeat from all crashed modules and will issue obituaries to the message space, and if configuration resync is enabled it will eventually re- propagate the lost reconfiguration messages.
b. When a configuration server crashes, all new registration activity will come to a standstill. But no application modules fail (at least, not because of communication failure), and on restart of the configuration server the registration of new modules eventually resumes.
AMS can be configured to confine service access to application modules that can prove they are authorized to participate. For this purpose, asymmetric MAMS encryption may be used as follows:
a. The AMS MIB exposed to the configuration server contains a list of all applications for which registration service may be offered, identified by application name. Associated with each application name is the AMS public encryption key for that application.
b. The AMS MIB exposed to every registrar in each message space contains a list of all functional role names defined for the message space's application; this list limits the role names under which modules may register in that message space. Associated with each role name is the AMS public encryption key for the application module(s) that may register in that role.
c. The AMS MIBs exposed to all registrars and application modules in the message space contain the AMS public encryption key of the configuration server.
d. The AMS MIBs exposed to the configuration server and to all registrars and application modules in the message space contain the private encryption keys that are relevant to those entities.
As described later, this information is used to authenticate registrar registration and exclude spurious registrars from the message space, to authenticate module registration attempts and deny registration to unauthorized application modules, and to assure the authenticity, confidentiality, and integrity of MAMS traffic exchanged between modules and their registrars.
In addition, the confidentiality and integrity of AMS message exchange may be protected at subject granularity. The AMS MIB exposed to each module of a given message space may contain, for any subset of the message subjects (identified by name and number) used in the message space's application:
e. a list of the role names of all modules that are authorized senders of messages on this subject;
f. a list of the role names of all modules that are authorized receivers of messages on this subject;
g. encryption parameters, including a symmetric encryption key, enabling encryption of messages on this subject.
This information may be used to support secure transmission of messages on selected subjects.
Note*, though, that the JPL implementation of AMS does not implement* any of the cryptographic algorithms that are required to support these security features.
The structure of the content of messages on a given subject is application-specific; message content structure is not defined by the AMS protocol. However, the AMS MIB exposed to all modules of a given message space will contain, for each message subject (identified by name and number) used in the message space:
a. a description of this message subject, discussing the semantics of this type of message;
b. a detailed specification of the structure of the content of messages on this subject;
c. optionally, a specification of the manner in which a correctly assembled message is marshaled for network transmission in a platform-neutral manner and, on reception, un-marshaled into a format that is suitable for processing by the application.
When AMS is requested to send a message on a given subject, the message content that is presented for transmission is always in a format that is suitable for processing by the application. In the event that this format is not suitable for network transmission in a platform-neutral manner, as indicated by the presence in the MIB of a marshaling specification for this subject, AMS will marshal the message content as required before transmitting the message.
When AMS receives a message on a subject for which a marshaling specification is present in the MIB, AMS will un-marshal the message content into a format that is suitable for processing by the application before delivering the message.
Message subjects, as noted earlier, are integers with application-defined semantics. This minimizes the cost of including subject information (in effect, message type) in every message, and it makes processing simpler and faster: subscription and invitation information are recorded in arrays that are indexed by subject number.
This implementation choice, however, requires that message management control arrays be large enough to accommodate the largest subject numbers used in the application. The use of extremely large subject numbers would therefore cause these arrays to consume significant amounts of memory. In general, it is best for an AMS application to use the smallest subject numbers possible, starting with 1.
AMS' asynchronous message issuance model allows for a high degree of concurrency in the operations of data system modules. This means that a module can issue a message without suspending its operation until a response is received. This feature also largely insulates applications from variations in signal propagation time across the AMS continuum.
However, some critical MAMS (Multicast AMS) communication is unavoidably synchronous. For instance, a newly registering module must wait for responses from the configuration server and the registrar before it can proceed with application activity. Therefore, the core AMS protocol is best suited for operational contexts with generally uninterrupted network connectivity and relatively small and predictable signal propagation times, such as the Internet or a stand-alone local area network. It is typically advantageous for all entities within a single AMS continuum to operate within such a \"low-latency\" environment
AMS application messages can be exchanged between modules in different AMS continua using the Remote AMS (RAMS) procedures. These procedures are executed by special-purpose application modules known as RAMS gateways. Each RAMS gateway interfaces with two communication environments: the AMS message space it serves and the RAMS network, which is a mesh or tree of mutually aware RAMS gateways. This network enables AMS messages produced in one message space to be forwarded to other message spaces within the same venture.. RAMS gateways operate as follows:
a. RAMS gateways operate by opening private RAMS network communication channels to the RAMS gateways of other message spaces within the same venture. These interconnected gateways use these communication channels to forward message petition assertions and cancellations among themselves.
b. Each RAMS gateway subscribes locally to all subjects that are of interest in any of the linked message spaces.
c. When a RAMS gateway receives a message on any of these subjects, it uses the RAMS network to forward the message to every other linked RAMS gateway whose message space contains at least one module that has subscribed to messages on that subject.
d. On receiving a message the RAMS gateway module forwards the message to any subscribers in its own message space.
The RAMS protocol allows for the free flow of published application messages across deep space links while ensuring efficient utilization of those links. Only a single copy of any message is ever transmitted on any RAMS grid communication channel, regardless of how many subscribers will receive copies when the message reaches its destination.
RAMS operations generalize the AMS architecture as shown in Figure 2 below.
Figure 2 General AMS application structure
This extension of the publish/subscribe model to inter-continuum communications is invisible to application modules. Application functionality is unaffected by these details of network configuration, and the only effects on behavior being those intrinsic to variability in message propagation latency.
It's important to note that the nature of the RAMS network communication channels depends on the implementation of the RAMS network. To communicate over the RAMS network for a given venture, each RAMS gateway must know the RAMS network location, expressed as an endpoint in the protocol used to implement the RAMS network.
Also, only AMS application messages are propagated across continuum boundaries by RAMS. Modules are never notified of registrations, subscriptions, and invitations that occur in remote continua. The purpose of RAMS is to limit traffic on the scarce link resources supporting inter-continuum communication to the minimum necessary for successful operation of the venture. MAMS message traffic within a message space is required to enable the operation of the message space, but venture-wide application message exchange can readily be provided without propagating MAMS messages to remote continua.
"},{"location":"AMS-Programmer-Guide/#the-jpl-implementation","title":"The JPL Implementation","text":"JPL's implementation of AMS has the following components:
The codebase, written in C, relies on a shared library, ICI. This library supports other JPL implementations, like CFDP and the DTN Bundle Protocol. ICI includes a \"platform\" portability layer, easing code compilation and execution in environments like Linux, vxWorks, and Interix.
ICI also includes its own dynamic memory management system, called \"PSM\", which provides dynamic management of a privately allocated block of memory. This may be useful in environments such as spacecraft flight software where the dynamic management of system memory (malloc, free) cannot be tolerated. Use of PSM by AMS is optional.
An AMS application program, linked with libams, uses the ams_register function to instantiate an AMS module registered within a specified unit of a specified message space. Once registration is accomplished, the application may commence inviting, subscribing to, publishing, announcing, sending, and replying to messages.
This AMS implementation is multi-threaded. The process of registration starts a pair of POSIX threads, or pthreads, which manage timing and MAMS events in the background. Additionally, another pthread is started to receive MAMS messages via the primary transport service and add them to the MAMS event queue. This queue also includes MAMS message transmission requests. For each transport service that the module can receive AMS messages from, one more pthread is started. These threads receive AMS messages and add them to the AMS event queue, combining them with \"discovery\" events added by the MAMS event handling thread.
The general structure of an AMS module, then, is as shown in Figure 3 below.
Figure 3 AMS module structure
The application program has the option to start another thread to manage AMS events. This thread automatically calls event-type-specific callback functions, leaving the main application thread free to respond to non-AMS events, such as mouse events or keyboard input. The application code can also add application-specific events to the AMS event queue, potentially with higher priority than any queued AMS messages. However, to prevent certain types of unusual application behavior, the main application thread is not allowed to receive and handle any AMS events while the background AMS event handling thread is running.
"},{"location":"AMS-Programmer-Guide/#primary-transport-services","title":"Primary Transport Services","text":"As shipped, AMS currently includes support for two underlying transport services: TCP, and DGR (Datagram Retransmission, a UDP-based system that includes congestion control and retransmission-based reliability). Although TCP is faster than DGR, its connection-based architecture makes it unsuitable as a primary transport service: all MAMS message traffic is conveyed via connectionless DGR.
"},{"location":"AMS-Programmer-Guide/#installation","title":"Installation","text":"AMS source is provided in the ION distribution (a gzipped tarfile containing AMS and all supporting ION packages: ici, dgr, ltp, and bp, etc.).
The following two installation methods are provided.
"},{"location":"AMS-Programmer-Guide/#automake","title":"Automake","text":"This method automatically compiles and links all required executables, installs them, and copies ION library headers to the relevant system path(s) on your system.Use the following command sequence in the unzipped ION source directory (Linux).
./configure\nmake\nsudo make install\nsudo ldconfig\nNote: if support for the expat XML parsing library is required see 4.3 \"Support for the Expat XML Parsing Library\" below
"},{"location":"AMS-Programmer-Guide/#make","title":"Make","text":"This alternate installation method installs all ION packages (if run from ION root directory), or installs individual ION packages as follows
Note that for both install methods (e.g. on Linux) the default configuration used in the ION makefiles is as follows:
If you want a different configuration, you'll need to modify the makefiles accordingly (e.g. see the OPT variable in 2b above).
"},{"location":"AMS-Programmer-Guide/#support-for-the-expat-xml-parsing-library","title":"Support for the Expat XML Parsing Library","text":"The expat open-source XML parsing library is required by AMS only if MIBs use the XML format (see man amsxml and man amsrc for additional information).
Note that Linux environments typically have expat built in, but for VxWorks installations it is necessary to download and install expat prior to installing AMS.
To build ION with support for expat use the following flag during the .configure step of installation (see 4.1 \"Automake\" above):
./configure --with-expat
The AMS daemon program amsd can function as the configuration server for a continuum, as the registrar for one cell of a specified message space, or both. To run it, enter a command of the following form at a terminal window prompt:
amsd mib_source_name eid_spec
or
amsd mib_source_name eid_spec application_name authority_name unit_name
The former form of the command starts amsd as a configuration server only.
mib_source_name is as discussed in the documentation of ams_register below; it enables amsd to run.
eid_spec is a string that specifies the IP address and port that amsd must establish in order to receive MAMS messages in its capacity as a configuration server. See man amsd for more information.
When the latter form of the amsd command is used, the daemon is configured to function as the registrar for the indicated message space unit. If the value \".\" (period character) is supplied for eid_spec, then the daemon will [only] function as a registrar. Otherwise the daemon will function as both configuration server and registrar; this option can be useful when operating a simple, stand-alone message space, such as a demo.
"},{"location":"AMS-Programmer-Guide/#c-application-programming-interface","title":"\"C\" Application Programming Interface","text":"The AMS application programming interface is defined by the header file ams.h, which must be #included at the beginning of any AMS application program source file.
See section 9 'Application Development Guide' for compilation and linkage instructions.
"},{"location":"AMS-Programmer-Guide/#type-and-macro-definitions","title":"Type and Macro Definitions","text":"#define THIS_CONTINUUM (-1)\n#define ALL_CONTINUA (0)\n#define ANY_CONTINUUM (0)\n#define ALL_SUBJECTS (0)\n#define ANY_SUBJECT (0)\n#define ALL_ROLES (0)\n#define ANY_ROLE (0)\n\ntypedef enum\n{\nAmsArrivalOrder = 0, AmsTransmissionOrder\n} AmsSequence;\n\ntypedef enum\n{\nAmsBestEffort = 0, AmsAssured\n} AmsDiligence;\n\ntypedef enum\n{\nAmsMsgUnary = 0, AmsMsgQuery, AmsMsgReply, AmsMsgNone\n} AmsMsgType;\n\ntypedef struct amssapst *AmsModule; typedef struct amsevtst *AmsEvent;\n\n/* AMS event types. */\n#define AMS_MSG_EVT 1\n#define TIMEOUT_EVT 2\n#define NOTICE_EVT 3\n#define USER_DEFINED_EVT 4\n\n\ntypedef enum\n{\nAmsRegistrationState, AmsInvitationState, AmsSubscriptionState\n} AmsStateType;\n\ntypedef enum\n{\nAmsStateBegins = 1, AmsStateEnds\n} AmsChangeType;\n\ntypedef void (*AmsMsgHandler)(AmsModule module, void *userData, AmsEvent *eventRef, int continuumNbr, int unitNbr,\nint moduleNbr, int subjectNbr,\nint contentLength, char *content,\nint context, AmsMsgType msgType, int priority);\n\ntypedef void (*AmsRegistrationHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr, int roleNbr);\n\ntypedef void (*AmsUnregistrationHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr);\n\ntypedef void (*AmsInvitationHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr,\nint domainRoleNbr,\nint domainContinuumNbr, int domainUnitNbr,\nint subjectNbr, int priority,\nunsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence);\n\ntypedef void (*AmsDisinvitationHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr,\nint domainRoleNbr,\nint domainContinuumNbr, int domainUnitNbr,\nint subjectNbr);\n\ntypedef void (*AmsSubscriptionHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr,\nint domainRoleNbr,\nint domainContinuumNbr, int domainUnitNbr,\nint subjectNbr, int priority,\nunsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence);\n\ntypedef void (*AmsUnsubscriptionHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr,\nint domainRoleNbr,\nint domainContinuumNbr, int domainUnitNbr,\nint subjectNbr);\n\ntypedef void (*AmsUserEventHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int code,int dataLength, char *data);\n\ntypedef void (*AmsMgtErrHandler)(void *userData, AmsEvent *eventRef);\ntypedef struct\n{\nAmsMsgHandler msgHandler;\nvoid *msgHandlerUserData;\nAmsRegistrationHandler registrationHandler;\nvoid *registrationHandlerUserData; AmsUnregistrationHandler unregistrationHandler;\nvoid *unregistrationHandlerUserData;\nAmsInvitationHandler invitationHandler;\nvoid *invitationHandlerUserData; AmsDisinvitationHandler disinvitationHandler;\nvoid *disinvitationHandlerUserData; AmsSubscriptionHandler subscriptionHandler;\nvoid *subscriptionHandlerUserData; AmsUnsubscriptionHandler unsubscriptionHandler;\nvoid *unsubscriptionHandlerUserData;\nAmsUserEventHandler userEventHandler;\nvoid *userEventHandlerUserData;\nAmsMgtErrHandler errHandler;\nvoid *errHandlerUserData;\n} AmsEventMgt;\n\n/* Predefined term values for ams_query and ams_get_event. */ \n#define AMS_POLL (0) /* Return immediately. */ \n#define AMS_BLOCKING (-1) /* Wait forever. */\nint ams_register(char *mibSource, char *tsorder, char *applicationName, char *authorityName, char *unitName, char *roleName, AmsModule\n*module);\nThis function is used to initiate the application's participation as a module in the message space identified by specified application and authority names, within the local AMS continuum.
mibSource indicates the location of the Management Information Base (MIB) information that will enable the proposed new module to participate in its chosen message space. Nominally it is the name of an XML file in the current working directory; if NULL, mibSource defaults to roleName.xml. (A future version of loadmib.c might load MIB information from an ICI \"sdr\" database rather than from a file.)
tsorder is the applicable overriding transport service selection order string. This capability is not yet fully supported; for now, tsorder should always be NULL.
applicationName identifies the AMS application within which the proposed new module is designed to function. The application must be declared in the MIB.
authorityName, together with applicationName, identifies the message space in which the new module proposes to register. The message space must be declared in the MIB.
unitName identifies the cell, within the specified message space, in which the new module proposes to register. The unit must be declared in the MIB for ventures containing the specified message space, and a registrar for this cell of this message space must currently be running in order for the ams_register function to succeed.
roleName identifies the functional role that the proposed new module is designed to perform within the indicated application. The role must be declared in the MIB for that application, and its name will serve as the name of the module.
module points to the variable in which the applicable AMS service access point will be returned upon successful registration of the new module.
The function returns 0 on success, -1 on any error.
The application thread that invoked ams_register is assumed by AMS to be the main application thread for the module, or \"prime thread\". Following successful completion of ams_register all threads of the application process may commence invoking AMS services -- inviting messages, publishing messages, etc. -- except that only the prime thread may receive AMS events, e.g., process incoming messages.
int ams_get_module_nbr(AmsModule module);\nThe function returns the unique identifying number (within its chosen cell) assigned to the indicated module as a result of successful registration.
int ams_get_unit_nbr(AmsModule module);\nThe function returns the number that uniquely (within the message space) identifies the cell in which the module registered. The combination of unit number and module number uniquely identifies the module within its message space.
int ams_set_event_mgr(AmsModule module, AmsEventMgt\n *rules);\nThe function starts a background \"event manager\" thread that automatically receives and processes all AMS events (messages, notices of message space configuration change, etc.) enqueued for the indicated module.
The thread processes each event according to the indicated rules structure; any event for which a NULL callback function is provided is simply discarded. For details of the rules structure and prototype definitions for the callback functions that the rules point to, see 6.1 above. Some notes on this interface:
While the event manager thread is running, the prime thread is prohibited from receiving any AMS events itself, i.e., ams_get_event will always fail.
Only the prime thread may call ams_set_event_mgr. The function returns 0 on success, -1 on any error.
void ams_remove_event_mgr(AmsModule module);\nint ams_unregister(AmsModule module);\nOnly the prime thread may call ams_unregister. The function returns 0 on success, -1 on any error.
"},{"location":"AMS-Programmer-Guide/#message-subscription-and-invitation","title":"Message Subscription and Invitation","text":" int ams_invite (AmsModule module, int roleNbr, int\n continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char\n flowLabel, AmsSequence sequence, AmsDiligence diligence);\nmodule must be a valid AMS service access point as returned from ams_register.
roleNbr identifies the role that constrains the invitation: only messages from modules registered as performing the indicated role are included in this invitation. If zero, indicates \"all modules\".
continuumNbr identifies the continuum that constrains the invitation: only messages from modules operating within the indicated continuum are included in this invitation. If -1, indicates \"the local continuum\". If zero, indicates \"all continua\".
unitNbr identifies the unit that constrains the invitation: only messages from modules registered in cells identified by the indicated number -- or in cells that are contained within such cells -- are included in this invitation. A reminder: cell zero is the \"root cell\", encompassing the entire message space.
subjectNbr identifies the subject that constrains the invitation: only messages on the indicated subject are included in this invitation.
priority indicates the level of priority (from 1 to 15, where 1 is the highest priority indicating greatest urgency) at which the inviting module prefers that messages responding to this invitation be sent.
flowLabel specifies the flow label (a number from 1 to 255, which AMS may pass through to transport service adapters for quality-of-service specification purposes) that the inviting module asks issuing modules to cite when sending messages in response to this invitation. Flow label 0 signifies \"no flow label.\"
sequence indicates the minimum level of transmission order preservation that the inviting module requires for messages responding to this invitation.
diligence indicates the minimum level of reliability (based on acknowledgement and retransmission) that the inviting module requires for messages responding to this invitation.
The function returns 0 on success, -1 on any error. When successful, it causes the invitation to be propagated automatically to all modules in the inviting module's own message space.
int ams_disinvite (AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr);\nThis function terminates the module's prior invitation for messages on a specified subject under specified conditions. roleNbr, continuumNbr, unitNbr, and subjectNbr must be identical to those that characterized the invitation that is to be terminated. The function returns 0 on success, -1 on any error. When successful, it causes cancellation of the invitation to be propagated automatically to all modules in the inviting module's own message space.
int ams_subscribe (AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence);\nThis function establishes the module's request to receive a copy of every future message published on a specified subject, under specified conditions, and states the quality of service at which the module would prefer those messages to be sent. Subscriptions are implicitly constrained by venture number: only messages from modules registered in messages spaces characterized by the same application and authority names as the message space in which the subscribing module itself is registered are included in any subscription.
module must be a valid AMS service access point as returned from ams_register.
roleNbr identifies the role that constrains the subscription: only messages from modules registered as performing the indicated role are included in this subscription. If zero, indicates \"all modules\".
continuumNbr identifies the continuum that constrains the subscription: only messages from modules operating within the indicated continuum are included in this subscription. If -1, indicates \"the local continuum\". If zero, indicates \"all continua\".
unitNbr identifies the unit that constrains the subscription: only messages from modules registered in cells identified by the indicated number -- or in cells that are contained within such cells -- are included in this subscription. A reminder: cell zero is the \"root cell\", encompassing the entire message space.
subjectNbr identifies the subject that constrains the subscription: only messages on the indicated subject are included in this subscription. subjectNbr may be zero to indicate that messages published on all subjects are requested; in this case, continuumNbr must be -1.
priority indicates the level of priority (from 1 to 15, where 1 is the highest priority indicating greatest urgency) at which the subscribing module prefers that messages responding to this subscription be sent.
flowLabel specifies the flow label (a number from 1 to 255, which AMS may pass through to transport service adapters for quality-of-service specification purposes) that the subscribing module asks issuing modules to cite when publishing messages in response to this subscription. Flow label 0 signifies \"no flow label.\"
sequence indicates the minimum level of transmission order preservation that the subscribing module requires for messages responding to this subscription.
diligence indicates the minimum level of reliability (based on acknowledgement and retransmission) that the subscribing module requires for messages responding to this subscription.
The function returns 0 on success, -1 on any error. When successful, it causes the subscription to be propagated automatically to all modules in the subscribing module's own message space.
int ams_unsubscribe (AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr);\nThis function terminates the module's prior subscription to messages on a specified subject under specified conditions. roleNbr, continuumNbr, unitNbr, and subjectNbr must be identical to those that characterized the subscription that is to be terminated. The function returns 0 on success, -1 on any error. When successful, it causes cancellation of the subscription to be propagated automatically to all modules in the subscribing module's own message space.
"},{"location":"AMS-Programmer-Guide/#configuration-lookup","title":"Configuration Lookup","text":" int ams_lookup_unit_nbr (AmsModule module, char\n *unitName);\n int ams_lookup_role_nbr (AmsModule module, char\n *roleName);\n int ams_lookup_subject_nbr (AmsModule module, char\n *subjectName);\n int ams_lookup_continuum_nbr (AmsModule module, char\n *continuumName);\n char * ams_lookup_unit_name (AmsModule module, int\n unitNbr);\n char * ams_lookup_role_name (AmsModule module, int\n roleNbr);\n char * ams_lookup_subject_name (AmsModule module, int\n subjectNbr);\n char * ams_lookup_continuum_name (AmsModule module, int\n continuumNbr);\n char * ams_get_role_name (AmsModule module, int unitNbr,\n int moduleNbr);\n Lyst ams_list_msgspaces (AmsModule module);\n int ams_subunit_of (AmsModule module, int argUnitNbr, int\n refUnitNbr);\n int ams_get_continuum_nbr ();\n int ams_continuum_is_neighbor (int continuumNbr);\n int ams_rams_net_is_tree (AmsModule module);\n int ams_publish (AmsModule module, int subjectNbr, int\n priority, unsigned char flowLabel, int contentLength, char *content,\n int context);\npriority may be any value from 1 to 15, overriding the priority preference(s) asserted by the subscriber(s), or it may be zero indicating \"use each subscriber's preferred priority.\" flowLabel may be any value from 1 to 255, overriding the flow label preference(s) asserted by the subscriber(s), or it may be zero indicating \"use each subscriber's preferred flow label.\"
The function returns 0 on success, -1 on any error.
int ams_send (AmsModule module, int continuumNbr, int\n unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char\n flowLabel, int contentLength, char *content, int context);\nIf continuumNbr is -1, the local continuum is inferred.
priority may be any value from 1 to 15, overriding the priority preference asserted by the destination module, or it may be zero indicating \"use the destination module's preferred priority.\" flowLabel may be any value from 1 to 255, overriding the flow label preference asserted by the destination module, or it may be zero indicating \"use the destination module's preferred flow label.\"
The function returns 0 on success, -1 on any error.
int ams_query (AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context, int term, AmsEvent *event);\nThe function returns 0 on success, -1 on any error.
int ams_reply (AmsModule module, AmsEvent msg, int\n subjectNbr, int priority, unsigned char flowLabel, int contentLength,\n char *content);\nThe function returns 0 on success, -1 on any error.
int ams_announce (AmsModule module, int roleNbr, int\n continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char\n flowLabel, int contentLength, char *content, int context);\ncontinuumNbr indicates \"the local continuum\"; a value of zero indicates \"all continua\".
priority may be any value from 1 to 15, overriding the priority preference(s) asserted by the destination module(s), or it may be zero indicating \"use each destination module's preferred priority.\" flowLabel may be any value from 1 to 255, overriding the flow label preference(s) asserted by the destination module(s), or it may be zero indicating \"use each destination module's preferred flow label.\"
The function returns 0 on success, -1 on any error.
"},{"location":"AMS-Programmer-Guide/#event-including-message-reception","title":"Event (Including Message) Reception","text":"int ams_get_event (AmsModule module, int term, AmsEvent\n *event);\nThe function returns 0 on success, -1 on any error. Following acquisition of an event, the application program should:
int ams_get_event_type (AmsEvent event);\n int ams_parse_msg (AmsEvent event, int *continuumNbr,\n int *unitNbr, int *moduleNbr, int *subjectNbr, int *contentLength, char **content,\n int *context, AmsMsgType *msgType, int *priority, unsigned char *flowLabel);\nint ams_parse_notice (AmsEvent event, AmsStateType\n *state, AmsChangeType *change, int *unitNbr, int *moduleNbr, int *roleNbr, int *domainContinuumNbr, int *domainUnitNbr, int *subjectNbr, int *priority, unsigned char *flowLabel, AmsSequence *sequence, AmsDiligence *diligence);\nstate and change indicate the nature of the change.
unitNbr and moduleNbr identify the module to which the change pertains.
roleNbr is provided in the event that the change is the registration of a new module (in which case it indicates the functional nature of the new module) or is a subscription, unsubscription, invitation, or disinvitation (in which case it indicates the role constraining the subscription or invitation).
For a notice of subscription, unsubscription, invitation, or disinvitation:
For a notice of subscription or invitation, priority, flowLabel, sequence, and diligence indicate the quality of service requested by the module for this subscription or invitation.
Returns 0 unless one or more of the arguments provided to the function are NULL, in which case the function returns -1.
int ams_parse_user_event (AmsEvent event, int *code, int *dataLength, char **data);\n int ams_recycle_event (AmsEvent event);\n int ams_post_user_event (AmsModule module, int\n userEventCode, int userEventDataLength, char *userEventData, int\n priority);\npriority may be any value from 0 to 16. Note that this enables the application to post an event to itself that is guaranteed to be of higher priority than any message -- assuring that it will be processed before any message that is currently enqueued or that arrives in the future -- or, alternatively, to post an event that is guaranteed to be of lower priority than any message and will therefore only be processed during a lull in message reception.
Returns 0 on success, -1 on any error.
"},{"location":"AMS-Programmer-Guide/#remote-ams","title":"Remote AMS","text":"The JPL implementation of Remote AMS comprises a library (librams.c) and a sample RAMS gateway program (ramsTest.c) that uses that library.
"},{"location":"AMS-Programmer-Guide/#library","title":"Library","text":"The RAMS library implements a very simple API, which is defined by the header file
rams.h and comprises just a single function:
int rams_run (char *mibSource, char *tsorder, char\n *applicationName, char *authorityName, char *unitName, char\n *roleName, int lifetime);\nNote that the priority assigned to any DTN bundle that conveys a published or privately sent AMS message over the RAMS network will be computed as a function of the flow label specified at the time the message was originally published or sent. If no overriding flow label was specified, then the bundle priority will be 1 (standard). Otherwise, the number represented by the two low-order bits of the flow label will be used as the bundle priority and two \"extended class of service\" parameters will be derived from the next two higher-order bits of the flow label: bit 5 (the 3^rd^-lowest-order bit) will be used as the value of the \"minimum latency\" flag, with a value of 1 indicating that the bundle is critical, and bit 4 (the 4^th^-lowest-order bit) will be used as the value of the \"best-effort\" flag, with a value of 1 indicating that the bundle should be sent over an unacknowledged convergence-layer protocol. All bundles issued by the RAMS gateway that don't carry AMS messages will be assigned bundle priority 1.
This function runs indefinitely until it fails or is interrupted by a SIGINT signal. Returns -1 on any failure, 0 on normal termination.
"},{"location":"AMS-Programmer-Guide/#ramsgate","title":"ramsgate","text":"The sample RAMS gateway program ramsgate provides basic RAMS gateway functionality. To run it, enter a command of the following form at a terminal window prompt:
ramsgate *application_name authority_name_name lifetime*\n [*memory_size* [*memory_manager_name*]]\nNote that ramsgate relies on the ION implementation of DTN; be sure an ION node is operating on the local computer before starting ramsgate. (See the ION Design and Operations Guide for details.)
To terminate operation of the gateway process, just use CTRL-C to interrupt the program.
"},{"location":"AMS-Programmer-Guide/#management-information-base","title":"Management Information Base","text":"In order to operate correctly, every AMS application process -- and amsd as well -- must initially load Management Information Base (MIB) values that are universally consistent.
Currently this is accomplished automatically during registration: MIB value declaration commands in XML format are read from a file, parsed, and processed automatically.
"},{"location":"AMS-Programmer-Guide/#mib-file-syntax","title":"MIB file syntax","text":"The elements of the XML files used to load AMS MIBs are as follows: [ams_mib_load] : contains a series of MIB load commands.
Attributes: none
[ams_mib_init] : command that initializes the MIB. Attributes:
continuum_nbr: the number identifying the local continuum ptsname: the name of the primary transport service
[ams_mib_add] : contains a series of elements that add items to the MIB.
Attributes: none
[continuum] :
Attributes:
nbr: the number that identifies this continuum name: the name that identifies this continuum
neighbor: a Boolean indication (\"1\" or \"0\") of whether or not this is a neighboring continuum [If omitted, the continuum is by default assumed to be a neighbor -- that is, an implicit neighbor=\"1\" attribute is the default.]
desc: a brief textual description of this continuum
[csendpoint] : configuration server endpoint specification (i.e., network location of configuration server)
Attributes:
epspec: PTS-specific endpoint specification string (to be more fully documented in a later edition of this [Programmer's Guide] )
[application] : defines an application Attributes:
name: name of application
[venture] : defines a venture (an instance of an application) Attributes:
[nbr]: the number that identifies this venture
[appname]: the name of the application served by this venture
[authname]: the name of the authority responsible for this instance of this application
[net_config]: the configuration (\"mesh\" or \"tree\") of the RAMS network comprising all AMS continua that participate in this venture. If omitted, the RAMS network configuration is by default assumed to be a mesh.
[gweid]: a string identifying the endpoint for the local continuum's RAMS gateway within the RAMS network for this venture; default is \"bp@ipn:local_continuum_nbr.venture_nbr\"
root_cell_resync_period: the period (expressed as a count of registrar heartbeats) on which the configuration of the root unit of this venture will automatically be resynchronized. If omitted or set to zero, automatic resync is disabled within the root unit.
[role] : defines a role within a venture Attributes:
[nbr]: the number that identifies this role
[name]: the name that identifies this role
[subject] : defines a message subject within a venture Attributes:
[nbr]: the number that identifies this subject
[name]: the name that identifies this subject
[desc]: a brief textual description of this message subject
[element] : defines one of the elements (fields) of a message on a given subject (note that elements must be defined in the order in which they appear in the message, without omission)
Attributes:
[type]: a number that specifies the data type of this element (1 = long, 2 = int, 3 = short, 4 = char, 5 = string)
[name]: the name that identifies this element
[desc]: a brief textual description of this message field. [unit] : defines a unit of a venture
Attributes:
[nbr]: the number that identifies this unit name: the name that identifies this unit
[resync_period]: the period (expressed as a count of registrar heartbeats) on which the configuration of this unit will automatically be resynchronized. If omitted or set to zero, automatic resync is disabled within this unit.
[msgspace] : identifies a remote continuum that contains a message space that is part of this venture
[Attributes]:
[nbr]: the number that identifies the continuum containing this message space
[gweid]: a string identifying the endpoint for the indicated continuum's RAMS gateway, within the RAMS network for this venture; default is \"bp@ipn:continuum_nbr.venture_nbr\"
neighbor: Signifies adjacency of the message space with the parent continuum using a Boolean value (i.e. 1 is adjacent, 0 is non-adjacent). Note that in this context message space is analogous to continuum. If the neighbor attribute is omitted the default value is 1.
"},{"location":"AMS-Programmer-Guide/#a-sample-mib","title":"A Sample MIB","text":"<?xml version=\"1.0\" standalone=\"yes\"?>\n<ams_mib_load>\n<ams_mib_init continuum_nbr=\"1\" ptsname=\"dgr\"/>\n<ams_mib_add>\n<continuum nbr=\"2\" name=\"gsfc\"\" desc=\"Goddard Space Flight Center\"/>\n<csendpoint epspec=\"amroc.net:2502\"/>\n<application name=\"demo\"/>\n<venture nbr=\"9\" appname=\"demo\" authname=\"test\" >\n<role nbr=\"2\" name=\"shell\"/>\n<role nbr=\"3\" name=\"log\"/>\n<role nbr=\"4\" name=\"pitch\"/>\n<role nbr=\"5\" name=\"catch\"/>\n<role nbr=\"6\" name=\"benchs\"/>\n<role nbr=\"7\" name=\"benchr\"/>\n<subject nbr=\"1\" name=\"text\" desc=\"ASCII text\"/>\n<subject nbr=\"2\" name=\"noise\" desc=\"more ASCII text\"/>\n<subject nbr=\"3\" name=\"bench\" desc=\"numbered messages\"/>\n<unit nbr=\"1\" name=\"orbiters\"/>\n<unit nbr=\"2\" name=\"orbiters.near\"/>\n<unit nbr=\"3\" name=\"orbiters.far\"/>\n<msgspace nbr=\"2\" neighbor=1/>\n</venture>\n</ams_mib_add>\n</ams_mib_load>\nAMS applications (i.e. \"modules\") are custom software built using AMS' application programming interface (API). These AMS modules serve as the interfaces between AMS and mission-specific processes or applications.
"},{"location":"AMS-Programmer-Guide/#overview_1","title":"Overview","text":"A general overview of the required steps follows this sequence:
Applications created with the API must be compiled with links to ION's dynamic libraries.
The following two-step build procedure provides an example of how this works (note that the default path for installed ION library files (Linux) is used: /usr/local/lib/):
gcc -g -Wall -Werror -Dlinux -DUDPTS -DTCPTS -DDGRTS -DNOEXPAT -fPIC -DSPACE_ORDER=3 -I../library -I../include -I../rams -I/usr/local/include -c your_module_name.c\n\ngcc -g -Wall -Werror -Dlinux -DUDPTS -DTCPTS -DDGRTS -DNOEXPAT -fPIC -DSPACE_ORDER=3 -I../library -I../include -I../rams -I/usr/local/include -o your_module_name your_module_name.o -L./lib -L/usr/local/lib -lams -ldgr -lici -lpthread -lm*\nApplications must self-register with an AMS registrar. To facilitate this the following information is required by the application (i.e. using the ams_register() function):
Given this requirement, it may be useful (but not necessary) for the application to accept command line arguments.
An example command to start a custom AMS module might look like the following:
./your_module_name ' ' your_module_mib_role_name amsdemo test\nFollows is the complete source code for 'amshello', a simple Unix-based AMS application installed alongside AMS. It is a complete distributed system comprising two AMS application modules that functions as follows.
When the amshello program starts it fork()s into two processes, a \"pitcher\" and a \"catcher\". Both processes then register as modules in the root cell of an \"amsdemo/test\" message space. The catcher invites messages on subject \"text\" and waits for the first such message to arrive. The pitcher waits for an invitation to send messages of subject \"text\" and, when it arrives, sends one such message and terminates. When the catcher receives the message it prints the text of the message and then terminates.
To run the 'amshello' demonstration application the following 2 steps are required.
Important points regarding the above amsd command (see man amsd for additional details):
/*\namshello.c\n\"Hello world\" demonstration using AMS - Unix platform (only)\n\nCopyright (c) 2023, California Institute of Technology. \nSky DeBaun, Jet Propulsion Laboratory.\n\n\nThis program assumes the following conditions---------------\n1.) ION is running\n2.) An AMS Registrar is running \n3.) An AMS Configuration Server is running \n4.) An MIB configuration file has been created and is specified for use (see note below)\n\n*NOTE: the following command completes steps 2, 3, and 4 above (run this command after other ION processes start, then run the \u2018amshello\u2019 command from terminal to run the program):\n\namsd @ @ amsdemo test \"\" &\n\n\n*/\n\n#include \"ams.h\"\n\nstatic int runPitcher()\n{\n AmsModule me;\n AmsEvent evt;\n AmsStateType state;\n AmsChangeType change;\n int zn, nn, rn, dcn, dzn, sn, pr, textlen;\n unsigned char fl;\n AmsSequence sequence;\n AmsDiligence diligence;\n char buffer[80];\n\n isprintf(buffer, sizeof buffer, \"Hello from process %d\", (int) getpid());\n textlen = strlen(buffer) + 1;\n\n //register pitch module using default in-memory MIB (i.e. using the @)\n oK(ams_register(\"@\", NULL, \"amsdemo\", \"test\", \"\", \"pitch\", &me));\n\n while (1)\n {\n if (ams_get_event(me, AMS_BLOCKING, &evt) < 0) \n{\nreturn 0;\n}\nelse\n{\n ams_parse_notice(evt, &state, &change, &zn, &nn, &rn, &dcn,\n &dzn, &sn, &pr, &fl, &sequence, &diligence);\n ams_recycle_event(evt);\n}\n\n if (state == AmsInvitationState && sn == 1)\n {\n printf(\"Process %d sending: '%s'\\n\", (int) getpid(), buffer);\n fflush(stdout);\n ams_send(me, -1, zn, nn, 1, 0, 0, textlen, buffer, 0);\n ams_unregister(me); \nreturn 0;\n }\n }\n}\n\nstatic int runCatcher()\n{\n AmsModule me;\n AmsEvent evt;\n int cn, zn, nn, sn, len, ct, pr;\n unsigned char fl;\n AmsMsgType mt;\n char *txt;\n\n //register catch module using default in-memory MIB (i.e. @)\n oK(ams_register(\"@\", NULL, \"amsdemo\", \"test\", \"\", \"catch\", &me));\n ams_invite(me, 0, 0, 0, 1, 8, 0, AmsArrivalOrder, AmsAssured);\n\n while (1)\n {\n if (ams_get_event(me, AMS_BLOCKING, &evt) < 0) return 0;\n if (ams_get_event_type(evt) == AMS_MSG_EVT) break;\n else ams_recycle_event(evt);\n }\n\n ams_parse_msg(evt, &cn, &zn, &nn, &sn, &len, &txt, &ct, &mt, &pr, &fl);\n printf(\"Process %d received: '%s'\\n\", (int) getpid(), txt); fflush(stdout);\n ams_recycle_event(evt); ams_unregister(me); return 0;\n}\n\n\nint main(void) \n{\n pid_t pid = fork();\n\n if (pid == -1) {\n fprintf(stderr, \"Failed to create child process.\\n\");\n return EXIT_FAILURE;\n }\n\n if (pid == 0)\n //child process runs transmitter----------------------\n runPitcher();\n else \n {\n //parent process runs receiver------------------------\n runCatcher();\n }\n\n return 0;\n}\nThe research described in this publication was carried out at the Jet Propulsion Laboratory, California Institute of Technology, under a contract with the National Aeronautics and Space Administration.
"},{"location":"BP-Service-API/","title":"BP Service API","text":"This tutorial goes over the basic user APIs for developing application software to take advantage of the Bundle Protocol (BP) services provided by ION.
"},{"location":"BP-Service-API/#pre-requisite","title":"Pre-requisite","text":"For a user-developed software to utilize BP services provided by ION, there are two pre-requisite conditions: (1) ION services must be properly configured and already running in a state ready to provide BP services, and (2) BP libraries and header files must be installed and linked to the user application.
"},{"location":"BP-Service-API/#check-ion-installation-bp-version","title":"Check ION Installation & BP Version","text":"A simple way to check if ION is installed in the host is to determine the installation location of ION, one can execute which ionadmin and it will show the directory where ionadmin is currently located:
$ which ionadmin\n/usr/local/bin/ionadmin\nIf ionadmin is not found, it means either ION was not built or not properly installed in the execution path. If ionadmin is found, run it and provide the command v at the : prompt to determine the installed ION software version. For example:
$ ionadmin\n: v\nION-OPEN-SOURCE-4.1.2\nQuit ionadmin by command q. Quitting ionadmin will not terminate any ION and BP services, it simply ends ION's user interface for configuration query and management. If you see warning messages such as those shown below when quitting ionadmin, then it confirms that ION is actually not running at the moment. There are no software error:
: q\nat line 427 of ici/library/platform_sm.c, Can't get shared memory segment: Invalid argument (0)\nat line 312 of ici/library/memmgr.c, Can't open memory region.\nat line 367 of ici/sdr/sdrxn.c, Can't open SDR working memory.\nat line 513 of ici/sdr/sdrxn.c, Can't open SDR working memory.\nat line 963 of ici/library/ion.c, Can't initialize the SDR system.\nStopping ionadmin.\nYou can also run bpversion to determine the version of Bundle Protocol built in the host:
$ bpversion\nbpv7\nOnce it is determined that ION has been installed, a user may want to determine whether BP service is running by checking for the presence of various BP daemons and shared memory/semaphores, which are created by ION for interprocess communications among the various the BP service daemons.
To check if BP service is running, you can list current running processes using ps -aux command and inspect if you see the following BP service daemons:
rfxclock - background daemon that schedules ION network configuration eventsbpclm - background daemon that selects and meters data transmission to outbound convergence layersbpclock - background daemon that schedule BP level eventsbptransit - daemon to move inbound traffic to outbound queue for forwardingipnfw - BP IPN scheme-specific bundle routing daemonipnadminep - IPN scheme-specific administrative end-point daemonYou can find more details about these daemons in the manual pages. You may also see daemons related to other activate modules. For example, if the LTP engine is active in the system, you will see the following daemons:
ltpclockltpdelivltpmeterudplsoudplsiltpcliltpcloTo further vary that BP service is running, you can check for presence of ION shared memory and semaphores:
------ Shared Memory Segments --------\nkey shmid owner perms bytes nattch status \n0x0000ee02 47 userIon 666 641024 13 \n0x0000ff00 48 userIon 666 50000000 13 \n0x93de0005 49 userIon 666 1200002544 13 \n0x0000ff01 50 userIon 666 500000000 13 \n\n------ Semaphore Arrays --------\nkey semid owner perms nsems \n0x0000ee01 23 userIon 666 1 \n0x18020001 24 userIon 666 250 \nIn this example, the shared memory and semaphore keys for the SDR heap space (shmid 49) and the semaphorebase (semid 24) are created using a random key generated from the process ID of ionadmin and they will vary each time ION is instantiated. This is specific to SVR4 semaphore, which is the default for ION 4.1.2. However, starting with ION 4.1.3, the default semaphore will switch to POSIX semaphore and the output will be different. The other memory and semaphore keys listed in this example are typical default values, but they too, can be changed through ionconfig files.
If ION is installed but not running (either you see no shared memory or don't see the BP service daemons) you can restart ION. Before restarting ION, run ionstop to clear all remaining orphaned processes/shared memory allocations in case the previous instance of BP service was not properly shutdown or has suffered a crash. Here is an example of the output you may see:
$ ionstop\nIONSTOP will now stop ion and clean up the node for you...\ncfdpadmin .\nStopping cfdpadmin.\nbpv7\nbpadmin .\nStopping bpadmin.\nltpadmin .\nStopping ltpadmin.\nionadmin .\nStopping ionadmin.\nbsspadmin .\nBSSP not initialized yet.\nStopping bsspadmin.\nThis is a single-ION instance configuration. Run killm.\nkillm\nSending TERM to acsadmin lt-acsadmin acslist lt-acslist aoslsi lt-aoslsi aoslso lt-aoslso bibeadmin lt-bibeadmin bibeclo lt-bibeclo bpadmin lt-bpadmin bpcancel lt-bpcancel bpchat lt-bpchat bpclm lt-bpclm bpclock lt-bpclock bpcounter lt-bpcounter bpdriver lt-bpdriver bpecho lt-bpecho bping lt-bping bplist lt-bplist bpnmtest lt-bpnmtest bprecvfile lt-bprecvfile bpsecadmin lt-bpsecadmin bpsendfile lt-bpsendfile bpsink lt-bpsink bpsource lt-bpsource bpstats lt-bpstats bpstats2 lt-bpstats2 bptrace lt-bptrace bptransit lt-bptransit brsccla lt-brsccla brsscla lt-brsscla bsscounter lt-bsscounter bssdriver lt-bssdriver bsspadmin lt-bsspadmin bsspcli lt-bsspcli bsspclo lt-bsspclo bsspclock lt-bsspclock bssrecv lt-bssrecv bssStreamingApp lt-bssStreamingApp cgrfetch lt-cgrfetch cpsd lt-cpsd dccpcli lt-dccpcli dccpclo lt-dccpclo dccplsi lt-dccplsi dccplso lt-dccplso dgr2file lt-dgr2file dgrcli lt-dgrcli dgrclo lt-dgrclo dtka lt-dtka dtkaadmin lt-dtkaadmin dtn2admin lt-dtn2admin dtn2adminep lt-dtn2adminep dtn2fw lt-dtn2fw dtpcadmin lt-dtpcadmin dtpcclock lt-dtpcclock dtpcd lt-dtpcd dtpcreceive lt-dtpcreceive dtpcsend lt-dtpcsend file2dgr lt-file2dgr file2sdr lt-file2sdr file2sm lt-file2sm file2tcp lt-file2tcp file2udp lt-file2udp hmackeys lt-hmackeys imcadmin lt-imcadmin imcadminep lt-imcadminep imcfw lt-imcfw ionadmin lt-ionadmin ionexit lt-ionexit ionrestart lt-ionrestart ionsecadmin lt-ionsecadmin ionunlock lt-ionunlock ionwarn lt-ionwarn ipnadmin lt-ipnadmin ipnadminep lt-ipnadminep ipnd lt-ipnd ipnfw lt-ipnfw lgagent lt-lgagent lgsend lt-lgsend ltpadmin lt-ltpadmin ltpcli lt-ltpcli ltpclo lt-ltpclo ltpclock lt-ltpclock ltpcounter lt-ltpcounter ltpdeliv lt-ltpdeliv ltpdriver lt-ltpdriver ltpmeter lt-ltpmeter ltpsecadmin lt-ltpsecadmin nm_agent lt-nm_agent nm_mgr lt-nm_mgr owltsim lt-owltsim owlttb lt-owlttb psmshell lt-psmshell psmwatch lt-psmwatch ramsgate lt-ramsgate rfxclock lt-rfxclock sdatest lt-sdatest sdr2file lt-sdr2file sdrmend lt-sdrmend sdrwatch lt-sdrwatch sm2file lt-sm2file smlistsh lt-smlistsh smrbtsh lt-smrbtsh stcpcli lt-stcpcli stcpclo lt-stcpclo tcaadmin lt-tcaadmin tcaboot lt-tcaboot tcacompile lt-tcacompile tcapublish lt-tcapublish tcarecv lt-tcarecv tcc lt-tcc tccadmin lt-tccadmin tcp2file lt-tcp2file tcpbsi lt-tcpbsi tcpbso lt-tcpbso tcpcli lt-tcpcli tcpclo lt-tcpclo udp2file lt-udp2file udpbsi lt-udpbsi udpbso lt-udpbso udpcli lt-udpcli udpclo lt-udpclo udplsi lt-udplsi udplso lt-udplso amsbenchr lt-amsbenchr amsbenchs lt-amsbenchs amsd lt-amsd amshello lt-amshello amslog lt-amslog amslogprt lt-amslogprt amsshell lt-amsshell amsstop lt-amsstop bputa lt-bputa cfdpadmin lt-cfdpadmin cfdpclock lt-cfdpclock cfdptest lt-cfdptest bpcp lt-bpcp bpcpd lt-bpcpd ...\nSending KILL to the processes...\nChecking if all processes ended...\nDeleting shared memory to remove SDR...\nKillm completed.\nION node ended. Log file: ion.log\nAt this point run ps -aux or ipcs to verify that ION has terminated completely.
When ION is not running, you can performance a simple unit test to verify ION is build properly.
Navigate to the root directory of the ION source code, cd into the tests folder and then execute a bping test using the command:
./runtest bping\nYou can watch the terminal output ION restarting itself and executing a loopback ping. When successful it will indicate at the end of the test:
TEST PASSED!\n\npassed: 1\n bping\n\nfailed: 0\n\nskipped: 0\n\nexcluded by OS type: 0\n\nexcluded by BP version: 0\n\nobsolete tests: 0\nThe standard ./configure; make; sudo make install; sudo ldconfig process should automatically install the BP libraries under /usr/local/lib and the relevant header files under /usr/local/include unless ION is specifically configured to a different customized install location through the ./configure script during the compilation process. Here is a list of libraries and header files you should find there:
$ cd /usr/local/lib\n$ ls\nlibamp.a libbp.so.0.0.0 libcgr.a libdtpc.la libmbedcrypto.so.7 libtc.so.0.0.0 libudpcla.a\nlibamp.la libbss.a libcgr.la libdtpc.so libmbedtls.a libtcaP.a libudpcla.la\nlibamp.so libbss.la libcgr.so libdtpc.so.0 libmbedtls.so libtcaP.la libudpcla.so\nlibamp.so.0 libbss.so libcgr.so.0 libdtpc.so.0.0.0 libmbedtls.so.14 libtcaP.so libudpcla.so.0\nlibamp.so.0.0.0 libbss.so.0 libcgr.so.0.0.0 libici.a libmbedx509.a libtcaP.so.0 libudpcla.so.0.0.0\nlibampAgentADM.a libbss.so.0.0.0 libdgr.a libici.la libmbedx509.so libtcaP.so.0.0.0 libudplsa.a\nlibampAgentADM.la libbssp.a libdgr.la libici.so libmbedx509.so.1 libtcc.a libudplsa.la\nlibampAgentADM.so libbssp.la libdgr.so libici.so.0 libstcpcla.a libtcc.la libudplsa.so\nlibampAgentADM.so.0 libbssp.so libdgr.so.0 libici.so.0.0.0 libstcpcla.la libtcc.so libudplsa.so.0\nlibampAgentADM.so.0.0.0 libbssp.so.0 libdgr.so.0.0.0 libltp.a libstcpcla.so libtcc.so.0 libudplsa.so.0.0.0\nlibams.a libbssp.so.0.0.0 libdtka.a libltp.la libstcpcla.so.0 libtcc.so.0.0.0 libzfec.a\nlibams.la libcfdp.a libdtka.la libltp.so libstcpcla.so.0.0.0 libtcpbsa.a libzfec.la\nlibbp.a libcfdp.la libdtka.so libltp.so.0 libtc.a libtcpbsa.la libzfec.so\nlibbp.la libcfdp.so libdtka.so.0 libltp.so.0.0.0 libtc.la libtcpbsa.so libzfec.so.0\nlibbp.so libcfdp.so.0 libdtka.so.0.0.0 libmbedcrypto.a libtc.so libtcpbsa.so.0 libzfec.so.0.0.0\nlibbp.so.0 libcfdp.so.0.0.0 libdtpc.a libmbedcrypto.so libtc.so.0 libtcpbsa.so.0.0.0\n\n\n$ cd /usr/local/include\n$ ls\nams.h bpsec_instr.h cfdpops.h eureka.h llcv.h platform.h rfc9173_utils.h sdrhash.h sdrxn.h tcaP.h\nbcb_aes_gcm_sc.h bpsec_util.h crypto.h icinm.h ltp.h platform_sm.h rfx.h sdrlist.h smlist.h tcc.h\nbib_hmac_sha2_sc.h bss.h dgr.h ion.h lyst.h psa sci.h sdrmgt.h smrbt.h tccP.h\nbp.h bssp.h dtka.h ion_test_sc.h mbedtls psm.h sda.h sdrstring.h sptrace.h zco.h\nbpsec_asb.h cfdp.h dtpc.h ionsec.h memmgr.h radix.h sdr.h sdrtable.h tc.h\nIn this document, we assume that ION was build and installed via the ./configure installation process using the full open-source codebase and with the standard set of options.
The location and content of the library and header directories shown above included non-BP modules and may not match exactly with what you have especially if you have built ION with features options enabled via ./configure or used a manual/custom Makefile, or built ION from the ion-core package instead.
Once you are confidant that ION has been properly built and installed in the system, you can start BP service by launching ION. To do this, please consult the various tutorials under Configuration.
After launching ION, you can verify BP service status in the same manner as described in previous section.
"},{"location":"BP-Service-API/#bp-service-api-reference","title":"BP Service API Reference","text":""},{"location":"BP-Service-API/#header","title":"Header","text":"#include \"bp.h\"\nFunction Prototype
int bp_attach( )\nParameters
Return Value
Example Call
if (bp_attach() < 0)\n{\n printf(\"Can't attach to BP.\\n\");\n /* user inser error handling code */\n}\nDescription
Typically the bp_attach() call is made at the beginning of a user's application to attach to BP Service provided by ION in the host machine. This code checks for a negative return value.
bp_attach() automatically calls the ICI API ion_attach() when necessary, so there is no need to call them separately. In addition to gaining access to ION's SDR, which is what ion_attach() provides, bp_attach() also gains access to the Bundle Protocol's state information and database. For user application that interacts with the Bundle Protocol, bp_attach() is the entry point to ION.
Function Prototype
Sdr bp_get_sdr()\nParameters
Return Value
NULL: any errorExample Call
/* declare SDR handle */\nSdr sdr;\n\n/* get SDR handle */\nsdr = bp_get_sdr();\n\n/* user check sdr for NULL \n * and handle error */\nDescription
Returns handle for the SDR data store used for BP, to enable creation and interrogation of bundle payloads (application data units). Since the SDR handle is needed by many APIs, this function is typically executed early in the user's application in order to access other BP services.
"},{"location":"BP-Service-API/#bp_detach","title":"bp_detach","text":"Function Prototype
void bp_detach( )\nParameters
Return Value
Description
Terminates all access to BP functionality for the invoking process.
"},{"location":"BP-Service-API/#bp_open","title":"bp_open","text":"Function Prototype
int bp_open(char *eid, BpSAP *ionsapPtr)\nParameters
*eid: name of the endpoint*ionsapPtr: pointer to variable in which address of BP service access point will be returnedReturn Value
Example Call
if (bp_open(ownEid, &sap) < 0)\n{\n putErrmsg(\"bptrace can't open own endpoint.\", ownEid);\n\n /* user's error handling function here */\n}\nDescription
Opens the application's access to the BP endpoint identified by the string at eid, so that the application can take delivery of bundles destined for the indicated endpoint. This SAP can also be used for sending bundles whose source is the indicated endpoint.
Please note that all bundles sent via this SAP will be subject to immediate destruction upon transmission, i.e., no bundle addresses will be returned by bp_send for use in tracking, suspending/resuming, or cancelling transmission of these bundles.
On success, places a value in *ionsapPtr that can be supplied to future bp function invocations.
NOTE: To allow for bp_send to return a bundle address for tracking purpose, please use bp_open_source instead.
Function Prototype
int bp_open_source(char *eid, BpSAP *ionsapPtr, int detain)\nParameters
*eid: name of the endpoint*ionsapPtr: pointer to variable in which address of BP service access point will be returneddetain: indicator as to whether or not bundles sourced using this BpSAP should be detained in storage until explicitly releasedReturn Value
Example Call
if (bp_open_source(ownEid, &txSap, 1) < 0)\n{\n putErrmsg(\"can't open own 'send' endpoint.\", ownEid);\n\n /* user error handling routine here */\n}\nDescription
Opens the application's access to the BP endpoint identified by eid, so that the application can send bundles whose source is the indicated endpoint. If and only if the value of detain is non-zero, citing this SAP in an invocation of bp_send() will cause the address of the newly issued bundle to be returned for use in tracking, suspending/resuming, or cancelling transmission of this bundle.
USE THIS FEATURE WITH GREAT CARE: such a bundle will continue to occupy storage resources until it is explicitly released by an invocation of bp_release() or until its time to live expires, so bundle detention increases the risk of resource exhaustion. (If the value of detain is zero, all bundles sent via this SAP will be subject to immediate destruction upon transmission.)
On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
"},{"location":"BP-Service-API/#bp_send","title":"bp_send","text":"Function Prototype
int bp_send(BpSAP sap, char *destEid, char *reportToEid, \n int lifespan, int classOfService, BpCustodySwitch custodySwitch, \n unsigned char srrFlags, int ackRequested, \n BpAncillaryData *ancillaryData, Object adu, Object *newBundle)\nParameters
sap: the source endpoint for the bundle, provided by the bp_open call.*destEid: identifies the destination endpoint for the bundle.reportToEid: identifies the endpoint to which any status reports pertaining to this bundle will be sent; if NULL, defaults to the source endpoint.lifespan: is the maximum number of seconds that the bundle can remain in-transit (undelivered) in the network prior to automatic deletion.classOfService: is simply priority for now: BP_BULK_PRIORITY, BP_STD_PRIORITY, or BP_EXPEDITED_PRIORITY. If class-of-service flags are defined in a future version of Bundle Protocol, those flags would be OR'd with priority.custodySwitch: indicates whether or not custody transfer is requested for this bundle and, if so, whether or not the source node itself is required to be the initial custodian. The valid values are SourceCustodyRequired, SourceCustodyOptional, NoCustodyRequired. Note that custody transfer is possible only for bundles that are uniquely identified, so it cannot be requested for bundles for which BP_MINIMUM_LATENCY is requested, since BP_MINIMUM_LATENCY may result in the production of multiple identical copies of the same bundle. Similarly, custody transfer should never be requested for a \"loopback\" bundle, i.e., one whose destination node is the same as the source node: the received bundle will be identical to the source bundle, both residing in the same node, so no custody acceptance signal can be applied to the source bundle and the source bundle will remain in storage until its TTL expires.srrFlags: if non-zero, is the logical OR of the status reporting behaviors requested for this bundle: BP_RECEIVED_RPT, BP_CUSTODY_RPT, BP_FORWARDED_RPT, BP_DELIVERED_RPT, BP_DELETED_RPT.ackRequested: is a Boolean parameter indicating whether or not the recipient application should be notified that the source application requests some sort of application-specific end-to-end acknowledgment upon receipt of the bundle.ancillaryData: if not NULL, is used to populate the Extended Class Of Service block for this bundle. The block's ordinal value is used to provide fine-grained ordering within \"expedited\" traffic: ordinal values from 0 (the default) to 254 (used to designate the most urgent traffic) are valid, with 255 reserved for custody signals. The value of the block's flags is the logical OR of the applicable extended class-of-service flags:BP_MINIMUM_LATENCY designates the bundle as \"critical\" for the\npurposes of Contact Graph Routing.\n\nBP_BEST_EFFORT signifies that non-reliable convergence-layer protocols, as\navailable, may be used to transmit the bundle. Notably, the bundle may be\nsent as \"green\" data rather than \"red\" data when issued via LTP.\n\nBP_DATA_LABEL_PRESENT signifies whether or not the value of _dataLabel_\nin _ancillaryData_ must be encoded into the ECOS block when the bundle is\ntransmitted.\nNOTE: For Bundle Protocol v7, no Extended Class of Service, or equivalent, has been standardized yet. This capability, however, has been retained from BPv6 and is available to BPv7 implementation in ION.
adu: is the \"application data unit\" that will be conveyed as the payload of the new bundle. adu must be a \"zero-copy object\" (ZCO). To ensure orderly access to transmission buffer space for all applications, adu must be created by invoking ionCreateZco(), which may be configured either to block so long as insufficient ZCO storage space is available for creation of the requested ZCO or to fail immediately if insufficient ZCO storage space is available.Return Value
Example Call
if (bp_send(sap, destEid, reportToEid, ttl, priority,\n custodySwitch, srrFlags, 0, &ancillaryData,\n traceZco, &newBundle) <= 0)\n{\n putErrmsg(\"bptrace can't send file in bundle.\",\n fileName);\n\n /* user error handling code goes here */\n}\nDescription
Sends a bundle to the endpoint identified by destEid, from the source endpoint as provided to the bp_open() call that returned sap.
When sap is NULL, the transmitted bundle is anonymous, i.e., the source of the bundle is not identified. This is legal, but anonymous bundles cannot be uniquely identified; custody transfer and status reporting therefore cannot be requested for an anonymous bundle.
The function returns 1 on success, 0 on user error, -1 on any system error.
If 0 is returned, then an invalid argument value was passed to bp_send(); a message to this effect will have been written to the log file.
If 1 is returned, then either the destination of the bundle was \"dtn:none\" (the bit bucket) or the ADU has been accepted and queued for transmission in a bundle. In the latter case, if and only if sap was a reference to a BpSAP returned by an invocation of bp_open_source() that had a non-zero value in the detain parameter, then newBundle must be non-NULL and the address of the newly created bundle within the ION database is placed in newBundle. This address can be used to track, suspend/resume, or cancel transmission of the bundle.
"},{"location":"BP-Service-API/#bp_track","title":"bp_track","text":"Function Prototype
int bp_track(Object bundle, Object trackingElt)\nParameters
bundle: the bundle object data structuretrackingElt: an sdrlist element managed by the user's applicationReturn Value
Example Call
/* a lyst of bundles in SDR */\nObject bundleList;\n\n/* a bundle object in SDR */\nObject bundleObject;\n\nbundleElt = sdr_list_insert_last(sdr, bundleList,\n bundleObject);\nif (bp_track(outAdu.bundleObj, bundleElt) < 0)\n{\n sdr_cancel_xn(sdr);\n putErrmsg(\"Can't track bundle.\", NULL);\n\n /* user error handling code goes here */\n}\nThe bundleList is managed via the sdr_list library of APIs.
Description
Adds trackingElt to the list of \"tracking\" references in bundle. trackingElt must be the address of an SDR list element -- whose data is the address of this same bundle -- within some list of bundles that is privately managed by the application. Upon destruction of the bundle this list element will automatically be deleted, thus removing the bundle from the application's privately managed list of bundles. This enables the application to keep track of bundles that it is operating on without risk of inadvertently de-referencing the address of a nonexistent bundle.
Function Prototype
void bp_untrack(Object bundle, Object trackingElt)\nParameters
bundle: the bundle object data structuretrackingElt: an sdrlist element managed by the user's applicationReturn Value
Description
Removes trackingElt from the list of \"tracking\" references in bundle, if it is in that list. Does not delete trackingElt itself.
Function Prototype
int bp_suspend(Object bundle)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Suspends transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or if the bundle is already suspended. Otherwise, reverses the enqueuing of the bundle to its selected transmission outduct and places it in the \"limbo\" queue until the suspension is lifted by calling bp_resume. Returns 0 on success, -1 on any error.
"},{"location":"BP-Service-API/#bp_resume","title":"bp_resume","text":"Function Prototype
int bp_resume(Object bundle)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Terminates suspension of transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or is not suspended. Otherwise, removes the bundle from the \"limbo\" queue and queues it for route re-computation and re-queuing. Returns 0 on success, -1 on any error.
"},{"location":"BP-Service-API/#bp_cancel","title":"bp_cancel","text":"Function Prototype
int bp_cancel(Object bundle)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Cancels transmission of bundle. If the indicated bundle is currently queued for forwarding, transmission, or retransmission, it is removed from the relevant queue and destroyed exactly as if its Time To Live had expired. Returns 0 on success, -1 on any error.
"},{"location":"BP-Service-API/#bp_release","title":"bp_release","text":"Function Prototype
int bp_release(Object bundle)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Releases a detained bundle for destruction when all retention constraints have been removed. After a detained bundle has been released, the application can no longer track, suspend/resume, or cancel its transmission. Returns 0 on success, -1 on any error.
NOTE: for bundles sent through an bundle protocol end-point which is opened via bp_open_source with detain set to non-zero value, they will not be destroyed, even after successful transmissions, until time-to-live has expired or explicitly released via bp_release.
Function Prototype
int bp_receive(BpSAP sap, BpDelivery *dlvBuffer, int timeoutSeconds)\nParameters
sap: the source endpoint for the bundle, provided by the bp_open call*dlvBuffer: a pointer to a BpDelivery structure used to return the received bundle and/or outcome of receptiontimoutSeconds: a reception timer in secondsReturn Value
Example Call
if (bp_receive(state.sap, &dlv, BP_BLOCKING) < 0)\n{\n putErrmsg(\"bpsink bundle reception failed.\", NULL);\n\n /* user code to handle error or timeout*/\n}\nIn this example, BP_BLOCKING is set to -1, that means that the call will block forever until a bundle is received, unless interrupted bp_interrupt.
Description
Receives a bundle, or reports on some failure of bundle reception activity.
The \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one bundle destined for the endpoint for which this SAP is opened has not yet been delivered to the SAP, then the payload of the oldest such bundle will be returned in dlvBuffer->adu and dlvBuffer->result will be set to BpPayloadPresent. If there is no such bundle, bp_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is BP_POLL (i.e., zero) and no bundle is awaiting delivery, or if timeoutSeconds is greater than zero but no bundle arrives before timeoutSeconds have elapsed, then dlvBuffer->result will be set to BpReceptionTimedOut. If timeoutSeconds is BP_BLOCKING (i.e., -1) then bp_receive() blocks until either a bundle arrives or the function is interrupted by an invocation of bp_interrupt().
dlvBuffer->result will be set to BpReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer->result will be set to BpEndpointStopped in the event that the operation of the indicated endpoint has been terminated.
The application data unit delivered in the data delivery structure, if any, will be a \"zero-copy object\" reference. Use zco reception functions (see zco(3)) to read the content of the application data unit.
Be sure to call bp_release_delivery() after every successful invocation of bp_receive().
The function returns 0 on success, -1 on any error.
"},{"location":"BP-Service-API/#bp_interrupt","title":"bp_interrupt","text":"Function Prototype
void bp_interrupt(BpSAP sap)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Interrupts a bp_receive() invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, sap may need to be obtained from a static variable.
Function Prototype
void bp_release_delivery(BpDelivery *dlvBuffer, int releaseAdu)\nParameters
*dlvBuffer: a pointer to a BpDelivery structure used to return the received bundle and/or outcome of receptionreleaseAdu: a Boolean parameter: if non-zero, the ADU ZCO reference in dlvBuffer (if any) is destroyed.Return Value
Description
Releases resources allocated to the indicated delivery by dlvBuffer, which is returned by bp_receive. releaseAdu is a Boolean parameter: if non-zero, the ADU ZCO reference in dlvBuffer (if any) is destroyed, causing the ZCO itself to be destroyed if no other references to it remain.
Function Prototype
void bp_close(BpSAP sap)\nParameters
sap: the source endpoint for the bundle, provided by the bp_open or bp_open_source callReturn Value
Description
Terminates the application's access to the BP endpoint identified by the eid cited by the indicated service access point. The application relinquishes its ability to take delivery of bundles destined for the indicated endpoint and to send bundles whose source is the indicated endpoint.
"},{"location":"BP-Service-API/#walk-through-of-bpsourcec","title":"Walk Through ofbpsource.c","text":"TO BE UPDATED.
"},{"location":"BP-Service-API/#compiling-and-linking","title":"Compiling and Linking","text":""},{"location":"BP-Service-API/#zero-copy-object-zco-types","title":"Zero-copy Object (ZCO) Types","text":"We have shown that the way to hand user data from an application to BP is via a zero-copy object (ZCO).
In general there are two types of ZCO that is relevant to a user.
bpsource.cbpdriver.cThe following tools are available to you after ION is built:
Daemon and Configuration
Simple Sending and Receiving
Testing and Benchmarking
It is important to note that, by default, the administrative programs will all trigger the creation of a log file called\u00a0ion.log\u00a0in the directory where the program is called. This means that write-access in your current working directory is required. The log file itself will contain the expected log information from administrative daemons, but it will also contain error reports from simple applications such as\u00a0bpsink. This is important to note since the BP applications may not be reporting all error information to stdout or stderr.
"},{"location":"Basic-Configuration-File-Tutorial/#starting-the-ion-daemon","title":"Starting the ION Daemon","text":"A script has been created which allows a more streamlined configuration and startup of an ION node. This script is called\u00a0ionstart, and it has the following syntax. Don't run it yet; we still have to configure it!
ionstart -I <filename>
filename: This is the name for configuration file which the script will attempt to use for the various configuration commands. The script will perform a sanity check on the file, splitting it into command sections appropriate for each of the administration programs.
Configuration information (such as routes, connections, etc) can be specified one of two ways for any of the individual administration programs:
(Recommended) Creating a configuration file and passing it to\u00a0ionadmin,\u00a0bpadmin,\u00a0ipnadmin...\u00a0either directly or via the\u00a0ionstart\u00a0helper script. Manually typing configuration commands into the terminal for each administration program.
You can find appropriate commands in the following sections.
"},{"location":"Basic-Configuration-File-Tutorial/#configuration-files-overview","title":"Configuration Files Overview","text":"There are five configuration files about which you should be aware.
The first,\u00a0ionadmin's configuration file, assigns an identity (node number) to the node, optionally configures the resources that will be made available to the node, and specifies contact bandwidths and one-way transmission times. Specifying the \"contact plan\" is important in deep-space scenarios where the bandwidth must be managed and where acknowledgments must be timed according to propagation delays. It is also vital to the function of contact-graph routing.
The second,\u00a0ltpadmin's configuration file, specifies spans, transmission speeds, and resources for the Licklider Transfer Protocol convergence layer.
The third,\u00a0ipnadmin's configuration file, maps endpoints at \"neighboring\" (topologically adjacent, directly reachable) nodes to convergence-layer addresses. Our examples use TCP/IP and LTP (over IP/UDP), so it maps endpoint IDs to IP addresses. This file populates the ION analogue to an ARP cache for the \"ipn\" naming scheme.
The fourth,\u00a0bpadmin's configuration file, specifies all of the open endpoints for delivery on your local end and specifies which convergence layer protocol(s) you intend to use. With the exception of LTP, most convergence layer adapters are fully configured in this file.
The fifth,\u00a0dtn2admin's configuration file, populates the ION analogue to an ARP cache for the \"dtn\" naming scheme.
"},{"location":"Basic-Configuration-File-Tutorial/#the-ion-configuration-file","title":"The ION Configuration File","text":"Given to\u00a0ionadmin\u00a0either as a file or from the daemon command line, this file configures contacts for the ION node. We will assume that the local node's identification number is 1.
This file specifies contact times and one-way light times between nodes. This is useful in deep-space scenarios: for instance, Mars may be 20 light-minutes away, or 8. Though only some transport protocols make use of this time (currently, only LTP), it must be specified for all links nonetheless. Times may be relative (prefixed with a + from current time) or absolute. Absolute times, are in the format\u00a0yyyy/mm/dd-hh:mm:ss. By default, the contact-graph routing engine will make bundle routing decisions based on the contact information provided.
The configuration file lines are as follows:
1 1 ''
This command will initialize the ion node to be node number 1.
1\u00a0refers to this being the initialization or ''first'' command. 1\u00a0specifies the node number of this ion node. (IPN node 1). ''\u00a0specifies the name of a file of configuration commands for the node's use of shared memory and other resources (suitable defaults are applied if you leave this argument as an empty string).
s
This will start the ION node. It mostly functions to officially \"start\" the node in a specific instant; it causes all of ION's protocol-independent background daemons to start running.
a contact +1 +3600 1 1 100000
specifies a transmission opportunity for a given time duration between two connected nodes (or, in this case, a loopback transmission opportunity).
a\u00a0adds this entry in the configuration table. contact\u00a0specifies that this entry defines a transmission opportunity. +1\u00a0is the start time for the contact (relative to when the\u00a0s\u00a0command is issued). +3600\u00a0is the end time for the contact (relative to when the\u00a0s\u00a0command is issued). 1\u00a0is the source node number. 1\u00a0is the destination node number. 100000\u00a0is the maximum rate at which data is expected to be transmitted from the source node to the destination node during this time period (here, it is 100000 bytes / second).
a range +1 +3600 1 1 1
specifies a distance between nodes, expressed as a number of light seconds, where each element has the following meaning:
a\u00a0adds this entry in the configuration table. range\u00a0declares that what follows is a distance between two nodes. +1\u00a0is the earliest time at which this is expected to be the distance between these two nodes (relative to the time\u00a0s\u00a0was issued). +3600\u00a0is the latest time at which this is still expected to be the distance between these two nodes (relative to the time\u00a0s\u00a0was issued). 1\u00a0is one of the two nodes in question. 1\u00a0is the other node. 1\u00a0is the distance between the nodes, measured in light seconds, also sometimes called the \"one-way light time\" (here, one light second is the expected distance).
m production 1000000
specifies the maximum rate at which data will be produced by the node.
m\u00a0specifies that this is a management command. production\u00a0declares that this command declares the maximum rate of data production at this ION node. 1000000\u00a0specifies that at most 1000000 bytes/second will be produced by this node.
m consumption 1000000
specifies the maximum rate at which data can be consumed by the node.
m\u00a0specifies that this is a management command. consumption\u00a0declares that this command declares the maximum rate of data consumption at this ION node. 1000000\u00a0specifies that at most 1000000 bytes/second will be consumed by this node.
This will make a final configuration file\u00a0host1.ionrc\u00a0which looks like this:
1 1 ''\ns\na contact +1 +3600 1 1 100000\na range +1 +3600 1 1 1\nm production 1000000\nm consumption 1000000\nGiven to\u00a0ltpadmin\u00a0as a file or from the command line, this file configures the LTP engine itself. We will assume the local IPN node number is 1; in ION, node numbers are used as the LTP engine numbers.
1 32
This command will initialize the LTP engine:
1\u00a0refers to this being the initialization or ''first'' command. 32\u00a0is an estimate of the maximum total number of LTP ''block'' transmission sessions - for all spans - that will be concurrently active in this LTP engine. It is used to size a hash table for session lookups.
a span 1 32 32 1400 10000 1 'udplso localhost:1113'
This command defines an LTP engine 'span':
a\u00a0indicates that this will add something to the engine.
span\u00a0indicates that an LTP span will be added.
1\u00a0is the engine number for the span, the number of the remote engine to which LTP segments will be transmitted via this span. In this case, because the span is being configured for loopback, it is the number of the local engine, i.e., the local node number. This will have to match an outduct in Section\u00a02.6.
32\u00a0specifies the maximum number of LTP ''block'' transmission sessions that may be active on this span. The product of the mean block size and the maximum number of transmission sessions is effectively the LTP flow control ''window'' for this span: if it's less than the bandwidth delay product for traffic between the local LTP engine and this spa's remote LTP engine then you'll be under-utilizing that link. We often try to size each block to be about one second's worth of transmission, so to select a good value for this parameter you can simply divide the span's bandwidth delay product (data rate times distance in light seconds) by your best guess at the mean block size.
The second\u00a032specifies the maximum number of LTP ''block'' reception sessions that may be active on this span. When data rates in both directions are the same, this is usually the same value as the maximum number of transmission sessions.
1400\u00a0is the number of bytes in a single segment. In this case, LTP runs atop UDP/IP on ethernet, so we account for some packet overhead and use 1400.
1000\u00a0is the LTP aggregation size limit, in bytes. LTP will aggregate multiple bundles into blocks for transmission. This value indicates that the block currently being aggregated will be transmitted as soon as its aggregate size exceeds 10000 bytes.
1\u00a0is the LTP aggregation time limit, in seconds. This value indicates that the block currently being aggregated will be transmitted 1 second after aggregation began, even if its aggregate size is still less than the aggregation size limit.
'udplso localhost:1113'\u00a0is the command used to implement the link itself. The link is implemented via UDP, sending segments to the localhost Internet interface on port 1113 (the IANA default port for LTP over UDP).
s 'udplsi localhost:1113'
Starts the ltp engine itself:
s\u00a0starts the ltp engine.
'udplsi localhost:1113'\u00a0is the link service input task. In this case, the input ''duct' is a UDP listener on the local host using port 1113.
This means that the entire configuration file\u00a0host1.ltprc\u00a0looks like this:
1 32\na span 1 32 32 1400 10000 1 'udplso localhost:1113'\ns 'udplsi localhost:1113'\nGiven to\u00a0bpadmin\u00a0either as a file or from the daemon command line, this file configures the endpoints through which this node's Bundle Protocol Agent (BPA) will communicate. We will assume the local BPA's node number is 1; as for LTP, in ION node numbers are used to identify bundle protocol agents.
1
This initializes the bundle protocol:
1\u00a0refers to this being the initialization or ''first'' command.
a scheme ipn 'ipnfw' 'ipnadminep'
This adds support for a new Endpoint Identifier (EID) scheme:
a\u00a0means that this command will add something.
scheme\u00a0means that this command will add a scheme.
ipn\u00a0is the name of the scheme to be added.
'ipnfw'\u00a0is the name of the IPN scheme's forwarding engine daemon.
'ipnadminep'\u00a0is the name of the IPN scheme's custody transfer management daemon.
a endpoint ipn:1.0 q
This command establishes this BP node's membership in a BP endpoint:
a\u00a0means that this command will add something.
endpoint\u00a0means that this command adds an endpoint.
ipn\u00a0is the scheme name of the endpoint.
1.0\u00a0is the scheme-specific part of the endpoint. For the IPN scheme the scheme-specific part always has the form\u00a0nodenumber:servicenumber. Each node must be a member of the endpoint whose node number is the node's own node number and whose service number is 0, indicating administrative traffic.
q\u00a0means that the behavior of the engine, upon receipt of a new bundle for this endpoint, is to queue it until an application accepts the bundle. The alternative is to silently discard the bundle if no application is actively listening; this is specified by replacing\u00a0q\u00a0with\u00a0x.
a endpoint ipn:1.1 q
a endpoint ipn:1.2 q
These specify two more endpoints that will be used for test traffic.
a protocol ltp 1400 100
This command adds support for a convergence-layer protocol:
a\u00a0means that this command will add something.
protocol\u00a0means that this command will add a convergence-layer protocol.
ltp\u00a0is the name of the convergence-layer protocol.
1400\u00a0is the estimated size of each convergence-layer protocol data unit (in bytes); in this case, the value is based on the size of a UDP/IP packet on Ethernet.
100\u00a0is the estimated size of the protocol transmission overhead (in bytes) per convergence-layer procotol data unit sent.
a induct ltp 1 ltpcli
This command adds an induct, through which incoming bundles can be received from other nodes:
a\u00a0means that this command will add something.
induct\u00a0means that this command will add an induct.
ltp\u00a0is the convergence layer protocol of the induct.
1\u00a0is the identifier of the induct, in this case the ID of the local LTP engine.
ltpcli\u00a0is the name of the daemon used to implement the induct.
a outduct ltp 1 ltpclo
This command adds an outduct, through which outgoing bundles can be sent to other nodes:
a\u00a0means that this command will add something.
outduct\u00a0means that this command will add an outduct.
ltp\u00a0is the convergence layer protocol of the outduct.
1\u00a0is the identifier of the outduct, the ID of the convergence-layer protocol induct of some remote node. See Section\u00a02.5\u00a0for remote LTP engine IDs.
ltpclo\u00a0is the name of the daemon used to implement the outduct.
s
This command starts the bundle engine including all daemons for the inducts and outducts.
That means that the entire configuration file\u00a0host1.bprc\u00a0looks like this:
1\na scheme ipn 'ipnfw' 'ipnadminep'\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\na protocol ltp 1400 100\na induct ltp 1 ltpcli\na outduct ltp 1 ltpclo\ns\nAs noted earlier, this file is used to build ION's analogue to an ARP cache, a table of ''egress plans.'' It specifies which outducts to use in order to forward bundles to the local node's neighbors in the network. Since we only have one outduct, for forwarding bundles to one place (the local node), we only have one egress plan.
a plan 1 ltp/1
This command defines an egress plan for bundles to be transmitted to the local node:
a\u00a0means this command adds something.
plan\u00a0means this command adds an egress plan.
1\u00a0is the node number of the remote node. In this case, that is the local node's own node number; we're configuring for loopback.
ltp/1\u00a0is the identifier of the outduct through which to transmit bundles in order to convey them to this ''remote'' node.
This means that the entire configuration file\u00a0host1.ipnrc\u00a0looks like this:
a plan 1 ltp/1
Assuming no errors occur with the configuration above, we are now ready to test loopback communications. In one terminal, we have to run the start script (the one we said that you would have to have earlier). It's right here, in case you forgot to write it down:
ionstart -i host1.ionrc -l host1.ltprc -b host1.bprc -p host1.ipnrc
This command will run the appropriate administration programs, in order, with the appropriate configuration files. Don't worry that the command is lengthy and unwieldly; we will show you how to make a more clean single configuration file later.
Once the daemon is started, run:
bpsink ipn:1.1
This will begin listening on the Endpoint ID with the\u00a0endpoint_number\u00a01 on\u00a0service_number\u00a01, which is used for testing.
Now open another terminal and run the command:
bpsource ipn:1.1
This will begin sending messages you type to the Endpoint ID\u00a0ipn:1.1, which is currently being listened to by\u00a0bpsink. Type messages into\u00a0bpsource, press enter, and see if they are reported by\u00a0bpsink.
If so, you're ready for bigger and better things. If not, check the following:
Do you have write permissions for your current directory? If not, you will not be able to start the daemon as it has to write out to the ion.log file. Are your config files exactly as specified, except for IP address changes? Are you running it on one of our supported platforms? Currently, those are the only supported distributions.
If you are still having problems, you can ask for help on the ION users' list or file an ION bug report.
"},{"location":"Basic-Configuration-File-Tutorial/#stopping-the-daemon","title":"Stopping the Daemon","text":"As the daemon launches many ducts and helper applications, it can be complicated to turn it all off. To help this, we provided a script. The script similar to\u00a0ionstart\u00a0exists called\u00a0ionstop, which tears down the ion node in one step. You can call it like so:
ionstop
After stopping the daemon, it can be restarted using the same procedures as outlined above. Do remember that the ion.log file is still present, and will just keep growing as you experiment with ION.
IMPORTANT:\u00a0The user account that runs ionstart\u00a0must also run ionstop. If that account does not, no other accounts can successfully start the daemon, as the shared memory vital to ION's functionality will already be occupied.
"},{"location":"Basic-Configuration-File-Tutorial/#more-advanced-usage","title":"More Advanced Usage","text":"Detailed documentation of ION and its applications are available via the man pages. It is suggested that you start with\u00a0man ion\u00a0, as this is an overview man page listing all available ION packages.
"},{"location":"Basic-Configuration-File-Tutorial/#ionscript-for-simplified-configuration-files","title":"Ionscript for Simplified Configuration Files","text":"The most difficult and cumbersome method of starting an ION node is to manually run the various administration programs in order, manually typing configuration commands all the way. It is much more efficient and less error-prone to place the configuration commands into a configuration file and using that as input to the administration program, but this is still cumbersome as you must type in each administration program in order. The\u00a0ionstart\u00a0program will automatically execute the appropriate administration programs with their respective configuration files in order. Unfortunately, as seen in the previous sections,\u00a0the command is lengthy. This is why the\u00a0ionscript\u00a0script was added to make things even easier.
The ionscript\u00a0will basically concatenate the configuration files into one large file. The format of this large configuration file is simply to bookend configuration sections with the lines:\u00a0## begin PROGRAM\u00a0and\u00a0## end PROGRAM, where\u00a0PROGRAM\u00a0is the name of the administration program for which the configuration commands should be sent (such as\u00a0ionadmin, bpadmin, ipnadmin).
To create a single file\u00a0host1.rc\u00a0out of the various configuration files defined in the previous section, run this command:
ionscript -i host1.ionrc -p host1.ipnrc -l host1.ltprc -b host1.bprc -O host1.rc
The command can also be used to split the large\u00a0host1.rc\u00a0into the individual configuration files (so long as the large file is formatted correctly). Just run this command to revert the process:
ionscript -i host1.ionrc -p host1.ipnrc -l host1.ltprc -b host1.bprc -I host1.rc
This isn't very practical in this specific case (as you already have the individual files) but if you start with a single configuration file, this can be helpful.
Once you have a single configuration file, starting the ION node is a single command:
ionstart -I host1.rc
Note that\u00a0ionstart\u00a0and\u00a0ionscript\u00a0require\u00a0sed\u00a0and\u00a0awk, but those are almost universally available on Unix-based systems. The two scripts will always sanity-check the large configuration file to ensure that it interprets the bookend lines correctly- and it will warn you of any errors you have made in the file. Consult the USAGE for each script for further help, by attempting to run the script with no arguments or the\u00a0-h\u00a0argument.
"},{"location":"Basic-Configuration-File-Tutorial/#examples-of-network-configurations","title":"Examples of Network Configurations","text":"For a simple single-node ION configuration - running multiple instances of ION in the same host, see the tutorial here.
For a two-node configuration, see the tutorial here.
For a multi-hop and also multi-network configuration, see this page.
"},{"location":"CLA-API/","title":"Convergence Layer Adaptor - APIs","text":"ION currently provides several CLAs, include LTP, TCP, UDP, STCP. However, it is possible to develop a customized CLA using ION's API. This document will describe the basic set of API used to develop a customized CLA.
"},{"location":"CLA-API/#cla-apis","title":"CLA APIs","text":""},{"location":"CLA-API/#header","title":"Header","text":"#include \"bpP.h\"\nFunction Prototype
extern int bpDequeue(VOutduct *vduct,\n Object *outboundZco,\n BpAncillaryData *ancillaryData,\n int stewardship);\nThis function is invoked by a convergence-layer output adapter (outduct) daemon to get a bundle that it is to transmit to some remote convergence-layer input adapter (induct) daemon.
The function first pops the next (only) outbound bundle from the queue of outbound bundles for the indicated duct. If no such bundle is currently waiting for transmission, it blocks until one is [or until the duct is closed, at which time the function returns zero without providing the address of an outbound bundle ZCO].
On obtaining a bundle, bpDequeue does DEQUEUE processing on the bundle's extension blocks; if this processing determines that the bundle is corrupt, the function returns zero while providing 1 (a nonsense address) in *bundleZco as the address of the outbound bundle ZCO. The CLO should handle this result by simply calling bpDequeue again.
bpDequeue then catenates (serializes) the BP header information (primary block and all extension blocks) in the bundle and prepends that serialized header to the source data of the bundle's payload ZCO. Then it returns the address of that ZCO in *bundleZco for transmission at the convergence layer (possibly entailing segmentation that would be invisible to BP).
Requested quality of service for the bundle is provided in *ancillaryData so that the requested QOS can be mapped to the QOS features of the convergence-layer protocol. For example, this is where a request for custody transfer is communicated to BIBE when the outduct daemon is one that does BIBE transmission. The stewardship argument controls the disposition of the bundle following transmission. Any value other than zero indicates that the outduct daemon is one that performs \"stewardship\" procedures. An outduct daemon that performs stewardship procedures will disposition the bundle as soon as the results of transmission at the convergence layer are known, by calling one of two functions: either bpHandleXmitSuccess or else bpHandleXmitFailure. A value of zero indicates that the outduct daemon does not perform stewardship procedures and will not disposition the bundle following transmission; instead, the bpDequeue function itself will assume that transmission at the convergence layer will be successful and will disposition the bundle on that basis.
Return Values
Function Prototype
extern int bpHandleXmitSuccess(Object zco);\nThis function is invoked by a convergence-layer output adapter (an outduct) on detection of convergence- layer protocol transmission success. It causes the serialized (catenated) outbound bundle in zco to be destroyed, unless some constraint (such as local delivery of a copy of the bundle) requires that bundle destruction be deferred.
Return Values
Function Prototype
extern int bpHandleXmitFailure(Object zco);\nThis function is invoked by a convergence-layer output adapter (an outduct) on detection of a convergence- layer protocol transmission error. It causes the serialized (catenated) outbound bundle in zco to be queued up for re-forwarding.
Return Values
extern AcqWorkArea *bpGetAcqArea(VInduct *vduct);\nAllocates a bundle acquisition work area for use in acquiring inbound bundles via the indicated duct. This is typically invoked just once at the beginning of a CLA process initialization
Return Value
NULL: on any failureextern void bpReleaseAcqArea(AcqWorkArea *workArea);\nReleases dynamically allocated bundle acquisition work area. This should be called before shutting down a CLA process.
Return Value
NULL: on any failureextern int bpBeginAcq( AcqWorkArea *workArea,\n int authentic,\n char *senderEid);\nThis function is invoked by a convergence-layer input adapter to initiate acquisition of a new bundle via the indicated workArea. It initializes deserialization of an array of bytes constituting a single transmitted bundle. The \"authentic\" Boolean and \"senderEid\" string are knowledge asserted by the convergence-layer input adapter invoking this function: an assertion of authenticity of the data being acquired (e.g., per knowledge that the data were received via a physically secure medium) and, if non-NULL, an EID characterizing the node that send this inbound bundle.
Return Values
extern int bpContinueAcq( AcqWorkArea *workArea,\n char *bytes,\n int length,\n ReqAttendant *attendant,\n unsigned char priority);\nThis function continues acquisition of a bundle as initiated by an invocation of bpBeginAcq(). To do so, it appends the indicated array of bytes, of the indicated length, to the byte array that is encapsulated in workArea.
bpContinueAcq is an alternative to bpLoadAcq, intended for use by convergence-layer adapters that incrementally acquire portions of concatenated bundles into byte-array buffers. The function transparently creates a zero-copy object for acquisition of the bundle, if one does not already exist, and appends \"bytes\" to the source data of that ZCO.
The behavior of bpContinueAcq when currently available space for zero- copy objects is insufficient to contain this increment of bundle source data depends on the value of \"attendant\". If \"attendant\" is NULL, then bpContinueAcq will return 0 but will flag the acquisition work area for refusal of the bundle due to resource exhaustion (congestion). Otherwise, (i.e., \"attendant\" points to a ReqAttendant structure, which MUST have already been initialized by ionStartAttendant()), bpContinueAcq will block until sufficient space is available or the attendant is paused or the function fails, whichever occurs first.
\"priority\" is normally zero, but for the TCPCL convergence-layer receiver threads it is very high (255) because any delay in allocating space to an extent of TCPCL data delays the processing of TCPCL control messages, potentially killing TCPCL performance.
Return Values
extern void bpCancelAcq( AcqWorkArea *workArea);\nCancels acquisition of a new bundle via the indicated workArea, destroying the bundle acquisition ZCO of workArea.
"},{"location":"CLA-API/#bpendacq","title":"bpEndAcq","text":"extern int bpEndAcq( AcqWorkArea *workArea);\nReturn Value
1: on success, the bundle has been fully acquired and dispatched (that is, queued for delivery and/or forwarding). In this case, the invoking convergence- layer input adapter should simply continue with the next cycle of bundle acquisition, i.e., it should call bpBeginAcq().
0: on any failure pertaining only to this bundle. The failure is transient, applying only to the bundle that is currently being acquired. In this case, the current bundle acquisition has failed but BP itself can continue; the invoking convergence-layer input adapter should simply continue with the next cycle of bundle acquisition just as if the return code had been 1.
-1: on any other (i.e., system) failure.
extern int bpLoadAcq( AcqWorkArea *workArea,\n Object zco);\nbpLoadAcq is an alternative to bpContinueAcq, intended for use by convergence-layer adapters that natively acquire concatenated bundles into zero-copy objects such as LTP.
Return Value
This section is under construction
"},{"location":"Configure-Multiple-Network-Interfaces/","title":"Configure ION for Multiple Network Interfaces","text":"Lab testing of ION-based DTN network often uses only a single network. However, during deployment or operational testing, ION network must operate over multiple networks. To clarify how to configure ION, we consider the following hypothetical network configuration.
The basic topology is illustrated here:
+-------+ protocol a protocol b +-------+\n | | | |\n | SC1 +-----+ +--->+ MOC1 |\n | 21 | | | | 24 |\n +-------+ | +-------+ | +-------+\n +---->+ +----+\n rfnet | GS | gsnet\n +---->+ 23 +----+\n +-------+ | +-------+ | +-------+\n | | | | | |\n | SC2 +-----+ +--->+ MOC2 |\n | 22 | | 25 |\n +-------+ +-------+\n\nsubnet: 192.168.100.0/24 subnet:192.168.200.0/24\nrfnet (192.168.100.0/24) and gsnet (192.168.200.0/24).rfnet is protocol A and in gsnet, protocol B.ION associates each neighbor with an convergence layer protocol and an outduct. With the exception of UDP convergence layer, each outduct is associated with an induct as well.
When there are multiple neighbors using the same convergence layer protocol, only one induct is used to 'pair' with multiple outducts of the same protocol.
If neighbors using the same protocol are all within the same network, then the induct is associated with the IP address of the ION node on that particular network.
If the neighbors using the same protocol are from multiple networks, then the induct will need to be associated with INADDR_ANY, 0.0.0.0:port defined for protocols such as TCP, UDP, and STCP.
For LTP, however, multiple inducts can be defined for each network using the IP address of each network separately, and the induct for a network is called seat (see manual page for ltprc).
In this case, SC1 and SC2 communicates with GS using LTP, while MOC1 and MOC2 communicate with GS using TCP. The port we used is 4556.
For GS, it defines TCP in this manner in the .bprc file:
a protocol tcp\n\na induct tcp 192.168.200.23:4556 tcpcli\n\na outduct tcp 192.168.200.24:4556 tcpclo\na outduct tcp 192.168.200.25:4556 tcpclo\n\na plan ipn:24.0\na planduct ipn:24.0 tcp 192.168.200.24:4556\na planduct ipn:25.0 tcp 192.168.200.25:4556\nThere is only induct for the two outducts. Since node 23, 24, and 25 are in the 192.168.200.0/24 subnet, the induct for 23 can simply use its statically assigned IP address of 192.168.200.23:4556.
For MOC1, TCP is specified in this manner in the .bprc file:
a protocol tcp\n\na induct tcp 192.168.200.24:4556 tcpcli\n\na outduct tcp 192.168.200.23:4556 tcpclo\n\na plan ipn:23.0\n\na planduct ipn:23.0 tcp 192.168.200.23:4556\nSince MOC1 has only 1 neighbor and uses TCP, the induct/outduct and egress plans are very much the standard configuration we see typically in a single network configuration.
Similar configuration can be written for MOC2.
For LTP, the configuration for GS is:
# in bprc file\na protocol ltp\n\na induct ltp 23 ltpcli\n\na outduct ltp 21 ltpclo\na outduct ltp 22 ltpclo\n\na plan ipn:21.0 \na plan ipn:22.0\n\na planduct ipn:21.0 ltp 21\na planduct ipn:22.0 ltp 22\n\n# in .ltprc file\na span 21 100 100 1482 100000 1 'udplso 192.168.100.21:1113'\na span 22 100 100 1482 100000 1 'udplso 192.168.100.22:1113'\na seat 'udplsi 192.168.100.23:1113'\n\ns\nFor ltp, a single induct is specified for the 192.168.100.0/24 subnet using the a seat (add seat) command. The older syntax is s 'udplsi 192.168.100.23:1113', which works only for the case of a single network and port combination. However, when extending LTP to multiple seats (inducts) when there are multiple networks or when there are multiple ports, the seat command offers the flexibility to support more complex configurations.
The syntax for LTP/STCP is identical, except replacing tcp with stcp, tcpcli and tcpclo with stcpcli and stcpclo in the configuration files.
When runing TCP or STCP over both networks, the only change is that for the GS node, the induct definitions in .bprc are replaced by:
a induct tcp 0.0.0.0:4556 tcpcli and a induct stcp 0.0.0.0:4556 tcpcli
When running LTP over both networks, the only key difference is that in the .ltprc file for the GS node, two seats are defined:
a span 21 100 100 1482 100000 1 'udplso 192.168.100.21:1113'\na span 22 100 100 1482 100000 1 'udplso 192.168.100.22:1113'\na span 24 100 100 1482 100000 1 'udplso 192.168.200.24:1113'\na span 25 100 100 1482 100000 1 'udplso 192.168.200.25:1113'\na seat 'udplsi 192.168.100.23:1113'\na seat 'udplsi 192.168.200.23:1113'\n\ns\nOf course the bprc file must also be updated to add reflect the additional LTP neighbors, but that extension is straightforward so we will not be listing them here.
"},{"location":"Configure-Multiple-Network-Interfaces/#use-of-contact-graph","title":"Use of Contact Graph","text":"For ION, the use contact graph is optional when there is one hop. In that case, the data rate, normally defined in the contact graph, is provided through commands plan command in .bprc file.
When contact graph is present, the information in the contact graph supersedes the data rate specified in the plan command.
If there are no contact graph and the data rate is either 0 or omitted in the plan command, then there is no bundle level throttling of data.
exit command","text":"When no contact graph is provided, only immediate neighbor can exchange data. If relay operation is stil desired, an exit command can be used. In the case of the topology presented earlier, the node GS can be a gateway between the rfnet and gsnet. So GS can be added as an exit node for identified pair of source-destination.
ION offers software developer a set of standard interface for adding extensions to Bundle Protocol without modifying the core BP source code. This capability can be used to implement both standardized bundle extension blocks or user-specific extension blocks.
ION's interface for extending the Bundle Protocol enables the definition of external functions that insert extension blocks into outbound bundles (either before or after the payload block), parse and record extension blocks in inbound bundles, and modify extension blocks at key points in bundle processing. All extension-block handling is statically linked into ION at build time, but the addition of an extension never requires that any standard ION source code be modified.
Standard structures for recording extension blocks -- both in transient storage memory during bundle acquisition (AcqExtBlock) and in persistent storage [the ION database] during subsequent bundle processing (ExtensionBlock) -- are defined in the bei.h header file. In each case, the extension block structure comprises a block type code, block processing flags, possibly a list of EID references, an array of bytes (the serialized form of the block, for transmission), the length of that array, optionally an extension-specific opaque object whose structure is designed to characterize the block in a manner that's convenient for the extension processing functions, and the size of that object.
"},{"location":"Extension-Block-Interface/#extension-definition-extesniondef-extensiondefs","title":"Extension Definition:ExtesnionDef & extensionDefs","text":"The definition of each extension is asserted in an ExtensionDef structure, also as defined in the bei.h header file.
/**\n * \\struct ExtensionDef\n * \\brief Defines the callbacks used to process extension blocks.\n *\n * ExtensionDef defines the callbacks for production and acquisition\n * of a single type of extension block, identified by block type name\n * and number.\n */\ntypedef struct\n{\n char name[32]; /** Name of extension */\n BpBlockType type; /** Block type */\n\n /* Production callbacks. */\n\n BpExtBlkOfferFn offer; /** Offer */\n BpExtBlkSerializeFn serialize; /** Serialize */\n BpExtBlkProcessFn process[5]; /** Process */\n BpExtBlkReleaseFn release; /** Release */\n BpExtBlkCopyFn copy; /** Copy */\n\n /* Acquisition callbacks. */\n\n BpAcqExtBlkAcquireFn acquire; /** Acquire */\n BpAcqExtReviewFn review; /** Review */\n BpAcqExtBlkDecryptFn decrypt; /** Decrypt */\n BpAcqExtBlkParseFn parse; /** Parse */\n BpAcqExtBlkCheckFn check; /** Check */\n BpExtBlkRecordFn record; /** Record */\n BpAcqExtBlkClearFn clear; /** Clear */\n} ExtensionDef;\nEach ExtensionDef must supply:
The name of the extension. (Used in some diagnostic messages.)
The extension's block type code.
A pointer to an offer function.
A pointer to a function to be called when forwarding a bundle containing this sort of block.
A pointer to a function to be called when taking custody of a bundle containing this sort of block.
A pointer to a function to be called when enqueuing for transmission a bundle containing this sort of block.
A pointer to a function to be called when a convergence-layer adapter dequeues a bundle containing this sort of block, before serializing it.
A pointer to a function to be called immediately before a convergence-layer adapter transmits a bundle containing this sort of block, after the bundle has been serialized.
A pointer to a release function.
A pointer to a copy function.
A pointer to an acquire function.
A pointer to a review function.
A pointer to a decrypt function.
A pointer to a parse function.
A pointer to a check function.
A pointer to a record function.
A pointer to a clear function.
All extension definitions must be coded into an array of ExtensionDef structures named extensionDefs.
"},{"location":"Extension-Block-Interface/#extensionspec-specification-for-producing-an-extension-block","title":"ExtensionSpec - specification for producing an extension block","text":"/* ExtensionSpec provides the specification for producing an\n * outbound extension block: block definition (identified by\n * block type number), a formulation tag whose semantics are\n * block-type-specific, and applicable CRC type. */\n\ntypedef struct\n{\n BpBlockType type; /* Block type */\n unsigned char tag; /* Extension-specific */\n BpCrcType crcType; /* Type of CRC on block */\n} ExtensionSpec;\nAn array of ExtensionSpec structures named extensionSpecs is also required. Each ExtensionSpec provides the specification for producing an outbound extension block:
The order of appearance of extension specifications in the extensionSpecs array determines the order in which extension blocks will be inserted into locally sourced bundles.
"},{"location":"Extension-Block-Interface/#procedure-to-extend-the-bundle-protocol","title":"Procedure to Extend the Bundle Protocol","text":"The standard extensionDefs array -- which is empty -- is in the noextensions.c prototype source file. The procedure for extending the Bundle Protocol in ION is as follows:
Specify -DBP_EXTENDED in the Makefile's compiler command line when building the libbpP.c library module.
Create a copy of the prototype extensions file, named \"bpextensions.c\", in a directory that is made visible to the Makefile's libbpP.c compilation command line (by a -I parameter).
In the \"external function declarations\" area of \"bpextensions.c\", add \"extern\" function declarations identifying the functions that will implement your extension (or extensions).
Add one or more ExtensionDef structure initialization lines to the extensionDefs array, referencing those declared functions.
Add one or more ExtensionSpec structure initialization lines to the extensionSpecs array, referencing those extension definitions.
Develop the implementations of the extension implementation functions in one or more new source code files.
Add the object file or files for the new extension implementation source file (or files) to the Makefile's command line for linking libbpP.so.
The function pointers supplied in each ExtensionDef must conform to the following specifications.
NOTE that any function that modifies the bytes member of an ExtensionBlock or AckExtBlock must set the corresponding length to the new length of the bytes array, if changed.
int (*BpExtBlkOfferFn)(ExtensionBlock *blk, Bundle *bundle)\nPopulates all fields of the indicated ExtensionBlock structure for inclusion in the indicated outbound bundle. This function is automatically called when a new bundle is locally sourced or upon acquisition of a remotely sourced bundle that does not contain an extension block of this type. The values of the extension block are typically expected to be a function of the state of the bundle, but this is extension-specific. If it is not appropriate to offer an extension block of this type as part of this bundle, then the size, length, object, and bytes members of blk must all be set to zero. If it is appropriate to offer such a block but no internal object representing the state of the block is needed, the object and size members of blk must be set to zero. The type, blkProcFlags, and dataLength members of blk must be populated by the implementation of the \"offer\" function, but the length and bytes members are typically populated by calling the BP library function serializeExtBlk(), which must be passed the block to be serialized (with type, blkProcFlags and dataLength already set), a Lyst of EID references (two list elements -- offsets -- per EID reference, if applicable; otherwise NULL), and a pointer to the extension-specific block data. The block's bytes array and object (if present) must occupy space allocated from the ION database heap. Return zero on success, -1 on any system failure.
int (*BpExtBlkProcessFn)(ExtensionBlock *blk, Bundle *bundle, void *context)\nPerforms some extension-specific transformation of the data encapsulated in blk based on the state of bundle. The transformation to be performed will typically vary depending on whether the identified function is the one that is automatically invoked upon forwarding the bundle, upon taking custody of the bundle, upon enqueuing the bundle for transmission, upon removing the bundle from the transmission queue, or upon transmitting the serialized bundle. The context argument may supply useful supplemental information; in particular, the context provided to the ON_DEQUEUE function will comprise the name of the protocol for the duct from which the bundle has been dequeued, together with the EID of the neighboring node endpoint to which the bundle will be directly transmitted when serialized. The block-specific data in blk is located within bytes immediately after the header of the extension block; the length of the block's header is the difference between length and dataLength. Whenever the block's blkProcFlags, EID extensions, and/or block-specific data are altered, the serializeExtBlk() function should be called again to recalculate the size of the extension block and rebuild the bytes array. Return zero on success, -1 on any system failure.
void (*BpExtBlkReleaseFn)(ExtensionBlock *blk)\nReleases all ION database space occupied by the object member of blk. This function is automatically called when a bundle is destroyed. Note that incorrect implementation of this function may result in a database space leak.
int (*BpExtBlkCopyFn)(ExtensionBlock *newblk, ExtensionBlock *oldblk)\nCopies the object member of oldblk to ION database heap space and places the address of that new non-volatile object in the object member of newblk, also sets size in newblk. This function is automatically called when two copies of a bundle are needed, e.g., in the event that it must both be delivered to a local client and also fowarded to another node. Return zero on success, -1 on any system failure.
int (*BpAcqExtBlkAcquireFn)(AcqExtBlock *acqblk, AcqWorkArea *work)\nPopulates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is only to be provided for extension blocks that are never encrypted; a extension block that may be encrypted should have a BpAcqExtBlkParseFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkReviewFn)(AcqWorkArea *work)\nReviews the extension blocks that have been acquired for this bundle, checking to make sure that all blocks of this type that are required by policy are present. Returns 0 if any blocks are missing, 1 if all required blocks are present, -1 on any system failure.
int (*BpAcqExtBlkDecryptFn)(AcqExtBlock *acqblk, AcqWorkArea *work)\nDecrypts some other extension block that has been acquired but not yet parsed, nominally using encapsulated ciphersuite information. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if no error in decryption was encountered, -1 on any system failure.
int (*BpAcqExtBlkParseFn)(AcqExtBlock *acqblk, AcqWorkArea *work)\nPopulates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is provided for extension blocks that may be encrypted; a extension block that can never be encrypted should have a BpAcqExtBlkAcquireFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkCheckFn)(AcqExtBlock *acqblk, AcqWorkArea *work)\nExamines the bundle in work to determine whether or not it is authentic, in the context of the indicated extension block. Return 1 if the block is determined to be inauthentic (this will cause the bundle to be discarded), zero if no inauthenticity is detected, -1 on any system failure.
int (*BpExtBlkRecordFn)(ExtensionBlock *blk, AcqExtBlock *acqblk)\nCopies the object member of acqblk to ION database heap space and places the address of that non-volatile object in the object member of blk; also sets size in blk. This function is automatically called when an acquired bundle is accepted for forwarding and/or delivery. Return zero on success, -1 on any system failure.
void (*BpAcqExtBlkClearFn)(AcqExtBlock *acqblk)\nUses MRELEASE to release all ION working memory occupied by the object member of acqblk. This function is automatically called when acquisition of a bundle is completed, whether or not the bundle is accepted. Note that incorrect implementation of this function may result in a working memory leak.
"},{"location":"Extension-Block-Interface/#utility-functions-for-extension-processing","title":"Utility Functions for Extension Processing","text":"void discardExtensionBlock(AcqExtBlock *blk)\nDeletes this block from the bundle acquisition work area prior to the recording of the bundle in the ION database.
void scratchExtensionBlock(ExtensionBlock *blk)\nDeletes this block from the bundle after the bundle has been recorded in the ION database.
Object findExtensionBlock(Bundle *bundle, unsigned int type, unsigned char tag1, unsigned char tag2, unsigned char tag3)\nOn success, returns the address of the ExtensionBlock in bundle for the indicated type and tag values. If no such extension block exists, returns zero.
int serializeExtBlk(ExtensionBlock *blk, char *blockData)\nConstructs a BPv7-conformant serialized representation of this extension block in blk->bytes. Returns 0 on success, -1 on an unrecoverable system error.
void suppressExtensionBlock(ExtensionBlock *blk)\nCauses blk to be omitted when the bundle to which it is attached is serialized for transmission. This suppression remains in effect until it is reversed by restoreExtensionBlock();
void restoreExtensionBlock(ExtensionBlock *blk)\nReverses the effect of suppressExtensionBlock(), enabling the block to be included when the bundle to which it is attached is serialized.
"},{"location":"ICI-API/","title":"Interplanetary Communications Infrastructure (ICI) APIs","text":"This section will focus on a subset of ICI APIs that enables an external application to create, manipulate, and access data objects inside ION's SDR.
"},{"location":"ICI-API/#ici-apis","title":"ICI APIs","text":""},{"location":"ICI-API/#header","title":"Header","text":"#include \"ion.h\"\n#define MTAKE(size) allocFromIonMemory(__FILE__, __LINE__, size)\n#define MRELEASE(addr) releaseToIonMemory(__FILE__, __LINE__, addr)\nallocFromIonMemory and releaseToIonMemory, the functional equivalent of malloc and free for ION. The allocated memory space comes from the ION working memory, which has been pre-allocated during the ION configuration.Function Prototype
extern int ionAttach();\nParameters
Return Value
Example Call
if (ionAttach() < 0)\n{\n putErrmsg(\"bpadmin can't attach to ION.\", NULL);\n\n /* User calls error handling routine. */\n}\nDescription
Attached is the invoking task to ION infrastructure as previously established by running the ionadmin utility program. After successful execution, the handle to the ION SDR can be obtained by a separate API call. putErrmsg is an ION logging API, which will be described later in this document.
Function Prototype
extern void ionDetach();\nParameters
Return Value
Example Call
ionDetach();\nDescription
Detaches the invoking task from ION infrastructure. In particular, releases handle allocated for access to ION's non-volatile database.
"},{"location":"ICI-API/#ionterminate","title":"ionTerminate","text":"Function Prototype
extern void ionTerminate();\nParameters
Return Value
Example Call
ionTerminate();\nDescription
Shuts down the entire ION node, terminating all daemons. The state of the SDR will be destroyed during the termination process, even if the SDR heap is implemented in a non-volatile storage, such as a file.
"},{"location":"ICI-API/#ionstartattendant","title":"ionStartAttendant","text":"Function Prototype
extern int ionStartAttendant(ReqAttendant *attendant);\nParameters
*attendant: pointer to a ReqAttendant structure that will be initialized by this function.typedef struct\n{\n sm_SemId semaphore;\n} ReqAttendant;\nReturn Value
Example Call
if (ionStartAttendant(&attendant))\n{\n putErrmsg(\"Can't initialize blocking transmission.\", NULL);\n\n /* user implemented error handling routine */\n}\nDescription
Initializes the semaphore in attendant to block a pending ZCO space request. This is necessary to ensure that the invoking task cannot inject data into the Bundle Protocol Agent until SDR space has been allocated.
Function Prototype
extern void ionStopAttendant(ReqAttendant *attendant);\nParameters
*attendant: pointer to a ReqAttendant structure that will be destroyed by this function.Return Value
Example Call
ionStopAttendant(&attendant);\nDescription
Destroys the semaphore in attendant, preventing a potential resource leak. This is typically called at the end of a BP application after all user data have been injected into the SDR.
Function Prototype
void ionPauseAttendant(ReqAttendant *attendant)\nParameters
*attendant: pointer to a ReqAttendant structure.Return Value
Example Call
ionStopAttendant(&attendant);\nDescription
\"Ends\" the semaphore in attendant so that the task blocked on taking it is interrupted and may respond to an error or shutdown condition. This may be required when trying to quit a blocked user application while acquiring ZCO space.
"},{"location":"ICI-API/#ioncreatezco","title":"ionCreateZco","text":"Function Prototype
extern Object ionCreateZco( ZcoMedium source,\n Object location,\n vast offset,\n vast length,\n unsigned char coarsePriority,\n unsigned char finePriority,\n ZcoAcct acct,\n ReqAttendant *attendant);\nParameters
Source: the type of ZCO to be created. Each source data object may be either a file, a \"bulk\" item in mass storage, an object in SDR heap space (identified by heap address stored in an \"object reference\" object in SDR heap), an array of bytes in SDR heap space (identified by heap address), or another ZCO.
typedef enum\n{\n ZcoFileSource = 1,\n ZcoBulkSource = 2,\n ZcoObjSource = 3,\n ZcoSdrSource = 4,\n ZcoZcoSource = 5\n} ZcoMedium;\nlocation: the location in the heap where a single extent of source data resides. The user application usually places this data via sdr_malloc(), which will be discussed later.offset: the offset within the source data object where the first byte of the ZCO should be placed.length: the length of the ZCO to be created.coarsePriority: this sets the bundle's Class of Service (COS) as an inherited feature from BPv6. Although COS is not specified in BPv7, ION API supports this feature when creating ZCOs. From the lowest to the highest priorities, it can be set to the following values:BP_BULK_PRIORITY (value =0)BP_STD_PRIORITY (value = 1), or BP_EXPEDITED_PRIORITY (value = 2)finePriority: this is inherited from BPv6 COS and is the finer grain priority level (level 0 to 254) within the BP_STD_PRIORITY class. The default value is 0.acct: The accounting category for the ZCO, which is either ZcoInbound (0), ZcoOutbound (1), or ZcoUnknown (2). If a ZCO is created for transmission to another node, this parameter is typically set to ZcoOutbound.*attendant: the semaphore that blocks the return of the function until the necessary resources have been allocated in the SDR for the ZCOReturn Value
((Object) -1): the function has failed0: either the attendant was NULL and sufficient space for the first extent of the ZCO was not immediately available, or the function was interrupted by ionPauseAttendant before space for the ZCO became available.Example Call
SdrObject bundleZco;\n\nbundleZco = ionCreateZco(ZcoSdrSource, extent, 0, lineLength,\n BP_STD_PRIORITY, 0, ZcoOutbound, &attendant);\nif (bundleZco == 0 || bundleZco == (Object) ERROR)\n{\n putErrmsg(\"Can't create ZCO extent.\", NULL);\n /* user implemented error handling routine goes here */\n}\nDescription
This function provides a \"blocking\" implementation of admission control in ION. Like zco_create(), it constructs a zero-copy object (see zco(3)) that contains a single extent of source data residing at a location in the source, of which the initial offset number of bytes are omitted and the subsequent length bytes are included. By providing an attendant semaphore, initialized by ionStartAttendant, ionCreateZco() can be executed as a blocking call so long as the total amount of space in the source available for new ZCO formation is less than the length. ionCreateZco() operates by calling ionRequestZcoSpace, then pending on the semaphore in attendant as necessary before creating the ZCO and then populating it with the user's data.
SDR persistent data are referenced by object and address values in the application code, simply displacements (offsets) within the SDR address space. The difference between the two is that an Object is always the address of a block of heap space returned by some call to sdr_malloc, while an Address can refer to any byte in the SDR address space. An Address is the SDR functional equivalent of a C pointer; some Addresses point to actual Objects.
The number of SDR-related APIs is significant, and most are used by ION internally. Fortunately, there are only a few APIs that an external application will likely need to use. The following list of the most commonly used APIs is drawn from the Database I/O and the Heap Space Management API categories.
"},{"location":"ICI-API/#header_1","title":"Header","text":"#include \"sdr.h\"\nFunction Prototype
Object sdr_malloc(Sdr sdr, unsigned long size)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachsize: size of the block to allocateReturn Value
Example Call
CHKZERO(sdr_begin_xn(sdr));\nextent = sdr_malloc(sdr, lineLength);\nif (extent)\n{\n sdr_write(sdr, extent, text, lineLength);\n}\n\nif (sdr_end_xn(sdr) < 0)\n{\n putErrmsg(\"No space for ZCO extent.\", NULL);\n bp_detach();\n return 0;\n}\nIn this example, a 'critical section' has been implemented by API calls: sdr_begin_xn and sdr_end_xn. The critical section ensures that the SDR is not altered while the space allocation is in progress. These APIs will be explained later in this document. The sdr_write API is used to write data into the space acquired by sdr_malloc.
It may seem strange that failing to allocate space or write the data into the allocated space relies on checking the return value of sdr_end_xn instead of sdr_malloc and sdr_write functions. This is because when sdr_end_xn returns a negative value, it indicates that an SDR transaction was already terminated, which occurs when sdr_malloc or sdr_write fails. So, this is a convenient way to detect the failure of two calls simultaneously by checking the sdr_end_xn call return value.
Description
Allocates a block of space from the indicated SDR's heap. The maximum size is 1/2 of the maximum address space size (i.e., 2G for a 32-bit machine). Returns block address if successful, zero if block could not be allocated.
"},{"location":"ICI-API/#sdr_insert","title":"sdr_insert","text":"Function Prototype
Object sdr_insert(Sdr sdr, char *from, unsigned long size)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attach*from: pointer to the location where several bytes (specified by size) of data are to be copied into the allocated space in the SDRsize: size of the block to allocateReturn Value
Example Call
CHKZERO(sdr_begin_xn(sdr));\nextent = sdr_insert(sdr, text, lineLength);\nif (sdr_end_xn(sdr) < 0)\n{\n putErrmsg(\"No space for ZCO extent.\", NULL);\n bp_detach();\n return 0;\n}\nDescription
This function combines the action of sdr_malloc and sdr_write. It first uses sdr_malloc to obtain a block of space, and if this allocation is successful, it uses sdr_write to copy size bytes of data from memory into the newly allocated block.
Function Prototype
Object sdr_stow(sdr, variable)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachvariable: the variable whose value is to be inserted into an SDR spaceReturn Value
Description
sdr_stow is a macro that uses sdr_insert to insert a copy of a variable into the dataspace. The size of the variable is used as the number of bytes to copy.
Function Prototype
int sdr_object_length(Sdr sdr, Object object)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachobject: the location of an application data objectReturn Value
Description
Returns the number of bytes of heap space allocated to the application data at object.
"},{"location":"ICI-API/#sdr_free","title":"sdr_free","text":"Function Prototype
void sdr_free(Sdr sdr, Object object)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachobject: the location of an application data ObjectReturn Value
Description
Frees the heap space occupied by an object at object. The space freed are put back into the SDR memory pool and will become available for subsequent re-allocation.
"},{"location":"ICI-API/#sdr_read","title":"sdr_read","text":"Function Prototype
void sdr_read(Sdr sdr, char *into, Address from, int length)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attach*into: the location in memory data should be read intofrom: this is a location in the SDR heaplength: this is the size to be readReturn Value
Description
Copies length characters from (a location in the indicated SDR) to the memory location given by into. The data are copied from the shared memory region in which the SDR resides, if any; otherwise, they are read from the file in which the SDR resides.
"},{"location":"ICI-API/#sdr_stage","title":"sdr_stage","text":"Function Prototype
void sdr_stage(Sdr sdr, char *into, Object from, int length)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attach*into: the location in memory data should be read intofrom: this is a location in the SDR heap which is occupied by an allocated objectlength: this is the size to be readReturn Value
Description
Like sdr_read, this function will copy length characters from (a location in the heap of the indicated SDR) to the memory location given by into. Unlike sdr_get, sdr_stage requires that from be the address of some allocated object, not just any location within the heap. sdr_stage, when called from within a transaction, notifies the SDR library that the indicated object may be updated later in the transaction; this enables the library to retrieve the object's size for later reference in validating attempts to write into some location within the object. If the length is zero, the object's size is privately retrieved by SDR, but none of the object's content is copied into memory.
sdr_get is a macro that uses sdr_read to load variables from the SDR address given by heap_pointer; heap_pointer must be (or be derived from) a heap pointer as returned by sdr_pointer. The size of the variable is used as the number of bytes to copy.
Function Prototype
void sdr_write(Sdr sdr, Address into, char *from, int length)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attach*into: the location in the SDR heap where data should be written intofrom: this is a location in memory where data should copied fromlength: this is the size to be writtenReturn Value
Description
Like sdr_read, this function will copy length characters from (a location in the heap of the indicated SDR) to the memory location given by into. Unlike sdr_get, sdr_stage requires that from be the address of some allocated object, not just any location within the heap. sdr_stage, when called from within a transaction, notifies the SDR library that the indicated object may be updated later in the transaction; this enables the library to retrieve the object's size for later reference in validating attempts to write into some location within the object. If length is zero, the object's size is privately retrieved by SDR but none of the object's content is copied into memory.
sdr_get is a macro that uses sdr_read to load variables from the SDR address given by heap_pointer; heap_pointer must be (or be derived from) a heap pointer as returned by sdr_pointer. The size of the variable is used as the number of bytes to copy.
The following APIs manage transactions by implementing a critical section in which SDR content cannot be modified.
"},{"location":"ICI-API/#header_2","title":"Header","text":"#include \"sdrxn.h\"\nFunction Prototype
int sdr_begin_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Initiates a transaction. Returns 1 on success, 0 on any failure. Note that transactions are single-threaded; any task that calls sdr_begin_xn is suspended until all previously requested transactions have been ended or canceled.
Function Prototype
int sdr_in_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Returns 1 if called in the course of a transaction, 0 otherwise.
"},{"location":"ICI-API/#sdr_exit_xn","title":"sdr_exit_xn","text":"Function Prototype
void sdr_exit_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Simply abandons the current transaction, ceasing the calling task's lock on ION. MUST NOT be used if any dataspace modifications were performed during the transaction; sdr_end_xn must be called instead to commit those modifications.
Function Prototype
void sdr_cancel_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Cancels the current transaction. If reversibility is enabled for the SDR, canceling a transaction reverses all heap modifications performed during that transaction.
"},{"location":"ICI-API/#sdr_end_xn","title":"sdr_end_xn","text":"Function Prototype
int sdr_end_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Ends the current transaction. Returns 0 if the transaction was completed without any error; returns -1 if any operation performed in the course of the transaction failed, in which case the transaction was automatically canceled.
"},{"location":"ICI-API/#sdr-list-management-apis","title":"SDR List management APIs","text":"The SDR list management functions manage doubly-linked lists in managed SDR heap space. The functions manage two kinds of objects: lists and list elements. A list knows how many elements it contains and what its start and end elements are. An element knows what list it belongs to and the elements before and after it in the list. An element also knows its content, which is normally the SDR Address of some object in the SDR heap. A list may be sorted, which speeds the process of searching for a particular element.
"},{"location":"ICI-API/#header_3","title":"Header","text":"#include \"sdr.h\"\n\ntypedef int (*SdrListCompareFn)(Sdr sdr, Address eltData, void *argData);\ntypedef void (*SdrListDeleteFn)(Sdr sdr, Object elt, void *argument);\nUSAGE
When inserting elements or searching a list, the user may optionally provide a compare function of the form:
int user_comp_name(Sdr sdr, Address eltData, void *dataBuffer);\nWhen provided, this function is automatically called by the sdrlist function being invoked; when the function is called, it is passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, dataBuffer, which is nominally the address in the local memory of some other item in the same format. The user-supplied function normally compares some key values of the two data items. It returns 0 if they are equal, an integer less than 0 if eltData's key value is less than that of dataBuffer, and an integer greater than 0 if eltData's key value is greater than that of dataBuffer. These return values will produce a list in ascending order. If the user desires the list to be in descending order, the function must reverse the signs of these return values.
When deleting an element or destroying a list, the user may optionally provide a delete function of the form:
void user_delete_name(Sdr sdr, Address eltData, void *argData)\nWhen provided, this function is automatically called by the sdrlist function being invoked; when the function is called, it is passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, argData, which if non-NULL is normally the address in the local memory of a data item providing context for the list element deletion. The user-supplied function performs any application-specific cleanup associated with deleting the element, such as freeing the element's content data item and/or other SDR heap space associated with the element.
"},{"location":"ICI-API/#sdr_list_insert_first","title":"sdr_list_insert_first","text":""},{"location":"ICI-API/#sdr_list_insert_last","title":"sdr_list_insert_last","text":"Function Prototype
Object sdr_list_insert_first(Sdr sdr, Object list, Address data)\nObject sdr_list_insert_last(Sdr sdr, Object list, Address data)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a listdata: an address in SDRReturn Value
address of newly created element: success0: any errorDescription
Creates a new element and inserts it at the front/end of the list. This function should not be used to insert a new element into any ordered list; use sdr_list_insert() instead.
Function Prototype
Object sdr_list_create(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
address of newly created list: Success0: any errorDescription
Creates a new list object in the SDR; the new list object initially contains no list elements. Returns the address of the new list or zero on any error.
"},{"location":"ICI-API/#sdr_list_length","title":"sdr_list_length","text":"Function Prototype
int sdr_list_length(Sdr sdr, Object list)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDRReturn Value number of elements in the list: Success *-1`: any error
Description
Returns the number of elements in the list, or -1 on any error.
"},{"location":"ICI-API/#sdr_list_destroy","title":"sdr_list_destroy","text":"Function Prototype
void sdr_list_destroy(Sdr sdr, Object list, SdrListDeleteFn fn, void *arg)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDR to be destroyedfn: a sdrlist delete functionarg: arguments passed to the delete functionReturn Value
Description
Destroys a list, freeing all elements of the list. If fn is non-NULL, that function is called once for each freed element; when called, fn is passed the Address that is the element's data, and the argument pointer is passed to sdr_list_destroy. See the manual page for sdrlist for details on the form of the delete function sdrlist.
Do not use sdr_free to destroy an SDR list, as this would leave the elements of the list allocated yet unreferenced.
"},{"location":"ICI-API/#sdr_list_user_data_set","title":"sdr_list_user_data_set","text":"Function Prototype
void sdr_list_user_data_set(Sdr sdr, Object list, Address userData)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDR to be destroyeduserData: a single word which is a SDR addressReturn Value
Description
Sets the \"user data\" word of list to userData. Note that userData is nominally an Address but can be any value that occupies a single word. It is typically used to point to an SDR object that somehow characterizes the list as a whole, such as a name.
"},{"location":"ICI-API/#sdr_list_user_data","title":"sdr_list_user_data","text":"Function Prototype
Address sdr_list_user_data(Sdr sdr, Object list)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDR to be destroyedReturn Value
value of the \"user data\" word of list: Success0: any errorDescription
Returns the value of the \"user data\" word of list, or zero on any error.
"},{"location":"ICI-API/#sdr_list_insert","title":"sdr_list_insert","text":"Function Prototype
Object sdr_list_insert(Sdr sdr, Object list, Address data, SdrListCompareFn fn, void *dataBuffer)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDR to be destroyeddata: address in SDRfn: a sdrlist compare functiondataBuffer: data pass to the compare functionReturn Value
value of the \"user data\" word of list: Success0: any errorDescription
Creates a new list element whose data value is data and inserts that element into the list. If fn is NULL, the new list element is simply appended to the list; otherwise, the new list element is inserted after the last element in the list whose data value is \"less than or equal to\" the data value of the new element (in dataBuffer) according to the collating sequence established by fn. Returns the address of the newly created element or zero on any error.
"},{"location":"ICI-API/#sdr_list_insert_before","title":"sdr_list_insert_before","text":""},{"location":"ICI-API/#sdr_list_insert_after","title":"sdr_list_insert_after","text":"Function Prototype
Object sdr_list_insert_before(Sdr sdr, Object elt, Address data)\nObject sdr_list_insert_after(Sdr sdr, Object elt, Address data)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: an element of a list in the SDRdata: an address in SDRReturn Value
address of the newly created list element: success0: any errorDescription
Creates a new element and inserts it before/after the specified list element. This function should not be used to insert a new element into an ordered list; use sdr_list_insert instead. Returns the address of the newly created list element or zero on any error.
Function Prototype
void sdr_list_delete(Sdr sdr, Object elt, SdrListDeleteFn fn, void *arg)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: an element of a list in the SDRfn: a sdr list delete function*arg: argument passed to the delete functionReturn Value
Description
Delete elt from the list it is in. If fn is non-NULL, that function will be called upon deletion of elt; when called, that function is passed the Address that is the list element's data value and the arg pointer passed to sdr_list_delete.
Function Prototype
Object sdr_list_first(Sdr sdr, Object list)\nObject sdr_list_last(Sdr sdr, Object list)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: address of a list in the SDRReturn Value
address to the first/last element: success0: any errorDescription
Returns the address of the first/last element of the list, or zero on any error.
"},{"location":"ICI-API/#sdr_list_next","title":"sdr_list_next","text":""},{"location":"ICI-API/#sdr_list_prev","title":"sdr_list_prev","text":"Function Prototype
Object sdr_list_next(Sdr sdr, Object elt)\nObject sdr_list_prev(Sdr sdr, Object elt)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistReturn Value
address to the element following/preceding the element provided: success0: any errorDescription
Returns the address of the element following/preceding elt in that element's list or zero on any error.
"},{"location":"ICI-API/#sdr_list_search","title":"sdr_list_search","text":"Function Prototype
Object sdr_list_search(Sdr sdr, Object elt, int reverse, SdrListCompareFn fn, void *dataBuffer);\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistreverse: order of searchfn: a sdrlist compare function*dataBuffer: address of data to be used for searchReturn Value
address to the matching element: success0: any errorDescription
Search a list for an element whose data matches the data in dataBuffer, starting at the indicated initial list element.
If the compare function is non-NULL, the list is assumed to be sorted in the order implied by that function, and the function is automatically called once for each element of the list until it returns a value that is greater than or equal to zero (where zero indicates an exact match and a value greater than zero indicates that the list contains no matching element); each time compare is called it is passed the Address that is the element's data value and the dataBuffer value passed to sm_list_search(). If the reverse is non-zero, then the list is searched in reverse order (starting at the indicated initial list element), and the search ends when the compare function returns a value that is less than or equal to zero. If the compare function is NULL, then the entire list is searched (in either forward or reverse order, as directed) until an element is located whose data value is equal to ((Address) dataBuffer). Returns the address of the matching element if one is found, 0 otherwise.
"},{"location":"ICI-API/#sdr_list_list","title":"sdr_list_list","text":"Function Prototype
Object sdr_list_list(Sdr sdr, Object elt)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistReturn Value
address to the list to which elt belongs: success0: any errorDescription
Returns the address of the list to which elt belongs, or 0 on any error.
"},{"location":"ICI-API/#sdr_list_data","title":"sdr_list_data","text":"Function Prototype
Address sdr_list_data(Sdr sdr, Object elt)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistReturn Value
address that is the data value of elt: success0: any errorDescription
Returns the Address that is the data value of elt, or 0 on any error.
"},{"location":"ICI-API/#sdr_list_data_set","title":"sdr_list_data_set","text":"Function Prototype
Address sdr_list_data_set(Sdr sdr, Object elt, Address data)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistdata: address of data in SDRReturn Value
original data value of elt: success0: any errorDescription
Sets the data value for elt to data, replacing the original value. Returns the original data value for elt, or 0 on any error. The original data value for elt may or may not have been the address of an object in heap data space; even if it was, that object was NOT deleted.
Warning: changing the data value of an element of an ordered list may ruin the ordering of the list.
"},{"location":"ICI-API/#other-less-used-ici-apis","title":"Other less used ICI APIs","text":"There are many other less frequently used APIs. Please see the manual pages for the following:
ion, sdr, sdrlist, platform, lyst, psm, memmgr, sdrstring, sdrtable, and smlist.
This section covers interfaces for users to access the following four DTN application-level services provided by ION:
The CFDP library provides functions enabling application software to use CFDP to send and receive files. It conforms to the Class 1 (Unacknowledged) service class defined in the CFDP Blue Book and includes several standard CFDP user operations implementations.
In the ION implementation of CFDP, the CFDP notion of entity ID is identical to the BP (CBHE) notion of DTN node number used in ION.
CFDP entity and transaction numbers may be up to 64 bits in length. For portability to 32-bit machines, these numbers are stored in the CFDP state machine as structures of type CfdpNumber.
To simplify the interface between CFDP and the user application without risking storage leaks, the CFDP-ION API uses MetadataList objects. A MetadataList is a specially formatted SDR list of user messages, filestore requests, or filestore responses. During the time that a MetadataList is pending processing via the CFDP APIs, but is not yet (or is no longer) reachable from any FDU object, a pointer to the list is appended to one of the lists of MetadataList objects in the CFDP non-volatile database. This assures that any unplanned termination of the CFDP daemons won't leave any SDR lists unreachable - and therefore un-recyclable - due to the absence of references to those lists. Restarting CFDP will automatically purge any unused MetadataLists from the CFDP database. The \"user data\" variable of the MetadataList itself is used to implement this feature: while the list is reachable only from the database root, its user data variable points to the database root list from which it is referenced. In contrast, the list is attached to a File Delivery Unit; its user data is NULL.
CFDP transmits the data in a source file in fixed-sized segments by default. The user application can override this behavior at the time transmission of a file is requested by supplying a file reader callback function that reads the file - one byte at a time - until it detects the end of a \"record\" that has application significance. Each time CFDP calls the reader function, the function must return the length of one such record (not greater than 65535).
When CFDP is used to transmit a file, a 32-bit checksum must be provided in the \"EOF\" PDU to enable the receiver of the file to ensure that it was not corrupted in transit. When supplied with an application-specific file reader function, it updates the computed checksum as it reads each file byte; a CFDP library function is provided. Two types of file checksums are supported: a simple modular checksum or a 32-bit CRC. The checksum type must be passed through to the CFDP checksum computation function, so it must be provided by (and thus to) the file reader function.
The user application may provide per-segment metadata. To enable this, upon formation of each file data segment, CFDP will invoke the user-provided per-segment metadata composition callback function (if any), a function conforming to the CfdpMetadataFn type definition. The callback will be passed the offset of the segment within the file, the segment's offset within the current record (as applicable), the length of the segment, an open file descriptor for the source file (in case the data must be read to construct the metadata), and a 63-byte buffer in which to place the new metadata. The callback function must return the metadata length to attach to the file data segment PDU (may be zero) or -1 in case of a general system failure.
The return value for each CFDP \"request\" function (put, cancel, suspend, resume, report) is a reference number that enables \"events\" obtained by calling cfdp_get_event() to be matched to the requests that caused them. Events with a reference number set to zero were caused by autonomous CFDP activity, e.g., the reception of a file data segment.
#include \"cfdp.h\"\n\ntypedef enum\n{\n CksumTypeUnknown = -1,\n ModularChecksum = 0,\n CRC32CChecksum = 2,\n NullChecksum = 15\n} CfdpCksumType;\n\ntypedef int (*CfdpReaderFn)(int fd, unsigned int *checksum, CfdpCksumType ckType);\n\ntypedef int (*CfdpMetadataFn)(uvast fileOffset, unsigned int recordOffset, unsigned int length, int sourceFileFD, char *buffer);\n\ntypedef enum\n{\n CfdpCreateFile = 0,\n CfdpDeleteFile,\n CfdpRenameFile,\n CfdpAppendFile,\n CfdpReplaceFile,\n CfdpCreateDirectory,\n CfdpRemoveDirectory,\n CfdpDenyFile,\n CfdpDenyDirectory\n} CfdpAction;\n\ntypedef enum\n{\n CfdpNoEvent = 0,\n CfdpTransactionInd,\n CfdpEofSentInd,\n CfdpTransactionFinishedInd,\n CfdpMetadataRecvInd,\n CfdpFileSegmentRecvInd,\n CfdpEofRecvInd,\n CfdpSuspendedInd,\n CfdpResumedInd,\n CfdpReportInd,\n CfdpFaultInd,\n CfdpAbandonedInd\n} CfdpEventType;\n\ntypedef struct\n{\n char *sourceFileName;\n char *destFileName;\n MetadataList messagesToUser;\n MetadataList filestoreRequests;\n CfdpHandler *faultHandlers;\n int unacknowledged;\n unsigned int flowLabelLength;\n unsigned char *flowLabel;\n int recordBoundsRespected;\n int closureRequested;\n} CfdpProxyTask;\n\ntypedef struct\n{\n char *directoryName;\n char *destFileName;\n} CfdpDirListTask;\nint cfdp_attach()\nAttaches the application to CFDP functionality on the local computer.
Return Value
int cfdp_entity_is_started()\nReturn Value * 1: if the local CFDP entity has been started and not yet stopped * 0: otherwise
"},{"location":"ION-Application-Service-Interface/#cfdp_detach","title":"cfdp_detach","text":"void cfdp_detach()\nTerminates all access to CFDP functionality on the local computer.
"},{"location":"ION-Application-Service-Interface/#cfdp_compress_number","title":"cfdp_compress_number","text":"void cfdp_compress_number(CfdpNumber *toNbr, uvast from)\nConverts an unsigned vast number into a CfdpNumber structure, e.g., for use when invoking the cfdp_put() function.
"},{"location":"ION-Application-Service-Interface/#cfdp_decompress_number","title":"cfdp_decompress_number","text":"void cfdp_decompress_number(uvast toNbr, CfdpNumber *from)\nConverts a numeric value in a CfdpNumber structure to an unsigned vast integer.
"},{"location":"ION-Application-Service-Interface/#cfdp_update_checksum","title":"cfdp_update_checksum","text":"void cfdp_update_checksum(unsigned char octet, uvast *offset, unsigned int *checksum, CfdpCksumType ckType)\nFor use by an application-specific file reader callback function, which must pass to cfdp_update_checksum() the value of each byte (octet) it reads. offset must be octet's displacement in bytes from the start of the file. The checksum pointer is provided to the reader function by CFDP.
"},{"location":"ION-Application-Service-Interface/#cfdp_create_usrmsg_list","title":"cfdp_create_usrmsg_list","text":"MetadataList cfdp_create_usrmsg_list()\nCreates a non-volatile linked list, suitable for containing messages-to-user that are to be presented to cfdp_put().
"},{"location":"ION-Application-Service-Interface/#cfdp_add_usrmsg","title":"cfdp_add_usrmsg","text":"int cfdp_add_usrmsg(MetadataList list, unsigned char *text, int length)\nAppends the indicated message-to-user to list.
"},{"location":"ION-Application-Service-Interface/#cfdp_get_usrmsg","title":"cfdp_get_usrmsg","text":"int cfdp_get_usrmsg(MetadataList list, unsigned char *textBuf, int *length)\nRemoves from list the first of the remaining messages-to-user contained in the list and delivers its text and length. When the last message in the list is delivered, destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_destroy_usrmsg_list","title":"cfdp_destroy_usrmsg_list","text":"void cfdp_destroy_usrmsg_list(MetadataList *list)\nRemoves and destroys all messages-to-user in list and destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_create_fsreq_list","title":"cfdp_create_fsreq_list","text":"MetadataList cfdp_create_fsreq_list()\nCreates a non-volatile linked list, suitable for containing filestore requests that are to be presented to cfdp_put().
"},{"location":"ION-Application-Service-Interface/#cfdp_add_fsreq","title":"cfdp_add_fsreq","text":"int cfdp_add_fsreq(MetadataList list, CfdpAction action, char *firstFileName, char *seconfdFIleName)\nAppends the indicated filestore request to list.
"},{"location":"ION-Application-Service-Interface/#cfdp_get_fsreq","title":"cfdp_get_fsreq","text":"int cfdp_get_fsreq(MetadataList list, CfdpAction *action, char *firstFileNameBuf, char *secondFileNameBuf)\nRemoves from list the first of the remaining filestore requests contained in the list and delivers its action code and file names. When the last request in the list is delivered, destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_destroy_fsreq_list","title":"cfdp_destroy_fsreq_list","text":"void cfdp_destroy_fsreq_list(MetadataList *list)\nRemoves and destroys all filestore requests in list and destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_get_fsresp","title":"cfdp_get_fsresp","text":"int cfdp_get_fsresp(MetadataList list, CfdpAction *action, int *status, char *firstFileNameBuf, char *secondFileNameBuf, char *messageBuf)\nRemoves from list the first of the remaining filestore responses contained in the list and delivers its action code, status, file names, and message. When the last response in the list is delivered, it destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_destroy_fsresp_list","title":"cfdp_destroy_fsresp_list","text":"void cfdp_destroy_fsresp_list(MetadataList *list)\nRemoves and destroys all filestore responses in list and destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_read_space_packets","title":"cfdp_read_space_packets","text":"int cfdp_read_space_packets(int fd, unsigned int *checksum)\nThis is a standard \"reader\" function that segments the source file on CCSDS space packet boundaries. Multiple small packets may be aggregated into a single file data segment.
"},{"location":"ION-Application-Service-Interface/#cfdp_read_text_lines","title":"cfdp_read_text_lines","text":"int cfdp_read_text_lines(int fd, unsigned int *checksum)\nThis is a standard \"reader\" function that segments a source file of text lines on line boundaries.
"},{"location":"ION-Application-Service-Interface/#cfdp_put","title":"cfdp_put","text":"int cfdp_put(CfdpNumber *destinationEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpMetadataFn metadataFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *transactionId)\nSends the file identified by sourceFileName to the CFDP entity identified by destinationEntityNbr. destinationFileName is used to indicate the name by which the file will be catalogued upon arrival at its final destination; if NULL, the destination file name defaults to sourceFileName. If sourceFileName is NULL, it is assumed that the application is requesting transmission of metadata only (as discussed below) and destinationFileName is ignored. Note that both sourceFileName and destinationFileName are interpreted as path names, i.e., directory paths may be indicated in either or both. The syntax of path names is opaque to CFDP; the syntax of sourceFileName must conform to the path naming syntax of the source entity's file system and the syntax of destinationFileName must conform to the path naming syntax of the destination entity's file system.
The byte array identified by utParms, if non-NULL, is interpreted as transmission control information that is to be passed on to the UT layer. The nominal UT layer for ION's CFDP being Bundle Protocol, the utParms array is normally a pointer to a structure of type BpUtParms; see the bp man page for a discussion of the parameters in that structure.
closureLatency is the length of time following transmission of the EOF PDU within which a responding Transaction Finish PDU is expected. If no Finish PDU is requested, this parameter value should be zero.
messagesToUser and filestoreRequests, where non-zero, must be the addresses of non-volatile linked lists (that is, linked lists in ION's SDR database) of CfdpMsgToUser and CfdpFilestoreRequest objects identifying metadata that are intended to accompany the transmitted file. Note that this metadata may accompany a file of zero length (as when sourceFileName is NULL as noted above) -- a transmission of metadata only.
Return Value
*transactionID with the source entity ID and the transaction number assigned to this transmission and returns the request number identifying this \"put\" request. The transaction ID may be used to suspend, resume, cancel, or request a report on the progress of this transmission. int cfdp_cancel(CfdpTransactionId *transactionId)\nCancels transmission or reception of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, cancellation of a file transmission may have little effect.
Return Value * request number: on success * -1: on any error
"},{"location":"ION-Application-Service-Interface/#cfdp_suspend","title":"cfdp_suspend","text":"int cfdp_suspend(CfdpTransactionId *transactionId)\nSuspends transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, suspension of a file transmission may have little effect.
Return Value * request number: on success * -1: on any error
"},{"location":"ION-Application-Service-Interface/#cfdp_resume","title":"cfdp_resume","text":"int cfdp_resume(CfdpTransactionId *transactionId)\nResumes transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, resumption of a file transmission may have little effect.
Return Value * request number: on success * -1: on any error
"},{"location":"ION-Application-Service-Interface/#cfdp_report","title":"cfdp_report","text":"int cfdp_report(CfdpTransactionId *transactionId)\nRequests issuance of a report on the transmission or reception progress of the indicated transaction. The report takes the form of a character string that is returned in a CfdpEvent structure; use cfdp_get_event() to receive the event (which may be matched to the request by request number).
Return Value * request number: on success * 0: if the transaction ID is unknown * -1: on any error
"},{"location":"ION-Application-Service-Interface/#cfdp_get_event","title":"cfdp_get_event","text":"int cfdp_get_event(CfdpEventType *type, time_t *time, int *reqNbr, CfdpTransactionId *transactionId, char *sourceFileNameBuf, char *destFileNameBuf, uvast *fileSize, MetadataList *messagesToUser, uvast *offset, unsigned int *length, CfdpCondition *condition, uvast *progress, CfdpFileStatus *fileStatus, CfdpDeliveryCode *deliveryCode, CfdpTransactionId *originatingTransactionId, char *statusReportBuf, MetadataList *filestoreResponses);\nPopulates return value fields with data from the oldest CFDP event not yet delivered to the application. cfdp_get_event() blocks indefinitely until a CFDP processing event is delivered or the function is interrupted by an invocation of cfdp_interrupt().
Return Value * 0: on success -OR- on application error, returns zero but sets errno to EINVAL. * -1: on system failure
"},{"location":"ION-Application-Service-Interface/#cfdp_interrupt","title":"cfdp_interrupt","text":"void cfdp_interrupt()\nInterrupts an cfdp_get_event() invocation. This function is designed to be called from a signal handler.
"},{"location":"ION-Application-Service-Interface/#cfdp_rput","title":"cfdp_rput","text":"int cfdp_rput(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpNumber *beneficiaryEntityNbr, CfdpProxyTask *proxyTask, CfdpTransactionId *transactionId)\nSends to the indicated respondent entity a \"proxy\" request to perform a file transmission. The transmission is to be subject to the configuration values in proxyTask and the destination of the file is to be the entity identified by beneficiaryEntityNbr.
int cfdp_rput_cancel(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *rputTransactionId, CfdpTransactionId *transactionId)\nSends to the indicated respondent entity a request to cancel a prior \"proxy\" file transmission request as identified by rputTransactionId, which is the value of transactionId that was returned by that earlier proxy transmission request.
"},{"location":"ION-Application-Service-Interface/#cfdp_get","title":"cfdp_get","text":"int cfdp_get(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpProxyTask *proxyTask, CfdpTransactionId *transactionId)\nSame as cfdp_rput except that beneficiaryEntityNbr is omitted; the local entity is the implicit beneficiary of the request.
"},{"location":"ION-Application-Service-Interface/#cfdp_rls","title":"cfdp_rls","text":"int cfdp_rls(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpDirListTask *dirListTask, CfdpTransactionId *transactionId)\nSends to the indicated respondent entity a request to prepare a directory listing, save that listing in a file, and send it to the local entity. The request is subject to the configuration values in dirListTask.
int cfdp_preview(CfdpTransactionId *transactionId, uvast offset, unsigned int length, char *buffer);\nThis function enables the application to get an advanced look at the content of a file that CFDP has not yet fully received. Reads length bytes starting at offset bytes from the start of the file that is the destination file of the transaction identified by transactionID, into buffer.
Return Value * number of bytes read: on success * 0: on user error (transaction is nonexistent or is outbound, or offset is beyond the end of file) * -1: on system failure
"},{"location":"ION-Application-Service-Interface/#cfdp_map","title":"cfdp_map","text":"int cfdp_map(CfdpTransactionId *transactionId, unsigned int *extentCount, CfdpExtent *extentsArray);\nThis function enables the application to report on the portions of a partially-received file that have been received and written. Lists the received continuous data extents in the destination file of the transaction identified by transactionID. The extents (offset and length) are returned in the elements of extentsArray; the number of extents returned in the array is the total number of continuous extents received so far, or extentCount, whichever is less.
Return Value * 0: on success, the total number of extents received so far is reported through extentCount * -1: on system failure, returns -1
cfdptest","text":"ION provides application CFDP test program called cfdptest, which installed as part of regular ION build/install process and can be invoked from terminal this way:
cfdptest\nThe shell program present a ':' prompt for interactive mode commanding. You can type 'h' to see a list of available commands.
One can also feed a sequence of commands to cfdptest non-interactively such that you will not see the stdout of the program. This is useful for running automated tests.
cfdptest [file_containing_cfdptest_commands]\nA third way to use cfdptest is to feed command scripts but allows the interactive responses to be displayed in stdout:
cfdptest < [file_containing_cfdptest_commands]\nThe cfdptest.c source code is also provided as a code examples on how write applications using the CFDP APIs. The cfdptest command set can be found in the manual pages here.
this section is work-in-progress
"},{"location":"ION-Application-Service-Interface/#bundle-streaming-service-bss","title":"Bundle Streaming Service (BSS)","text":"The BSS library supports the streaming of data over delay-tolerant networking (DTN) bundles. The intent of the library is to enable applications that pass streaming data received in transmission time order (i.e., without time regressions) to an application-specific \"display\" function -- notionally for immediate real-time display -- but to store all received data (including out-of-order data) in a private database for playback under user control. The reception and real-time display of in-order data is performed by a background thread, leaving the application's main (foreground) thread free to respond to user commands controlling playback or other application-specific functions.
The application-specific \"display\" function invoked by the background thread must conform to the RTBHandler type definition. It must return 0 on success, -1 on any error that should terminate the background thread. Only on return from this function will the background thread proceed to acquire the next BSS payload.
All data acquired by the BSS background thread is written to a BSS database comprising three files: table, list, and data. The name of the database is the root name that is common to the three files, e.g., db3.tbl, db3.lst, db3.dat would be the three files making up the db3 BSS database. All three files of the selected BSS database must reside in the same directory of the file system.
Several replay navigation functions in the BSS library require that the application provide a navigation state structure of type bssNav as defined in the bss.h header file. The application is not reponsible for populating this structure; it's strictly for the private use of the BSS library.
"},{"location":"ION-Application-Service-Interface/#bundle-streaming-service-bss-bundle-streaming-service-protocol-bssp-cla","title":"Bundle Streaming Service (BSS) & Bundle Streaming Service Protocol (BSSP CLA)","text":"The Bundle Streaming Service (BSS) and the Bundle Streaming Service Protocol (BSSP) CLA are independent modules.
The BSSP CLA is designed to emulate a connection between two DTN neighboring nodes characterized by two delivery mechanisms: (a) a minimal delay, unreliable channel (physical or logical), and (b) a potentially delayed, but reliable channel. The minimal delay channel is emulated by transpot UDP (with a timer mechanism added) and the reliable channel is emulated via TCP transport.
A DTN user mission may decide to use a single CCSDS AOS or TM downlink with LTP CLA running on top as its reliability mechanism. In that case, it can directly use the LTP CLA in ION and interface it with the CCSDS framing protocol which could be implemented by the mission's avionic system or the radio.
However, it is also possible that a mission may utilize different types of transports, for example, using multiple downlinks via S, X, Ka-band or optical, each with different reliability mechanism (or not). Alternatively, a flight system may also use commercial communications services with differentiated delays and levels of reliability. In such case, BSSP can be used to approximate such configuration in a lab environment for prototyping and testing the impact on streaming data delivery, until the actual CLAs are implemented and tested.
The Bundle Streaming Service, on the other hand, is an application-level service that can be used with any underlying CLAs to handle both realtime and delayed, in-order playback of streaming data including video, audio, and telemetry. When the user scenario is appropriate, BSS can certainly be used over BSSP CLA, but that is not a requirement.
"},{"location":"ION-Application-Service-Interface/#bss-apis","title":"BSS APIs","text":"The following section describes the BSS library APIs.
"},{"location":"ION-Application-Service-Interface/#bssopen","title":"bssOpen","text":"int bssOpen(char *bssName, char *path, char *eid)\nint bssStart(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)\nStarts a BSS data acquisition background thread. bssName identifies the BSS database into which data will be acquired. path identifies the directory in which that database resides. eid is used to open the BP endpoint at which the delivered BSS bundle payload contents will be acquired. buffer identifies a data acquisition buffer, which must be provided by the application, and bufLen indicates the length of that buffer; received bundle payloads in excess of this length will be discarded.
handler identifies the display function to which each in-order bundle payload will be passed. The time and count parameters passed to this function identify the received bundle, indicating the bundle's creation timestamp time (in seconds) and counter value. The buffer and bufLength parameters indicate the location into which the bundle's payload was acquired and the length of the acquired payload. handler must return -1 on any unrecoverable system error, 0 otherwise. A return value of -1 from handler will terminate the BSS data acquisition background thread.
On any failure, returns -1. On success, returns zero.
"},{"location":"ION-Application-Service-Interface/#bssrun","title":"bssRun","text":"int bssRun(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)\nA convenience function that performs both bssOpen() and bssStart(). On any failure, returns -1. On success, returns zero.
"},{"location":"ION-Application-Service-Interface/#bssclose","title":"bssClose","text":"void bssClose()\nvoid bssStop()\nTerminates the most recently initiated BSS data acquisition background thread.
"},{"location":"ION-Application-Service-Interface/#bssexit","title":"bssExit","text":"void bssExit()\nA convenience function that performs both bssClose() and bssStop().
"},{"location":"ION-Application-Service-Interface/#bssread","title":"bssRead","text":"long bssRead(bssNav nav, char *data, int dataLen)\nCopies the data at the current playback position in the database, as indicated by nav, into data; if the length of the data is in excess of dataLen then an error condition is asserted (i.e., -1 is returned). Note that bssRead() cannot be successfully called until nav has been populated, nominally by a preceding call to bssSeek(), bssNext(), or bssPrev(). Returns the length of data read, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssseek","title":"bssSeek","text":"long bssSeek(bssNav *nav, time_t time, time_t *curTime, unsigned long *count)\nSets the current playback position in the database, in nav, to the data received in the bundle with the earliest creation time that was greater than or equal to time. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssseek_read","title":"bssSeek_read","text":"long bssSeek_read(bssNav *nav, time_t time, time_t *curTime, unsigned long *count, char *data, int dataLen)\nA convenience function that performs bssSeek() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssnext","title":"bssNext","text":"long bssNext(bssNav *nav, time_t *curTime, unsigned long *count)\nSets the playback position in the database, in nav, to the data received in the bundle with the earliest creation time and ID count greater than that of the bundle at the current playback position. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location (if any), -2 on reaching end of list, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssnext_read","title":"bssNext_read","text":"long bssNext_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)\nA convenience function that performs bssNext() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, -2 on reaching end of list, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssprev","title":"bssPrev","text":"long bssPrev(bssNav *nav, time_t *curTime, unsigned long *count)\nSets the playback position in the database, in nav, to the data received in the bundle with the latest creation time and ID count earlier than that of the bundle at the current playback position. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location (if any), -2 on reaching end of list, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssprev_read","title":"bssPrev_read","text":"long bssPrev_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)\nA convenience function that performs bssPrev() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, -2 on reaching end of list, or -1 on any error
"},{"location":"ION-Application-Service-Interface/#asynchronous-messaging-service-ams-apis","title":"Asynchronous Messaging Service (AMS) APIs","text":"This section is under construction.
"},{"location":"ION-Application-Service-Interface/#delay-tolerant-payload-conditioning-dtpc-communications-library","title":"Delay-Tolerant Payload Conditioning (DTPC) communications library","text":""},{"location":"ION-Application-Service-Interface/#description","title":"Description","text":"The dtpc library provides functions enabling application software to use Delay-Tolerant Payload Conditioning (DTPC) when exchanging information over a delay-tolerant network. DTPC is an application service protocol, running in a layer immediately above Bundle Protocol, that offers delay-tolerant support for several end-to-end services to applications that may require them. These services include delivery of application data items in transmission (rather than reception) order; detection of reception gaps in the sequence of transmitted application data items, with end-to-end negative acknowledgment of the missing data; end-to-end positive acknowledgment of successfully received data; end-to-end retransmission of missing data, driven either by negative acknowledgment or timer expiration; suppression of duplicate application data items; aggregation of small application data items into large bundle payloads, to reduce bundle protocol overhead; and application-controlled elision of redundant data items in aggregated payloads, to improve link utiliization.
"},{"location":"ION-Application-Service-Interface/#dtpc-apis","title":"DTPC APIs","text":"int dptc_attach( )\nvoid dptc_detach( )\nTerminates all access to DTPC functionality on the local computer.
int dtpc_entity_is_started( )\nint dtpc_open(unsigned int topicID, DtpcElisionFn elisionFn, DtpcSAP *dtpcsapPtr)\nEstablishes the application as the sole authorized client for posting and receiving application data items on topic topicID within the local BP node. On success, the service access point for posting and receiving such data items is placed in *dtpcsapPtr, the elision callback function elisionFn (if not NULL) is associated with this topic, and 0 is returned. Returns -1 on any error.
int dtpc_send(unsigned int profileID, DtpcSAP sap, char *destEid, unsigned int maxRtx, unsigned int aggrSizeLimit, unsigned int aggrTimeLimit, int lifespan, BpAncillaryData *ancillaryData, unsigned char srrFlags, BpCustodySwitch custodySwitch, char *reportToEid, int classOfService, Object item, unsigned int length)\nTransmission of that outbound ADU will be subject to the profile identified by profileID, as asserted by dtpcadmin(1), if profileID is non-zero. In that case, maxRtx, aggrSizeLimit, aggrTimeLimit, lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService are ignored.
If profileID is zero then the profile asserted by dtpcadmin(1) that matches maxRtx, aggrSizeLimit, aggrTimeLimit, lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService will govern transmission of the ADU, unless no such profile has been asserted, in which case dtpc_send() returns 0 indicating user error.
maxRtx is the maximum number of times any single DTPC ADU transmitted subject to the indicated profile may be retransmitted by the DTPC entity. If maxRtx is zero, then the DTPC transport service features (in-order delivery, end-to-end acknowledgment, etc.) are disabled for this profile.
aggrSizeLimit is the size threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrSizeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
aggrTimeLimit is the time threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrTimeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService are as defined for bp_send (see bp(3)).
item must be an object allocated within ION's SDR \"heap\", and length must be the length of that object. The item will be inserted into the outbound ADU's list of data items posted for the topic associated with sap, and the elision callback function declared for sap (if any, and if the applicable profile does not disable transmission optimization features) will be invoked immediately after insertion of the application data item but before DTPC makes any decision on whether or not to initiate transmission of the outbound ADU.
The function returns 1 on success, 0 on any user application error, -1 on any system error.
int dtpc_receive(DtpcSAP sap, DtpcDelivery *dlvBuffer, int timeoutSeconds)\nThe \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one application data item on the topic associated with sap has not yet been delivered to the SAP, then the payload of the oldest such item will be returned in dlvBuffer-__item_ and dlvBuffer-__result_ will be set to PayloadPresent. If there is no such item, dtpc_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is DTPC_POLL (i.e., zero) and no application data item is awaiting delivery, or if timeoutSeconds is greater than zero but no item arrives before timeoutSeconds have elapsed, then dlvBuffer-__result_ will be set to ReceptionTimedOut. If timeoutSeconds is DTPC_BLOCKING (i.e., -1) then bp_receive() blocks until either an item arrives or the function is interrupted by an invocation of dtpc_interrupt().
dlvBuffer-__result_ will be set to ReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer-__result_ will be set to DtpcServiceStopped in the event that DTPC service has been terminated on the local node.
The application data item delivered in the DTPC delivery structure, if any, will be an object allocated within ION's SDR \"heap\"; the length of that object will likewise be provided in the DtpcDelivery structure.
Be sure to call dtpc_release_delivery() after every successful invocation of dtpc_receive().
The function returns 0 on success, -1 on any error.
void dtpc_interrupt(DtpcSAP sap)\nvoid dtpc_release_delivery(DtpcDelivery *dlvBuffer)\nvoid dtpc_close(DtpcSAP sap)\nThe following coding guidelines apply to all software delivered as part of the Interplanetary Overlay Network (ION) distribution, except:
Every process should return an exit code on termination. * On normal termination, the exit code should be 0. * On abnormal or error termination, the exit code should be a non-zero number in the range 1-255. * In this case the code should be 1 unless specific codes are used to distinguish between different kinds of errors.
"},{"location":"ION-Coding-Guide/#function-design-guidelines","title":"Function Design Guidelines","text":"All file I/O should be performed using POSIX functions rather than the buffered I/O functions fopen, fread, fseek, etc. This is because buffered I/O entails the dynamic allocation of system memory, which some missions may prohibit in flight software.
The iputs function provided in platform.c should be used in place of fputs, and the igets function should be used in place of fgets. Rather than fscanf, use igets and sscanf; rather than fprintf, use isprintf and iputs.
All varargs-based string composition should be performed using isprintf rather than sprintf, to minimize the chance of overrunning string composition buffers. (isprintf is similar to snprintf. Since VxWorks 5.4 does not support snprintf, isnprintf is included in platform.c.)
Similarly, all string copying should be performed using istrcpy rather than strcpy, strncpy, and strcat.
The isignal function should be used instead of signal; it ensures that reception of a signal will always interrupt system calls in SVR4 fashion even when running on a FreeBSD platform.
The iblock function provides a simple, portable means of preventing reception of the indicated signal by the calling thread.
Data objects larger than 1024 bytes should not be declared in stack space. This is to * Minimize complaints by Coverity, and * Minimize the chance of overrunning allocated stack space when running on a VxWorks platform.
Static variables that must be made globally accessible should be declared within external functions, rather than declared as external variables. This is per the JPL C Coding Standard, but it also has the useful property of providing an easy way to track all access to a global static variable in gdb: you just set a breakpoint at the start of the function in which the variable is declared.
In the implementation of any ION library function or any ION task\u2019s top-level driver function, any condition that prevents the function from continuing execution toward producing the effect it is designed to produce is considered an \u201cerror\u201d.
Detection of an error should result in the printing of an error message and, normally, the immediate return of whatever return value is used to indicate the failure of the function in which the error was detected.
By convention this value is usually -1, but both zero and NULL are appropriate failure indications under some circumstances such as object creation.
The CHKERR, CHKZERO, CHKNULL, and CHKVOID macros are used to implement this behavior in a standard and lexically terse manner. Use of these macros offers an additional feature: for debugging purposes, they can easily be configured to call sm_Abort() to terminate immediately with a core dump instead of returning a error indication. This option is enabled by setting the compiler parameter CORE_FILE_NEEDED to 1 at compilation time.
In the absence of any error, the function returns a value that indicates nominal completion. By convention this value is usually zero, but under some circumstances other values (such as pointers or addresses) are appropriate indications of nominal completion. Any additional information produced by the function, such as an indication of \u201csuccess\u201d, is usually returned as the value of a reference argument.
However, database management functions and the SDR hash table management functions deviate from this rule: most return 0 to indicate nominal completion but functional failure (e.g., duplicate key or object not found) and return 1 to indicate functional success.
Whenever returning a value that indicates an error: * If the failure is due to the failure of a system call or some other non-ION function, assu=me that errno has already been set by the function at the lowest layer of the call stack; use putSysErrmsg (or postSysErrmsg if in a hurry) as described below. * Otherwise \u2013 i.e., the failure is due to a condition that was detected within ION \u2013use putErrmsg (or postErrmg if pressed for time) as described below; this will aid in tracing the failure through the function stack in which the failure was detected.
When a failure in a called function is reported to \u201cdriver\u201d code in an application program, before continuing or exiting use writeErrmsgMemos() to empty the message pool and print a simple stack trace identifying the failure.
Calling code may choose to ignore the error indication returned by a function (e.g., when an error returned by an sdr function is subsumed by a future check of the error code returned by sdr_end_xn). To do so without incurring the wrath of a static analysis tool, pass the entire function call as the sole argument to the oK macro; the macro operates on the return code, casting it to (void) and thus placating static analysis.
To write a simple status message, use writeMemo. To write a status message and annotate that message with some other context-dependent string, use writeMemoNote. (The itoa and utoa functions may be used to express signed and unsigned integer values, respectively, as strings for this purpose.) Note that adhering to ION\u2019s conventions for tagging status messages will simplify any automated status message processing that the messages might be delivered to, i.e., the first four characters of the status message should be as follows:
To write a simple diagnostic message, use putErrmsg; the source file name and line number will automatically be inserted into the message text, and a context-dependent string may be provided. (Again the itoa and utoa functions may be helpful here.) The diagnostic message should normally begin with a capital letter and end with a period.
To write a diagnostic message in response to the failure of a system call or some other non-ION function that sets errno, use putSysErrmsg instead. In this case, the diagnostic message should normally begin with a capital letter and not end with a period.
This page contains guidelines for programming in the C language.
"},{"location":"ION-Coding-Guide/#naming-conventions","title":"Naming Conventions","text":"Names of global variables, local variables, structure fields, and function arguments are in mixed upper and lower case, without embedded underscores, and beginning with a lowercase letter.
int numItems;\nvoid computeSomething(int firstArg, int secondArg);\n extern int ltp_open(unsigned long clientId);\n#define SYMBOLIC_CONSTANT 5\nUnions are not used.
Typedef names are in mixed upper and lower case, with the first token capitalized. Type names are never the same as the structure or enum tags for the structures and enums that they name.
typedef struct gloplist_str\n{\nint thing1;\nint thing2;\n} GlopList;\nNo line of source text is ever more than 80 characters long. When the length of a line of code exceeds 80 characters, the line of code is wrapped across two or more lines of text. Whenever the point at which the text must be wrapped is within a literal, a newline character () is inserted at the wrap point and the continuation of the literal begins in the first column of the next text line. Otherwise, each continuation line is normally indented two tab stops from the first text line of the long line of code; when indenting just one tab stop (rather than two) seems to make the code more readable, indenting one tab stop is okay. When a single meaningful clause of a source code line must be wrapped across multiple lines of text, each text line after the first line in that clause is normally indented one additional tab stop.
In the declaration of a function or variable, the type name and function/variable name are normally separated by a single tab. They may be separated by multiple tabs when this is necessary in order to have the variable names in multiple consecutive variable declarations line up, which is always preferred.
Functions are written with the return type, function name, and arguments as a single line of code, subject to the code line wrapping guidelines given above. The opening brace of the function definition appears in the first column of the next line.
The opening brace of a structure definition likewise appears in the first column of the next line after the structure name.
A control statement (starting with if, else, while, or switch) begins a new line of code. The opening brace for the control statement always appears on the next line, at the same indentation as the control statement keyword.
The first line of code appearing after an opening brace (whether for a structure definition, for a function definition, or in the scope of a control statement) always appears on the next line, indented one tab stop. From that point on, every subsequent line of code is indented the same number of tabs as the preceding line of code, subject to the code line wrapping guidelines given above.
Every closing brace always appears in the same column as the corresponding opening brace.
Every closing brace is always followed by a single blank line, except when it is immediately followed either by another closing brace (which will be indented one less tab stop) or by an else (which will be indented by the same number of tab stops as the closing brace and, therefore, the corresponding if).
static void computeSomething(int numItems, Item *items)\n{\n unsigned int x;\n int i;\n\n while (x > 0)\n {\n x--;\n }\n\n for (i = 0; i < numItems; i++)\n {\n x += items[i].field1;\n }\n\n if (numItems == 0)\n {\n doThis();\n }\n else\n {\n doThat();\n }\n}\nThe case labels in switch statements line up with the braces. Every case (or default) label in the switch, after the first case, is preceded by a blank line. Cases which do not include a break or return statement either contain no code at all or else end with a comment along the lines of:
/* Intentional fall-through to next case. */\nFor example:\nswitch (ch)\n{\ncase 'A':\n.\n.\n.\nbreak;\n\ncase 'B':\ncase 'C':\n.\n.\n.\nbreak;\n\ncase 'D':\n.\n.\n.\n/* Intentionally falls through. */\n\ncase 'E':\n.\n.\n.\nbreak;\n\ndefault:\n.\n.\n.\nbreak;\n}\nComments are so rare and valuable that we hesitate to risk discouraging them by overly constraining their format. In general, comments should be inserted in such a way as to be as easy as possible to read in relevant context. The multi-line comment formatting performed automatically by vim is particularly acceptable.
/* Here is the beginning of an extremely long comment, so long\n * that it has to wrap over two lines of source code text. */\nUse \u2013 and write \u2013 thread-safe library functions where possible. E.g., normally prefer strtok_r() to strtok().
Avoid writing non-portable code, e.g., prefer POSIX library calls to OS-specific library calls.
Template for \".c\" files
1 2 3 4 5 6 7 \n123456789012345678901234567890123456789012345678901234567890123456789012\n/*\n platform_sm.c: platform-dependent implementation of common\n functions, to simplify porting.\n\n Author: Alan Schlutsmeyer, JPL\n\n Copyright 1997, California Institute of Technology.\n ALL RIGHTS RESERVED. U.S. Government sponsorship\n acknowledged.\n */\nEach file should have a header comment like the one shown above.
#include <stdio.h>\n#include <locallib.h>\n#include \"appheader.h\"\n .\n .\n .\n.h files are included just after the header. System-provided headers should be specified with angle brackets; ION-provided headers should be specified with double-quotes.
#define SYMBOLIC_CONSTANT 5\nNext, symbolic constants and macros (if any) are defined. They normally go first, because they might be used in the definitions of data types and static variables. However, symbolic constants and macros may be inserted later in the source text if that will improve the readability of the file.
typedef struct fb_str\n{\n int field1;\n in field2;\n} Foobar;\nData types are defined next because they might be used by static variables.
static int numFoobars = 0; /* Number of foobars in the program. */\n .\n .\n .\nGlobal functions used only within the program should be declared static. Public function prototypes should be in a header file; the definitions of those functions, with their headers, are included in the corresponding .c file. Low-level functions, such as commonly-used utility functions, appear first in the .c file. They are followed by the functions that call those functions directly, followed by higher-level-functions that call those functions, and so on.
Template for \".h\" Files
1 2 3 4 5 6 7 \n123456789012345678901234567890123456789012345678901234567890123456789012\n/*\n platform_sm.h: portable definitions of types and functions.\n\n Author: Alan Schlutsmeyer, JPL\n\n Copyright 1997, California Institute of Technology.\n ALL RIGHTS RESERVED. U.S. Government sponsorship\n acknowledged.\n */\nEach header file begins with a standard header comment like the one shown above.
#ifndef _PLATFORM_SM_H_\n#define _PLATFORM_SM_H_\nEach header file must have an \"include\" guard.
#include \"platform.h\"\n .\n .\n .\n#ifdef __cplusplus\nextern \"C\" {\n#endif\nNext come declarations of various sorts, followed by the ends of the C++ and \u201cinclude\u201d guards.
#ifdef __cplusplus\n}\n#endif\n\n#endif\nNothing should go after the \"#endif\" of the include guard.
"},{"location":"ION-Config-File-Templates/","title":"Available Configuration File Templates","text":"The following configurations can be downloaded (see file attachment)
These configuration files are provided to give you a basic functional setup; they may not be sufficient to support all features and throughput performance you want to achieve for your network. So please use them as a template and apply update as necessary.
"},{"location":"ION-Deployment-Guide/","title":"ION Deployment Guide","text":"Version 4.1.3
Jay Gao, Jet Propulsion Laboratory, California Institute of Technology
Sky DeBaun, Jet Propulsion Laboratory, California Institute of Technology
Document Change Log
Ver No. Date Description Note V4.1.3 11/6/2023 Add LTP Performance Test Converted to markd down V4.1.2 1/5/2023 Added notes on SDR file and CGRM"},{"location":"ION-Deployment-Guide/#overview","title":"Overview","text":"The effort required to deploy the Interplanetary Overlay Network (ION) software in an operational setting may vary widely depending on the scope of the deployment and the degree to which the required ION functionality coincides with the capability provided by default in the software as distributed. This effort will be expended in two general phases: initial infusion and ongoing operation.
"},{"location":"ION-Deployment-Guide/#infusion","title":"Infusion","text":"Even in the best case, some minimal degree of configuration will be required. Many elements of ION behavior are managed at run time by decisions recorded in ION's protocol state databases, as populated by a variety of administration utility programs. Others are managed at compile time by means of compiler command-line switches selected when the software is built. These compile-time configuration options are described in the Configuration section below.
In some cases, mission-specific behavior that goes beyond the options built into ION must be enabled during ION deployment. The intent of the ION design is to minimize -- to eliminate, if possible -- any need to modify ION source code in order to enable mission-specific behavior. Two general strategies are adopted for this purpose.
First, ION includes a number of conditionally defined functions that can be cleanly replaced with mission-specific alternative source code by setting a compiler command-line switch at build time. Setting such a switch causes the mission-specific source code, written in C, to be simply included within the standard ION source code at the time of compilation.
Second, more generally it is always possible to add new application executables, new startup/shutdown/monitor/control utilities or scripts, and even entirely new route computation systems, BP convergence-layer adapters, and/or LTP link service adapters without ever altering the distributed ION source code. A few rough guidelines for making these kinds of modifications are described in the Adaptation section below.
Finally, in rare cases it may be necessary to execute ION in an operating-system environment to which it has not yet been ported. Guidance for porting ION to new platforms will be provided in a future edition of this Deployment Guide.
"},{"location":"ION-Deployment-Guide/#operation","title":"Operation","text":"On an ongoing basis, an ION deployment may require reconfiguration from time to time and/or may require troubleshooting to resolve performance or stability problems. Some suggestions for reconfiguration and troubleshooting procedures are offered in the Operation section below.
"},{"location":"ION-Deployment-Guide/#configuration","title":"Configuration","text":""},{"location":"ION-Deployment-Guide/#configuring-the-ici-module","title":"Configuring the \"ici\" module","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DFSWSOURCE or --DSM_SEMBASEKEY=0xff13), will alter the functionality of ION as noted below.
PRIVATE_SYMTAB
This option causes ION to be built for VxWorks 5.4 or RTEMS with reliance on a small private local symbol table that is accessed by means of a function named sm_FindFunction. Both the table and the function definition are, by default, provided by the symtab.c source file, which is automatically included within the platform_sm.c source when this option is set. The table provides the address of the top-level function to be executed when a task for the indicated symbol (name) is to be spawned, together with the priority at which that task is to execute and the amount of stack space to be allocated to that task.
PRIVATE_SYMTAB is defined by default for RTEMS but not for VxWorks 5.4.
Absent this option, ION on VxWorks 5.4 must successfully execute the VxWorks symFindByName function in order to spawn a new task. For this purpose the entire VxWorks symbol table for the compiled image must be included in the image, and task priority and stack space allocation must be explicitly specified when tasks are spawned.
FSWLOGGER
This option causes the standard ION logging function, which simply writes all ION status messages to a file named ion.log in the current working directory, to be replaced (by #include) with code in the source file fswlogger.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
FSWCLOCK
This option causes the invocation of the standard time function within getUTCTime (in ion.c) to be replaced (by #include) with code in the source file fswutc.c, which might for example invoke a mission-specific function to read a value from the spacecraft clock. A file of this name must be in the inclusion path for the compiler.
FSWWDNAME
This option causes the invocation of the standard getcwd function within cfdpInit (in libcfdpP.c) to be replaced (by #include) with code in the source file wdname.c, which must in some way cause the mission-specific value of current working directory name to be copied into cfdpdbBuf.workingDirectoryName. A file of this name must be in the inclusion path for the compiler.
FSWSYMTAB
If the PRIVATE_SYMTAB option is also set, then the FSWSYMTAB option causes the code in source file mysymtab.c to be included in platform_sm.c in place of the default symbol table access implementation in symtab.c. A file named mysymtab.c must be in the inclusion path for the compiler.
FSWSOURCE
This option simply causes FSWLOGGER, FSWCLOCK, FSWWDNAME, and FSWSYMTAB all to be set.
GDSLOGGER
This option causes the standard ION logging function, which simply writes all ION status messages to a file named ion.log in the current working directory, to be replaced (by #include) with code in the source file gdslogger.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
GDSSOURCE
This option simply causes GDSLOGGER to be set.
TRACKRFXEVENTS
This option causes user-written code, in a file named rfxtracker.c, to be executed every time the rfxclock daemon dispatches a schedule RFX event such as the start or end of a transmission contact. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
ION_OPS_ALLOC=*xx*
This option specifies the percentage of the total non-volatile storage space allocated to ION that is reserved for protocol operational state information, i.e., is not available for the storage of bundles or LTP segments. The default value is 40.
ION_SDR_MARGIN=*xx*
This option specifies the percentage of the total non-volatile storage space allocated to ION that is reserved simply as margin, for contingency use. The default value is 20.
The sum of ION_OPS_ALLOC and ION_SDR_MARGIN defines the amount of non-volatile storage space that is sequestered at the time ION operations are initiated: for purposes of congestion forecasting and prevention of resource oversubscription, this sum is subtracted from the total size of the SDR \"heap\" to determine the maximum volume of space available for bundles and LTP segments. Data reception and origination activities fail whenever they would cause the total amount of data store space occupied by bundles and segments to exceed this limit.
HEAP_PTRS
This is an optimization option for the SDR non-volatile data management system: when set, it enables the value of any variable in the SDR heap to be accessed directly by means of a pointer into the dynamic memory that is used as the data store storage medium, rather than by reading the variable into a location in local stack memory. Note that this option must not be enabled if the data store is configured for file storage only, i.e., if the SDR_IN_DRAM flag was set to zero at the time the data store was created by calling sdr_load_profile. See the ionconfig(5) man page in Appendix A for more information.
NO_SDR_TRACE
This option causes non-volatile storage utilization tracing functions to be omitted from ION when the SDR system is built. It disables a useful debugging option but reduces the size of the executable software.
NO_PSM_TRACE
This option causes memory utilization tracing functions to be omitted from ION when the PSM system is built. It disables a useful debugging option but reduces the size of the executable software.
IN_FLIGHT
This option controls the behavior of ION when an unrecoverable error is encountered.
If it is set, then when an unrecoverable error is encountered the status message \"Unrecoverable SDR error\" is logged and the SDR non-volatile storage management system is globally disabled: the current data store access transaction is ended and (provided transaction reversibility is enabled) rolled back, and all ION tasks terminate.
Otherwise, the ION task that encountered the error is simply aborted, causing a core dump to be produced to support debugging.
SM_SEMKEY=0x*XXXX*
This option overrides the default value (0xee01) of the identifying \"key\" used in creating and locating the global ION shared-memory system mutex.
SVR4_SHM
This option causes ION to be built using svr4 shared memory as the pervasive shared-memory management mechanism. svr4 shared memory is selected by default when ION is built for any platform other than MinGW (for which File Mapping objects are used), VxWorks 5.4, or RTEMS. (For the latter two operating systems all memory is shared anyway, due to the absence of a protected-memory mode.)
POSIX1B_SEMAPHORES
This option causes ION to be built using POSIX semaphores as the pervasive semaphore mechanism. POSIX semaphores are selected by default when ION is built for RTEMS but are otherwise not used or supported; this option enables the default to be overridden.
SVR4_SEMAPHORES
This option causes ION to be built using svr4 semaphores as the pervasive semaphore mechanism. svr4 semaphores are selected by default when ION is built for any platform other than MinGW (for which Windows event objects are used), VxWorks 5.4 (for which VxWorks native semaphores are the default choice), or RTEMS (for which POSIX semaphores are the default choice).
SM_SEMBASEKEY=0x*XXXX*
This option overrides the default value (0xee02) of the identifying \"key\" used in creating and locating the global ION shared-memory semaphore database, in the event that svr4 semaphores are used.
SEMMNI=*xxx*
This option declares to ION the total number of svr4 semaphore sets provided by the operating system, in the event that svr4 semaphores are used. It overrides the default value, which is 128. (Changing this value typically entails rebuilding the O/S kernel.)
SEMMSL=*xxx*
This option declares to ION the maximum number of semaphores in each svr4 semaphore set, in the event that svr4 semaphores are used. It overrides the default value, which is 250. (Changing this value typically entails rebuilding the O/S kernel.)
SEMMNS=*xxx*
This option declares to ION the total number of svr4 semaphores that the operating system can support; the maximum possible value is SEMMNI x SEMMSL. It overrides the default value, which is 32000. (Changing this value typically entails rebuilding the O/S kernel.)
Note that this option is also supported in the MinGW (Windows) port of ION, with the same default value; changing this value does not involve an operating system modification.
ION_NO_DNS
This option causes the implementation of a number of Internet socket I/O operations to be omitted for ION. This prevents ION software from being able to operate over Internet connections, but it prevents link errors when ION is loaded on a spacecraft where the operating system does not include support for these functions.
ERRMSGS_BUFSIZE=*xxxx*
This option set the size of the buffer in which ION status messages are constructed prior to logging. The default value is 4 KB.
SPACE_ORDER=*x*
This option declares the word size of the computer on which the compiled ION software will be running: it is the base-2 log of the number of bytes in an address. The default value is 2, i.e., the size of an address is 2^2^ = 4 bytes. For a 64-bit machine, SPACE_ORDER must be declared to be 3, i.e., the size of an address is 2^3^ = 8 bytes.
NO_SDRMGT
This option enables the SDR system to be used as a data access transaction system only, without doing any dynamic management of non-volatile data. With the NO_SDRMGT option set, the SDR system library can (and in fact must) be built from the sdrxn.c source file alone.
DOS_PATH_DELIMITER
This option causes ION_PATH_DELIMITER to be set to '\\' (backslash), for use in the construction of path names. The default value of ION_PATH_DELIMITER is '/' (forward slash, as is used in Unix-like operating systems).
"},{"location":"ION-Deployment-Guide/#configuring-the-ltp-module","title":"Configuring the \"ltp\" module","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DUDP_MULTISEND, will alter the functionality of LTP as noted below.
UDP_MULTISEND
The UDP_MULTISEND option can improve LTP performance by sharply reducing system call overhead: multiple LTP segments encapsulated in UDP datagrams may be transmitted with a single sendmmsg() call rather than multiple sendmsg() calls. This reduces the cost of sending LTP blocks in small segments, which in turn can limit IP fragmentation for LTP traffic.
Note that sendmmsg() has no built-in rate control and offers no opportunity to exercise the rate control algorithm that minimizes UDP congestion loss in non-MULTISEND LTP. In order to achieve similar reduction in UDP congestion loss, a node that receives data sent by sendmmsg() may need to be configured for larger socket buffers. The sysctl operating system utility may be used for this purpose, setting new values for net.core.rmem_max and _default and net.core.wmem_max and _default.
Note also that not all operating systems support the sendmmsg() system call. ION currently enables UDP_MULTISEND only for flavors of Linux other than bionic.
MULTISEND_SEGMENT_SIZE
By default, ION LTP in UDP_MULTISEND mode will always limit LTP segment size to 1450 so that every segment may be encapsulated in an IP packet whose size does not exceed the standard Ethernet frame size. For networks in which the MTU is known to be larger, this parameter may be overridden at compile time.
MULTISEND_BATCH_LIMIT
By default, the maximum number of UDP datagrams that ION LTP in UDP_MULTISEND mode will send in a single sendmmsg() call is automatically computed as the block aggregation size threshold divided by the maximum segment size; that is, normally the amount of data sent per sendmmsg() call is about one LTP block. This parameter may be overridden at compile time.
MULTIRECV_BUFFER_COUNT
In UDP_MULTISEND mode, ION LTP will also use recvmmsg() to receive multiple LTP segments (encapsulated in UDP datagrams) in a single system call. By default, 127 segment reception buffers (each one large enough to receive a single LTP segment of maximum size) are reserved for this purpose. This parameter may be overridden at compile time.
"},{"location":"ION-Deployment-Guide/#configuring-the-bp-module","title":"Configuring the \"bp\" module","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DION_NOSTATS or --DBRSTERM=60), will alter the functionality of BP as noted below.
TargetFFS
Setting this option adapts BP for use with the TargetFFS flash file system on the VxWorks operating system. TargetFFS apparently locks one or more system semaphores so long as a file is kept open. When a BP task keeps a file open for a sustained interval, subsequent file system access may cause a high-priority non-BP task to attempt to lock the affected semaphore and therefore block; in this event, the priority of the BP task may automatically be elevated by the inversion safety mechanisms of VxWorks. This \"priority inheritance\" can result in preferential scheduling for the BP task -- which does not need it -- at the expense of normally higher-priority tasks, and can thereby introduce runtime anomalies. BP tasks should therefore close files immediately after each access when running on a VxWorks platform that uses the TargetFFS flash file system. The TargetFFS compile-time option ensures that they do so.
MULTIDUCTS
It is possible for multiple outducts to be attached to a single egress plan, enabling some bundles to be forwarded to a neighboring node using one outduct while others are forwarded using another. Selection of the outduct to use for the forwarding of a given bundle is a function of the bpclm \"convergence-layer manager\" daemon; each of a given node's egress plans is managed by a single bpclm task. The default outduct selection algorithm exercised by bpclm can be overridden by means of the MULTIDUCTS compile-time configuration option. Setting the -DMULTIDUCTS switch causes the standard outduct configuration logic in the outductSelected() function of bpclm.c to be replaced (by #include) with code in the source file named selectcla.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
The implementation of outductSelected() in ION bpv7 implementation differs somewhat from that in the bpv6 implementation. The content of a very simple selectcla.c file for a node deploying bpv7 might look like this:
if (bundle-\\>destination.ssp.ipn.serviceNbr == 99)\n{\n if (strcmp(protocol-\\>name, \"bssp\") == 0)\n {\n return 1; /\\* Use a BSSP outduct for this bundle. \\*/\n }\n}\nNote that any element of the state of the bundle may be used to select an outduct based on any element of the state of the outduct. The intent is for ION to be able to accommodate virtually any mission-defined algorithm for selecting among communication channels between topologically adjacent BP nodes.
BRSTERM=*xx*
This option sets the maximum number of seconds by which the current time at the BRS server may exceed the time tag in a BRS authentication message from a client; if this interval is exceeded, the authentication message is presumed to be a replay attack and is rejected. Small values of BRSTERM are safer than large ones, but they require that clocks be more closely synchronized. The default value is 5.
ION_NOSTATS
Setting this option prevents the logging of bundle processing statistics in status messages.
KEEPALIVE_PERIOD=*xx*
This option sets the number of seconds between transmission of keep-alive messages over any TCP or BRS convergence-layer protocol connection. The default value is 15.
ION_BANDWIDTH_RESERVED
Setting this option overrides strict priority order in bundle transmission, which is the default. Instead, bandwidth is shared between the priority-1 and priority-0 queues on a 2:1 ratio whenever there is no priority-2 traffic.
"},{"location":"ION-Deployment-Guide/#configuring-the-ams-module","title":"Configuring the \"ams\" module","text":"Defining the following macros, by setting parameters that are provided to the C compiler (for example, -DNOEXPAT or --DAMS_INDUSTRIAL), will alter the functionality of AMS as noted below.
NOEXPAT
Setting this option adapts AMS to expect MIB information to be presented to it in \"amsrc\" syntax (see the amsrc(5) man page) rather than in XML syntax (as described in the amsxml(5) man page), normally because the expat XML interpretation system is not installed. Note that the default syntax for AMS MIB information is now amsrc syntax so the -DNOEXPAT switch is rarely needed.
AMS_INDUSTRIAL
Setting this option adapts AMS to an \"industrial\" rather than safety-critical model for memory management. By default, the memory acquired for message transmission and reception buffers in AMS is allocated from limited ION working memory, which is fixed at ION start-up time; this limits the rate at which AMS messages may be originated and acquired. When --DAMS_INDUSTRIAL is set at compile time, the memory acquired for message transmission and reception buffers in AMS is allocated from system memory, using the familiar malloc() and free() functions; this enables much higher message traffic rates on machines with abundant system memory where flight software constraints on dynamic system memory allocation are not applicable.
"},{"location":"ION-Deployment-Guide/#configuring-the-cfdp-module","title":"Configuring the \"cfdp\" module","text":"Defining the following macro, by setting a parameter that is provided to the C compiler (i.e., --DTargetFFS), will alter the functionality of CFDP as noted below.
TargetFFS
Setting this option adapts CFDP for use with the TargetFFS flash file system on the VxWorks operating system. TargetFFS apparently locks one or more system semaphores so long as a file is kept open. When a CFDP task keeps a file open for a sustained interval, subsequent file system access may cause a high-priority non-CFDP task to attempt to lock the affected semaphore and therefore block; in this event, the priority of the CFDP task may automatically be elevated by the inversion safety mechanisms of VxWorks. This \"priority inheritance\" can result in preferential scheduling for the CFDP task -- which does not need it -- at the expense of normally higher-priority tasks, and can thereby introduce runtime anomalies. CFDP tasks should therefore close files immediately after each access when running on a VxWorks platform that uses the TargetFFS flash file system. The TargetFFS compile-time option assures that they do so.
"},{"location":"ION-Deployment-Guide/#initialization","title":"Initialization","text":"ION requires several runtime configuration settings to be defined at the time a node is initialized. Most notable are the settings for the Admin functions of ION. ION provides a variety of administration utilities including ionadmin, ionsecadmin, ltpadmin, bsspadmin, bpadmin, ipnadmin, and cfdpadmin. Each of the corresponding modules that is to be used at runtime will need to be configured. The commands that perform these configuration tasks are normally presented to the admin utility in an admin configuration file.
In the Linux environment, two different styles of configuration files are possible. Both styles are accepted by the \"ionstart\" program that installs as part of the official release, an AWK program. The first style requires that all configuration commands for all in-use admins will be stored in one file. This single file is sectioned off internally to separate the commands of each admin. The ionstart program accepts this single configuration file's name as a parameter, parses this file looking for sectioned-off areas for each possible admin function, and then uses the commands within these sections to configure the corresponding modules.
The other style requires that each admin will have its own distinct configuration file. The ionstart program consumes these files as guided by command line switches and parameters identifying each configuration file.
"},{"location":"ION-Deployment-Guide/#runtime-parameters","title":"Runtime Parameters","text":"Some ION configuration parameters are declared only at node initialization time; they cannot later be revised. In particular, the ionadmin \"1\" (the numeral one) initialization command must be executed just once, before any other configuration command is processed. The first parameter to this command is required and is a numeric value that indicates the node number of the DTN node being configured. The second parameter to this command is optional; if present, it must provide the full pathname of a local file of immutable configuration parameter values:
wmKey (integer)\nwmSize (integer)\nwmAddress (integer)\nsdrName (string)\n\nsdrWmSize (integer)\n# bit pattern in integer form, e.g., 3 for 00000011\nconfigFlags 3\nheapWords (integer)\nheapKey (integer)\npathName (string)\nThis path name should NOT be enclosed in any type of quotation marks. The file is a text file with 2 fields per line; lines are processed in sequence. The first field on each line holds one of the parameter identifier text strings as shown above. The second field holds the value that will be placed into the identified parameter. Make sure that the data type specified in the second field matches the type expected.
For documentation on these parameters, see the ionconfig(5) man page.
"},{"location":"ION-Deployment-Guide/#configflags","title":"configFlags","text":"The configFlags entry controls several features of the Simple Data Recorder (SDR).\u00a0 There are several flags of interest:
#define SDR_IN_DRAM\u00a0\u00a0\u00a0\u00a0 1\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 /*\u00a0\u00a0Write to & read from memory.\u00a0 */\n#define SDR_IN_FILE\u00a0\u00a0\u00a0\u00a0 2\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 /*\u00a0\u00a0Write file; read file if nec. */\n#define SDR_REVERSIBLE\u00a0 4\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 /*\u00a0\u00a0Transactions may be reversed.\u00a0*/\nSDR_IN_DRAM is required for normal ION operation and should virtually always be specified.
When SDR_REVERSIBLE is specified, SDR transactions that fail (e.g., due to memory allocation failure) are rolled back, allowing transactions to fail gracefully without corrupting the ION databases.\u00a0 If the flag is not supplied, failed transactions will cause an immediate task failure and, where supported, a core dump.\u00a0 This feature is intended only as an aid to debugging; in operations ION should normally be configured with reversible transactions.\u00a0 When transaction reversibility is enabled, ION creates & manages a log file in the directory named by \"pathName\" which must be writable by ION and which tracks the SDR changes and supports rollback to the last consistent state.\u00a0 The filesystem for this directory should be high-performance; a ramdisk is usually ideal.\u00a0 The maximum size of the logfile is dependent upon the largest transaction in the SDR, and is therefore of a size on the same order of magnitude as the largest bundle. NOTE that if the directory named by \"pathname\" does not exist then transaction reversibility will be disabled automatically; a message to this effect will be written to the ION log file.
When SDR_IN_FILE is specified, ION creates a file in the \"pathName\" directory, which is maintained as a copy of the SDR heap in DRAM; whenever the SDR heap in memory is modified, the changes are also written to the sdr heap file.\u00a0 Thus the heap file is always the same size as the in-memory heap. Again, if the directory named by \"pathname\" does not exist then retention of the ION SDR heap in a file will be disabled automatically; a message to this effect will be written to the ION log file. NOTE that
SDR_IN_FILE may have the adverse effect of slowing down all SDR transactions, which can significantly impact transmission, relay, and reception speed of ION. Users should conduct performance testing to ensure that keeping SDR in file can still achieve the operational performance expected.SDR_IN_FILE option is that in the case of ION shutdown due to power reset where the state of SDR is not corrupted, it is possible to start ION with the SDR file and resume data transfer operations such as LTP transaction. However, if ION shuts down due to an internal error, then it is not recommended to keep the SDR file when restarting ION, as the SDR state is not certain to be without corruption.When ION stores a bundle, it typically holds part of the bundle part in memory (heap) as determined by the maxheap parameter in bprc. The default value is about 650 bytes. The rest of the payload is placed into file reference. Also a bundle, before transmission, kept its header and extensions inside a data structure for quick look up and manipulations; the bundle is serialized into a chunk of octet according to the standard just prior to transmission. Therefore, when a bundle is stored in an ION node, part of its footprint is in the 'heap' and part of it is in the 'working memory.'
Test shows that leaving the maxHeap parameter to its default value, a bundle uses about 1.5KB of space in heap and about 100-150 Byte in working memory. Adding a 200% margin, we recommend that following relationship between heapWords and wmSize:
wmSize = 3 x heapWords x 8 x 0.4 / 10\nwhere 3 is the margin, 8 is the number of octets per word, 0.4 accounts for the fact that inbound and outbound heap space is only 40% of the heap, and 10 accounts for the empirically estimated 10:1 ratio between heap and working memory footprints per bundle.
Many ION runtime configuration parameters can be declared at node initialization and later revised dynamically, either by passing supplementary configuration files to the admin utilities or by exercising the admin utilities in interactive mode.
For documentation on the admin commands, see the man pages. The man page names are in the form of <xxx>rc, where <xxx> gets replaced by the specific module name (bp, dtn2, ion, ionsec, ipn, ltp, bssp, cfdp). The directories in which to find these files are: ./ici/doc/pod5, ./ltp/doc/pod5, ./bssp/doc/pod5, ./bp/doc/pod5, and ./cfdp/doc/pod5.
Normally the instantiation of ION on a given computer establishes a single ION node on that computer, for which hard-coded values of wmKey and sdrName (see ionconfig(5)) are used in common by all executables to assure that all elements of the system operate within the same state space. For some purposes, however, it may be desirable to establish multiple ION nodes on a single workstation. (For example, constructing an entire self-contained DTN network on a single machine may simplify some kinds of regression testing.) ION supports this configuration option as follows:
ION_NODE_LIST_DIR is defined in the environment of every participating ION process. Moreover, the value assigned to this variable must be the same text string in the environments of all participating ION processes. That value must be the name (preferably, fully qualified) of the directory in which the ION multi-node database file \"ion_nodes\" will reside.ION_NODE_LIST_DIR makes it possible to establish up to one ION node per directory rather than just one ION node on the computer. When ionadmin is used to establish a node, the ionInitialize() function will get that node's wmKey and sdrName from the .ionconfig file, use them to allocate working memory and create the SDR data store, and then write a line to the ion_nodes file noting the nodeNbr, wmKey, sdrName, and wdName for the node it just initialized. wdName is the current working directory in which ionadmin was running at the time it called ionInitialize(); it is the directory within which the node resides.sdrWmSize or default. If any later ION instance launched with sdrWmSize exceeding the first ION instance, it will result in crash upon launch. It is further recommended that all ION instances running simultaneously on a single host should set their sdrWmSize the same.Included in the root directory of the ION distribution is a bash script named ionstop. This script executes each of the \"admin\" utilities and instructs each subsystem to exit, by supplying the dummy command file name \".\". Once all of the utilities have exited, the script calls another script named killm (likewise located in the root directory of ion-open-source). The killm script first tries to kill all ION processes by name, then tries to destroy all of the shared-memory resources allocated to ION at the time the node was created.
There are also many \"local\" versions of ionstop script, stored in test subdirectories out of which one or multiple ION instances were launched on the same host. These local versions of ionstop script differ from the ionstop script in the root directory in that it usually contains (a) additional, customized scripts to clean up test artifacts such as ion.log, sdr file, received test files, and temporarily acquisition files for LTP and BP that remained after a test is completed and (b) it generally does not execute kilim, which will kill all ION processes, not just the ones related to the ION instance being terminated.
If you invoke the ionstop script that is part of the ION root directory, it does not clean up test artifacts or other products created during operation and if it detects that there are multiple ION instances running in the same host, it will NOT execute killm. In that case, the user is advised to always check that all processes are terminated properly and that the shared memory is cleared appropriately.
When running ionstop, various administrative programs will process a dummy command file \".\" that signals shutdown. It will first check the value of the environment variable ION_NODE_WDNAME, defined in the current shell, to determine which instance of ION must be taken down. The ION instance that was shutdown does not depend on the current directory the shell is in. Therefore it is possible to use either the ionstop script provided in ION's root directory or a local, customized version to shutdown an individual ION instance.
If you are having trouble shutting an ION node down, see the notes on \"Destroying a Node\" later in this Guide.
It has been pointed out that if you are running ION in a Docker container inside a Kubernetes pod, the system is likely to assign process ID 1 to one of the ION processes at startup; since process 1 cannot be killed, the ionstop script can't complete and your node will not be cleanly destroyed. One solution seems to be to usedumb-init for the docker container.
To make this work, you may have to override your entry point in the manifest file used by the Kubectl \"apply\" command.
"},{"location":"ION-Deployment-Guide/#example-configuration-files","title":"Example Configuration Files","text":""},{"location":"ION-Deployment-Guide/#ion-node-number-cross-reference","title":"ION Node Number Cross-reference","text":"When you define a DTN node, you do so using ionadmin and its Initialize command (using the token '1'). This node is then referenced by its node number throughout the rest of the configuration file.
## begin ionadmin \n1 1 /home/spwdev/cstl/ion-configs/23/badajoz/3node-udp-ltp/badajoz.ionconfig\ns\n\na contact +1 +86400 25 25 50000000\na contact +1 +84600 25 101 50000000\na contact +1 +84600 25 1 50000000\n\na contact +1 +86400 101 25 50000000\na contact +1 +86400 101 101 50000000\na contact +1 +86400 101 1 50000000\n\na contact +1 +86400 1 25 50000000\na contact +1 +86400 1 101 50000000\na contact +1 +86400 1 1 50000000\n\n\na range +1 +86400 25 25 1\na range +1 +86400 25 101 10\na range +1 +86400 25 1 10\n\na range +1 +86400 101 25 10\na range +1 +86400 101 101 1\na range +1 +86400 101 1 10\n\na range +1 +86400 1 25 10\na range +1 +86400 1 101 10\na range +1 +86400 1 1 1\n\nm production 50000000\nm consumption 50000000\n\n## end ionadmin\n##########################################################################\n## begin ltpadmin \n1 32\n\na span 25 1 1 1400 1400 1 'udplso 192.168.1.25:1113 1000000000'\na span 101 1 1 1400 1400 1 'udplso 192.168.1.101:1113 1000000000'\na span 1 1 1 1400 1400 1 'udplso 192.168.1.1:1113 1000000000'\n\ns 'udplsi 192.168.1.1:1113'\n\n## end ltpadmin \n##########################################################################\n## begin bpadmin \n1\n\na scheme ipn 'ipnfw' 'ipnadminep'\n\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n\na protocol ltp 1400 100\na protocol tcp 1400 100\n\na outduct ltp 25 ltpclo\na outduct ltp 101 ltpclo\na outduct ltp 1 ltpclo\n\na induct ltp 1 ltpcli\n\ns\n## end bpadmin\n##########################################################################\n## begin ipnadmin\n\na plan 25 ltp/25\na plan 101 ltp/101\na plan 1 ltp/1\n\n## end ipnadmin \nThe \"ipn\" scheme for URI formation is generally used to form the endpoint IDs of endpoints in an ION deployment. Any transmission using endpoints formed in the \"ipn\" scheme will have endpoints IDs of this form:
ipn:nodenumber.servicenumber
The Add Scheme command on line 51 below specifies that the \"ipn\" endpoint naming scheme is supported; the names of three endpoints formed in this scheme are shown in lines 53 thru 55.
The two remaining parameters on this command are used to define the software functions that will act as data forwarder and administrative data receiver.
"},{"location":"ION-Deployment-Guide/#the-bpadmin-add-scheme-command","title":"The bpadmin Add Scheme command","text":"a scheme scheme_name forwarder_command admin_app_command
The add scheme command. This command declares an endpoint naming scheme for use in endpoint IDs, which are structured as URIs: scheme_name:scheme-specific_part. forwarder_command will be executed when the scheme is started on this node, to initiate operation of a forwarding daemon for this scheme. admin_app_command will also be executed when the scheme is started on this node, to initiate operation of a daemon that opens an administrative endpoint identified within this scheme so that it can receive and process custody signals and bundle status reports.
Starting at line 71, the egress plans are defined. These determine the outducts by which data are sent to nodes that are topologically adjacent to the current node in the DTN-based network.
"},{"location":"ION-Deployment-Guide/#the-ipnadmin-add-plan-command","title":"The ipnadmin Add Plan command","text":"a plan node_nbr default_duct_expression
The add plan command. This command establishes an egress plan for the bundles that must be transmitted to the neighboring node identified by node_nbr. Each duct expression is a string of the form
protocol_name outduct_name
signifying that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
"},{"location":"ION-Deployment-Guide/#ltp-parameters-cross-reference","title":"LTP Parameters Cross-reference","text":"The ltpadmin utility allows the features of the LTP protocol to become available. For details of the LTP protocol, see RFC 5325.
The first command that must be issued to ltpadmin is the Initialize command (see line number 38 below, the command token is the '1' (one)). The sole parameter passed to this command is est_max_export_sessions.
"},{"location":"ION-Deployment-Guide/#the-ltpadmin-initialize-command","title":"The ltpadmin Initialize command","text":"This command uses est_max_export_sessions to configure the hash table 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 this parameter and 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.
- Essentially, the \"max export sessions\" must be >= the total number of export sessions on all the spans. If it is expected that new spans will be added during an ION session, then max export sessions figure should be large enough to cover the maximum # of sessions possible.
- Next to be defined are the Spans. They define the interconnection between two LTP engines. There are many parameters associated with the Spans.
"},{"location":"ION-Deployment-Guide/#the-ltpadmin-add-span-command","title":"The ltpadmin Add Span command","text":"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 the 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. max_segment_size specifies the largest LTP segment that this span will produce.
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 limit, aggregation into this block must cease and the block must be segmented and transmitted. When numerous small bundles are outbound, they are aggregated into a block of at least this size instead of being sent individually.
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. When a small number of small bundles are outbound, they are collected until this time limit is met, whereupon the aggregated quantity is sent as a single, larger block.
max_export_sessions constitutes the size of the local LTP engine's retransmission window for this span. The retransmission windows of the spans impose flow control on LTP transmission, preventing the allocation of all available space in the ION node's data store to LTP transmission sessions.
The max_import_sessions parameter is simply the neighboring engine's own value for the corresponding export session parameter.
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 is 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.
Additional notes:
- A \"session block\" is filled by outbound bundles until its aggregation size threshold is reached, or its aggregation time limit is reached, whereupon it is output as a series of segments (of size bounded by max_segment_size). This series of segments is reliably transferred via a LTP protocol session with the remote node, one session per block. By adjusting the size of the session block, the rate of arrival of response segments from the remote node can be controlled. Assuming a bundle rate sufficient to fill the session block, a large session block size means a lot of LTP segments per session (good for a high-rate return, low-rate forward link situation). A small session block size means the number of segments per session is smaller and the LTP protocol will complete the block transfer more quickly because the number of segment retries is generally smaller.
- A good starting point for a configuration is to set the aggregation size threshold to the number of bytes that will typically be transmitted in one second, so that blocks are typically clocked out about once per second. The maximum number of export sessions then should be at least the total number of seconds in the round-trip time for traffic on this LTP span, to prevent transmission from being blocked due to inability to start another session while waiting for the LTP acknowledgment that can end one of the current sessions.
- The multiplicity of session blocks permits bundles to stream; while one session block is being transmitted, a second can be filled (and itself transmitted) before the first is completed. By increasing the number of blocks, high latency links can be filled to capacity (provided there is adequate bandwidth available in the return direction for the LTP acknowledgments). But it is desirable to reduce the max_export_sessions to a value where \"most\" of the sessions are employed because each session allocates an increment of buffer memory from the SDR whether it is used or not.
- When a session block is transmitted, it is emitted as a series of back-to-back LTP segments that are simply queued for transmission; LTP does not meter segment issuance in any way. The underlying link layer is expected to pop segments from the queue and transmit them at the current rate as indicated in the contact plan. The udplso task does limit the task's rate of segment transmission over UDP/IP to the transmission rate declared in the contact plan, reducing the incidence of UDP congestion loss.
- Note that an LTP session can only be concluded (enabling space occupied by the block to be recycled) when all segments have been successfully received -- or retransmission limits have been reached and the session is canceled. High bit error rates on the link correlate to high rates of data loss when segments are large and/or blocks comprise large numbers of segments; this typically results in larger numbers of NACK/retransmit cycles, retarding session completion. When bit error rates are high, LTP performance can be improved by reducing segment size and/or aggregation size threshold.
"},{"location":"ION-Deployment-Guide/#the-ltpadmin-start-command","title":"The ltpadmin Start command","text":"s 'LSI command'
This command starts link service output tasks for all LTP spans (to remote engines) from the local LTP engine, and it starts the link service input task for the local engine.
The sole command on line number 44 below starts two main operations within LTP. The first of these operations starts all of the link service output tasks, the ones defined for each LTP span (see the LSO_command parameter of the Add Span command). In this example, each task instantiates the same function (named 'udplso'). Each 'udplso' needs a destination for its transmissions and these are defined as hostname or IP Address (192.168.1.1) and port number (nominally 1113, the pre-defined default port number for all LTP traffic).
The second operation started by this command is to instantiate the link service input task. In this instance, the task is named \"udplsi\". It is through this task that all LTP input traffic will be received. Similar to the output tasks, the input task also needs definition of the interface on which LTP traffic will arrive, namely hostname or IP address (192.168.1.1) and port number (1113). If it is necessary for udplsi to listen on multiple network interfaces simultaneously, \\'udplsi 0.0.0.0[:port]\\' can be invoked. This instructs udplsi to listen to the UDP broadcast address, which aggregates traffic from all available network interfaces, including localhost.
Once the LTP engine has been defined, initialized and started, we need a definition as to how data gets routed to the Convergence Layer Adaptors. Defining a protocol via bpadmin is the first step in that process.
"},{"location":"ION-Deployment-Guide/#the-bpadmin-add-protocol-command","title":"The bpadmin Add Protocol command","text":"a protocol protocol_name payload_bytes_per_frame overhead_bytes_per_frame
The \"add protocol\" command. This command establishes access to the named convergence layer protocol at the local node. As noted earlier, the payload_bytes_per_frame and overhead_bytes_per_frame arguments were previously used in calculating the estimated transmission capacity consumption of each bundle, to aid in route computation and congestion forecasting; in later versions of ION they are not needed and may be omitted.
Once the protocol has been defined, it can be used to define ducts, both inducts and outducts, as seen in lines 76 thru 80 below. The Add \"duct\" commands associate a protocol (in this case, LTP) with individual node numbers (in this case, 25, 101 and 1) and a task designed to handle the appropriate Convergence Layer output operations. A similar scenario applies for the induct where the LTP protocol and node number 13 get connected with \"ltpcli\" as the input Convergence Layer function.
"},{"location":"ION-Deployment-Guide/#the-bpadmin-add-outduct-and-add-induct-commands","title":"The bpadmin Add Outduct and Add Induct commands","text":"a outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The \"add outduct\" command. This command establishes a duct for transmission of bundles via the indicated CL protocol. The duct's data transmission structure is serviced by the outduct task whose operation is initiated by CLO_command at the time the duct is started. max_payload_length, if specified, causes ION to fragment bundles issued via this outduct (as necessary) to ensure that all such bundles have payloads that are no larger than max_payload_length.
a induct protocol_name duct_name 'CLI_command'
The \"add induct\" command. This command establishes a duct for reception of bundles via the indicated CL protocol. The duct's data acquisition structure is used and populated by the induct task whose operation is initiated by CLI_command at the time the duct is started.
Note that only a single induct is needed for all bundle reception via any single protocol at any single node, and in fact ION may operate poorly if multiple inducts are established for any single protocol. For any induct whose duct name includes an IP address, use IP address 0.0.0.0 (INADDR_ANY) if the machine on which the node resides is multihomed and you want the node to be reachable via all of the machine's network interfaces.
Once all of this has been defined, the last piece needed is the egress plan -- namely how do packets get transmitted to DTN nodes that are the local node's \"neighbors\" in the topology of the network.
As you can see from line numbers 6 thru 29, the only network neighbor to node 1 is node 101. Node 25 has not been defined (because the commands in lines 8, 14, 21 and 27 have been commented). In line numbers 15 and 16, we see that the only destinations for data beginning at node 1 are nodes 101 and 1 (a loopback as such). Therefore, in order to get data from node 1 to node 25, our only choice is to send data to node 101. Out best hope of reaching node 25 is that the configurations for node 101 define a connection to node 25 (either a one-hop direct connection, or more multi-hop assumptions). This is where egress plans come into play.
On line numbers 87 thru 89, this configuration defines the only choices that can be made regarding destinations. For a destination of node 25, which is not a neighbor, all node 1 can do is pass the data to its only neighbor, namely node 101; the \"exit\" command enables this operation. For destinations of nodes 101 and 1, the scenario is pretty simple.
"},{"location":"ION-Deployment-Guide/#the-ipnadmin-add-exit-command","title":"The ipnadmin Add Exit command","text":"a exit first_node_nbr last_node_nbr gateway_endpoint_ID
The \"add exit\" command. This command establishes an \"exit\" for static routing. An exit is an association of some defined routing behavior with some range of node numbers identifying a set of nodes. Whenever a bundle is to be forwarded to a node whose number is in the exit's node number range and it has not been possible to compute a dynamic route to that node from the contact schedules that have been provided to the local node and that node is not a neighbor to which the bundle can be directly transmitted, BP will forward the bundle to the gateway node associated with this exit.
"},{"location":"ION-Deployment-Guide/#the-ipnadmin-add-plan-command_1","title":"The ipnadmin Add Plan command","text":"a plan node_nbr duct_expression [nominal_data_rate]
The \"add plan\" command. This command establishes an egress plan for the bundles that must be transmitted to the neighboring node identified by node_nbr.
Each duct expression is a string of the form
protocol_name outduct_name
signifying that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
The duct expression used in these examples has \"ltp\" being the protocol name and 101 and 1 being the outduct names.
"},{"location":"ION-Deployment-Guide/#ipnadmins-plan-commands-have-been-superseded-by-bpadmin","title":"ipnadmin's \"plan\" commands have been superseded by bpadmin","text":"As of ION 4.1.0, bprc's \"plan\" and \"planduct\" commands supersede and generalize the egress plan commands documented in the ipnrc(5) and dtn2rc(5) man pages, which are [retained for backward compatibility]. The syntax of the egress plan commands consumed by bpadmin is DIFFERENT from that of the commands consumed by ipnadmin and dtn2admin. Please see the man page for bprc (5) for details.
"},{"location":"ION-Deployment-Guide/#bundle-in-bundle-encapsulation","title":"Bundle-in-Bundle Encapsulation","text":"For some purposes it may be helpful to encapsulate a bundle inside another bundle -- that is, to let the serialized representation of a bundle be part of the payload of another bundle. This mechanism is called \"Bundle-in-Bundle Encapsulation\" (BIBE) and is defined in Internet Draft draft-burleigh-dtn-bibect-00.txt (which will likely be renamed at some point and ideally will become an IETF standards-track Request For Comments in due course).
"},{"location":"ION-Deployment-Guide/#introduction-to-bibe","title":"Introduction to BIBE","text":"By way of overview, here is an excerpt from that document:
Each BP node that conforms to the BIBE specification provides a BIBE convergence-layer adapter (CLA) that is implemented within the administrative element of the BP node's application agent. Like any convergence-layer adapter, the BIBE CLA provides:
The BIBE CLA performs these services by:
Bundle-in-bundle encapsulation may have broad utility, but the principal motivating use case is the deployment of \"cross domain solutions\" in secure communications. Under some circumstances a bundle may arrive at a node that is on the frontier of a region of network topology in which augmented security is required, from which the bundle must egress at some other designated node. In that case, the bundle may be encapsulated within a bundle to which the requisite additional BP Security (BPSEC) extension block(s) can be attached, whose source is the point of entry into the insecure region (the \"security source\") and whose destination is the point of egress from the insecure region (the \"security destination\").
Note that:
The protocol includes a mechanism for recovery from loss of an encapsulating bundle, called \"custody transfer\". This mechanism is adapted from the custody transfer procedures described in the experimental Bundle Protocol specification developed by the Delay-Tolerant Networking Research group of the Internet Research Task Force and documented in RFC 5050. Custody transfer is a convention by which the loss or corruption of BIBE encapsulating bundles can be mitigated by the exchange of other bundles, which are termed \"custody signals\".
BIBE is implemented in ION, but configuring ION nodes to employ BIBE is not as simple as one might think. That is because BIBE functions as both a BP application and a convergence-layer adapter; coercing the Bundle Protocol to function in both capacities, offering services to itself at two different layers of the protocol stack, requires careful configuration.
"},{"location":"ION-Deployment-Guide/#configuring-bibe-in-ion","title":"Configuring BIBE in ION","text":"Like any convergence-layer protocol, BIBE is used to copy a bundle from one BP node (the sending node) to another node (the receiving node), over one segment of the end-to-end path from the bundle's source node to its destination node. Somewhat confusingly, in BIBE the copying of the bundle is accomplished by issuing a second encapsulating bundle, which has its own source node and destination node:
Each pair of sending and receiving nodes can be thought of as a \"tunnel\" which requires specific configuration. These tunnels constitute the communication relationships that must be implemented as \"outducts\" in ION.
"},{"location":"ION-Deployment-Guide/#bclas","title":"BCLAs","text":"While the node IDs of the source and destination nodes of encapsulating bundles are necessary parameters for BIBE transmission, they are not sufficient: encapsulating bundles are characterized by quality of service, lifetime, etc., just like other bundles. For this purpose we use an additional BIBE administration utility program -- bibeadmin -- that consumes a file of .bprc commands; these commands add, revise, and delete BIBE convergence layer adapter objects (bclas) that are managed in a BIBE database. For example:
a bcla ipn:3.0 20 20 300 2 128
This command adds a bcla identified by \"ipn:3.0\" -- the ID of the destination node of all encapsulating bundles formed according to this bcla -- which asserts that the expected latency for each encapsulating bundle to reach this destination node is 20 seconds, the expected latency for a responding custody signal bundle is likewise 20 seconds, the encapsulating bundle's time-to-live is 300 seconds, its class of service is 2 (expedited), and its ordinal sub-priority is 128.
Note that other configuration elements may also be implicitly associated with this bcla. For example, BPSEC security rules may map this BIBE source/destination node pair to security block configurations that will pertain to all encapsulating bundles formed according to this bcla.
"},{"location":"ION-Deployment-Guide/#ducts","title":"Ducts","text":"Since BIBE is a convergence-layer protocol, each BIBE tunnel must be configured by means of BP administration (bpadmin) using .bprc commands; BIBE must be added as a protocol, the local node must be added as the BIBE induct, and each supported BIBE tunnel must be added as a BIBE outduct. For example:
a protocol bibe\na induct bibe \\* ''\na outduct bibe ipn:4.0 'bibeclo ipn:3.0'\nThe \"a outduct\" command states that the BIBE outduct (tunnel) identified by node ID \"ipn:4.0\" (the receiving node) is serviced by a BIBE convergence-layer output daemon operating according to the bcla identified by \"ipn:3.0\" as described above. The destination node ipn:3.0 is responsible for forwarding each extracted (encapsulated) bundle to the receiving node ipn:4.0. The sending node and the source node of the encapsulating bundles are both, implicitly, the local node.
Note that for most convergence-layer adapters the node ID of the receiving node for a given outduct is implicit; for example, an stcp outduct explicitly identifies only the socket address of the receiving node's socket -- that is, the convergence-layer protocol endpoint ID -- not the node ID of the receiving node. BIBE differs only in that the convergence-layer protocol endpoint ID is, explicitly, the node ID of the receiving node, simply because BP is being used as the convergence-layer protocol.
"},{"location":"ION-Deployment-Guide/#plans","title":"Plans","text":"In order to cause bundles to be conveyed to a specified receiving node via a BIBE outduct, that outduct must be associated with that node in an egress plan. For example, in the .ipnrc file:
a plan ipn:4.0 bibe/ipn:4.0\na plan ipn:3.0 stcp/91.7.31.134:4546\nThe first command asserts that all bundles destined for node \"ipn:4.0\" are to be forwarded using BIBE outduct \"ipn:4.0\". The second asserts that all bundles destined for node \"ipn:3.0\" (here, all BIBE encapsulating bundles formed according to the bcla identified by \"ipn:3.0\") are to be forwarded using the stcp outduct connected to TCP socket \"91.7.31.134:4546\".
"},{"location":"ION-Deployment-Guide/#contacts","title":"Contacts","text":"Finally, in order for data to flow to receiving node ipn:4.0 via the bibe/ipn:4.0 outduct, a contact object must be added to the contact plan enabling the transmissions:
a contact +0 +1000000000 2 4 100000
This command states that data flow from node 2 (here, the local node) to node 4 (the receiving node) is continuously enabled, but the rate of transmission is limited to 100,000 bytes per second.
"},{"location":"ION-Deployment-Guide/#overrides","title":"Overrides","text":"Under some circumstances, successful forwarding of BIBE bundles requires that outduct overrides be applied. See the biberc(5) man page for details.
"},{"location":"ION-Deployment-Guide/#adaptations","title":"Adaptations","text":""},{"location":"ION-Deployment-Guide/#error-logging","title":"Error Logging","text":"ION contains a flexible system that allows its code to display errors in several different ways. At the core of this system is a typedef that defines a data type named \"Logger\" (with upper case \"L\") that is a function variable that accepts a character pointer (string) parameter and returns a value of type void.
typedef void (* Logger)(char *);
In ION, there is one variable defined to be of this type. Its identifier is \"logger\" (with lower case \"L\") and it is initialized to a value of \"logToStdout\". The function \"logToStdout\" is defined and its contents cause the string parameter to be printed to the stdout device. Therefore, any call to the function variable \"logger\" will have same effects as a call to the function \"logToStdout\".
However, remember that \"logger\" is a variable and is allowed to change its value to that of other functions that accept string parameters and return void. This is how ION allows for flexibility in logging errors.
At startup, ION makes a call to \"ionRedirectMemos\". This function makes a call to \"setLogger\" which eventually changes the value of the \"logger\" variable. The new value of the variable named \"logger\" is \"writeMemoToIonLog\". This function writes strings to a file named \"ion.log\".
It is through this mechanism that any calls to the functions \"writeMemo\", \"writeMemoNote\" or \"writeErrMemo\" eventually pass their parameters to the function \"writeMemoToIonLog\". This is how the Linux-based ION's operate.
Check out the FSWLOGGER macro option as documented in section 2.1.1 of the Design Guide.
"},{"location":"ION-Deployment-Guide/#memory-allocation","title":"Memory Allocation","text":"What types of memory does ION use and how is memory allocated/controlled?
For an introductory description of the memory resources used by ION, see Section 1.5 of the ION Design and Operation guide entitled \"Resource Management in ION\".
Section 1.5 of the Design and Operation guide makes reference to parameters called \"wmSize\" and \"heapWords\". Discussion on these and all of the parameters can be found in this document under the section entitled \"Runtime Parameters\".
ION allocates its large blocks of memory via calls to malloc. Should the need ever arise to place these large blocks of memory at known, fixed addresses, it would be possible to modify the function memalign, in the file platform.c. A better approach would be to create a shared-memory segment for each pre-allocated memory block (possibly using ION's sm_ShmAttach() function to do this) and pass the applicable shared-memory key values to ION at startup, in the \"heapKey\" and/or \"wmKey\" runtime parameters.
Any code that references the function \"sm_ShmAttach\" will be looking to acquire some block of memory. These would include the Space Management Trace features and standalone programs such as \"file2sm\", \"sm2file\" and \"smlistsh\".
"},{"location":"ION-Deployment-Guide/#testing-known-issues","title":"Testing & Known Issues","text":""},{"location":"ION-Deployment-Guide/#factors-affecting-ltp-testing-over-udp","title":"Factors Affecting LTP Testing Over UDP","text":"Terrestrial testing of LTP during the prototype and initial system integration phases often relies on using the UDP protocol because it is readily available on most terrestrial computing systems. ION's udplso and udplsi programs provide the basic capability to flow LTP traffic between two hosts on the internet. To increase the fidelity of LTP testing, short of directly utilizing actual radio systems, customized software or hardware can be added to the data path. This addition aims to introduce longer delays and data corruption/loss in a controlled manner.
However, testing LTP over UDP can yield unpredictable results due to several factors. Understanding these factors is essential for accurate analysis and troubleshooting:
"},{"location":"ION-Deployment-Guide/#udps-inherent-unreliability","title":"UDP's Inherent Unreliability","text":"UDP lacks a built-in mechanism for retransmitting lost packets. Consequently, the rate at which packets are lost can fluctuate significantly. This inherent unreliability of UDP may affect the performance and reliability tests of LTP, as LTP relies on UDP for transport.
"},{"location":"ION-Deployment-Guide/#kernel-buffering-and-ip-fragment-reassembly","title":"Kernel Buffering and IP Fragment Reassembly","text":"The ability of the operating system kernel to buffer and reassemble IP fragments plays a critical role, especially if an LTP segment exceeds the Maximum Transmission Unit (MTU) size. The efficiency of this process can vary based on:
External testing tools, either customized software or WAN emulators, are often used to simulate network conditions or impairments but may also impact the fidelity of testing by exaggerating the delay differences between different traffic streams, including UDP fragments, when improperly configured, and further complicate the interpretation of LTP performance results over UDP.
"},{"location":"ION-Deployment-Guide/#operation_1","title":"Operation","text":"ION is generally optimized for continuous operational use rather than research. In practice, this means that a lot more attention, both in the code and in the documentation, has been paid to the care and feeding of an existing ION-based network than to the problem of setting up a new network in the first place. (The unspoken expectation is that you're only going to do it once anyway.)
Unfortunately this can make ION somewhat painful for new users to work with. The notes in this section are aimed at reducing this pain, at least a little.
"},{"location":"ION-Deployment-Guide/#wrong-profile-for-this-sdr","title":"\"Wrong profile for this SDR\"","text":"ION is based on shared access to a common data store in memory (and/or in a file), and the objects in that data store are intended to persist across multiple restarts of network activity in a continuously operational network. That's okay for Space Station operations, but it's not helpful while you're still struggling to get the network running in the first place. For this purpose you are probably creating and destroying one or more nodes repetitively.
A key concept:
Each time you run the standard ionstart script provided with ION, you are creating a new network from scratch. To minimize confusion, be sure to clear out the old data store first.
If you don't wipe out the old system before trying to start the new one, then either you will pick up where you left off in testing the old system (and any endpoints, ducts, etc. you try to add will be rejected as duplicates) or -- in the event that you have changed something fundamental in the configuration, or are using an entirely different configuration file -- you'll see the \"Wrong profile for this SDR\" message and won't be able to continue at all.
"},{"location":"ION-Deployment-Guide/#destroying-a-node","title":"Destroying a node","text":"In most cases the ionstop script should terminate the node for you. Invoke it once for every node of your network. To verify that you're starting from a clean slate, run the ipcs command after ionstop: the list of Semaphore Arrays should be empty. If it's not, you've got one or more leftover processes from the previous network still running; use ps ax to find them and kill -9 to get rid of them. The process names to look for are:
Then run the killm script again to make sure the node's shared-memory resources have been released; run ipcs again to verify, and review your leftover processes again if those resources still haven't been released.
An additional wrinkle: if you configure ION to manage your ION data store in a file as well as (or instead of) managing it in shared memory, then in addition to calling killm to destroy the semaphores and the copy of the data store that resides in shared memory, you also need to delete the data store file; this destroys the copy of the data store that resides in the file system. If the data store isn't deleted, then when you restart ION using your standard configuration file the file-system copy of the data store will automatically be reloaded into shared memory and all the config file commands that create new schemes, endpoints, etc. will fail, because they're still in the data store that you were using before.
Another habit that can be helpful: whenever you restart ION from scratch, delete all the ion.log files in all of the directories in which you're configuring your ION nodes. This isn't mandatory -- ION will happily append new log messages to existing log files, and the messages are time-tagged anyway, so it's always possible to work out what happened when. But starting fresh with new log files removes a lot of clutter so that it's easy to see exactly what's happening in this particular iteration of your network research. ION will create new log files automatically if they don't exist; if there's something particularly interesting in the log from a prior system, copy that log file with a different name so you can come back to it if you need to.
"},{"location":"ION-Deployment-Guide/#no-such-directory-disabling-heap-residence-in-file","title":"\"No such directory; disabling heap residence in file...\"","text":"This message just means that the directory whose name you've provided as the value of pathName in the ION configuration file does not exist, and therefore the ION operations that rely on being able to write files in that directory are disabled. It's strictly informative; nearly everything in ION will work just fine even if this message is printed every time you run.
But if you do care about transaction reversibility, for example, or if you just want to get rid of the annoying message, simply create the directory that is named in pathName (it can be any path name you like) and make sure it's world-writable. The ionconfig(5) man page discusses this parameter and others that affect the fundamental character of the system you're configuring.
"},{"location":"ION-Deployment-Guide/#cant-find-ion-security-database","title":"\"Can't find ION security database\"","text":"These messages are just warnings, but they are annoying. We're still struggling to work out a way to support bundle security protocol as fully and readily as possible but still let people run ION without it, if they want, without too much hassle.
For now, the best answer might be to insert the following lines into each host.rc file immediately after the \"##end ionadmin\" line. They should create an empty ION security database on each host, which should shut down all those warnings:
## begin ionsecadmin\n1\n## end ionsecadmin\nSeveral key elements of ION (notably LTP transmission and bundle expiration) rely on the clocks of all nodes in the network being synchronized to within a few seconds. NTP is a good way to accomplish this, if you've got access to an NTP server. If you can't get your clocks synchronized, stick to the TCP or UDP convergence-layer adapters, don't count on using contact graph routing, and use long lifetimes on all bundles to prevent premature bundle expiration.
"},{"location":"ION-Deployment-Guide/#node-numbers","title":"Node numbers","text":"In ION we always use the same numeric value for LTP (and BSSP) engine number and BP node number -- and for CFDP entity number and AMS continuum number as well. The idea is that a given ION node has a single identifying number, which by convention we use wherever a protocol endpoint identifier is needed for any local protocol agent. This is not a DTN or CCSDS requirement, but it doesn't violate any of the protocol specifications and it does marginally simplify both implementation and configuration.
"},{"location":"ION-Deployment-Guide/#duct-names","title":"Duct names","text":"The bprc(5) man page explains the general format of the commands for adding convergence-layer inducts and outducts, but it doesn't provide the syntax for duct names, since duct name syntax is different for different CL protocols. Here's a summary of duct name syntax for the CL protocols supported as of ION 3.6.1:
Here are some other points to bear in mind as you debug your ION node configuration:
In this section, we present LTP throughput measurements collected on different computing platforms. The goal of these tests is to provide a set of data points that give ION users a sense of the achievable LTP throughput for a given level of computing resources, ranging from single-board computers (SBC) to medium-level or high-end servers connected via 10Gbps Ethernet. We made no attempt to match any particular user's computing environment in this test. Users must exercise their own good engineering sense when generalizing and applying these data points to make predictions regarding the performance of their own systems. The users are encouraged to install ION on the target platform and configure ION - using some of the configuration recommendations in this report - when conducting their own tests.
Since our focus is to explore the speed limitation caused by software processing within ION, we try to eliminate external factors that can slow down throughput, such as a poor network connection or other processing-intensive software running concurrently on the host machine that compete for CPU cycles, etc. We also eliminated the impact of round-trip delay and packet error by testing LTP over a high-speed, low-error, direct Ethernet connection between two LTP peers.
"},{"location":"ION-Deployment-Guide/#considerations-for-configuration","title":"Considerations for Configuration","text":"Given that LTP is designed for space links, not terrestrial links, LTP segment sizes much larger than typical terrestrial network MTUs (nominally 1,500 to 9,000 bytes) are considered in our testing. For LTP configuration in space, the CCSDS Packet Encapsulation service enables LTP segments of variable sizes to be transmitted over different CCSDS space link protocols.
Most of our testing was conducted with the SDR in DRAM (configuration 1) to achieve higher data processing speed. However, we did collect data on several cases where reversibility and SDR object boundness checks were turned on.
In the interest of efficiency, we also favor selecting larger bundles, potentially much larger than the LTP aggregation block size. In previous TCPCL testing, it was observed that a larger bundle size improves throughput since more data can be transferred per logical operation. For the same reason, we believe that a larger bundle size will improve LTP performance.
ION performs bundle-level metering to throttle the speed with which data is presented to LTP engines for transmission. The throttle rate is set by the contact plan and should not exceed the line rate of the physical Ethernet connection. In many cases, we configure ION with a contact plan rate that is lower than the Ethernet line rate to allow BP/LTP to operate as fast as possible without creating a destructive level of congestion. To facilitate better testing, we also use the bpdriver utility program with the \\'i\\' option to control the source data injection rate. For some tests, we find data metering unnecessary, and ION can buffer and handle local congestion and deliver the maximum possible throughput.
NOTE: The results presented here are based on System V semaphore. Recent upgrade and testing of a POSIX semaphore approach indicated a substantial performance increase to ION, and that result will be published in the next release of this document.
As stated earlier, our goal is to test the ION processing rate limitation, not the host system\\'s memory availability. Therefore, we configure ION SDR with a generous amount of heap and working memory to ensure that data storage is not a limiting factor.
Now, we present our test cases.
"},{"location":"ION-Deployment-Guide/#test-case-1-mid-grade-linux-server-with-direct-ethernet-connection","title":"Test Case 1: Mid-grade Linux Server with Direct Ethernet Connection","text":"B = byte
b = bit
M = mega
K = kilo
G = giga
ION Configuration:
Hardware Specification and Operating System:
Throughput Measured:
ION Configuration:
Hardware Specification and Operating System:
Throughput Measured:
In this test case, we considered several SDR configuration combinations and assessed their impact.
We do not include the \"SDR in file\" or any combination with that since file operation will slow down performance significantly.
Base ION Memory Configuration
BP/LTP Configuration
The following is representational of .ltprc file on both nodes
1 50
Contact Plan Data Rate (1 Gb/sec)
Hardware Specification and Operating System:
Network link reported by iperf as follows (PTL Orange Testbed)
UDP: 1.35 GB/sec
Throughput Measured
General observation is that SDR boundedness checks (each write operation must ensure that the location where data is written is occupied by an object of the same size of the write operation) introduce about 11% of throughput degradation. Adding reversibility will substantially slow down the system since the reversibility, by default, saves transaction operations record in a file until the transaction is complete or until when the transaction is canceled and must be reversed. Although it is possible to store transaction record in ION's working memory, we didn't consider this case in our testing due to time constraint.
"},{"location":"ION-Deployment-Guide/#test-case-4-10gbps-physical-ethernet-study-with-2012-xeon-sandy-bridge","title":"Test Case 4: 10Gbps Physical Ethernet Study (with 2012 Xeon Sandy Bridge)","text":"In this 10Gbps case study, we measured LTP performance between two machines physically connected by a 10Gbps Ethernet switch. Initial testing with iperf showed that although the physical connection was 10Gbps, the actual throughput maxed out at 2.5Gbps. Improved throughput was attained by increasing the kernel buffer sizes to 8MB. Additionally, increasing the MTU (Maximum Transmission Unit) size from 1500 to 9600 resolved some caching issues seen at the receiving node.
UDP Configuration Details
The following kernel buffer size settings were used to enable full utilization of the 10Gbps Ethernet on the host machine. These are provided for your reference. Depending on your host system's configuration, you may not need to adjust any parameters to make sure the full capacity of the Ethernet connection is achievable. Even in cases where you do find it necessary to make such adjustments, the actual parameters values may not be the same.
To resolve the caching issue, which allows the LTP engine to clean up after the test quickly, we set the MTU to 9600. This is not strictly required but we find it helpful when the MTU is set to 9600 Bytes instead of the typical value of 1500 Bytes (we observed improved LTP session cleanup times with the higher MTU). After applying these updates, iperf testing showed 9.9Gbps throughput on the Ethernet connection between the two hosts.
Test Network Details
The test network consists of 2 host machines physically connected via 10 Gb Network Interface Card
Hardware
ION Memory Configuration Details
LTP Configuration Details
Throughput Measurement
The first series of tests provided some insights into the impact of bundle size on throughput. In general, using a larger bundle size allows ION to transfer more data per logical operation since the overhead of a bundle is relatively fixed regardless of the size of the payload. In our tests, we controlled the size of all bundles injected into ION for LTP transfer. In real operations, bundle size will vary, but for bulk data transfer, the user is generally able to dictate the size of the bundle it sends. To avoid processing smaller bundles individually (which occurs in real operations), we turned on LTP block aggregation and set the size to 64KB.
Figure 1: LTP Throughput as a Function of Bundle Size
In Figure 1, we can immediately observe that bundle size has a significant impact on LTP throughput. This is because the bundle is the basic unit of an LTP block. When LTP block aggregation is turned on, a block may consist of one or multiple bundles. When LTP block aggregation is not applied, each block is one bundle. When the bundle size is less than the aggregation size, LTP will accumulate several bundles before creating a block. While this will limit LTP overhead, the use of small bundles still has an impact on the bundle protocol level processing, both before LTP transmission and during post-LTP-reception reconstruction. Therefore, as we can see, when the bundle size is dropped below the LTP aggregation threshold, the throughput is still impacted by bundle size.
While it may seem that the aggregation size limit does not have a strong impact on throughput, it does for long delay-bandwidth space links, where it dictates the maximum number of import/export sessions that ION must support simultaneously. That will be another investigation for a future study. For now, we focus solely on testing the limit of ION\\'s data processing speed in a low latency lab environment.
We also conducted a second series of tests to look at the impact of LTP segment sizes on throughput. The results are in Figure 2 below.
Figure 2: Impact of LTP Segment Size on Throughput
In this test, we looked at bundle sizes that are 1MB or lower, with segment sizes ranging from 64KB to 1,500 bytes. Again, we observed that segment size has a stronger impact on throughput when it is less than 10% of the bundle size; once it goes above 10%, the impact is noticeably diminished. This has to do with the fact that each segment levies a minimal amount of logical operation. Using a large segment size can help reduce LTP processing overhead. However, since the segment is LTP\\'s standard protocol data unit and it determines the vulnerability/likelihood of data loss (large segments expose more data to loss due to corruption), it is not advised to arbitrarily increase the segment size in a real flight environment with a substantial data loss probability. The key point here is to illustrate that the choice of segment size can impact the processing overhead and speed of LTP.
"},{"location":"ION-Deployment-Guide/#impact-of-variable-bundles-size","title":"Impact of variable bundles size","text":"In real life operation, we expect the users to generate a wide mixture of large and small bundles. Although we don't have a commonly agreed on \"profile\" of how a typical DTN user will generate bundles, it is nonetheless valuable for us to get a sense of how BP/LTP in ION would perform when handling bundles of random sizes.
For a quick study, we leveraged the same 2.1GHz Xeon Sandy Bridge processor configuration with 1MB LTP aggregation limit and injected bundles whose payload size is a uniformly distributed random value between 1024 bytes and 62464 bytes. We found that the throughput is approximately 260Mbps for segment size of 9600 B, and 300Mbps when segment size is increased to 64,000B. For the second test, we increased the bundle size ranges to be between 1KB and 1MB, the measured throughput is 2.08Gbps.
This performance is higher than we expected. For the same amount of data delivery, using 1MB bundle vs an average of 31KB per bundle (uniform between 1K and 62K) would increase bundle process overhead by a factor of 32. Holding all other parameters constant, the 300Mbps throughput is only a factor of 9.6 lower compared to the 1MB bundle case with throughput of 2.9Gbps. The 32-fold increase of bundle overhead didn't result in a 32-fold reduction of speed. The reason for this better-than-expected result is, we believe, due to the use of LTP block aggregation. Similarly, for the second test, we increased the average bundle overhead by a factor 2, but the data rate reduction is only about 29 percent. By keeping the block aggregation to 1MB, we keep the number of LTP sessions and handshaking overhead low, which mitigated some of the impact of the presence of smaller bundles.
Our initial assessment is that the mixed use of larger and smaller bundles will reduce throughput but not as substantially as one would expect based on a linear interpolation of the bundle processing overhead. The use of LTP block aggregation can maintain a higher efficiency under such circumstances. Additional investigation in this area will be conducted and reported in the near future.
"},{"location":"ION-Deployment-Guide/#summary-of-ltp-throughput-test-results","title":"Summary of LTP Throughput Test Results","text":"We conducted a series of tests, documenting the performance of BP/LTP for a range of hardware and ION configuration options. At the lower end, we tested two stock Raspberry Pi 4B single-board computers running ION 4.1.2 and achieved 60 Mbps one-way data transfer without any hardware or OS optimization. At the higher end of our tests, we measured ION performance between two Linux servers (see spec in Test Case 4; 2012 era Xeon Sandy Bridge Processors) and showed that ION's BP/LTP implementation can support up to 3.7Gbps throughput over a 10Gbps Ethernet physical connection. We also presented a discussion on the performance trades regarding various LTP configuration parameters.
We hope that these data points will provide users with a sense of how to configure ION, BP, and LTP to achieve the highest possible throughput on their own systems. We acknowledge that these tests focus on exploring the performance envelope of ION\\'s data processing speed and do not emulate specific flight configurations, nor do they cover long round-trip delay and high error rate space links. For specific link conditions and computing the recommended LTP settings, please consult the LTP Configuration Tool spreadsheet provided with each ION open-source package.
"},{"location":"ION-Deployment-Guide/#acknowledgment","title":"Acknowledgment","text":"Some of the technology described in this Deployment Guide was developed at the Jet Propulsion Laboratory, California Institute of Technology, under a contract with the National Aeronautics and Space Administration.
Copyright \u00a9 2021 California Institute of Technology
The ION team would like to acknowledge the following individuals for contributed to the earlier versions of this Guide: Jane Marquart, NASA; Greg Menke, Columbus; Larry Shackelford, Microtel LLC; Scott Burleigh (retired), Jet Propulsion Laboratory, California Institute of Technology
"},{"location":"ION-Design-and-API-Overview/","title":"ION Design and API Overview","text":""},{"location":"ION-Design-and-API-Overview/#basic-philosophy","title":"Basic Philosophy","text":"The development of ION began in the early 2000's, focusing on flight systems running Real-time Operating System (RTOS) with minimum resources under strict control. While these constraints might be somewhat relaxed for modern embedded systems, ION's lightweight, modular, and portable traits remain desirable to both flight and ground systems today:
Hard Memory Allocation Limits: ION operates within a host-specified memory allocation, managing dynamic allocation internally via a private memory management system. This approach ensures efficient use of the allocated memory resources.
Modular and Robust Operation: ION's design allows individual modules to start, stop, re-build, or possibly be replaced independently. This modular structure is implemented through separate daemons and libraries, enhancing system resilience. In a process crash, data in the process's queues/buffers can be preserved in the non-volatile SDR, preventing data loss.
Efficient Resource Utilization: ION is optimized for environments with limited memory, storage, and processing resources. It avoids duplicate data copies during multi-stage processing by utilizing Zero-Copy Objects (ZCO) in shared memory space for fast hand-off between modules. This method, while more complex, ensures rapid data handling. Additionally, BP and CLA services operate as background daemons to minimize competition with critical spacecraft functions during nominal, high-stress, and off-nominal events.
Independence from Native IP Socket Support: ION employs software abstraction to decouple socket-based programming from its core functionalities. This allows ION to interface the Bundle Protocol and CLAs with various underlying communication systems, such as CCSDS space links, radio communications systems, or customized processing chains that are not IP-based.
Portability and Minimal Footprint for Static Linking: ION prioritizes portability and minimal resource footprint by building its function libraries. This approach supports static linking through the ION-core package for a specific set of modules. It reduces dependency on external libraries, thereby mitigating the risk of interference from unexercised or non-required code segments that cannot be removed from the libraries. This design also avoids potential compatibility issues between the target system\u2019s build environment and those of externally sourced libraries.
"},{"location":"ION-Design-and-API-Overview/#ion-modules","title":"ION Modules","text":"The BP Service API document shows the default installation location of various libraries and daemons. Interactions with these daemons rely on various APIs made available through the libraries. The following diagram shows ION's modular architecture:
ION provides four application-layer services that utilize the underlying DTN protocols. These services are:
ION provides BP services based on Bundle Protocol v6 and Bundle Protocol v7, BPSec (Bundle Protocol Security), and the Interplanetary Internet (IPN) naming scheme. In addition, it offers several standardized convergence layer adaptors, namely:
ION also provides UDP-based Underlying Communication Protocol (UCP) to support testing of the LTP CLA in terrestrial systems.
ION also supports the AMS (Asynchronous Management Architecture) by implementing both an Asynchronous Management Protocol (AMP) Agent and Manager and the associated Application Data Model (ADM) that describes both common and ION-specific DTN network management state information and commands.
The entire ION software suite operates within a prescribed memory space. It is privately managed by ION's ICI infrastructure library functions for space allocation/deallocation, data I/O, and linked list and zero-copy object (ZCO) management. There are two types of data storage: working memory to facilitate data processing and heap in the SDR designed to store state information and data that should persist through a power cycle when implemented on a non-volatile storage medium. ION's APIs are exposed to the user through a set of C header files associated with each module's library.
"},{"location":"ION-Design-and-API-Overview/#modular-packaging-ion-core","title":"Modular Packaging - ION Core","text":"Due to the highly modular design of ION, it is possible to build a streamlined package that contains only the modules required for a specific system to maximize resource efficiency and reduce V&V costs. ION-Core 4.1.2b package offers the ability to selectively build different sets of CLAs and bundle extensions blocks, targeting either 32-bit or 64-bit operating systems.
"},{"location":"ION-Design-and-API-Overview/#ion-apis","title":"ION APIs","text":"For software development, ION provides several sets of APIs for interacting with services/daemons of the underlying DTN protocols, as shown below:
ION APIs can be roughly categorized as follows:
Version 4.1.3 JPL D-48259
Document Change Log
Ver No. Date Description Note V4.1.3 12/08 /2023 converted to MarkDown V4.0.1 11/20/2020 ION 4.0.1 V3.6.2 11/19/2018 ION 3.6.2 release features Skipped V3.6.1. V3.6 12/31/2017 ION 3.6 release features Skipped V3.5. V3.4 3/28/2016 ION 3.4 release features V3.3 3/4/2015 ION 3.3 release features V3.2 12/17/2013 ION 3.2 release features V3.1 9/28/2012 ION 3.1 release features V3.0 3/22/2012 Align with ION 3.0 release V1.13 10/13/2011 Updates for Source Forge Release V1.12 6/11/2010 Updates for second open source release (2.2) V1.11 12/11/2009 BRS updates, multi-node config V1.10 10/23/2009 Final additions prior to DINET 2 experiment V1.9 6/29/2009 Add updates for DINET 2, including CFDP, ionsec V1.8 2/6/2009 Update discussion of Contact Graph Routing; document status msg formats V1.7 12/1/2008 Add documentation for OWLT simulator, BP extension V1.6 10/03/2008 Add documentation of sm_SemUnend V1.5 09/20/2008 Revisions requested SQA V1.4 07/31/2008 Add a section on optimizing ION-based network; tuning V1.3 07/08/2008 Revised some details of CGR V1.2 05/24/2008 Revised man pages for bptrace, ltprc, bprc. V1.1 05/18/2008 Some additional diagrams V1.0 04/28/2008 Initial version of ION design and ops manual"},{"location":"ION-Guide/#design","title":"Design","text":"The Interplanetary Overlay Network (ION) software distribution is an implementation of Delay-Tolerant Networking (DTN) architecture as described in Internet RFC 4838. It is designed to enable inexpensive insertion of DTN functionality into embedded systems such as robotic spacecraft. The intent of ION deployment in space flight mission systems is to reduce cost and risk in mission communications by simplifying the construction and operation of automated digital data communication networks spanning space links, planetary surface links, and terrestrial links.
A comprehensive overview of DTN is beyond the scope of this document. Very briefly, though, DTN is a digital communication networking technology that enables data to be conveyed between two communicating entities automatically and reliably even if one or more of the network links in the end-to-end path between those entities is subject to very long signal propagation latency and/or prolonged intervals of unavailability.
The DTN architecture is much like the architecture of the Internet, except that it is one layer higher in the familiar ISO protocol \"stack\". The DTN analog to the Internet Protocol (IP), called \"Bundle Protocol\" (BP), is designed to function as an \"overlay\" network protocol that interconnects \"internets\" -- including both Internet-structured networks and also data paths that utilize only space communication links as defined by the Consultative Committee for Space Data Systems (CCSDS) -- in much the same way that IP interconnects \"subnets\" such as those built on Ethernet, SONET, etc. By implementing the DTN architecture, ION provides communication software configured as a protocol stack that looks like this:
Figure 1 DTN protocol stack
Data traversing a DTN are conveyed in DTN bundles -- which are functionally analogous to IP packets -- between BP endpoints which are functionally analogous to sockets. Multiple BP endpoints may be accessed at a single DTN node -- functionally analogous to a network interface card -- and multiple nodes may reside on the same computer just as a single computer (host or router) in the Internet may have multiple network interface cards.
BP endpoints are identified by Universal Record Identifiers (URIs), which are ASCII text strings of the general form:
scheme_name:scheme_specific_part
For example:
dtn://topquark.caltech.edu/mail
But for space flight communications this general textual representation might impose more transmission overhead than missions can afford. For this reason, ION is optimized for networks of endpoints whose IDs conform more narrowly to the following scheme:
ipn:node_number.service_number
This enables them to be abbreviated to pairs of unsigned binary integers via a technique called Compressed Bundle Header Encoding (CBHE). CBHE-conformant BP endpoint IDs (EIDs) are not only functionally similar to Internet socket addresses but also structurally similar: node numbers are roughly analogous to Internet node numbers (IP addresses), in that they typically identify the flight or ground data system computers on which network software executes, and service numbers are roughly analogous to TCP and UDP port numbers.
More generally, the node numbers in CBHE-conformant BP endpoint IDs are one manifestation of the fundamental ION notion of network node number: in the ION architecture there is a natural one-to-one mapping not only between node numbers and BP endpoint node numbers but also between node numbers and:
Starting with version 3.1 of ION, this endpoint naming rule is experimentally extended to accommodate bundle multicast, i.e., the delivery of copies of a single transmitted bundle to multiple nodes at which interest in that bundle's payload has been expressed. Multicast in ION -- \"Interplanetary Multicast\" (IMC) -- is accomplished by simply issuing a bundle whose destination endpoint ID conforms to the following scheme:
imc:group_number.service_number
A copy of the bundle will automatically be delivered at every node that has registered in the destination endpoint.
(Note: for now, the operational significance of a given group number must be privately negotiated among ION users. If this multicast mechanism proves useful, IANA may at some point establish a registry for IMC group numbers. Also note that a new mechanism for bundle multicast is introduced in ION 4.0.1, along with support for Bundle Protocol version 7. This new mechanism vastly simplifies bundle multicast; chiefly, the imcadmin utility is deprecated.)
"},{"location":"ION-Guide/#structure-and-function","title":"Structure and function","text":"The ION distribution comprises the following software packages:
ams (Asynchronous Message Service), an application-layer service that is not part of the DTN architecture but utilizes underlying DTN protocols. AMS comprises three protocols supporting the distribution of brief messages within a network:
The core AAMS (Application AMS) protocol, which does message distribution on both the publish/subscribe model and the client/server model, as required by the application.
Taken together, the packages included in the ION software distribution constitute a communication capability characterized by the following operational features:
Management of traffic through such a network, taking into consideration:
requirements for data security
A DTN implementation intended to function in an interplanetary network environment -- specifically, aboard interplanetary research spacecraft separated from Earth and from one another by vast distances -- must operate successfully within two general classes of design constraints: link constraints and processor constraints.
All communications among interplanetary spacecraft are, obviously, wireless. Less obviously, those wireless links are generally slow and are usually asymmetric.
The electrical power provided to on-board radios is limited and antennae are relatively small, so signals are weak. This limits the speed at which data can be transmitted intelligibly from an interplanetary spacecraft to Earth, usually to some rate on the order of 256 Kbps to 6 Mbps.
The electrical power provided to transmitters on Earth is certainly much greater, but the sensitivity of receivers on spacecraft is again constrained by limited power and antenna mass allowances. Because historically the volume of command traffic that had to be sent to spacecraft was far less than the volume of telemetry the spacecraft were expected to return, spacecraft receivers have historically been engineered for even lower data rates from Earth to the spacecraft, on the order of 1 to 2 Kbps.
As a result, the cost per octet of data transmission or reception is high and the links are heavily subscribed. Economical use of transmission and reception opportunities is therefore important, and transmission is designed to enable useful information to be obtained from brief communication opportunities: units of transmission are typically small, and the immediate delivery of even a small part (carefully delimited) of a large data object may be preferable to deferring delivery of the entire object until all parts have been acquired.
The computing capability aboard a robotic interplanetary spacecraft is typically quite different from that provided by an engineering workstation on Earth. In part this is due, again, to the limited available electrical power and limited mass allowance within which a flight computer must operate. But these factors are exacerbated by the often intense radiation environment of deep space. In order to minimize errors in computation and storage, flight processors must be radiation-hardened and both dynamic memory and non-volatile storage (typically flash memory) must be radiation-tolerant. The additional engineering required for these adaptations takes time and is not inexpensive, and the market for radiation-hardened spacecraft computers is relatively small; for these reasons, the latest advances in processing technology are typically not available for use on interplanetary spacecraft, so flight computers are invariably slower than their Earth-bound counterparts. As a result, the cost per processing cycle is high and processors are heavily subscribed; economical use of processing resources is very important.
The nature of interplanetary spacecraft operations imposes a further constraint. These spacecraft are wholly robotic and are far beyond the reach of mission technicians; hands-on repairs are out of the question. Therefore the processing performed by the flight computer must be highly reliable, which in turn generally means that it must be highly predictable. Flight software is typically required to meet \"hard\" real-time processing deadlines, for which purpose it must be run within a hard real-time operating system (RTOS).
One other implication of the requirement for high reliability in flight software is that the dynamic allocation of system memory may be prohibited except in certain well-understood states, such as at system start-up. Unrestrained dynamic allocation of system memory introduces a degree of unpredictability into the overall flight system that can threaten the reliability of the computing environment and jeopardize the health of the vehicle.
"},{"location":"ION-Guide/#design-principles","title":"Design Principles","text":"The design of the ION software distribution reflects several core principles that are intended to address these constraints.
Figure 2 ION inter-task communication
Since ION must run on flight processors, it had to be designed to function successfully within an RTOS. Many real-time operating systems improve processing determinism by omitting the support for protected-memory models that is provided by Unix-like operating systems: all tasks have direct access to all regions of system memory. (In effect, all tasks operate in kernel mode rather than in user mode.) ION therefore had to be designed with no expectation of memory protection.
But universally shared access to all memory can be viewed not only as a hazard but also as an opportunity. Placing a data object in shared memory is an extremely efficient means of passing data from one software task to another.
ION is designed to exploit this opportunity as fully as possible. In particular, virtually all inter-task data interchange in ION follows the model shown in Figure 2:
Semaphore operations are typically extremely fast, as is the storage and retrieval of data in memory, so this inter-task data interchange model is suitably efficient for flight software.
Given ION's orientation toward the shared memory model, a further strategy for processing efficiency offers itself: if the data item appended to a linked list is merely a pointer to a large data object, rather than a copy, then we can further reduce processing overhead by eliminating the cost of byte-for-byte copying of large objects.
Moreover, in the event that multiple software elements need to access the same large object at the same time, we can provide each such software element with a pointer to the object rather than its own copy (maintaining a count of references to assure that the object is not destroyed until all elements have relinquished their pointers). This serves to reduce somewhat the amount of memory needed for ION operations.
The efficiency of inter-task communications based on shared memory makes it practical to distribute ION processing among multiple relatively simple pipelined tasks rather than localize it in a single, somewhat more complex daemon. This strategy has a number of advantages:
The clear interfaces between tasks simplify the implementation of flow control measures to prevent uncontrolled resource consumption.
Portability
Designs based on these kinds of principles are foreign to many software developers, who may be far more comfortable in development environments supported by protected memory. It is typically much easier, for example, to develop software in a Linux environment than in VxWorks 5.4. However, the Linux environment is not the only one in which ION software must ultimately run.
Consequently, ION has been designed for easy portability. POSIX\u2122 API functions are widely used, and differences in operating system support that are not concealed within the POSIX abstractions are mostly encapsulated in two small modules of platform-sensitive ION code. The bulk of the ION software runs, without any source code modification whatsoever, equally well in Linux\u2122 (Red Hat\u00ae, Fedora\u2122, and Ubuntu\u2122, so far), FreeBSD\u00ae, Solaris\u00ae 9, Microsoft Windows (the MinGW environment), OS/X\u00ae, VxWorks\u00ae 5.4, and RTEMS\u2122, on both 32-bit and 64-bit processors. Developers may compile and test ION modules in whatever environment they find most convenient.
"},{"location":"ION-Guide/#organizational-overview","title":"Organizational Overview","text":"Two broad overviews of the organization of ION may be helpful at this point. First, here is a summary view of the main functional dependencies among ION software elements:
Figure 3 ION software functional dependencies
That is, BP and LTP invoke functions provided by the sdr, zco, psm, and platform elements of the ici package, in addition to functions provided by the operating system itself; the zco functions themselves also invoke sdr, psm, and platform functions; and so on.
Second, here is a summary view of the main line of data flow in ION's DTN protocol implementations:
Figure 4 Main line of ION data flow
Note that data objects residing in shared memory, many of them in a nominally non-volatile SDR data store, constitute the central organizing principle of the design. Here as in other diagrams showing data flow in this document:
A few notes on this main line data flow:
Finally, note that the data flow shown here represents the sustained operational configuration of a node that has been successfully instantiated on a suitable computer. The sequence of operations performed to reach this configuration is not shown. That startup sequence will necessarily vary depending on the nature of the computing platform and the supporting link services. Broadly, the first step normally is to run the ionadmin utility program to initialize the data management infrastructure required by all elements of ION. Following this initialization, the next steps normally are (a) any necessary initialization of link service protocols, (b) any necessary initialization of convergence-layer protocols (e.g., LTP -- the ltpadmin utility program), and finally (c) initialization of the Bundle Protocol by means of the bpadmin utility program. BP applications should not try to commence operation until BP has been initialized.
"},{"location":"ION-Guide/#resource-management-in-ion","title":"Resource Management in ION","text":"Successful Delay-Tolerant Networking relies on retention of bundle protocol agent state information -- including protocol traffic that is awaiting a transmission opportunity -- for potentially lengthy intervals. The nature of that state information will fluctuate rapidly as the protocol agent passes through different phases of operation, so efficient management of the storage resources allocated to state information is a key consideration in the design of ION.
Two general classes of storage resources are managed by ION: volatile \"working memory\" and non-volatile \"heap\".
ION's \"working memory\" is a fixed-size pool of shared memory (dynamic RAM) that is allocated from system RAM at the time the bundle protocol agent commences operation. Working memory is used by ION tasks to store temporary data of all kinds: linked lists, red-black trees, transient buffers, volatile databases, etc. All intermediate data products and temporary data structures that ought not to be retained in the event of a system power cycle are written to working memory.
Data structures residing in working memory may be shared among ION tasks or may be created and managed privately by individual ION tasks. The dynamic allocation of working memory to ION tasks is accomplished by the Personal Space Management (PSM) service, described later. All of the working memory for any single ION bundle protocol agent is managed as a single PSM \"partition\". The size of the partition is specified in the wmSize parameter of the ionconfig file supplied at the time ION is initialized.
ION's \"heap\" is a fixed-size pool of notionally non-volatile storage that is likewise allocated at the time the bundle protocol agent commences operation. This notionally non-volatile space may occupy a fixed-size pool of shared memory (dynamic RAM, which might or might not be battery-backed), or it may occupy only a single fixed-size file in the file system, or it may occupy both. In the latter case, all heap data are written both to memory and to the file but are read only from memory; this configuration offers the reliable non-volatility of file storage coupled with the high performance of retrieval from dynamic RAM.
We characterize ION's heap storage as \"notionally\" non-volatile because the heap may be configured to reside only in memory (or, for that matter, in a file that resides in the file system of a RAM disk). When the heap resides only in memory, its contents are truly non-volatile only if that memory is battery-backed. Otherwise heap storage is in reality as volatile as working memory: heap contents will be lost upon a system power cycle (which may in fact be the preferred behavior for any given deployment of ION). However, the heap should not be thought of as \\\"memory\\\" even when it in fact resides only in DRAM, just as a disk device should not be thought of as \\\"memory\\\" even when it is in fact a RAM disk.
{width=\"4.738575021872266in\" height=\"3.338542213473316in\"}
Figure 5 ION heap space use
The ION heap is used for storage of data that (in at least some deployments) would have to be retained in the event of a system power cycle to ensure the correct continued operation of the node. For example, all queues of bundles awaiting route computation, transmission, or delivery reside in the node's heap. So do the non-volatile databases for all of the protocols implemented within ION, together with all of the node's persistent configuration parameters.
The dynamic allocation of heap space to ION tasks is accomplished by the Simple Data Recorder (SDR) service, described later. The entire heap for any single ION bundle protocol agent is managed as a single SDR \"data store\".
Space within the ION heap is apportioned as shown in Figure 5. The total number of bytes of storage space in the heap is computed as the product of the size of a \"word\" on the deployment platform (normally the size of a pointer) multiplied by the value of the heapWords parameter of the ionconfig file supplied at the time ION is initialized. Of this total, 20% is normally reserved as margin and another 40% is normally reserved for various infrastructure operations. (Both of these percentages are macros that may be overridden at compile time.) The remainder is available for storage of protocol state data in the form of \"zero-copy objects\", described later. At any given moment, the data encapsulated in a zero-copy object may \"belong\" to any one of the protocols in the ION stack (AMS, CFDP, BP, LTP), depending on processing state; the available heap space is a single common resource to which all of the protocols share concurrent access.
Because the heap is used to store queues of bundles awaiting processing, blocks of LTP data awaiting transmission or reassembly, etc., the heap for any single ION node must be large enough to contain the maximum volume of such data that the node will be required to retain during operations. Demand for heap space is substantially mitigated if most of the application data units passed to ION for transmission are file-resident, as the file contents themselves need not be copied into the heap. In general, however, computing the optimum ION heap size for a given deployment remains a research topic.
"},{"location":"ION-Guide/#package-overviews","title":"Package Overviews","text":""},{"location":"ION-Guide/#interplanetary-communication-infrastructure-ici","title":"Interplanetary Communication Infrastructure (ICI)","text":"The ICI package in ION provides a number of core services that, from ION's point of view, implement what amounts to an extended POSIX-based operating system. ICI services include the following:
1. Platform
The platform system contains operating-system-sensitive code that enables ICI to present a single, consistent programming interface to those common operating system services that multiple ION modules utilize. For example, the platform system implements a standard semaphore abstraction that may invisibly be mapped to underlying POSIX semaphores, SVR4 IPC semaphores, Windows Events, or VxWorks semaphores, depending on which operating system the package is compiled for. The platform system also implements a standard shared-memory abstraction, enabling software running on operating systems both with and without memory protection to participate readily in ION's shared-memory-based computing environment.
2. Personal Space Management (PSM)
Although sound flight software design may prohibit the uncontrolled dynamic management of system memory, private management of assigned, fixed blocks of system memory is standard practice. Often that private management amounts to merely controlling the reuse of fixed-size rows in static tables, but such techniques can be awkward and may not make the most efficient use of available memory. The ICI package provides an alternative, called PSM, which performs high-speed dynamic allocation and recovery of variable-size memory objects within an assigned memory block of fixed size. A given PSM-managed memory block may be either private or shared memory.
3. Memmgr
The static allocation of privately-managed blocks of system memory for different purposes implies the need for multiple memory management regimes, and in some cases a program that interacts with multiple software elements may need to participate in the private shared-memory management regimes of each. ICI's memmgr system enables multiple memory managers -- for multiple privately-managed blocks of system memory -- to coexist within ION and be concurrently available to ION software elements.
4. Lyst
The lyst system is a comprehensive, powerful, and efficient system for managing doubly-linked lists in private memory. It is the model for a number of other list management systems supported by ICI; as noted earlier, linked lists are heavily used in ION inter-task communication.
5. Llcv
The llcv (Linked-List Condition Variables) system is an inter-thread communication abstraction that integrates POSIX thread condition variables (vice semaphores) with doubly-linked lists in private memory.
6. Smlist
Smlist is another doubly-linked list management service. It differs from lyst in that the lists it manages reside in shared (rather than private) DRAM, so operations on them must be semaphore-protected to prevent race conditions.
7. SmRbt
The SmRbt service provides mechanisms for populating and navigating \"red/black trees\" (RBTs) residing in shared DRAM. RBTs offer an alternative to linked lists: like linked lists they can be navigated as queues, but locating a single element of an RBT by its \"key\" value can be much quicker than the equivalent search through an ordered linked list.
8. Simple Data Recorder (SDR)
SDR is a system for managing non-volatile storage, built on exactly the same model as PSM. Put another way, SDR is a small and simple \"persistent object\" system or \"object database\" management system. It enables straightforward management of linked lists (and other data structures of arbitrary complexity) in non-volatile storage, notionally within a single file whose size is pre-defined and fixed.
SDR includes a transaction mechanism that protects database integrity by ensuring that the failure of any database operation will cause all other operations undertaken within the same transaction to be backed out. The intent of the system is to assure retention of coherent protocol engine state even in the event of an unplanned flight computer reboot in the midst of communication activity.
9. Sptrace
The sptrace system is an embedded diagnostic facility that monitors the performance of the PSM and SDR space management systems. It can be used, for example, to detect memory \"leaks\" and other memory management errors.
10. Zco
ION's zco (zero-copy objects) system leverages the SDR system's storage flexibility to enable user application data to be encapsulated in any number of layers of protocol without copying the successively augmented protocol data unit from one layer to the next. It also implements a reference counting system that enables protocol data to be processed safely by multiple software elements concurrently -- e.g., a bundle may be both delivered to a local endpoint and, at the same time, queued for forwarding to another node -- without requiring that distinct copies of the data be provided to each element.
11. Rfx
The ION rfx (R/F Contacts) system manages lists of scheduled communication opportunities in support of a number of LTP and BP functions.
12. Ionsec
The IONSEC (ION security) system manages information that supports the implementation of security mechanisms in the other packages: security policy rules and computation keys.
"},{"location":"ION-Guide/#licklider-transmission-protocol-ltp","title":"Licklider Transmission Protocol (LTP)","text":"The ION implementation of LTP conforms fully to RFC 5326, but it also provides two additional features that enhance functionality without affecting interoperability with other implementations:
In the ION stack, LTP serves effectively the same role that is performed by an LLC protocol (such as IEEE 802.2) in the Internet architecture, providing flow control and retransmission-based reliability between topologically adjacent bundle protocol agents.
All LTP session state is safely retained in the ION heap for rapid recovery from a spacecraft or software fault.
"},{"location":"ION-Guide/#bundle-protocol-bp","title":"Bundle Protocol (BP)","text":"The ION implementation of BP conforms fully to RFC 5050, including support for the following standard capabilities:
The system also provides three additional features that enhance functionality without affecting interoperability with other implementations:
In addition, ION BP includes a system for computing dynamic routes through time-varying network topology assembled from scheduled, bounded communication opportunities. This system, called \"Contact Graph Routing,\" is described later in this Guide.
In short, BP serves effectively the same role that is performed by IP in the Internet architecture, providing route computation, forwarding, congestion avoidance, and control over quality of service.
All bundle transmission state is safely retained in the ION heap for rapid recovery from a spacecraft or software fault.
"},{"location":"ION-Guide/#asynchronous-message-service-ams","title":"Asynchronous Message Service (AMS)","text":"The ION implementation of the CCSDS AMS standard conforms fully to CCSDS 735.0-B-1. AMS is a data system communications architecture under which the modules of mission systems may be designed as if they were to operate in isolation, each one producing and consuming mission information without explicit awareness of which other modules are currently operating. Communication relationships among such modules are self-configuring; this tends to minimize complexity in the development and operations of modular data systems.
A system built on this model is a \"society\" of generally autonomous inter-operating modules that may fluctuate freely over time in response to changing mission objectives, modules' functional upgrades, and recovery from individual module failure. The purpose of AMS, then, is to reduce mission cost and risk by providing standard, reusable infrastructure for the exchange of information among data system modules in a manner that is simple to use, highly automated, flexible, robust, scalable, and efficient.
A detailed discussion of AMS is beyond the scope of this Design Guide. For more information, please see the AMS Programmer's Guide.
"},{"location":"ION-Guide/#datagram-retransmission-dgr","title":"Datagram Retransmission (DGR)","text":"The DGR package in ION is an alternative implementation of LTP that is designed to operate responsibly -- i.e., with built-in congestion control -- in the Internet or other IP-based networks. It is provided as a candidate \"primary transfer service\" in support of AMS operations in an Internet-like (non-delay-tolerant) environment. The DGR design combines LTP's concept of concurrent transmission transactions with congestion control and timeout interval computation algorithms adapted from TCP.
"},{"location":"ION-Guide/#ccsds-file-delivery-protocol-cfdp","title":"CCSDS File Delivery Protocol (CFDP)","text":"The ION implementation of CFDP conforms fully to Service Class 1 (Unreliable Transfer) of CCSDS 727.0-B-4, including support for the following standard capabilities:
All CFDP transaction state is safely retained in the ION heap for rapid recovery from a spacecraft or software fault.
"},{"location":"ION-Guide/#bundle-streaming-service-bss","title":"Bundle Streaming Service (BSS)","text":"The BSS service provided in ION enables a stream of video, audio, or other continuously generated application data units, transmitted over a delay-tolerant network, to be presented to a destination application in two useful modes concurrently:
The TC service provided in ION enables critical but non-confidential information (such as public keys, for asymmetric cryptography) to be provided in a delay-tolerant, trustworthy manner. An instance of TC comprises:
Any number of Clients, which:
Announce new content to the Authority via authenticated bundle multicast, and/or
A small number of network operation design elements -- fragmentation and reassembly, bandwidth management, and delivery assurance (retransmission) -- can potentially be addressed at multiple layers of the protocol stack, possibly in different ways for different reasons. In stack design it's important to allocate this functionality carefully so that the effects at lower layers complement, rather than subvert, the effects imposed at higher layers of the stack. This allocation of functionality is discussed below, together with a discussion of several related key concepts in the ION design.
"},{"location":"ION-Guide/#fragmentation-and-reassembly","title":"Fragmentation and Reassembly","text":"To minimize transmission overhead and accommodate asymmetric links (i.e., limited \"uplink\" data rate from a ground data system to a spacecraft) in an interplanetary network, we ideally want to send \"downlink\" data in the largest possible aggregations -- coarse-grained transmission.
But to minimize head-of-line blocking (i.e., delay in transmission of a newly presented high-priority item) and minimize data delivery latency by using parallel paths (i.e., to provide fine-grained partial data delivery, and to minimize the impact of unexpected link termination), we want to send \"downlink\" data in the smallest possible aggregations -- fine-grained transmission.
We reconcile these impulses by doing both, but at different layers of the ION protocol stack.
First, at the application service layer (AMS and CFDP) we present relatively small application data units (ADUs) -- on the order of 64 KB -- to BP for encapsulation in bundles. This establishes an upper bound on head-of-line blocking when bundles are de-queued for transmission, and it provides perforations in the data stream at which forwarding can readily be switched from one link (route) to another, enabling partial data delivery at relatively fine, application-appropriate granularity.
(Alternatively, large application data units may be presented to BP and the resulting large bundles may be proactively fragmented at the time they are presented to the convergence-layer manager. This capability is meant to accommodate environments in which the convergence-layer manager has better information than the application as to the optimal bundle size, such as when the residual capacity of a contact is known to be less than the size of the bundle.)
Then, at the BP/LTP convergence layer adapter lower in the stack, we aggregate these small bundles into blocks for presentation to LTP:
Any continuous sequence of bundles that are to be shipped to the same LTP engine and all require assured delivery may be aggregated into a single block, to reduce overhead and minimize report traffic.
However, this aggregation is constrained by an aggregation size limit rule: aggregation must stop and the block must be transmitted as soon as the sum of the sizes of all bundles aggregated into the block exceeds the block aggregation threshhold value declared for the applicable span (the relationship between the local node's LTP engine and the receiving LTP engine) during LTP protocol configuration via ltpadmin.
Given a preferred block acknowledgment period -- e.g., a preferred acknowledgement traffic rate of one report per second -- the nominal block aggregation threshold is notionally computed as the amount of data that can be sent over the link to the receiving LTP engine in a single block acknowledgment period at the planned outbound data rate to that engine.
Taken together, application-level fragmentation (or BP proactive fragmentation) and LTP aggregation place an upper limit on the amount of data that would need to be re-transmitted over a given link at next contact in the event of an unexpected link termination that caused delivery of an entire block to fail. For example, if the data rate is 1 Mbps and the nominal block size is 128 KB (equivalent to 1 second of transmission time), we would prefer to avoid the risk of having wasted five minutes of downlink in sending a 37.5 MB file that fails on transmission of the last kilobyte, forcing retransmission of the entire 37.5 MB. We therefore divide the file into, say, 1200 bundles of 32 KB each which are aggregated into blocks of 128 KB each: only a single block failed, so only that block (containing just 4 bundles) needs to be retransmitted. The cost of this retransmission is only 1 second of link time rather than 5 minutes. By controlling the cost of convergence-layer protocol failure in this way, we avoid the overhead and complexity of \"reactive fragmentation\" in the BP implementation.
Finally, within LTP itself we fragment the block as necessary to accommodate the Maximum Transfer Unit (MTU) size of the underlying link service, typically the transfer frame size of the applicable CCSDS link protocol.
"},{"location":"ION-Guide/#bandwidth-management","title":"Bandwidth Management","text":"The allocation of bandwidth (transmission opportunity) to application data is requested by the application task that's passing data to DTN, but it is necessarily accomplished only at the lowest layer of the stack at which bandwidth allocation decisions can be made -- and then always in the context of node policy decisions that have global effect.
The transmission queue interface to a given neighbor in the network is actually three queues of outbound bundles rather than one: one queue for each of the defined levels of priority (\"class of service\") supported by BP. When an application presents an ADU to BP for encapsulation in a bundle, it indicates its own assessment of the ADU's priority. Upon selection of a proximate forwarding destination node for that bundle, the bundle is appended to whichever of the queues corresponds to the ADU's priority.
Normally the convergence-layer manager (CLM) task servicing a given proximate node extracts bundles in strict priority order from the heads of the three queues. That is, the bundle at the head of the highest-priority non-empty queue is always extracted.
However, if the ION_BANDWIDTH_RESERVED compiler option is selected at the time ION is built, the convergence-layer manager task servicing a given proximate node extracts bundles in interleaved fashion from the heads of the node's three queues:
Following insertion of the extracted bundles into transmission buffers, CLO tasks other than ltpclo simply segment the buffered bundles as necessary and transmit them using the underlying convergence-layer protocols. In the case of ltpclo, the output task aggregates the buffered bundles into blocks as described earlier and a second daemon task named ltpmeter waits for aggregated blocks to be completed; ltpmeter, rather than the CLO task itself, segments each completed block as necessary and passes the segments to the link service protocol that underlies LTP. Either way, the transmission ordering requested by application tasks is preserved.
"},{"location":"ION-Guide/#contact-plans","title":"Contact Plans","text":"In the Internet, protocol operations can be largely driven by currently effective information that is discovered opportunistically and immediately, at the time it is needed, because the latency in communicating this information over the network is negligible: distances between communicating entities are small and connectivity is continuous. In a DTN-based network, however, ad-hoc information discovery would in many cases take so much time that it could not be completed before the information lost currency and effectiveness. Instead, protocol operations must be largely driven by information that is pre-placed at the network nodes and tagged with the dates and times at which it becomes effective. This information takes the form of contact plans that are managed by the R/F Contacts (rfx) services of ION's ici package.
Figure 6 RFX services in ION
The structure of ION's RFX (contact plan) database, the rfx system elements that populate and use that data, and affected portions of the BP and LTP protocol state databases are shown in Figure 6. (For additional details of BP and LTP database management, see the BP/LTP discussion later in this document.)
To clarify the notation of this diagram, which is also used in other database structure diagrams in this document:
A contact is here defined as an interval during which it is expected that data will be transmitted by DTN node A (the contact's transmitting node) and most or all of the transmitted data will be received by node B (the contact's receiving node). Implicitly, the transmitting mode will utilize some \"convergence-layer\" protocol underneath the Bundle Protocol to effect this direct transmission of data to the receiving node. Each contact is characterized by its start time, its end time, the identities of the transmitting and receiving nodes, and the rate at which data are expected to be transmitted by the transmitting node throughout the indicated time period.
(Note that a contact is specifically not an episode of activity on a link. Episodes of activity on different links -- e.g., different radio transponders operating on the same spacecraft -- may well overlap, but contacts by definition cannot; they are bounded time intervals and as such are innately \"tiled\". For example, suppose transmission on link X from node A to node B, at data rate RX, begins at time T1 and ends at time T2; also, transmission on link Y from node A to node B, at data rate RY begins at time T3 and ends at time T4. If T1 = T3 and T2 = T4, then there is a single contact from time T1 to time T2 at data rate RX + RY. If T1 \\< T3 and T2 = T4, then there are two contiguous contacts: one from T1 to T3 at data rate RX, then one from T3 to T2 at data rate RX + RY. If T1 \\< T3 and T3\\<T2 \\< T4, then there are three contiguous contacts: one from T1 to T3 at data rate RX, then one from T3 to T2 at data rate RX + RY, then one from T2 to T4 at data rate RY. And so on.)
A range interval is a period of time during which the displacement between two nodes A and B is expected to vary by less than 1 light second from a stated anticipated distance. (We expect this information to be readily computable from the known orbital elements of all nodes.) Each range interval is characterized by its start time, its end time, the identities of the two nodes to which it pertains, and the anticipated approximate distance between those nodes throughout the indicated time period, to the nearest light second.
The topology timeline at each node in the network is a time-ordered list of scheduled or anticipated changes in the topology of the network. Entries in this list are of two types:
\u2022 Contact entries characterize scheduled contacts.
\u2022 Range entries characterize anticipated range intervals.
Each node to which, according to the RFX database, the local node transmits data directly via some convergence-layer protocol at some time is termed a neighbor of the local node. Each neighbor is associated with one or more outduct for the applicable BP convergence-layer (CL) protocol adapter(s), so bundles that are to be transmitted directly to this neighbor can simply be queued for transmission by outduct (as discussed in the Bandwidth Management notes above).
At startup, and at any time while the system is running, ionadmin inserts and removes Contact and Range entries in the topology timeline of the RFX database. Inserting or removing a Contact or Range entry will cause routing tables to be recomputed for the destination nodes of all subsequently forwarded bundles, as described in the discussion of Contact Graph Routing below.
Once per second, the rfxclock task (which appears in multiple locations on the diagram to simplify the geometry) applies all topology timeline events (Contact and Range start, stop, purge) with effective time in the past. Applying a Contact event that cites a neighboring node revises the transmission or reception data rate between the local node and that Neighbor. Applying a Range event that cites a neighboring node revises the OWLT between the local node and that neighbor. Setting data rate or OWLT for a node with which the local node will at some time be in direct communication may entail creation of a Neighbor object.
"},{"location":"ION-Guide/#route-computation","title":"Route Computation","text":"ION's computation of a route for a given bundle with a given destination endpoint is accomplished by one of several methods, depending on the destination. In every case, the result of successful routing is the insertion of the bundle into an outbound transmission queue (selected according to the bundle's priority) for one or more neighboring nodes.
But before discussing these methods it will be helpful to establish some terminology:
Egress plans
ION can only forward bundles to a neighboring node by queuing them on some explicitly specified transmission queue. Specifications that associate neighboring nodes with outducts are termed egress plans. They are retained in ION's unicast forwarding database.
Static routes
ION can be configured to forward to some specified node all bundles that are destined for a given node to which no dynamic route can be discovered from an examination of the contact graph, as described later. Static routing is implemented by means of the \"exit\" mechanism described below.
Unicast
When the destination of a bundle is a single node that is registered within a known \"singleton endpoint\" (that is, an endpoint that is known to have exactly one member), then transmission of that bundle is termed unicast. For this purpose, the destination endpoint ID must be a URI formed in either the \"dtn\" scheme (e.g., dtn://bobsmac/mail) or the \"ipn\" scheme (e.g., ipn:913.11).
Exits
When unicast routes must be computed to nodes for which no contact plan information is known (e.g., the size of the network makes it impractical to distribute all Contact and Range information for all nodes to every node, or the destination nodes don't participate in Contact Graph Routing at all), the job of computing routes to all nodes may be partitioned among multiple exit nodes. Each exit is responsible for managing routing information (for example, a comprehensive contact graph) for some subset of the total network population -- a group comprising all nodes whose node numbers fall within the range of node numbers assigned to the exit. A bundle destined for a node for which no dynamic route can be computed from the local node's contact graph may be routed to the exit node for the group within whose range the destination's node number falls. Exits are defined in ION's unicast forwarding database. (Note that the exit implements static routes in ION in addition to improving scalability.)
Multicast
When the destination of a bundle is all nodes that are registered within a known \"multicast endpoint\" (that is, an endpoint that is not known to have exactly one member), then transmission of that bundle is termed multicast. For this purpose (in ION), the destination endpoint ID must be a URI formed in the \"imc\" scheme (e.g., imc:913.11).
Multicast Groups
A multicast group is the set of all nodes in the network that are members of a given multicast endpoint. Forwarding a bundle to all members of its destination multicast endpoint is the responsibility of all of the multicast-aware nodes of the network. These nodes are additionally configured to be nodes of a single multicast spanning tree overlaid onto the dtnet. A single multicast tree serves to forward bundles to all multicast groups: each node of the tree manages petitions indicating which of its \"relatives\" (parent and children) are currently interested in bundles destined for each multicast endpoint, either natively (due to membership in the indicated group) or on behalf of more distant relatives.
"},{"location":"ION-Guide/#unicast","title":"Unicast","text":"We begin unicast route computation by attempting to compute a dynamic route to the bundle's final destination node. The details of this algorithm are described in the section on Contact Graph Routing, below.
If no dynamic route can be computed, but the final destination node is a \"neighboring\" node that is directly reachable, then we assume that taking this direct route is the best strategy unless transmission to that neighbor is flagged as \"blocked\" for network operations purposes.
Otherwise we must look for a static route. If the bundle's destination node number is in one of the ranges of node numbers assigned to exit nodes, then we forward the bundle to the exit node for the smallest such range. (If the exit node is a neighbor and transmission to that neighbor is not blocked, we simply queue the bundle for transmission to that neighbor; otherwise we similarly look up the static route for the exit node until eventually we resolve to some egress plan.)
If we can determine neither a dynamic route nor a static route for this bundle, but the reason for this failure was transmission blockage that might be resolved in the future, then the bundle is placed in a \"limbo\" list for future re-forwarding when transmission to some node is \"unblocked.\"
Otherwise, the bundle cannot be forwarded. If custody transfer is requested for the bundle, we send a custody refusal to the bundle's current custodian; in any case, we discard the bundle.
"},{"location":"ION-Guide/#multicast","title":"Multicast","text":"Multicast route computation is much simpler.
A bundle whose destination endpoint cites a multicast group, whether locally sourced or received from another node:
Is delivered immediately, if the local node is a member of the indicated endpoint.
End-to-end delivery of data can fail in many ways, at different layers of the stack. When delivery fails, we can either accept the communication failure or retransmit the data structure that was transmitted at the stack layer at which the failure was detected. ION is designed to enable retransmission at multiple layers of the stack, depending on the preference of the end user application.
At the lowest stack layer that is visible to ION, the convergence-layer protocol, failure to deliver one or more segments due to segment loss or corruption will trigger segment retransmission if a \"reliable\" convergence-layer protocol is in use: LTP \"red-part\" transmission or TCP (including Bundle Relay Service, which is based on TCP)1.
Segment loss may be detected and signaled via NAK by the receiving entity, or it may only be detected at the sending entity by expiration of a timer prior to reception of an ACK. Timer interval computation is well understood in a TCP environment, but it can be a difficult problem in an environment of scheduled contacts as served by LTP. The round-trip time for an acknowledgment dialogue may be simply twice the one-way light time (OWLT) between sender and receiver at one moment, but it may be hours or days longer at the next moment due to cessation of scheduled contact until a future contact opportunity. To account for this timer interval variability in retransmission, the ltpclock task infers the initiation and cessation of LTP transmission, to and from the local node, from changes in the current xmit and recv data rates in the corresponding Neighbor objects. This controls the dequeuing of LTP segments for transmission by underlying link service adapter(s) and it also controls suspension and resumption of timers, removing the effects of contact interruption from the retransmission regime. For a further discussion of this mechanism, see the section below on LTP Timeout Intervals.
Note that the current OWLT in Neighbor objects is also used in the computation of the nominal expiration times of timers and that ltpclock is additionally the agent for LTP segment retransmission based on timer expiration.
It is, of course, possible for the nominally reliable convergence-layer protocol to fail altogether: a TCP connection might be abruptly terminated, or an LTP transmission might be canceled due to excessive retransmission activity (again possibly due to an unexpected loss of connectivity). In this event, BP itself detects the CL protocol failure and re-forwards all bundles whose acquisition by the receiving entity is presumed to have been aborted by the failure. This re-forwarding is initiated in different ways for different CL protocols, as implemented in the CL input and output adapter tasks. If immediate re-forwarding is impossible because transmission to all potentially viable neighbors is blocked, the affected bundles are placed in the limbo list for future re-forwarding when transmission to some node is unblocked.
In addition to the implicit forwarding failure detected when a CL protocol fails, the forwarding of a bundle may be explicitly refused by the receiving entity, provided the bundle is flagged for custody transfer service. A receiving node's refusal to take custody of a bundle may have any of a variety of causes: typically the receiving node either (a) has insufficient resources to store and forward the bundle, (b) has no route to the destination, or (c) will have no contact with the next hop on the route before the bundle's TTL has expired. In any case, a \"custody refusal signal\" (packaged in a bundle) is sent back to the sending node, which must re-forward the bundle in hopes of finding a more suitable route.
Alternatively, failure to receive a custody acceptance signal within some convergence-layer-specified or application-specified time interval may also be taken as an implicit indication of forwarding failure. Here again, when BP detects such a failure it attempts to re-forward the affected bundle, placing the bundle in the limbo list if re-forwarding is currently impossible.
In the worst case, the combined efforts of all the retransmission mechanisms in ION are not enough to ensure delivery of a given bundle, even when custody transfer is requested. In that event, the bundle's \"time to live\" will eventually expire while the bundle is still in custody at some node: the bpclock task will send a bundle status report to the bundle's report-to endpoint, noting the TTL expiration, and destroy the bundle. The report-to endpoint, upon receiving this report, may be able to initiate application-layer retransmission of the original application data unit in some way. This final retransmission mechanism is wholly application-specific, however.
"},{"location":"ION-Guide/#rate-control","title":"Rate Control","text":"In the Internet, the rate of transmission at a node can be dynamically negotiated in response to changes in level of activity on the link, to minimize congestion. On deep space links, signal propagation delays (distances) may be too great to enable effective dynamic negotiation of transmission rates. Fortunately, deep space links are operationally reserved for use by designated pairs of communicating entities over pre-planned periods of time at pre-planned rates. Provided there is no congestion inherent in the contact plan, congestion in the network can be avoided merely by adhering to the planned contact periods and data rates. Rate control in ION serves this purpose.
While the system is running, transmission and reception of bundles is constrained by the current capacity in the throttle of each convergence-layer manager. Completed bundle transmission activity reduces the current capacity of the applicable throttle by the capacity consumption computed for that bundle. This reduction may cause the throttle's current capacity to become negative. Once the current capacity of the applicable throttle goes negative, activity is blocked until non-negative capacity has been restored by bpclock.
Once per second, the bpclock task increases the current capacity of each throttle by one second's worth of traffic at the nominal data rate for transmission to that node, thus enabling some possibly blocked bundle transmission and reception to proceed.
bpclock revises all throttles' nominal data rates once per second in accord with the current data rates in the corresponding Neighbor objects, as adjusted by rfxclock per the contact plan.
Note that this means that, for any neighboring node for which there are planned contacts, ION's rate control system will enable data flow only while contacts are active.
"},{"location":"ION-Guide/#flow-control","title":"Flow Control","text":"A further constraint on rates of data transmission in an ION-based network is LTP flow control. LTP is designed to enable multiple block transmission sessions to be in various stages of completion concurrently, to maximize link utilization: there is no requirement to wait for one session to complete before starting the next one. However, if unchecked this design principle could in theory result in the allocation of all memory in the system to incomplete LTP transmission sessions. To prevent complete storage resource exhaustion, we set a firm upper limit on the total number of outbound blocks that can be concurrently in transit at any given time. These limits are established by ltpadmin at node initialization time.
The maximum number of transmission sessions that may be concurrently managed by LTP therefore constitutes a transmission \"window\" -- the basis for a delay-tolerant, non-conversational flow control service over interplanetary links. Once the maximum number of sessions are in flight, no new block transmission session can be initiated -- regardless of how much outduct transmission capacity is provided by rate control -- until some existing session completes or is canceled.
Note that this consideration emphasizes the importance of configuring the aggregation size limits and session count limits of spans during LTP initialization to be consistent with the maximum data rates scheduled for contacts over those spans.
"},{"location":"ION-Guide/#storage-management","title":"Storage Management","text":"Congestion in a dtnet is the imbalance between data enqueuing and dequeuing rates that results in exhaustion of queuing (storage) resources at a node, preventing continued operation of the protocols at that node.
In ION, the affected queuing resources are allocated from notionally non-volatile storage space in the SDR data store and/or file system. The design of ION is required to prevent resource exhaustion by simply refusing to enqueue additional data that would cause it.
However, a BP router's refusal to enqueue received data for forwarding could result in costly retransmission, data loss, and/or the \"upstream\" propagation of resource exhaustion to other nodes. Therefore the ION design additionally attempts to prevent potential resource exhaustion by forecasting levels of queuing resource occupancy and reporting on any congestion that is predicted. Network operators, upon reviewing these forecasts, may revise contact plans to avert the anticipated resource exhaustion.
The non-volatile storage used by ION serves several purposes: it contains queues of bundles awaiting forwarding, transmission, and delivery; it contains LTP transmission and reception sessions, including the blocks of data that are being transmitted and received; it contains queues of LTP segments awaiting radiation; it may contain CFDP transactions in various stages of completion; and it contains protocol operational state information, such as configuration parameters, static routes, the contact graph, etc.
Effective utilization of non-volatile storage is a complex problem. Static pre-allocation of storage resources is in general less efficient (and also more labor-intensive to configure) than storage resource pooling and automatic, adaptive allocation: trying to predict a reasonable maximum size for every data storage structure and then rigidly enforcing that limit typically results in underutilization of storage resources and underperformance of the system as a whole. However, static pre-allocation is mandatory for safety-critical resources, where certainty of resource availability is more important than efficient resource utilization.
The tension between the two approaches is analogous to the tension between circuit switching and packet switching in a network: circuit switching results in underutilization of link resources and underperformance of the network as a whole (some peaks of activity can never be accommodated, even while some resources lie idle much of the time), but dedicated circuits are still required for some kinds of safety-critical communication.
So the ION data management design combines these two approaches (see 1.5 above for additional discussion of this topic):
The maximum projected occupancy of the node is the result of computing a congestion forecast for the node, by adding to the current occupancy all anticipated net increases and decreases from now until some future time, termed the horizon for the forecast.
The forecast horizon is indefinite -- that is, \"forever\" -- unless explicitly declared by network management via the ionadmin utility program. The difference between the horizon and the current time is termed the interval of the forecast.
Net occupancy increases and decreases are of four types:
The type-1 anticipated net increase (total data origination) is computed by multiplying the node's projected rate of local data production, as declared via an ionadmin command, by the interval of the forecast. Similarly, the type-4 anticipated net decrease (total data delivery) is computed by multiplying the node's projected rate of local data consumption, as declared via an ionadmin command, by the interval of the forecast. Net changes of types 2 and 3 are computed by multiplying inbound and outbound data rates, respectively, by the durations of all periods of planned communication contact that begin and/or end within the interval of the forecast.
Congestion forecasting is performed by the ionwarn utility program. ionwarn may be run independently at any time; in addition, the ionadmin utility program automatically runs ionwarn immediately before exiting if it executed any change in the contact plan, the forecast horizon, or the node's projected rates of local data production or consumption. Moreover, the rfxclock daemon program also runs ionwarn automatically whenever any of the scheduled reconfiguration events it dispatches result in contact state changes that might alter the congestion forecast.
If the final result of the forecast computation -- the maximum projected occupancy of the node over the forecast interval -- is less than the total protocol traffic allocation, then no congestion is forecast. Otherwise, a congestion forecast status message is logged noting the time at which maximum projected occupancy is expected to equal the total protocol traffic allocation.
Congestion control in ION, then, has two components:
First, ION's congestion detection is anticipatory (via congestion forecasting) rather than reactive as in the Internet.
Anticipatory congestion detection is important because the second component -- congestion mitigation -- must also be anticipatory: it is the adjustment of communication contact plans by network management, via the propagation of revised schedules for future contacts.
(Congestion mitigation in an ION-based network is likely to remain mostly manual for many years to come, because communication contact planning involves much more than orbital dynamics: science operations plans, thermal and power constraints, etc. It will, however, rely on the automated rate control features of ION, discussed above, which ensure that actual network operations conform to established contact plans.)
Rate control in ION is augmented by admission control. ION tracks the sum of the sizes of all zero-copy objects currently residing in the heap and file system at any moment. Whenever any protocol implementation attempts to create or extend a ZCO in such a way that total heap or file occupancy would exceed an upper limit asserted for the node, that attempt is either blocked until ZCO space becomes available or else rejected altogether.
"},{"location":"ION-Guide/#optimizing-an-ion-based-network","title":"Optimizing an ION-based network","text":"ION is designed to deliver critical data to its final destination with as much certainty as possible (and optionally as soon as possible), but otherwise to try to maximize link utilization. The delivery of critical data is expedited by contact graph routing and bundle prioritization as described elsewhere. Optimizing link utilization, however, is a more complex problem.
If the volume of data traffic offered to the network for transmission is less than the capacity of the network, then all offered data should be successfully delivered3. But in that case the users of the network are paying the opportunity cost of whatever portion of the network capacity was not used.
Offering a data traffic volume that is exactly equal to the capacity of the network is in practice infeasible. TCP in the Internet can usually achieve this balance because it exercises end-to-end flow control: essentially, the original source of data is blocked from offering a message until notified by the final destination that transmission of this message can be accommodated given the current negotiated data rate over the end-to-end path (as determined by TCP's congestion control mechanisms). In a delay-tolerant network no such end-to-end negotiated data rate may exist, much less be knowable, so such precise control of data flow is impossible.4
The only alternative: the volume of traffic offered by the data source must be greater than the capacity of the network and the network must automatically discard excess traffic, shedding lower-priority data in preference to high-priority messages on the same path.
ION discards excess traffic proactively when possible and reactively when necessary.
Proactive data triage occurs when ION determines that it cannot compute a route that will deliver a given bundle to its final destination prior to expiration of the bundle's Time To Live (TTL). That is, a bundle may be discarded simply because its TTL is too short, but more commonly it will be discarded because the planned contacts to whichever neighboring node is first on the path to the destination are already fully subscribed: the queue of bundles awaiting transmission to that neighbor is already so long as to consume the entire capacity of all announced opportunities to transmit to it. Proactive data triage causes the bundle to be immediately destroyed as one for which there is \"No known route to destination from here.\"
The determination of the degree to which a contact is subscribed is based not only on the aggregate size of the queued bundles but also on the estimated aggregate size of the overhead imposed by all the convergence-layer (CL) protocol data units -- at all layers of the underlying stack -- that encapsulate those bundles: packet headers, frame headers, etc. This means that the accuracy of this overhead estimate will affect the aggressiveness of ION's proactive data triage:
Essentially, all reactive data triage -- the destruction of bundles due to TTL expiration prior to successful delivery to the final destination -- occurs when the network conveys bundles at lower net rates than were projected during route computation. These performance shortfalls can have a variety of causes:
Some level of data triage is essential to cost-effective network utilization, and proactive triage is preferable because its effects can be communicated immediately to users, improving user control over the use of the network. Optimizing an ION-based network therefore amounts to managing for a modicum of proactive data triage and as little reactive data triage as possible. It entails the following:
As an example, suppose the local node uses LTP over CCSDS Telemetry to send bundles. The immediate convergence-layer protocol is LTP, but the total overhead per CL \"frame\" (in this case, per LTP segment) will include not only the size of the LTP header (nominally 5 bytes) but also the size of the encapsulating space packet header (nominally 6 bytes) and the overhead imposed by the outer encapsulating TM frame.
Suppose each LTP segment is to be wrapped in a single space packet, which is in turn wrapped in a single TM frame, and Reed-Solomon encoding is applied. An efficient TM frame size is 1115 bytes, with an additional 160 bytes of trailing Reed-Solomon encoding and another 4 bytes of leading pseudo-noise code. The frame would contain a 6-byte TM frame header, a 6-byte space packet header, a 5-byte LTP segment header, and 1098 bytes of some LTP transmission block.
So the number of \"payload bytes per frame\" in this case would be 1098 and the number of \"overhead bytes per frame\" would be 4 + 6 + 6 + 5 + 160 = 181. Nominal total transmission overhead on the link would be 181 / 1279 = about 14%. 2. Synchronizing nodes' clocks as accurately as possible, so that timing margins configured to accommodate clock error can be kept as close to zero as possible. 3. Setting the LTP session limit and block size limit as generously as possible (whenever LTP is at the convergence layer), to assure that LTP flow control does not constrain data flow to rates below those supported by BP rate control. 4. Setting ranges (one-way light times) and queuing delays as accurately as possible, to prevent unnecessary retransmission. Err on the side of pessimism -- that is, overestimate a little. 5. Communicating changes in configuration -- especially contact plans -- to all nodes as far in advance of the time they take effect as possible. 6. Providing all nodes with as much storage capacity as possible for queues of bundles awaiting transmission.
"},{"location":"ION-Guide/#bpltp-detail-how-they-work","title":"BP/LTP Detail -- How They Work","text":"Although the operation of BP/LTP in ION is complex in some ways, virtually the entire system can be represented in a single diagram. The interactions among all of the concurrent tasks that make up the node -- plus a Remote AMS task or CFDP UT-layer task, acting as the application at the top of the stack -- are shown below. (The notation is as used earlier but with semaphores added. Semaphores are shown as small circles, with arrows pointing into them signifying that the semaphores are being given and arrows pointing out of them signifying that the semaphores are being taken.)
Figure 7 ION node functional overview
Further details of the BP/LTP data structures and flow of control and data appear on the following pages. (For specific details of the operation of the BP and LTP protocols as implemented by the ION tasks, such as the nature of report-initiated retransmission in LTP, please see the protocol specifications. The BP specification is documented in Internet RFC 5050, while the LTP specification is documented in Internet RFC 5326.)
"},{"location":"ION-Guide/#databases","title":"Databases","text":"Figure 8: Bundle protocol database
Figure 9: Licklider transmission protocol database
"},{"location":"ION-Guide/#control-and-data-flow","title":"Control and data flow","text":""},{"location":"ION-Guide/#bundle-protocol","title":"Bundle Protocol","text":"Figure 10 BP forwarder
Figure 11 BP convergence layer output
"},{"location":"ION-Guide/#ltp","title":"LTP","text":"Figure 12 LTP transmission metering
Figure 13 LTP link service output
Figure 14 LTP link service input
"},{"location":"ION-Guide/#contact-graph-routing-cgr","title":"Contact Graph Routing (CGR)","text":"CGR is a dynamic routing system that computes routes through a time-varying topology of scheduled communication contacts in a DTN network. It is designed to support operations in a space network based on DTN, but it also could be used in terrestrial applications where operation according to a predefined schedule is preferable to opportunistic communication, as in a low-power sensor network.
The basic strategy of CGR is to take advantage of the fact that, since communication operations are planned in detail, the communication routes between any pair of \"bundle agents\" in a population of nodes that have all been informed of one another's plans can be inferred from those plans rather than discovered via dialogue (which is impractical over long-one-way-light-time space links).
"},{"location":"ION-Guide/#contact-plan-messages","title":"Contact Plan Messages","text":"CGR relies on accurate contact plan information provided in the form of contact plan messages that currently are only read from ionrc files and processed by ionadmin, which retains them in a non-volatile contact plan in the RFX database, in ION's SDR data store.
Contact plan messages are of two types: contact messages and range messages.
Each contact message has the following content:
Each range message has the following content:
Note that range messages may be used to declare that the \"distance\" in light seconds between nodes A and B is different in the B\ud83e\udc6aA direction from the distance in the A\ud83e\udc6aB direction. While direct radio communication between A and B will not be subject to such asymmetry, it's possible for connectivity established using other convergence-layer technologies to take different physical paths in different directions, with different signal propagation delays.
"},{"location":"ION-Guide/#routing-tables","title":"Routing Tables","text":"Each node uses Range and Contact messages in the contact plan to build a \\\"routing table\\\" data structure.
The routing table constructed locally by each node in the network is a list of entry node lists, one route list for every other node D in the network that is cited in any Contact or Range in the contact plan. Entry node lists are computed as they are needed, and the maximum number of entry node lists resident at a given time is the number of nodes that are cited in any Contacts or Ranges in the contact plan. Each entry in the entry node list for node D is a list of the neighbors of local node X; included with each entry of the entry node list is a list one or more routes to D through the indicated neighbor, termed a route list.
Each route in the route list for node D identifies a path to destination node D, from the local node, that begins with transmission to one of the local node's neighbors in the network-- the initial receiving node for the route, termed the route's entry node.
For any given route, the contact from the local node to the entry node constitutes the initial transmission segment of the end-to-end path to the destination node. Additionally noted in each route object are all of the other contacts that constitute the remaining segments of the route's end-to-end path.
Each route object also notes the forwarding cost for a bundle that is forwarded along this route. In this version of ION, CGR is configured to deliver bundles as early as possible, so best-case final delivery time is used as the cost of a route. Other metrics might be substituted for final delivery time in other CGR implementations. NOTE, however, that if different metrics are used at different nodes along a bundle's end-to-end path it becomes impossible to prevent routing loops that can result in non-delivery of the data.
Finally, each route object also notes the route's termination time, the time after which the route will become moot due to the termination of the earliest-ending contact in the route.
"},{"location":"ION-Guide/#key-concepts","title":"Key Concepts","text":""},{"location":"ION-Guide/#expiration-time","title":"Expiration time","text":"Every bundle transmitted via DTN has a time-to-live (TTL), the length of time after which the bundle is subject to destruction if it has not yet been delivered to its destination. The expiration time of a bundle is computed as its creation time plus its TTL. When computing the next-hop destination for a bundle that the local bundle agent is required to forward, there is no point in selecting a route that can\\'t get the bundle to its final destination prior to the bundle's expiration time.
"},{"location":"ION-Guide/#owlt-margin","title":"OWLT margin","text":"One-way light time (OWLT) -- that is, distance -- is obviously a factor in delivering a bundle to a node prior to a given time. OWLT can actually change during the time a bundle is en route, but route computation becomes intractably complex if we can\\'t assume an OWLT \\\"safety margin\\\" -- a maximum delta by which OWLT between any pair of nodes can change during the time a bundle is in transit between them.
We assume that the maximum rate of change in distance between any two nodes in the network is about 150,000 miles per hour, which is about 40 miles per second. (This was the speed of the Helios spacecraft, the fastest man-made object launched to date.)
At this speed, the distance between any two nodes that are initially separated by a distance of N light seconds will increase by a maximum of 80 miles per second of transit (in the event that they are moving in opposite directions). This will result in data arrival no later than roughly (N + 2Q) seconds after transmission -- where the \"OWLT margin\" value Q is (40 * N) divided by 186,000 -- rather than just N seconds after transmission as would be the case if the two nodes were stationary relative to each other. When computing the expected time of arrival of a transmitted bundle we simply use N + 2Q, the most pessimistic case, as the anticipated total in-transit time.
"},{"location":"ION-Guide/#capacity","title":"Capacity","text":"The capacity of a contact is the product of its data transmission rate (in bytes per second) and its duration (stop time minus start time, in seconds).
"},{"location":"ION-Guide/#estimated-capacity-consumption","title":"Estimated capacity consumption","text":"The size of a bundle is the sum of its payload size and its header size5, but bundle size is not the only lien on the capacity of a contact. The total estimated volume consumption (or \"EVC\") for a bundle is the sum of the sizes of the bundle's payload and header and the estimated convergence-layer overhead. For a bundle whose header is of size M and whose payload is of size N, the estimated convergence-layer overhead is defined as 3% of (M+N), or 100 bytes, whichever is larger.
"},{"location":"ION-Guide/#residual-capacity","title":"Residual capacity","text":"The residual capacity of a given contact between the local node and one of its neighbors, as computed for a given bundle, is the sum of the capacities of that contact and all prior scheduled contacts between the local node and that neighbor, less the sum of the ECCs of all bundles with priority equal to or higher than the priority of the subject bundle that are currently queued on the outduct for transmission to that neighbor.
"},{"location":"ION-Guide/#excluded-neighbors","title":"Excluded neighbors","text":"A neighboring node C that refuses custody of a bundle destined for some remote node D is termed an excluded neighbor for (that is, with respect to computing routes to) D. So long as C remains an excluded neighbor for D, no bundles destined for D will be forwarded to C -- except that occasionally (once per lapse of the RTT between the local node and C) a custodial bundle destined for D will be forwarded to C as a \"probe bundle\". C ceases to be an excluded neighbor for D as soon as it accepts custody of a bundle destined for D.
"},{"location":"ION-Guide/#critical-bundles","title":"Critical bundles","text":"A Critical bundle is one that absolutely has got to reach its destination and, moreover, has got to reach that destination as soon as is physically possible6.
For an ordinary non-Critical bundle, the CGR dynamic route computation algorithm uses the routing table to select a single neighboring node to forward the bundle through. It is possible, though, that due to some unforeseen delay the selected neighbor may prove to be a sub-optimal forwarder: the bundle might arrive later than it would have if another neighbor had been selected, or it might not even arrive at all.
For Critical bundles, the CGR dynamic route computation algorithm causes the bundle to be inserted into the outbound transmission queues for transmission to all neighboring nodes that can plausibly forward the bundle to its final destination. The bundle is therefore guaranteed to travel over the most successful route, as well as over all other plausible routes. Note that this may result in multiple copies of a Critical bundle arriving at the final destination.
"},{"location":"ION-Guide/#dynamic-route-selection-algorithm","title":"Dynamic Route Selection Algorithm","text":"Given a bundle whose destination is node D, we proceed as follows.
First, if no contacts in the contact plan identify transmission to node D, then we cannot use CGR to find a route for this bundle; CGR route selection is abandoned.
Next, if the contact plan has been modified in any way since routes were computed for any nodes, we discard all routes for all nodes and authorize route recomputation. (The contact plan changes may have invalidated any or all of those earlier computations.)
We create an empty list of Proximate Nodes (network neighbors) to send the bundle to.
We create a list of Excluded Nodes, i.e., nodes through which we will not compute a route for this bundle. The list of Excluded Nodes is initially populated with:
If all routes computed for node D have been discarded due to contact plan modification, then we must compute a new list of all routes from the local node to D. To do so:
We perform several Dijkstra searches within this graph, one search for each of the local node's neighbors. On each search we find the lowest-cost route that begins at the root of the graph and ends at the terminal vertex. Each time a route is computed, we add it to the list of routes for that route's entry node and then remove from further consideration all contacts from the local node to the entry node of that route.
The lowest-cost route computed during a search is the one that is found to have the earliest best-case delivery time, where the best-case delivery time characterizing a route is given by the time at which a bundle would arrive at node D if transmitted at the earliest possible moment of the last contact in the route prior to the terminal vertex.
We next examine all of the routes that are currently computed for transmission of bundles to node D.
For each route that is not ignored, the route's entry node is added to the list of Proximate Nodes for this bundle. Associated with the entry node number in this list entry are the best-case final delivery time of the route, the total number of \"hops\" in the route's end-to-end path, and the forfeit time for transmission to this node. Forfeit time is the route's termination time, the time by which the bundle must have been transmitted to this node in order to have any chance of being forwarded on this route.
If, at the end of this procedure, the Proximate Nodes list is empty, then we have been unable to use CGR to find a route for this bundle; CGR route selection is abandoned.
Otherwise:
Otherwise, the bundle is enqueued for transmission on the outduct to the most preferred neighbor in the Proximate Nodes list:
If one of the nodes in this list is associated with a best-case delivery time that is earlier than that of all other nodes in the list, then it is the most preferred neighbor.
Conveyance of a bundle from source to destination through a DTN can fail in a number of ways, many of which are best addressed by means of the Delivery Assurance mechanisms described earlier. Failures in Contact Graph Routing, specifically, occur when the expectations on which routing decisions are based prove to be false. These failures of information fall into two general categories: contact failure and custody refusal.
"},{"location":"ION-Guide/#contact-failure","title":"Contact Failure","text":"A scheduled contact between some node and its neighbor on the end-to-end route may be initiated later than the originally scheduled start time, or be terminated earlier than the originally scheduled stop time, or be canceled altogether. Alternatively, the available capacity for a contact might be overestimated due to, for example, diminished link quality resulting in unexpectedly heavy retransmission at the convergence layer. In each of these cases, the anticipated transmission of a given bundle during the affected contact may not occur as planned: the bundle might expire before the contact's start time, or the contact's stop time might be reached before the bundle has been transmitted.
For a non-Critical bundle, we handle this sort of failure by means of a timeout: if the bundle is not transmitted prior to the forfeit time for the selected Proximate Node, then the bundle is removed from its outbound transmission queue and the Dynamic Route Computation Algorithm is re-applied to the bundle so that an alternate route can be computed.
"},{"location":"ION-Guide/#custody-refusal","title":"Custody refusal","text":"A node that receives a bundle may find it impossible to forward it, for any of several reasons: it may not have enough storage capacity to hold the bundle, it may be unable to compute a forward route (static, dynamic, or default) for the bundle, etc. Such bundles are simply discarded, but discarding any such bundle that is marked for custody transfer will cause a custody refusal signal to be returned to the bundle's current custodian.
When the affected bundle is non-Critical, the node that receives the custody refusal re-applies the Dynamic Route Computation Algorithm to the bundle so that an alternate route can be computed -- except that in this event the node from which the bundle was originally directly received is omitted from the initial list of Excluded Nodes. This enables a bundle that has reached a dead end in the routing tree to be sent back to a point at which an altogether different branch may be selected.
For a Critical bundle no mitigation of either sort of failure is required or indeed possible: the bundle has already been queued for transmission on all plausible routes, so no mechanism that entails re-application of CGR's Dynamic Route Computation Algorithm could improve its prospects for successful delivery to the final destination. However, in some environments it may be advisable to re-apply the Dynamic Route Computation Algorithm to all Critical bundles that are still in local custody whenever a new Contact is added to the contact graph: the new contact may open an additional forwarding opportunity for one or more of those bundles.
"},{"location":"ION-Guide/#remarks","title":"Remarks","text":"The CGR routing procedures respond dynamically to the changes in network topology that the nodes are able know about, i.e., those changes that are subject to mission operations control and are known in advance rather than discovered in real time. This dynamic responsiveness in route computation should be significantly more effective and less expensive than static routing, increasing total data return while at the same time reducing mission operations cost and risk.
Note that the non-Critical forwarding load across multiple parallel paths should be balanced automatically:
Although the route computation procedures are relatively complex they are not computationally difficult. The impact on computation resources at the vehicles should be modest.
"},{"location":"ION-Guide/#ltp-timeout-intervals","title":"LTP Timeout Intervals","text":"Suppose we've got Earth ground station ES that is currently in view of Mars but will be rotating out of view (\"Mars-set\") at some time T1 and rotating back into view (\"Mars-rise\") at time T3. Suppose we've also got Mars orbiter MS that is currently out of the shadow of Mars but will move behind Mars at time T2, emerging at time T4. Let's also suppose that ES and MS are 4 light-minutes apart (Mars is at its closest approach to Earth). Finally, for simplicity, let's suppose that both ES and MS want to be communicating at every possible moment (maximum link utilization) but never want to waste any electricity.
Neither ES nor MS wants to be wasting power on either transmitting or receiving at a time when either Earth or Mars will block the signal.
ES will therefore stop transmitting at either T1 or (T2 - 4 minutes), whichever is earlier; call this time Tet0. It will stop receiving -- that is, power off the receiver -- at either T1 or (T2 + 4 minutes), whichever is earlier; call this time Ter0. It will resume transmitting at either T3 or (T4 - 4 minutes), whichever is late, and it will resume reception at either T3 or (T4 + 4 minutes), whichever is later; call these times Tet1 and Ter1.
Similarly, MS will stop transmitting at either T2 or (T1 - 4 minutes), whichever is earlier; call this time Tmt0. It will stop receiving -- that is, power off the receiver -- at either T2 or (T1 + 4 minutes), whichever is earlier; call this time Tmr0. It will resume transmitting at either T4 or (T3 - 4 minutes), whichever is later, and it will resume reception at either T4 or (T3 + 4 minutes), whichever is later; call these times Tmt1 and Tmr1.
By making sure that we don't transmit when the signal would be blocked, we guarantee that anything that is transmitted will arrive at a time when it can be received. Any reception failure is due to data corruption en route.
So the moment of transmission of an acknowledgment to any message is always equal to the moment the original message was sent plus some imputed outbound queuing delay QO1 at the sending node, plus 4 minutes, plus some imputed inbound and outbound queuing delay QI1 + QO2 at the receiving node. The nominally expected moment of reception of this acknowledgment is that moment of transmission plus 4 minutes, plus some imputed inbound queuing delay QI2 at the original sending node. That is, the timeout interval is 8 minutes + QO1 + QI1 + QO2 + QO2 -- unless this moment of acknowledgement transmission is during an interval when the receiving node is not transmitting, for whatever reason. In this latter case, we want to suspend the acknowledgment timer during any interval in which we know the remote node will not be transmitting. More precisely, we want to add to the timeout interval the time difference between the moment of message arrival and the earliest moment at which the acknowledgment could be sent, i.e., the moment at which transmission is resumed7.
So the timeout interval Z computed at ES for a message sent to MS at time TX is given by:
Z = QO1 + 8 + QI1 + ((TA = TX + 4) > Tmt0 && TA < Tmt1) ?\nTmt1 - TA: 0) + QI2 + QO2\nThis can actually be computed in advance (at time TX) if T1, T2, T3, and T4 are known and are exposed to the protocol engine.
If they are not exposed, then Z must initially be estimated to be (2 * the one-way light time) + QI + QO. The timer for Z must be dynamically suspended at time Tmt0 in response to a state change as noted by ltpclock. Finally, the timer must be resumed at time Tmt1 (in response to another state change as noted by ltpclock), at which moment the correct value for Z can be computed.
"},{"location":"ION-Guide/#cfdp","title":"CFDP","text":"The ION implementation of CFDP is very simple, because only Class-1 (Unacknowledged) functionality is implemented: the store-and-forward routing performed by Bundle Protocol makes the CFDP Extended Procedures unnecessary and the inter-node reliability provided by the CL protocol underneath BP -- in particular, by LTP -- makes the CFDP Acknowledged Procedures unnecessary. All that CFDP is required to do is segment and reassemble files, interact with the underlying Unitdata Transfer layer -- BP/LTP -- to effect the transmission and reception of file data segments, and handle CFDP metadata including filestore requests. CFDP-ION does all this, including support for cancellation of a file transfer transaction by cancellation of the transmission of the bundles encapsulating the transaction's protocol data units.
Note that all CFDP data transmission is \"by reference\", via the ZCO system, rather than \"by value\": the retransmission buffer for a bundle containing CFDP file data is an extent of the original file itself, not a copy retained in the ION database, and data received in bundles containing CFDP PDU is written immediately to the appropriate location in the reconstituted file rather than stored in the ION database. This minimizes the space needed for the database. In general, file transmission via CFDP is the most memory-efficient way to use ION in flight operations.
Figure 15 A CFDP-ION entity
"},{"location":"ION-Guide/#list-data-structures-lyst-sdrlist-smlist","title":"List data structures (lyst, sdrlist, smlist)","text":"Figure 16 ION list data structures
"},{"location":"ION-Guide/#psm-partition-structure","title":"PSM Partition Structure","text":"Figure 17 psm partition structure
"},{"location":"ION-Guide/#psm-and-sdr-block-structures","title":"PSM and SDR Block Structures","text":"Figure 18 psm and sdr block structures
"},{"location":"ION-Guide/#sdr-heap-structure","title":"SDR Heap Structure","text":"Figure 19 sdr heap structure
"},{"location":"ION-Guide/#operation","title":"Operation","text":"The ION source distribution contains a README.TXT file with details on building ION from source. For installations starts with the open source distribution ION-DTN, using the standard sequence of
./configure
Note: the user needs to clear all errors reported by the configure script before proceeding. The distribution contains a default \"Makefile\" at the top level of the distribution for developer use. The configure script must complete successfully to produce an updated Makefile.
will build ION and install it under /usr/local.
Users building from a clone of the repository need to use the command
before starting the installation.
The \"Build\" instructions shown in the following sections for each package are the instructions for building each package individually, for ION development purposes. The default installation target for the individual package build commands is /opt.
One compile-time option is applicable to all ION packages: the platform selection parameters --DVXWORKS and --DRTEMS affect the manner in which most task instantiation functions are compiled. For VXWORKS and RTEMS, these functions are compiled as library functions that must be identified by name in the platform's symbol table, while for Unix-like platforms they are compiled as main()functions.
"},{"location":"ION-Guide/#interplanetary-communication-infrastructure-ici_1","title":"Interplanetary Communication Infrastructure (ICI)","text":""},{"location":"ION-Guide/#compile-time-options","title":"Compile-time options","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DFSWSOURCE or --DSM_SEMBASEKEY=0xff13), will alter the functionality of ION as noted below.
PRIVATE_SYMTAB
This option causes ION to be built for VxWorks 5.4 or RTEMS with reliance on a small private local symbol table that is accessed by means of a function named sm_FindFunction. Both the table and the function definition are, by default, provided by the symtab.c source file, which is automatically included within the platform_sm.c source when this option is set. The table provides the address of the top-level function to be executed when a task for the indicated symbol (name) is to be spawned, together with the priority at which that task is to execute and the amount of stack space to be allocated to that task.
PRIVATE_SYMTAB is defined by default for RTEMS but not for VxWorks 5.4.
Absent this option, ION on VxWorks 5.4 must successfully execute the VxWorks symFindByName function in order to spawn a new task. For this purpose the entire VxWorks symbol table for the compiled image must be included in the image, and task priority and stack space allocation must be explicitly specified when tasks are spawned.
FSWLOGGER
This option causes the standard ION logging function, which simply writes all ION status messages to a file named ion.log in the current working directory, to be replaced (by #include) with code in the source file fswlogger.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
FSWCLOCK
This option causes the invocation of the standard time function within getUTCTime (in ion.c) to be replaced (by #include) with code in the source file fswutc.c, which might for example invoke a mission-specific function to read a value from the spacecraft clock. A file of this name must be in the inclusion path for the compiler.
FSWWDNAME
This option causes the invocation of the standard getcwd function within cfdpInit (in libcfdpP.c) to be replaced (by #include) with code in the source file wdname.c, which must in some way cause the mission-specific value of the current working directory name to be copied into cfdpdbBuf.workingDirectoryName. A file of this name must be in the inclusion path for the compiler.
FSWSYMTAB
If the PRIVATE_SYMTAB option is also set, then the FSWSYMTAB option causes the code in source file mysymtab.c to be included in platform_sm.c in place of the default symbol table access implementation in symtab.c. A file named mysymtab.c must be in the inclusion path for the compiler.
FSWSOURCE
This option simply causes FSWLOGGER, FSWCLOCK, FSWWDNAME, and FSWSYMTAB all to be set.
GDSLOGGER
This option causes the standard ION logging function, which simply writes all ION status messages to a file named ion.log in the current working directory, to be replaced (by #include) with code in the source file gdslogger.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
GDSSOURCE
This option simply causes GDSLOGGER to be set.
ION_OPS_ALLOC=*xx*
This option specifies the percentage of the total non-volatile storage space allocated to ION that is reserved for protocol operational state information, i.e., is not available for the storage of bundles or LTP segments. The default value is 20.
ION_SDR_MARGIN=*xx*
This option specifies the percentage of the total non-volatile storage space allocated to ION that is reserved simply as margin, for contingency use. The default value is 20.
The sum of ION_OPS_ALLOC and ION_SDR_MARGIN defines the amount of non-volatile storage space that is sequestered at the time ION operations are initiated: for purposes of congestion forecasting and prevention of resource oversubscription, this sum is subtracted from the total size of the SDR \"heap\" to determine the maximum volume of space available for bundles and LTP segments. Data reception and origination activities fail whenever they would cause the total amount of data store space occupied by bundles and segments to exceed this limit.
USING_SDR_POINTERS
This is an optimization option for the SDR non-volatile data management system: when set, it enables the value of any variable in the SDR data store to be accessed directly by means of a pointer into the dynamic memory that is used as the data store storage medium, rather than by reading the variable into a location in local stack memory. Note that this option must not be enabled if the data store is configured for file storage only, i.e., if the SDR_IN_DRAM flag was set to zero at the time the data store was created by calling sdr_load_profile. See the ionconfig(5) man page in Appendix A for more information.
NO_SDR_TRACE
This option causes non-volatile storage utilization tracing functions to be omitted from ION when the SDR system is built. It disables a useful debugging option but reduces the size of the executable software.
NO_PSM_TRACE
This option causes memory utilization tracing functions to be omitted from ION when the PSM system is built. It disables a useful debugging option but reduces the size of the executable software.
IN_FLIGHT
This option controls the behavior of ION when an unrecoverable error is encountered.
If it is set, then the status message \"Unrecoverable SDR error\" is logged and the SDR non-volatile storage management system is globally disabled: the current database access transaction is ended and (provided transaction reversibility is enabled) rolled back, and all ION tasks terminate.
Otherwise, the ION task that encountered the error is simply aborted, causing a core dump to be produced to support debugging.
SM_SEMKEY=0x*XXXX*
This option overrides the default value (0xee01) of the identifying \"key\" used in creating and locating the global ION shared-memory system mutex.
SVR4_SHM
This option causes ION to be built using svr4 shared memory as the pervasive shared-memory management mechanism. svr4 shared memory is selected by default when ION is built for any platform other than MinGW, VxWorks 5.4, or RTEMS. (For these latter operating systems all memory is shared anyway, due to the absence of a protected-memory mode.)
POSIX1B_SEMAPHORES
This option causes ION to be built using POSIX semaphores as the pervasive semaphore mechanism. POSIX semaphores are selected by default when ION is built for RTEMS but are otherwise not used or supported; this option enables the default to be overridden.
SVR4_SEMAPHORES
This option causes ION to be built using svr4 semaphores as the pervasive semaphore mechanism. svr4 semaphores are selected by default when ION is built for any platform other than MinGW (for which Windows event objects are used), VxWorks 5.4 (for which VxWorks native semaphores are the default choice), or RTEMS (for which POSIX semaphores are the default choice).
SM_SEMBASEKEY=0x*XXXX*
This option overrides the default value (0xee02) of the identifying \"key\" used in creating and locating the global ION shared-memory semaphore database, in the event that svr4 semaphores are used.
SEMMNI=*xxx*
This option declares to ION the total number of svr4 semaphore sets provided by the operating system, in the event that svr4 semaphores are used. It overrides the default value, which is 10 for Cygwin and 128 otherwise. (Changing this value typically entails rebuilding the O/S kernel.)
SEMMSL=*xxx*
This option declares to ION the maximum number of semaphores in each svr4 semaphore set, in the event that svr4 semaphores are used. It overrides the default value, which is 6 for Cygwin and 250 otherwise. (Changing this value typically entails rebuilding the O/S kernel.)
SEMMNS=*xxx*
This option declares to ION the total number of svr4 semaphores that the operating system can support; the maximum possible value is SEMMNI x SEMMSL. It overrides the default value, which is 60 for Cygwin and 32000 otherwise. (Changing this value typically entails rebuilding the O/S kernel.)
ION_NO_DNS
This option causes the implementation of a number of Internet socket I/O operations to be omitted for ION. This prevents ION software from being able to operate over Internet connections, but it prevents link errors when ION is loaded on a spacecraft where the operating system does not include support for these functions.
ERRMSGS_BUFSIZE=*xxxx*
This option set the size of the buffer in which ION status messages are constructed prior to logging. The default value is 4 KB.
SPACE_ORDER=*x*
This option declares the word size of the computer on which the compiled ION software will be running: it is the base-2 log of the number of bytes in an address. The default value is 2, i.e., the size of an address is 2^2^ = 4 bytes. For a 64-bit machine, SPACE_ORDER must be declared to be 3, i.e., the size of an address is 2^3^ = 8 bytes.
NO_SDRMGT
This option enables the SDR system to be used as a data access transaction system only, without doing any dynamic management of non-volatile data. With the NO_SDRMGT option set, the SDR system library can (and in fact must) be built from the sdrxn.c source file alone.
DOS_PATH_DELIMITER
This option causes ION_PATH_DELIMITER to be set to '\\' (backslash), for use in construction path names. The default value of ION_PATH_DELIMITER is '/' (forward slash, as is used in Unix-like operating systems).
"},{"location":"ION-Guide/#build","title":"Build","text":"To build ICI for a given deployment platform:
Decide where you want ION's executables, libraries, header files, etc. to be installed. The ION makefiles all install their build products to subdirectories (named bin, lib, include, man, man/man1, man/man3, man/man5) of an ION root directory, which by default is the directory named /opt. If you wish to use the default build configuration, be sure that the default directories (/opt/bin, etc.) exist; if not, select another ION root directory name -- this document will refer to it as $OPT -- and create the subdirectories as needed. In any case, make sure that you have read, write, and execute permission for all of the ION installation directories and that:
The directory /$OPT/bin is in your execution path.
Edit the Makefile in ion/ici:
Make sure PLATFORMS is set to the appropriate platform name, e.g., x86-redhat, sparc-sol9, etc.
Set OPT to the directory where you want to install the ici packages you build, if other than \"/opt\" (for example: /usr/local).
Then:
cd ion/ici\nsudo make\nsudo make install\nThree types of files are used to provide the information needed to perform global configuration of the ION protocol stack: the ION system configuration (or ionconfig) file, the ION administration command (ionrc) file, and the ION security configuration (ionsecrc) file. For details, see the man pages for ionconfig(5), ionrc(5), and ionsecrc(5) in Appendix A.
Normally the instantiation of ION on a given computer establishes a single ION node on that computer, for which hard-coded values of wmKey and sdrName (see ionconfig(5)) are used in common by all executables to assure that all elements of the system operate within the same state space. For some purposes, however, it may be desirable to establish multiple ION nodes on a single workstation. (For example, constructing an entire self-contained DTN network on a single machine may simplify some kinds of regression testing.) ION supports this configuration option as follows:
sdrWmSize or default. If any later ION instance launched with sdrWmSize exceeding the first ION instance, it will result in crash upon launch. It is further recommended that all ION instances running simultaneously on a single host should set their sdrWmSize the same.The executable programs used in operation of the ici component of ION include:
Each time it is executed, ionadmin computes a new congestion forecast and, if a congestion collapse is predicted, invokes the node's congestion alarm script (if any). ionadmin also establishes the node number for the local node and starts/stops the rfxclock task, among other functions. For further details, see the man pages for ionadmin(1), ionsecadmin(1), rfxclock(1), sdrmend(1), sdrwatch(1), and psmwatch(1) in Appendix A.
"},{"location":"ION-Guide/#test","title":"Test","text":"Six test executables are provided to support testing and debugging of the ICI component of ION:
For details, see the man pages for file2sdr(1), sdr2file(1), psmshell(1), file2sm(1), sm2file(1), and smlistsh(1) in Appendix A.
"},{"location":"ION-Guide/#licklider-transmission-protocol-ltp_1","title":"Licklider Transmission Protocol (LTP)","text":""},{"location":"ION-Guide/#build_1","title":"Build","text":"To build LTP:
Edit the Makefile in ion/ltp:
As for ici, make sure PLATFORMS is set to the name of the platform on which you plan to run LTP.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/ltp\nmake\nsudo make install\nThe LTP administration command (ltprc) file provides the information needed to configure LTP on a given ION node. For details, see the man page for ltprc(5) in Appendix A.
"},{"location":"ION-Guide/#run_1","title":"Run","text":"The executable programs used in operation of the ltp component of ION include:
ltpadmin starts/stops the ltpclock and ltpmeter tasks and, as mandated by configuration, the udplsi and udplso tasks.
For details, see the man pages for ltpadmin(1), ltpclock(1), ltpmeter(1), udplsi(1), and udplso(1) in Appendix A.
"},{"location":"ION-Guide/#test_1","title":"Test","text":"Two test executables are provided to support testing and debugging of the LTP component of ION:
For details, see the man pages for ltpdriver(1) and ltpcounter(1) in Appendix A.
"},{"location":"ION-Guide/#bundle-streaming-service-protocol-bssp","title":"Bundle Streaming Service Protocol (BSSP)","text":""},{"location":"ION-Guide/#build_2","title":"Build","text":"To build BSSP:
Edit the Makefile in ion/bssp:
As for ici, make sure PLATFORMS is set to the name of the platform on which you plan to run BSSP.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/bssp\nmake\nsudo make install\nThe BSSP administration command (bssprc) file provides the information needed to configure BSSP on a given ION node. For details, see the man page for bssprc(5) in Appendix A.
The bssprc file has a command option specifying the max_block_size. This is to prevent retransmission inefficiency when the blocks size of a stream data is too large. The unit of retransmission for BSSP is the block, so if the block size is too large, it is very expensive to the network to provide retransmission. If one needs bulk data transfer, instead of streaming, one should use BP with reliability LTP instead of using BSSP. If you are using udpbso and udpbsi as the underlying convergence layer, then the max_block_size parameter for bssprc cannot be larger than 65507 bytes, because each UDP datagram can only be as large as 65507 bytes (payload) + 20 (IP Header) + 8 (UDP Header) = 65535 byte.
"},{"location":"ION-Guide/#run_2","title":"Run","text":"The executable programs used in operation of the bssp component of ION include:
bsspadmin starts/stops the bsspclock task and, as mandated by configuration, the udpbsi and udblso tasks.
For details, see the man pages for bsspadmin(1), bsspclock(1), bsspmeter(1), udpbsi(1), and udpbso(1) in Appendix A.
"},{"location":"ION-Guide/#bundle-protocol-bp_1","title":"Bundle Protocol (BP)","text":""},{"location":"ION-Guide/#compile-time-options_1","title":"Compile-time options","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DION_NOSTATS or --DBRSTERM=60), will alter the functionality of BP as noted below.
"},{"location":"ION-Guide/#targetffs","title":"TargetFFS","text":"Setting this option adapts BP for use with the TargetFFS flash file system on the VxWorks operating system. TargetFFS apparently locks one or more system semaphores so long as a file is kept open. When a BP task keeps a file open for a sustained interval, subsequent file system access may cause a high-priority non-BP task to attempt to lock the affected semaphore and therefore block; in this event, the priority of the BP task may automatically be elevated by the inversion safety mechanisms of VxWorks. This \"priority inheritance\" can result in preferential scheduling for the BP task -- which does not need it -- at the expense of normally higher-priority tasks, and can thereby introduce runtime anomalies. BP tasks should therefore close files immediately after each access when running on a VxWorks platform that uses the TargetFFS flash file system. The TargetFFS compile-time option ensures that they do so.
"},{"location":"ION-Guide/#brstermxx","title":"BRSTERM=xx","text":"This option sets the maximum number of seconds by which the current time at the BRS server may exceed the time tag in a BRS authentication message from a client; if this interval is exceeded, the authentication message is presumed to be a replay attack and is rejected. Small values of BRSTERM are safer than large ones, but they require that clocks be more closely synchronized. The default value is 5.
"},{"location":"ION-Guide/#ion_nostats","title":"ION_NOSTATS","text":"Setting this option prevents the logging of bundle processing statistics in status messages.
"},{"location":"ION-Guide/#keepalive_periodxx","title":"KEEPALIVE_PERIOD=xx","text":"This option sets the number of seconds between transmission of keep-alive messages over any TCP or BRS convergence-layer protocol connection. The default value is 15.
"},{"location":"ION-Guide/#ion_bandwidth_reserved","title":"ION_BANDWIDTH_RESERVED","text":"Setting this option overrides strict priority order in bundle transmission, which is the default. Instead, bandwidth is shared between the priority-1 and priority-0 queues on a 2:1 ratio whenever there is no priority-2 traffic.
"},{"location":"ION-Guide/#enable_bpacs","title":"ENABLE_BPACS","text":"This option causes Aggregate Custody Signaling source code to be included in the build. ACS is alternative custody transfer signaling mechanism that sharply reduces the volume of custody acknowledgment traffic.
"},{"location":"ION-Guide/#enable_imc","title":"ENABLE_IMC","text":"This option causes IPN Multicast source code to be included in the build. IMC is discussed in section 1.8.4 above.
"},{"location":"ION-Guide/#build_3","title":"Build","text":"To build BP:
Edit the Makefile in ion/bp:
As for ici, make sure PLATFORMS is set to the name of the platform on which you plan to run BP.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/bp\nmake\nsudo make install\nThe BP administration command (bprc) file provides the information needed to configure generic BP on a given ION node. The IPN scheme administration command (ipnrc) file provides information that configures static and default routes for endpoints whose IDs conform to the \"ipn\" scheme. The DTN scheme administration command (dtn2rc) file provides information that configures static and default routes for endpoints whose IDs conform to the \"dtn\" scheme, as supported by the DTN2 reference implementation. For details, see the man pages for bprc(5), ipnrc(5), and dtn2rc(5) in Appendix A.
"},{"location":"ION-Guide/#run_3","title":"Run","text":"The executable programs used in operation of the bp component of ION include:
bpadmin starts/stops the bpclock task and, as mandated by configuration, the ipnfw, dtn2fw, ipnadminep, dtn2adminep, bpclm, brsscla, brsccla, tcpcli, stcpcli, stcpclo, udpcli, udpclo, ltpcli, ltpclo, and dgrcla tasks.
For details, see the man pages for bpadmin(1),ipnadmin(1), dtn2admin(1), bpclock(1), bpclm(1), ipnfw(1), dtn2fw(1), ipnadminep(1), dtn2adminep(1), brsscla(1), brsccla(1),tcpcli(1), stcpcli(1), stcpclo(1), udpcli(1), udpclo(1), ltpcli(1), ltpclo(1), dgrcla(1), bpsendfile(1), bpstats(1), bptrace(1), lgsend(1), lgagent(1), and hmackeys(1) in Appendix A.
"},{"location":"ION-Guide/#test_2","title":"Test","text":"Five test executables are provided to support testing and debugging of the BP component of ION:
For details, see the man pages for bpdriver(1), bpcounter(1), bpecho(1), bpsource(1), and bpsink(1) in Appendix A.
"},{"location":"ION-Guide/#datagram-retransmission-dgr_1","title":"Datagram Retransmission (DGR)","text":""},{"location":"ION-Guide/#build_4","title":"Build","text":"To build DGR:
Edit the Makefile in ion/dgr:
As for ici, make sure PLATFORMS is set to the name of the platform on which you plan to run DGR.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/dgr\nmake\nsudo make install\nNo additional configuration files are required for the operation of the DGR component of ION.
"},{"location":"ION-Guide/#run_4","title":"Run","text":"No runtime executables are required for the operation of the DGR component of ION.
"},{"location":"ION-Guide/#test_3","title":"Test","text":"Two test executables are provided to support testing and debugging of the DGR component of ION:
For details, see the man pages for file2dgr(1) and dgr2file(1) in Appendix A.
"},{"location":"ION-Guide/#asynchronous-message-service-ams_1","title":"Asynchronous Message Service (AMS)","text":""},{"location":"ION-Guide/#compile-time-options_2","title":"Compile-time options","text":"Note that, by default, the syntax by which AMS MIB information is presented to AMS is as documented in the \"amsrc\" man page. Alternatively it is possible to use an XML-based syntax as documented in the \"amsxml\" man page. To use the XML-based syntax instead, be sure that the \"expat\" XML interpretation system is installed and pass the argument \"--with-expat\" to \"./configure\" when building ION.
Defining the following macros, by setting parameters that are provided to the C compiler (for example, DAMS_INDUSTRIAL), will alter the functionality of AMS as noted below.
AMS_INDUSTRIAL
Setting this option adapts AMS to an \"industrial\" rather than safety-critical model for memory management. By default, the memory acquired for message transmission and reception buffers in AMS is allocated from limited ION working memory, which is fixed at ION start-up time; this limits the rate at which AMS messages may be originated and acquired. When --DAMS_INDUSTRIAL is set at compile time, the memory acquired for message transmission and reception buffers in AMS is allocated from system memory, using the familiar malloc() and free() functions; this enables much higher message traffic rates on machines with abundant system memory.
"},{"location":"ION-Guide/#build_5","title":"Build","text":"To build AMS:
Edit the Makefile in ion/cfdp:
Just as for bp, make sure PLATFORMS is set to the name of the platform on which you plan to run AMS.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/ams\nmake\nsudo make install\nThere is no central configuration of AMS; each AMS entity (configuration server, registrar, or application module) is individually configured at the time its initial MIB is loaded at startup. Note that a single MIB may be shared between multiple AMS entities without issue.
For details of MIB file syntax, see the man pages for amsrc(5) and amsxml(5) in Appendix A.
"},{"location":"ION-Guide/#run_5","title":"Run","text":"The executable programs used in operation of the AMS component of ION include:
For details, see the man pages for amsd(1), ramsgate(1), amsstop(1), and amsmib(1) in Appendix A.
"},{"location":"ION-Guide/#test_4","title":"Test","text":"Seven test executables are provided to support testing and debugging of the AMS component of ION:
For details, see the man pages for amsbenchs(1), amsbenchr(1), amshello(1), amsshell(1), amslog(1), amslogprt(1), amspub(1), and amssub(1) in Appendix A.
For further operational details of the AMS system, please see sections 4 and 5 of the AMS Programmer's Guide.
"},{"location":"ION-Guide/#ccsds-file-delivery-protocol-cfdp_1","title":"CCSDS File Delivery Protocol (CFDP)","text":""},{"location":"ION-Guide/#compile-time-options_3","title":"Compile-time options","text":"Defining the following macro, by setting a parameter that is provided to the C compiler (i.e., --DTargetFFS), will alter the functionality of CFDP as noted below.
"},{"location":"ION-Guide/#targetffs_1","title":"TargetFFS","text":"Setting this option adapts CFDP for use with the TargetFFS flash file system on the VxWorks operating system. TargetFFS apparently locks one or more system semaphores so long as a file is kept open. When a CFDP task keeps a file open for a sustained interval, subsequent file system access may cause a high-priority non-CFDP task to attempt to lock the affected semaphore and therefore block; in this event, the priority of the CFDP task may automatically be elevated by the inversion safety mechanisms of VxWorks. This \"priority inheritance\" can result in preferential scheduling for the CFDP task -- which does not need it -- at the expense of normally higher-priority tasks, and can thereby introduce runtime anomalies. CFDP tasks should therefore close files immediately after each access when running on a VxWorks platform that uses the TargetFFS flash file system. The TargetFFS compile-time option ensures that they do so.
"},{"location":"ION-Guide/#build_6","title":"Build","text":"To build CFDP:
Edit the Makefile in ion/cfdp:
Just as for bp, make sure PLATFORMS is set to the name of the platform on which you plan to run CFDP.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed.
Then:
cd ion/cfdp\n\nmake\n\nmake install\nThe CFDP administration command (cfdprc) file provides the information needed to configure CFDP on a given ION node. For details, see the man page for cfdprc(5) in Appendix A.
"},{"location":"ION-Guide/#run_6","title":"Run","text":"The executable programs used in operation of the CFDP component of ION include:
cfdpadmin starts/stops the cfdpclock task and, as mandated by configuration, the bputa task.
For details, see the man pages for cfdpadmin(1), cfdpclock(1), and bputa(1) in Appendix A.
"},{"location":"ION-Guide/#test_5","title":"Test","text":"A single executable, cfdptest, is provided to support testing and debugging of the DGR component of ION. For details, see the man page for cfdptest(1) in Appendix A.
"},{"location":"ION-Guide/#bundle-streaming-service-bss_1","title":"Bundle Streaming Service (BSS)","text":""},{"location":"ION-Guide/#compile-time-options_4","title":"Compile-time options","text":"Defining the following macro, by setting a parameter that is provided to the C compiler (e.g., --DWINDOW=10000), will alter the functionality of BSS as noted below.
"},{"location":"ION-Guide/#windowxx","title":"WINDOW=xx","text":"Setting this option changes the maximum number of seconds by which the BSS database for a BSS application may be \"rewound\" for replay. The default value is 86400 seconds, which is 24 hours.
"},{"location":"ION-Guide/#build_7","title":"Build","text":"To build BSS:
cd ion/bss\n\nmake\n\nsudo make install\nNo additional configuration files are required for the operation of the BSS component of ION.
"},{"location":"ION-Guide/#run_7","title":"Run","text":"No runtime executables are required for the operation of the BSS component of ION.
"},{"location":"ION-Guide/#test_6","title":"Test","text":"Four test executables are provided to support testing and debugging of the BSS component of ION:
For details, see the man pages for bssdriver(1), bsscounter(1), bssStreamingApp(1), and bssrecv(1) in Appendix A.
In ION, reliable convergence-layer protocols (where available) are by default used for every bundle. The application can instead mandate selection of \"best-effort\" service at the convergence layer by setting the BP_BEST_EFFORT flag in the \"extended class of service flags\" parameter, but this feature is an ION extension that is not supported by other BP implementations at the time of this writing.\u00a0\u21a9
Note that, in all occupancy figures, ION data management accounts not only for the sizes of the payloads of all queued bundles but also for the sizes of their headers.\u00a0\u21a9
Barring data loss or corruption for which the various retransmission mechanisms in ION cannot compensate.\u00a0\u21a9
Note that ION may indeed block the offering of a message to the network, but this is local admission control -- assuring that the node's local buffer space for queuing outbound bundles is not oversubscribed -- rather than end-to-end flow control. It is always possible for there to be ample local buffer space yet insufficient network capacity to convey the offered data to their final destination, and vice versa.\u00a0\u21a9
The minimum size of an ION bundle header is 26 bytes. Adding extension blocks (such as those that effect the Bundle Security Protocol) will increase this figure.\u00a0\u21a9
In ION, all bundles are by default non-critical. The application can indicate that data should be sent in a Critical bundle by setting the BP_MINIMUM_LATENCY flag in the \"extended class of service\" parameter, but this feature is an ION extension that is not supported by other BP implementations at the time of this writing.\u00a0\u21a9
If we wanted to be extremely accurate we could also subtract from the timeout interval the imputed inbound queuing delay QI, since inbound queuing would presumably be completed during the interval in which transmission was suspended. But since we're guessing at the queuing delays anyway, this adjustment doesn't make a lot of sense.\u00a0\u21a9
Last Updated: 12/27/2023
Previous versions of ION required a good understanding of the different ION adminstrative programs, how to write RC files from them, and what the different configuration commands mean.
The ionlauncher was developed to ease the user into ION configuration by taking a few parameters that mission designer would likely know when planning a network. Using those parameters, captured in a simple JSON format, an entire ION network with defined configurations files can be created and started rather quickly.
This section will outline the necessary parameters needed to create a simple model for ionlauncher.
There are seven parameters that are needed to define a simple network model. They are as follows:
NAME: serves as the key for the other parameters and naming start scripts\nIP ADDRESS: Host IP address or domain name the node will be running on\nNODE: assigned node number, will be used for addressing with neighbor(s)\nSERVICES: Applications running on the node, currently supports CFDP, AMS, & AMP\nDEST: node's neighbor(s)\nPROTOCOL: convergance layer to reach a neighbor. Currently supported options include LTP, TCP, UDP, and STCP. \n (untested options: BSSP & DCCP)\nRATE: Data rate used to communicate with neighbor(s), in bytes/s\nThere are a few example models included with the ionlauncher prototype under example_models/. This section shows one of them and explains how it works.
{\n \"SC\": {\n \"IP\": \"192.168.1.115\",\n \"NODE\": 21,\n \"SERVICES\": [],\n \"DEST\": [\n \"Relay\"\n ],\n \"PROTOCOL\": [\n \"ltp\"\n ],\n \"RATE\": [\n 100000\n ]\n },\n \"Relay\": {\n \"IP\": \"192.168.1.114\",\n \"NODE\": 22,\n \"SERVICES\": [],\n \"DEST\": [\n \"SC\",\n \"GS\"\n ],\n \"PROTOCOL\": [\n \"ltp\",\n \"tcp\"\n ],\n \"RATE\": [\n 10000,\n 2500000\n ]\n },\n \"GS\": {\n \"IP\": \"192.168.1.113\",\n \"NODE\": 23,\n \"SERVICES\": [],\n \"DEST\": [\n \"Relay\"\n ],\n \"PROTOCOL\": [\n \"tcp\"\n ],\n \"RATE\": [\n 2500000\n ]\n }\n}\nThis is an example of a three node setup where Relay serves as a DTN relay between SC and GS. Order is important in the lists for DEST, PROTOCOL, and RATE. They assume each element in the lists correspond to each other. For example, Relay communicates with SC via LTP at 10,000 bytes/s and Relay communicates with GS via TCP at 2,500,000 bytes/s.
There are other two examples included with ionlaucher. The first is a simple two node setup over TCP. The second is a four node scenario where SC can only uplink to Relay1 and downlink from Relay2, while GS has continuous coverage of the two relays.
Ionlauncher is currently a prototype and may not be installed globally. Please make sure that both ionlauncher and net_model_gen in the demo folder has been copied to the execution path of ION, which is typically /usr/local/bin or something specified as part of the ./configure script during initial ION installation.
Ionlauncher's simple network model file current does not handle multi-network interface configuration - this will be updated for ION 4.1.4.
"},{"location":"ION-Launcher/#usage","title":"Usage","text":"This section will outline how to run ionlauncher and what the different parameters mean. It is assumed ionlauncher will be run on each host independently with the same simple model and the only parameter changing is the node name.
ionlauncher [-h] -n <node name> -m <simple model file> [-d <ionconfig cli directory>]
-h: display help\n-n: node name that will be used to start ION on the host\n-m: path to simple model file, ionlauncher assumes the file \n is in the same directory or a directory below\n-d: optional parameter that defines the path to the ION Config \n tool CLI scripts, default is /home/$USER/ionconfig-4.8.1/cli/bin\nOnce the ION configuration files have been generate. ION will be started using the configuration files for the node passed via -n. Stopping the node is done via ionstop and if that hangs or errors out, killm can be used to force stop ION processes. To restart ION, ionlauncher can be used again, but this will overwrite the configuration files and wipe out any customization that has been added to the initial set of configuration files generated from previous run. If you did not add any customization, it is perfectly find to launch ION again in the same way. If you did make changes, then it is recommended that you use the start script in the node's working directory, ./start_{node_name}.sh to start ION.
The ionlauncher and associated net_model_gen python scripts will be installed in the same install path for ION, therefore making them available for use from any working directory.
For example, say the 3 node simple file is called 3node.json and it is stored at directory $WKDIR. After cd into the working directory and executing the ionlauncher, a new directory $WKDIR/3node-ion will be created and it contains the following:
-ion.json. In this case, it will be called 3node-ion.json. This file can be opened and edited by the ION Config Tool's browser-based GUI-net_model.json. In this case, it will be called 3node-net_model.json. This file can be opened and edited by the ION Network Model's browser-based GUI.$WKDIR/3node/SC, $WKDIR/3node/Relay, and $WKDIR/3node/GSstart_<node name>.sh, that you can use to launch ION again.After the initial ionlauncher run, the ION configuration files are generated for you based on the simple network model description and a set of default settings. To activate additional features, optimize parameters settings, and refine protocol behaviors, you will need to edit the ION config files individually. For those changes to take effect, you need to stop ION and restart ION using the start script in each node's working folder.
NOTE: If you run ionlauncher again, the ION configuration files will regenerate and over-write your custom changes. So it is recommended that you make a copy or rename the configuration to avoid this situation.
"},{"location":"ION-Launcher/#dependency","title":"Dependency","text":"The ionlaunch script requires that the installation of the ION Config Tool, which is publically accessible (starting January 2024) from GitHub, and the companion tool called ION Network Model is also available for download, although it is not needed for using ionlauncher.
Download the latest release of the ION Config Tool and note the directory of the CLI (command line interface executables). For example, if it is /home/$USER/ionconfig-4.8.1/cli/bin, then you don't need to provide the -d option to ionlauncher. If it is somewhere else, then you should provide the -d option.
You also need to install node.js and make sure python version 3.6 or higher is available in your system.
To build and install the entire ION system on a Linux, MacOS, or Solaris platform, cd into ion-open-source and enter the following commands:
./configure
If configure is not present run: autoreconf -fi first
make
sudo make install
sudo ldconfig
For MacOS, the ldconfig command is not present and not necessary to run.
If you want to set overriding compile-time switches for a build, the place to do this is in the ./configure command. For details,
./configure -h
By default, Bundle Protocol V7 will be built and installed, but BPv6 source code is still available. The BPv6 implementation is essentially the same as that of ION 3.7.4, with only critical bugs being updated going forward. All users are encouraged to switch to BPV7.
To build BPv6, run
./configure --enable-bpv6
To clean up compilation artifacts such as object files and shared libraries stored within the ION open-source directory, cd to the ION open-source directory and run:
make clean
To remove executables and shared libraries installed in the system, run:
sudo make uninstall
To install ION for Windows, please download the Windows installer.
"},{"location":"ION-Quick-Start-Guide/#build-individual-packages","title":"Build Individual Packages","text":"It's also possible to build the individual packages of ION, using platform-specific Makefiles in the package subdirectories. Currently the only actively maintained platform-specific Makefile is for 64-bits Linux under the \"i86_48-fedora\" folder. If you choose this option, be aware of the dependencies among the packages:
make and make install) before any other package.For more detailed instruction on building ION, see section 2 of the \"ION Design and Operation Guide\" document that is distributed with this package.
Also, be aware that these Makefiles install everything into subdirectories of /usr/local. To override this behavior, change the value of OPT in the top-level Makefile of each package.
Additional details are provided in the README.txt files in the root directories of some of the subsystems.
Note that all Makefiles are for gmake; on a FreeBSD platform, be sure to install gmake before trying to build ION.
"},{"location":"ION-Quick-Start-Guide/#running-ion","title":"Running ION","text":""},{"location":"ION-Quick-Start-Guide/#check-installed-bp-and-ion-versions","title":"Check Installed BP and ION versions","text":"Before running ION, let's confirm which version of Bundle Protocol is installed by running:
bpversion
You will see a simple string on the terminal windows indicating either \"bpv6\" or \"bpv7\".
Also check the ION version installed by running:
ionadmin
At the \":\" prompt, please enter the single character command 'v' and you should see a response like this:
$ ionadmin\n: v\nION-OPEN-SOURCE-4.1.2\nThen type 'q' to quit ionadmin. While ionadmin quits, it may display certain error messages like this:
at line 427 of ici/library/platform_sm.c, Can't get shared memory segment: Invalid argument (0)\nat line 312 of ici/library/memmgr.c, Can't open memory region.\nat line 367 of ici/sdr/sdrxn.c, Can't open SDR working memory.\nat line 513 of ici/sdr/sdrxn.c, Can't open SDR working memory.\nat line 963 of ici/library/ion.c, Can't initialize the SDR system.\nStopping ionadmin.\nThis is normal due to the fact that ION has not launched yet.
"},{"location":"ION-Quick-Start-Guide/#try-the-bping-test","title":"Try the 'bping' test","text":"The tests directory contains regression tests used by system integrator to check ION before issuing each new release. To make sure ION is operating properly after installation, you can also manually run the bping test:
First enter the test directory: cd tests
Enter the command: ./runtests bping/
This command invokes one of the simplest test whereby two ION instances are created and a ping message is sent from one to the other and an echo is returned to the sender of the ping.
During test, ION will display the configuration files used, clean the system of existing ION instances, relaunch ION according to the test configuration files, execute bping actions, display texts that indicates what the actions are being executed in real-time, and then shutdown ION, and display the final test status message, which looks like this:
ION node ended. Log file: ion.log\nTEST PASSED!\n\npassed: 1\n bping\n\nfailed: 0\n\nskipped: 0\n\nexcluded by OS type: 0\n\nexcluded by BP version: 0\n\nobsolete tests: 0\nIn this case, the test script confirms that ION is able to execute a bping function properly.
"},{"location":"ION-Quick-Start-Guide/#try-to-setup-a-udp-session","title":"Try to Setup a UDP Session","text":"Under the demos folder of the ION code directory, there are benchmark tests for various ION configurations. These tests also provide a template of how to configure ION.
Take the example of the bench-udp demo:
Go into the demos/bench-udp/ folder, you will see two subfolders: 2.bench.udp and 3.bench.udp, these folders configures two ION nodes, one with node numbers 2 and 3.
Looking inside the 2.bench.udp folder, you will see specific files used to configure ION. These include:
bench.bprc \nbench.ionconfig \nbench.ionrc \nbench.ionsecrc \nbench.ipnrc \nionstart \nionstop\nbench.bprc is the configuration file for the bundle protocol. To study the command options contained in this file, run man bprc.bench.ionconfig is the configuration file for the storage configuration of ION. See man ionconfig for details.bench.ionrc is the configuration file for ION. See man ionrc for details.bench.ionsecrc is the configuration file for ION security administration. See man ionsecrc for details.bench.ipnrc is the configuration file for the IPN scheme. See man ipnrc for details.ionstart and ionstop are scripts to launch and shutdown ION.One must note that ION distribution comes with a separate, global ionstart and ionstop scripts installed in /usr/local/bin that can launch and stop ION. The advantage of using local script is that it allows you customize the way you launch and stop ION, for example add helpful text prompt, perform additional checks and clean up activities, etc.
To run this demo test, first go into the test directory bench-udp, then run the dotest script:
./dotest
You can also study the test script to understand better what is happening.
"},{"location":"ION-Quick-Start-Guide/#running-multiple-ion-instances-on-a-single-host","title":"Running multiple ION instances on a single host","text":"If you study the test script under the \"tests\" and the \"demos\" folders, you will realize that these tests often will launch 2 or 3 ION nodes on the same host to conduct the necessary tests. While this is necessary to simplify and better automate regression testing for ION developer and integration, it is not a typical, recommended configuration for new users.
In order to run multiple ION instances in one host, specific, different IPCS keys must be used for each instance, and several variables must be set properly in the shell environment. Please see the ION Deployment Guide (included with the ION distribution) for more information on how to do that.
We recommend that most users, unless due to specific contrain that they must run multiple ION instance on one host, to run each ION instance on a separate host or (VM).
"},{"location":"ION-Quick-Start-Guide/#setup-udp-configuration-on-two-hosts","title":"Setup UDP Configuration on Two Hosts","text":"Once you have studied these scripts, you can try to run it on two different machines running ION.
First, install ION in host A with an IP address of, for example, 192.168.0.2, and host B with an IP address of 192.168.0.3. Verify your installation based on earlier instructions.
Copy the 2.bench.udp folder into host A and the 3.bench.udp folder into host B.
Also copy the file global.ionrc from the bench.udp folder into the same folder where you placed 2.bench.udp and 3.bench.udp
Then you need to modify the IP addresses in the UDP demo configuration files to match the IP addresses of hosts A and B.
For example, the bprc files copied into host A is:
1\na scheme ipn 'ipnfw' 'ipnadminep'\na endpoint ipn:2.0 x\na endpoint ipn:2.1 x\na endpoint ipn:2.2 x\na endpoint ipn:2.64 x\na endpoint ipn:2.65 x\na protocol udp 1400 100\na induct udp 127.0.0.1:2113 udpcli\na outduct udp 127.0.0.1:3113 'udpclo 1'\nr 'ipnadmin bench.ipnrc'\ns\nTo make it work for host A, you need to replace the induct ip address 127.0.0.1:2113 to 192.168.0.2:2113 - this is where host A's ION will receive incoming UDP traffic.
Similarly for outduct, you want to change the ip address from 127.0.0.1:3113 to 192.168.0.3:3113 - this is where UDP traffic will go out to host B.
You can make similar modifications to the ipnrc file as well.
In the ionconfig file, you want to comment out or delete the wmKey and sdrName entries. Since we are running these two nodes on different hosts, we always let ION use the default values for these parameters.
If you don\u2019t do this you get an error on startup.
Repeat the same updates for host B by appropriately substituting old IP address to that of the new hosts.
"},{"location":"ION-Quick-Start-Guide/#launch-ion-on-two-separate-hosts","title":"Launch ION on two separate hosts","text":"After updating the configuration files on host A and B to reflect the new IP addresses and using default wmKey (by not specifying any), we are new ready to try launching ION.
Before you try to launch ION, it is recommended that you:
global.ionrc file, change the data rates for the a contact command down to something similar to your connection speed. Remember, the unit in the global.ionrc file is Bytes per second, not bits per second, which is typically what iperf test report uses.Once you are ready to launch ION on both host A and B, open a terminal and go to the directory where the configuration files are stored, and run the local ionstart script:
./ionstart
Note: do not run ionstart since that will trigger the global script in the execution PATH
You should see some standard output confirming that ION launch has completed. For example you might see something like this:
Starting ION...\nwmSize: 5000000\nwmAddress: 0\nsdrName: 'ion2'\nsdrWmSize: 0\nconfigFlags: 1\nheapWords: 100000000\nheapKey: -1\nlogSize: 0\nlogKey: -1\npathName: '/tmp'\nStopping ionadmin.\nStopping ionadmin.\nStopping ionsecadmin.\nStopping ltpadmin.\nStopping ipnadmin.\nStopping bpadmin.\nYou can also see additional status information in the ion.log file in the same directory.
Launch ION on both host A and B.
"},{"location":"ION-Quick-Start-Guide/#run-a-bpdriver-bpcounter-test","title":"Run a bpdriver-bpcounter test","text":"Now that we have launched ION on both host A and B, it's time to send some data.
We can repeat the bping test at this point. But since you have already seen that before, let's try something different.
Let's use the bpdriver-bpcounter test utilities. This pair of utility programs simply sends a number of data in bundles from one node to another and provides a measurement on the throughput.
On host B, run this command:
bpcounter ipn:3.2 3
This command tells ION node number 3 to be ready to receive three bundles on the end-point ID ipn:3.2 which was specified in the .bprc file.
After host B has launched bpcounter, then on host A, run this command:
bpdriver 3 ipn:2.2 ipn:3.2 -10000
This command tells ION running in host A to send 3 bundles from EID 2.2 to EID 3.2, which is waiting for data (per bpcounter command.) And each bundle should be 10,000 bytes in size.
Why use the \"-\" sign in front of the size parameter? It's not a typo. The \"-\" indicates that bpdriver should keep sending bundles without waiting for any response from the receiver. The feature where bpdriver waits for the receiver is available in BPv6 but no longer part of BPv7.
When the test completed, you should see output indicating that all the data were sent, how many bundles were transmitted/received, and at what rate.
Please note that on the sending side the transmission may appear to be almost instantaneous. That is because bpdriver, as an application, is pushing data into bundle protocol which has the ability to rate buffer the data. So as soon as the bpdriver application pushes all data into the local bundle protocol agent, it considers the transmission completed and it will report a very high throughput value, one that is far above the contact graph's data rate limit. This is not an error; it simple report the throughput as experienced by the sending application, knowing that the data has not yet delivered fully to the destination.
Throughput reported by bpcounter, on the other hand, is quite accurate if a large number of bundles are sent. To accurately measure the time it takes to send the bundles, bpdriver program will send a \"pilot\" bundle just before sending the test data to signals to the bpcounter program to run its throughput calculation timer. This allows the user to run bpcounter and not haveing to worry about immediately send all the bundles in order to produce an accurate throughput measurement.
If you want to emulate the action of a constant rate source, instead of having bpdriver pushing all data as fast as possible, then you can use the 'i' option to specify a data rate throttle in bits per second.
If you want to know more about how bpdriver and bpcounter work, look up their man pages for details on syntax and command line options. Other useful ION test utility commands include bpecho, bping, bpsource, bpsink, bpsendfile, bprecvfile, etc.
To confirm whether ION is running properly or has experienced an error, the first thing to do is to check the ion.log, which is a file created in the directory from which ION was launched. If an ion.log file exists when ION starts, it will simply append additional log entries into that file. Each entry has a timestamp to help you determine the time and the relative order in which events occurred.
When serious error occurs, ion.log will have detailed messages that can pinpoint the name and line number of the source code where the error was reported or triggered.
"},{"location":"ION-Quick-Start-Guide/#bpacq-and-ltpacq-files","title":"bpacq and ltpacq files","text":"Sometimes after operating ION for a while, you will notice a number of files with names such as \"bpacq\" or \"ltpacq\" followed by a number. These are temporary files created by ION to stage bundles or LTP blocks during reception and processing. Once a bundle or LTP block is completely constructed, delivered, or cancelled properly, these temporary files are automatically removed by ION. But if ION experiences an anomalous shutdown, then these files may remain and accumulate in the local directory.
It is generally safe to remove these files between ION runs. Their presence does not automatically imply issues with ION but can indicate that ION operations were interrupted for some reason. By noting their creation time stamp, it can provide clues on when these interruptions occurred. Right now there are no ION utilty program to parse them because these files are essentially bit buckets and do not contain internal markers or structure and allows user to parse them or extract information by processes outside the bundle agents that created them in the first place.
"},{"location":"ION-Quick-Start-Guide/#forced-shutdown-of-ion","title":"Forced Shutdown of ION","text":"Sometimes shutting down ION does not go smoothly and you can't seem to relaunch ION properly. In that case, you can use the global ionstop script (or the killm script) to kill all ION processes that did not terminate using local ionstop script. The global ionstop or killm scripts also clears out the IPC shared memory and semaphores allocations that were locked by ION processes and would not terminate otherwise.
To learn about the configuration files and the basic set of command syntax and functions: ION Config File Tutorial
"},{"location":"ION-Quick-Start-Guide/#ion-configuration-file-template","title":"ION Configuration File Template","text":"ION Config File Template
"},{"location":"ION-Quick-Start-Guide/#ion-nasa-course","title":"ION NASA Course","text":"To learn more about the design principle of ION and how to use it, a complete series of tutorials is available here: NASA ION Course
The ION Dev Kit mentioned in the NASA ION Course had been deprecated. However, some additional helpful files can be found here to complete the examples: Additional DevKit Files
"},{"location":"ION-Quick-Start-Guide/#accessing-ion-open-source-code-repository","title":"Accessing ION Open-Source Code Repository","text":""},{"location":"ION-Quick-Start-Guide/#releases","title":"Releases","text":"Use the Summary or the Files tab to download point releases
"},{"location":"ION-Quick-Start-Guide/#using-the-code-repository","title":"Using the code repository","text":"If you plan to contribute to the ION project, please keep these in mind:
The NASA team will review these contributions and determine to either
incorporate the code into the baseline, or
Generate a pull request (called Merge Request on Source Forge) with
Your feature or bugfix branch as the Source branch
The tests directory under ION's root folder contains the test suite. Each test lives in its own subdirectory of this directory. Each test is conducted by a script $TESTNAME/dotest. Another directory that contains ION tests is the demos directory, which includes examples of ION configurations using different convergence layers. For this document, we focus on the usage of the tests directory.
Exclude files are hidden files that allow for tests to be disabled based on certain conditions that may cause the test not to run correctly. If an exclude file exists, it should have a short message about why the test has been excluded.
Exclude files can exist in any of the following formats:
.exclude_OS-TYPE: Disables a test for an operating system that it does not run successfully on. Acceptable values to fill in for OS-TYPE are \"windows\", \"linux\", \"mac\", and \"solaris\".
.exclude_BP-VERSION: Disables a test for a version of the bundle protocol that it does not run correctly or does not make sense with. As of ION 4.0.0, the acceptable values to fill in for BP-VERSION are \"bpv6\" and \"bpv7\".
.exclude_all: Disables a test for all platforms.
.exclude_expert: Disables a test because of additional utilities that are required for the test. To work around this exclusion if you want to run an expert test, you can set ION_RUN_EXPERT=\"yes\" in your shell environment to enable all ION tests classified as expert.
.exclude_cbased: Disables a test that relies on compiling a C program to generate the dotest executable script. To exclude C-based tests, you need to define the environment variable ION_EXCLUDE_CBASED.
The tests are run by running make test-all in the top-level directory, or by running runtests in this directory.
An individual test can also be run: ./runtests <test_name>
A file defining a set of tests can be run with runtestset. The arguments to runtestset are files that contain globs of tests to run, for example: ./runtestset quicktests.
A test directory must contain an executable file named dotest. If a directory does not contain this, the test will be ignored. The dotest program should execute the test, possibly reporting runtime information on stdout and stderr, and indicate by its return value the result of the test as follows:
0: Success\n1: Failure\n2: Skip this test\nThe test program starts without the ION stack running. The test program is responsible for starting ION in the ways that is appropriate for the test.
The test program must stop the ION protocol stack before returning.
"},{"location":"ION-TestSet-Readme/#the-test-environment","title":"The test environment","text":"The dotest scripts are run in their test directory. The following environment variables are set as part of the test environment:
IONDIR is the root of the local ION source directory.
PATH begins with IONDIR (this is where the local executables are found.)
The runtests script maintains a file called tests/progress that gives the start time, finish time, and final result for each test.
If the environment variable RUNTESTS_OUTPUTDIR is set, as in, export RUNTESTS_OUTPUTDIR=\"/tmp\", then the output from each test will be stored in /tmp/results, which makes it much easier to find particular text or results when debugging.
The follow tutorials will help you get started with the ION BP Suite:
Note: These presentations/videos were released in 2020 and has not been updated since then. Some technical details and reference materials may be outdated. Please consult the latest man pages and released documentations.
"},{"location":"ION-Utilities/","title":"ION Utility Programs","text":"Here is a short list of utility programs that comes with ION that are frequently used by users launch, stop, and query ION/BP operation status:
ionexit - A program that shuts down ION with the option to preserve the SDR.Normally, when ION's various daemons were stopped down by calling ionstop, issuing the command '.' to the administration programs, the SDR will be modified/destroyed in the process. Calling ionexit with an argument 'keep' allows the SDR state just prior to the execution of ionexit to be preserved in the non-volatile storage such as a file if ION was configured to use a file for the SDR.
ION Version: 4.1.3
Bundle Protocol Version:7
Watch characters, when activated, provide immediate feedback on ION operations by printing various characters standard output (terminal). By examing the watch characters, and the order in which they appear, operators can quickly confirm proper operation or detect configuration or run-time errors.
This document will list all watch characters currently supported by ION.
"},{"location":"ION-Watch-Characters/#enhanced-watch-characters-ion-413-or-later","title":"Enhanced Watch Characters (ION 4.1.3 or later)","text":"Enhanced watch characters were added ION 4.1.3 to provide detailed state information at Bundle Protocol (BP) and LTP levels and can be activated at compile time by:
./configure --enable-ewchar\nor \n./configure CFLAGS=-DEWCHAR\nEnhanced watch characters prepends additional state information to the standard watch characters inside a pair of parenthesis. In this document, we use the following notion regarding enhanced watch characters information.
nnn = source node numbersss = service numberttt = bundle creation time in milliseconds Epoch(2000)ccc = bundle sequence numberxxx (LTP session number)Each field can be longer or shorter than 3 digits/characters.
"},{"location":"ION-Watch-Characters/#logging-and-processing-of-watch-characters","title":"Logging and Processing of Watch Characters","text":"Besides real-time monitoring of the watch characters on standard out, ION can redirect the watch characters to customized user applications for network monitoring purposes.Prior to and including ION 4.1.2, watch characters are single character. Starting from ION 4.1.3 release, a watch character is now generalized to a string of type char*.
To activate customized processing, there are two steps:
gdswatcher.c that defines a functions to process watch characters, and pass that function to ION to handle watch character:static void processWatchChar(char* token)\n{\n //your code goes here\n} \n\nstatic void ionRedirectWatchCharacters()\n{ \n setWatcher(processWatchChar);\n}\n./configure --enable-ewchar CFLAGS=\"-DGDSWATCHER -I/<path to the folder holding the gdswatcher.c file>\"\n./configure --enable-ewchar CFLAGS=\"-DGDSWATCHER -DGDSLOGGER -I/<path to the folder holding the gdswatcher.c file>\"\na - new bundle is queued for forwarding; (nnn,sss,tttt,cccc)a
b - bundle is queued for transmission; (nnn,sss,ccc)b
c - bundle is popped from its transmission queue; (nnn,sss,ccc)c
m - custody acceptance signal is received
w - custody of bundle is accepted
x - custody of bundle is refused
y - bundle is accepted upon arrival; (nnn,sss,tttt,ccc)y
z - bundle is queued for delivery to an application; (nnn,sss,tttt,ccc)z
~ - bundle is abandoned (discarded) on attempt to forward it; (nnn,sss,ccc)~
! - bundle is destroyed due to TTL expiration; (nnn,sss,ccc)!
& - custody refusal signal is received
# - bundle is queued for re-forwarding due to CL protocol failure; (nnn,sss,ccc)#
j - bundle is placed in \\\"limbo\\\" for possible future re-forwarding; (nnn,sss,ccc)j
k - bundle is removed from \\\"limbo\\\" and queued for re-forwarding; (nnn,sss,ccc)k
d - bundle appended to block for next session
e - segment of block is queued for transmission
f - block has been fully segmented for transmission; (xxxx)f
g - segment popped from transmission queue;
(cpxxx)g -- checkpoint, this could be a data segment or a standalone check point
(dsxxx)g -- non-check point data segment
(rcpxxx)g -- retransmitted checkpoint(prsxxx)g -- positive report (all segments received)(nrsxxx)g -- negative report (gaps)(rrsxxx)g -- retransmitted report (either positive or negative)(rasxxx)g -- a report ack segment(csxxx)g -- cancellation by block source(crxxx)g -- cancellation by block receiver(caxxx)g -- cancellation ack for either CS or CRh - positive ACK received for block, session ended; (xxx)h
s - segment received
t - block has been fully received
@ - negative ACK received for block, segments retransmitted; (xxx)@
= - unacknowledged checkpoint was retransmitted; (xxx)=
+ - unacknowledged report segment was retransmitted; (xxx)+
{ - export session canceled locally (by sender)
} - import session canceled by remote sender
[ - import session canceled locally (by receiver)
] - export session canceled by remote receiver
w - custody request is accepted (by receiving entity)
m - custody acceptance signal is received (by requester)
x - custody of bundle has been refused
& - custody refusal signal is received (by requester)
$ - bundle retransmitted due to expiration of custody request timer
D - bssp send completed
E - bssp block constructed for issuance
F - bssp block issued
G - bssp block popped from best-efforts transmission queue
H - positive ACK received for bssp block, session ended
S - bssp block received
T - bssp block popped from reliable transmission queue
- - unacknowledged best-efforts block requeued for reliable transmission
* - session canceled locally by sender
Here is a list of known issues that will updated on a regular basis to captures various lessons-learned relating to the configurations, testing, performance, and deployment of ION:
"},{"location":"Known-Issues/#convergence-layer-adaptor","title":"Convergence Layer Adaptor","text":""},{"location":"Known-Issues/#udp-cla","title":"UDP CLA","text":"In the Licklider Transmission Protocol (LTP) Specification issued by CCSDS 734.1-B-1, the elements of a LTP architecture is shown as follows:
The LTP Engine and MIB is implemented and configured by ION, and the Client Service Instance is either BPv6 or BPv7. The storage is provided by the host system through the ICI APIs.
The Underlying Communication Protocol element is responsible for data and control message exchanges between two peered LTP Engines. It is not responsible for flow control, error correction/detection, and in-ordered delivery.
For a spacecraft, the LTP Engine will execute the LTP protocol logic and handing the LTP segments to the underlying communication services provided in the form of a simple UDP socket or a radio frequency/optical telecommunication system. In ION, the standard underlying communications protocol is UDP since it is widely available in terrestrial computer systems. In actual deployment, the UDP protocol may need to be substituted by a different ground-based or flight communications system.
In the document we describe a few essential APIs for any externally implemented underlying communication protocols to interface with LTP engine and perform the most basic tasks of (a) submitting a received LTP segments to the LTP Engine for processing and (b) acquiring an LTP segment from the LTP Engine for transmission to its peer.
"},{"location":"LTP-UComm-API/#connecting-to-the-ltp-engine","title":"Connecting to the LTP Engine","text":"There are several steps for an external application to connecting to LTP:
.ltprc file processed ltpadmin. See the Configuration File Tutorial to understand how BP and LTP services are instantiated.ltprc for more details.ltpInit() API.ltpInit called returned successfully, it must obtain access to ION SDR and detemine the associated LTP span (based on a peer engine number) for which communication service will be provisioned. This is done by using the findSpan() API. A span defines the communication parameters between two LTP engine peers.ltpDequeueOUtboundSegment API to acquire each available segment from the LTP Engine for transmission to the peer entity.In the following section we will describe the private APIs used by the underlying communication protocols. There are other APIs for external processes to use LTP as a reliable point-to-point data transmission service, but they are not described in this document; they are available in the manual pages.
"},{"location":"LTP-UComm-API/#ltp-data-structure","title":"LTP Data Structure","text":"Here is a diagram of the major LTP data structures and their relationships.
+----------------------------------+----------------------------------+\n| | |\n| non->olatile (SDR heap) | volatile (working memory ION) |\n| | |\n| | |\n| LtpDB | LtpVdb |\n| + (list) | + (list) |\n| +---> spans +--+ | +-----+ spans+------+ |\n| | | | | | |\n| +---> seats +---------+ | +-----+ seats+---+ | |\n| | | | | | |\n| | | | | | |\n| LtpSpan <--------+ | | LtpVspan <----------+ |\n| + | | + | |\n| +---> importSessions+----+ | +-> importSessions+--+ |\n| | (list) | | | (list) | | |\n| +---> exportSessions+------+ | | | |\n| | | | | LtpVseat <-------+ | |\n| LtpSeat <---------------+ | | | | |\n| | | | | |\n| | | | | |\n| LtpImportSession <---------+ | | LtpVImportSession<-----+ |\n| | | |\n| | | |\n| LtpExportSession <-----------+ | |\n| | |\n+----------------------------------+----------------------------------+\nLtpDB: The LTP database is a global database that contains the LTP configuration information for the entire system. It is a persistent data stored in the SDR's heap - assuming the SDR is implemented in a non-volatile medium such as a disk or a battery backed RAM.
LtpSpan: A span is a communication channel between two LTP engine peers. A span is defined by a unique span number and a set of communication parameters stored in a non-volatile database. Each instance of LtpSpan is tracked as an element in the LTP database under the LtpDB.spans list.
LtpSeat: A seat is the reception process for LTP and its parameters are stored under LtpSeat, and its tracked as an element in the list LtpDB.seats.
LtpImportSession and LtpExportSession are tracked by lists in the LtpSpan structure.
LtpVdb: The LTP volatile database is a global database that contains the LTP configuration information for the entire system. It is a volatile data stored in the working memory and not expected to persist through power reset. It tracks, in two lists, each instance of LtpVspan and LtpVseat that are currently active.
LtpVspan: contains the state information of an active span in the working memory. It is tracked as an element in the list LtpVdb.spans.
LtpVseat: contains the state information of an active seat in the working memory. It is tracked as an element in the list LtpVdb.seats.
LtpVImportSession: contains the state information of an active import session in the working memory. It is tracked as an element in the list LtpVspan.importSessions.
#include \"ltpP.h\"\nFunction Prototype
extern int ltpInit(int estMaxExportSessions);\nParameters
estMaxExportSessions: name of the endpointReturn Value
Example Call
/* Note that ltpadmin must be run before the first\n * invocation of ltplso, to initialize the LTP database\n * (as necessary) and dynamic database.*/\n\nif (ltpInit(0) < 0)\n{\n putErrmsg(\"aoslso can't initialize LTP.\", NULL);\n\n /* user error handling routine here */\n}\nDescription
This call attaches to ION and either initializes a new LTP database or loads the LTP database of an existing service. If the value of estMaxExportSessions is positive and no existing LTP service are found, then LTP service will be initialized with the specified maximum number of export sessions indicated. If the value of estMaxExportSessions is zero or negative, then ltpInit will load the LTP database or otherwise quit if no existing LTP service is found. NOTE: for the underlying communication protocol implementation, setting ltpInit(0) is appropriate since the intention is to load an existing LTP service only.
Once a LTP service is either found or initialized, it loads the address to the LTP database object defined by LtpDB in ltpP.h.
Function Prototype
void findSpan(uvast engineId, LtpVspan **vspan, PsmAddress *vspanElt);\nParameters
engineId: The engine number of the peer LTP enginevspan: pointer to the pointer of the LTP span object in ION working memory that encapsulates the current state of the LTP spanvspanElt: pointer to the address stored in a list of span in the volatile database defined by LtpVdbReturn Value
Example Code
sdr = getIonsdr();\nCHKZERO(sdr_begin_xn(sdr)); /* Lock SDR. */\nfindSpan(remoteEngineId, &vspan, &vspanElt);\nif (vspanElt == 0)\n{\n sdr_exit_xn(sdr);\n putErrmsg(\"No such engine in database.\", itoa(remoteEngineId));\n /* user error handling routine here */\n}\n\nif (vspan->lsoPid != ERROR && vspan->lsoPid != sm_TaskIdSelf())\n{\n sdr_exit_xn(sdr);\n putErrmsg(\"LSO task is already started for this span.\",\n itoa(vspan->lsoPid));\n /* user error handling routine here */\n}\n\n/* unlock the SDR */\nsdr_exit_xn(sdr);\nDescription
This function searches the volatile database for the span that corresponds to the specified engine number. If the span is found, then the pointer to the span object is stored in the vspan parameter and the address of the span object in the list of spans in the volatile database is stored in the vspanElt parameter. If the span is not found, then vspanElt parameter is set to 0.
Note: In addition to check the value of vspanElt, one can also check for the process ID of the LSO task (the LTP output process, i.e., the underlying communication protocol) of the span has not already been serviced by another protocol implementation.
Function Prototype
extern int ltpDequeueOutboundSegment(LtpVspan *vspan, char **buf);\nParameters
vspan: address to the volatile LTP span objectbuf: the buffer in which outbound LTP segments are storedReturn Value
length of segment: success0: session associated to the dequeued segment has already closed; no need to transmit any data-1: any errorExample Code
segmentLength = ltpDequeueOutboundSegment(vspan, &segment);\nif (segmentLength < 0)\n{\n /* handle error */\n}\n\nif (segmentLength == 0)\n{\n /* session is closed, take appropriate action */\n\n}\n\n/* transmit the segment */\nDescription:
This function dequeues a LTP segment, based on the segSemaphore in vspan object, into a buffer space for the calling task to process for transmission. The returned value is the length of the LTP segment dequeue; 0 if the segment belongs to a session that already closed (therefore no action is required), and -1 if an error occurred.
If this call is implemented in a loop, then it is suggested that the loop monitors the segSemaphore in vspan to detect the termination of the semaphore using the sm_SemEnded(vspan->segSemaphore) call. If the semaphore has ended, it means the span associated with the underlying communication protocol instance has ended. This is the right time to end the task itself.
After each successful iteration in a loop, it is recommended that you call sm_TaskYield() to give other tasks a chance to run. A good example code to read is the udplso.c program.
Function Prototype
int ltpHandleInboundSegment(char *buf, int length)\nParameters
buf: pointer to buffer storing the received LTP segment, to be submitted to LTP engine for processinglength: the length of the received LTP segmentReturn Value
0: segment successfully handled-1: any errorExample Code
if (ltpHandleInboundSegment(buffer, segmentLength) < 0)\n{\n putErrmsg(\"Can't handle inbound segment.\", NULL);\n /* handle error here */\n}`\nDescription
This function submits received LTP segments to LTP engine for processing. The return value is 0 if the segment is successfully handled, and -1 if an error occurred. A successfully handled segment includes cases where the segments are ignored for several possible, non-critial, non-fatal discrepencies such as wrong LTP version number, closed session number, session under cancellation (therefore the segment was not processed) and other conditions are may occur under nominal condition.
To develop one's own underlying communication protocol implementation to support LTP, the udplsi.c and udplso.c programs are good templates to use.
NO WARRANTY:
DISCLAIMER
THE SOFTWARE AND/OR RELATED MATERIALS ARE PROVIDED \"AS-IS\" WITHOUT WARRANTY OF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OR PURPOSE (AS SET FORTH IN UCC 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE LICENSED PRODUCT, HOWEVER USED.
IN NO EVENT SHALL CALTECH/JPL BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING BUT NOT LIMITED TO INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, REGARDLESS OF WHETHER CALTECH/JPL SHALL BE ADVISED, HAVE REASON TO KNOW, OR IN FACT SHALL KNOW OF THE POSSIBILITY.
USER BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWARE AND/OR RELATED MATERIALS.
Copyright 2002-2013, by the California Institute of Technology. ALL RIGHTS RESERVED. U.S. Government Sponsorship acknowledged.
This software and/or related materials may be subject to U.S. export control laws. By accepting this software and related materials, the user agrees to comply with all applicable U.S. export laws and regulations. User has the responsibility to obtain export licenses or other export authority as may be required before exporting the software or related materials to foreign countries or providing access to foreign persons.
The QCBOR code included is distributed with the following condition
Copyright (c) 2016-2018, The Linux Foundation. Copyright (c) 2018-2019, Laurence Lundblade. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of The Linux Foundation nor the names of its contributors, nor the name \"Laurence Lundblade\" may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
"},{"location":"List-of-Papers/","title":"List of Papers","text":"From manual page for \"platform\"
"},{"location":"Platform-Macros-Error-Reporting/#platform-compatibility","title":"Platform Compatibility","text":"The platform library \"patches\" the APIs of supported OS's to guarantee that all of the following items may be utilized by application software:
The strchr(), strrchr(), strcasecmp(), and strncasecmp() functions.\n\nThe unlink(), getpid(), and gettimeofday() functions.\n\nThe select() function.\n\nThe FD_BITMAP macro (used by select()).\n\nThe MAXHOSTNAMELEN macro.\n\nThe NULL macro.\n\nThe timer_t type definition.\nThe generic macros and functions in this section may be used in place of comparable O/S-specific functions, to enhance the portability of code. (The implementations of these macros and functions are no-ops in environments in which they are inapplicable, so they're always safe to call.)
"},{"location":"Platform-Macros-Error-Reporting/#fdtable_size","title":"FDTABLE_SIZE","text":"The FDTABLE_SIZE macro returns the total number of file descriptors defined for the process (or VxWorks target).
"},{"location":"Platform-Macros-Error-Reporting/#ion_path_delimiter","title":"ION_PATH_DELIMITER","text":"The ION_PATH_DELIMITER macro returns the ASCII character -- either '/' or '\\' -- that is used as a directory name delimiter in path names for the file system used by the local platform.
"},{"location":"Platform-Macros-Error-Reporting/#ok","title":"oK","text":"oK(expression)\nCHKERR(condition)\nThe CHKERR macro is an \"assert\" mechanism. It causes the calling function to return -1 immediately if condition is false.
"},{"location":"Platform-Macros-Error-Reporting/#chkzero","title":"CHKZERO","text":"CHKZERO(condition)\nThe CHKZERO macro is an \"assert\" mechanism. It causes the calling function to return 0 immediately if condition is false.
"},{"location":"Platform-Macros-Error-Reporting/#chknull","title":"CHKNULL","text":"CHKNULL(condition)\nCHKVOID(condition)\nThe CHKVOID macro is an \"assert\" mechanism. It causes the calling function to return immediately if condition is false.
"},{"location":"Platform-Macros-Error-Reporting/#snooze","title":"snooze","text":"void snooze(unsigned int seconds)\nvoid microsnooze(unsigned int microseconds)\nSuspends execution of the invoking task or process for the indicated number of microseconds.
"},{"location":"Platform-Macros-Error-Reporting/#getcurrenttime","title":"getCurrentTime","text":"void getCurrentTime(struct timeval *time)\nReturns the current local time (ctime, i.e., Unix epoch time) in a timeval structure (see gettimeofday(3C)).
"},{"location":"Platform-Macros-Error-Reporting/#isprintf","title":"isprintf","text":"void isprintf(char *buffer, int bufSize, char *format, ...)\nisprintf() is a safe, portable implementation of snprintf(); see the snprintf(P) man page for details. isprintf() differs from snprintf() in that it always NULL-terminates the string in buffer, even if the length of the composed string would equal or exceed bufSize. Buffer overruns are reported by log message; unlike snprintf(), isprintf() returns void.
"},{"location":"Platform-Macros-Error-Reporting/#istrlen","title":"istrlen","text":"size_t istrlen(const char *sourceString, size_t maxlen)\nistrlen() is a safe implementation of strlen(); see the strlen(3) man page for details. istrlen() differs from strlen() in that it takes a second argument, the maximum valid length of sourceString. The function returns the number of non-NULL characters in sourceString preceding the first NULL character in sourceString, provided that a NULL character appears somewhere within the first maxlen characters of sourceString; otherwise it returns maxlen.
"},{"location":"Platform-Macros-Error-Reporting/#istrcpy","title":"istrcpy","text":"char *istrcpy(char *buffer, char *sourceString, int bufSize)\nistrcpy() is a safe implementation of strcpy(); see the strcpy(3) man page for details. istrcpy() differs from strcpy() in that it takes a third argument, the total size of the buffer into which sourceString is to be copied. istrcpy() always NULL-terminates the string in buffer, even if the length of sourceString string would equal or exceed bufSize (in which case sourceString is truncated to fit within the buffer).
"},{"location":"Platform-Macros-Error-Reporting/#istrcat","title":"istrcat","text":"char *istrcat(char *buffer, char *sourceString, int bufSize)\nistrcat() is a safe implementation of strcat(); see the strcat(3) man page for details. istrcat() differs from strcat() in that it takes a third argument, the total size of the buffer for the string that is being aggregated. istrcat() always NULL-terminates the string in buffer, even if the length of sourceString string would equal or exceed the sum of bufSize and the length of the string currently occupying the buffer (in which case sourceString is truncated to fit within the buffer).
"},{"location":"Platform-Macros-Error-Reporting/#igetcwd","title":"igetcwd","text":"char *igetcwd(char *buf, size_t size)\nigetcwd() is normally just a wrapper around getcwd(3). It differs from getcwd(3) only when FSWWDNAME is defined, in which case the implementation of igetcwd() must be supplied in an included file named \"wdname.c\"; this adaptation option accommodates flight software environments in which the current working directory name must be configured rather than discovered at run time.
"},{"location":"Platform-Macros-Error-Reporting/#isignal","title":"isignal","text":"void isignal(int signbr, void (*handler)(int))\nisignal() is a portable, simplified interface to signal handling that is functionally indistinguishable from signal(P). It assures that reception of the indicated signal will interrupt system calls in SVR4 fashion, even when running on a FreeBSD platform.
"},{"location":"Platform-Macros-Error-Reporting/#iblock","title":"iblock","text":"void iblock(int signbr)\niblock() simply prevents reception of the indicated signal by the calling thread. It provides a means of controlling which of the threads in a process will receive the signal cited in an invocation of isignal().
"},{"location":"Platform-Macros-Error-Reporting/#ifopen","title":"ifopen","text":"int ifopen(const char *fileName, int flags, int pmode)\nifopen() is a portable function for opening \"regular\" files. It operates in exactly the same way as open() except that it fails (returning -1) if fileName does not identify a regular file, i.e., it's a directory, a named pipe, etc.
NOTE that ION also provides iopen() which is nothing more than a portable wrapper for open(). iopen() can be used to open a directory, for example.
"},{"location":"Platform-Macros-Error-Reporting/#igets","title":"igets","text":"char *igets(int fd, char *buffer, int buflen, int *lineLen)\nigets() reads a line of text, delimited by a newline character, from fd into buffer and writes a NULL character at the end of the string. The newline character itself is omitted from the NULL-terminated text line in buffer; if the newline is immediately preceded by a carriage return character (i.e., the line is from a DOS text file), then the carriage return character is likewise omitted from the NULL-terminated text line in buffer. End of file is interpreted as an implicit newline, terminating the line. If the number of characters preceding the newline is greater than or equal to buflen, only the first (buflen - 1) characters of the line are written into buffer. On error the function sets lineLen to -1 and returns NULL. On reading end-of-file, the function sets lineLen to zero and returns NULL. Otherwise the function sets *lineLen to the length of the text line in buffer, as if from strlen(3), and returns buffer.
"},{"location":"Platform-Macros-Error-Reporting/#iputs","title":"iputs","text":"int iputs(int fd, char *string)\niputs() writes to fd the NULL-terminated character string at string. No terminating newline character is appended to string by iputs(). On error the function returns -1; otherwise the function returns the length of the character string written to fd, as if from strlen(3).
"},{"location":"Platform-Macros-Error-Reporting/#strtovast","title":"strtovast","text":"vast strtovast(char *string)\nConverts the leading characters of string, skipping leading white space and ending at the first subsequent character that can't be interpreted as contributing to a numeric value, to a vast integer and returns that integer.
"},{"location":"Platform-Macros-Error-Reporting/#strtouvast","title":"strtouvast","text":"uvast strtouvast(char *string)\nSame as strtovast() except the result is an unsigned vast integer value.
"},{"location":"Platform-Macros-Error-Reporting/#findtoken","title":"findToken","text":"void findToken(char **cursorPtr, char **token)\nLocates the next non-whitespace lexical token in a character array, starting at cursorPtr. The function NULL-terminates that token within the array and places a pointer to the token in token. Also accommodates tokens enclosed within matching single quotes, which may contain embedded spaces and escaped single-quote characters. If no token is found, *token contains NULL on return from this function.
"},{"location":"Platform-Macros-Error-Reporting/#acquiresystemmemory","title":"acquireSystemMemory","text":"void *acquireSystemMemory(size_t size)\nUses memalign() to allocate a block of system memory of length size, starting at an address that is guaranteed to be an integral multiple of the size of a pointer to void, and initializes the entire block to binary zeroes. Returns the starting address of the allocated block on success; returns NULL on any error.
"},{"location":"Platform-Macros-Error-Reporting/#createfile","title":"createFile","text":"int createFile(const char *name, int flags)\nCreates a file of the indicated name, using the indicated file creation flags. This function provides common file creation functionality across VxWorks and Unix platforms, invoking creat() under VxWorks and open() elsewhere. For return values, see creat(2) and open(2).
"},{"location":"Platform-Macros-Error-Reporting/#getinternetaddress","title":"getInternetAddress","text":"unsigned int getInternetAddress(char *hostName)\nReturns the IP address of the indicated host machine, or zero if the address cannot be determined.
"},{"location":"Platform-Macros-Error-Reporting/#getinternethostname","title":"getInternetHostName","text":"char *getInternetHostName(unsigned int hostNbr, char *buffer)\nWrites the host name of the indicated host machine into buffer and returns buffer, or returns NULL on any error. The size of buffer should be (MAXHOSTNAMELEN + 1).
"},{"location":"Platform-Macros-Error-Reporting/#getnameofhost","title":"getNameOfHost","text":"int getNameOfHost(char *buffer, int bufferLength)\nWrites the first (bufferLength - 1) characters of the host name of the local machine into buffer. Returns 0 on success, -1 on any error.
"},{"location":"Platform-Macros-Error-Reporting/#getaddressofhost","title":"getAddressOfHost","text":"unsigned int getAddressOfHost()\nReturns the IP address for the host name of the local machine, or 0 on any error.
"},{"location":"Platform-Macros-Error-Reporting/#parsesocketspec","title":"parseSocketSpec","text":"void parseSocketSpec(char *socketSpec, unsigned short *portNbr, unsigned int *hostNbr)\nParses socketSpec, extracting host number (IP address) and port number from the string. socketSpec is expected to be of the form \"{ @ | hostname }[:]\", where @ signifies \"the host name of the local machine\". If host number can be determined, writes it into hostNbr; otherwise writes 0 into hostNbr. If port number is supplied and is in the range 1024 to 65535, writes it into portNbr; otherwise writes 0 into portNbr."},{"location":"Platform-Macros-Error-Reporting/#printdottedstring","title":"printDottedString","text":"
void printDottedString(unsigned int hostNbr, char *buffer)\nComposes a dotted-string (xxx.xxx.xxx.xxx) representation of the IPv4 address in hostNbr and writes that string into buffer. The length of buffer must be at least 16.
"},{"location":"Platform-Macros-Error-Reporting/#getnameofuser","title":"getNameOfUser","text":"char *getNameOfUser(char *buffer)\nWrites the user name of the invoking task or process into buffer and returns buffer. The size of buffer must be at least L_cuserid, a constant defined in the stdio.h header file. Returns buffer.
"},{"location":"Platform-Macros-Error-Reporting/#reuseaddress","title":"reUseAddress","text":"int reUseAddress(int fd)\nMakes the address that is bound to the socket identified by fd reusable, so that the socket can be closed and immediately reopened and re-bound to the same port number. Returns 0 on success, -1 on any error.
"},{"location":"Platform-Macros-Error-Reporting/#makeiononblocking","title":"makeIoNonBlocking","text":"int makeIoNonBlocking(int fd)\nMakes I/O on the socket identified by fd non-blocking; returns -1 on failure. An attempt to read on a non-blocking socket when no data are pending, or to write on it when its output buffer is full, will not block; it will instead return -1 and cause errno to be set to EWOULDBLOCK.
"},{"location":"Platform-Macros-Error-Reporting/#watchsocket","title":"watchSocket","text":"int watchSocket(int fd)\nTurns on the \"linger\" and \"keepalive\" options for the socket identified by fd. See socket(2) for details. Returns 0 on success, -1 on any failure.
"},{"location":"Platform-Macros-Error-Reporting/#closeonexec","title":"closeOnExec","text":"void closeOnExec(int fd)\nEnsures that fd will NOT be open in any child process fork()ed from the invoking process. Has no effect on a VxWorks platform.
"},{"location":"Platform-Macros-Error-Reporting/#exception-reporting","title":"Exception Reporting","text":"The functions in this section offer platform-independent capabilities for reporting on processing exceptions.
The underlying mechanism for ICI's exception reporting is a pair of functions that record error messages in a privately managed pool of static memory. These functions -- postErrmsg() and postSysErrmsg() -- are designed to return very rapidly with no possibility of failing, themselves. Nonetheless they are not safe to call from an interrupt service routing (ISR). Although each merely copies its text to the next available location in the error message memory pool, that pool is protected by a mutex; multiple processes might be queued up to take that mutex, so the total time to execute the function is non-deterministic.
Built on top of postErrmsg() and postSysErrmsg() are the putErrmsg() and putSysErrmsg() functions, which may take longer to return. Each one simply calls the corresponding \"post\" function but then calls the writeErrmsgMemos() function, which calls writeMemo() to print (or otherwise deliver) each message currently posted to the pool and then destroys all of those posted messages, emptying the pool.
Recommended general policy on using the ICI exception reporting functions (which the functions in the ION distribution libraries are supposed to adhere to) is as follows:
In the implementation of any ION library function or any ION\ntask's top-level driver function, any condition that prevents\nthe function from continuing execution toward producing the\neffect it is designed to produce is considered an \"error\".\n\nDetection of an error should result in the printing of an\nerror message and, normally, the immediate return of whatever\nreturn value is used to indicate the failure of the function\nin which the error was detected. By convention this value\nis usually -1, but both zero and NULL are appropriate\nfailure indications under some circumstances such as object\ncreation.\n\nThe CHKERR, CHKZERO, CHKNULL, and CHKVOID macros are used to\nimplement this behavior in a standard and lexically terse\nmanner. Use of these macros offers an additional feature:\nfor debugging purposes, they can easily be configured to\ncall sm_Abort() to terminate immediately with a core dump\ninstead of returning a error indication. This option is\nenabled by setting the compiler parameter CORE_FILE_NEEDED\nto 1 at compilation time.\n\nIn the absence of either any error, the function returns a\nvalue that indicates nominal completion. By convention this\nvalue is usually zero, but under some circumstances other\nvalues (such as pointers or addresses) are appropriate\nindications of nominal completion. Any additional information\nproduced by the function, such as an indication of \"success\",\nis usually returned as the value of a reference argument.\n[Note, though, that database management functions and the\nSDR hash table management functions deviate from this rule:\nmost return 0 to indicate nominal completion but functional\nfailure (e.g., duplicate key or object not found) and return\n1 to indicate functional success.]\n\nSo when returning a value that indicates nominal completion\nof the function -- even if the result might be interpreted\nas a failure at a higher level (e.g., an object identified\nby a given string is not found, through no failure of the\nsearch function) -- do NOT invoke putErrmsg().\n\nUse putErrmsg() and putSysErrmsg() only when functions are\nunable to proceed to nominal completion. Use writeMemo()\nor writeMemoNote() if you just want to log a message.\n\nWhenever returning a value that indicates an error:\n\n If the failure is due to the failure of a system call\n or some other non-ION function, assume that errno\n has already been set by the function at the lowest\n layer of the call stack; use putSysErrmsg (or\n postSysErrmsg if in a hurry) to describe the nature\n of the activity that failed. The text of the error\n message should normally start with a capital letter\n and should NOT end with a period.\n\n Otherwise -- i.e., the failure is due to a condition\n that was detected within ION -- use putErrmsg (or\n postErrmg if pressed for time) to describe the nature\n of the failure condition. This will aid in tracing\n the failure through the function stack in which the\n failure was detected. The text of the error message\n should normally start with a capital letter and should\n end with a period.\n\nWhen a failure in a called function is reported to \"driver\"\ncode in an application program, before continuing or exiting\nuse writeErrmsgMemos() to empty the message pool and print a\nsimple stack trace identifying the failure.\nchar *system_error_msg( )\nReturns a brief text string describing the current system error, as identified by the current value of errno.
"},{"location":"Platform-Macros-Error-Reporting/#setlogger","title":"setLogger","text":"void setLogger(Logger usersLoggerName)\nSets the user function to be used for writing messages to a user-defined \"log\" medium. The logger function's calling sequence must match the following prototype:
void usersLoggerName(char *msg);\nThe default Logger function simply writes the message to standard output.
"},{"location":"Platform-Macros-Error-Reporting/#writememo","title":"writeMemo","text":"void writeMemo(char *msg)\nWrites one log message, using the currently defined message logging function. To construct a more complex string, it is customary and safer to use the isprintf function to build a message string first, and then pass that string as an argument to writeMemo.
"},{"location":"Platform-Macros-Error-Reporting/#writememonote","title":"writeMemoNote","text":"void writeMemoNote(char *msg, char *note)\nWrites a log message like writeMemo(), accompanied by the user-supplied context-specific text string in note. The text string can also be build separately using isprintf().
"},{"location":"Platform-Macros-Error-Reporting/#writeerrmemo","title":"writeErrMemo","text":"void writeErrMemo(char *msg)\nWrites a log message like writeMemo(), accompanied by text describing the current system error.
"},{"location":"Platform-Macros-Error-Reporting/#itoa","title":"itoa","text":"char *itoa(int value)\nReturns a string representation of the signed integer in value, nominally for immediate use as an argument to putErrmsg(). [Note that the string is constructed in a static buffer; this function is not thread-safe.]
"},{"location":"Platform-Macros-Error-Reporting/#utoa","title":"utoa","text":"char *utoa(unsigned int value)\nReturns a string representation of the unsigned integer in value, nominally for immediate use as an argument to putErrmsg(). [Note that the string is constructed in a static buffer; this function is not thread-safe.]
"},{"location":"Platform-Macros-Error-Reporting/#posterrmsg","title":"postErrmsg","text":"void postErrmsg(char *text, char *argument)\nConstructs an error message noting the name of the source file containing the line at which this function was called, the line number, the text of the message, and -- if not NULL -- a single textual argument that can be used to give more specific information about the nature of the reported failure (such as the value of one of the arguments to the failed function). The error message is appended to the list of messages in a privately managed pool of static memory, ERRMSGS_BUFSIZE bytes in length.
If text is NULL or is a string of zero length or begins with a newline character (i.e., *text == '\\0' or '\\n'), the function returns immediately and no error message is recorded.
The errmsgs pool is designed to be large enough to contain error messages from all levels of the calling stack at the time that an error is encountered. If the remaining unused space in the pool is less than the size of the new error message, however, the error message is silently omitted. In this case, provided at least two bytes of unused space remain in the pool, a message comprising a single newline character is appended to the list to indicate that a message was omitted due to excessive length.
"},{"location":"Platform-Macros-Error-Reporting/#postsyserrmsg","title":"postSysErrmsg","text":"void postSysErrmsg(char *text, char *arg)\nLike postErrmsg() except that the error message constructed by the function additionally contains text describing the current system error. text is truncated as necessary to assure that the sum of its length and that of the description of the current system error does not exceed 1021 bytes.
"},{"location":"Platform-Macros-Error-Reporting/#geterrmsg","title":"getErrmsg","text":"int getErrmsg(char *buffer)\nCopies the oldest error message in the message pool into buffer and removes that message from the pool, making room for new messages. Returns zero if the message pool cannot be locked for update or there are no more messages in the pool; otherwise returns the length of the message copied into buffer. Note that, for safety, the size of buffer should be ERRMSGS_BUFSIZE.
Note that a returned error message comprising only a single newline character always signifies an error message that was silently omitted because there wasn't enough space left on the message pool to contain it.
"},{"location":"Platform-Macros-Error-Reporting/#writeerrmsgmemos","title":"writeErrmsgMemos","text":"void writeErrmsgMemos( )\nCalls getErrmsg() repeatedly until the message pool is empty, using writeMemo() to log all the messages in the pool. Messages that were omitted due to excessive length are indicated by logged lines of the form \"[message omitted due to excessive length]\".
"},{"location":"Platform-Macros-Error-Reporting/#puterrmsg","title":"putErrmsg","text":"void putErrmsg(char *text, char *argument)\nThe putErrmsg() function merely calls postErrmsg() and then writeErrmsgMemos().
"},{"location":"Platform-Macros-Error-Reporting/#putsyserrmsg","title":"putSysErrmsg","text":"void putSysErrmsg(char *text, char *arg)\nThe putSysErrmsg() function merely calls postSysErrmsg() and then writeErrmsgMemos().
"},{"location":"Platform-Macros-Error-Reporting/#discarderrmsgs","title":"discardErrmsgs","text":"void discardErrmsgs( )\nCalls getErrmsg() repeatedly until the message pool is empty, discarding all of the messages.
"},{"location":"Platform-Macros-Error-Reporting/#printstacktrace","title":"printStackTrace","text":"void printStackTrace( )\nOn Linux machines only, uses writeMemo() to print a trace of the process's current execution stack, starting with the lowest level of the stack and proceeding to the main() function of the executable.
Note that (a) printStackTrace() is only implemented for Linux platforms at this time; (b) symbolic names of functions can only be printed if the -rdynamic flag was enabled when the executable was linked; (c) only the names of non-static functions will appear in the stack trace.
For more complete information about the state of the executable at the time the stack trace snapshot was taken, use the Linux addr2line tool. To do this, cd into a directory in which the executable file resides (such as /opt/bin) and submit an addr2line command as follows:
addr2line -e name_of_executable stack_frame_address where both name_of_executable and stack_frame_address are taken from one of the lines of the printed stack trace. addr2line will print the source file name and line number for that stack frame.
Scott Burleigh, Jay Gao, and Leigh Torgerson
Jet Propulsion Laboratory, California Institute of Technology
Version 4.1.3
"},{"location":"Using-LTP-Config-Tool/#introduction","title":"Introduction","text":"ION open source comes with an Excel spreadsheet to help users configure the LTP protocol to optimize performance based on each user's unique use case.
ION's implementation of LTP is challenging to configure: there are a lot of configuration parameters to set, because the design is intended to support a very wide variety of deployment scenarios that are optimized for a variety of different figures of merit (utility metrics).
LTP-ION is managed as a collection of \"spans\", that is, transmission/reception relationships between the local LTP engine (the engine -- or DTN \"node\" -- that you are configuring) and each other LTP engine with which the local engine can exchange LTP protocol segments. Spans are managed using functions defined in libltpP.c that are offered to the operator by the ltpadmin program.
ltpadmin can be used to add a span, update an existing span, delete a span, provide current information on a specified span, or list all spans. The span configuration parameters that must be set when you add or update a span are as follows:
remote LTP engine number identifying the span. For ION, this is by convention the same as the BP node number as established when the ION database was initialized.maximum number of export sessions that can be held open on this span at any one time. This implements LTP flow control across the span: since no new data can be transmitted until it is appended to a block -- the data to be conveyed in a single export session -- and no new session can be started until the total number of open sessions drops below the maximum, the closure of export sessions regulates the rate at which LTP can be used to transmit data.maximum number of import sessions that will be open on this span at any one time. This value is simply the remote engine's own value for the \"maximum number of export sessions\" parameter.Maximum LTP segment size. This value is typically the maximum permitted size of the payload of each link-layer protocol data unit -- nominally a frame.Aggregation size limit. This is the \"nominal\" size for blocks to be sent over this span: normally LTP will concatenate multiple service data units (such as BP bundles) into a single block until the aggregate size of those service data units exceeds the aggregation size limit, and only then will it divide the block into segments and use the underlying link service to transmit the segments. (Note that it is normal for the aggregation size limit to be exceeded. In this sense, the word \"limit\" is really a misnomer; \"threshold\" would be a better term.)Aggregation time limit. This parameter establishes an alternate means of terminating block aggregation and initiating segment transmission: in the event that service data units are not being presented to LTP rapidly enough to promptly fill blocks of nominal size, LTP will arbitrarily terminate aggregation when the length of time that the oldest service data units in the block have been waiting for transmission exceeds the aggregation time limit.The Link Service Output command. This parameter declares the command that will be used to start the link service output task for this span. The value of this parameter is a string, typically enclosed in single quote marks and typically beginning with the name of the executable object for the task. When the \"udplso\" link service output module is to be used for a given span, the module name is followed by the IPAddress:Port of the remote engine and (optionally) the UDP transmission rate limit in bits per second.In addition, at the time you initialize LTP (normally at the start of the ltpadmin configuration file) you must set one further configuration parameter:
Estimated total number of export sessions, for all spans: this value is used to size the hash table that LTP uses for storing and retrieving export session information.In many cases, the best values for these configuration parameters will not be obvious to the DTN network administrator. To simplify this task, an LTP Configuration Worksheet has been developed.
"},{"location":"Using-LTP-Config-Tool/#worksheet-overview","title":"Worksheet overview","text":"The LTP configuration worksheet is designed to aid in the configuration of a single span -- that is, the worksheet for the span between engines X and Y will provide configuration parameter values for use in commanding ltpadmin on both engine X and engine Y.
The cells of the worksheet are of two general types, Input Cells and Calculated Cells.
Input Cells are cells in which the network administrator must supply values based on project decisions. These cells are yellow-filled.Calculated Cells are cells that are computed by the worksheet based on LTP configuration principles. These cells are grey-filled. The cells are protected from modification (though you can unprotect them if you want by selecting \"Unprotect Sheet\" on the Excel \"Review\" tab).Some of these cells are used as span configuration parameters or are figures of merit for network administrators:
Note: Configuration parameters that are described in detail in this document are numbered. To ease cross referencing between this document and the worksheet, the parameter numbers are placed next to the title cells in the worksheet.*
"},{"location":"Using-LTP-Config-Tool/#input-parameters","title":"Input Parameters","text":"This section provides guidance on the values that must be supplied by the network administrator. Global parameters affect calculated values and configuration file parameters for all spans involving the local LTP engine.
"},{"location":"Using-LTP-Config-Tool/#global-parameters","title":"Global Parameters","text":"Maximum bit error rate is the maximum bit error rate that the LTP should provide for in computing the maximum number of transmission efforts to initiate in the course of transmitting 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, i.e., 10^-6^, one uncorrected (but detected) bit error per million bits transmitted.
The size - estimated size of an LTP report segment in bytes - may vary slightly depending on the sizes of the session numbers in use. 25 bytes is a reasonable estimate.
Values for the following parameters must be provided by the network administrator in order for the worksheet to guide the configuration. Values must be provided for both engine \"X\" and engine \"Y\".
OWLT between engines (sec) is the maximum one-way light time over this span, i.e., the distance between the engines. (Note that this value is assumed to be symmetrical.)engine number for each engine.IP address of each engine. (Assuming udplso will be used as the link service output daemon.)LTP reception port number for each engine. (Again assuming udplso will be used as the link service output daemon.)mean size of the LTP service data units (nominally bundles) sent from this engine over this span.Link service overhead. The expected number of bytes of link service protocol header information per LTP segment.Aggregation size limit - this is the service data unit aggregation size limit for LTP. Note that a suggested value for this parameter is automatically computed as described below, based on available return channel capacity.scheduled transmission rate (in bytes per second) at which this engine will transmit data over this span when the two engines are in contact.Maximum percentage of channel capacity that may be consumed by LTP report segments. A warning will be displayed if other configuration parameters cause this limit to be breached. There are no actual mechanism to enforce this limit in ION. This only set in order to check the estimated report traffic for the current configuration. It is provided as an aid to LTP link designer.estimate of the percentage of all data sent over this span that will be red data, i.e., will be subject to positive and negative LTP acknowledgment.Aggregation time limit. The minimum value is 1 second. Increasing this limit can marginally reduce the number of blocks transmitted, and hence protocol overhead, at times of low communication activity. However, it reduces the \"responsiveness\" of the protocol, increasing the maximum possible delay before transmission of any given service data unit. (This delay is referred to as \"data aggregation latency\".)
Low communication activity is defined as a rate of presentation of service data to LTP that is less than the aggregation size limit divided by the aggregation time limit.LTP segment size (bytes) is the maximum LTP segment size sent over this span by this engine. Typically, this is the maximum permitted size of the payloads of link-layer protocol data units (frames).The maximum number of export sessions. This implements a form of flow control by placing a limit on the number of concurrent LTP sessions used to transmit blocks. Smaller numbers will result in slower transmission, while higher numbers increase storage resource occupancy. Note that a suggested value for this parameter is automatically computed as described below, based on transmission rate and one-way light time.This section provides further information on the methods used to compute the Calculated Cells and also guidance for Input Cell values.
The following parameters are automatically computed based on the values of the basic input parameters.
Estimated \"red\" data transmission rate (bytes/sec) is simply the scheduled transmission rate multiplied by the estimated \"red\" data percentage.Maximum export data in transit (bytes) is the product of the estimated red data transmission rate and the round-trip light time (which is twice the one-way light time between the engines). This is the maximum amount of red data that cannot yet have been positively acknowledged by the remote engine and therefore must be retained in storage for possible retransmission.Values for the following parameters must be chosen by the network administrator on the basis of (a) known project requirements or preferences. (b) the first-order computed parameters, and (c) the computed values of figures of merit that result from tentative parameter value selections, as noted.
#6 Aggregation size limit (revisited). Reducing this parameter tends to increase the number of blocks transmitted, increasing total protocol overhead. The suggested value for this parameter is computed as follows:The threshold block size, expressed in bytes per block, is then given by dividing the local engine's transmission data rate (in bytes per second) by the maximum number of blocks to be transmitted per second.
Est. mean export block size is computed as follows:
a. If the mean service data unit size is so large that aggregation of multiple service data units into a block is never necessary, then that mean service data unit size will in effect determine the mean export block size (one service data unit per block).
b. Otherwise, the mean export block size will be determined by aggregation. If the red data transmission rate is so high that the aggregation time limit will normally never be reached, then the aggregation size limit constitutes the mean export block size. Otherwise, block size will be constrained by aggregation time limit expiration: the estimated mean export block size will be approximated by multiplying the red data transmission rate by the number of seconds in the aggregation time limit.
c. So estimated mean export block size is computed as larger of mean service data unit size and \"expected aggregate block size\", where expected aggregate block size is the lesser of block aggregation size limit and the product of red data transmission rate and aggregation time limit. 16. Estimated blocks transmitted per second are computed as Estimated red data xmit rate (bytes/sec) (parameter 13) divided by Est. mean export block size (parameter 15). 17. Est. Report bytes/sec sent by the remote engine in response to these transmitted blocks is computed as the product of Est. blocks transmitted per second (parameter 16) and Size (mean) of LTP acknowledgment (bytes) (a global parameter). When mean service data unit size is less than the aggregation size limit and the red data transmission rate is high enough to prevent the aggregation time limit from ever being reached, this value will be about the same as the maximum number of bytes of LTP report content that the remote engine may transmit per second as computed above.
Note: increasing the aggregation size limit reduces the block transmission rate at the local engine, reducing the rate of transmission of acknowledgment data at the remote engine; this can be a significant consideration on highly asymmetrical links. 18. Est. segments per block is computed as Est. mean export block size (parameter 15) divided by LTP segment size (bytes) (parameter 11). 19. Est. LTP delivery efficiency on the span is calculated by dividing Est. blocks delivered per second by Est blocks transmitted per second. Reducing the aggregation size limit indirectly improves delivery efficiency by reducing block size, thus reducing the percentage of transmitted blocks that will be affected by the loss of a given number of frames.
#12 Maximum number of export sessions (revisited). Increasing the maximum number of export sessions will tend to improve link bandwidth utilization but will increase the amount of storage space needed for span state retention. The suggested value for this parameter is computed as the maximum export data in transit (bytes) (Parameter 14) divided by Est. mean export block size (parameter 15) as determined above. Configuring the span for a maximum export session count that is less than this limit will make it impossible to fully utilize the link even if all blocks are of estimated mean size.Nominal export SDU's in transit is computed by dividing Nominal export data in transit (bytes) by the Size (mean) of service data units (bytes) (parameter 4).Expected link utilization is then computed by dividing Nominal export data in transit (bytes) by Maximum export data in transit (bytes) (parameter 14). Note that a low value of expected link utilization indicates that a high percentage of the span's transmission capacity is not being used. Utilization can be improved by increasing estimated mean export block size (e.g., by increasing aggregation size limit) or by increasing the maximum number of export sessions.Max data aggregation latency (sec) is simply the value supplied for Aggregation time limit (sec) (parameter 10) as this time limit is never exceeded.Finally, the remaining LTP initialization parameter can be computed when all span configuration decisions have been made.
Maximum number of import sessions is automatically taken from the remote engine's maximum number of export sessions.This research was carried out at the Jet Propulsion Laboratory, California Institute of Technology, under a contract with the National Aeronautics and Space Administration.
"},{"location":"Using-LTP-Config-Tool/#updated-features-may-2021","title":"Updated Features - May 2021","text":"This section describes the following features added to the configuration tool as of May 2021:
The recommended workflow for using the LTP configuration tool is to first establish the space link configuration using the link worksheet before attempting to generate a LTP configuration under the main worksheet. The link worksheet has the following input and computed cells:
Select CCSDS Frame Size (bits) \\[user input\\]-- this cell allows the user to select a standard CCSDS AOS/TM frame size from a drop down list that includes LDPC, Turbo, and Reed-Solomon codes.CCSDS Frame Size (bytes) \\[computed\\]-- converts frame size from bits to bytes.Desired Frame Error Rate \\[user input\\] -- this parameter sets the expected frame error rate of the LTP link in operation. This parameter could be derived from link budget analysis or a mission requirement document.Segment size (byte) \\[user input\\] -- this parameter sets the maximum segment payload size used by LTP. The size of the segment, in relation to the underlying CCSDS frame, will determine the segment error rate and the probability that LTP will need to request retransmission.Ethernet Frame Size (byte) \\[user input\\] -- this is the Ethernet frame size used in a laboratory environment to simulate space link frame losses.Segment Error Rate Computation \\[computed\\] -- this is the LTP segment error rate derived from the frame error rate and the segment and CCSDS frame size selections.*maxBER* Computation \\[computed\\] -- this is the computed maxBER parameter for LTP. The maxBER parameter is what LTP uses to estimate segment error rate, which in turn will affect how LTP handles handshaking failure and repeated retransmission requests. To properly operate LTP, the maxBER value provided must result in the same segment error rate as one expects to encounter in real space link.Ethernet Error Rate Computation \\[computed\\] -- this is the recommended setting for using laboratory Ethernet frame error software/hardware to simulate space link loss. This value is translated from the segment error rate to Ethernet frame error to make sure that laboratory testing provides a statistically equivalent impact on LTP.In the main worksheet described in Section 3, we made the following enhancements:
Aggregation size limit (bytes) -- a green icon is displayed when the input parameter is greater or equal to the suggested value; a red icon is displayed when this parameter is below the suggested value. The suggested value aggregation size limit upper bounds the LTP block rate such that the acknowledgement traffic (report segments) from the receiver to the sender can be supported.Aggregation time limit (sec) -- there are two factors affecting LTP block aggregation: time limit and size limit. The aggregation process stops as soon as one of the two limits is reached. A green icon is displayed if the time limit value in this cell is sufficiently large such that the aggregation process will be size limited, i.e., on average the LTP block aggregation process will reach the size limit before the time limit. This is the nominal and desired configuration unless there is a strict latency requirement that forces one to use a very low aggregation time limit. A red icon is displayed if the time limit will be driving, which means the LTP block size will generally be smaller than the aggregation size limit and the block rate will be higher than desired. If a latency requirement forces the use of a low aggregation time limit, one must check to make sure there is still sufficient bandwidth to support the acknowledgement (report segment) traffic.Est. report bytes/sec sent - this field estimates the bandwidth required to support LTP report segment traffic up to 95 percentile of all cases involving retransmission of missing segments. The segment error rate was derived from the link worksheet. The green icon indicates that estimated report bandwidth is feasible based on current configuration.A simple HeapWord size estimate calculation is added to the main worksheet, based on the following assumptions:
Longest Expected Period to Buffer Data Period (sec) -- this is the expected longest period of time one expects ION will buffer user data. The data accumulation rate is the same as the LTP red data data rate.(32/64) bit system -- this is platform dependent parameter. Heap space is specified in the number of words. For a 32-bit system, each word has 32 bits; for a 64-bit system, each word has 64 bits.Additional Margin -- adds more margin to the model per user's discretionRecommended heapWords value (with 40% for ZCO) -- this is the suggested heapWords value for ionconfig.Recommended heapWords value - iif source data completely in memory -- this is the suggested heapWords value for ionconfig assuming the source data is copied into heap space at the time of bundle creation without using file-resident reference.wmSize recommendation - this is the suggested wmSize parameter to use to support the staging of large quantities of bundles in the heap. This recommended value includes an additional 200% margin. The rationale for the calculation is derived from analysis summarized in the ION Deployment Guide and based on previous studies.In this section, we summarize the finding documented in a powerpoint presentation titled, \"ION DTN/LTP Configuration and ION Memory Usage Analysis\", dated January 2021, that is used as the basis for estimating the heap space required for BP/LTP operation in ION:
With 1 bundle in the system that is under active LTP session, the minimum heap space needed can be approximated as: heap space = S + base
S is the bundle size / segment size x segment header size x 10
If N \\<= M, heap space usage is approximately S x N + 1560 bytes x N + base
S x N is LTP related heap usage, 1560 x N is bundle level heap usage
If N > M, heap space usage is approximately S x M + 1560 bytes x N + base
For bundle in LTP transmission, we count both LTP and bundle level heap usage
Nik Ansell co-authored/contributed to the 2016 version of this document, which has been updated and revised in 2021.
\u00a9 2016 California Institute of Technology. Government sponsorship acknowledged.
"},{"location":"community/Contributing-Code-to-ION/","title":"Contributing Code to ION","text":""},{"location":"community/Contributing-Code-to-ION/#expectations","title":"Expectations","text":"If you plan to contribute to the ION project, please keep these in mind:
The NASA team will review these contributions and determine to either
Incorporate the code into the baseline, or
/contrib folder for continued experimental use,This project has been developed by Dr Lara Suzuki, a Visiting Researcher at NASA JPL.
"},{"location":"community/dtn-gcp-2nodes/ION-Two-Node-on-Cloud-Linux-VMs/#introduction","title":"Introduction","text":"In this project we demonstrate how to run DTN on two nodes on Cloud VM using NASA's implementation of the bundle protocol - ION.
Two-Node Topology
The ION (interplanetary overlay network) software is a suite of communication protocol implementations designed to support mission operation communications across an end-to-end interplanetary network, which might include on-board (flight) subnets, in-situ planetary or lunar networks, proximity links, deep space links, and terrestrial internets.
"},{"location":"community/dtn-gcp-2nodes/ION-Two-Node-on-Cloud-Linux-VMs/#dtn-on-cloud-linux-vms-101","title":"DTN on Cloud Linux VMs 101","text":"We strongly recommend that you firstly get familiar with the Loopback communication of ION running on a single node on Google Cloud Platform.
"},{"location":"community/dtn-gcp-2nodes/ION-Two-Node-on-Cloud-Linux-VMs/#getting-started-with-two-linux-cloud-vms","title":"Getting Started with Two Linux Cloud VMs","text":"On your preferred Cloud provider dashboard, create a Linux VM instance (e.g. for instance Debian). In this tutorial we have created one instance named Golstone in Zone: us-central1 and the another instance named Madrid in Zone: europe-west2-c. The diagram below illustrates the two node communication that we will be developing in this tutorial.
In this section we will walk you through the creation of the host1.rc file. Follow the same steps to create the same file for host2.rc.
ionadmin configuration","text":"The ionadmin configuration assigns an identity (node number) to the node, optionally configures the resources that will be made available to the node, and specifies contact bandwidths and one-way transmission times.
## begin ionadmin \n# Initialization command (command 1). \n# Set this node to be node 1 (as in ipn:1).\n# Use default sdr configuration (empty configuration file name '').\n1 1 ''\n\n# Start ion node\ns\n\n# Add a contact.\n# It will start at +1 seconds from now, ending +3600 seconds from now.\n# It will connect node 1 to itself.\n# It will transmit 100000 bytes/second.\na contact +1 +3600 1 1 100000\n\n# Add more contacts.\n# The network goes 1--2\n# Note that contacts are unidirectional, so order matters.\na contact +1 +3600 1 2 100000\na contact +1 +3600 2 1 100000\na contact +1 +3600 2 2 100000\n\n# Add a range. This is the physical distance between nodes.\n# It will start at +1 seconds from now, ending +3600 seconds from now.\n# It will connect node 1 to itself.\n# Data on the link is expected to take 1 second to reach the other\n# end (One Way Light Time).\na range +1 +3600 1 1 1\n\n# Add more ranges.\n# We will assume every range is one second.\n# Note that ranges cover both directions, so you \n#only need define one range for any combination of nodes.\na range +1 +3600 1 2 1\na range +1 +3600 2 2 1\n\n# Set this node to consume and produce a mean of 1000000 bytes/second.\nm production 1000000\nm consumption 1000000\n## end ionadmin \nltpadmin configuration","text":"The ltpadmin configuration specifies spans, transmission speeds, and resources for the Licklider Transfer Protocol convergence layer
# Initialization command (command 1).\n1 32\n\n# Add a span. (a connection)\na span 1 10 10 1400 10000 1 'udplso `external_IP_of_node_1`:1113'\n\n# Add another span. (to host2) \n# Identify the span as engine number 2.\n# Use the command 'udplso 10.1.1.2:1113' to implement the link itself. \na span 2 10 10 1400 10000 1 'udplso `external_IP_of_node_2`:1113'\n\n# Start command.\n# This command actually runs the link service output commands.\n# It also starts the link service INPUT task 'udplsi `internal_IP_of_node_1`:1113' \n# to listen locally on UDP port 1113 for incoming LTP traffic.\ns 'udplsi `internal_IP_of_node_1`:1113'\n## end ltpadmin \nbpadmin configuration","text":"The bpadmin configuration specifies all of the open endpoints for delivery on your local end and specifies which convergence layer protocol(s) you intend to use.
## begin bpadmin \n# Initialization command (command 1).\n1\n\n# Add an EID scheme.\n# The scheme's name is ipn.\n# This scheme's forwarding engine is handled by the program 'ipnfw.'\n# This scheme's administration program (acting as the custodian\n# daemon) is 'ipnadminep.'\na scheme ipn 'ipnfw' 'ipnadminep'\n\n# Add endpoints.\n# Establish endpoints ipn:1.0, ipn:1.1, and ipn:1.2 on the local node.\n# ipn:1.0 is expected for custodian traffic. The rest are usually\n# used for specific applications (such as bpsink).\n# The behavior for receiving a bundle when there is no application\n# currently accepting bundles, is to queue them 'q', as opposed to\n# immediately and silently discarding them (use 'x' instead of 'q' to\n# discard).\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n\n# Add a protocol. \n# Add the protocol named ltp.\n# Estimate transmission capacity assuming 1400 bytes of each frame (in\n# this case, udp on ethernet) for payload, and 100 bytes for overhead.\na protocol ltp 1400 100\n\n# Add an induct. (listen)\n# Add an induct to accept bundles using the ltp protocol.\n# The duct's name is 1 (this is for future changing/deletion of the\n# induct). \n# The induct itself is implemented by the 'ltpcli' command.\na induct ltp 1 ltpcli\n\n# Add an outduct (send to yourself).\n# Add an outduct to send bundles using the ltp protocol.\na outduct ltp 1 ltpclo\n\n# Add an outduct. (send to host2)\n# Add an outduct to send bundles using the ltp protocol.\na outduct ltp 2 ltpclo\n\n# Start bundle protocol engine, also running all of the induct, outduct,\n# and administration programs defined above\ns\n## end bpadmin \nipnadmin configuration","text":"The ipnadmin configuration maps endpoints at \"neighboring\" (topologically adjacent, directly reachable) nodes to convergence-layer addresses.
## begin ipnadmin \n# ipnrc configuration file for host1 in a 3node ltp/tcp test. \n# Essentially, this is the IPN scheme's routing table.\n\n# Add an egress plan.\n# Bundles to be transmitted to node number 1 (that is, yourself).\n# The plan is to queue for transmission on protocol 'ltp' using\n# the outduct identified as '1.'\na plan 1 ltp/1\n\n# Add other egress plans.\n# Bundles for elemetn 2 can be transmitted directly to host2 using\n# ltp outduct identified as '2.' \na plan 2 ltp/2\n## end ipnadmin\nionsecadmin configuration","text":"The ionsecadmin enables bundle security (also avoid error messages in ion.log).
## begin ionsecadmin\n# Enable bundle security and avoid error messages in ion.log\n1\n## end ionsecadmin\nOn the terminal of host 1 execute the command
$ ionstart -I host1.rc\nhost 2 execute the command $ ionstart -I host2.rc\nhost 1 to host 2, you must firstly start bpsink in host 2 by executing the command below $ bpsink ipn:2.1 &\nhost 1, enter the following command and hit enter $ echo \"hi\" | bpsource ipn:2.1\nhost 2 the following message $ ION event: Payload delivered.\n$ payload length is 2.\n$ 'hi'\nhost 2 sending a hello message to host 1. "},{"location":"community/dtn-gcp-2nodes/rc_files/host1-start-script-2node/","title":"ION Start Script Example","text":"Note: place this in a file named host1.rc
## begin ionadmin \n1 1 ''\ns \n\na contact +1 +3600 1 1 100000\na contact +1 +3600 1 2 100000\na contact +1 +3600 2 1 100000\na contact +1 +3600 2 2 100000\n\na range +1 +3600 1 1 1\na range +1 +3600 1 2 1\na range +1 +3600 2 2 1\n\nm production 1000000\nm consumption 1000000\n## end ionadmin \n\n## begin ltpadmin \n1 32\n\na span 1 10 10 1400 10000 1 'udplso `external_IP_of_node_1`:1113'\na span 2 10 10 1400 10000 1 'udplso `external_IP_of_node_2`:1113'\ns 'udplsi `internal_IP_of_node_1`:1113'\n## end ltpadmin \n\n## begin bpadmin \n1\na scheme ipn 'ipnfw' 'ipnadminep'\n\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n\na protocol ltp 1400 100\na induct ltp 1 ltpcli\na outduct ltp 1 ltpclo\na outduct ltp 2 ltpclo\n\ns\n## end bpadmin \n\n## begin ipnadmin \na plan 1 ltp/1\na plan 2 ltp/2\n## end ipnadmin\n\n## begin ionsecadmin\n1\n## end ionsecadmin\nNote: place this in a file named host2.rc
## begin ionadmin \n1 2 ''\ns\n\na contact +1 +3600 1 1 100000\na contact +1 +3600 1 2 100000\na contact +1 +3600 2 1 100000\na contact +1 +3600 2 2 100000 \n\na range +1 +3600 1 1 1\na range +1 +3600 1 2 1\na range +1 +3600 2 2 1\n\nm production 1000000\nm consumption 1000000\n## end ionadmin \n\n## begin ltpadmin \n1 32\n\na span 1 10 10 1400 10000 1 'udplso `external_IP_of_node_1`:1113'\na span 2 10 10 1400 10000 1 'udplso `external_IP_of_node_2`:1113'\ns 'udplsi `internal_IP_of_node_2`:1113'\n## end ltpadmin \n\n## begin bpadmin \n1\na scheme ipn 'ipnfw' 'ipnadminep'\n\na endpoint ipn:2.0 q\na endpoint ipn:2.1 q\na endpoint ipn:2.2 q\n\na protocol ltp 1400 100\na induct ltp 2 ltpcli\na outduct ltp 2 ltpclo\na outduct ltp 1 ltpclo\n\ns\n## end bpadmin \n\n## begin ipnadmin \na plan 1 ltp/1\na plan 2 ltp/2\n## end ipnadmin\n\n## begin ionsecadmin\n1\n## end ionsecadmin\nThis project has been developed by Dr Lara Suzuki, a visiting Researcher at NASA JPL.
In this tutorial we will demonstrate how to connect a Raspberry Pi and Sensor Hat onto Google Cloud using cloud Pub/Sub on host 1 and serving the messages over DTN to host 2. This tutorial follows the [Running DTN on Google Cloud using a Two-Node Ring] tutorial and uses the configurations of host 1 and host 2 as described in the tutorial.
In this tutorial we use Raspberry Pi 4 model B (2018) and Sense Hat Version 1.0.
The first step is to be sure your Pi can connect to the Internet. You can either plug in an ethernet cable, or if you\u2019re using WiFi, scan for networks your Pi can see. Plug your Pi in a monitor, and when it starts, at the top right corner you can find the wifi logo. Select the network you want to connect to. Once that is connected open your browser to check whether you can access the Internet.
"},{"location":"community/dtn-gcp-iot-main/ION-and-IOT-on-Linux-VMs-running-on-Cloud-Computing/#library-dependency-setup","title":"Library dependency setup","text":"The first thing to do is to make sure that the places where Raspberry Pi will be getting its libraries from is current. For this, on your Pi's terminal, run the following command:
$ sudo apt-get update\npyjwt). The meta-model for communication used on the cloud Pub/Sub is based on publish/subscribe messaging technology provided by the MQTT (MQ Telemetry Transport) protocol (library paho-mqtt). MQTT is a topic-based publish/subscribe communications protocol that is designed to be open, simple, lightweight, easy-to-implement, and efficient in terms of processor, memory, and network resources. On your Pi's terminal run the following commands
$ sudo apt-get install build-essential\n$ sudo apt-get install libssl-dev\n$ sudo apt-get install python-dev\n$ sudo apt-get install libffi-dev\n$ sudo pip install paho-mqtt\npyjwt library and its dependency, the cryptography library . $ sudo pip install pyjwt\n$ sudo pip install cryptography\n$ sudo apt get install sense-hat\nIn order to authenticate in Google Cloud IoT Core, we need a SSL certificate. We will create an RSA with X509 wrapper. For this, execute the following command on your Pi's terminal:
$ openssl req -x509 -newkey rsa:2048 -keyout sensing_private.pem -nodes -out demo.pub -subj \u201c/CN=unused\u201d\nOnce your Raspberry Pi is fully set up, follow the instructions of your Cloud provider to create a Registry of your new Pub/Sub service. For your Pub/Sub 'topic', create a topic named: sensing
To connect your device on your cloud provider, you will likely to need to use an authentication method. In our case we use authentication using a Public Key in the format RS256_X509.
To copy the content of your Pi's public key, on the Pi's terminal run:
$ cat demo.pub\nCopy everything, including the tages, between
-----BEGIN PUBLIC KEY-----\n-----END PUBLIC KEY-----\nPublic Key Value textbox."},{"location":"community/dtn-gcp-iot-main/ION-and-IOT-on-Linux-VMs-running-on-Cloud-Computing/#create-a-subscription-to-listen-to-the-pubsub-topic","title":"Create a Subscription to listen to the Pub/Sub Topic","text":"On your cloud provide Console, create a 'Subscription' to listen to the topic sensing we created in the previous steps. Now you should have all the pieces needed to send telemetry data from your Pi to a Pub/Sub service on a VM instance running on the cloud!
The code on this repository named sense.py is based on the implementation of GabeWeiss.
In the code, edit the following fields:
ssl_private_key_filepath = '/home/pi/sensing_private.pem'\nssl_algorithm = 'RS256'\nroot_cert_filepath = '/home/pi/roots.pem'\nproject_id = 'if you have to use a project ID identifier in your cloud service'\nregistry_id = 'name of your registry'\ndevice_id = 'name of your device'\n$ python3 sense.py\nLog into the VM host 1. In the VM go to the base directory of ION and create a folder named dtn
$ mkdir dtn\niot.py. In this file configure the following parameters: subscription_path = subscriber.subscription_path(\n 'ID_OF_YOUR_CLOUD_PROJECT', 'ID_OF_YOUR_SUBSCRIPTION')\nhost 2 as the receiver of the telemetry data: os.system(f'echo \"{value}\" | bpsource ipn:2.1')\nhost 1 and host 2, start ion: $ ionstart -I hostX.rc #where X is the number of the host\nhost 2, start bpsink $ bpsink ipn:2.1 &\nhost 1, start iot.py $ python3 iot.py\nhost 1 you should see the print out of the telemetry data received as below: On the terminal of host 2 you should see the payloads delivered. Please note that messages beyond 80 characters are not shown on bpsink:
Note: place this in a file named iot.py
```` import os import time from google.cloud import pubsub_v1 subscriber = pubsub_v1.SubscriberClient()
"},{"location":"community/dtn-gcp-iot-main/iot-python-script/#the-subscription_path-method-creates-a-fully-qualified-identifier","title":"Thesubscription_path method creates a fully qualified identifier","text":""},{"location":"community/dtn-gcp-iot-main/iot-python-script/#in-the-form-projectsproject_idsubscriptionssubscription_name","title":"in the form projects/{project_id}/subscriptions/{subscription_name}","text":"subscription_path = subscriber.subscription_path( 'ID_OF_YOUR_GOOGLE_CLOUD_PROJECT', 'ID_OF_YOUR_SUBSCRIPTION') def callback(message): value = message.data os.system(f'echo \"{value}\" | bpsource ipn:2.1') print('Received message: {}'.format(value)) message.ack() # Acknowledges the receipt of the message and remove it from the topic queue subscriber.subscribe(subscription_path, callback=callback)
"},{"location":"community/dtn-gcp-iot-main/iot-python-script/#the-subscriber-is-non-blocking-we-must-keep-the-main-thread-from","title":"The subscriber is non-blocking. We must keep the main thread from","text":""},{"location":"community/dtn-gcp-iot-main/iot-python-script/#exiting-to-allow-it-to-process-messages-asynchronously-in-the-background","title":"exiting to allow it to process messages asynchronously in the background.","text":"print('Listening for messages on {}'.format(subscription_path)) while True: time.sleep(60)
````
"},{"location":"community/dtn-gcp-iot-main/sense-python-script/","title":"ION Start Script Example","text":"Note: place this in a file named sense.py
```` from sense_hat import SenseHat import Adafruit_DHT import time import datetime import time import jwt import paho.mqtt.client as mqtt
"},{"location":"community/dtn-gcp-iot-main/sense-python-script/#define-some-project-based-variables-to-be-used-below-this-should-be-the-only","title":"Define some project-based variables to be used below. This should be the only","text":""},{"location":"community/dtn-gcp-iot-main/sense-python-script/#block-of-variables-that-you-need-to-edit-in-order-to-run-this-script","title":"block of variables that you need to edit in order to run this script","text":"ssl_private_key_filepath = '' # The .pem file of your Pi ssl_algorithm = 'RS256' root_cert_filepath = '' # The .pem file of Google project_id = '' # The project ID on Google Cloud gcp_location = '' # The zone where your project is deployed registry_id = '' # The ID of your registry on Google IoT Core device_id = '' # The ID of your Pi as set up on Google IoT Core
cur_time = datetime.datetime.utcnow()
DHT_SENSOR = Adafruit_DHT.DHT11 DHT_PIN = 4
def create_jwt(): token = { 'iat': cur_time, 'exp': cur_time + datetime.timedelta(minutes=60), 'aud': project_id }
with open(ssl_private_key_filepath, 'r') as f: private_key = f.read()
return jwt.encode(token, private_key, ssl_algorithm)
_CLIENT_ID = 'projects/{}/locations/{}/registries/{}/devices/{}'.format(project_id, gcp_location, registry_id, device_id) _MQTT_TOPIC = '/devices/{}/events'.format(device_id)
client = mqtt.Client(client_id=_CLIENT_ID) client.username_pw_set( username='unused', password=create_jwt())def error_str(rc): return '{}: {}'.format(rc, mqtt.error_string(rc))
def on_connect(unusued_client, unused_userdata, unused_flags, rc): print('on_connect', error_str(rc))
def on_publish(unused_client, unused_userdata, unused_mid): print('on_publish')
client.on_connect = on_connect client.on_publish = on_publish
client.tls_set(ca_certs=root_cert_filepath) client.connect('mqtt.googleapis.com', 8883) client.loop_start()
"},{"location":"community/dtn-gcp-iot-main/sense-python-script/#could-set-this-granularity-to-whatever-we-want-based-on-device-monitoring-needs-etc","title":"Could set this granularity to whatever we want based on device, monitoring needs, etc","text":"temperature = 0 humidity = 0 pressure = 0
sense = SenseHat()
while True: cur_temp = sense.get_temperature() cur_pressure = sense.get_pressure() cur_humidity = sense.get_humidity() if cur_temp == temperature and cur_humidity == humidity and cur_pressure == pressure: time.sleep(1) continue temperature = cur_temp pressure = cur_pressure humidity = cur_humidity
payload = '{{ \"ts\": {}, \"temperature\": {}, \"pressure\": {}, \"humidity\": {} }}'.format(cur_time, \"%.1f C\" % temperature,\"%.2f Millibars\" % press$
client.publish(_MQTT_TOPIC, payload, qos=1)
print(\"{}\\n\".format(payload))
sense.set_rotation(180) # Set LED matrix to scroll from right to left
sense.show_message(\"%.1f C\" % temperature, scroll_speed=0.10, text_colour=[0, 255, 0]) # Show the temperature on the LED Matrix
time.sleep(10)
````
"},{"location":"community/dtn-gcp-ltp-tcp-main/ION-LTP-TCP-on-Azure/","title":"Three-Node Network communication via DTN on Google Cloud Platform and Windows Azure","text":"This project has been developed by Dr Lara Suzuki, a Visiting Researcher at NASA JPL.
"},{"location":"community/dtn-gcp-ltp-tcp-main/ION-LTP-TCP-on-Azure/#introduction","title":"Introduction","text":"This is the third tutorial on a series of DTN on Google Cloud tutorials. In this tutorial we will introduce you to Windows Azure, and how to configure a 3-node network using ION. The figure below shows the network we will be building. Note that this example network uses two different convergence layers: TCP and LTP. This can illustrates the case of a terrestrial connection with two interplanetary internet nodes.
"},{"location":"community/dtn-gcp-ltp-tcp-main/ION-LTP-TCP-on-Azure/#getting-started-on-windows-azure","title":"Getting Started on Windows Azure","text":"Sign up for a free account on Windows Azure. Once your free account is set up, log into the Azure Portal. Under Azure Services, click Virtual Machines. In the Virtual Machines window, click Add and follow the steps below. 1. Click Add then Virtual Machine 2. Subscription free trial 3. In Resource Group select Create New and name it dtn 4. In Virtual Machine name give it a name. In our example it is named Canberra 5. In Region select the region closest to you or of your choice. In our example it is Australia Central 6. In Image select Debian 10 \"Buster\" Gen 1 7. Size leave it as Standard 8. Under Administrator Account select either the use of SSH public key or Password 9. For Select inbound ports leave SSH(22) 10. Click Review and Create, then click Create
To get ION working you must enable the inbound traffic to port 1113 and port 4556 - IANA assigned default DTN TCP port. To enable inbound traffic in those ports, at the top right of your window, hit Home, then Virtual Machines. Click on the Virtual Machine you have just created. On the new loaded page, under Settings click Networking as shown in the image below.
On the networking page, click Add inbound port rule. Select Source as Any, on Source port ranges add the port numbers you want to allow inbound traffic, select the Protocol, the Action (Allow), and add a high Priority (e.g. 380). Give it a name and hit Add. You now can execute ION and the induct and outducts will work.
In this section, we assume that host 3 has an IP address of 10.0.0.3. Please modify this for your uses. Please note that in this tutorial we are not covering routing, therefore, host2 cannot communicate with host3. The routing tutorial can be found here.
This network is created by running the following command on host 1
ionstart -I host1.rc\nhost 2: ionstart -I host2.rc\nhost 3 ionstart -I host3.rc\nFor the configuration files host 1 and host 2, follow the examples given in the tutorial Running DTN on Google Cloud using a Two-Node Ring
. Remember to add contact, range, span, outduct and a plan for host 3. Below is the configuration file host3.rc.
The ionadmin configuration uses tcp from host 2 to host 3
## begin ionadmin \n# ionrc configuration file for host3 in a 3node tcp/ltp test.\n# This uses tcp from 1 to 3.\n# \n# Initialization command (command 1). \n# Set this node to be node 3 (as in ipn:3).\n# Use default sdr configuration (empty configuration file name '').\n1 3 ''\n# start ion node\ns\n# Add a contact.\n# It will start at +1 seconds from now, ending +3600 seconds from now.\n# It will connect node 3 to itself\n# It will transmit 100000 bytes/second.\na contact +1 +3600 3 3 100000\n\n# Add more contacts.\n# They will connect 2 to 3, 3 to 2, and 3 to itself\n# Note that contacts are unidirectional, so order matters.\na contact +1 +3600 3 2 100000\na contact +1 +3600 2 3 100000\na contact +1 +3600 2 2 100000\n\n# Add a range. This is the physical distance between nodes.\na range +1 +3600 3 3 1\n\n# Add more ranges.\na range +1 +3600 2 2 1\na range +1 +3600 2 3 1\n\n# set this node to consume and produce a mean of 1000000 bytes/second.\nm production 1000000\nm consumption 1000000\n## end ionadmin \nThe bpadmin configuration uses adds the endpoints and the protocol tcp. In the protocol section, it estimates transmission capacity assuming 1400 bytes of each frame (in this case, tcp on ethernet) for payload, and 100 bytes for overhead. The induct and outduct will listen on port 4556, the IANA assigned default DTN TCP convergence layer port. The induct itself is implemented by the tcpcli command and the outduct is implemented by the tcpclo
## begin bpadmin \n# bprc configuration file for host3 in a 3node test.\n# Initialization command (command 1).\n1\n\n# Add an EID scheme.\na scheme ipn 'ipnfw' 'ipnadminep'\n\n# Add endpoints.\na endpoint ipn:3.0 q\na endpoint ipn:3.1 q\na endpoint ipn:3.2 q\n\n# Add a protocol. \n# Add the protocol named tcp.\na protocol tcp 1400 100\n\n# Add an induct. (listen)\na induct tcp 10.0.0.3:4556 tcpcli\n\n# Add an outduct (send to yourself).\na outduct tcp 10.0.0.3:4556 tcpclo\n\n# Add an outduct. (send to host2)\na outduct tcp external_ip_of_host_2:4556 tcpclo\n\n# Start bundle protocol engine, also running all of the induct, outduct,\n# and administration programs defined above.\ns\n## end bpadmin \nThe ipnadmin configuration adds the egress plans (to host 3 itself and to host 2) using tcp.
## begin ipnadmin \n# ipnrc configuration file for host1 in the 3node tcp network.\n# Add an egress plan (to yourself).\na plan 2 tcp/10.0.0.3:4556\n# Add an egress plan (to the host 2).\na plan 2 tcp/external_IP_of_node_2:4556\n## end ipnadmin\nThe ionsecadmin configuration enables bundle security
## begin ionsecadmin\n1\n## end ionsecadmin\nNote: place this in a file named host3.rc
## begin ionadmin \n# ionrc configuration file for host3 in a 3node tcp/ltp test.\n# This uses tcp from 1 to 3.\n# \n# Initialization command (command 1). \n# Set this node to be node 3 (as in ipn:3).\n# Use default sdr configuration (empty configuration file name '').\n1 3 ''\n# start ion node\ns\n# Add a contact.\n# It will start at +1 seconds from now, ending +3600 seconds from now.\n# It will connect node 3 to itself\n# It will transmit 100000 bytes/second.\na contact +1 +3600 3 3 100000\n\n# Add more contacts.\n# They will connect 2 to 3, 3 to 2, and 3 to itself\n# Note that contacts are unidirectional, so order matters.\na contact +1 +3600 3 2 100000\na contact +1 +3600 2 3 100000\na contact +1 +3600 2 2 100000\n\n# Add a range. This is the physical distance between nodes.\na range +1 +3600 3 3 1\n\n# Add more ranges.\na range +1 +3600 2 2 1\na range +1 +3600 2 3 1\n\n# set this node to consume and produce a mean of 1000000 bytes/second.\nm production 1000000\nm consumption 1000000\n## end ionadmin \n\n## begin bpadmin \n# bprc configuration file for host3 in a 3node test.\n# Initialization command (command 1).\n1\n\n# Add an EID scheme.\na scheme ipn 'ipnfw' 'ipnadminep'\n\n# Add endpoints.\na endpoint ipn:3.0 q\na endpoint ipn:3.1 q\na endpoint ipn:3.2 q\n\n# Add a protocol. \n# Add the protocol named tcp.\na protocol tcp 1400 100\n\n# Add an induct. (listen)\na induct tcp 10.0.0.3:4556 tcpcli\n\n# Add an outduct (send to yourself).\na outduct tcp 10.0.0.3:4556 tcpclo\n\n# Add an outduct. (send to host2)\na outduct tcp external_ip_of_host_2:4556 tcpclo\n\n# Start bundle protocol engine, also running all of the induct, outduct,\n# and administration programs defined above.\ns\n## end bpadmin \n\n## begin ipnadmin \n# ipnrc configuration file for host1 in the 3node tcp network.\n# Add an egress plan (to yourself).\na plan 2 tcp/10.0.0.3:4556\n# Add an egress plan (to the host 2).\na plan 2 tcp/external_IP_of_node_2:4556\n## end ipnadmin\n\n## begin ionsecadmin\n1\n## end ionsecadmin\nThis project has been developed by Dr Lara Suzuki, a visiting researcher at NASA JPL.
"},{"location":"community/dtn-gcp-main/ION-One-Node-on-Cloud-Linux-VM/#introduction","title":"Introduction","text":"In this project we demonstrate how to run DTN on a cloud VM using NASA's implementation of the bundle protocol - ION. DTN stands for delay-tolerant and disruption-tolerant networks.
\"It is an evolution of the architecture originally designed for the Interplanetary Internet, a communication system envisioned to provide Internet-like services across interplanetary distances in support of deep space exploration\" Cerf et al, 2007.
The ION (interplanetary overlay network) software is a suite of communication protocol implementations designed to support mission operation communications across an end-to-end interplanetary network, which might include on-board (flight) subnets, in-situ planetary or lunar networks, proximity links, deep space links, and terrestrial internets.
"},{"location":"community/dtn-gcp-main/ION-One-Node-on-Cloud-Linux-VM/#getting-started-with-cloud-linux-vms","title":"Getting Started with Cloud Linux VMs","text":"On your preferred Cloud provider dashboard, create a Linux VM (e.g. Debian).
When prompted, select the reagion closest to you. If you are prompted to select the machine type, select the configuration that will suit your needs. I have selected the a machine which has 2 virtual CPUs and 4 GB memory.
For boot disk, in this tutorial we are using Debian GNU/Linux 10 (buster). In firewall configurations, I have selected it Allow HTTP and HTTPS.
Once the VM is started you can SSH directly into the VM.
Mac and Linux support SSH connection natively. You just need to generate an SSH key pair (public key/private key) to connect securely to the virtual machine.
To generate the SSH key pair to connect securely to the virtual machine, follow these steps:
ssh-keygen -t rsa . ENTER to accept the default locationcat ~/.ssh/id_rsa.pub . Back in the Cloud VM tools, follow your provider's direction on how to SSH into the VM. If you are requested to provide your SSH Keys, locate the SSH key file in your computer and inform it here.
Now you can just open your terminal on your Mac or Linux machine and type ssh IP.IP.IP.IP and you will be on the VM (IP.IP.IP.IP is the external IP of the VM).
This example uses ION version 4.0.1, which can be downloaded here. ION 4.0.1 uses the version 7 of the Bundle Protocol.
On your VM execute the following commands
$ sudo apt update\n$ sudo apt install build-essential -y\n$ sudo apt-get install wget -y\n$ wget https://sourceforge.net/projects/ion-dtn/files/ion-open-source-4.0.1.tar.gz/download\n$ tar xzvf download\nFollow the standard autoconf method for compiling the project. In the base ION directory run:
$ ./configure\n$ make\n````\nFinally, install (requires root privileges):\nFor Linux based systems, you may need to run sudo ldconfig with no arguments after install.
The following tools are a few examples of programs availale to you after ION is built:
1. Daemon and Configuration: - ionadmin is the administration and configuration interface for the local ION node contacts and manages shared memory resources used by ION. - ltpadmin is the administration and configuration interface for LTP operations on the local ION node. - bsspadmin is the administrative interface for operations of the Bundle Streaming Service Protocol on the local ion node. - bpadmin is the administrative interface for bundle protocol operations on the local ion node. - ipnadmin is the administration and configuration interface for the IPN addressing system and routing on the ION node. (ipn:) - ionstart is a script which completely configures an ION node with the proper configuration file(s). - ionstop is a script which cleanly shut down all of the daemon processes. - killm is a script which releases all of the shared-memory resources that had been allocated to the state of the node. This actually destroys the node and enables a subsequent clean new start (the \u201cionstart\u201d script) to succeed. - ionscript is a script which aides in the creation and management of configuration files to be used with ionstart.
2. Simple Sending and Receiving: - bpsource and bpsink are for testing basic connectivity between endpoints. bpsink listens for and then displays messages sent by bpsource. - bpsendfile and bprecvfile are used to send files between ION nodes.
3. Testing and Benchmarking: - bpdriver benchmarks a connection by sending bundles in two modes: request-response and streaming. - bpecho issues responses to bpdriver in request-response mode. - bpcounter acts as receiver for streaming mode, outputting markers on receipt of data from bpdriver and computing throughput metrics.
4. Logging: - By default, the administrative programs will all trigger the creation of a log file called ion.log in the directory where the program is called. This means that write-access in your current working directory is required. The log file itself will contain the expected log information from administrative daemons, but it will also contain error reports from simple applications such as bpsink.
Below we present the configuration files that you should be aware and configure for ION to execute correctly.
ionadmin's configuration file, assigns an identity (node number) to the node, optionally configures the resources that will be made available to the node, and specifies contact bandwidths and one-way transmission times. Specifying the \"contact plan\" is important in deep-space scenarios where the bandwidth must be managed and where acknowledgments must be timed according to propagation delays. It is also vital to the function of contact-graph routing - How To
ltpadmin's configuration file, specifies spans, transmission speeds, and resources for the Licklider Transfer Protocol convergence layer - How To
bpadmin's configuration file, specifies all of the open endpoints for delivery on your local end and specifies which convergence layer protocol(s) you intend to use. With the exception of LTP, most convergence layer adapters are fully configured in this file - How To
ipnadmin's configuration file, maps endpoints at \"neighboring\" (topologically adjacent, directly reachable) nodes to convergence-layer addresses. This file populates the ION analogue to an ARP cache for the \"ipn\" naming scheme - How To
ionsecadmin's configuration file, enables bundle security to avoid error messages in ion.log - How To
Assuming no errors occur with the configuration files above, we are now ready to test loopback communications, and also learn how to properly stop ION nodes. The below items are covered in this How To page.
A script has been created which allows a more streamlined configuration and startup of an ION node. This script is called ionstart, and it has the following syntax. Don't run it yet; we still have to configure it!
ionstart -I <rc filename >\nfilename: This is the name for configuration file which the script will attempt to use for the various configuration commands. The script will perform a sanity check on the file, splitting it into command sections appropriate for each of the administration programs. Configuration information (such as routes, connections, etc) can be specified one of two ways for any of the individual administration programs:
(Recommended) Creating a configuration file and passing it to ionadmin, bpadmin, ipnadmin, ltpadmin, etc. either directly or via the ionstart helper script.
Assuming no errors occur with the configuration above, we are now ready to test loopback communications. In one terminal, we have to run the start script alongside the configuration files.
ionstart -i host1.ionrc -l host1.ltprc -b host1.bprc -p host1.ipnrc\nThis command will run the appropriate administration programs, in order, with the appropriate configuration files. Don't worry that the command is lengthy and unwieldly; we will show you how to make a more clean single configuration file later. The image below illustrates the start of the administration programs.
Once the daemon is started, run:
bpsink ipn:1.1 &\nThis will begin constantly listening on the Endpoint ID with the endpoint_number 1 on service_number 1, which is used for testing.
Now run the command:
bpsource ipn:1.1\nThis will begin sending messages you type to the Endpoint ID ipn:1.1, which is currently being listened to by bpsink. Type messages into bpsource, press enter, and see if they are reported by bpsink. In the example below I am using the Endpoint ID ipn:2.1.
"},{"location":"community/dtn-gcp-main/Running-ION/#stopping-the-daemon","title":"Stopping the Daemon","text":"As the daemon launches many ducts and helper applications, it can be complicated to turn it all off. The script similar to ionstart exists called ionstop, which tears down the ion node in one step. You can call it like so:
ionstop\nionstop script is shown below. # shell script to stop node\n#!/bin/bash\nbpadmin .\nsleep 1\nltpadmin .\nsleep 1\nionadmin .\nAfter stopping the daemon, you can start fresh with a brand-new node. To do that, you first need to run the killm script (to destroy all of the persistent state objects in shared memory); after that, you can run your ionstart script again, whether with changes or not. Do remember that the ion.log file is still present, and will just keep growing as you experiment with ION. You can of course periodically delete entries out of the ion.log file.
To create a single file host1.rc out of the various configuration files defined in the previous section, run this command:
ionscript -i host1.ionrc -p host1.ipnrc -l host1.ltprc -b host1.bprc -O host1.rc\nOnce you have a single configuration file, starting the ION node is a single command:
ionstart -I host1.rc\nAssuming no errors occur with the configuration files above, we are now ready to test a Loopback communication, and also learn how to properly stop the ION node. The single rc file for host 1 can be found here.
The execution of the host should be performed using the command
$ ionstart -I host1.rc\nThe image below illustrates the loopback communication using bpsink and bpsource.
To stop ION in the VM instance, use the command
$ ionstop. \nGiven to bpadmin either as a file or from the daemon command line, this file configures the endpoints through which this node's Bundle Protocol Agent (BPA) will communicate. We will assume the local BPA's node number is 1; as for LTP, in ION node numbers are used to identify bundle protocol agents.
"},{"location":"community/dtn-gcp-main/bp-config/#initialise-the-bundle-protocol","title":"Initialise the bundle protocol","text":"1\n````. \n\n`1` refers to this being the initialization or ''first'' command.\n\n## Add support for a new Endpoint Identifier (EID) scheme\n`a` means that this command will add something.\n\n`scheme` means that this command will add a scheme.\n\n`ipn` is the name of the scheme to be added.\n\n`'ipnfw'` is the name of the IPN scheme's forwarding engine daemon.\n\n`'ipnadminep'` is the name of the IPN scheme's custody transfer management daemon.\n\n## Establishes the BP node's membership in a BP endpoint\n`a` means that this command will add something.\n\n`endpoint` means that this command adds an endpoint.\n\n`ipn` is the scheme name of the endpoint.\n\n`1.0` is the scheme-specific part of the endpoint. For the IPN scheme the scheme-specific part always has the form nodenumber:servicenumber. Each node must be a member of the endpoint whose node number is the node's own node number and whose service number is 0, indicating administrative traffic.\n\n`q` means that the behavior of the engine, upon receipt of a new bundle for this endpoint, is to queue it until an application accepts the bundle. The alternative is to silently discard the bundle if no application is actively listening; this is specified by replacing q with x.\n\n\n## Specify two more endpoints that will be used for test traffic\n## Add support for a convergence-layer protocol\n`a` means that this command will add something.\n\n`protocol` means that this command will add a convergence-layer protocol.\n\n`ltp` is the name of the convergence-layer protocol.\n\n`1400` is the estimated size of each convergence-layer protocol data unit (in bytes); in this case, the value is based on the size of a UDP/IP packet on Ethernet.\n\n`100` is the estimated size of the protocol transmission overhead (in bytes) per convergence-layer procotol data unit sent.\n\n\n## Add an induct, through which incoming bundles can be received from other nodes\n`a` means that this command will add something.\n\n`induct` means that this command will add an induct.\n\n`ltp` is the convergence layer protocol of the induct.\n\n`1` is the identifier of the induct, in this case the ID of the local LTP engine.\n\n`ltpcli` is the name of the daemon used to implement the induct.\n\n\n\n## Add an outduct, through which outgoing bundles can be sent to other nodes\n`a` means that this command will add something.\n\n`outduct` means that this command will add an outduct.\n\n`ltp` is the convergence layer protocol of the outduct.\n\n`1` is the identifier of the outduct, the ID of the convergence-layer protocol induct of some remote node. \n\n`ltpclo` is the name of the daemon used to implement the outduct.\n\n\n## Start the bundle engine including all daemons for the inducts and outducts\n## Final configuration file - `host1.bprc`\n1 a scheme ipn 'ipnfw' 'ipnadminep' a endpoint ipn:1.0 q a endpoint ipn:1.1 q a endpoint ipn:1.2 q a protocol ltp 1400 100 a induct ltp 1 ltpcli a outduct ltp 1 ltpclo s
"},{"location":"community/dtn-gcp-main/bp-config/#end-bpadmin","title":"end bpadmin","text":"````
"},{"location":"community/dtn-gcp-main/host1-start-script/","title":"ION Start Script Example","text":"Note: place this in a file named host1.rc
## begin ionadmin\n1 1 ''\ns\n# Define contact plan\na contact +1 +3600 1 1 100000\n\n# Define 1sec OWLT between nodes\na range +1 +3600 1 1 1\nm production 1000000\nm consumption 1000000\n## end ionadmin\n\n## begin ltpadmin\n1 32\na span 1 32 32 1400 10000 1 'udplso 127.0.0.1:1113' 300\n# Start listening for incoming LTP traffic - assigned to the IP internal\ns 'udplsi 127.0.0.1:1113'\n## end ltpadmin\n\n## begin bpadmin\n1\n# Use the ipn eid naming scheme\na scheme ipn 'ipnfw' 'ipnadminep'\n# Create a endpoints\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n# Define ltp as the protocol used\na protocol ltp 1400 100\n# Listen \na induct ltp 1 ltpcli\n# Send to yourself\na outduct ltp 1 ltpclo\ns\n## end bpadmin\n\n## begin ipnadmin\n# Send to yourself\na plan 1 ltp/1\n## end ipnadmin\n\n## begin ionsecadmin\n# Enable bundle security to avoid error messages in ion.log\n1\n## end ionsecadmin\nGiven to ionadmin either as a file or from the daemon command line, this file configures contacts for the ION node. We will assume that the local node's identification number is 1.
This file specifies contact times and one-way light times between nodes. This is useful in deep-space scenarios: for instance, Mars may be 20 light-minutes away, or 8. Though only some transport protocols make use of this time (currently, only LTP), it must be specified for all links nonetheless. Times may be relative (prefixed with a + from current time) or absolute. Absolute times, are in the format yyyy/mm/dd-hh:mm:ss. By default, the contact-graph routing engine will make bundle routing decisions based on the contact information provided.
The configuration file lines are as follows:
"},{"location":"community/dtn-gcp-main/ion-config/#initialize-the-ion-node-to-be-node-number-1","title":"Initialize the ion node to be node number 1","text":"1 1 ''\n1 refers to this being the initialization or first command.
1 specifies the node number of this ion node. (IPN node 1).
'' specifies the name of a file of configuration commands for the node's use of shared memory and other resources (suitable defaults are applied if you leave this argument as an empty string).
s
This will start the ION node. It mostly functions to officially \"start\" the node in a specific instant; it causes all of ION's protocol-independent background daemons to start running.
"},{"location":"community/dtn-gcp-main/ion-config/#specify-a-transmission-opportunity","title":"Specify a transmission opportunity","text":"a contact +1 +3600 1 1 100000\nspecifies a transmission opportunity for a given time duration between two connected nodes (or, in this case, a loopback transmission opportunity).
a adds this entry in the configuration table.
contact specifies that this entry defines a transmission opportunity.
+1 is the start time for the contact (relative to when the s command is issued).
+3600 is the end time for the contact (relative to when the s command is issued).
1 is the source node number.
1 is the destination node number.
100000 is the maximum rate at which data is expected to be transmitted from the source node to the destination node during this time period (here, it is 100000 bytes / second).
a range +1 +3600 1 1 1\nspecifies a distance between nodes, expressed as a number of light seconds, where each element has the following meaning:
a adds this entry in the configuration table.
range declares that what follows is a distance between two nodes.
+1 is the earliest time at which this is expected to be the distance between these two nodes (relative to the time s was issued).
+3600 is the latest time at which this is still expected to be the distance between these two nodes (relative to the time s was issued).
1 is one of the two nodes in question.
1 is the other node.
1 is the distance between the nodes, measured in light seconds, also sometimes called the \"one-way light time\" (here, one light second is the expected distance).
m production 1000000\nm specifies that this is a management command.
production declares that this command declares the maximum rate of data production at this ION node.
1000000 specifies that at most 1000000 bytes/second will be produced by this node.
m consumption 1000000\nm specifies that this is a management command.
consumption declares that this command declares the maximum rate of data consumption at this ION node.
1000000 specifies that at most 1000000 bytes/second will be consumed by this node.
host1.ionrc","text":"## begin ionadmin\n1 1 ''\ns\na contact +1 +3600 1 1 100000\na range +1 +3600 1 1 1\nm production 1000000\nm consumption 1000000\n## end ionadmin\nThe ionsecadmin section is used to enable bundle security. Adding it will also avoid error messages in ion.log.
1 enables the bundle security
ionsec.rc","text":"## begin ionsecadmin\n1\n## end ionsecadmin\nAs noted earlier, this file is used to build ION's analogue to an ARP cache, a table of egress plans. It specifies which outducts to use in order to forward bundles to the local node's neighbors in the network. Since we only have one outduct, for forwarding bundles to one place (the local node), we only have one egress plan.
a plan 1 ltp/1\na means this command adds something. plan means this command adds an egress plan. 1 is the node number of the remote node. In this case, that is the local node's own node number; we're configuring for loopback. ltp/1 is the identifier of the outduct through which to transmit bundles in order to convey them to this ''remote'' node.
host1.ipnrc","text":"## begin ipnadmin\na plan 1 ltp/1\n## end ipnadmin\nGiven to ltpadmin as a file or from the command line, this file configures the LTP engine itself. We will assume the local IPN node number is 1; in ION, node numbers are used as the LTP engine numbers.
"},{"location":"community/dtn-gcp-main/ltp-config/#initialize-the-ltp-engine","title":"Initialize the LTP engine","text":"1 32 \n1 refers to this being the initialization or ''first'' command.
32 is an estimate of the maximum total number of LTP ''block'' transmission sessions - for all spans - that will be concurrently active in this LTP engine. It is used to size a hash table for session lookups.
a span 1 32 32 1400 10000 1 'udplso localhost:1113'\na indicates that this will add something to the engine.
span indicates that an LTP span will be added.
1 is the engine number for the span, the number of the remote engine to which LTP segments will be transmitted via this span. In this case, because the span is being configured for loopback, it is the number of the local engine, i.e., the local node number.
32 specifies the maximum number of LTP ''block'' transmission sessions that may be active on this span. The product of the mean block size and the maximum number of transmission sessions is effectively the LTP flow control ''window'' for this span: if it's less than the bandwidth delay product for traffic between the local LTP engine and this spa's remote LTP engine then you'll be under-utilizing that link. We often try to size each block to be about one second's worth of transmission, so to select a good value for this parameter you can simply divide the span's bandwidth delay product (data rate times distance in light seconds) by your best guess at the mean block size.
The second 32 specifies the maximum number of LTP ''block'' reception sessions that may be active on this span. When data rates in both directions are the same, this is usually the same value as the maximum number of transmission sessions.
1400 is the number of bytes in a single segment. In this case, LTP runs atop UDP/IP on ethernet, so we account for some packet overhead and use 1400.
1000 is the LTP aggregation size limit, in bytes. LTP will aggregate multiple bundles into blocks for transmission. This value indicates that the block currently being aggregated will be transmitted as soon as its aggregate size exceeds 10000 bytes.
1 is the LTP aggregation time limit, in seconds. This value indicates that the block currently being aggregated will be transmitted 1 second after aggregation began, even if its aggregate size is still less than the aggregation size limit.
'udplso localhost:1113' is the command used to implement the link itself. The link is implemented via UDP, sending segments to the localhost Internet interface on port 1113 (the IANA default port for LTP over UDP).
s 'udplsi localhost:1113'\ns starts the ltp engine.
'udplsi localhost:1113' is the link service input task. In this case, the input ''duct' is a UDP listener on the local host using port 1113.
host1.ltprc","text":"## begin ltpadmin\n1 32\na span 1 32 32 1400 10000 1 'udplso localhost:1113'\ns 'udplsi localhost:1113'\n## end ltpadmin\nThis project has been developed by Dr Lara Suzuki, a visiting Researcher at NASA JPL.
NOTE to reader: After ION 4.1, the imc multicasting implementation has changed its configuration and no longer requires the imcadmin program for configuration. Please see ION 4.1.2 man pages for more information. This tutorial is based on earlier version of ION's imc multicasting. The proper adaptation to latest ION version is left as an exercise for the reader.
Multicasting over the Interplanetary Internet uses version 7 of the Bundle Protocol. In a multicasting scenario, we send messages to a multicasting end point and the messages are propagated across the nodes of the network, removing the need to send data to individual nodes one at a time.
Use multicasting when the messages you are sending should be delivered to all the known nodes of the network.
"},{"location":"community/dtn-multicasting-main/Multicasting-over-ION/#executing-multicasting","title":"Executing Multicasting","text":"This tutorial presents the configurations of one host. To create additional hosts, you just need to copy the same configurations and alter the configuraation documents with the appropriate data as explained in our first tutorial.
To execute multicasting:
Execute the \"execute\" file to get ion started
$ ./execute\nWhen performing multicasting, the eid naming scheme is imc 'imcfw' 'imcadminep'
Once ION is started you can run the commands to open bpsink to listen to packages sent over DTN. Simply run on your terminal the command below. This command will leave bpsink running on the background. In our configuration file host.bprc.2 we define interplanetary multicasting EID as 19.0. Messages sent to this EID will be delivered to all the hosts running the same configuration.
$ bpsink imc:19.0 &\n$ bpsendfile ipn:1.1 imc:19.0 image.jpeg\n$ bprecvfile imc:19.0 1\nIn this section I will give a little overview of the basic concepts of the Interplanetary Overlay Network from Nasa.
Digital communication between interplanetary spacecraft and space flight control centres on Earth is subject to constraints that differ in some ways from those that characterize terrestrial communications.
"},{"location":"community/dtn-multicasting-main/Multicasting-over-ION/#basic-concepts-of-interplanetary-overlay-network","title":"Basic Concepts of Interplanetary Overlay Network","text":"Delay-Disruption Tolerant Networking (DTN) is NASA\u2019s solution for reliable, automated network communications in space missions. The DTN2 reference implementation of the Delay-Tolerant Networking (DTN) RFC 4838 and the current version of the Bundle Protocol (BP) is the foundation for a wide range of current DTN industrial and research applications.
The Jet Propulsion Laboratory (JPL) has developed an alternative implementation of BP, named \u201cInterplanetary Overlay Network\u201d (ION). ION addresses those constraints and enables delay-tolerant network communications in interplanetary mission operations.
"},{"location":"community/dtn-multicasting-main/Multicasting-over-ION/#space-communication-challenges","title":"Space communication challenges","text":"To give you a sense of signal propagation -> send a message and receive a response (RRT) back: 1. A typical round trip time between two points on the internet is 100ms to 300ms 2. Distance to ISS (throught TDRS - Tracking and Data Relay Satellite) approx 71322km -> round trip time is approx 1200 ms on Ku Link 3. Distance to the moon approx 384400 km - rrt 2560 ms -2,5 seconds 4. Minimun distance to mars: approx 54.6 million km - rrt of approx 6 min 5. Average distance to mars: approx 225 million km - rrt of approx 25 mins 6. Farthest distance to mars: approx 401 million km - rtt of approc 44.6 min
The internet architecture is based on the assumption that network nodes are continuously connected. The following assumptions are valid for the terrestrial Internet architecture: - Networks have short signal propagation delays - Data links are symmetric and bidirectional - Bit error rates are low
These assumptions are not valid in the space environment - a new sort of network is needed. In a space environment: - Connections can be routinely interrupted - Interplanetary distances impose delays - Link data rates are often asymmetric and some links are simplex - Bit error rates can be very high
To communicate across these vast distances, NASA manages three communication networks consisting of distributed ground stations and space relay satellites for data transmission and reception that support both NASA and non-NASA missions. These are: - the Deep Space Network (DSN) - the Near Earth Network (NEN) - the Space Network (SN).
Communication opportunities are scheduled, based on orbit dynamics and operation plans. Sometimes a spacecraft is on the far side of a planet and you cannot communicate with it. Transmission and reception episodes are individually configured, started and ended by command. Reliability over deeps space links is by management: on loss of data, command retransmission. More recently for Mars missions we have managed forwarding through relay points so that data from these surface vehicles is relayed thought Odyssey and other orbiting mars vehicles.
"},{"location":"community/dtn-multicasting-main/Host1/execute/","title":"Execute","text":"#!/usr/bin/bash\necho \"starting ION...\"\nionadmin host.ionrc\n./ionstart\n## begin bpadmin\n1\n# Use the ipn eid naming scheme\na scheme ipn 'ipnfw' 'ipnadminep'\n# Create a endpoints\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n# Define ltp as the protocol used\na scheme imc 'imcfw' 'imcadminep'\n#a endpoint imc:19.0 q\na protocol ltp 1400 100\n# Listen\na induct ltp 1 ltpcli\n# Send to yourself\na outduct ltp 1 ltpclo\n# Send to server2\na outduct ltp 2 ltpclo\na outduct ltp 3 ltpclo\nw 1\ns\n## end bpadmin\na endpoint imc:19.0 q\n## begin ionadmin\n1 1 ''\ns\n# Define contact plan\na contact +1 +3600 1 1 100000\na contact +1 +3600 1 2 100000\na contact +1 +3600 2 1 100000\na contact +1 +3600 2 2 100000\n\n# Define 1sec OWLT between nodes\na range +1 +3600 1 1 1\na range +1 +3600 1 2 1\na range +1 +3600 2 1 1\na range +1 +3600 2 2 1\nm production 1000000\nm consumption 1000000\n## end ionadmin\n1\n## begin ipnadmin\n# Send to yourself#\na plan 1 ltp/1\n# Send to server 2\na plan 2 ltp/2\n## end ipnadmin\n1 32\n#a span peer_engine_nbr\n# [queuing_latency]\n# Create a span to tx\na span 1 32 32 1400 10000 1 'udplso external_ip_host1:1113' 300\na span 2 32 32 1400 10000 1 'udplso external_ip_host2:1113' 300\n# Start listening for incoming LTP traffic - assigned to the IP internal\ns 'udplsi internal_ip:1113'\n## end ltpadmin\n#!/bin/bash\n# shell script to get node running\n\nionsecadmin host.ionsecrc\nsleep 1\nltpadmin host.ltprc\nsleep 1\nbpadmin host.bprc.1\nsleep 1\nipnadmin host.ipnrc\nsleep 2\nbpadmin host.bprc.2\necho \"Started Host 1.\"\n#!/bin/bash\n#\n# ionstop\n# David Young\n# Aug 20, 2008\n#\n# will quickly and completely stop an ion node.\n\nION_OPEN_SOURCE=1\n\necho \"IONSTOP will now stop ion and clean up the node for you...\"\nbpversion\nif [ $? -eq 6 ]; then\necho \"acsadmin .\"\nacsadmin .\nsleep 1\nfi\necho \"bpadmin .\"\nbpadmin .\nsleep 1\nif [ \"$ION_OPEN_SOURCE\" == \"1\" ]; then\necho \"cfdpadmin .\"\ncfdpadmin .\nsleep 1\nfi\necho \"ltpadmin .\"\nltpadmin .\nsleep 1\necho \"ionadmin .\"\nionadmin .\nsleep 1\necho \"killm\"\nkillm\necho \"ION node ended. Log file: ion.log\"\nThis project has been developed by Dr Lara Suzuki, a visiting researcher at NASA JPL.
In this tutorial I will demonstrate how to connect use GCP Video Intelligence over the Interplanetary Internet.
"},{"location":"community/dtn-video-intelligence-main/Video-Intelligence/#setting-up-the-interplanetary-internet","title":"Setting up the Interplanetary Internet","text":"Please follow tutorial Multicasting over the Interplanetary Internet to set up your nodes.
As noted in the multicasting tutorial, current ION imc multicasting operation has been updated and adaptation is required to make this tutorial work.
Once the hosts are configured you can run the command to get ionstart running:
$ ./execute\nCloud Video Intelligence API allows you to process frames of videos with a simple API call from anywhere. With GCP Video Intelligence you can:
Quickly understand video content by encapsulating powerful machine learning models in an easy to use REST API.
Accurately annotate videos stored in Google Cloud Storage with video and frame-level (1 fps) contextual information.
Make sense of large amount of video files in a very short amount of time.
Utilise the technology via an easy to use REST API to analyze videos stored anywhere, or integrate with your image storage on Google Cloud Storage.
In the Interplanetary host you choose to run the excecution of the Video Intelligence API, install the library:
$ pip install --upgrade google-cloud-videointelligence\nTo use the Video Intelligence API you must be Authenticated. To do that, please follow the instructions in this GCP Tutorial. After you've created your service account, Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS.
$ export GOOGLE_APPLICATION_CREDENTIALS=\"/home/user/Downloads/my-key.json\"\nOn the host that will run the Video Intelligence, execute:
python\npython3 video_processing.py\nimport argparse\nfrom google.cloud import videointelligence\n\nvideo_client = videointelligence.VideoIntelligenceServiceClient()\nfeatures = [videointelligence.Feature.LABEL_DETECTION]\noperation = video_client.annotate_video(\nrequest={\"features\": features, \"input_uri\":'gs://test_bucket_pi/video1_pi.mp4'})\nprint(\"Processing video for label annotations:\")\n\nresult = operation.result(timeout=90)\nprint(\"\\nFinished processing.\")\n\nsegment_labels = result.annotation_results[0].segment_label_annotations\nfor i, segment_label in enumerate(segment_labels):\n print(\"Video label description: {}\".format(segment_label.entity.description))\n for category_entity in segment_label.category_entities:\n print( \"\\tLabel category description: {}\".format(category_entity.description)\n )\n\n for i, segment in enumerate(segment_label.segments):\n start_time = (\n segment.segment.start_time_offset.seconds\n + segment.segment.start_time_offset.microseconds / 1e6\n )\n end_time = (\n segment.segment.end_time_offset.seconds\n + segment.segment.end_time_offset.microseconds / 1e6\n )\n positions = \"{}s to {}s\".format(start_time, end_time)\n confidence = segment.confidence\n print(\"\\tSegment {}: {}\".format(i, positions))\n print(\"\\tConfidence: {}\".format(confidence))\n print(\"\\n\")\nams - CCSDS Asynchronous Message Service(AMS) communications library
"},{"location":"man/ams/ams/#synopsis","title":"SYNOPSIS","text":"#include \"ams.h\"\n\ntypedef void (*AmsMsgHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int continuumNbr,\n int unitNbr,\n int moduleNbr,\n int subjectNbr,\n int contentLength,\n char *content,\n int context,\n AmsMsgType msgType,\n int priority,\n unsigned char flowLabel);\n\ntypedef void (*AmsRegistrationHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int roleNbr);\n\ntypedef void (*AmsUnregistrationHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr);\n\ntypedef void (*AmsInvitationHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int domainRoleNbr,\n int domainContinuumNbr,\n int domainUnitNbr,\n int subjectNbr,\n int priority,\n unsigned char flowLabel,\n AmsSequence sequence,\n AmsDiligence diligence);\n\ntypedef void (*AmsDisinvitationHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int domainRoleNbr,\n int domainContinuumNbr,\n int domainUnitNbr,\n int subjectNbr);\n\ntypedef void (*AmsSubscriptionHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int domainRoleNbr,\n int domainContinuumNbr,\n int domainUnitNbr,\n int subjectNbr,\n int priority,\n unsigned char flowLabel,\n AmsSequence sequence,\n AmsDiligence diligence);\n\ntypedef void (*AmsUnsubscriptionHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int domainRoleNbr,\n int domainContinuumNbr,\n int domainUnitNbr,\n int subjectNbr);\n\ntypedef void (*AmsUserEventHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int code,\n int dataLength,\n char *data);\n\ntypedef void (*AmsMgtErrHandler)(void *userData,\n AmsEvent *eventRef);\n\ntypedef struct\n{\n AmsMsgHandler msgHandler;\n void *msgHandlerUserData;\n AmsRegistrationHandler registrationHandler;\n void *registrationHandlerUserData;\n AmsUnregistrationHandler unregistrationHandler;\n void *unregistrationHandlerUserData;\n AmsInvitationHandler invitationHandler;\n void *invitationHandlerUserData;\n AmsDisinvitationHandler disinvitationHandler;\n void *disinvitationHandlerUserData;\n AmsSubscriptionHandler subscriptionHandler;\n void *subscriptionHandlerUserData;\n AmsUnsubscriptionHandler unsubscriptionHandler;\n void *unsubscriptionHandlerUserData;\n AmsUserEventHandler userEventHandler;\n void *userEventHandlerUserData;\n AmsMgtErrHandler errHandler;\n void *errHandlerUserData;\n} AmsEventMgt;\n\ntypedef enum\n{\n AmsArrivalOrder = 0,\n AmsTransmissionOrder\n} AmsSequence;\n\ntypedef enum\n{\n AmsBestEffort = 0,\n AmsAssured\n} AmsDiligence;\n\ntypedef enum\n{\n AmsRegistrationState,\n AmsInvitationState,\n AmsSubscriptionState\n} AmsStateType;\n\ntypedef enum\n{\n AmsStateBegins = 1,\n AmsStateEnds\n} AmsChangeType;\n\ntypedef enum\n{\n AmsMsgUnary = 0,\n AmsMsgQuery,\n AmsMsgReply,\n AmsMsgNone\n} AmsMsgType;\n\n[see description for available functions]\nThe ams library provides functions enabling application software to use AMS to send and receive brief messages, up to 65000 bytes in length. It conforms to AMS Blue Book, including support for Remote AMS (RAMS).
In the ION implementation of RAMS, the \"RAMS network protocol\" may be either the DTN Bundle Protocol (RFC 5050) or -- mainly for testing purposes -- the User Datagram Protocol (RFC 768). BP is the default. When BP is used as the RAMS network protocol, endpoints are by default assumed to conform to the \"ipn\" endpoint identifier scheme with node number set to the AMS continuum number and service number set to the AMS venture number.
Note that RAMS functionality is enabled by instantiating a ramsgate daemon, which is simply an AMS application program that acts as a gateway between the local AMS message space and the RAMS network.
AMS differs from other ION packages in that there is no utilization of non-volatile storage (aside from the BP functionality in RAMS, if applicable). Since there is no non-volatile AMS database, there is no AMS administration program and there are no library functions for attaching to or detaching from such a database. AMS is instantiated by commencing operation of the AMS real-time daemon amsd; once amsd is running, AMS application programs (\"modules\") can be started. All management of AMS operational state is performed automatically in real time.
However, amsd and the AMS application programs all require access to a common store of configuration data at startup in order to load their Management Information Bases. This configuration data must reside in a readable file, which may take either of two forms: a file of XML statements conforming to the scheme described in the amsxml(5) man page, or a file of simple but less powerful configuration statements as described in the amsrc(5) man page. The amsxml alternative requires that the expat XML parsing system be installed; the amsrc alternative was developed to simplify deployment of AMS in environments in which expat is not readily supported. Selection of the configuration file format is a compile-time decision, implemented by setting (or not setting) the -DNOEXPAT compiler option.
The path name of the applicable configuration file may be passed as a command-line parameter to amsd and as a registration function parameter by any AMS application program. Note, though, that ramsgate and the AMS test and utility programs included in ION always assume that the configuration file resides in the current working directory and that it is named \"mib.amsrc\" if AMS was built with -DNOEXPAT, \"amsmib.xml\" otherwise.
The transport services that are made available to AMS communicating entities are declared by the transportServiceLoaders array in the libams.c source file. This array is fixed at compile time. The order of preference of the transport services in the array is hard-coded, but the inclusion or omission of individual transport services is controlled by setting compiler options. The \"udp\" transport service -- nominally the most preferred because it imposes the least processing and transmission overhead -- is included by setting the -DUDPTS option. The \"dgr\" service is included by setting the -DDGRTS option. The \"vmq\" (VxWorks message queue) service, supported only on VxWorks, is included by setting the -DVMQTS option. The \"tcp\" transport service -- selected only when its quality of service is required -- is included by setting the -DTCPTS option.
The operating state of any single AMS application program is managed in an opaque AmsModule object. This object is returned when the application begins AMS operations (that is, registers) and must be provided as an argument to most AMS functions.
int ams_register(char *mibSource, char *tsorder, char *applicationName, char *authorityName, char *unitName, char *roleName, AmsModule *module)
Registers the application within a cell (identified by unitName) of a message space that is that portion of the venture identified by applicationName and authorityName that runs within the local AMS continuum. roleName identifies the role that this application will perform in this venture. The operating state of the registered application is returned in module.
The application module's identifying parameters are validated against the configuration information in the applicable Management Information Base, which is automatically loaded from the file whose pathname is provided in mibSource. If mibSource is the zero-length string (\"\") then the default configuration file name is used as noted above. If mibSource is NULL then a rudimentary hard-coded default MIB, useful for basic testing purposes, is loaded. This default MIB defines a single venture for application \"amsdemo\" and authority \"test\", using only the \"dgr\" transport service, with the configuration server residing on the local host machine; subject \"text\" and roles \"shell\", \"log\", \"pitch\", and \"catch\" are defined.
The tsorder argument is normally NULL. If non-NULL it must be a NULL-terminated string of ASCII numeric digits '0' through '9' identifying an alternative transport service preference order that overrides the standard transport service preference order defined by the hard-coded array of transportServiceLoaders in the libams.c source file. Each character of the tsorder string must represent the index position of one of the transport services within the array. For example, if services \"udp\", \"dgr\", \"vmq\", and \"tcp\" are all available in the array, a tsorder string of \"32\" would indicate that this application will only communicate using the tcp and vmq services; services 0 (udp) and 1 (dgr) will not be used, and tcp is preferred to vmq when both are candidate services for transmission of a given message.
Returns 0 on success. On any error, sets module to NULL and returns -1.
int ams_unregister(AmsModule module)
Reverses the operation of ams_unregister(), destroying module. Returns 0 on success, -1 on any error.
int ams_invite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)
Announces this module's agreement to receive messages on the subject identified by subjectNbr.
The invitation is extended only to modules registered in the role identified by roleNbr (where 0 indicates \"all roles\"), operating in the continuum identifed by continuumNbr (where 0 indicates \"all continua\"), and registered within the unit identified by unitNbr (where 0 indicates the venture's root unit) or any of that unit's subunits. These parameters define the \"domain\" of the invitation.
Such messages should be sent at the priority indicated by priority with flow label as indicated by flowLabel and with quality of service as indicated by sequence and diligence. priority must be an integer in the range 1-15, where priority 1 indicates the greatest urgency. Flow labels are passed through to transport services and are opaque to AMS itself; in the absence of defined flow labels, a value of 0 is typically used. These parameters define the \"class of service\" of the invitation.
Returns 0 on success, -1 on any error.
int ams_disinvite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)
Rescinds the invitation characterized by the indicated subject and domain. Returns 0 on success, -1 on any error.
int ams_subscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)
Announces this module's subscription to messages on the indicated subject, constrained by the indicated domain, and transmitted subject to the indicated class of service. Note that subscriptions differ from invitations in that reception of these messages is actively solicited, not just permitted.
Returns 0 on success, -1 on any error.
int ams_unsubscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)
Cancels the subscription characterized by the indicated subject and domain. Returns 0 on success, -1 on any error.
int ams_publish(AmsModule module, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)
Publishes contentLength bytes of data starting at content as the content of a message that is sent to all modules whose subscriptions to subjectNbr are characterized by a domain that includes this module. priority and flowLabel, if non-zero, override class of service as requested in the subscriptions. context is an opaque \"hint\" to the receiving modules; its use is application-specific.
Returns 0 on success, -1 on any error.
int ams_send(AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)
Sends contentLength bytes of data starting at content as the content of a message that is transmitted privately to the module in the continuum identified by continuumNbr (where 0 indicates \"the local continuum\") that is identified by unitNbr and moduleNbr -- provided that module is in the domain of one of that module's invitations on subjectNbr. priority and flowLabel, if non-zero, override class of service as requested in the invitation. context is an opaque \"hint\" to the receiving module; its use is application-specific.
Returns 0 on success, -1 on any error.
int ams_query(AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context, int term, AmsEvent *event)
Sends a message exactly is described above for ams_send(), but additionally suspends the delivery and processing of newly received messages until either (a) a \"reply\" message sent in response to this message is received or (b) the time interval indicated by term, in seconds, expires. The event (reply or timeout) that ends the suspension of processing is provided in event (as if from ams_get_event() when the function returns.
If term is AMS_BLOCKING then the timeout interval is indefinite; only reception of a reply message enables the function to return. If term is AMS_POLL then the function returns immediately, without waiting for a reply message.
Returns 0 on success, -1 on any error.
int ams_reply(AmsModule module, AmsEvent msg, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content)
Sends a message exactly is described above for ams_send(), except that the destination of the message is the sender of the message identified by msg and the \"context\" value included in the message is the context that was provided in msg. This message is identified as a \"reply\" message that will end the processing suspension resulting from transmission of msg if that message was issued by means of ams_query() rather than ams_send().
Returns 0 on success, -1 on any error.
int ams_announce(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)
Sends a message exactly is described above for ams_send(), except that one copy of the message is sent to every module in the domain of this function (role, continuum, unit) whose invitation for messages on this subject is itself characterized by a domain that includes the the sending module, rather than to any specific module.
Returns 0 on success, -1 on any error.
int ams_get_event(AmsModule module, int term, AmsEvent *event)
Returns in event the next event in the queue of AMS events pending delivery to this module. If the event queue is empty at the time this function is called, processing is suspended until either an event is queued or the time interval indicated by term, in seconds, expires. See ams_query() above for the semantics of term. When the function returns on expiration of term, an event of type TIMEOUT_EVT is returned in event. Otherwise the event will be of type AMS_MSG_EVT (indicating arrival of a message), NOTICE_EVT (indicating a change in the configuration of the message space), or USER_DEFINED_EVT (indicating that application code posted an event).
The nature of the event returned by ams_get_event() can be determined by passing event to ams_get_event_type() as described below. Event type can then be used to determine whether the information content of the event must be obtained by calling ams_parse_msg(), ams_parse_notice(), or ams_parse_user_event().
In any case, the memory occupied by event must be released after the event object is no longer needed. The ams_recycle_event() function is invoked for this purpose.
Returns 0 on success, -1 on any error.
int ams_get_event_type(AmsEvent event)
Returns the event type of event, or -1 on any error.
int ams_parse_msg(AmsEvent event, int *continuumNbr, int *unitNbr, int *moduleNbr, int *subjectNbr, int *contentLength, char **content, int *context, AmsMsgType *msgType, int *priority, unsigned char *flowLabel);
Extracts all relevant information pertaining to the AMS message encapsulated in event, populating the indicated fields. Must only be called when the event type of event is known to be AMS_MSG_EVT.
Returns 0 on success, -1 on any error.
int ams_parse_notice(AmsEvent event, AmsStateType *state, AmsChangeType *change, int *unitNbr, int *moduleNbr, int *roleNbr, int *domainContinuumNbr, int *domainUnitNbr, int *subjectNbr, int *priority, unsigned char *flowLabel, AmsSequence *sequence, AmsDiligence *diligence)
Extracts all relevant information pertaining to the AMS configuration change notice encapsulated in event, populating the relevant fields. Must only be called when the event type of event is known to be NOTICE_EVT.
Note that different fields will be populated depending on the nature of the notice in event. state will be set to AmsRegistrationState, AmsInvitationState, or AmsSubscription state depending on whether the notice pertains to a change in module registration, a change in invitations, or a change in subscriptions. change will be set to AmsStateBegins or AmsStateEnds depending on whether the notice pertains to the initiation or termination of a registration, invitation, or subscription.
Returns 0 on success, -1 on any error.
int ams_post_user_event(AmsModule module, int userEventCode, int userEventDataLength, char *userEventData, int priority)
Posts a \"user event\" whose content is the userEventDataLength bytes of data starting at userEventData. userEventCode is an application-specific value that is opaque to AMS. priority determines the event's position in the queue of events pending delivery to this module; it may be any integer in the range 0-15, where 0 indicates the greatest urgency. (Note that user events can be delivered ahead of all message reception events if necessary.)
Returns 0 on success, -1 on any error.
int ams_parse_user_event(AmsEvent event, int *code, int *dataLength, char **data)
Extracts all relevant information pertaining to the user event encapsulated in event, populating the indicated fields. Must only be called when the event type of event is known to be USER_DEFINED_EVT.
Returns 0 on success, -1 on any error.
int ams_recycle_event(AmsEvent event)
Releases all memory occupied by event. Returns 0 on success, -1 on any error.
int ams_set_event_mgr(AmsModule module, AmsEventMgt *rules)
Starts a background thread that processes events queued for this module, handling each event in the manner indicated by rules. Returns 0 on success, -1 on any error.
void ams_remove_event_mgr(AmsModule module)
Terminates the background thread established to process events queued for this module. Returns 0 on success, -1 on any error.
int ams_get_module_nbr(AmsModule module)
Returns the module number assigned to this module upon registration, or -1 on any error.
int ams_get_unit_nbr(AmsModule module)
Returns the unit number assigned to the unit within which this module registered, or -1 on any error.
Lyst ams_list_msgspaces(AmsModule module)
Returns a dynamically allocated linked list of all message spaces identified in the MIB for this module, or -1 on any error. See lyst(3) for operations that can be performed on the returned linked list.
int ams_get_continuum_nbr()
Returns the continuum number assigned to the continuum within which this module operates, or -1 on any error.
int ams_rams_net_is_tree(AmsModule module)
Returns 1 if the RAMS net for the venture in which this module is registered is configured as a tree, 0 if that RAMS net is configured as a mesh, -1 on any error.
int ams_continuum_is_neighbor(int continuumNbr)
Returns 1 if continuumNbr identifies a continuum whose RAMS gateways are immediate neighbors (within the applicable RAMS networks) of the RAMS gateways in the local continuum. Returns 0 otherwise.
char *ams_get_role_name(AmsModule module, int unitNbr, int moduleNbr)
Returns the name of the role in which the module identified by unitNbr and moduleNbr registered, or NULL on any error.
int ams_subunit_of(AmsModule module, int argUnitNbr, int refUnitNbr)
Returns 1 if argUnitNbr identifies a unit that is wholly contained within the unit identified by refUnitNbr, in the venture within which this module is registered. Returns 0 otherwise.
int ams_lookup_unit_nbr(AmsModule module, char *unitName)
Returns the number assigned to the unit identified by unitName, in the venture within which this module is registered, or -1 on any error.
int ams_lookup_role_nbr(AmsModule module, char *roleName)
Returns the number assigned to the role identified by roleName, in the venture within which this module is registered, or -1 on any error.
int ams_lookup_subject_nbr(AmsModule module, char *subjectName)
Returns the number assigned to the subject identified by subjectName, in the venture within which this module is registered, or -1 on any error.
int ams_lookup_continuum_nbr(AmsModule module, char *continuumName)
Returns the number of the continuum identified by continuumName, or -1 on any error.
char *ams_lookup_unit_name(AmsModule module, int unitNbr)
Returns the name of the unit identified by unitNbr, in the venture within which this module is registered, or -1 on any error.
char *ams_lookup_role_name(AmsModule module, int roleNbr)
Returns the name of the role identified by roleNbr, in the venture within which this module is registered, or -1 on any error.
char *ams_lookup_subject_name(AmsModule module, int subjectNbr)
Returns the name of the subject identified by subjectNbr, in the venture within which this module is registered, or -1 on any error.
char *ams_lookup_continuum_name(AmsModule module, int continuumNbr)
Returns the name of the continuum identified by continuumNbr, or -1 on any error.
amsd(1), ramsgate(1), amsxml(5), amsrc(5)
"},{"location":"man/ams/amsbenchr/","title":"NAME","text":"amsbenchr - Asynchronous Message Service (AMS) benchmarking meter
"},{"location":"man/ams/amsbenchr/#synopsis","title":"SYNOPSIS","text":"amsbenchr
"},{"location":"man/ams/amsbenchr/#description","title":"DESCRIPTION","text":"amsbenchr is a test program that simply subscribes to subject \"bench\" and receives messages published by amsbenchs until all messages in the test - as indicated by the count of remaining messages, in in the first four bytes of each message - have been received. Then it stops receiving messages, calculates and prints performance statistics, and terminates.
amsbenchr will register as an application module in the root unit of the venture identified by application name \"amsdemo\" and authority name \"test\". A configuration server for the local continuum and a registrar for the root unit of that venture (which may both be instantiated in a single amsd daemon task) must be running in order for amsbenchr to commence operations.
"},{"location":"man/ams/amsbenchr/#exit-status","title":"EXIT STATUS","text":"-1
amsbenchr failed, for reasons noted in the ion.log file.
\"0\"
amsbenchr terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amsbenchr/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsbenchr/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
amsbenchr can't register.
amsbenchr failed to register, for reasons noted in the ion.log file.
amsbenchr: subject 'bench' is unknown.
amsbenchr can't subscribe to test messages; probably an error in the MIB initialization file.
amsbenchr can't subscribe.
amsbenchr failed to subscribe, for reasons noted in the ion.log file.
amsbenchr can't get event.
amsbenchr failed to receive a message, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsbenchr/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amsbenchs/","title":"NAME","text":"amsbenchs - Asynchronous Message Service (AMS) benchmarking driver
"},{"location":"man/ams/amsbenchs/#synopsis","title":"SYNOPSIS","text":"amsbenchs count size
"},{"location":"man/ams/amsbenchs/#description","title":"DESCRIPTION","text":"amsbenchs is a test program that simply publishes count messages of size bytes each on subject \"bench\", then waits while all published messages are transmitted, terminating when the user uses ^C to interrupt the program. The remaining number of messages to be published in the test is written into the first four octets of each message.
amsbenchs will register as an application module in the root unit of the venture identified by application name \"amsdemo\" and authority name \"test\". A configuration server for the local continuum and a registrar for the root unit of that venture (which may both be instantiated in a single amsd daemon task) must be running in order for amsbenchs to commence operations.
"},{"location":"man/ams/amsbenchs/#exit-status","title":"EXIT STATUS","text":"-1
amsbenchs failed, for reasons noted in the ion.log file.
\"0\"
amsbenchs terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amsbenchs/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsbenchs/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
No memory for amsbenchs.
Insufficient available memory for a message content buffer of the indicated size.
amsbenchs can't register.
amsbenchs failed to register, for reasons noted in the ion.log file.
amsbenchs can't set event manager.
amsbenchs failed to start its background event management thread, for reasons noted in the ion.log file.
amsbenchs: subject 'bench' is unknown.
amsbenchs can't publish test messages; probably an error in the MIB initialization file.
amsbenchs can't publish message.
amsbenchs failed to publish, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsbenchs/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amsd/","title":"NAME","text":"amsd - AMS configuration server and/or registrar daemon
"},{"location":"man/ams/amsd/#synopsis","title":"SYNOPSIS","text":"amsd { @ | MIB_source_name } { . | @ | config_server_endpoint_spec } [application_name authority_name registrar_unit_name]
"},{"location":"man/ams/amsd/#description","title":"DESCRIPTION","text":"amsd is a background \"daemon\" task that functions as an AMS \"configuration server\" in the local continuum, as an AMS \"registrar\" in a specified cell, or both.
If MIB_source_name is specified, it must name a MIB initialization file in the correct format for amsd, either amsrc(5) or amsxml(5), depending on whether or not -DNOEXPAT was set at compile time. Otherwise @ is required; in this case, the built-in default MIB is loaded.
If this amsd task is NOT to run as a configuration server then the second command-line argument must be a '.' character. Otherwise the second command-line argument must be either '@' or config_server_endpoint_spec. If '@' then the endpoint specification for this configuration server is automatically computed as the default endpoint specification for the primary transport service as noted in the MIB: \"hostname:2357\".
If an AMS module is NOT to be run in a background thread for this daemon (enabling shutdown by amsstop(1) and/or runtime MIB update by amsmib(1)), then either the last three command-line arguments must be omitted or else the \"amsd\" role must not be defined in the MIB loaded for this daemon. Otherwise the application_name and authority_name arguments are required and the \"amsd\" role must be defined in the MIB.
If this amsd task is NOT to run as a registrar then the last command-line argument must be omitted. Otherwise the last three command-line arguments are required and they must identify a unit in an AMS venture for the indicated application and authority that is known to operate in the local continuum, as noted in the MIB. Note that the unit name for the \"root unit\" of a venture is the zero-length string \"\".
"},{"location":"man/ams/amsd/#exit-status","title":"EXIT STATUS","text":"\"0\"
amsd terminated without error.
-1
amsd terminated due to an anomaly as noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and restart amsd.
If MIB source name is specified, then a file of this name must be present. Otherwise a MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amsd/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsd/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
amsd can't load MIB.
MIB initialization file was missing, unreadable, or invalid.
amsd can't start CS.
Configuration server initialization failed for reasons noted in ion.log file.
amsd can't start RS.
Registrar initialization failed for reasons noted in ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsd/#see-also","title":"SEE ALSO","text":"amsmib(1), amsstop(1), amsrc(5), amsxml(5)
"},{"location":"man/ams/amshello/","title":"NAME","text":"amshello - Asynchronous Message Service (AMS) demo program for UNIX
"},{"location":"man/ams/amshello/#synopsis","title":"SYNOPSIS","text":"amshello
"},{"location":"man/ams/amshello/#description","title":"DESCRIPTION","text":"amshello is a sample program designed to demonstrate that an entire (very simple) distributed AMS application can be written in just a few lines of C code. When started, amshello forks a second process and initiates transmission of a \"Hello\" text message from one process to the other, after which both processes unregister and terminate.
The amshello processes will register as application modules in the root unit of the venture identified by application name \"amsdemo\" and authority name \"test\". A configuration server for the local continuum and a registrar for the root unit of that venture (which may both be instantiated in a single amsd daemon task) must be running in order for the amshello processes to run.
"},{"location":"man/ams/amshello/#exit-status","title":"EXIT STATUS","text":"\"0\"
amshello terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amshello/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amshello/#diagnostics","title":"DIAGNOSTICS","text":"No diagnostics apply.
"},{"location":"man/ams/amshello/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amshello/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amslog/","title":"NAME","text":"amslog - Asynchronous Message Service (AMS) test message receiver
"},{"location":"man/ams/amslog/#synopsis","title":"SYNOPSIS","text":"amslog unit_name role_name application_name authority_name [{ s | i }]
"},{"location":"man/ams/amslog/#description","title":"DESCRIPTION","text":"amslog is a message reception program designed to test AMS functionality.
When amslog is started, it registers as an application module in the unit identified by unit_name of the venture identified by application_name and authority_name; the role in which it registers must be indicated in role_name. A configuration server for the local continuum and a registrar for the indicated unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for amslog to run.
amslog runs as two threads: a background thread that receives AMS messages and logs them to standard output, together with a foreground thread that acquires operating parameters in lines of console input to control the flow of messages to the background thread.
When the first character of a line of input from stdin to the amslog foreground thread is '.' (period), amslog immediately terminates. Otherwise, the first character of each line of input from stdin must be either '+' indicating assertion of interest in a message subject or '-' indicating cessation of interest in a subject. In each case, the name of the subject in question must begin in the second character of the input line. Note that \"everything\" is a valid subject name.
By default, amslog runs in \"subscribe\" mode: when interest in a message subject is asserted, amslog subscribes to that subject; when interest in a message subject is rescinded, amslog unsubscribes to that subject. This behavior can be overridden by providing a third command-line argument to amslog - a \"mode\" indicator. When mode is 'i', amslog runs in \"invite\" mode. In \"invite\" mode, when interest in a message subject is asserted, amslog invites messages on that subject; when interest in a message subject is rescinded, amslog cancels its invitation for messages on that subject.
The \"domain\" of a subscription or invitation can optionally be specified immediately after the subject name, on the same line of console input:
Domain continuum name may be specified, or the place-holder domain continuum name \"_\" may be specified to indicate \"all continua\".
If domain continuum name (\"_\" or otherwise) is specified, then domain unit name may be specified or the place-holder domain unit name \"_\" may be specified to indicate \"the root unit\" (i.e., the entire venture).
If domain unit name (\"_\" or otherwise) is specified, then domain role name may be specified.
When amslog runs in VxWorks or RTEMS, the subject and content of each message are simply written to standard output in a text line for display on the console. When amslog runs in a UNIX environment, the subject name length (a binary integer), subject name (ASCII text), content length (a binary integer), and content (ASCII text) are written to standard output for redirection either to a file or to a pipe to amslogprt.
Whenever a received message is flagged as a Query, amslog returns a reply message whose content is the string \"Got \" followed by the first 128 bytes of the content of the Query message, enclosed in single quote marks and followed by a period.
"},{"location":"man/ams/amslog/#exit-status","title":"EXIT STATUS","text":"-1
amslog terminated with an error as noted in the ion.log file.
\"0\"
amslog terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amslog/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amslog/#diagnostics","title":"DIAGNOSTICS","text":"amslog can't register.
amslog failed to register, for reasons noted in the ion.log file.
amslog can't set event manager.
amslog failed to start its background thread, for reasons noted in the ion.log file.
amslog can't read from stdin
amslog foreground thread failed to read console input, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amslog/#see-also","title":"SEE ALSO","text":"amsshell(1), amslogprt(1), amsrc(5)
"},{"location":"man/ams/amslogprt/","title":"NAME","text":"amslogprt - UNIX utility program for printing AMS log messages from amslog
"},{"location":"man/ams/amslogprt/#synopsis","title":"SYNOPSIS","text":"amslogprt
"},{"location":"man/ams/amslogprt/#description","title":"DESCRIPTION","text":"amslogprt simply reads AMS activity log messages from standard input (nominally written by amslog and prints them. When the content of a logged message is judged not to be an ASCII text string, the content is printed in hexadecimal.
amslogprt terminates at the end of input.
"},{"location":"man/ams/amslogprt/#exit-status","title":"EXIT STATUS","text":"\"0\"
amslogprt terminated normally.
No files are needed by amslogprt.
"},{"location":"man/ams/amslogprt/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amslogprt/#diagnostics","title":"DIAGNOSTICS","text":"None.
"},{"location":"man/ams/amslogprt/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amslogprt/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amsmib/","title":"NAME","text":"amsmib - Asynchronous Message Service (AMS) MIB update utility
"},{"location":"man/ams/amsmib/#synopsis","title":"SYNOPSIS","text":"amsmib application_name authority_name role_name continuum_name unit_name file_name
"},{"location":"man/ams/amsmib/#description","title":"DESCRIPTION","text":"amsmib is a utility program that announces relatively brief Management Information Base (MIB) updates to a select population of AMS modules. Because amsd processes may run AAMS modules in background threads, and because a single MIB is shared in common among all threads of any process, amsmib may update the MIBs used by registrars and/or configuration servers as well.
MIB updates can only be propagated to modules for which the subject \"amsmib\" was defined in the MIB initialization files cited at module registration time. All ION AMS modules implicitly invite messages on subject \"amsmib\" (from all modules registered in role \"amsmib\" in all continua of the same venture) at registration time if subject \"amsmib\" and role \"amsmib\" are defined in the MIB.
amsmib registers in the root cell of the message space identified by application_name and authority_name, within the local continuum. It registers in the role \"amsmib\"; if this role is not defined in the (initial) MIB loaded by amsmib at registration time, then registration fails and amsmib terminates.
amsmib then reads into a memory buffer up to 4095 bytes of MIB update text from the file identified by file_name. The MIB update text must conform to amsxml(5) or amsrc(5) syntax, depending on whether or not the intended recipient modules were compiled with the -DNOEXPAT option.
amsmib then \"announces\" (see ams_announce() in ams(3)) the contents of the memory buffer to all modules of this same venture (identified by application_name and authority_name) that registered in the indicated role, in the indicated unit of the indicated continuum. If continuum_name is \"\" then the message will be sent to modules in all continua. If role_name is \"\" then all modules will be eligible to receive the message, regardless of the role in which they registered. If unit_name is \"\" (the root unit) then all modules will be eligible to receive the message, regardless of the unit in which they registered.
Upon reception of the announced message, each destination module will apply all of the MIB updates in the content of the message, in exactly the same way that its original MIB was loaded from the MIB initialization file when the module started running.
If multiple modules are running in the same memory space (e.g., in different threads of the same process, or in different tasks on the same VxWorks target) then the updates will be applied multiple times, because all modules in the same memory space share a single MIB. MIB updates are idempotent, so this is harmless (though some diagnostics may be printed).
Moreover, an amsd daemon will have a relevant \"MIB update\" module running in a background thread if application_name and authority_name were cited on the command line that started the daemon (provided the role \"amsd\" was defined in the initial MIB loaded at the time amsd began running). The MIB exposed to the configuration server and/or registrar running in that daemon will likewise be updated upon reception of the announced message.
The name of the subject of the announced mib update message is \"amsmib\"; if this subject is not defined in the (initial) MIB loaded by amsmib then the message cannot be announced. Nor can any potential recipient module receive the message if subject \"amsmib\" is not defined in that module's MIB.
"},{"location":"man/ams/amsmib/#exit-status","title":"EXIT STATUS","text":"\"0\"
amsmib terminated normally.
\"1\"
An anomalous exit status, indicating that amsmib failed to register.
A MIB initialization file with the applicable default name (see amsrc(5) and amsxml(5)) must be present.
"},{"location":"man/ams/amsmib/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsmib/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
amsmib subject undefined.
The amsmib utility was unable to announce the MIB update message.
amsmib domain role unknown.
The amsmib utility was unable to announce the MIB update message.
amsmib domain continuum unknown.
The amsmib utility was unable to announce the MIB update message.
amsmib domain unit unknown.
The amsmib utility was unable to announce the MIB update message.
amsmib can't open MIB file.
The amsmib utility was unable to construct the MIB update message.
MIB file length > 4096.
The MIB update text file was too long to fit into the amsmib message buffer.
Can't seek to end of MIB file.
I/O error in processing the MIB update text file.
Can't read MIB file.
I/O error in processing the MIB update text file.
amsmib can't announce 'amsmib' message.
The amsmib utility was unable to announce the MIB update message, for reasons noted in the log file.
amsmib can't register.
The amsmib utility failed to register, for reasons noted in the log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsmib/#see-also","title":"SEE ALSO","text":"amsd(1), ams(3), amsrc(5), amsxml(5)
"},{"location":"man/ams/amspub/","title":"NAME","text":"amspub - Asynchronous Message Service (AMS) test driver for VxWorks
"},{"location":"man/ams/amspub/#synopsis","title":"SYNOPSIS","text":"amspub \"application_name\", \"authority_name\", \"subject_name\", \"message_text\"
"},{"location":"man/ams/amspub/#description","title":"DESCRIPTION","text":"amspub is a message publication program designed to test AMS functionality in a VxWorks environment. When an amspub task is started, it registers as an application module in the root unit of the venture identified by application_name and authority_name, looks up the subject number for subject_name, publishes a single message with content message_text on that subject, unregisters, and terminates.
A configuration server for the local continuum and a registrar for the root unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for amspub to run.
"},{"location":"man/ams/amspub/#exit-status","title":"EXIT STATUS","text":"-1
amspub terminated with an error as noted in the ion.log file.
\"0\"
amspub terminated normally.
The amspub source code is in the amspubsub.c source file.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amspub/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amspub/#diagnostics","title":"DIAGNOSTICS","text":"amspub can't register.
amspub failed to register, for reasons noted in the ion.log file.
amspub: subject is unknown
amspub can't publish test messages on the specified subject; possibly an error in the MIB initialization file.
amspub can't publish message.
amspub failed to publish, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amspub/#see-also","title":"SEE ALSO","text":"amssub(1), amsrc(5)
"},{"location":"man/ams/amsrc/","title":"NAME","text":"amsrc - CCSDS Asynchronous Message Service MIB initialization file
"},{"location":"man/ams/amsrc/#description","title":"DESCRIPTION","text":"The Management Information Base (MIB) for an AMS communicating entity (either amsd or an AMS application module) must contain enough information to enable the entity to initiate participation in AMS message exchange, such as the network location of the configuration server and the roles and message subjects defined for some venture.
AMS entities automatically load their MIBs from initialization files at startup. When AMS is built with the -DNOEXPAT compiler option set, the MIB initialization file must conform to the amsrc syntax described below; otherwise the expat XML parsing library must be linked into the AMS executable and the MIB initialization file must conform to the amsxml syntax described in amsxml(5).
The MIB initialization file lists elements of MIB update information, each of which may have one or more attributes. An element may also have sub-elements that are listed within the declaration of the parent element, and so on.
The declaration of an element may occupy a single line of text in the MIB initialization file or may extend across multiple lines. A single-line element declaration is indicated by a '*' in the first character of the line. The beginning of a multi-line element declaration is indicated by a '+' in the first character of the line, while the end of that declaration is indicated by a '-' in the first character of the line. In every case, the type of element must be indicated by an element-type name beginning in the second character of the line and terminated by whitespace. Every start-of-element line must be matched by a subsequent end-of-element line that precedes the start of any other element that is not a nested sub-element of this element.
Attributes are represented by whitespace-terminated <name>=<value> expressions immediately following the element-type name on a '*' or '+' line. An attribute value that contains whitespace must be enclosed within a pair of single-quote (') characters.
Two types of elements are recognized in the MIB initialization file: control elements and configuration elements. A control element establishes the update context within which the configuration elements nested within it are processed, while a configuration element declares values for one or more items of AMS configuration information in the MIB.
Note that an aggregate configuration element (i.e., one which may contain other interior configuration elements; venture, for example) may be presented outside of any control element, simply to establish the context in which subsequent control elements are to be interpreted.
"},{"location":"man/ams/amsrc/#control-elements","title":"CONTROL ELEMENTS","text":"ams_mib_init
Initializes an empty MIB. This element must be declared prior to the declaration of any other element.
Sub-elements: none
Attributes:
continuum_nbr
Identifies the local continuum.
ptsname
Identifies the primary transport service for the continuum. Valid values include \"dgr\" and \"udp\".
pubkey
This is the name of the public key used for validating the digital signatures of meta-AMS messages received from the configuration server for this continuum. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
privkey
This is the name of the private key used for constructing the digital signatures of meta-AMS messages sent by the configuration server for this continuum. This attribute should only be present in the MIB initialization file for amsd(). The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
ams_mib_add
This element contains a list of configuration items that are to be added to the MIB.
ams_mib_change
This element contains a list of configuration items that are to be revised in the MIB.
ams_mib_delete
This element contains a list of configuration items that are to be deleted from the MIB.
continuum
Identifies a known remote continuum.
Sub-elements: none
Attributes:
nbr
Identifies the remote continuum.
name
Identifies the remote continuum.
neighbor
1 if the continuum is a neighbor of the local continuum, zero otherwise.
desc
A textual description of this continuum.
csendpoint
Identifies one of the network locations at which the configuration server may be reachable. If the configuration server might be running at any one of several locations, the number of other locations that are preferred to this one is noted; in this case, csendpoints must be listed within the ams_mib_add element in descending order of preference, i.e., with the most preferred network location listed first.
Sub-elements: none
Attributes:
epspec
Identifies the endpoint at which the configuration server may be reachable. The endpoint specification must conform to the endpoint specification syntax defined for the continuum's primary transport service; see the AMS Blue Book for details.
after
If present, indicates the number of other configuration server network locations that are considered preferable to this one. This attribute is used to ensure that csendpoints are listed in descending order of preference.
amsendpoint
Normally the specifications of the transport service endpoints at which an AMS application module can receive messages are computed automatically using standard transport-service-specific rules. However, in some cases it might be necessary for a module to receive messages at one or more non-standard endpoints; in these cases, amsendpoint elements can be declared in order to override the standard endpoint specification rules.
Sub-elements: none
Attributes:
tsname
Identifies the transport service for which a non-standard endpoint specification is being supplied.
epspec
Identifies an endpoint at which the application module will be reachable, in the context of the named transport service. The endpoint specification must conform to the endpoint specification syntax defined for the named transport service; see the AMS Blue Book for details.
application
Identifies one of the applications supported within this continuum.
Sub-elements: none
Attributes:
name
Identifies the application.
pubkey
This is the name of the public key used for validating the digital signatures of meta-AMS messages received from the registrars for all cells of any message space in this continuum that is characterized by this application name. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
privkey
This is the name of the private key used for constructing the digital signatures of meta-AMS messages sent by the registrars for all cells of any message space in this continuum that is characterized by this application name. This attribute should only be present in the MIB initialization file for amsd(). The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
venture
Identifies one of the ventures operating within the local continuum.
Sub-elements: role, subject, unit, msgspace
Attributes:
nbr
Identifies the venture.
appname
Identifies the application addressed by this venture.
authname
Identifies the authority under which the venture operates, distinguishing this venture from all other ventures that address the same application.
gweid
Identifies the RAMS network endpoint ID of the RAMS gateway module for this venture's message space in the local continuum. Gateway endpoint ID is expressed as <protocol_name>@<eid_string> where protocol_name is either \"bp\" or \"udp\". If protocol name is \"bp\" then eid_string must be a valid Bundle Protocol endpoint ID; otherwise, eid_string must be of the form <hostname>:<port_number>. If the gweid attribute is omitted, the RAMS gateway module's RAMS network endpoint ID defaults to \"bp@ipn:<local_continuum_number>.<venture_number>\".
net_config
Has the value \"tree\" if the RAMS network supporting this venture is configured as a tree; otherwise \"mesh\", indicating that the RAMS network supporting this venture is configured as a mesh.
root_cell_resync_period
Indicates the number of seconds in the period on which resynchronization is performed for the root cell of this venture's message space in the local continuum. If this attribute is omitted, resynchronization in that cell is disabled.
role
Identifies one of the functional roles in the venture that is the element that's currently being configured.
Sub-elements: none
Attributes:
nbr
Identifies the role.
name
Identifies the role.
authname
Identifies the authority under which the venture operates, distinguishing this venture from all other ventures that address the same application.
pubkey
This is the name of the public key used for validating the digital signatures of meta-AMS messages received from all application modules that register in this functional role. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
privkey
This is the name of the private key used for constructing the digital signatures of meta-AMS messages sent by all application modules that register in this functional role. This attribute should only be present in the MIB initialization file for application modules that register in this role. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
subject
Identifies one of the subjects on which messages may be sent, within the venture that is the element that's currently being configured.
Sub-elements: sender, receiver
Attributes:
nbr
Identifies the subject.
name
Identifies the subject.
desc
A textual description of this message subject.
symkey
This is the name of the symmetric key used for both encrypting and decrypting the content of messages on this subject; if omitted, messages on this subject are not encrypted by AMS. If authorized senders and receivers are defined for this subject, then this attribute should only be present in the MIB initialization file for application modules that register in roles that appear in the subject's lists of authorized senders and/or receivers. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
marshal
This is the name associated with the content marshaling function defined for this message subject. If present, whenever a message on this subject is issued the associated function is automatically called to convert the supplied content data to a platform-independent representation for transmission; this conversion occurs before any applicable content encryption is performed. If omitted, content data are transmitted without conversion to a platform-independent representation. Marshaling functions are defined in the marshalRules table in the marshal.c source file.
unmarshal
This is the name associated with the content unmarshaling function defined for this message subject. If present, whenever a message on this subject is received the associated function is automatically called to convert the transmitted content to local platform-specific representation; this conversion occurs after any applicable content decryption is performed. If omitted, received content data are delivered without conversion to a local platform-specific representation. Unmarshaling functions are defined in the unmarshalRules table in the marshal.c source file.
sender
Identifies one of the roles in which application modules must register in order to be authorized senders of messages on the subject that is the element that's currently being configured.
Sub-elements: none
Attributes:
name
Identifies the sender. The value of this attribute must be the name of a role that has been defined for the venture that is currently being configured.
receiver
Identifies one of the roles in which application modules must register in order to be authorized receivers of messages on the subject that is the element that's currently being configured.
Sub-elements: none
Attributes:
name
Identifies the receiver. The value of this attribute must be the name of a role that has been defined for the venture that is currently being configured.
unit
Identifies one of the organizational units within the venture that is the element that's currently being configured.
Sub-elements: none
Attributes:
nbr
Identifies the unit.
name
Identifies the unit.
resync_period
Indicates the number of seconds in the period on which resynchronization is performed, for the cell of this venture's message space that is the portion of the indicated unit which resides in the local continuum. If this attribute is omitted, resynchronization in that cell is disabled.
msgspace
Identifies one of the message spaces in remote continua that are encompassed by the venture that is the element that's currently being configured.
Sub-elements: none
Attributes:
nbr
Identifies the remote continuum within which the message space operates.
gweid
Identifies the RAMS network endpoint ID of the RAMS gateway module for this message space. Gateway endpoint ID is expressed as <protocol_name>@<eid_string> where protocol_name is either \"bp\" or \"udp\". If protocol name is \"bp\" then eid_string must be a valid Bundle Protocol endpoint ID; otherwise, eid_string must be of the form <hostname>:<port_number>. If the gweid attribute is omitted, the RAMS network endpoint ID of the message space's RAMS gateway module defaults to \"bp@ipn:<remote_continuum_number>.<venture_number>\".
symkey
This is the name of the symmetric key used for both encrypting and decrypting all messages to and from modules in the remote message space that are forwarded between the local RAMS gateway server and modules in the local message space; if omitted, these messages are not encrypted. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
*ams_mib_init continuum_nbr=2 ptsname=dgr
+ams_mib_add
*continuum nbr=1 name=apl desc=APL
*csendpoint epspec=beaumont.stepsoncats.com:2357
*application name=amsdemo
+venture nbr=1 appname=amsdemo authname=test
*role nbr=2 name=shell
*role nbr=3 name=log
*role nbr=4 name=pitch
*role nbr=5 name=catch
*role nbr=6 name=benchs
*role nbr=7 name=benchr
*role nbr=96 name=amsd
*role nbr=97 name=amsmib
*role nbr=98 name=amsstop
*subject nbr=1 name=text desc='ASCII text'
*subject nbr=2 name=noise desc='more ASCII text'
*subject nbr=3 name=bench desc='numbered msgs'
*subject nbr=97 name=amsmib desc='MIB updates'
*subject nbr=98 name=amsstop desc='shutdown'
*unit nbr=1 name=orbiters
*unit nbr=2 name=orbiters.near
*unit nbr=3 name=orbiters.far
*msgspace nbr=2
-venture
-ams_mib_add
"},{"location":"man/ams/amsrc/#see-also","title":"SEE ALSO","text":"amsxml(5)
"},{"location":"man/ams/amsshell/","title":"NAME","text":"amsshell - Asynchronous Message Service (AMS) test message sender (UNIX)
"},{"location":"man/ams/amsshell/#synopsis","title":"SYNOPSIS","text":"amsshell unit_name role_name application_name authority_name [{ p | s | q | a }]
"},{"location":"man/ams/amsshell/#description","title":"DESCRIPTION","text":"amsshell is a message issuance program designed to test AMS functionality.
When amsshell is started, it registers as an application module in the unit identified by unit_name of the venture identified by application_name and authority_name; the role in which it registers must be indicated in role_name. A configuration server for the local continuum and a registrar for the indicated unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for amsshell to run.
amsshell runs as two threads: a background thread that receives watches for AMS configuration events (including shutdown), together with a foreground thread that acquires operating parameters and message content in lines of console input to control the issuance of messages.
The first character of each line of input from stdin to the amsshell indicates the significance of that line:
=
Sets the name of the subject on which all messages are to be issued, until superseded by another \"=\" line. The subject name must begin at the second character of this line. Optionally, subject name may be followed by a single ' ' (space) character and then the text of the first message to be issued on this subject, which is to be issued immediately.
r
Sets the number of the role constraining the domain of message issuance. The role number must begin at the second character of this line.
c
Sets the number of the continuum constraining the domain of message issuance. The continuum number must begin at the second character of this line.
u
Sets the number of the unit constraining the domain of message issuance. The unit number must begin at the second character of this line.
m
Sets the number of the module to which subsequent messages are to be issued. The module number must begin at the second character of this line.
.
Terminates amsshell.
When the first character of a line of input from stdin is none of the above, the entire line is taken to be the text of a message that is to be issued immediately, on the previously specified subject, to the previously specified module (if applicable), and subject to the previously specified domain (if applicable).
By default, amsshell runs in \"publish\" mode: when a message is to be issued, it is simply published. This behavior can be overridden by providing a fifth command-line argument to amsshell - a \"mode\" indicator. The supported modes are as follows:
p
This is \"publish\" mode. Every message is published.
s
This is \"send\" mode. Every message is sent privately to the application module identified by the specified module, unit, and continuum numbers.
q
This is \"query\" mode. Every message is sent privately to the application module identified by the specified module, unit, and continuum numbers, and amsshell then waits for a reply message before continuing.
a
This is \"announce\" mode. Every message is announced to all modules in the domain established by the previously specified role, unit, and continuum numbers.
-1
amsshell terminated with an error as noted in the ion.log file.
\"0\"
amsshell terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amsshell/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsshell/#diagnostics","title":"DIAGNOSTICS","text":"amsshell can't register.
amsshell failed to register, for reasons noted in the ion.log file.
amsshell can't set event manager.
amsshell failed to start its background thread, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsshell/#see-also","title":"SEE ALSO","text":"amslog(1), amsrc(5)
"},{"location":"man/ams/amsstop/","title":"NAME","text":"amsstop - Asynchronous Message Service (AMS) message space shutdown utility
"},{"location":"man/ams/amsstop/#synopsis","title":"SYNOPSIS","text":"amsstop application_name authority_name
"},{"location":"man/ams/amsstop/#description","title":"DESCRIPTION","text":"amsstop is a utility program that terminates the operation of all registrars and all application modules running in the message space which is that portion of the indicated AMS venture that is operating in the local continuum. If one of the amsd tasks that are functioning as registrars for this venture is also functioning as the configuration server for the local continuum, then that configuration server is also terminated.
application_name and authority_name must identify an AMS venture that is known to operate in the local continuum, as noted in the MIB for the amsstop application module.
A message space can only be shut down by amsstop if the subject \"amsstop\" is defined in the MIBs of all modules in the message spaces.
"},{"location":"man/ams/amsstop/#exit-status","title":"EXIT STATUS","text":"\"0\"
amsstop terminated normally.
\"1\"
An anomalous exit status, indicating that amsstop was unable to register and therefore failed to shut down its message space, for reasons noted in the ion.log file.
A MIB initialization file with the applicable default name (see amsrc(5) and amsxml(5)) must be present.
"},{"location":"man/ams/amsstop/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsstop/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
amsstop can't register.
This message indicates that amsstop was unable to register, possibly because the \"amsstop\" role is not defined in the MIB initialization file.
amsstop subject undefined.
This message indicates that amsstop was unable to stop the message space because the \"amsstop\" subject is not defined in the MIB initialization file.
amsstop can't publish 'amsstop' message.
This message indicates that amsstop was unable to publish a message on subject 'amsstop' for reasons noted in the ion.log log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsstop/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amssub/","title":"NAME","text":"amssub - Asynchronous Message Service (AMS) test message receiver for VxWorks
"},{"location":"man/ams/amssub/#synopsis","title":"SYNOPSIS","text":"amssub \"application_name\", \"authority_name\", \"subject_name\"
"},{"location":"man/ams/amssub/#description","title":"DESCRIPTION","text":"amssub is a message reception program designed to test AMS functionality in a VxWorks environment. When an amssub task is started, it registers as an application module in the root unit of the venture identified by application_name and authority_name, looks up the subject number for subject_name, subscribes to that subject, and begins receiving and printing messages on that subject until terminated by amsstop.
A configuration server for the local continuum and a registrar for the root unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for amssub to run.
"},{"location":"man/ams/amssub/#exit-status","title":"EXIT STATUS","text":"-1
amssub terminated with an error as noted in the ion.log file.
\"0\"
amssub terminated normally.
The amssub source code is in the amspubsub.c source file.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amssub/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amssub/#diagnostics","title":"DIAGNOSTICS","text":"amssub can't register.
amssub failed to register, for reasons noted in the ion.log file.
amssub: subject is unknown
amssub can't subscribe to messages on the specified subject; possibly an error in the MIB initialization file.
amssub can't subscribe.
amssub failed to subscribe, for reasons noted in the ion.log file.
amssub can't get event.
amssub failed to receive message, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amssub/#see-also","title":"SEE ALSO","text":"amspub(1), amsrc(5)
"},{"location":"man/ams/amsxml/","title":"NAME","text":"amsxml - CCSDS Asynchronous Message Service MIB initialization XML file
"},{"location":"man/ams/amsxml/#description","title":"DESCRIPTION","text":"The Management Information Base (MIB) for an AMS communicating entity (either amsd or an AMS application module) must contain enough information to enable the entity to initiate participation in AMS message exchange, such as the network location of the configuration server and the roles and message subjects defined for some venture.
AMS entities automatically load their MIBs from initialization files at startup. When AMS is built with the -DNOEXPAT compiler option set, the MIB initialization file must conform to the amsrc syntax described in amsrc(5); otherwise the expat XML parsing library must be linked into the AMS executable and the MIB initialization file must conform to the amsxml syntax described below.
The XML statements in the MIB initialization file constitute elements of MIB update information, each of which may have one or more attributes. An element may also have sub-elements that are listed within the declaration of the parent element, and so on.
Two types of elements are recognized in the MIB initialization file: control elements and configuration elements. A control element establishes the update context within which the configuration elements nested within it are processed, while a configuration element declares values for one or more items of AMS configuration information in the MIB.
For a discussion of the recognized control elements and configuration elements of the MIB initialization file, see the amsrc(5) man page. NOTE, though, that all elements of an XML-based MIB initialization file must be sub-elements of a single sub-element of the XML extension type ams_load_mib in order for the file to be parsed successfully by expat.
"},{"location":"man/ams/amsxml/#example","title":"EXAMPLE","text":"<?xml version=\"1.0\" standalone=\"yes\"?>
<ams_mib_load>
<ams_mib_init continuum_nbr=\"2\" ptsname=\"dgr\"/>\n\n <ams_mib_add>\n\n <continuum nbr=\"1\" name=\"apl\" desc=\"APL\"/>\n\n <csendpoint epspec=\"beaumont.stepsoncats.com:2357\"/>\n\n <application name=\"amsdemo\" />\n\n <venture nbr=\"1\" appname=\"amsdemo\" authname=\"test\">\n\n <role nbr=\"2\" name=\"shell\"/>\n\n <role nbr=\"3\" name=\"log\"/>\n\n <role nbr=\"4\" name=\"pitch\"/>\n\n <role nbr=\"5\" name=\"catch\"/>\n\n <role nbr=\"6\" name=\"benchs\"/>\n\n <role nbr=\"7\" name=\"benchr\"/>\n\n <role nbr=\"96\" name=\"amsd\"/>\n\n <role nbr=\"97\" name=\"amsmib\"/>\n\n <role nbr=\"98\" name=\"amsstop\"/>\n\n <subject nbr=\"1\" name=\"text\" desc=\"ASCII text\"/>\n\n <subject nbr=\"2\" name=\"noise\" desc=\"more ASCII text\"/>\n\n <subject nbr=\"3\" name=\"bench\" desc=\"numbered msgs\"/>\n\n <subject nbr=\"97\" name=\"amsmib\" desc=\"MIB updates\"/>\n\n <subject nbr=\"98\" name=\"amsstop\" desc=\"shutdown\"/>\n\n <unit nbr=\"1\" name=\"orbiters\"/>\n\n <unit nbr=\"2\" name=\"orbiters.near\"/>\n\n <unit nbr=\"3\" name=\"orbiters.far\"/>\n\n <msgspace nbr=\"2\"/>\n\n </venture>\n\n </ams_mib_add>\n</ams_mib_load>
"},{"location":"man/ams/amsxml/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/petition_log/","title":"NAME","text":"petition.log - Remote AMS petition log
"},{"location":"man/ams/petition_log/#description","title":"DESCRIPTION","text":"The Remote AMS daemon ramsgate records all \"petitions\" (requests for data on behalf of AMS modules in other continua) in a file named petition.log. At startup, the ramsgate daemon automatically reads and processes all petitions in the petition.log file just as if they were received in real time, to re-establish the petition state that was in effect at the time the ramsgate daemon shut down. Note that this means that you can cause petitions to be, in effect, \"pre-received\" by simply editing this file prior to startup. This can be an especially effective way to configure a RAMS network in which long signal propagation times would otherwise retard real-time petitioning and thus delay the onset of fully functional message exchange.
Entries in petition.log are simple ASCII text lines, with parameters separated by spaces. Each line of petition.log has the following parameters:
protocolId
This is a number that identifies the RAMS network protocol characterizing the network on which the petition was received: 1 == DTN Bundle Protocol, 2 = UDP.
gatewayID
This is a string that identifies the remote RAMS gateway node that issued this petition.
controlCode
This is a number that indicates whether the petition described by this line is one that is being asserted (2) or canceled (3).
subject
A number that identifies the subject of the traffic to which the petition pertains.
continuumNumber
Identifies the continuum for the domain of the petition.
unitNumber
Identifies the unit for the domain of the petition.
roleNumber
Identifies the role for the domain of the petition.
ramsgate(1), ams(3)
"},{"location":"man/ams/ramsgate/","title":"NAME","text":"ramsgate - Remote AMS gateway daemon
"},{"location":"man/ams/ramsgate/#synopsis","title":"SYNOPSIS","text":"ramsgate application_name authority_name [bundles_TTL]
"},{"location":"man/ams/ramsgate/#description","title":"DESCRIPTION","text":"ramsgate is a background \"daemon\" task that functions as a Remote AMS gateway. application_name and authority_name must identify an AMS venture that is known to operate in the local continuum, as noted in the MIB for the ramsgate application module.
ramsgate will register as an application module in the root unit of the indicated venture, so a configuration server for the local continuum and a registrar for the root unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for ramsgate to commence operations.
ramsgate with communicate with other RAMS gateway modules in other continua by means of the RAMS network protocol noted in the RAMS gateway endpoint ID for the local continuum, as identified (explicitly or implicitly) in the MIB.
If the RAMS network protocol is \"bp\" (i.e., the DTN Bundle Protocol), then an ION Bundle Protocol node must be operating on the local computer and that node must be registered in the BP endpoint identified by the RAMS gateway endpoint ID for the local continuum. Moreover, in this case the value of bundles_TTL - if specified - will be taken as the lifetime in seconds that is to be declared for all \"bundles\" issued by ramsgate; bundles_TTL defaults to 86400 seconds (one day) if omitted.
"},{"location":"man/ams/ramsgate/#exit-status","title":"EXIT STATUS","text":"\"0\"
ramsgate terminated normally.
\"1\"
ramsgate failed, for reasons noted in the ion.log file; the task terminated.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
ramsgate records all \"petitions\" (requests for data on behalf of AMS modules in other continua) in a file named \"petition.log\". At startup, the ramsgate daemon automatically reads and processes all petitions in the petition.log file just as if they were received in real time. Note that this means that you can cause petitions to be, in effect, \"pre-received\" by simply editing this file prior to startup. This can be an especially effective way to configure a RAMS network in which long signal propagation times would otherwise retard real-time petitioning and thus delay the onset of fully functional message exchange.
"},{"location":"man/ams/ramsgate/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/ramsgate/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ramsgate can't run.
RAMS gateway functionality failed, for reasons noted in the ion.log file.
Note that the AMS design principle of receiving messages immediately and enqueuing them for eventual ingestion by the application module - rather than imposing application-layer flow control on AMS message traffic - enables high performance but makes ramsgate vulnerable to message spikes. Since production and transmission of bundles is typically slower than AMS message reception over TCP service, the ION working memory and/or heap space available for AMS event insertion and/or bundle production can be quickly exhausted if a high rate of application message production is sustained for a long enough time. Mechanisms for defending against this sort of failure are under study, but for now the best mitigations are simply to (a) build with compiler option -DAMS_INDUSTRIAL=1, (b) allocate as much space as possible to ION working memory and SDR heap (see ionconfig(5)) and (c) limit the rate of AMS message issuance.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/ramsgate/#see-also","title":"SEE ALSO","text":"amsrc(5), petition_log(5)
"},{"location":"man/bpv6/","title":"Index of Man Pages","text":"acsadmin - ION Aggregate Custody Signal (ACS) administration interface
"},{"location":"man/bpv6/acsadmin/#synopsis","title":"SYNOPSIS","text":"acsadmin [ commands_filename ]
"},{"location":"man/bpv6/acsadmin/#description","title":"DESCRIPTION","text":"acsadmin configures aggregate custody signal behavior for the local ION node.
It operates in response to ACS configuration commands found in the file commands_filename, if provided; if not, acsadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from acsadmin with the 'h' or '?' commands at the prompt. The commands are documented in acsrc(5).
"},{"location":"man/bpv6/acsadmin/#exit-status","title":"EXIT STATUS","text":"acsadmin
Enter interactive ACS configuration command entry mode.
acsadmin host1.acs
Execute all configuration commands in host1.acs, then terminate immediately.
See acsrc(5) for details of the ACS configuration commands.
"},{"location":"man/bpv6/acsadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/acsadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the acsrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to acsadmin. Otherwise acsadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
acsadmin can't attach to ION.
There is no SDR data store for acsadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause acsadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see acsrc(5) for details.
"},{"location":"man/bpv6/acsadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/acsadmin/#see-also","title":"SEE ALSO","text":"ionadmin(1), bpadmin(1), acsrc(5)
"},{"location":"man/bpv6/acslist/","title":"NAME","text":"acslist - Aggregate Custody Signals (ACS) utility for checking custody IDs.
"},{"location":"man/bpv6/acslist/#synopsis","title":"SYNOPSIS","text":"acslist [-s|--stdout]
"},{"location":"man/bpv6/acslist/#description","title":"DESCRIPTION","text":"acslist is a utility program that lists all mappings from bundle ID to custody ID currently in the local bundle agent's ACS ID database, in no specific order. A bundle ID (defined in RFC5050) is the tuple of (source EID, creation time, creation count, fragment offset, fragment length). A custody ID (defined in draft-jenkins-aggregate-custody-signals) is an integer that the local bundle agent will be able to map to a bundle ID for the purposes of aggregating and compressing custody signals.
The format for mappings is:
(ipn:13.1,333823688,95,0,0)->(26)
While listing, acslist also checks the custody ID database for self-consistency, and if it detects any errors it will print a line starting with \"Mismatch:\" and describing the error.
-s|--stdout tells acslist to print results to stdout, rather than to the ION log.
"},{"location":"man/bpv6/acslist/#exit-status","title":"EXIT STATUS","text":"\"0\"
acslist terminated after verifying the consistency of the custody ID database.
\"1\"
acslist was unable to attach to the ACS database, or it detected an inconsistency.
No configuration files are needed.
"},{"location":"man/bpv6/acslist/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/acslist/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued:
Can't attach to ACS.
acsadmin has not yet initialized ACS operations.
Mismatch: (description of the mismatch)
acslist detected an inconsistency in the database; this is a bug in ACS.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/acslist/#see-also","title":"SEE ALSO","text":"acsadmin(1), bplist(1)
"},{"location":"man/bpv6/acsrc/","title":"NAME","text":"acsrc - Aggregate Custody Signal management commands file
"},{"location":"man/bpv6/acsrc/#description","title":"DESCRIPTION","text":"Aggregate Custody Signal management commands are passed to acsadmin either in a file of text lines or interactively at acsadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the Aggregate Custody Signal management commands are described below.
"},{"location":"man/bpv6/acsrc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 acsadmin 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 <logLevel> [<heapWords>]
The initialize command. Until this command is executed, Aggregate Custody Signals are not in operation on the local ION node and most acsadmin commands will fail.
The logLevel argument specifies at which log level the ACS appending and transmitting implementation should record its activity to the ION log file. This argument is the bitwise \"OR\" of the following log levels:
0x01 ERROR
Errors in ACS programming are logged.
0x02 WARN
Warnings like \"out of memory\" that don't cause ACS to fail but may change behavior are logged.
0x04 INFO
Informative information like \"this custody signal is a duplicate\" is logged.
0x08 DEBUG
Verbose information like the state of the pending ACS tree is logged.
The optional heapWords argument informs ACS to allocate that many heap words in its own DRAM SDR for constructing pending ACS. If not supplied, the default value 10000 is used. Once all ACS SDR is allocated, any incoming custodial bundles that would trigger an ACS will trigger a normal, non-aggregate custody signal instead, until ACS SDR is freed. If your node intermittently emits non-aggregate custody signals when it should emit ACS, you should increase heapWords.
Since ACS uses SDR only for emitting Aggregate Custody Signals, ION can still receive ACS even if this command is not executed, or all ACS SDR memory is allocated.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
s <minimumCustodyId>
This command sets the minimum custody ID that the local bundle agent may use in custody transfer enhancement blocks that it emits. These custody IDs must be unique in the network (for the lifetime of the bundles to which they refer).
The minimumCustodyId provided is stored in SDR, and incremented every time a new custody ID is required. So, this command should be used only when the local bundle agent has discarded its SDR and restarted.
t <acsBundleLifetime>
This command sets the lifetime that will be asserted for every ACS bundle subsequently issued by the local bundle agent. The new acsBundleLifetime is stored in SDR.
a custodianEid acsSize [acsDelay]
The add custodian command. This command provides information about the ACS characteristics of a remote custodian. custodianEid is the custodian EID for which this command is providing information. acsSize is the preferred size of ACS bundles sent to custodianEid; ACS bundles this implementation sends to custodianEid will aggregate until ACS are at most acsSize bytes (if acsSize is smaller than 19 bytes, some ACS containing only one signal will exceed acsSize and be sent anyways; setting acsSize to 0 causes \"aggregates\" of only 1 signal to be sent).
acsDelay is the maximum amount of time to delay an ACS destined for this custodian before sending it, in seconds; if not specified, the default value 15 will be used.
a ipn:15.0 100 27
Informs ACS on the local node that the local node should send ACS bundles destined for the custodian ipn:15.0 whenever they are 100 bytes in size or have been delayed for 27 seconds, whichever comes first.
acsadmin(1)
"},{"location":"man/bpv6/bibeclo/","title":"NAME","text":"bibeclo - BP convergence layer output task using bundle-in-bundle encapsulation
"},{"location":"man/bpv6/bibeclo/#synopsis","title":"SYNOPSIS","text":"bibeclo peer_node_eid destination_node_eid
"},{"location":"man/bpv6/bibeclo/#description","title":"DESCRIPTION","text":"bibeclo is a background \"daemon\" task that extracts bundles from the queues of bundles ready for transmission to destination_node_eid via bundle-in-bundle encapsulation (BIBE), encapsulates them in BP administrative records of (non-standard) record type 7 (BP_ENCAPSULATED_BUNDLE), and sends those administrative records to the DTN node identified by peer_node_eid. The receiving node is expected to process these received administrative records by simply dispatching the encapsulated bundles as if they had been received from neighboring nodes in the normal course of operations.
bibeclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. bibeclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BIBE convergence layer protocol.
"},{"location":"man/bpv6/bibeclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
bibeclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bibeclo.
\"1\"
bibeclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart bibeclo.
No configuration files are needed.
"},{"location":"man/bpv6/bibeclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bibeclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bibeclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such bibe duct.
No BIBE outduct with duct name destination_node_eid has been added to the BP database. Use bpadmin to stop the BIBE convergence-layer protocol, add the outduct, and then restart the BIBE protocol.
No such bcla.
No BIBE convergence layer adapter named peer_node_eid has been added to the BIBE database. Use bibeadmin to add the BCLA.
CLO task is already started for this duct.
Redundant initiation of bibeclo.
Can't prepend header; CLO stopping.
This is a system error. Check ION log, correct problem, and restart BIBE.
Can't send encapsulated bundle; CLO stopping.
This is a system error. Check ION log, correct problem, and restart BIBE.
[!] Encapsulated bundle not sent.
Malformed bundle issuance request, which might be a software error. Contact technical support.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bibeclo/#see-also","title":"SEE ALSO","text":"bibeadmin(1), bp(3), biberc(5)
"},{"location":"man/bpv6/bp/","title":"NAME","text":"bp - Bundle Protocol communications library
"},{"location":"man/bpv6/bp/#synopsis","title":"SYNOPSIS","text":"#include \"bp.h\"\n\n[see description for available functions]\nThe bp library provides functions enabling application software to use Bundle Protocol to send and receive information over a delay-tolerant network. It conforms to the Bundle Protocol specification as documented in Internet RFC 5050.
int bp_attach( )
Attaches the application to BP functionality on the local computer. Returns 0 on success, -1 on any error.
Note that all ION libraries and applications draw memory dynamically, as needed, from a shared pool of ION working memory. The size of the pool is established when ION node functionality is initialized by ionadmin(1). This is a precondition for initializing BP functionality by running bpadmin(1), which in turn is required in order for bp_attach() to succeed.
Sdr bp_get_sdr( )
Returns handle for the SDR data store used for BP, to enable creation and interrogation of bundle payloads (application data units).
void bp_detach( )
Terminates all access to BP functionality on the local computer.
int bp_open(char *eid, BpSAP *ionsapPtr)
Opens the application's access to the BP endpoint identified by eid, so that the application can take delivery of bundles destined for the indicated endpoint. This SAP can also be used for sending bundles whose source is the indicated endpoint; all bundles sent via this SAP will be subject to immediate destruction upon transmission, i.e., no bundle addresses will be returned by bp_send() for use in tracking, suspending/resuming, or cancelling transmission of these bundles. On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
int bp_open_source(char *eid, BpSAP *ionsapPtr, detain)
Opens the application's access to the BP endpoint identified by eid, so that the application can send bundles whose source is the indicated endpoint. If and only if the value of detain is non-zero, citing this SAP in an invocation of bp_send() will cause the address of the newly issued bundle to be returned for use in tracking, suspending/resuming, or cancelling transmission of this bundle. USE THIS FEATURE WITH GREAT CARE: such a bundle will continue to occupy storage resources until it is explicitly released by an invocation of bp_release() or until its time to live expires, so bundle detention increases the risk of resource exhaustion. (If the value of detain is zero, all bundles sent via this SAP will be subject to immediate destruction upon transmission.) On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
int bp_send(BpSAP sap, char *destEid, char *reportToEid, int lifespan, int classOfService, BpCustodySwitch custodySwitch, unsigned char srrFlags, int ackRequested, BpAncillaryData *ancillaryData, Object adu, Object *newBundle)
Sends a bundle to the endpoint identified by destEid, from the source endpoint as provided to the bp_open() call that returned sap. When sap is NULL, the transmitted bundle is anonymous, i.e., the source of the bundle is not identified. This is legal, but anonymous bundles cannot be uniquely identified; custody transfer and status reporting therefore cannot be requested for an anonymous bundle.
reportToEid identifies the endpoint to which any status reports pertaining to this bundle will be sent; if NULL, defaults to the source endpoint.
lifespan is the maximum number of seconds that the bundle can remain in-transit (undelivered) in the network prior to automatic deletion.
classOfService is simply priority for now: BP_BULK_PRIORITY, BP_STD_PRIORITY, or BP_EXPEDITED_PRIORITY. If class-of-service flags are defined in a future version of Bundle Protocol, those flags would be OR'd with priority.
custodySwitch indicates whether or not custody transfer is requested for this bundle and, if so, whether or not the source node itself is required to be the initial custodian. The valid values are SourceCustodyRequired, SourceCustodyOptional, NoCustodyRequired. Note that custody transfer is possible only for bundles that are uniquely identified, so it cannot be requested for bundles for which BP_MINIMUM_LATENCY is requested, since BP_MINIMUM_LATENCY may result in the production of multiple identical copies of the same bundle. Similarly, custody transfer should never be requested for a \"loopback\" bundle, i.e., one whose destination node is the same as the source node: the received bundle will be identical to the source bundle, both residing in the same node, so no custody acceptance signal can be applied to the source bundle and the source bundle will remain in storage until its TTL expires.
srrFlags, if non-zero, is the logical OR of the status reporting behaviors requested for this bundle: BP_RECEIVED_RPT, BP_CUSTODY_RPT, BP_FORWARDED_RPT, BP_DELIVERED_RPT, BP_DELETED_RPT.
ackRequested is a Boolean parameter indicating whether or not the recipient application should be notified that the source application requests some sort of application-specific end-to-end acknowledgment upon receipt of the bundle.
ancillaryData, if not NULL, is used to populate the Extended Class Of Service block for this bundle. The block's ordinal value is used to provide fine-grained ordering within \"expedited\" traffic: ordinal values from 0 (the default) to 254 (used to designate the most urgent traffic) are valid, with 255 reserved for custody signals. The value of the block's flags is the logical OR of the applicable extended class-of-service flags:
BP\\_MINIMUM\\_LATENCY designates the bundle as \"critical\" for the\npurposes of Contact Graph Routing.\n\nBP\\_BEST\\_EFFORT signifies that non-reliable convergence-layer protocols, as\navailable, may be used to transmit the bundle. Notably, the bundle may be\nsent as \"green\" data rather than \"red\" data when issued via LTP.\n\nBP\\_DATA\\_LABEL\\_PRESENT signifies whether or not the value of _dataLabel_\nin _ancillaryData_ must be encoded into the ECOS block when the bundle is\ntransmitted.\nadu is the \"application data unit\" that will be conveyed as the payload of the new bundle. adu must be a \"zero-copy object\" (ZCO). To ensure orderly access to transmission buffer space for all applications, adu must be created by invoking ionCreateZco(), which may be configured either to block so long as insufficient ZCO storage space is available for creation of the requested ZCO or to fail immediately if insufficient ZCO storage space is available.
The function returns 1 on success, 0 on user error, -1 on any system error. If 0 is returned, then an invalid argument value was passed to bp_send(); a message to this effect will have been written to the log file. If 1 is returned, then either the destination of the bundle was \"dtn:none\" (the bit bucket) or the ADU has been accepted and queued for transmission in a bundle. In the latter case, if and only if sap was a reference to a BpSAP returned by an invocation of bp_open_source() that had a non-zero value in the detain parameter, then newBundle must be non-NULL and the address of the newly created bundle within the ION database is placed in newBundle. This address can be used to track, suspend/resume, or cancel transmission of the bundle.
int bp_track(Object bundle, Object trackingElt)
Adds trackingElt to the list of \"tracking\" references in bundle. trackingElt must be the address of an SDR list element -- whose data is the address of this same bundle -- within some list of bundles that is privately managed by the application. Upon destruction of the bundle this list element will automatically be deleted, thus removing the bundle from the application's privately managed list of bundles. This enables the application to keep track of bundles that it is operating on without risk of inadvertently de-referencing the address of a nonexistent bundle.
void bp_untrack(Object bundle, Object trackingElt)
Removes trackingElt from the list of \"tracking\" references in bundle, if it is in that list. Does not delete trackingElt itself.
int bp_memo(Object bundle, unsigned int interval)
Implements custodial retransmission. This function inserts a \"custody-acceptance due\" event into the timeline. The event causes the indicated bundle to be re-forwarded if it is still in the database (i.e., it has not yet been accepted by another custodian) as of the time computed by adding the indicated interval to the current time.
int bp_suspend(Object bundle)
Suspends transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or if the bundle is already suspended. Otherwise, reverses the enqueuing of the bundle to its selected transmission outduct and places it in the \"limbo\" queue until the suspension is lifted by calling bp_resume. Returns 0 on success, -1 on any error.
int bp_resume(Object bundle)
Terminates suspension of transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or is not suspended. Otherwise, removes the bundle from the \"limbo\" queue and queues it for route re-computation and re-queuing. Returns 0 on success, -1 on any error.
int bp_cancel(Object bundle)
Cancels transmission of bundle. If the indicated bundle is currently queued for forwarding, transmission, or retransmission, it is removed from the relevant queue and destroyed exactly as if its Time To Live had expired. Returns 0 on success, -1 on any error.
int bp_release(Object bundle)
Releases a detained bundle for destruction when all retention constraints have been removed. After a detained bundle has been released, the application can no longer track, suspend/resume, or cancel its transmission. Returns 0 on success, -1 on any error.
int bp_receive(BpSAP sap, BpDelivery *dlvBuffer, int timeoutSeconds)
Receives a bundle, or reports on some failure of bundle reception activity.
The \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one bundle destined for the endpoint for which this SAP is opened has not yet been delivered to the SAP, then the payload of the oldest such bundle will be returned in dlvBuffer->adu and dlvBuffer->result will be set to BpPayloadPresent. If there is no such bundle, bp_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is BP_POLL (i.e., zero) and no bundle is awaiting delivery, or if timeoutSeconds is greater than zero but no bundle arrives before timeoutSeconds have elapsed, then dlvBuffer->result will be set to BpReceptionTimedOut. If timeoutSeconds is BP_BLOCKING (i.e., -1) then bp_receive() blocks until either a bundle arrives or the function is interrupted by an invocation of bp_interrupt().
dlvBuffer->result will be set to BpReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer->result will be set to BpEndpointStopped in the event that the operation of the indicated endpoint has been terminated.
The application data unit delivered in the data delivery structure, if any, will be a \"zero-copy object\" reference. Use zco reception functions (see zco(3)) to read the content of the application data unit.
Be sure to call bp_release_delivery() after every successful invocation of bp_receive().
The function returns 0 on success, -1 on any error.
void bp_interrupt(BpSAP sap)
Interrupts a bp_receive() invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, sap may need to be obtained from a static variable.
void bp_release_delivery(BpDelivery *dlvBuffer, int releaseAdu)
Releases resources allocated to the indicated delivery. releaseAdu is a Boolean parameter: if non-zero, the ADU ZCO reference in dlvBuffer (if any) is destroyed, causing the ZCO itself to be destroyed if no other references to it remain.
void bp_close(BpSAP sap)
Terminates the application's access to the BP endpoint identified by the eid cited by the indicated service access point. The application relinquishes its ability to take delivery of bundles destined for the indicated endpoint and to send bundles whose source is the indicated endpoint.
bpadmin(1), lgsend(1), lgagent(1), bpextensions(3), bprc(5), lgfile(5)
"},{"location":"man/bpv6/bpadmin/","title":"NAME","text":"bpadmin - ION Bundle Protocol (BP) administration interface
"},{"location":"man/bpv6/bpadmin/#synopsis","title":"SYNOPSIS","text":"bpadmin [ commands_filename | . | ! ]
"},{"location":"man/bpv6/bpadmin/#description","title":"DESCRIPTION","text":"bpadmin configures, starts, manages, and stops bundle protocol operations for the local ION node.
It operates in response to BP configuration commands found in the file commands_filename, if provided; if not, bpadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to bpadmin -- that is, the ION node's bpclock task, forwarder tasks, and convergence layer adapter tasks are stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's bpclock task, forwarder tasks, and convergence layer adapter tasks are restarted.
The format of commands for commands_filename can be queried from bpadmin with the 'h' or '?' commands at the prompt. The commands are documented in bprc(5).
"},{"location":"man/bpv6/bpadmin/#exit-status","title":"EXIT STATUS","text":"bpadmin
Enter interactive BP configuration command entry mode.
bpadmin host1.bp
Execute all configuration commands in host1.bp, then terminate immediately.
bpadmin .
Stop all bundle protocol operations on the local node.
See bprc(5) for details of the BP configuration commands.
"},{"location":"man/bpv6/bpadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the bprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bpadmin. Otherwise bpadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ION can't set custodian EID information.
The custodial_endpoint_id specified in the BP initialization ('1') command is malformed. Remember that the format for this argument is ipn:element_number.0 and that the final 0 is required, as custodial/administration service is always service 0. Additional detail for this error is provided if one of the following other errors is present:
Malformed EID.\n\nMalformed custodian EID.\nbpadmin can't attach to ION.
There is no SDR data store for bpadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bpadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see bprc(5) for details.
"},{"location":"man/bpv6/bpadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpadmin/#see-also","title":"SEE ALSO","text":"ionadmin(1), bprc(5), ipnadmin(1), ipnrc(5), dtnadmin(1), dtnrc(5)
"},{"location":"man/bpv6/bpcancel/","title":"NAME","text":"bpcancel - Bundle Protocol (BP) bundle cancellation utility
"},{"location":"man/bpv6/bpcancel/#synopsis","title":"SYNOPSIS","text":"bpcancel source_EID creation_seconds [creation_count [fragment_offset [fragment_length]]]
"},{"location":"man/bpv6/bpcancel/#description","title":"DESCRIPTION","text":"bpcancel attempts to locate the bundle identified by the command-line parameter values and cancel transmission of this bundle. Bundles for which multiple copies have been queued for transmission can't be canceled, because one or more of those copies might already have been transmitted. Transmission of a bundle that has never been cloned and that is still in local bundle storage is cancelled by simulation of an immediate time-to-live expiration.
"},{"location":"man/bpv6/bpcancel/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcancel has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bpcancel/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpcancel/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
bpcancel failed finding bundle.
The attempt to locate the subject bundle failed due to some serious system error. It will probably be necessary to terminate and re-initialize the local ION node.
bpcancel failed destroying bundle.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpcancel failed.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpcancel/#see-also","title":"SEE ALSO","text":"bplist(1)
"},{"location":"man/bpv6/bpchat/","title":"NAME","text":"bpchat - Bundle Protocol chat test program
"},{"location":"man/bpv6/bpchat/#synopsis","title":"SYNOPSIS","text":"bpchat sourceEID destEID [ct]
"},{"location":"man/bpv6/bpchat/#description","title":"DESCRIPTION","text":"bpchat uses Bundle Protocol to send input text in bundles, and display the payload of received bundles as output. It is similar to the talk utility, but operates over the Bundle Protocol. It operates like a combination of the bpsource and bpsink utilities in one program (unlike bpsource, bpchat emits bundles with a sourceEID).
If the sourceEID and destEID are both bpchat applications, then two users can chat with each other over the Bundle Protocol: lines that one user types on the keyboard will be transported over the network in bundles and displayed on the screen of the other user (and the reverse).
bpchat terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv6/bpchat/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpchat has terminated normally. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpchat has terminated due to a BP transmit or reception failure. Details should be noted in the ion.log log file.
If the string \"ct\" is appended as the last argument, then bundles will be sent with custody transfer requested.
No configuration files are needed.
"},{"location":"man/bpv6/bpchat/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpchat/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpchat are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpchat bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpchat can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpchat/#see-also","title":"SEE ALSO","text":"bpecho(1), bpsource(1), bpsink(1), bp(3)
"},{"location":"man/bpv6/bpclm/","title":"NAME","text":"bpclm - DTN bundle protocol convergence layer management daemon
"},{"location":"man/bpv6/bpclm/#synopsis","title":"SYNOPSIS","text":"bpclm neighboring_node_ID
"},{"location":"man/bpv6/bpclm/#description","title":"DESCRIPTION","text":"bpclm is a background \"daemon\" task that manages the transmission of bundles to a single designated neighboring node (as constrained by an \"egress plan\" data structure for that node) by one or more convergence-layer (CL) adapter output daemons (via buffer structures called \"outducts\").
bpclm is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. bpclm can also be spawned and terminated in response to commands that START and STOP the corresponding node's egress plan.
"},{"location":"man/bpv6/bpclm/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpclm terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the egress plan for this node.
\"1\"
bpclm terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the egress plan for this node.
No configuration files are needed.
"},{"location":"man/bpv6/bpclm/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpclm/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpclm can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No egress plan for this node
No egress plan for the node identified by neighboring_node_ID has been added to the BP database. Use bpadmin to add and start the plan.
bpclm task is already started for this node
Redundant initiation of bpclm.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpclm/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv6/bpclock/","title":"NAME","text":"bpclock - Bundle Protocol (BP) daemon task for managing scheduled events
"},{"location":"man/bpv6/bpclock/#synopsis","title":"SYNOPSIS","text":"bpclock
"},{"location":"man/bpv6/bpclock/#description","title":"DESCRIPTION","text":"bpclock is a background \"daemon\" task that periodically performs scheduled Bundle Protocol activities. It is spawned automatically by bpadmin in response to the 's' command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command.
Once per second, bpclock takes the following action:
First it (a) destroys all bundles whose TTLs have expired, (b) enqueues for re-forwarding all bundles that were expected to have been transmitted (by convergence-layer output tasks) by now but are still stuck in their assigned transmission queues, and (c) enqueues for re-forwarding all bundles for which custody has not yet been taken that were expected to have been received and acknowledged by now (as noted by invocation of the bpMemo() function by some convergence-layer adapter that had CL-specific insight into the appropriate interval to wait for custody acceptance).
Then bpclock adjusts the transmission and reception \"throttles\" that control rates of LTP transmission to and reception from neighboring nodes, in response to data rate changes as noted in the RFX database by rfxclock.
bpclock then checks for bundle origination activity that has been blocked due to insufficient allocated space for BP traffic in the ION data store: if space for bundle origination is now available, bpclock gives the bundle production throttle semaphore to unblock that activity.
Finally, bpclock applies rate control to all convergence-layer protocol inducts and outducts:
For each induct, bpclock increases the current capacity of the duct by the applicable nominal data reception rate. If the revised current capacity is greater than zero, bpclock gives the throttle's semaphore to unblock data acquisition (which correspondingly reduces the current capacity of the duct) by the associated convergence layer input task.
For each outduct, bpclock increases the current capacity of the duct by the applicable nominal data transmission rate. If the revised current capacity is greater than zero, bpclock gives the throttle's semaphore to unblock data transmission (which correspondingly reduces the current capacity of the duct) by the associated convergence layer output task.
"},{"location":"man/bpv6/bpclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bpclock.
\"1\"
bpclock was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/bpclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpclock can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't dispatch events.
An unrecoverable database error was encountered. bpclock terminates.
Can't adjust throttles.
An unrecoverable database error was encountered. bpclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpclock/#see-also","title":"SEE ALSO","text":"bpadmin(1), rfxclock(1)
"},{"location":"man/bpv6/bpcounter/","title":"NAME","text":"bpcounter - Bundle Protocol reception test program
"},{"location":"man/bpv6/bpcounter/#synopsis","title":"SYNOPSIS","text":"bpcounter ownEndpointId [maxCount]
"},{"location":"man/bpv6/bpcounter/#description","title":"DESCRIPTION","text":"bpcounter uses Bundle Protocol to receive application data units from a remote bpdriver application task. When the total number of application data units it has received exceeds maxCount, it terminates and prints its reception count. If maxCount is omitted, the default limit is 2 billion application data units.
"},{"location":"man/bpv6/bpcounter/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcounter has terminated. Any problems encountered during operation will be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv6/bpcounter/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpcounter/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpcounter are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpcounter bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpcounter/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpdriver(1), bpecho(1), bp(3)
"},{"location":"man/bpv6/bpdriver/","title":"NAME","text":"bpdriver - Bundle Protocol transmission test program
"},{"location":"man/bpv6/bpdriver/#synopsis","title":"SYNOPSIS","text":"bpdriver nbrOfCycles ownEndpointId destinationEndpointId [length] [t_TTL_]
"},{"location":"man/bpv6/bpdriver/#description","title":"DESCRIPTION","text":"bpdriver uses Bundle Protocol to send nbrOfCycles application data units of length indicated by length, to a counterpart application task that has opened the BP endpoint identified by destinationEndpointId.
If omitted, length defaults to 60000.
TTL indicates the number of seconds the bundles may remain in the network, undelivered, before they are automatically destroyed. If omitted, TTL defaults to 300 seconds.
bpdriver normally runs in \"echo\" mode: after sending each bundle it waits for an acknowledgment bundle before sending the next one. For this purpose, the counterpart application task should be bpecho.
Alternatively bpdriver can run in \"streaming\" mode, i.e., without expecting or receiving acknowledgments. Streaming mode is enabled when length is specified as a negative number, in which case the additive inverse of length is used as the effective value of length. For this purpose, the counterpart application task should be bpcounter.
If the effective value of length is 1, the sizes of the transmitted service data units will be randomly selected multiples of 1024 in the range 1024 to 62464.
bpdriver normally runs with custody transfer disabled. To request custody transfer for all bundles sent by bpdriver, specify nbrOfCycles as a negative number; the additive inverse of nbrOfCycles will be used as its effective value in this case.
When all copies of the file have been sent, bpdriver prints a performance report.
"},{"location":"man/bpv6/bpdriver/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpdriver has terminated. Any problems encountered during operation will be noted in the ion.log log file.
The service data units transmitted by bpdriver are sequences of text obtained from a file in the current working directory named \"bpdriverAduFile\", which bpdriver creates automatically.
"},{"location":"man/bpv6/bpdriver/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpdriver/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpdriver are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
Can't create ADU file
Operating system error. Check errtext, correct problem, and rerun.
Error writing to ADU file
Operating system error. Check errtext, correct problem, and rerun.
bpdriver can't create file ref.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpdriver can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpdriver can't send message
Bundle Protocol service to the remote endpoint has been stopped.
bpdriver reception failed
bpdriver is in \"echo\" mode, and Bundle Protocol delivery service has been stopped.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpdriver/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpcounter(1), bpecho(1), bp(3)
"},{"location":"man/bpv6/bpecho/","title":"NAME","text":"bpecho - Bundle Protocol reception test program
"},{"location":"man/bpv6/bpecho/#synopsis","title":"SYNOPSIS","text":"bpecho ownEndpointId
"},{"location":"man/bpv6/bpecho/#description","title":"DESCRIPTION","text":"bpecho uses Bundle Protocol to receive application data units from a remote bpdriver application task. In response to each received application data unit it sends back an \"echo\" application data unit of length 2, the NULL-terminated string \"x\".
bpecho terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv6/bpecho/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpecho has terminated normally. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpecho has terminated due to a BP reception failure. Details should be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv6/bpecho/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpecho/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpecho are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpecho bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpecho can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpecho/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpdriver(1), bpcounter(1), bp(3)
"},{"location":"man/bpv6/bpextensions/","title":"NAME","text":"bpextensions - interface for adding extensions to Bundle Protocol
"},{"location":"man/bpv6/bpextensions/#synopsis","title":"SYNOPSIS","text":"#include \"bpextensions.c\"\nION's interface for extending the Bundle Protocol enables the definition of external functions that insert extension blocks into outbound bundles (either before or after the payload block), parse and record extension blocks in inbound bundles, and modify extension blocks at key points in bundle processing. All extension-block handling is statically linked into ION at build time, but the addition of an extension never requires that any standard ION source code be modified.
Standard structures for recording extension blocks -- both in transient storage [memory] during bundle acquisition (AcqExtBlock) and in persistent storage [the ION database] during subsequent bundle processing (ExtensionBlock) -- are defined in the bei.h header file. In each case, the extension block structure comprises a block type code, block processing flags, possibly a list of EID references, an array of bytes (the serialized form of the block, for transmission), the length of that array, optionally an extension-specific opaque object whose structure is designed to characterize the block in a manner that's convenient for the extension processing functions, and the size of that object.
The definition of each extension is asserted in an ExtensionDef structure, also as defined in the bei.h header file. Each ExtensionDef must supply:
The name of the extension. (Used in some diagnostic messages.)
The extension's block type code.
A pointer to an offer function.
A pointer to a function to be called when forwarding a bundle containing this sort of block.
A pointer to a function to be called when taking custody of a bundle containing this sort of block.
A pointer to a function to be called when enqueuing for transmission a bundle containing this sort of block.
A pointer to a function to be called when a convergence-layer adapter dequeues a bundle containing this sort of block, before serializing it.
A pointer to a function to be called immediately before a convergence-layer adapter transmits a bundle containing this sort of block, after the bundle has been serialized.
A pointer to a release function.
A pointer to a copy function.
A pointer to an acquire function.
A pointer to a decrypt function.
A pointer to a parse function.
A pointer to a check function.
A pointer to a record function.
A pointer to a clear function.
All extension definitions must be coded into an array of ExtensionDef structures named extensionDefs.
An array of ExtensionSpec structures named extensionSpecs is also required. Each ExtensionSpec provides the specification for producing an outbound extension block: block definition (identified by block type number), three discriminator tags whose semantics are block-type-specific, and a list index value indicating whether the extension block is to be inserted before or after the Payload block. The order of appearance of extension specifications in the extensionSpecs array determines the order in which extension blocks will be inserted into locally sourced bundles.
The standard extensionDefs array -- which is empty -- is in the noextensions.c prototype source file. The procedure for extending the Bundle Protocol in ION is as follows:
1. Specify -DBP_EXTENDED in the Makefile's compiler command line when building the libbpP.c library module.
2. Create a copy of the prototype extensions file, named \"bpextensions.c\", in a directory that is made visible to the Makefile's libbpP.c compilation command line (by a -I parameter).
3. In the \"external function declarations\" area of \"bpextensions.c\", add \"extern\" function declarations identifying the functions that will implement your extension (or extensions).
4. Add one or more ExtensionDef structure initialization lines to the extensionDefs array, referencing those declared functions.
5. Add one or more ExtensionSpec structure initialization lines to the extensionSpecs array, referencing those extension definitions.
6. Develop the implementations of the extension implementation functions in one or more new source code files.
7. Add the object file or files for the new extension implementation source file (or files) to the Makefile's command line for linking libbpP.so.
The function pointers supplied in each ExtensionDef must conform to the following specifications. NOTE that any function that modifies the bytes member of an ExtensionBlock or AckExtBlock must set the corresponding length to the new length of the bytes array, if changed.
int (*BpExtBlkOfferFn)(ExtensionBlock *blk, Bundle *bundle)
Populates all fields of the indicated ExtensionBlock structure for inclusion in the indicated outbound bundle. This function is automatically called when a new bundle is locally sourced or upon acquisition of a remotely sourced bundle that does not contain an extension block of this type. The values of the extension block are typically expected to be a function of the state of the bundle, but this is extension-specific. If it is not appropriate to offer an extension block of this type as part of this bundle, then the size, length, object, and bytes members of blk must all be set to zero. If it is appropriate to offer such a block but no internal object representing the state of the block is needed, the object and size members of blk must be set to zero. The type, blkProcFlags, and dataLength members of blk must be populated by the implementation of the \"offer\" function, but the length and bytes members are typically populated by calling the BP library function serializeExtBlk(), which must be passed the block to be serialized (with type, blkProcFlags and dataLength already set), a Lyst of EID references (two list elements -- offsets -- per EID reference, if applicable; otherwise NULL), and a pointer to the extension-specific block data. The block's bytes array and object (if present) must occupy space allocated from the ION database heap. Return zero on success, -1 on any system failure.
int (*BpExtBlkProcessFn)(ExtensionBlock *blk, Bundle *bundle, void *context)
Performs some extension-specific transformation of the data encapsulated in blk based on the state of bundle. The transformation to be performed will typically vary depending on whether the identified function is the one that is automatically invoked upon forwarding the bundle, upon taking custody of the bundle, upon enqueuing the bundle for transmission, upon removing the bundle from the transmission queue, or upon transmitting the serialized bundle. The context argument may supply useful supplemental information; in particular, the context provided to the ON_DEQUEUE function will comprise the name of the protocol for the duct from which the bundle has been dequeued, together with the EID of the neighboring node endpoint to which the bundle will be directly transmitted when serialized. The block-specific data in blk is located within bytes immediately after the header of the extension block; the length of the block's header is the difference between length and dataLength. Whenever the block's blkProcFlags, EID extensions, and/or block-specific data are altered, the serializeExtBlk() function should be called again to recalculate the size of the extension block and rebuild the bytes array. Return zero on success, -1 on any system failure.
void (*BpExtBlkReleaseFn)(ExtensionBlock *blk)
Releases all ION database space occupied by the object member of blk. This function is automatically called when a bundle is destroyed. Note that incorrect implementation of this function may result in a database space leak.
int (*BpExtBlkCopyFn)(ExtensionBlock *newblk, ExtensionBlock *oldblk)
Copies the object member of oldblk to ION database heap space and places the address of that new non-volatile object in the object member of newblk, also sets size in newblk. This function is automatically called when two copies of a bundle are needed, e.g., in the event that it must both be delivered to a local client and also fowarded to another node. Return zero on success, -1 on any system failure.
int (*BpAcqExtBlkAcquireFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Populates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is only to be provided for extension blocks that are never encrypted; a extension block that may be encrypted should have a BpAcqExtBlkParseFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkDecryptFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Decrypts some other extension block that has been acquired but not yet parsed, nominally using encapsulated ciphersuite information. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if no error in decryption was encountered, -1 on any system failure.
int (*BpAcqExtBlkParseFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Populates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is provided for extension blocks that may be encrypted; a extension block that can never be encrypted should have a BpAcqExtBlkAcquireFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkCheckFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Examines the bundle in work to determine whether or not it is authentic, in the context of the indicated extension block. Return 1 if the block is determined to be inauthentic (this will cause the bundle to be discarded), zero if no inauthenticity is detected, -1 on any system failure.
int (*BpExtBlkRecordFn)(ExtensionBlock *blk, AcqExtBlock *acqblk)
Copies the object member of acqblk to ION database heap space and places the address of that non-volatile object in the object member of blk; also sets size in blk. This function is automatically called when an acquired bundle is accepted for forwarding and/or delivery. Return zero on success, -1 on any system failure.
void (*BpAcqExtBlkClearFn)(AcqExtBlock *acqblk)
Uses MRELEASE to release all ION working memory occupied by the object member of acqblk. This function is automatically called when acquisition of a bundle is completed, whether or not the bundle is accepted. Note that incorrect implementation of this function may result in a working memory leak.
void discardExtensionBlock(AcqExtBlock *blk)
Deletes this block from the bundle acquisition work area prior to the recording of the bundle in the ION database.
void scratchExtensionBlock(ExtensionBlock *blk)
Deletes this block from the bundle after the bundle has been recorded in the ION database.
Object findExtensionBlock(Bundle *bundle, unsigned int type, unsigned int listIdx)
On success, returns the address of the ExtensionBlock in bundle for the indicated type and listIdx. If no such extension block exists, returns zero.
int serializeExtBlk(ExtensionBlock *blk, Lyst eidReferences, char *blockData)
Constructs an RFC5050-conformant serialized representation of this extension block in blk->bytes. Returns 0 on success, -1 on an unrecoverable system error.
void suppressExtensionBlock(ExtensionBlock *blk)
Causes blk to be omitted when the bundle to which it is attached is serialized for transmission. This suppression remains in effect until it is reversed by restoreExtensionBlock();
void restoreExtensionBlock(ExtensionBlock *blk)
Reverses the effect of suppressExtensionBlock(), enabling the block to be included when the bundle to which it is attached is serialized.
bp(3)
"},{"location":"man/bpv6/bping/","title":"NAME","text":"bping - Send and receive Bundle Protocol echo bundles.
"},{"location":"man/bpv6/bping/#synopsis","title":"SYNOPSIS","text":"bping [-c count] [-i interval] [-p priority] [-q wait] [-r flags] [-t ttl] srcEID destEID [reporttoEID]
"},{"location":"man/bpv6/bping/#description","title":"DESCRIPTION","text":"bping sends bundles from srcEID to destEID. If the destEID echoes the bundles back (for instance, it is a bpecho endpoint), bping will print the round-trip time. When complete, bping will print statistics before exiting. It is very similar to ping, except it works with the bundle protocol.
bping terminates when one of the following happens: it receives the SIGINT signal (Ctrl+C), it receives responses to all of the bundles it sent, or it has sent all count of its bundles and waited wait seconds.
When bping is executed in a VxWorks or RTEMS environment, its runtime arguments are presented positionally rather than by keyword, in this order: count, interval, priority, wait, flags, TTL, verbosity (a Boolean, defaulting to zero), source EID, destination EID, report-to EID.
Source EID and destination EID are always required.
"},{"location":"man/bpv6/bping/#exit-status","title":"EXIT STATUS","text":"These exit statuses are taken from ping.
\"0\"
bping has terminated normally, and received responses to all the packets it sent.
\"1\"
bping has terminated normally, but it did not receive responses to all the packets it sent.
\"2\"
bping has terminated due to an error. Details should be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv6/bping/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bping/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bping are written to the ION log file ion.log and printed to standard error. Diagnostic messages that don't cause bping to terminate indicate a failure parsing an echo response bundle. This means that destEID isn't an echo endpoint: it's responding with some other bundle message of an unexpected format.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bping bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bping can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bping/#see-also","title":"SEE ALSO","text":"bpecho(1), bptrace(1), bpadmin(1), bp(3), ping(8)
"},{"location":"man/bpv6/bplist/","title":"NAME","text":"bplist - Bundle Protocol (BP) utility for listing queued bundles
"},{"location":"man/bpv6/bplist/#synopsis","title":"SYNOPSIS","text":"bplist [{count | detail} [destination_EID[/priority]]]
"},{"location":"man/bpv6/bplist/#description","title":"DESCRIPTION","text":"bplist is a utility program that reports on bundles that currently reside in the local node, as identified by entries in the local bundle agent's \"timeline\" list.
Either a count of bundles or a detailed list of bundles (noting primary block information together with hex and ASCII dumps of the payload and all extension blocks, in expiration-time sequence) may be requested.
Either all bundles or just a subset of bundles - restricted to bundles for a single destination endpoint, or to bundles of a given level of priority that are all destined for some specified endpoint - may be included in the report.
By default, bplist prints a detailed list of all bundles residing in the local node.
"},{"location":"man/bpv6/bplist/#exit-status","title":"EXIT STATUS","text":"\"0\"
bplist terminated, for reasons noted in the ion.log file.
\"1\"
bplist was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/bplist/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bplist/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bplist/#see-also","title":"SEE ALSO","text":"bpclock(1)
"},{"location":"man/bpv6/bpnmtest/","title":"NAME","text":"bpnmtest - Bundle Protocol (BP) network management statistics test
"},{"location":"man/bpv6/bpnmtest/#synopsis","title":"SYNOPSIS","text":"bpnmtest
"},{"location":"man/bpv6/bpnmtest/#description","title":"DESCRIPTION","text":"bpnmtest simply prints to stdout messages containing the current values of all BP network management tallies, then terminates.
"},{"location":"man/bpv6/bpnmtest/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpnmtest has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bpnmtest/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpnmtest/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bprc/","title":"NAME","text":"bprc - Bundle Protocol management commands file
"},{"location":"man/bpv6/bprc/#description","title":"DESCRIPTION","text":"Bundle Protocol management commands are passed to bpadmin either in a file of text lines or interactively at bpadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the Bundle Protocol management commands are described below.
"},{"location":"man/bpv6/bprc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 bpadmin 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 and the crypto suite BP was compiled with. HINT: combine with e 1 command to log the version number at startup.
1
The initialize command. Until this command is executed, Bundle Protocol is not in operation on the local ION node and most bpadmin commands will fail.
r 'command_text'
The run command. This command will execute command_text as if it had been typed at a console prompt. It is used to, for example, run another administrative program.
s
The start command. This command starts all schemes and all protocols on the local node.
m heapmax max_database_heap_per_acquisition
The manage heap for bundle acquisition command. This command declares the maximum number of bytes of SDR heap space that will be occupied by any single bundle acquisition activity (nominally the acquisition of a single bundle, but this is at the discretion of the convergence-layer input task). All data acquired in excess of this limit will be written to a temporary file pending extraction and dispatching of the acquired bundle or bundles. 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.
m maxcount max_value_of_bundle_ID_sequence_nbr
The manage maximum bundle ID sequence number command. This command sets the maximum value that will be assigned as the sequence number in a bundle ID for any bundle sourced at a node that lacks a synchronized clock (such that the creation time in the ID of every locally sourced bundle is always zero). The default value is -1, i.e., unlimited.
x
The stop command. This command stops all schemes and all protocols on the local node.
w { 0 | 1 | activity_spec }
The BP watch command. This command enables and disables production of a continuous stream of user-selected Bundle Protocol activity indication characters. A watch parameter of \"1\" selects all BP activity indication characters; \"0\" de-selects all BP activity indication characters; any other activity_spec such as \"acz~\" selects all activity indication characters in the string, de-selecting all others. BP will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
a new bundle is queued for forwarding
b bundle is queued for transmission
c bundle is popped from its transmission queue
m custody acceptance signal is received
w custody of bundle is accepted
x custody of bundle is refused
y bundle is accepted upon arrival
z bundle is queued for delivery to an application
~ bundle is abandoned (discarded) on attempt to forward it
! bundle is destroyed due to TTL expiration
& custody refusal signal is received
# bundle is queued for re-forwarding due to CL protocol failure
j bundle is placed in \"limbo\" for possible future re-forwarding
k bundle is removed from \"limbo\" and queued for re-forwarding
$ bundle's custodial retransmission timeout interval expired
Note that a slightly amended interpretation should be applied to watch characters printed in the course of multicast transmission. The '~' character, meaning Abandoned (node did not forward this bundle), is printed by a node that is a leaf of the multicast tree, i.e., a node with no children; it cannot forward the bundle because it's got nobody to forward it to. The '!' character, meaning Destroyed (node destroyed a physical copy of a bundle), is printed by a node that has forwarded copies of the bundle to all of its children and no longer needs to retain the original - so it does an immediate permanent bundle destruction just as if the bundle's time to live had expired. Neither condition is anomalous.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a scheme scheme_name 'forwarder_command' 'admin_app_command'
The add scheme command. This command declares an endpoint naming \"scheme\" for use in endpoint IDs, which are structured as URIs: scheme_name:scheme-specific_part. forwarder_command will be executed when the scheme is started on this node, to initiate operation of a forwarding daemon for this scheme. admin_app_command will also be executed when the scheme is started on this node, to initiate operation of a daemon that opens a custodian endpoint identified within this scheme so that it can receive and process custody signals and bundle status reports.
c scheme scheme_name 'forwarder_command' 'admin_app_command'
The change scheme command. This command sets the indicated scheme's forwarder_command and admin_app_command to the strings provided as arguments.
d scheme scheme_name
The delete scheme command. This command deletes the scheme identified by scheme_name. The command will fail if any bundles identified in this scheme are pending forwarding, transmission, or delivery.
i scheme scheme_name
This command will print information (number and commands) about the endpoint naming scheme identified by scheme_name.
l scheme
This command lists all declared endpoint naming schemes.
s scheme scheme_name
The start scheme command. This command starts the forwarder and administrative endpoint tasks for the indicated scheme task on the local node.
x scheme scheme_name
The stop scheme command. This command stops the forwarder and administrative endpoint tasks for the indicated scheme task on the local node.
a endpoint endpoint_ID { q | x } ['recv_script']
The add endpoint command. This command establishes a DTN endpoint named endpoint_ID on the local node. The remaining parameters indicate what is to be done when bundles destined for this endpoint arrive at a time when no application has got the endpoint open for bundle reception. If 'x', then such bundles are to be discarded silently and immediately. If 'q', then such bundles are to be enqueued for later delivery and, if recv_script is provided, recv_script is to be executed.
c endpoint endpoint_ID { q | x } ['recv_script']
The change endpoint command. This command changes the action that is to be taken when bundles destined for this endpoint arrive at a time when no application has got the endpoint open for bundle reception, as described above.
d endpoint endpoint_ID
The delete endpoint command. This command deletes the endpoint identified by endpoint_ID. The command will fail if any bundles are currently pending delivery to this endpoint.
i endpoint endpoint_ID
This command will print information (disposition and script) about the endpoint identified by endpoint_ID.
l endpoint
This command lists all local endpoints, regardless of scheme name.
a protocol protocol_name payload_bytes_per_frame overhead_bytes_per_frame [protocol_class]
The add protocol command. This command establishes access to the named convergence layer protocol at the local node. The payload_bytes_per_frame and overhead_bytes_per_frame arguments are used in calculating the estimated transmission capacity consumption of each bundle, to aid in route computation and congestion forecasting.
The optional protocol_class argument indicates the reliability of the protocol. The value 1 indicates that the protocol natively supports bundle streaming; currently the only protocol in class 1 is BSSP. The value 2 indicates that the protocol performs no retransmission; an example is UDP. The value 8 (which is the default) indicates that the protocol detects data loss and automatically retransmits data accordingly; an example is TCP. Protocol class need not be specified when protocol_name is bssp, udp, tcp, stcp, brss, brsc, or ltp, as the protocol classes for these well-known protocols are hard-coded in ION.
d protocol protocol_name
The delete protocol command. This command deletes the convergence layer protocol identified by protocol_name. The command will fail if any ducts are still locally declared for this protocol.
i protocol protocol_name
This command will print information about the convergence layer protocol identified by protocol_name.
l protocol
This command lists all convergence layer protocols that can currently be utilized at the local node.
s protocol protocol_name
The start protocol command. This command starts all induct and outduct tasks for inducts and outducts that have been defined for the indicated CL protocol on the local node.
x protocol protocol_name
The stop protocol command. This command stops all induct and outduct tasks for inducts and outducts that have been defined for the indicated CL protocol on the local node.
a induct protocol_name duct_name 'CLI_command'
The add induct command. This command establishes a \"duct\" for reception of bundles via the indicated CL protocol. The duct's data acquisition structure is used and populated by the \"induct\" task whose operation is initiated by CLI_command at the time the duct is started.
c induct protocol_name duct_name 'CLI_command'
The change induct command. This command changes the command that is used to initiate operation of the induct task for the indicated duct.
d induct protocol_name duct_name
The delete induct command. This command deletes the induct identified by protocol_name and duct_name. The command will fail if any bundles are currently pending acquisition via this induct.
i induct protocol_name duct_name
This command will print information (the CLI command) about the induct identified by protocol_name and duct_name.
l induct [protocol_name]
If protocol_name is specified, this command lists all inducts established locally for the indicated CL protocol. Otherwise it lists all locally established inducts, regardless of protocol.
s induct protocol_name duct_name
The start induct command. This command starts the indicated induct task as defined for the indicated CL protocol on the local node.
x induct protocol_name duct_name
The stop induct command. This command stops the indicated induct task as defined for the indicated CL protocol on the local node.
a outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The add outduct command. This command establishes a \"duct\" for transmission of bundles via the indicated CL protocol. The duct's data transmission structure is serviced by the \"outduct\" task whose operation is initiated by CLO_command at the time the duct is started. A value of zero for max_payload_length indicates that bundles of any size can be accommodated; this is the default.
c outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The change outduct command. This command sets new values for the indicated duct's payload size limit and the command that is used to initiate operation of the outduct task for this duct.
d outduct protocol_name duct_name
The delete outduct command. This command deletes the outduct identified by protocol_name and duct_name. The command will fail if any bundles are currently pending transmission via this outduct.
i outduct protocol_name duct_name
This command will print information (the CLO command) about the outduct identified by protocol_name and duct_name.
l outduct [protocol_name]
If protocol_name is specified, this command lists all outducts established locally for the indicated CL protocol. Otherwise it lists all locally established outducts, regardless of protocol.
s outduct protocol_name duct_name
The start outduct command. This command starts the indicated outduct task as defined for the indicated CL protocol on the local node.
x outduct protocol_name duct_name
The stop outduct command. This command stops the indicated outduct task as defined for the indicated CL protocol on the local node.
a plan endpoint_name [transmission_rate]
The add plan command. This command establishes an egress plan governing transmission to the neighboring node[s] identified by endpoint_name. The plan is functionally enacted by a bpclm(1) daemon dedicated to managing bundles queued for transmission to the indicated neighboring node[s].
NOTE that these \"plan\" commands supersede and generalize the egress plan commands documented in the ipnrc(5) and dtn2rc(5) man pages, which are retained for backward compatibility. The syntax of the egress plan commands consumed by bpadmin is DIFFERENT from that of the commands consumed by ipnadmin and dtn2admin. The endpoint_name identifying an egress plan is normally the node ID for a single node but may instead be \"wild-carded\". That is, when the last character of an endpoint name ID is either '*' or '~' (these two wild-card characters are equivalent for this purpose), the plan applies to all nodes whose IDs are identical to the wild-carded node name up to the wild-card character. For example, a bundle whose destination EID name is \"dtn://foghorn\" would be routed by plans citing the following node IDs: \"dtn://foghorn\", \"dtn://fogh*\", \"dtn://fog~\", \"//*\". When multiple plans are all applicable to the same destination EID, the one citing the longest (i.e., most narrowly targeted) node ID will be applied.
An egress plan may direct that bundles queued for transmission to the node[s] matching endpoint_name be transmitted using one of the convergence-layer protocol \"outducts\" that have been attached to the plan, or instead that those bundles be routed to some other \"gateway\" endpoint (resulting in transmission according to some other egress plan). In the event that both a gateway endpoint and one or more outducts have been declared for a given plan, the gateway declaration prevails.
A transmission_rate may be asserted for an egress plan; this rate is used as the basis for transmission rate control in the absence of applicable contacts (in the node's contact plan, as per ionrc(5)). A transmission rate of zero (absent applicable contacts) disables rate control completely; this is the default.
c plan endpoint_name [transmission_rate]
The change plan command. This command sets a new value for the indicated plan's transmission rate.
d plan endpoint_name
The delete plan command. This command deletes the outduct identified by endpoint_name. The command will fail if any bundles are currently pending transmission per this plan.
i plan endpoint_name
This command will print information (the transmission rate) about the plan identified by endpoint_name.
l plan
This command lists all locally established egress plans.
s plan endpoint_name
The start plan command. This command starts the bpclm(1) task for the indicated egress plan.
x plan endpoint_name
The stop plan command. This command stops the bpclm(1) task for the indicated egress plan.
b plan endpoint_name
The block plan command. This command disables transmission of bundles queued for transmission to the indicated node and reforwards all non-critical bundles currently queued for transmission to this node. This may result in some or all of these bundles being enqueued for transmission (actually just retention) to the pseudo-node \"limbo\".
u plan endpoint_name
The unblock plan command. This command re-enables transmission of bundles to the indicated node and reforwards all bundles in \"limbo\" in the hope that the unblocking of this egress plan will enable some of them to be transmitted.
g plan endpoint_name gateway_endpoint_name
The declare gateway command. This command declares the name of the endpoint to which bundles queued for transmission to the node[s] identified by endpoint_name must be re-routed. Declaring gateway_endpoint_name to be the zero-length string \"''\" disables re-routing: bundles will instead be transmitted using the plan's attached convergence-layer protocol outduct[s].
a planduct endpoint_name protocol_name duct_name
The attach outduct command. This command declares that the indicated convergence-layer protocol outduct is now a viable device for transmitting bundles to the node[s] identified by endpoint_name.
d planduct protocol_name duct_name
The detach outduct command. This command declares that the indicated convergence-layer protocol outduct is no longer a viable device for transmitting bundles to the node[s] to which it is currently assigned.
a scheme ipn 'ipnfw' 'ipnadminep'
Declares the \"ipn\" scheme on the local node.
a protocol udp 1400 100 16384
Establishes access to the \"udp\" convergence layer protocol on the local node, estimating the number of payload bytes per ultimate (lowest-layer) frame to be 1400 with 100 bytes of total overhead (BP, UDP, IP, AOS) per lowest-layer frame, and setting the default nominal data rate to be 16384 bytes per second.
r 'ipnadmin flyby.ipnrc'
Runs the administrative program ipnadmin from within bpadmin.
bpadmin(1), ipnadmin(1), dtn2admin(1)
"},{"location":"man/bpv6/bprecvfile/","title":"NAME","text":"bprecvfile - Bundle Protocol (BP) file reception utility
"},{"location":"man/bpv6/bprecvfile/#synopsis","title":"SYNOPSIS","text":"bprecvfile own_endpoint_ID [max_files]
"},{"location":"man/bpv6/bprecvfile/#description","title":"DESCRIPTION","text":"bprecvfile is intended to serve as the counterpart to bpsendfile. It uses bp_receive() to receive bundles containing file content. The content of each bundle is simply written to a file named \"testfileN\" where N is the total number of bundles received since the program began running.
If a max_files value of N (where N > 0) is provided, the program will terminate automatically upon completing its Nth file reception. Otherwise it will run indefinitely; use ^C to terminate the program.
"},{"location":"man/bpv6/bprecvfile/#exit-status","title":"EXIT STATUS","text":"\"0\"
bprecvfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bprecvfile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bprecvfile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
bprecvfile bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't open test file
File system error. bprecvfile terminates.
bprecvfile: can't receive bundle content.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't write to test file
File system error. bprecvfile terminates.
bprecvfile cannot continue.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't handle bundle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bprecvfile/#see-also","title":"SEE ALSO","text":"bpsendfile(1), bp(3)
"},{"location":"man/bpv6/bpsecadmin/","title":"NAME","text":"bpsecadmin - BP security policy administration interface
"},{"location":"man/bpv6/bpsecadmin/#synopsis","title":"SYNOPSIS","text":"bpsecadmin [ commands_filename ]
"},{"location":"man/bpv6/bpsecadmin/#description","title":"DESCRIPTION","text":"bpsecadmin configures and manages BP security policy on the local computer.
It configures and manages BP security policy on the local computer in response to BP configuration commands found in commands_filename, if provided; if not, bpsecadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from bpsecadmin by entering the command 'h' or '?' at the prompt. The commands are documented in bpsecrc(5).
"},{"location":"man/bpv6/bpsecadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of BP security policy administration.
bpsecadmin
Enter interactive ION security policy administration command entry mode.
bpsecadmin host1.bpsecrc
Execute all configuration commands in host1.bpsecrc, then terminate immediately.
Status and diagnostic messages from bpsecadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which bpsecadmin was run. The log file is typically named ion.log.
See also bpsecrc(5).
"},{"location":"man/bpv6/bpsecadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpsecadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bpsecadmin. Otherwise bpsecadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bpsecadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see bpsecrc(5) for details.
"},{"location":"man/bpv6/bpsecadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpsecadmin/#see-also","title":"SEE ALSO","text":"bpsecrc(5)
"},{"location":"man/bpv6/bpsecrc/","title":"NAME","text":"bpsecrc - BP security policy management commands file
"},{"location":"man/bpv6/bpsecrc/#description","title":"DESCRIPTION","text":"BP security policy management commands are passed to bpsecadmin either in a file of text lines or interactively at bpsecadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the BP security policy management commands are described below.
A parameter identifed as an eid_expr is an \"endpoint ID expression.\" For all commands, whenever the last character of an endpoint ID expression is the wild-card character '*', an applicable endpoint ID \"matches\" this EID expression if all characters of the endpoint ID expression prior to the last one are equal to the corresponding characters of that endpoint ID. Otherwise an applicable endpoint ID \"matches\" the EID expression only when all characters of the EID and EID expression are identical.
ION supports the proposed \"streamlined\" Bundle Security Protocol (currently posted as CCSDS Red Book 734.5-R-1) in place of the standard Bundle Security Protocol (RFC 6257). Since SBSP is not yet a published standard, ION's Bundle Protocol security mechanisms will not necessarily interoperate with those of other BP implementations. This is unfortunate but (we hope) temporary, as SBSP represents a major improvement in bundle security. It is possible that the SBSP specification will change somewhat between now and the time SBSP is published as a CCSDS standard and eventually an RFC, and ION will be revised as necessary to conform to those changes, but in the meantime we believe that the advantages of SBSP make it more suitable than RFC 6257 as a foundation for the development and deployment of secure DTN applications.
"},{"location":"man/bpv6/bpsecrc/#commands","title":"COMMANDS","text":"?
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 bpsecadmin 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.
a bspbibrule source_eid_expr destination_eid_expr block_type_number { '' | ciphersuite_name key_name }
The add bspbibrule command. This command adds a rule specifying the manner in which Block Integrity Block (BIB) validation will be applied to blocks of type block_type_number for all bundles sourced at any node whose administrative endpoint ID matches source_eid_expr and destined for any node whose administrative endpoint ID ID matches destination_eid_expr.
If a zero-length string ('') is indicated instead of a ciphersuite_name then BIB validation is disabled for this source/destination EID expression pair: blocks of the type indicated by block_type_number in all bundles sourced at nodes with matching administrative endpoint IDs and destined for nodes with matching administrative endpoint IDs will be immediately deemed valid. Otherwise, a block of the indicated type that is attached to a bundle sourced at a node with matching administrative endpoint ID and destined for a node with matching administrative endpoint ID will only be deemed valid if the bundle contains a corresponding BIB computed via the ciphersuite named by ciphersuite_name using a key value that is identical to the current value of the key named key_name in the local security policy database.
c bspbibrule source_eid_expr destination_eid_expr block_type_number { '' | ciphersuite_name key_name }
The change bspbibrule command. This command changes the ciphersuite name and/or key name for the BIB rule pertaining to the source/destination EID expression pair identified by source_eid_expr and destination_eid_expr and the block identified by block_type_number. Note that the _eid_expr_s must exactly match those of the rule that is to be modified, including any terminating wild-card character.
d bspbibrule source_eid_expr destination_eid_expr block_type_number
The delete bspbibrule command. This command deletes the BIB rule pertaining to the source/destination EID expression pair identified by sender_eid_expr and receiver_eid_expr and the block identified by block_type_number. Note that the _eid_expr_s must exactly match those of the rule that is to be deleted, including any terminating wild-card character.
i bspbibrule source_eid_expr destination_eid_expr block_type_number
This command will print information (the ciphersuite and key names) about the BIB rule pertaining to source_eid_expr, destination_eid_expr, and block_type_number.
l bspbibrule
This command lists all BIB rules in the security policy database.
a bspbcbrule source_eid_expr destination_eid_expr block_type_number { '' | ciphersuite_name key_name }
The add bspbcbrule command. This command adds a rule specifying the manner in which Block Confidentiality Block (BCB) encryption will be applied to blocks of type block_type_number for all bundles sourced at any node whose administrative endpoint ID matches source_eid_expr and destined for any node whose administrative endpoint ID ID matches destination_eid_expr.
If a zero-length string ('') is indicated instead of a ciphersuite_name then BCB encryption is disabled for this source/destination EID expression pair: blocks of the type indicated by block_type_number in all bundles sourced at nodes with matching administrative endpoint IDs and destined for nodes with matching administrative endpoint IDs will be sent in plain text. Otherwise, a block of the indicated type that is attached to a bundle sourced at a node with matching administrative endpoint ID and destined for a node with matching administrative endpoint ID can only be deemed decrypted if the bundle contains a corresponding BCB computed via the ciphersuite named by ciphersuite_name using a key value that is identical to the current value of the key named key_name in the local security policy database.
c bspbcbrule source_eid_expr destination_eid_expr block_type_number { '' | ciphersuite_name key_name }
The change bspbcbrule command. This command changes the ciphersuite name and/or key name for the BCB rule pertaining to the source/destination EID expression pair identified by source_eid_expr and destination_eid_expr and the block identified by block_type_number. Note that the _eid_expr_s must exactly match those of the rule that is to be modified, including any terminating wild-card character.
d bspbcbrule source_eid_expr destination_eid_expr block_type_number
The delete bspbcbrule command. This command deletes the BCB rule pertaining to the source/destination EID expression pair identified by sender_eid_expr and receiver_eid_expr and the block identified by block_type_number. Note that the _eid_expr_s must exactly match those of the rule that is to be deleted, including any terminating wild-card character.
i bspbcbrule source_eid_expr destination_eid_expr block_type_number
This command will print information (the ciphersuite and key names) about the BCB rule pertaining to source_eid_expr, destination_eid_expr, and block_type_number.
l bspbcbrule
This command lists all BCB rules in the security policy database.
x [ { ~ | sender_eid_expr } [ { ~ | receiver_eid_expr} [ { ~ | bib | bcb } ] ] ]
This command will clear all rules for the indicated type of bundle security block between the indicated security source and security destination. If block type is omitted it defaults to ~ signifying \"all SBSP blocks\". If both block type and security destination are omitted, security destination defaults to ~ signifying \"all SBSP security destinations\". If all three command-line parameters are omitted, then security source defaults to ~ signifying \"all SBSP security sources\".
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
bpsecadmin(1)
"},{"location":"man/bpv6/bpsendfile/","title":"NAME","text":"bpsendfile - Bundle Protocol (BP) file transmission utility
"},{"location":"man/bpv6/bpsendfile/#synopsis","title":"SYNOPSIS","text":"bpsendfile own_endpoint_ID destination_endpoint_ID file_name [class_of_service [time_to_live (seconds) ]]
"},{"location":"man/bpv6/bpsendfile/#description","title":"DESCRIPTION","text":"bpsendfile uses bp_send() to issue a single bundle to a designated destination endpoint, containing the contents of the file identified by file_name, then terminates. The bundle is sent with no custody transfer requested. When class_of_service is omitted, the bundle is sent at standard priority; for details of the class_of_service parameter, see bptrace(1). time_to_live, if not specified, defaults to 300 seconds (5 minutes). NOTE that time_to_live is specified AFTER class_of_service, rather than before it as in bptrace(1).
"},{"location":"man/bpv6/bpsendfile/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsendfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bpsendfile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpsendfile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
Can't stat the file
Operating system error. Check errtext, correct problem, and rerun.
bpsendfile can't create file ref.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpsendfile can't create ZCO.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpsendfile can't send file in bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpsendfile/#see-also","title":"SEE ALSO","text":"bprecvfile(1), bp(3)
"},{"location":"man/bpv6/bpsink/","title":"NAME","text":"bpsink - Bundle Protocol reception test program
"},{"location":"man/bpv6/bpsink/#synopsis","title":"SYNOPSIS","text":"bpsink ownEndpointId
"},{"location":"man/bpv6/bpsink/#description","title":"DESCRIPTION","text":"bpsink uses Bundle Protocol to receive application data units from a remote bpsource application task. For each application data unit it receives, it prints the ADU's length and -- if length is less than 80 -- its text.
bpsink terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv6/bpsink/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsink has terminated. Any problems encountered during operation will be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv6/bpsink/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpsink/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpsink are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpsink bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't receive payload.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't handle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpsink/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpsource(1), bp(3)
"},{"location":"man/bpv6/bpsource/","title":"NAME","text":"bpsource - Bundle Protocol transmission test shell
"},{"location":"man/bpv6/bpsource/#synopsis","title":"SYNOPSIS","text":"bpsource destinationEndpointId [\"text\"] [-t_TTL_]
"},{"location":"man/bpv6/bpsource/#description","title":"DESCRIPTION","text":"When text is supplied, bpsource simply uses Bundle Protocol to send text to a counterpart bpsink application task that has opened the BP endpoint identified by destinationEndpointId, then terminates.
Otherwise, bpsource offers the user an interactive \"shell\" for testing Bundle Protocol data transmission. bpsource prints a prompt string (\": \") to stdout, accepts a string of text from stdin, uses Bundle Protocol to send the string to a counterpart bpsink application task that has opened the BP endpoint identified by destinationEndpointId, then prints another prompt string and so on. To terminate the program, enter a string consisting of a single exclamation point (!) character.
TTL indicates the number of seconds the bundles may remain in the network, undelivered, before they are automatically destroyed. If omitted, TTL defaults to 300 seconds.
The source endpoint ID for each bundle sent by bpsource is the null endpoint ID, i.e., the bundles are anonymous. All bundles are sent standard priority with no custody transfer and no status reports requested.
"},{"location":"man/bpv6/bpsource/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsource has terminated. Any problems encountered during operation will be noted in the ion.log log file.
The service data units transmitted by bpsource are sequences of text obtained from a file in the current working directory named \"bpsourceAduFile\", which bpsource creates automatically.
"},{"location":"man/bpv6/bpsource/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpsource/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpsource are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
bpsource fgets failed
Operating system error. Check errtext, correct problem, and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpsource can't send ADU
Bundle Protocol service to the remote endpoint has been stopped.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpsource/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpsink(1), bp(3)
"},{"location":"man/bpv6/bpstats/","title":"NAME","text":"bpstats - Bundle Protocol (BP) processing statistics query utility
"},{"location":"man/bpv6/bpstats/#synopsis","title":"SYNOPSIS","text":"bpstats
"},{"location":"man/bpv6/bpstats/#description","title":"DESCRIPTION","text":"bpstats simply logs messages containing the current values of all BP processing statistics accumulators, then terminates.
"},{"location":"man/bpv6/bpstats/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpstats has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bpstats/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpstats/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpstats can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpstats/#see-also","title":"SEE ALSO","text":"ion(3)
"},{"location":"man/bpv6/bpstats2/","title":"NAME","text":"bpstats2 - Bundle Protocol (BP) processing statistics query utility via bundles
"},{"location":"man/bpv6/bpstats2/#synopsis","title":"SYNOPSIS","text":"bpstats2 sourceEID [default destEID] [ct]
"},{"location":"man/bpv6/bpstats2/#description","title":"DESCRIPTION","text":"bpstats2 creates bundles containing the current values of all BP processing statistics accumulators. It creates these bundles when:
\"0\"
bpstats2 has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpstats2 failed to start up or receive bundles. Diagnose the issue reported in the ion.log file and try again.
If the string \"ct\" is appended as the last argument, then statistics bundles will be sent with custody transfer requested.
No configuration files are needed.
"},{"location":"man/bpv6/bpstats2/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpstats2/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpstats2 can't bp_attach().
bpadmin has not yet initialized BP operations.
bpstats2 can't open own endpoint.
Another BP application has opened that endpoint; close it and try again.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpstats2 can't send stats bundle.
Bundle Protocol service to the remote endpoint has been stopped.
Can't send stats: bad dest EID (dest EID)
The destination EID printed is an invalid destination EID. The destination EID may be specified in default destEID or the source EID of the interrogation bundle. Ensure that default destEID is an EID that is valid for ION, and that the interrogator is a source EID that is also a valid destination EID. Note that \"dtn:none\" is not a valid destination EID, but is a valid source EID.
A very simple interrogator is bpchat which can repeatedly interrogate bpstats2 by just striking the enter key.
"},{"location":"man/bpv6/bpstats2/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpstats2/#see-also","title":"SEE ALSO","text":"bpstats(1), bpchat(1)
"},{"location":"man/bpv6/bptrace/","title":"NAME","text":"bptrace - Bundle Protocol (BP) network trace utility
"},{"location":"man/bpv6/bptrace/#synopsis","title":"SYNOPSIS","text":"bptrace own_endpoint_ID destination_endpoint_ID report-to_endpoint_ID TTL class_of_service \"trace_text\" [status_report_flags]
"},{"location":"man/bpv6/bptrace/#description","title":"DESCRIPTION","text":"bptrace uses bp_send() to issue a single bundle to a designated destination endpoint, with status reporting options enabled as selected by the user, then terminates. The status reports returned as the bundle makes its way through the network provide a view of the operation of the network as currently configured.
TTL indicates the number of seconds the trace bundle may remain in the network, undelivered, before it is automatically destroyed.
class_of_service is custody-requested.priority[.ordinal[.unreliable.critical[.data-label]]], where custody-requested must be 0 or 1 (Boolean), priority must be 0 (bulk) or 1 (standard) or 2 (expedited), ordinal must be 0-254, unreliable must be 0 or 1 (Boolean), critical must also be 0 or 1 (Boolean), and data-label may be any unsigned integer. ordinal is ignored if priority is not 2. Setting class_of_service to \"0.2.254\" or \"1.2.254\" gives a bundle the highest possible priority. Setting unreliable to 1 causes BP to forego retransmission in the event of data loss, both at the BP layer and at the convergence layer. Setting critical to 1 causes contact graph routing to forward the bundle on all plausible routes rather than just the \"best\" route it computes; this may result in multiple copies of the bundle arriving at the destination endpoint, but when used in conjunction with priority 2.254 it ensures that the bundle will be delivered as soon as physically possible.
trace_text can be any string of ASCII text; alternatively, if we want to send a file, it can be \"@\" followed by the file name.
status_report_flags must be a sequence of status report flags, separated by commas, with no embedded whitespace. Each status report flag must be one of the following: rcv, ct, fwd, dlv, del.
"},{"location":"man/bpv6/bptrace/#exit-status","title":"EXIT STATUS","text":"\"0\"
bptrace has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bptrace/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bptrace/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bptrace can't attach to BP.
bpadmin has not yet initialized BP operations.
bptrace can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
No space for bptrace text.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't create ZCO.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't send message.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bptrace/#see-also","title":"SEE ALSO","text":"bp(3)
"},{"location":"man/bpv6/bptransit/","title":"NAME","text":"bptransit - Bundle Protocol (BP) daemon task for forwarding received bundles
"},{"location":"man/bpv6/bptransit/#synopsis","title":"SYNOPSIS","text":"bptransit
"},{"location":"man/bpv6/bptransit/#description","title":"DESCRIPTION","text":"bptransit is a background \"daemon\" task that is responsible for presenting to ION's forwarding daemons any bundles that were received from other nodes (i.e., bundles whose payloads reside in Inbound ZCO space) and are destined for yet other nodes. In doing so, it migrates these bundles from Inbound buffer space to Outbound buffer space on the same prioritized basis as the insertion of locally sourced outbound bundles.
Management of the bptransit daemon is automatic. It is spawned automatically by bpadmin in response to the 's' command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command.
Whenever a received bundle is determined to have a destination other than the local node, a pointer to that bundle is appended to one of two queues of \"in-transit\" bundles, one for bundles whose forwarding is provisional (depending on the availability of Outbound ZCO buffer space; bundles in this queue are potentially subject to congestion loss) and one for bundles whose forwarding is confirmed. Bundles received via convergence-layer adapters that can sustain flow control, such as STCP, are appended to the \"confirmed\" queue, while those from CLAs that cannot sustain flow control (such as LTP) are appended to the \"provisional\" queue.
bptransit comprises two threads, one for each in-transit queue. The confirmed in-transit thread dequeues bundles from the \"confirmed\" queue and moves them from Inbound to Outbound ZCO buffer space, blocking (if necessary) until space becomes available. The provisional in-transit queue dequeues bundles from the \"provisional\" queue and moves them from Inbound to Outbound ZCO buffer space if Outbound space is available, discarding (\"abandoning\") them if it is not.
"},{"location":"man/bpv6/bptransit/#exit-status","title":"EXIT STATUS","text":"\"0\"
bptransit terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bptransit.
\"1\"
bptransit was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/bptransit/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bptransit/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bptransit can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bptransit/#see-also","title":"SEE ALSO","text":"bpadmin(1)
"},{"location":"man/bpv6/brsccla/","title":"NAME","text":"brsccla - BRSC-based BP convergence layer adapter (input and output) task
"},{"location":"man/bpv6/brsccla/#synopsis","title":"SYNOPSIS","text":"brsccla server_hostname[:server_port_nbr]_own_node_nbr
"},{"location":"man/bpv6/brsccla/#description","title":"DESCRIPTION","text":"BRSC is the \"client\" side of the Bundle Relay Service (BRS) convergence layer protocol for BP. It is complemented by BRSS, the \"server\" side of the BRS convergence layer protocol for BP. BRS clients send bundles directly only to the server, regardless of their final destinations, and the server forwards them to other clients as necessary.
brsccla is a background \"daemon\" task comprising three threads: one that connects to the BRS server, spawns the other threads, and then handles BRSC protocol output by transmitting bundles over the connected socket to the BRS server; one that simply sends periodic \"keepalive\" messages over the connected socket to the server (to assure that local inactivity doesn't cause the connection to be lost); and one that handles BRSC protocol input from the connected server.
The output thread connects to the server's TCP socket at server_hostname and server_port_nbr, sends over the connected socket the client's own_node_nbr (in SDNV representation) followed by a 32-bit time tag and a 160-bit HMAC-SHA1 digest of that time tag, to authenticate itself; checks the authenticity of the 160-bit countersign returned by the server; spawns the keepalive and receiver threads; and then begins extracting bundles from the queues of bundles ready for transmission via BRSC and transmitting those bundles over the connected socket to the server. Each transmitted bundle is preceded by its length, a 32-bit unsigned integer in network byte order. The default value for server_port_nbr, if omitted, is 80.
The reception thread receives bundles over the connected socket and passes them to the bundle protocol agent on the local ION node. Each bundle received on the connection is preceded by its length, a 32-bit unsigned integer in network byte order.
The keepalive thread simply sends a \"bundle length\" value of zero (a 32-bit unsigned integer in network byte order) to the server once every 15 seconds.
brsccla is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. brsccla can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BRSC convergence layer protocol.
"},{"location":"man/bpv6/brsccla/#exit-status","title":"EXIT STATUS","text":"\"0\"
brsccla terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSC protocol.
\"1\"
brsccla terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSC protocol.
No configuration files are needed.
"},{"location":"man/bpv6/brsccla/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/brsccla/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
brsccla can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such brsc induct.
No BRSC induct with duct name matching server_hostname, own_node_nbr, and server_port_nbr has been added to the BP database. Use bpadmin to stop the BRSC convergence-layer protocol, add the induct, and then restart the BRSC protocol.
CLI task is already started for this duct.
Redundant initiation of brsccla.
No such brsc outduct.
No BRSC outduct with duct name matching server_hostname, own_node_nbr, and server_port_nbr has been added to the BP database. Use bpadmin to stop the BRSC convergence-layer protocol, add the outduct, and then restart the BRSC protocol.
Can't connect to server.
Operating system error. Check errtext, correct problem, and restart BRSC.
Can't register with server.
Configuration error. Authentication has failed, probably because (a) the client and server are using different HMAC/SHA1 keys or (b) the clocks of the client and server differ by more than 5 seconds. Update security policy database(s), as necessary, and assure that the clocks are synchronized.
brsccla can't create receiver thread
Operating system error. Check errtext, correct problem, and restart BRSC.
brsccla can't create keepalive thread
Operating system error. Check errtext, correct problem, and restart BRSC.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/brsccla/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), brsscla(1)
"},{"location":"man/bpv6/brsscla/","title":"NAME","text":"brsscla - BRSS-based BP convergence layer adapter (input and output) task
"},{"location":"man/bpv6/brsscla/#synopsis","title":"SYNOPSIS","text":"brsscla local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/brsscla/#description","title":"DESCRIPTION","text":"BRSS is the \"server\" side of the Bundle Relay Service (BRS) convergence layer protocol for BP. It is complemented by BRSC, the \"client\" side of the BRS convergence layer protocol for BP.
brsscla is a background \"daemon\" task that spawns 2*N threads: one that handles BRSS client connections and spawns sockets for continued data interchange with connected clients; one that handles BRSS protocol output by transmitting over those spawned sockets to the associated clients; and two thread for each spawned socket, an input thread to handle BRSS protocol input from the associated connected client and an output thread to forward BRSS protocol output to the associated connected client.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 80.
Each reception thread receives over the socket connection the node number of the connecting client (in SDNV representation), followed by a 32-bit time tag and a 160-bit HMAC-SHA1 digest of that time tag. The receiving thread checks the time tag, requiring that it differ from the current time by no more than BRSTERM (default value 5) seconds. It then recomputes the digest value using the HMAC-SHA1 key named \"node_number.brs\" as recorded in the ION security database (see ionsecrc(5)), requiring that the supplied and computed digests be identical. If all registration conditions are met, the receiving thread sends the client a countersign -- a similarly computed HMAC-SHA1 digest, for the time tag that is 1 second later than the provided time tag -- to assure the client of its own authenticity, then commences receiving bundles over the connected socket. Each bundle received on the connection is preceded by its length, a 32-bit unsigned integer in network byte order. The received bundles are passed to the bundle protocol agent on the local ION node.
Each output thread extracts bundles from the queues of bundles ready for transmission via BRSS to the corresponding connected client and transmits the bundles over the socket to that client. Each transmitted bundle is preceded by its length, a 32-bit unsigned integer in network byte order.
brsscla is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. brsscla can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BRSS convergence layer protocol.
"},{"location":"man/bpv6/brsscla/#exit-status","title":"EXIT STATUS","text":"\"0\"
brsscla terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSS protocol.
\"1\"
brsscla terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSS protocol.
No configuration files are needed.
"},{"location":"man/bpv6/brsscla/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/brsscla/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
brsscla can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such brss induct.
No BRSS induct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the BRSS convergence-layer protocol, add the induct, and then restart the BRSS protocol.
CLI task is already started for this duct.
Redundant initiation of brsscla.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart BRSS.
Can't open TCP socket
Operating system error -- unable to open TCP socket for accepting connections. Check errtext, correct problem, and restart BRSS.
Can't initialize socket (note: must be root for port 80)
Operating system error. Check errtext, correct problem, and restart BRSS.
brsscla can't create sender thread
Operating system error. Check errtext, correct problem, and restart BRSS.
brsscla can't create access thread
Operating system error. Check errtext, correct problem, and restart BRSS.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/brsscla/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), brsccla(1)
"},{"location":"man/bpv6/cgrfetch/","title":"NAME","text":"cgrfetch - Visualize CGR simulations
"},{"location":"man/bpv6/cgrfetch/#synopsis","title":"SYNOPSIS","text":"cgrfetch [OPTIONS] DEST-NODE
"},{"location":"man/bpv6/cgrfetch/#description","title":"DESCRIPTION","text":"cgrfetch uses CGR to simulate sending a bundle from the local node to DEST-NODE. It traces the execution of CGR to generate graphs of the routes that were considered and the routes that were ultimately chosen to forward along. No bundle is sent during the simulation.
A JSON representation of the simulation is output to OUTPUT-FILE. The representation includes parameters of the simulation and a structure for each considered route, which in turn includes calculated parameters for the route and an image of the contact graph.
The dot(1) tool from the Graphviz package is used to generate the contact graph images and is required for cgrfetch(1). The base64(1) tool from coreutils is used to embed the images in the JSON and is also required.
Note that a trace of the route computation logic performed by CGR is printed to stderr; there is currently no cgrfetch option for redirecting this output to a file.
"},{"location":"man/bpv6/cgrfetch/#options","title":"OPTIONS","text":"DEST-NODE
The final destination to route to. To be useful, it should be a node that exists in the contact plan.
-q
Disable trace message output.
-j
Disable JSON output.
-m
Use a minimum-latency extended COS for the bundle. This ends up sending the bundle to all proximate nodes.
-t DISPATCH-OFFSET
Request a dispatch time of DISPATCH-OFFSET seconds from the time the command is run (default: 0).
-e EXPIRATION-OFFSET
Set the bundle expiration time to EXPIRATION-OFFSET seconds from the time the command is run (default: 3600).
-s BUNDLE-SIZE
Set the bundle payload size to BUNDLE-SIZE bytes (default: 0).
-o OUTPUT-FILE
Send JSON to OUTPUT-FILE (default: stdout).
-d PROTO:NAME
Use PROTO as the outduct protocol and NAME as the outduct name (default: udp:*). Use list to list all available outducts.
cgrfetch 8
Simulate CGR with destination node 8 and dispatch time equal to the current time.
cgrfetch 8 -t 60
Do the same with a dispatch time 60 seconds in the future.
cgrfetch -d list
List all available outducts.
dot(1), base64(1)
"},{"location":"man/bpv6/dccpcli/","title":"NAME","text":"dccpcli - DCCP-based BP convergence layer input task
"},{"location":"man/bpv6/dccpcli/#synopsis","title":"SYNOPSIS","text":"dccpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/dccpcli/#description","title":"DESCRIPTION","text":"dccpcli is a background \"daemon\" task that receives DCCP datagrams via a DCCP socket bound to local_hostname and local_port_nbr, extracts bundles from those datagrams, and passes them to the bundle protocol agent on the local ION node.
If not specified, port number defaults to 4556.
Note that dccpcli has no fragmentation support at all. Therefore, the largest bundle that can be sent via this convergence layer is limited to just under the link's MTU (typically 1500 bytes).
The convergence layer input task is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"dccp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. dccpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DCCP convergence layer protocol.
"},{"location":"man/bpv6/dccpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dccpcli.
\"1\"
dccpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dccpcli.
No configuration files are needed.
"},{"location":"man/bpv6/dccpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dccpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such dccp duct.
No DCCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DCCP convergence-layer protocol, add the induct, and then restart the DCCP protocol.
CLI task is already started for this duct.
Redundant initiation of dccpcli.
dccpcli can't get IP address for host.
Operating system error. Check errtext, correct problem, and restart dccpcli.
CLI can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccpcli.
CLI can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccpcli.
dccpcli can't get acquisition work area.
ION system error. Check errtext, correct problem, and restart dccpcli.
dccpcli can't create new thread.
Operating system error. Check errtext, correct problem, and restart dccpcli.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dccpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), dccpclo(1)
"},{"location":"man/bpv6/dccpclo/","title":"NAME","text":"dccpclo - DCCP-based BP convergence layer output task
"},{"location":"man/bpv6/dccpclo/#synopsis","title":"SYNOPSIS","text":"dccpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/dccpclo/#description","title":"DESCRIPTION","text":"dccpclo is a background \"daemon\" task that connects to a remote node's DCCP socket at remote_hostname and remote_port_nbr. It then begins extracting bundles from the queues of bundles ready for transmission via DCCP to this remote bundle protocol agent and transmitting those bundles as DCCP datagrams to the remote host.
If not specified, remote_port_nbr defaults to 4556.
Note that dccpclo has no fragmentation support at all. Therefore, the largest bundle that can be sent via this convergence layer is limited to just under the link's MTU (typically 1500 bytes).
dccpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dccpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DCCP convergence layer protocol.
"},{"location":"man/bpv6/dccpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dccpclo.
\"1\"
dccpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dccpclo.
No configuration files are needed.
"},{"location":"man/bpv6/dccpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dccpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No memory for DCCP buffer in dccpclo.
ION system error. Check errtext, correct problem, and restart dccpclo.
No such dccp duct.
No DCCP outduct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DCCP convergence-layer protocol, add the outduct, and then restart dccpclo.
CLO task is already started for this duct.
Redundant initiation of dccpclo.
dccpclo can't get IP address for host.
Operating system error. Check errtext, correct problem, and restart dccpclo.
dccpclo can't create thread.
Operating system error. Check errtext, correct problem, and restart dccpclo.
CLO can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccpclo.
CLO can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccpclo.
CLO send() error on socket.
Operating system error. Check errtext, correct problem, and restart dccpclo.
Bundle is too big for DCCP CLO.
Configuration error: bundles that are too large for DCCP transmission (i.e., larger than the MTU of the link or 65535 bytes--whichever is smaller) are being enqueued for dccpclo. Change routing or use smaller bundles.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dccpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), dccpcli(1)
"},{"location":"man/bpv6/dgrcli/","title":"NAME","text":"dgrcli - DGR-based BP convergence layer reception task
"},{"location":"man/bpv6/dgrcli/#synopsis","title":"SYNOPSIS","text":"dgrcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/dgrcli/#description","title":"DESCRIPTION","text":"dgrcli is a background \"daemon\" task that handles DGR convergence layer protocol input.
The daemon receives DGR messages via a UDP socket bound to local_hostname and local_port_nbr, extracts bundles from those messages, and passes them to the bundle protocol agent on the local ION node. (local_port_nbr defaults to 1113 if not specified.)
dgrcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dgrcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DGR convergence layer protocol.
"},{"location":"man/bpv6/dgrcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgrcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dgrcli.
\"1\"
dgrcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dgrcli.
No configuration files are needed.
"},{"location":"man/bpv6/dgrcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dgrcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dgrcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such dgr induct.
No DGR induct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DGR convergence-layer protocol, add the induct, and then restart the DGR protocol.
CLI task is already started for this engine.
Redundant initiation of dgrcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart DGR.
dgrcli can't open DGR service access point.
DGR system error. Check prior messages in ion.log log file, correct problem, and then stop and restart the DGR protocol.
dgrcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart DGR.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dgrcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv6/dgrclo/","title":"NAME","text":"dgrclo - DGR-based BP convergence layer transmission task
"},{"location":"man/bpv6/dgrclo/#synopsis","title":"SYNOPSIS","text":"dgrclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/dgrclo/#description","title":"DESCRIPTION","text":"dgrclo is a background \"daemon\" task that spawns two threads, one that handles DGR convergence layer protocol input (positive and negative acknowledgments) and a second that handles DGR convergence layer protocol output.
The output thread extracts bundles from the queues of bundles ready for transmission via DGR to a remote bundle protocol agent, encapsulates them in DGR messages, and uses a randomly configured local UDP socket to send those messages to the remote UDP socket bound to remote_hostname and remote_port_nbr. (local_port_nbr defaults to 1113 if not specified.)
The input thread receives DGR messages via the same local UDP socket and uses them to manage DGR retransmission of transmitted datagrams.
dgrclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dgrclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DGR convergence layer protocol.
"},{"location":"man/bpv6/dgrclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgrclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dgrclo.
\"1\"
dgrclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dgrclo.
No configuration files are needed.
"},{"location":"man/bpv6/dgrclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dgrclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dgrclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
CLI task is already started for this engine.
Redundant initiation of dgrclo.
No such dgr outduct.
No DGR outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the DGR convergence-layer protocol, add the outduct, and then restart the DGR protocol.
dgrclo can't open DGR service access point.
DGR system error. Check prior messages in ion.log log file, correct problem, and then stop and restart the DGR protocol.
dgrclo can't create sender thread
Operating system error. Check errtext, correct problem, and restart DGR.
dgrclo can't create receiver thread
Operating system error. Check errtext, correct problem, and restart DGR.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dgrclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv6/dtn2admin/","title":"NAME","text":"dtn2admin - baseline \"dtn\" scheme administration interface
"},{"location":"man/bpv6/dtn2admin/#synopsis","title":"SYNOPSIS","text":"dtn2admin [ commands_filename ]
"},{"location":"man/bpv6/dtn2admin/#description","title":"DESCRIPTION","text":"dtn2admin configures the local ION node's routing of bundles to endpoints whose IDs conform to the dtn endpoint ID scheme. dtn is a non-CBHE-conformant scheme. The structure of dtn endpoint IDs remains somewhat in flux at the time of this writing, but endpoint IDs in the dtn scheme historically have been strings of the form \"dtn://node_name[/demux_token]\", where node_name normally identifies a computer somewhere on the network and demux_token normally identifies a specific application processing point. Although the dtn endpoint ID scheme imposes more transmission overhead than the ipn scheme, ION provides support for dtn endpoint IDs to enable interoperation with other implementations of Bundle Protocol.
dtn2admin operates in response to \"dtn\" scheme configuration commands found in the file commands_filename, if provided; if not, dtn2admin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from dtn2admin with the 'h' or '?' commands at the prompt. The commands are documented in dtn2rc(5).
"},{"location":"man/bpv6/dtn2admin/#exit-status","title":"EXIT STATUS","text":"dtn2admin
Enter interactive \"dtn\" scheme configuration command entry mode.
dtn2admin host1.dtn2rc
Execute all configuration commands in host1.dtn2rc, then terminate immediately.
See dtn2rc(5) for details of the DTN scheme configuration commands.
"},{"location":"man/bpv6/dtn2admin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dtn2admin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the dtn2rc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to dtn2admin. Otherwise dtn2admin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
dtn2admin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
dtn2admin can't initialize routing database.
There is no SDR data store for dtn2admin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause dtn2admin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see dtn2rc(5) for details.
"},{"location":"man/bpv6/dtn2admin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dtn2admin/#see-also","title":"SEE ALSO","text":"dtn2rc(5)
"},{"location":"man/bpv6/dtn2adminep/","title":"NAME","text":"dtn2adminep - administrative endpoint task for the \"dtn\" scheme
"},{"location":"man/bpv6/dtn2adminep/#synopsis","title":"SYNOPSIS","text":"dtn2adminep
"},{"location":"man/bpv6/dtn2adminep/#description","title":"DESCRIPTION","text":"dtn2adminep is a background \"daemon\" task that receives and processes administrative bundles (all custody signals and, nominally, all bundle status reports) that are sent to the \"dtn\"-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. dtn2adminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the \"dtn\" scheme.
dtn2adminep responds to custody signals as specified in the Bundle Protocol specification, RFC 5050. It responds to bundle status reports by logging ASCII text messages describing the reported activity.
"},{"location":"man/bpv6/dtn2adminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtn2adminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dtn2adminep.
\"1\"
dtn2adminep was unable to attach to Bundle Protocol operations or was unable to load the \"dtn\" scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/dtn2adminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dtn2adminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtn2adminep can't attach to BP.
bpadmin has not yet initialized BP operations.
dtn2adminep can't load routing database.
dtn2admin has not yet initialized the \"dtn\" scheme.
dtn2adminep can't get admin EID.
dtn2admin has not yet initialized the \"dtn\" scheme.
dtn2adminep crashed.
An unrecoverable database error was encountered. dtn2adminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dtn2adminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), dtn2admin(1).
"},{"location":"man/bpv6/dtn2fw/","title":"NAME","text":"dtn2fw - bundle route computation task for the \"dtn\" scheme
"},{"location":"man/bpv6/dtn2fw/#synopsis","title":"SYNOPSIS","text":"dtn2fw
"},{"location":"man/bpv6/dtn2fw/#description","title":"DESCRIPTION","text":"dtn2fw is a background \"daemon\" task that pops bundles from the queue of bundle destined for \"dtn\"-scheme endpoints, computes proximate destinations for those bundles, and appends those bundles to the appropriate queues of bundles pending transmission to those computed proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is affected by static routes as configured by dtn2admin(1).
dtn2fw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. dtn2fw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the \"dtn\" scheme.
"},{"location":"man/bpv6/dtn2fw/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtn2fw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dtn2fw.
\"1\"
dtn2fw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dtn2fw.
No configuration files are needed.
"},{"location":"man/bpv6/dtn2fw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dtn2fw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtn2fw can't attach to BP.
bpadmin has not yet initialized BP operations.
dtn2fw can't load routing database.
dtn2admin has not yet initialized the \"dtn\" scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. dtn2fw terminates.
'dtn' scheme is unknown.
The \"dtn\" scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. dtn2fw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. dtn2fw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dtn2fw/#see-also","title":"SEE ALSO","text":"bpadmin(1), dtn2admin(1), bprc(5), dtn2rc(5).
"},{"location":"man/bpv6/dtn2rc/","title":"NAME","text":"dtn2rc - \"dtn\" scheme configuration commands file
"},{"location":"man/bpv6/dtn2rc/#description","title":"DESCRIPTION","text":"\"dtn\" scheme configuration commands are passed to dtn2admin either in a file of text lines or interactively at dtn2admin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
\"dtn\" scheme configuration commands establish static routing rules for forwarding bundles to \"dtn\"-scheme destination endpoints, identified by node ID. (Each node ID is simply a BP endpoint ID.)
Static routes are expressed as plans in the \"dtn\"-scheme routing database. A plan that is established for a given node name associates a routing directive with the named node. Each directive is a string of one of two possible forms:
f endpoint_ID
...or...
x protocol_name/outduct_name
The former form signifies that the bundle is to be forwarded to the indicated endpoint, requiring that it be re-queued for processing by the forwarder for that endpoint (which might, but need not, be identified by another \"dtn\"-scheme endpoint ID). The latter form signifies that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
The node IDs cited in dtn2rc plans may be \"wild-carded\". That is, when the last character of a node ID is either '*' or '~' (these two wild-card characters are equivalent for this purpose), the plan applies to all nodes whose IDs are identical to the wild-carded node name up to the wild-card character. For example, a bundle whose destination EID name is \"dtn://foghorn\" would be routed by plans citing the following node IDs: \"dtn://foghorn\", \"dtn://fogh*\", \"dtn://fog~\", \"//*\". When multiple plans are all applicable to the same destination EID, the one citing the longest (i.e., most narrowly targeted) node ID will be applied.
The formats and effects of the DTN scheme configuration commands are described below.
"},{"location":"man/bpv6/dtn2rc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 dtn2admin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a plan node_ID directive [nominal_xmit_rate]
The add plan command. This command establishes a static route for the bundles destined for the node(s) identified by node_ID. The nominal_xmit_rate is the assumed rate of transmission to this node in the absence of contact plan information. A nominal_data_rate of zero (the default) in the absence of contact plan information completely disables rate control.
Note that the plan commands consumed by dtn2admin are a simplified shortcut for submitting plan commands as consumed by bpadmin (see bprc(5)). The syntax of these commands is DIFFERENT from that of the more general and more powerful bpadmin commands.
c plan node_ID [directive] [nominal_xmit_rate]
The change plan command. This command revises the directive and/or nominal_data_rate of the static route for the node(s) identified by node_ID.
d plan node_ID
The delete plan command. This command deletes the static route for the node(s) identified by node_ID.
i plan node_ID
This command will print information about the static route for the node(s) identified by node_ID.
l plan
This command lists all static routes established in the DTN database for the local node.
a plan dtn://bbn2 f ipn:8.41
Declares a static route from the local node to node \"//bbn2\". Any bundle destined for any endpoint whose node name is \"//bbn2\" will be forwarded to endpoint \"ipn:8.41\".
a plan dtn://mitre1* x ltp/6
Declares a static route from the local node to node \"//mitre1\". Any bundle destined for any endpoint whose node ID begins with \"mitre1\" will be queued for transmission on LTP outduct 6.
dtn2admin(1)
"},{"location":"man/bpv6/hmackeys/","title":"NAME","text":"hmackeys - utility program for generating good HMAC-SHA1 keys
"},{"location":"man/bpv6/hmackeys/#synopsis","title":"SYNOPSIS","text":"hmackeys [ keynames_filename ]
"},{"location":"man/bpv6/hmackeys/#description","title":"DESCRIPTION","text":"hmackeys writes files containing randomized 160-bit key values suitable for use by HMAC-SHA1 in support of Bundle Authentication Block processing, Bundle Relay Service connections, or other functions for which symmetric hash computation is applicable. One file is written for each key name presented to hmackeys; the content of each file is 20 consecutive randomly selected 8-bit integer values, and the name given to each file is simply \"keyname.hmk\".
hmackeys operates in response to the key names found in the file keynames_filename, one name per file text line, if provided; if not, hmackeys prints a simple prompt (:) so that the user may type key names directly into standard input.
When the program is run in interactive mode, either enter 'q' or press ^C to terminate.
"},{"location":"man/bpv6/hmackeys/#exit-status","title":"EXIT STATUS","text":"hmackeys
Enter interactive HMAC/SHA1 key generation mode.
hmackeys host1.keynames
Create a key file for each key name in host1.keynames, then terminate immediately.
No other files are used in the operation of hmackeys.
"},{"location":"man/bpv6/hmackeys/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/hmackeys/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the logfile ion.log:
Can't open keynames file...
The keynames_filename specified in the command line doesn't exist.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/hmackeys/#see-also","title":"SEE ALSO","text":"brsscla(1), ionsecadmin(1)
"},{"location":"man/bpv6/imcadmin/","title":"NAME","text":"imcadmin - Interplanetary Multicast (IMC) scheme administration interface
"},{"location":"man/bpv6/imcadmin/#synopsis","title":"SYNOPSIS","text":"imcadmin [ commands_filename ]
"},{"location":"man/bpv6/imcadmin/#description","title":"DESCRIPTION","text":"imcadmin configures the local ION node's routing of bundles to endpoints whose IDs conform to the imc endpoint ID scheme. imc is a CBHE-conformant scheme; that is, every endpoint ID in the imc scheme is a string of the form \"imc:group_number.service_number\" where group_number (an IMC multicast group number) serves as a CBHE \"node number\" and service_number identifies a specific application processing point.
imcadmin operates in response to IMC scheme configuration commands found in the file commands_filename, if provided; if not, imcadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from imcadmin with the 'h' or '?' commands at the prompt. The commands are documented in imcrc(5).
"},{"location":"man/bpv6/imcadmin/#exit-status","title":"EXIT STATUS","text":"imcadmin
Enter interactive IMC scheme configuration command entry mode.
imcadmin host1.imcrc
Execute all configuration commands in host1.imcrc, then terminate immediately.
See imcrc(5) for details of the IMC scheme configuration commands.
"},{"location":"man/bpv6/imcadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/imcadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the imcrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to imcadmin. Otherwise imcadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
imcadmin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
imcadmin can't initialize routing database.
There is no SDR data store for imcadmin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause imcadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see imcrc(5) for details.
"},{"location":"man/bpv6/imcadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/imcadmin/#see-also","title":"SEE ALSO","text":"imcrc(5)
"},{"location":"man/bpv6/imcfw/","title":"NAME","text":"imcfw - bundle route computation task for the IMC scheme
"},{"location":"man/bpv6/imcfw/#synopsis","title":"SYNOPSIS","text":"imcfw
"},{"location":"man/bpv6/imcfw/#description","title":"DESCRIPTION","text":"imcfw is a background \"daemon\" task that pops bundles from the queue of bundle destined for IMC-scheme (Interplanetary Multicast) endpoints, determines which \"relatives\" on the IMC multicast tree to forward the bundles to, and appends those bundles to the appropriate queues of bundles pending transmission to those proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is determined by multicast group membership as resulting from nodes' registration in multicast endpoints, governed by multicast tree structure as configured by imcadmin(1).
imcfw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. imcfw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IMC scheme.
"},{"location":"man/bpv6/imcfw/#exit-status","title":"EXIT STATUS","text":"\"0\"
imcfw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart imcfw.
\"1\"
imcfw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart imcfw.
No configuration files are needed.
"},{"location":"man/bpv6/imcfw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/imcfw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
imcfw can't attach to BP.
bpadmin has not yet initialized BP operations.
imcfw can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. imcfw terminates.
'imc' scheme is unknown.
The IMC scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. imcfw terminates.
Can't exclude sender from routes.
An unrecoverable database error was encountered. imcfw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. imcfw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/imcfw/#see-also","title":"SEE ALSO","text":"bpadmin(1), imcadmin(1), bprc(5), imcrc(5)
"},{"location":"man/bpv6/imcrc/","title":"NAME","text":"imcrc - IMC scheme configuration commands file
"},{"location":"man/bpv6/imcrc/#description","title":"DESCRIPTION","text":"IMC scheme configuration commands are passed to imcadmin either in a file of text lines or interactively at imcadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
IMC scheme configuration commands simply establish which nodes are the local node's parents and children within a single IMC multicast tree. This single spanning tree, an overlay on a single BP-based network, is used to convey all multicast group membership assertions and cancellations in the network, for all groups. Each node privately tracks which of its immediate \"relatives\" in the tree are members of which multicast groups and on this basis selectively forwards -- directly, to all (and only) interested relatives -- the bundles destined for the members of each group.
Note that all of a node's immediate relatives in the multicast tree must be among its immediate neighbors in the underlying network. This is because multicast bundles can only be correctly forwarded within the tree if each forwarding node knows the identity of the relative that passed the bundle to it, so that the bundle is not passed back to that relative creating a routing loop. The identity of that prior forwarding node can only be known if the forwarding node was a neighbor, because no prior forwarding node (aside from the source) other than the immediate proximate (neighboring) sender of a received bundle is ever known.
IMC group IDs are unsigned integers, just as IPN node IDs are unsigned integers. The members of a group are nodes identified by node number, and the multicast tree parent and children of a node are neighboring nodes identified by node number.
The formats and effects of the IMC scheme configuration commands are described below.
"},{"location":"man/bpv6/imcrc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 ipnadmin to be logged as well as sent to stdout. Setting echo to 0 disables this behavior.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a node_nbr { 1 | 0 }
The add kin command. This command adds the neighboring node identified by node_nbr as an immediate relative of the local node. The Boolean value that follows the node number indicates whether or not this node is the local node's parent within the tree.
c node_nbr { 1 | 0 }
The change kin command. This command changes the parentage status of the indicated relative according to Boolean value that follows the node number, as noted for the add kin command.
d node_nbr
The delete kin command. This command deletes the immediate multicast tree relative identified by node_nbr. That node still exists but it is no longer a parent or child of the local node.
i node_nbr
This command will print information (the parentage switch) for the multicast tree relative identified by node_nbr.
l
This command lists all of the local node's multicast tree relatives, indicating which one is its parent in the tree.
a 983 1
Declares that 983 is the local node's parent in the network's multicast tree.
imcadmin(1)
"},{"location":"man/bpv6/ipnadmin/","title":"NAME","text":"ipnadmin - Interplanetary Internet (IPN) scheme administration interface
"},{"location":"man/bpv6/ipnadmin/#synopsis","title":"SYNOPSIS","text":"ipnadmin [ commands_filename ]
"},{"location":"man/bpv6/ipnadmin/#description","title":"DESCRIPTION","text":"ipnadmin configures the local ION node's routing of bundles to endpoints whose IDs conform to the ipn endpoint ID scheme. ipn is a CBHE-conformant scheme; that is, every endpoint ID in the ipn scheme is a string of the form \"ipn:node_number.service_number\" where node_number is a CBHE \"node number\" and service_number identifies a specific application processing point.
ipnadmin operates in response to IPN scheme configuration commands found in the file commands_filename, if provided; if not, ipnadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from ipnadmin with the 'h' or '?' commands at the prompt. The commands are documented in ipnrc(5).
"},{"location":"man/bpv6/ipnadmin/#exit-status","title":"EXIT STATUS","text":"ipnadmin
Enter interactive IPN scheme configuration command entry mode.
ipnadmin host1.ipnrc
Execute all configuration commands in host1.ipnrc, then terminate immediately.
See ipnrc(5) for details of the IPN scheme configuration commands.
"},{"location":"man/bpv6/ipnadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ipnadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ipnrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ipnadmin. Otherwise ipnadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ipnadmin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
ipnadmin can't initialize routing database.
There is no SDR data store for ipnadmin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ipnadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see ipnrc(5) for details.
"},{"location":"man/bpv6/ipnadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ipnadmin/#see-also","title":"SEE ALSO","text":"ipnrc(5)
"},{"location":"man/bpv6/ipnadminep/","title":"NAME","text":"ipnadminep - administrative endpoint task for the IPN scheme
"},{"location":"man/bpv6/ipnadminep/#synopsis","title":"SYNOPSIS","text":"ipnadminep
"},{"location":"man/bpv6/ipnadminep/#description","title":"DESCRIPTION","text":"ipnadminep is a background \"daemon\" task that receives and processes administrative bundles (all custody signals and, nominally, all bundle status reports) that are sent to the IPN-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. ipnadminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IPN scheme.
ipnadminep responds to custody signals as specified in the Bundle Protocol specification, RFC 5050. It responds to bundle status reports by logging ASCII text messages describing the reported activity.
"},{"location":"man/bpv6/ipnadminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
ipnadminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ipnadminep.
\"1\"
ipnadminep was unable to attach to Bundle Protocol operations or was unable to load the IPN scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/ipnadminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ipnadminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ipnadminep can't attach to BP.
bpadmin has not yet initialized BP operations.
ipnadminep can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
ipnadminep crashed.
An unrecoverable database error was encountered. ipnadminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ipnadminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), ipnadmin(1), bprc(5).
"},{"location":"man/bpv6/ipnd/","title":"NAME","text":"ipnd - ION IPND module
"},{"location":"man/bpv6/ipnd/#description","title":"DESCRIPTION","text":"The ipnd daemon is the ION implementation of DTN IP Neighbor Discovery. This module allows the node to send and receive beacon messages using unicast, multicast or broadcast IP addresses. Beacons are used for the discovery of neighbors and may be used to advertise services that are present and available on nodes, such as routing algorithms or CLAs.
ION IPND module is configured using a *.rc configuration file. The name of the configuration file must be passed as the sole command-line argument to ipnd when the daemon is started. Commands are interpreted line by line, with exactly one command per line. The formats and effects of the ION ipnd management commands are described below.
"},{"location":"man/bpv6/ipnd/#usage","title":"USAGE","text":"ipnd config_file_name
"},{"location":"man/bpv6/ipnd/#commands","title":"COMMANDS","text":"1
The initialize command. This must be the first command.
#
Comment line. Lines beginning with # are not interpreted.
e { 1 | 0 }
Echo control. Setting echo to 1 causes all output printed by ipnd to be logged into ion.log. Setting echo to 0 disables this behavior. Default is 1.
m eid eid
Local eid. This command sets the advertised BP endpoint ID by which the node will identify itself in beacon messages.
m announce period { 1 | 0 }
Announce period control. Setting to 1 causes all beacons messages sent to contain beacon period. Setting to 0 disables this behavior. Default is 1.
m announce eid { 1 | 0 }
Announce eid control. Setting to 1 causes all beacons messages sent to contain source eid. Setting to 0 disables this behavior. This should be always set to 1. Default is 1.
m interval unicast interval
Unicast interval. This command sets the beacon messages period on unicast transmissions. Time interval is expressed in seconds. Default is 5.
m interval multicast interval
Multicast interval. This command sets the beacon messages period on multicast transmissions. Time interval is expressed in seconds. Default is 7.
m interval broadcast interval
Broadcastcast interval. This command sets the beacon messages period on broadcast transmissions. Time interval is expressed in seconds. Default is 11.
m multicast ttl ttl
Multicast ttl. This command sets the multicast outgoing beacon messages' time to live, in seconds. Default is 255.
m svcdef id name child_name:child_type ...
Service definition. This command specifies definitions of \"services\", which are dynamically defined beacon message data structures indicating the capabilities of the beacon message sender. id is a service-identifying number in the range 128-255. name is the name of the service type that is being defined. The definition of the structure of the service is a sequence of elements, each of which is a name:type pair. Each child_type must be the name of a standard or previously defined service type. Infinite recursion is supported.
a svcadv name child_name:child_value ...
Service advertising command. This command defines which services will be advertised and with which values. All types of formats for values are supported (e.g. 999, 0345 (octal), 0x999 (hex), -1e-9, 0.32, etc.). For a service that contains only a single element, it is not necessary to provide that element's name. E.g. it is enough to write Booleans:true instead of Booleans:BooleanValues:B:true, as BooleanValues is the only child of Booleans and B is the only child of BooleanValues.
a listen IP_address
Listen socket specification command. This command asserts, in the form IP_address, the IP address of the socket at which the IPND daemon is to listen for incoming beacons; a default port number is used. The address can be an unicast, a multicast or a broadcast address. If a multicast address is provided all the configured unicast addresses will listen for multicast packets in that group. If a broadcast address is provided all the unicast addresses will listen for broadcasted packets.
a destination destination_socket_spec
Destination socket specification command. This command asserts the specification for a socket to which the IPND daemon is to send beacons. It can be an unicast, a multicast or a broadcast address.
s
The start command. This command starts the IPND daemon for the local ION node.
m scvdef 128 FooRouter Seed:SeedVal BaseWeight:WeightVal RootHash:bytes
Defines a new service called FooRouter comprising 3 elements. SeedVal and WeightVal are user defined services that must be already defined.
m svcdef 129 SeedVal Value:fixed16
m svcdef 130 WeightVal Value:fixed16
m svcdef 128 FooRouter Seed:SeedVal BaseWeight:WeightVal RootHash:bytes
m svcdef 150 FixedValuesList F16:fixed16 F32:fixed32 F64:fixed64
m svcdef 131 VariableValuesList U64:uint64 S64:sint64
m svcdef 132 BooleanValues B:boolean
m svcdef 133 FloatValuesList F:float D:double
m svcdef 135 IntegersList FixedValues:FixedValuesList VariableValues:VariableValuesList
m svcdef 136 NumbersList Integers:IntegersList Floats:FloatValuesList
m svcdef 140 HugeService CLAv4:CLA-TCP-v4 Booleans:BooleanValues Numbers:NumbersList FR:FooRouter
a svcadv HugeService CLAv4:IP:10.1.0.10 CLAv4:Port:4444 Booleans:true FR:Seed:0x5432 FR:BaseWeight:13 FR:RootHash:BEEF Numbers:Integers:FixedValues:F16:0x16 Numbers:Integers:FixedValues:F32:0x32 Numbers:Integers:FixedValues:F64:0x1234567890ABCDEF Numbers:Floats:F:0.32 Numbers:Floats:D:-1e-6 Numbers:Integers:VariableValues:U64:18446744073704783380 Numbers:Integers:VariableValues:S64:-4611686018422619668
This shows how to define multiple nested services and how to advertise them.
"},{"location":"man/bpv6/ipnd/#see-also","title":"SEE ALSO","text":"ion(3)
"},{"location":"man/bpv6/ipnfw/","title":"NAME","text":"ipnfw - bundle route computation task for the IPN scheme
"},{"location":"man/bpv6/ipnfw/#synopsis","title":"SYNOPSIS","text":"ipnfw
"},{"location":"man/bpv6/ipnfw/#description","title":"DESCRIPTION","text":"ipnfw is a background \"daemon\" task that pops bundles from the queue of bundle destined for IPN-scheme endpoints, computes proximate destinations for those bundles, and appends those bundles to the appropriate queues of bundles pending transmission to those computed proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is affected by static and default routes as configured by ipnadmin(1) and by contact graphs as managed by ionadmin(1) and rfxclock(1).
ipnfw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. ipnfw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IPN scheme.
"},{"location":"man/bpv6/ipnfw/#exit-status","title":"EXIT STATUS","text":"\"0\"
ipnfw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ipnfw.
\"1\"
ipnfw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart ipnfw.
No configuration files are needed.
"},{"location":"man/bpv6/ipnfw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ipnfw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ipnfw can't attach to BP.
bpadmin has not yet initialized BP operations.
ipnfw can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. ipnfw terminates.
'ipn' scheme is unknown.
The IPN scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. ipnfw terminates.
Can't exclude sender from routes.
An unrecoverable database error was encountered. ipnfw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. ipnfw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ipnfw/#see-also","title":"SEE ALSO","text":"bpadmin(1), ipnadmin(1), bprc(5), ipnrc(5)
"},{"location":"man/bpv6/ipnrc/","title":"NAME","text":"ipnrc - IPN scheme configuration commands file
"},{"location":"man/bpv6/ipnrc/#description","title":"DESCRIPTION","text":"IPN scheme configuration commands are passed to ipnadmin either in a file of text lines or interactively at ipnadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
IPN scheme configuration commands (a) establish egress plans for direct transmission to neighboring nodes that are members of endpoints identified in the \"ipn\" URI scheme and (b) establish static default routing rules for forwarding bundles to specified destination nodes.
The egress plan established for a given node associates a duct expression with that node. Each duct expression is a string of the form \"protocol_name/outduct_name\" signifying that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
Note that egress plans must be established for all neighboring nodes, regardless of whether or not contact graph routing is used for computing dynamic routes to distant nodes. This is by definition: if there isn't an egress plan to a node, it can't be considered a neighbor.
Static default routes are declared as exits in the ipn-scheme routing database. An exit is a range of node numbers identifying a set of nodes for which defined default routing behavior is established. Whenever a bundle is to be forwarded to a node whose number is in the exit's node number range and it has not been possible to compute a dynamic route to that node from the contact schedules that have been provided to the local node and that node is not a neighbor to which the bundle can be directly transmitted, BP will forward the bundle to the gateway node associated with this exit. The gateway node for any exit is identified by an endpoint ID, which might or might not be an ipn-scheme EID; regardless, directing a bundle to the gateway for an exit causes the bundle to be re-forwarded to that intermediate destination endpoint. Multiple exits may encompass the same node number, in which case the gateway associated with the most restrictive exit (the one with the smallest range) is always selected.
Note that \"exits\" were termed \"groups\" in earlier versions of ION. The term \"exit\" has been adopted instead, to minimize any possible confusion with multicast groups. To protect backward compatibility, the keyword \"group\" continues to be accepted by ipnadmin as an alias for the new keyword \"exit\", but the older terminology is deprecated.
The formats and effects of the IPN scheme configuration commands are described below.
"},{"location":"man/bpv6/ipnrc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 ipnadmin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a plan node_nbr duct_expression [nominal_data_rate]
The add plan command. This command establishes an egress plan for the bundles that must be transmitted to the neighboring node identified by node_nbr. The nominal_data_rate is the assumed rate of transmission to this node in the absence of contact plan information. A nominal_data_rate of zero (the default) in the absence of contact plan information completely disables rate control.
Note that the plan commands consumed by ipnadmin are a simplified shortcut for submitting plan commands as consumed by bpadmin (see bprc(5)). The syntax of these commands is DIFFERENT from that of the more general and more powerful bpadmin commands.
c plan node_nbr nominal_data_rate
The change plan command. This command changes the nominal data rate for the indicated plan.
d plan node_nbr
The delete plan command. This command deletes the egress plan for the node identified by node_nbr.
i plan node_nbr
This command will print information about the egress plan for the node identified by node_nbr.
l plan
This command lists all egress plans established in the IPN database for the local node.
a exit first_node_nbr last_node_nbr gateway_endpoint_ID
The add exit command. This command establishes an \"exit\" for static default routing as described above.
c exit first_node_nbr last_node_nbr gateway_endpoint_ID
The change exit command. This command changes the gateway node number for the exit identified by first_node_nbr and last_node_nbr .
d exit first_node_nbr last_node_nbr
The delete exit command. This command deletes the exit identified by first_node_nbr and last_node_nbr.
i exit first_node_nbr last_node_nbr
This command will print information (the gateway endpoint ID) about the exit identified by first_node_nbr and last_node_nbr.
l exit
This command lists all exits defined in the IPN database for the local node.
a rtovrd data_label dest_node_nbr source_node_nbr neighbor
The add rtovrd command. This command cause bundles characterized by data_label, dest_node_nbr (\"all other destinations\" if this node number is zero) and source_node_nbr (\"all other sources\" if this node number is zero) to be forwarded to neighbor. If neighbor is zero, the override will be \"learned\" by ION: the neighbor selected for this bundle, by whatever means, becomes the override for all subsequent matching bundles.
c rtovrd data_label dest_node_nbr source_node_nbr neighbor
The change rtovrd command. This command changes the override neighbor for the override identified by data_label, dest_node_nbr, and source_node_nbr. To cause ION to forget the override, use -1 as neighbor.
a cosovrd data_label dest_node_nbr source_node_nbr priority ordinal
The add cosovrd command. This command cause bundles characterized by data_label, dest_node_nbr (\"all other destinations\" if this node number is zero) and source_node_nbr (\"all other sources\" if this node number is zero) to have their effective class of service (priority and ordinal) changed as noted.
c cosovrd data_label dest_node_nbr source_node_nbr priority ordinal
The change cosovrd command. This command changes the override priority and ordinal for the override identified by data_label, dest_node_nbr, and source_node_nbr. To cause ION to forget the override, use -1 as priority.
d ovrd data_label dest_node_nbr source_node_nbr
The delete override command. This command deletes all overrides identified by data_label, dest_node_nbr, and source_node_nbr.
i ovrd data_label dest_node_nbr source_node_nbr
This command will print information for all overrides identified by data_label, dest_node_nbr, and source_node_nbr.
l ovrd
This command lists all overrides defined in the IPN database for the local node.
a plan 18 ltp/18
Declares the egress plan to use for transmission from the local node to neighboring node 18. By default, any bundle for which the computed \"next hop\" node is node 18 will be queued for transmission on LTP outduct 18.
a exit 1 999 dtn://stargate
Declares a default route for bundles destined for all nodes whose numbers are in the range 1 through 999 inclusive: absent any other routing decision, such bundles are to be forwarded to \"dtn://stargate\".
ipnadmin(1)
"},{"location":"man/bpv6/lgagent/","title":"NAME","text":"lgagent - ION Load/Go remote agent program
"},{"location":"man/bpv6/lgagent/#synopsis","title":"SYNOPSIS","text":"lgagent own_endpoint_ID
"},{"location":"man/bpv6/lgagent/#description","title":"DESCRIPTION","text":"ION Load/Go is a system for management of an ION-based network, enabling the execution of ION administrative programs at remote nodes. The system comprises two programs, lgsend and lgagent.
The lgagent task on a given node opens the indicated ION endpoint for bundle reception, receives the extracted payloads of Load/Go bundles sent to it by lgsend as run on one or more remote nodes, and processes those payloads, which are the text of Load/Go source files.
Load/Go source file content is limited to newline-terminated lines of ASCII characters. More specifically, the text of any Load/Go source file is a sequence of line sets of two types: file capsules and directives. Any Load/Go source file may contain any number of file capsules and any number of directives, freely intermingled in any order, but the typical structure of a Load/Go source file is simply a single file capsule followed by a single directive.
When lgagent identifies a file capsule, it copies all of the capsule's text lines to a new file that it creates in the current working directory. When lgagent identifies a directive, it executes the directive by passing the text of the directive to the pseudoshell() function (see platform(3)). lgagent processes the line sets of a Load/Go source file in the order in which they appear in the file, so the text of a directive may reference a file that was created as the result of processing a prior file capsule in the same source file.
"},{"location":"man/bpv6/lgagent/#exit-status","title":"EXIT STATUS","text":"\"0\"
Load/Go remote agent processing has terminated.
lgfile contains the Load/Go file capsules and directives that are to be processed.
"},{"location":"man/bpv6/lgagent/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/lgagent/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
lgagent: can't attach to BP.
Bundle Protocol is not running on this computer. Run bpadmin(1) to start BP.
lgagent: can't open own endpoint.
own_endpoint_ID is not a declared endpoint on the local ION node. Run bpadmin(1) to add it.
lgagent: bundle reception failed.
ION system problem. Investigate and correct before restarting.
lgagent cannot continue.
lgagent processing problem. See earlier diagnostic messages for details. Investigate and correct before restarting.
lgagent: no space for bundle content.
ION system problem: have exhausted available SDR data store reserves.
lgagent: can't receive bundle content.
ION system problem: have exhausted available SDR data store reserves.
lgagent: can't handle bundle delivery.
ION system problem. Investigate and correct before restarting.
lgagent: pseudoshell failed.
Error in directive line, usually an attempt to execute a non-existent administration program (e.g., a misspelled program name). Terminates processing of source file content.
A variety of other diagnostics noting source file parsing problems may also be reported. These errors are non-fatal but they terminate the processing of the source file content from the most recently received bundle.
"},{"location":"man/bpv6/lgagent/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/lgagent/#see-also","title":"SEE ALSO","text":"lgsend(1), lgfile(5)
"},{"location":"man/bpv6/lgfile/","title":"NAME","text":"lgfile - ION Load/Go source file
"},{"location":"man/bpv6/lgfile/#description","title":"DESCRIPTION","text":"The ION Load/Go system enables the execution of ION administrative programs at remote nodes:
The lgsend program reads a Load/Go source file from a local file system, encapsulates the text of that source file in a bundle, and sends the bundle to a designated DTN endpoint on the remote node.
An lgagent task running on the remote node, which has opened that DTN endpoint for bundle reception, receives the extracted payload of the bundle -- the text of the Load/Go source file -- and processes it.
Load/Go source file content is limited to newline-terminated lines of ASCII characters. More specifically, the text of any Load/Go source file is a sequence of line sets of two types: file capsules and directives. Any Load/Go source file may contain any number of file capsules and any number of directives, freely intermingled in any order, but the typical structure of a Load/Go source file is simply a single file capsule followed by a single directive.
Each file capsule is structured as a single start-of-capsule line, followed by zero or more capsule text lines, followed by a single end-of-capsule line. Each start-of-capsule line is of this form:
[file_name
Each capsule text line can be any line of ASCII text that does not begin with an opening ([) or closing (]) bracket character.
A text line that begins with a closing bracket character (]) is interpreted as an end-of-capsule line.
A directive is any line of text that is not one of the lines of a file capsule and that is of this form:
!directive_text
When lgagent identifies a file capsule, it copies all of the capsule's text lines to a new file named file_name that it creates in the current working directory. When lgagent identifies a directive, it executes the directive by passing directive_text to the pseudoshell() function (see platform(3)). lgagent processes the line sets of a Load/Go source file in the order in which they appear in the file, so the directive_text of a directive may reference a file that was created as the result of processing a prior file capsule line set in the same source file.
Note that lgfile directives are passed to pseudoshell(), which on a VxWorks platform will always spawn a new task; the first argument in directive_text must be a symbol that VxWorks can resolve to a function, not a shell command. Also note that the arguments in directive_text will be actual task arguments, not shell command-line arguments, so they should never be enclosed in double-quote characters (\"). However, any argument that contains embedded whitespace must be enclosed in single-quote characters (') so that pseudoshell() can parse it correctly.
"},{"location":"man/bpv6/lgfile/#examples","title":"EXAMPLES","text":"Presenting the following lines of source file text to lgsend:
[cmd33.bprc
x protocol ltp
]
!bpadmin cmd33.bprc
should cause the receiving node to halt the operation of the LTP convergence-layer protocol.
"},{"location":"man/bpv6/lgfile/#see-also","title":"SEE ALSO","text":"lgsend(1), lgagent(1), platform(3)
"},{"location":"man/bpv6/lgsend/","title":"NAME","text":"lgsend - ION Load/Go command program
"},{"location":"man/bpv6/lgsend/#synopsis","title":"SYNOPSIS","text":"lgsend command_file_name own_endpoint_ID destination_endpoint_ID
"},{"location":"man/bpv6/lgsend/#description","title":"DESCRIPTION","text":"ION Load/Go is a system for management of an ION-based network, enabling the execution of ION administrative programs at remote nodes. The system comprises two programs, lgsend and lgagent.
The lgsend program reads a Load/Go source file from a local file system, encapsulates the text of that source file in a bundle, and sends the bundle to an lgagent task that is waiting for data at a designated DTN endpoint on the remote node.
To do so, it first reads all lines of the Load/Go source file identified by command_file_name into a temporary buffer in ION's SDR data store, concatenating the lines of the file and retaining all newline characters. Then it invokes the bp_send() function to create and send a bundle whose payload is this temporary buffer, whose destination is destination_endpoint_ID, and whose source endpoint ID is own_endpoint_ID. Then it terminates.
"},{"location":"man/bpv6/lgsend/#exit-status","title":"EXIT STATUS","text":"\"0\"
Load/Go file transmission succeeded.
\"1\"
Load/Go file transmission failed. Examine ion.log to determine the cause of the failure, then re-run.
lgfile contains the Load/Go file capsules and directive that are to be sent to the remote node.
"},{"location":"man/bpv6/lgsend/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/lgsend/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
lgsend: can't attach to BP.
Bundle Protocol is not running on this computer. Run bpadmin(1) to start BP.
lgsend: can't open own endpoint.
own_endpoint_ID is not a declared endpoint on the local ION node. Run bpadmin(1) to add it.
lgsend: can't open file of LG commands: error description
command_file_name doesn't identify a file that can be opened. Correct spelling of file name or file's access permissions.
lgsend: can't get size of LG command file: error description
Operating system problem. Investigate and correct before rerunning.
lgsend: LG cmd file size > 64000.
Load/Go command file is too large. Split it into multiple files if possible.
lgsend: no space for application data unit.
ION system problem: have exhausted available SDR data store reserves.
lgsend: fgets failed: error description
Operating system problem. Investigate and correct before rerunning.
lgsend: can't create application data unit.
ION system problem: have exhausted available SDR data store reserves.
lgsend: can't send bundle.
ION system problem. Investigate and correct before rerunning.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/lgsend/#see-also","title":"SEE ALSO","text":"lgagent(1), lgfile(5)
"},{"location":"man/bpv6/ltpcli/","title":"NAME","text":"ltpcli - LTP-based BP convergence layer input task
"},{"location":"man/bpv6/ltpcli/#synopsis","title":"SYNOPSIS","text":"ltpcli local_node_nbr
"},{"location":"man/bpv6/ltpcli/#description","title":"DESCRIPTION","text":"ltpcli is a background \"daemon\" task that receives LTP data transmission blocks, extracts bundles from the received blocks, and passes them to the bundle protocol agent on the local ION node.
ltpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"ltp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. ltpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the LTP convergence layer protocol.
"},{"location":"man/bpv6/ltpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ltpcli.
\"1\"
ltpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart ltpcli.
No configuration files are needed.
"},{"location":"man/bpv6/ltpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ltpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such ltp duct.
No LTP induct matching local_node_nbr has been added to the BP database. Use bpadmin to stop the LTP convergence-layer protocol, add the induct, and then restart the LTP protocol.
CLI task is already started for this duct.
Redundant initiation of ltpcli.
ltpcli can't initialize LTP.
ltpadmin has not yet initialized LTP operations.
ltpcli can't open client access.
Another task has already opened the client service for BP over LTP.
ltpcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart LTP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ltpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), ltpadmin(1), ltprc(5), ltpclo(1)
"},{"location":"man/bpv6/ltpclo/","title":"NAME","text":"ltpclo - LTP-based BP convergence layer adapter output task
"},{"location":"man/bpv6/ltpclo/#synopsis","title":"SYNOPSIS","text":"ltpclo remote_node_nbr
"},{"location":"man/bpv6/ltpclo/#description","title":"DESCRIPTION","text":"ltpclo is a background \"daemon\" task that extracts bundles from the queues of segments ready for transmission via LTP to the remote bundle protocol agent identified by remote_node_nbr and passes them to the local LTP engine for aggregation, segmentation, and transmission to the remote node.
ltpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. ltpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the LTP convergence layer protocol.
"},{"location":"man/bpv6/ltpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSC protocol.
\"1\"
ltpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSC protocol.
No configuration files are needed.
"},{"location":"man/bpv6/ltpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ltpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such ltp duct.
No LTP outduct with duct name matching remote_node_nbr has been added to the BP database. Use bpadmin to stop the LTP convergence-layer protocol, add the outduct, and then restart the LTP protocol.
CLO task is already started for this duct.
Redundant initiation of ltpclo.
ltpclo can't initialize LTP.
ltpadmin has not yet initialized LTP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ltpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), ltpadmin(1), ltprc(5), ltpcli(1)
"},{"location":"man/bpv6/stcpcli/","title":"NAME","text":"sstcpcli - DTN simple TCP convergence layer input task
"},{"location":"man/bpv6/stcpcli/#synopsis","title":"SYNOPSIS","text":"stcpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/stcpcli/#description","title":"DESCRIPTION","text":"stcpcli is a background \"daemon\" task comprising 1 + N threads: one that handles TCP connections from remote stcpclo tasks, spawning sockets for data reception from those tasks, plus one input thread for each spawned socket to handle data reception over that socket.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 4556.
Each reception thread receives bundles over the associated connected socket. Each bundle received on the connection is preceded by a 32-bit unsigned integer in network byte order indicating the length of the bundle. The received bundles are passed to the bundle protocol agent on the local ION node.
stcpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"stcp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. stcpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the STCP convergence layer protocol.
"},{"location":"man/bpv6/stcpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
stcpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart stcpcli.
\"1\"
stcpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart stcpcli.
No configuration files are needed.
"},{"location":"man/bpv6/stcpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/stcpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
stcpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such stcp duct.
No STCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the STCP convergence-layer protocol, add the induct, and then restart the STCP protocol.
CLI task is already started for this duct.
Redundant initiation of stcpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart STCP.
Can't open TCP socket
Operating system error. Check errtext, correct problem, and restart STCP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart STCP.
stcpcli can't create access thread
Operating system error. Check errtext, correct problem, and restart STCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/stcpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), stcpclo(1)
"},{"location":"man/bpv6/stcpclo/","title":"NAME","text":"stcpclo - DTN simple TCP convergence layer adapter output task
"},{"location":"man/bpv6/stcpclo/#synopsis","title":"SYNOPSIS","text":"stcpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/stcpclo/#description","title":"DESCRIPTION","text":"stcpclo is a background \"daemon\" task that connects to a remote node's TCP socket at remote_hostname and remote_port_nbr. It then begins extracting bundles from the queues of bundles ready for transmission via TCP to this remote bundle protocol agent and transmitting those bundles over the connected socket to that node. Each transmitted bundle is preceded by a 32-bit integer in network byte order indicating the length of the bundle.
If not specified, remote_port_nbr defaults to 4556.
stcpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. stcpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the STCP convergence layer protocol.
"},{"location":"man/bpv6/stcpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
stcpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the STCP protocol.
\"1\"
stcpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the STCP protocol.
No configuration files are needed.
"},{"location":"man/bpv6/stcpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/stcpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
stcpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such stcp duct.
No STCP outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the STCP convergence-layer protocol, add the outduct, and then restart the STCP protocol.
CLO task is already started for this duct.
Redundant initiation of stcpclo.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart STCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/stcpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), stcpcli(1)
"},{"location":"man/bpv6/tcpcli/","title":"NAME","text":"tcpcli - DTN TCPCL-compliant convergence layer input task
"},{"location":"man/bpv6/tcpcli/#synopsis","title":"SYNOPSIS","text":"tcpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/tcpcli/#description","title":"DESCRIPTION","text":"tcpcli is a background \"daemon\" task comprising 3 + 2*N threads: an executive thread; a clock thread that periodically attempts to connect to remote TCPCL entities as identified by the tcp outducts enumerated in the bprc(5) file (each of which must specify the hostname[:port_nbr] to connect to); a thread that handles TCP connections from remote TCPCL entities, spawning sockets for data reception from those tasks; plus one input thread and one output thread for each connection, to handle data reception and transmission over that socket.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 4556.
Each time a connection is established, the entities will first exchange contact headers, because connection parameters need to be negotiated. tcpcli records the acknowledgement flags, reactive fragmentation flag, and negative acknowledgements flag in the contact header it receives from its peer TCPCL entity.
Each reception thread receives bundles over the associated connected socket. Each bundle received on the connection is preceded by message type, fragmentation flags, and size represented as an SDNV. The received bundles are passed to the bundle protocol agent on the local ION node.
Similarly, each transmission thread obtains outbound bundles from the local ION node, encapsulates them as noted above, and transmits them over the associated connected socket.
tcpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"tcp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. tcpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the TCP convergence layer protocol.
"},{"location":"man/bpv6/tcpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart tcpcli.
\"1\"
tcpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart tcpcli.
No configuration files are needed.
"},{"location":"man/bpv6/tcpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/tcpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such tcp duct.
No TCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the TCP convergence-layer protocol, add the induct, and then restart the TCP protocol.
CLI task is already started for this duct.
Redundant initiation of tcpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart TCP.
Can't open TCP socket
Operating system error. Check errtext, correct problem, and restart TCP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart TCP.
tcpcli can't create access thread
Operating system error. Check errtext, correct problem, and restart TCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/tcpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv6/tcpclo/","title":"NAME","text":"tcpclo - DTN TCPCL-compliant convergence layer adapter output task
"},{"location":"man/bpv6/tcpclo/#synopsis","title":"SYNOPSIS","text":"tcpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/tcpclo/#description","title":"DESCRIPTION","text":"tcpclo is a background \"daemon\" task that connects to a remote node's TCP socket at remote_hostname and remote_port_nbr. It sends a contact header, and it records the acknowledgement flag, reactive fragmentation flag and negative acknowledgements flag in the contact header it receives from its peer tcpcli task. It then begins extracting bundles from the queues of bundles ready for transmission via TCP to this remote bundle protocol agent and transmitting those bundles over the connected socket to that node. Each transmitted bundle is preceded by message type, segmentation flags, and an SDNV indicating the size of the bundle (in bytes).
If not specified, remote_port_nbr defaults to 4556.
tcpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. tcpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the TCP convergence layer protocol.
"},{"location":"man/bpv6/tcpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the TCPCL protocol.
\"1\"
tcpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the TCPCL protocol.
No configuration files are needed.
"},{"location":"man/bpv6/tcpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/tcpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such tcp duct.
No TCP outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the TCP convergence-layer protocol, add the outduct, and then restart the TCP protocol.
CLO task is already started for this duct.
Redundant initiation of tcpclo.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart TCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/tcpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), tcpcli(1)
"},{"location":"man/bpv6/udpcli/","title":"NAME","text":"udpcli - UDP-based BP convergence layer input task
"},{"location":"man/bpv6/udpcli/#synopsis","title":"SYNOPSIS","text":"udpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/udpcli/#description","title":"DESCRIPTION","text":"udpcli is a background \"daemon\" task that receives UDP datagrams via a UDP socket bound to local_hostname and local_port_nbr, extracts bundles from those datagrams, and passes them to the bundle protocol agent on the local ION node.
If not specified, port number defaults to 4556.
The convergence layer input task is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"udp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. udpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the UDP convergence layer protocol.
"},{"location":"man/bpv6/udpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart udpcli.
\"1\"
udpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart udpcli.
No configuration files are needed.
"},{"location":"man/bpv6/udpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/udpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such udp duct.
No UDP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the UDP convergence-layer protocol, add the induct, and then restart the UDP protocol.
CLI task is already started for this duct.
Redundant initiation of udpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart UDP.
Can't open UDP socket
Operating system error. Check errtext, correct problem, and restart UDP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart UDP.
udpcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart UDP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/udpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), udpclo(1)
"},{"location":"man/bpv6/udpclo/","title":"NAME","text":"udpclo - UDP-based BP convergence layer output task
"},{"location":"man/bpv6/udpclo/#synopsis","title":"SYNOPSIS","text":"udpclo round_trip_time remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/udpclo/#description","title":"DESCRIPTION","text":"udpclo is a background \"daemon\" task that extracts bundles from the queues of bundles ready for transmission via UDP to a remote node's UDP socket at remote_hostname and remote_port_nbr, encapsulates those bundles in UDP datagrams, and sends those datagrams to that remote UDP socket.
Because UDP is not itself a \"reliable\" transmission protocol (i.e., it performs no retransmission of lost data), it may be used in conjunction with BP custodial retransmission. BP custodial retransmission is triggered only by expiration of a timer whose interval is nominally the round-trip time between the sending BP node and the next node in the bundle's end-to-end path that is expected to take custody of the bundle; notionally, if no custody signal citing the transmitted bundle has been received before the end of this interval it can be assumed that either the bundle or the custody signal was lost in transmission and therefore the bundle should be retransmitted. The value of the custodial retransmission timer interval (the expected round-trip time between the sending node and the anticipated next custodian) must be provided as a run-time argument to udpclo. If the value of this parameter is zero, custodial retransmission is disabled.
udpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. udpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the UDP convergence layer protocol.
"},{"location":"man/bpv6/udpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart udpclo.
\"1\"
udpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart udpclo.
No configuration files are needed.
"},{"location":"man/bpv6/udpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/udpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No memory for UDP buffer in udpclo.
ION system error. Check errtext, correct problem, and restart UDP.
No such udp duct.
No UDP outduct with duct name remote_hostname[:<remote_port_nbr>] has been added to the BP database. Use bpadmin to stop the UDP convergence-layer protocol, add the outduct, and then restart the UDP protocol.
CLO task is already started for this engine.
Redundant initiation of udpclo.
CLO can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udpclo.
CLO write() error on socket
Operating system error. Check errtext, correct problem, and restart udpclo.
Bundle is too big for UDP CLA.
Configuration error: bundles that are too large for UDP transmission (i.e., larger than 65535 bytes) are being enqueued for udpclo. Change routing.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/udpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), udpcli(1)
"},{"location":"man/bpv7/","title":"Index of Man Pages","text":"bibeadmin - bundle-in-bundle encapsulation database administration interface
"},{"location":"man/bpv7/bibeadmin/#synopsis","title":"SYNOPSIS","text":"bibeadmin [ commands_filename ]
"},{"location":"man/bpv7/bibeadmin/#description","title":"DESCRIPTION","text":"bibeadmin configures the local ION node's database of parameters governing the forwarding of BIBE PDUs to specified remote nodes.
bibeadmin operates in response to BIBE configuration commands found in the file commands_filename, if provided; if not, bibeadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from bibeadmin with the 'h' or '?' commands at the prompt. The commands are documented in biberc(5).
"},{"location":"man/bpv7/bibeadmin/#exit-status","title":"EXIT STATUS","text":"bibeadmin
Enter interactive BIBE configuration command entry mode.
bibeadmin host1.biberc
Execute all configuration commands in host1.biberc, then terminate immediately.
See biberc(5) for details of the BIBE configuration commands.
"},{"location":"man/bpv7/bibeadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bibeadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the biberc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bibeadmin. Otherwise bibeadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
bibeadmin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
bibeadmin can't initialize routing database.
There is no SDR data store for bibeadmin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bibeadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see biberc(5) for details.
"},{"location":"man/bpv7/bibeadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bibeadmin/#see-also","title":"SEE ALSO","text":"bibeclo(1), biberc(5)
"},{"location":"man/bpv7/bibeclo/","title":"NAME","text":"bibeclo - BP convergence layer output task using bundle-in-bundle encapsulation
"},{"location":"man/bpv7/bibeclo/#synopsis","title":"SYNOPSIS","text":"bibeclo peer_EID destination_EID
"},{"location":"man/bpv7/bibeclo/#description","title":"DESCRIPTION","text":"bibeclo is a background \"daemon\" task that extracts bundles from the queues of bundles destined for destination_EID that are ready for transmission via bundle-in-bundle encapsulation (BIBE) to peer_EID, encapsulates them in BP administrative records of (non-standard) record type 7 (BP_BIBE_PDU), and sends those administrative records in encapsulating bundles destined for peer_EID. The forwarding of encapsulated bundles for which custodial acknowledgment is requested causes bibeclo to post custodial re-forwarding timers to the node's timeline. Parameters governing the forwarding of BIBE PDUs to peer_EID are stipulated in the corresponding BIBE convergence-layer adapter (bcla) structure residing in the BIBE database, as managed by bibeadmin.
The receiving node is expected to process received BIBE PDUs by simply dispatching the encapsulated bundles - whose destination is the node identified by destination_EID - as if they had been received from neighboring nodes in the normal course of operations; BIBE PDUs for which custodial acknowledgment was requested cause the received bundles to be noted in custody signals that are being aggregated by the receiving node.
bibeclo additionally sends aggregated custody signals in BP administrative records of (non-standard) record type 8 (BP_BIBE_SIGNAL) as the deadlines for custody signal transmission arrive.
Note that the reception and processing of both encapsulated bundles and custody signals is performed by the scheme-specific administration endpoint daemon(s) at the receiving nodes. Reception of a custody signal terminates the custodial re-forwarding timers for all bundles acknowledged in that signal; the re-forwarding of bundles upon custodial re-forwarding timer expiration is initiated by the bpclock daemon.
bibeclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. bibeclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BIBE convergence layer protocol.
"},{"location":"man/bpv7/bibeclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
bibeclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bibeclo.
\"1\"
bibeclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart bibeclo.
No configuration files are needed.
"},{"location":"man/bpv7/bibeclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bibeclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bibeclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such bibe outduct.
No BIBE outduct with duct name destination_EID exists. Use bpadmin to stop the BIBE convergence-layer protocol, add the outduct, and then restart the BIBE protocol.
No such bcla.
No bcla structure for the node identified by peer_EID has been added to the BP database. Use bpadmin to stop the BIBE convergence-layer protocol, use bibeadmin to add the bcla, and then use bpadmin to restart the BIBE protocol.
CLO task is already started for this duct.
Redundant initiation of bibeclo.
Can't dequeue bundle.
BIBE outduct closed deleted or other system error. Check ION log; correct the problem and restart BIBE.
[i] bibeclo outduct closed.
Nominal shutdown message.
Can't prepend header; CLO stopping.
System error. Check ION log; correct the problem and restart BIBE.
Can't destroy old ZCO; CLO stopping.
System error. Check ION log; correct the problem and restart BIBE.
Can't get outbound space for BPDU.
System error. Check ION log; correct the problem and restart BIBE.
Can't send encapsulated bundle.
System error. Check ION log; correct the problem and restart BIBE.
Can't track bundle.
System error. Check ION log; correct the problem and restart BIBE.
[!] Encapsulated bundle not sent.
Malformed bundle issuance request, which might be a software error. Contact technical support.
Can't release ZCO; CLO stopping.
System error. Check ION log; correct the problem and restart BIBE.
[i] bibeclo duct has ended.
Nominal shutdown message.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bibeclo/#see-also","title":"SEE ALSO","text":"biberc(5), bibeadmin(1)
"},{"location":"man/bpv7/biberc/","title":"NAME","text":"biberc - BIBE configuration commands file
"},{"location":"man/bpv7/biberc/#description","title":"DESCRIPTION","text":"BIBE configuration commands are passed to bibeadmin either in a file of text lines or interactively at bibeadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
BIBE configuration commands establish the parameters governing transmission of BIBE PDUs to specified peer nodes: anticipated delivery latency in the forward direction, anticipated delivery latency in the return direction, TTL for BIBE PDUs, priority for BIBE PDUs, ordinal priority for BIBE PDUs in the event that priority is Expedited, and (optionally) data label for BIBE PDUs. As such, they configure BIBE convergence-layer adapter (bcla) structures.
The formats and effects of the BIBE configuration commands are described below.
NOTE: in order to cause bundles to be transmitted via BIBE:
Plan
Remember that BIBE is a convergence-layer protocol; as such, it operates between two nodes that are topologically adjacent in a BP network (but in this case the BP network within which the nodes are topologically adjacent is an overlay on top of the real BP network). Since the sending and receiving nodes are topologically adjacent they are neighbors: the sending node MUST have an egress plan for transmission to the receiving (that is, peer) node, and there MUST be a BIBE outduct attached to that plan.
Routing
In order to compel bundles bound for some destination node to be forwarded via the BIBE peer node rather than over some other route computed by CGR, you have to override CGR routing for that bundle. The way to do this is to (a) tag the bundle with data label X (in ancillary data) and (b) use ipnadmin to establish at the sending node a routing override that coerces all bundles with data label X to be sent directly to the peer node.
If the peer node happens to be a true BP neighbor as well - that is, there is also a non-BIBE outduct attached to the egress plan for transmission to that node - then you additionally need to tell the egress plan management daemon (bpclm) for that node which bundles need to be forwarded using the BIBE outduct rather than the non-BIBE outduct. The way to do this is to use ipnadmin to establish at the sending node a class-of-service override that locally and temporarily OR's the BP_BIBE_REQUESTED flag (32) to the quality-of-service flags of any bundle tagged with data label X.
Quality of Service
If you want custody transfer to be invoked for each BIBE transmission of a bundle from the sending node to the peer node, you must additionally use ipnadmin to establish at the sending node a class-of-service override that locally and temporarily OR's the BP_CT_REQUESTED flag (64) to the quality-of-service flags of any bundle tagged with data label X.
If you need to establish a class-of-service override to set the BP_BIBE_REQUESTED flag (as described above) as well, then use the OR of BP_BIBE_REQUESTED and BP_CT_REQUESTED - that is, 96 - as the quality-of-service flags argument for that override.
NOTE that an alternative method of setting both the BP_BIBE_REQUESTED and BP_CT_REQUESTED flags for a given bundle is simply to request custody transfer when the bundle is sourced; this will OR that bundle's own quality-of-service flags (in ancillary data) with 96. But be careful: in this case the bundle will be permanently tagged with these flag values, meaning that it will be forwarded via BIBE with custody transfer over every \"hop\" of the end-to-end path to its destination, and if BIBE is unavailable at any forwarding node on the path then the bundle can never reach the destination node.
?
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 bibeadmin to be logged as well as sent to stdout. Setting echo to 0 disables this behavior.
w { 0 | 1 | activity_spec }
The watch command. This command enables and disables production of a continuous stream of user-selected Bundle-in-Bundle Encapsulation custody transfer activity indication characters. A watch parameter of \"1\" selects all BIBE-CT activity indication characters; \"0\" de-selects all BIBE-CT activity indication characters; any other activity_spec such as \"mw\" selects all activity indicators in the string, de-selecting all others. BIBE will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
w custody of bundle is accepted
m custody acceptance is received for one bundle
x custody of bundle is refused
& custody refusal is received for one bundle
$ bundle retransmitted due to expired custodial retransmission interval
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a bcla peer_EID fwd_latency rtn_latency time_to_live priority ordinal [data label]
The add bcla command. This command adds the neighboring node identified by peer_EID as a BIBE destination of the local node.
c bcla peer_EID fwd_latency rtn_latency time_to_live priority ordinal [data label]
The change bcla command. This command changes the transmission parameters governing BIBE PDU transmission to the indicated peer node.
d bcla peer_EID
The delete bcla command. This command deletes the bcla identified by peer_EID.
i bcla peer_EID
This command will print information (the transmission parameters) for the BIBE peer node identified by peer_EID.
l
This command lists all of the local node's BIBE peers.
a bcla ipn:3.2 10 10 60 1 0 16
Declares that ipn:3.2 is a BIBE destination and that BIBE PDUs destined for this node are to be sent with TTL 60 seconds, priority 1 (standard), and data label 16; it is expected that BIBE PDUs sent to this node will arrive within 10 seconds and that BIBE PDUs sent from this node will arrive within 10 seconds.
bibeadmin(1), bibeclo(1)
"},{"location":"man/bpv7/bp/","title":"NAME","text":"bp - Bundle Protocol communications library
"},{"location":"man/bpv7/bp/#synopsis","title":"SYNOPSIS","text":"#include \"bp.h\"\n\n[see description for available functions]\nThe bp library provides functions enabling application software to use Bundle Protocol to send and receive information over a delay-tolerant network. It conforms to the Bundle Protocol specification as documented in Internet RFC 5050.
int bp_attach( )
Attaches the application to BP functionality on the local computer. Returns 0 on success, -1 on any error.
Note that all ION libraries and applications draw memory dynamically, as needed, from a shared pool of ION working memory. The size of the pool is established when ION node functionality is initialized by ionadmin(1). This is a precondition for initializing BP functionality by running bpadmin(1), which in turn is required in order for bp_attach() to succeed.
Sdr bp_get_sdr( )
Returns handle for the SDR data store used for BP, to enable creation and interrogation of bundle payloads (application data units).
void bp_detach( )
Terminates all access to BP functionality on the local computer.
int bp_open(char *eid, BpSAP *ionsapPtr)
Opens the application's access to the BP endpoint identified by eid, so that the application can take delivery of bundles destined for the indicated endpoint. This SAP can also be used for sending bundles whose source is the indicated endpoint; all bundles sent via this SAP will be subject to immediate destruction upon transmission, i.e., no bundle addresses will be returned by bp_send() for use in tracking, suspending/resuming, or cancelling transmission of these bundles. On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
int bp_open_source(char *eid, BpSAP *ionsapPtr, detain)
Opens the application's access to the BP endpoint identified by eid, so that the application can send bundles whose source is the indicated endpoint. If and only if the value of detain is non-zero, citing this SAP in an invocation of bp_send() will cause the address of the newly issued bundle to be returned for use in tracking, suspending/resuming, or cancelling transmission of this bundle. USE THIS FEATURE WITH GREAT CARE: such a bundle will continue to occupy storage resources until it is explicitly released by an invocation of bp_release() or until its time to live expires, so bundle detention increases the risk of resource exhaustion. (If the value of detain is zero, all bundles sent via this SAP will be subject to immediate destruction upon transmission.) On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
int bp_send(BpSAP sap, char *destEid, char *reportToEid, int lifespan, int classOfService, BpCustodySwitch custodySwitch, unsigned char srrFlags, int ackRequested, BpAncillaryData *ancillaryData, Object adu, Object *newBundle)
Sends a bundle to the endpoint identified by destEid, from the source endpoint as provided to the bp_open() call that returned sap. When sap is NULL, the transmitted bundle is anonymous, i.e., the source of the bundle is not identified. This is legal, but anonymous bundles cannot be uniquely identified; status reporting therefore cannot be requested for an anonymous bundle.
reportToEid identifies the endpoint to which any status reports pertaining to this bundle will be sent; if NULL, defaults to the source endpoint.
lifespan is the maximum number of seconds that the bundle can remain in-transit (undelivered) in the network prior to automatic deletion.
classOfService is simply priority for now: BP_BULK_PRIORITY, BP_STD_PRIORITY, or BP_EXPEDITED_PRIORITY. If class-of-service flags are defined in a future version of Bundle Protocol, those flags would be OR'd with priority.
custodySwitch indicates whether or not custody transfer is requested for this bundle and, if so, whether or not the source node itself is required to be the initial custodian. The valid values are SourceCustodyRequired, SourceCustodyOptional, NoCustodyRequired. Note that custody transfer can take effect only for segments of the end-to-end path that are traversed using the Bundle-in-Bundle Encapsulation protocol at the \"convergence layer\"; however, requesting custody transfer is interpreted by ION as a request to use \"reliable\" convergence-layer protocols over all segments of the end-to-end path, whether implemented by custody transfer or not.
srrFlags, if non-zero, is the logical OR of the status reporting behaviors requested for this bundle: BP_RECEIVED_RPT, BP_FORWARDED_RPT, BP_DELIVERED_RPT, BP_DELETED_RPT.
ackRequested is a Boolean parameter indicating whether or not the recipient application should be notified that the source application requests some sort of application-specific end-to-end acknowledgment upon receipt of the bundle.
ancillaryData, if not NULL, is used to populate the Extended Class Of Service block for this bundle. The block's ordinal value is used to provide fine-grained ordering within \"expedited\" traffic: ordinal values from 0 (the default) to 254 (used to designate the most urgent traffic) are valid, with 255 reserved for custody signals. Note that the insertion of application-specific extension blocks into the bundle, in addition to the canonical extension blocks inserted automatically per the bpextensions.c file, may be requested by listing those blocks in the extensions variable of the ancillaryData block. The value of the block's flags is the logical OR of the applicable extended class-of-service flags:
BP\\_MINIMUM\\_LATENCY designates the bundle as \"critical\" for the\npurposes of Contact Graph Routing.\n\nBP\\_BEST\\_EFFORT signifies that non-reliable convergence-layer protocols, as\navailable, may be used to transmit the bundle. Notably, the bundle may be\nsent as \"green\" data rather than \"red\" data when issued via LTP.\n\nBP\\_DATA\\_LABEL\\_PRESENT signifies whether or not the value of _dataLabel_\nin _ancillaryData_ must be encoded into the ECOS block when the bundle is\ntransmitted.\nadu is the \"application data unit\" that will be conveyed as the payload of the new bundle. adu must be a \"zero-copy object\" (ZCO). To ensure orderly access to transmission buffer space for all applications, adu must be created by invoking ionCreateZco(), which may be configured either to block so long as insufficient ZCO storage space is available for creation of the requested ZCO or to fail immediately if insufficient ZCO storage space is available.
The function returns 1 on success, 0 on user error, -1 on any system error. If 0 is returned, then an invalid argument value was passed to bp_send(); a message to this effect will have been written to the log file. If 1 is returned, then either the destination of the bundle was \"dtn:none\" (the bit bucket) or the ADU has been accepted and queued for transmission in a bundle. In the latter case, if and only if sap was a reference to a BpSAP returned by an invocation of bp_open_source() that had a non-zero value in the detain parameter, then newBundle must be non-NULL and the address of the newly created bundle within the ION database is placed in newBundle. This address can be used to track, suspend/resume, or cancel transmission of the bundle.
int bp_track(Object bundle, Object trackingElt)
Adds trackingElt to the list of \"tracking\" references in bundle. trackingElt must be the address of an SDR list element -- whose data is the address of this same bundle -- within some list of bundles that is privately managed by the application. Upon destruction of the bundle this list element will automatically be deleted, thus removing the bundle from the application's privately managed list of bundles. This enables the application to keep track of bundles that it is operating on without risk of inadvertently de-referencing the address of a nonexistent bundle.
void bp_untrack(Object bundle, Object trackingElt)
Removes trackingElt from the list of \"tracking\" references in bundle, if it is in that list. Does not delete trackingElt itself.
int bp_suspend(Object bundle)
Suspends transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or if the bundle is already suspended. Otherwise, reverses the enqueuing of the bundle to its selected transmission outduct and places it in the \"limbo\" queue until the suspension is lifted by calling bp_resume. Returns 0 on success, -1 on any error.
int bp_resume(Object bundle)
Terminates suspension of transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or is not suspended. Otherwise, removes the bundle from the \"limbo\" queue and queues it for route re-computation and re-queuing. Returns 0 on success, -1 on any error.
int bp_cancel(Object bundle)
Cancels transmission of bundle. If the indicated bundle is currently queued for forwarding, transmission, or retransmission, it is removed from the relevant queue and destroyed exactly as if its Time To Live had expired. Returns 0 on success, -1 on any error.
int bp_release(Object bundle)
Releases a detained bundle for destruction when all retention constraints have been removed. After a detained bundle has been released, the application can no longer track, suspend/resume, or cancel its transmission. Returns 0 on success, -1 on any error.
int bp_receive(BpSAP sap, BpDelivery *dlvBuffer, int timeoutSeconds)
Receives a bundle, or reports on some failure of bundle reception activity.
The \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one bundle destined for the endpoint for which this SAP is opened has not yet been delivered to the SAP, then the payload of the oldest such bundle will be returned in dlvBuffer->adu and dlvBuffer->result will be set to BpPayloadPresent. If there is no such bundle, bp_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is BP_POLL (i.e., zero) and no bundle is awaiting delivery, or if timeoutSeconds is greater than zero but no bundle arrives before timeoutSeconds have elapsed, then dlvBuffer->result will be set to BpReceptionTimedOut. If timeoutSeconds is BP_BLOCKING (i.e., -1) then bp_receive() blocks until either a bundle arrives or the function is interrupted by an invocation of bp_interrupt().
dlvBuffer->result will be set to BpReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer->result will be set to BpEndpointStopped in the event that the operation of the indicated endpoint has been terminated.
The application data unit delivered in the data delivery structure, if any, will be a \"zero-copy object\" reference. Use zco reception functions (see zco(3)) to read the content of the application data unit.
Be sure to call bp_release_delivery() after every successful invocation of bp_receive().
The function returns 0 on success, -1 on any error.
void bp_interrupt(BpSAP sap)
Interrupts a bp_receive() invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, sap may need to be obtained from a static variable.
void bp_release_delivery(BpDelivery *dlvBuffer, int releaseAdu)
Releases resources allocated to the indicated delivery. releaseAdu is a Boolean parameter: if non-zero, the ADU ZCO reference in dlvBuffer (if any) is destroyed, causing the ZCO itself to be destroyed if no other references to it remain.
void bp_close(BpSAP sap)
Terminates the application's access to the BP endpoint identified by the eid cited by the indicated service access point. The application relinquishes its ability to take delivery of bundles destined for the indicated endpoint and to send bundles whose source is the indicated endpoint.
bpadmin(1), lgsend(1), lgagent(1), bpextensions(3), bprc(5), lgfile(5)
"},{"location":"man/bpv7/bpadmin/","title":"NAME","text":"bpadmin - ION Bundle Protocol (BP) administration interface
"},{"location":"man/bpv7/bpadmin/#synopsis","title":"SYNOPSIS","text":"bpadmin [ commands_filename | . | ! ]
"},{"location":"man/bpv7/bpadmin/#description","title":"DESCRIPTION","text":"bpadmin configures, starts, manages, and stops bundle protocol operations for the local ION node.
It operates in response to BP configuration commands found in the file commands_filename, if provided; if not, bpadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to bpadmin -- that is, the ION node's bpclock task, forwarder tasks, and convergence layer adapter tasks are stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's bpclock task, forwarder tasks, and convergence layer adapter tasks are restarted.
The format of commands for commands_filename can be queried from bpadmin with the 'h' or '?' commands at the prompt. The commands are documented in bprc(5).
"},{"location":"man/bpv7/bpadmin/#exit-status","title":"EXIT STATUS","text":"bpadmin
Enter interactive BP configuration command entry mode.
bpadmin host1.bp
Execute all configuration commands in host1.bp, then terminate immediately.
bpadmin .
Stop all bundle protocol operations on the local node.
See bprc(5) for details of the BP configuration commands.
"},{"location":"man/bpv7/bpadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the bprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bpadmin. Otherwise bpadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ION can't set custodian EID information.
The custodial_endpoint_id specified in the BP initialization ('1') command is malformed. Remember that the format for this argument is ipn:element_number.0 and that the final 0 is required, as custodial/administration service is always service 0. Additional detail for this error is provided if one of the following other errors is present:
Malformed EID.\n\nMalformed custodian EID.\nbpadmin can't attach to ION.
There is no SDR data store for bpadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bpadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see bprc(5) for details.
"},{"location":"man/bpv7/bpadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpadmin/#see-also","title":"SEE ALSO","text":"ionadmin(1), bprc(5), ipnadmin(1), ipnrc(5), dtnadmin(1), dtnrc(5)
"},{"location":"man/bpv7/bpcancel/","title":"NAME","text":"bpcancel - Bundle Protocol (BP) bundle cancellation utility
"},{"location":"man/bpv7/bpcancel/#synopsis","title":"SYNOPSIS","text":"bpcancel source_EID creation_seconds [creation_count [fragment_offset [fragment_length]]]
"},{"location":"man/bpv7/bpcancel/#description","title":"DESCRIPTION","text":"bpcancel attempts to locate the bundle identified by the command-line parameter values and cancel transmission of this bundle. Bundles for which multiple copies have been queued for transmission can't be canceled, because one or more of those copies might already have been transmitted. Transmission of a bundle that has never been cloned and that is still in local bundle storage is cancelled by simulation of an immediate time-to-live expiration.
"},{"location":"man/bpv7/bpcancel/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcancel has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bpcancel/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpcancel/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
bpcancel failed finding bundle.
The attempt to locate the subject bundle failed due to some serious system error. It will probably be necessary to terminate and re-initialize the local ION node.
bpcancel failed destroying bundle.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpcancel failed.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpcancel/#see-also","title":"SEE ALSO","text":"bplist(1)
"},{"location":"man/bpv7/bpchat/","title":"NAME","text":"bpchat - Bundle Protocol chat test program
"},{"location":"man/bpv7/bpchat/#synopsis","title":"SYNOPSIS","text":"bpchat sourceEID destEID [ct]
"},{"location":"man/bpv7/bpchat/#description","title":"DESCRIPTION","text":"bpchat uses Bundle Protocol to send input text in bundles, and display the payload of received bundles as output. It is similar to the talk utility, but operates over the Bundle Protocol. It operates like a combination of the bpsource and bpsink utilities in one program (unlike bpsource, bpchat emits bundles with a sourceEID).
If the sourceEID and destEID are both bpchat applications, then two users can chat with each other over the Bundle Protocol: lines that one user types on the keyboard will be transported over the network in bundles and displayed on the screen of the other user (and the reverse).
bpchat terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv7/bpchat/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpchat has terminated normally. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpchat has terminated due to a BP transmit or reception failure. Details should be noted in the ion.log log file.
If the string \"ct\" is appended as the last argument, then bundles will be sent with custody transfer requested.
No configuration files are needed.
"},{"location":"man/bpv7/bpchat/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpchat/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpchat are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpchat bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpchat can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpchat/#see-also","title":"SEE ALSO","text":"bpecho(1), bpsource(1), bpsink(1), bp(3)
"},{"location":"man/bpv7/bpclm/","title":"NAME","text":"bpclm - DTN bundle protocol convergence layer management daemon
"},{"location":"man/bpv7/bpclm/#synopsis","title":"SYNOPSIS","text":"bpclm neighboring_node_ID
"},{"location":"man/bpv7/bpclm/#description","title":"DESCRIPTION","text":"bpclm is a background \"daemon\" task that manages the transmission of bundles to a single designated neighboring node (as constrained by an \"egress plan\" data structure for that node) by one or more convergence-layer (CL) adapter output daemons (via buffer structures called \"outducts\").
bpclm is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. bpclm can also be spawned and terminated in response to commands that START and STOP the corresponding node's egress plan.
"},{"location":"man/bpv7/bpclm/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpclm terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the egress plan for this node.
\"1\"
bpclm terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the egress plan for this node.
No configuration files are needed.
"},{"location":"man/bpv7/bpclm/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpclm/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpclm can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No egress plan for this node
No egress plan for the node identified by neighboring_node_ID has been added to the BP database. Use bpadmin to add and start the plan.
bpclm task is already started for this node
Redundant initiation of bpclm.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpclm/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/bpclock/","title":"NAME","text":"bpclock - Bundle Protocol (BP) daemon task for managing scheduled events
"},{"location":"man/bpv7/bpclock/#synopsis","title":"SYNOPSIS","text":"bpclock
"},{"location":"man/bpv7/bpclock/#description","title":"DESCRIPTION","text":"bpclock is a background \"daemon\" task that periodically performs scheduled Bundle Protocol activities. It is spawned automatically by bpadmin in response to the 's' command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command.
Once per second, bpclock takes the following action:
First it (a) destroys all bundles whose TTLs have expired, (b) enqueues for re-forwarding all bundles that were expected to have been transmitted (by convergence-layer output tasks) by now but are still stuck in their assigned transmission queues, and (c) enqueues for re-forwarding all bundles for which custody has not yet been taken that were expected to have been received and acknowledged by now (as noted by invocation of the bpMemo() function by some convergence-layer adapter that had CL-specific insight into the appropriate interval to wait for custody acceptance).
Then bpclock adjusts the transmission and reception \"throttles\" that control rates of LTP transmission to and reception from neighboring nodes, in response to data rate changes as noted in the RFX database by rfxclock.
bpclock then checks for bundle origination activity that has been blocked due to insufficient allocated space for BP traffic in the ION data store: if space for bundle origination is now available, bpclock gives the bundle production throttle semaphore to unblock that activity.
Finally, bpclock applies rate control to all convergence-layer protocol inducts and outducts:
For each induct, bpclock increases the current capacity of the duct by the applicable nominal data reception rate. If the revised current capacity is greater than zero, bpclock gives the throttle's semaphore to unblock data acquisition (which correspondingly reduces the current capacity of the duct) by the associated convergence layer input task.
For each outduct, bpclock increases the current capacity of the duct by the applicable nominal data transmission rate. If the revised current capacity is greater than zero, bpclock gives the throttle's semaphore to unblock data transmission (which correspondingly reduces the current capacity of the duct) by the associated convergence layer output task.
"},{"location":"man/bpv7/bpclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bpclock.
\"1\"
bpclock was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/bpclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpclock can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't dispatch events.
An unrecoverable database error was encountered. bpclock terminates.
Can't adjust throttles.
An unrecoverable database error was encountered. bpclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpclock/#see-also","title":"SEE ALSO","text":"bpadmin(1), rfxclock(1)
"},{"location":"man/bpv7/bpcounter/","title":"NAME","text":"bpcounter - Bundle Protocol reception test program
"},{"location":"man/bpv7/bpcounter/#synopsis","title":"SYNOPSIS","text":"bpcounter ownEndpointId [maxCount]
"},{"location":"man/bpv7/bpcounter/#description","title":"DESCRIPTION","text":"bpcounter uses Bundle Protocol to receive application data units from a remote bpdriver application task. When the total number of application data units it has received exceeds maxCount, it terminates and prints its reception count. If maxCount is omitted, the default limit is 2 billion application data units.
"},{"location":"man/bpv7/bpcounter/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcounter has terminated. Any problems encountered during operation will be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv7/bpcounter/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpcounter/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpcounter are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpcounter bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpcounter/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpdriver(1), bpecho(1), bp(3)
"},{"location":"man/bpv7/bpdriver/","title":"NAME","text":"bpdriver - Bundle Protocol transmission test program
"},{"location":"man/bpv7/bpdriver/#synopsis","title":"SYNOPSIS","text":"bpdriver nbrOfCycles ownEndpointId destinationEndpointId [length] [t_TTL_] [i_Injection Rate_]
"},{"location":"man/bpv7/bpdriver/#description","title":"DESCRIPTION","text":"bpdriver uses Bundle Protocol to send nbrOfCycles application data units of length indicated by length, to a counterpart application task that has opened the BP endpoint identified by destinationEndpointId.
If omitted, length defaults to 60000.
TTL indicates the number of seconds the bundles may remain in the network, undelivered, before they are automatically destroyed. If omitted, TTL defaults to 300 seconds.
bpdriver normally runs in \"echo\" mode: after sending each bundle it waits for an acknowledgment bundle before sending the next one. For this purpose, the counterpart application task should be bpecho.
Alternatively bpdriver can run in \"streaming\" mode, i.e., without expecting or receiving acknowledgments. Streaming mode is enabled when length is specified as a negative number, in which case the additive inverse of length is used as the effective value of length. For this purpose, the counterpart application task should be bpcounter.
If the effective value of length is 1, the sizes of the transmitted service data units will be randomly selected multiples of 1024 in the range 1024 to 62464.
Injection Rate specifies in bits-per-second the equivalent, average rate at which bpdriver will send bundles into the network. A negative or 0 rate value will turn off injection rate control. By default, bpdriver will inject bundle as fast as it can be handled by ION unless a positive value for injection rate is provided.
bpdriver normally runs with custody transfer disabled. To request custody transfer for all bundles sent by bpdriver, specify nbrOfCycles as a negative number; the additive inverse of nbrOfCycles will be used as its effective value in this case.
When all copies of the file have been sent, bpdriver prints a performance report.
"},{"location":"man/bpv7/bpdriver/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpdriver has terminated. Any problems encountered during operation will be noted in the ion.log log file.
The service data units transmitted by bpdriver are sequences of text obtained from a file in the current working directory named \"bpdriverAduFile\", which bpdriver creates automatically.
"},{"location":"man/bpv7/bpdriver/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpdriver/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpdriver are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
Can't create ADU file
Operating system error. Check errtext, correct problem, and rerun.
Error writing to ADU file
Operating system error. Check errtext, correct problem, and rerun.
bpdriver can't create file ref.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpdriver can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpdriver can't send message
Bundle Protocol service to the remote endpoint has been stopped.
bpdriver reception failed
bpdriver is in \"echo\" mode, and Bundle Protocol delivery service has been stopped.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpdriver/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpcounter(1), bpecho(1), bp(3)
"},{"location":"man/bpv7/bpecho/","title":"NAME","text":"bpecho - Bundle Protocol reception test program
"},{"location":"man/bpv7/bpecho/#synopsis","title":"SYNOPSIS","text":"bpecho ownEndpointId
"},{"location":"man/bpv7/bpecho/#description","title":"DESCRIPTION","text":"bpecho uses Bundle Protocol to receive application data units from a remote bpdriver application task. In response to each received application data unit it sends back an \"echo\" application data unit of length 2, the NULL-terminated string \"x\".
bpecho terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv7/bpecho/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpecho has terminated normally. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpecho has terminated due to a BP reception failure. Details should be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv7/bpecho/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpecho/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpecho are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpecho bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpecho can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpecho/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpdriver(1), bpcounter(1), bp(3)
"},{"location":"man/bpv7/bpextensions/","title":"NAME","text":"bpextensions - interface for adding extensions to Bundle Protocol
"},{"location":"man/bpv7/bpextensions/#synopsis","title":"SYNOPSIS","text":"#include \"bpextensions.c\"\nION's interface for extending the Bundle Protocol enables the definition of external functions that insert extension blocks into outbound bundles (either before or after the payload block), parse and record extension blocks in inbound bundles, and modify extension blocks at key points in bundle processing. All extension-block handling is statically linked into ION at build time, but the addition of an extension never requires that any standard ION source code be modified.
Standard structures for recording extension blocks -- both in transient storage [memory] during bundle acquisition (AcqExtBlock) and in persistent storage [the ION database] during subsequent bundle processing (ExtensionBlock) -- are defined in the bei.h header file. In each case, the extension block structure comprises a block type code, block processing flags, possibly a list of EID references, an array of bytes (the serialized form of the block, for transmission), the length of that array, optionally an extension-specific opaque object whose structure is designed to characterize the block in a manner that's convenient for the extension processing functions, and the size of that object.
The definition of each extension is asserted in an ExtensionDef structure, also as defined in the bei.h header file. Each ExtensionDef must supply:
The name of the extension. (Used in some diagnostic messages.)
The extension's block type code.
A pointer to an offer function.
A pointer to a function to be called when forwarding a bundle containing this sort of block.
A pointer to a function to be called when taking custody of a bundle containing this sort of block.
A pointer to a function to be called when enqueuing for transmission a bundle containing this sort of block.
A pointer to a function to be called when a convergence-layer adapter dequeues a bundle containing this sort of block, before serializing it.
A pointer to a function to be called immediately before a convergence-layer adapter transmits a bundle containing this sort of block, after the bundle has been serialized.
A pointer to a release function.
A pointer to a copy function.
A pointer to an acquire function.
A pointer to a review function.
A pointer to a decrypt function.
A pointer to a parse function.
A pointer to a check function.
A pointer to a record function.
A pointer to a clear function.
All extension definitions must be coded into an array of ExtensionDef structures named extensionDefs.
An array of ExtensionSpec structures named extensionSpecs is also required. Each ExtensionSpec provides the specification for producing an outbound extension block: block definition (identified by block type number), three discriminator tags whose semantics are block-type-specific, and CRC type indicating what type of CRC must be used to protect this extension block. The order of appearance of extension specifications in the extensionSpecs array determines the order in which extension blocks will be inserted into locally sourced bundles.
The standard extensionDefs array -- which is empty -- is in the noextensions.c prototype source file. The procedure for extending the Bundle Protocol in ION is as follows:
1. Specify -DBP_EXTENDED in the Makefile's compiler command line when building the libbpP.c library module.
2. Create a copy of the prototype extensions file, named \"bpextensions.c\", in a directory that is made visible to the Makefile's libbpP.c compilation command line (by a -I parameter).
3. In the \"external function declarations\" area of \"bpextensions.c\", add \"extern\" function declarations identifying the functions that will implement your extension (or extensions).
4. Add one or more ExtensionDef structure initialization lines to the extensionDefs array, referencing those declared functions.
5. Add one or more ExtensionSpec structure initialization lines to the extensionSpecs array, referencing those extension definitions.
6. Develop the implementations of the extension implementation functions in one or more new source code files.
7. Add the object file or files for the new extension implementation source file (or files) to the Makefile's command line for linking libbpP.so.
The function pointers supplied in each ExtensionDef must conform to the following specifications. NOTE that any function that modifies the bytes member of an ExtensionBlock or AckExtBlock must set the corresponding length to the new length of the bytes array, if changed.
int (*BpExtBlkOfferFn)(ExtensionBlock *blk, Bundle *bundle)
Populates all fields of the indicated ExtensionBlock structure for inclusion in the indicated outbound bundle. This function is automatically called when a new bundle is locally sourced or upon acquisition of a remotely sourced bundle that does not contain an extension block of this type. The values of the extension block are typically expected to be a function of the state of the bundle, but this is extension-specific. If it is not appropriate to offer an extension block of this type as part of this bundle, then the size, length, object, and bytes members of blk must all be set to zero. If it is appropriate to offer such a block but no internal object representing the state of the block is needed, the object and size members of blk must be set to zero. The type, blkProcFlags, and dataLength members of blk must be populated by the implementation of the \"offer\" function, but the length and bytes members are typically populated by calling the BP library function serializeExtBlk(), which must be passed the block to be serialized (with type, blkProcFlags and dataLength already set), a Lyst of EID references (two list elements -- offsets -- per EID reference, if applicable; otherwise NULL), and a pointer to the extension-specific block data. The block's bytes array and object (if present) must occupy space allocated from the ION database heap. Return zero on success, -1 on any system failure.
int (*BpExtBlkProcessFn)(ExtensionBlock *blk, Bundle *bundle, void *context)
Performs some extension-specific transformation of the data encapsulated in blk based on the state of bundle. The transformation to be performed will typically vary depending on whether the identified function is the one that is automatically invoked upon forwarding the bundle, upon taking custody of the bundle, upon enqueuing the bundle for transmission, upon removing the bundle from the transmission queue, or upon transmitting the serialized bundle. The context argument may supply useful supplemental information; in particular, the context provided to the ON_DEQUEUE function will comprise the name of the protocol for the duct from which the bundle has been dequeued, together with the EID of the neighboring node endpoint to which the bundle will be directly transmitted when serialized. The block-specific data in blk is located within bytes immediately after the header of the extension block; the length of the block's header is the difference between length and dataLength. Whenever the block's blkProcFlags, EID extensions, and/or block-specific data are altered, the serializeExtBlk() function should be called again to recalculate the size of the extension block and rebuild the bytes array. Return zero on success, -1 on any system failure.
void (*BpExtBlkReleaseFn)(ExtensionBlock *blk)
Releases all ION database space occupied by the object member of blk. This function is automatically called when a bundle is destroyed. Note that incorrect implementation of this function may result in a database space leak.
int (*BpExtBlkCopyFn)(ExtensionBlock *newblk, ExtensionBlock *oldblk)
Copies the object member of oldblk to ION database heap space and places the address of that new non-volatile object in the object member of newblk, also sets size in newblk. This function is automatically called when two copies of a bundle are needed, e.g., in the event that it must both be delivered to a local client and also fowarded to another node. Return zero on success, -1 on any system failure.
int (*BpAcqExtBlkAcquireFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Populates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is only to be provided for extension blocks that are never encrypted; a extension block that may be encrypted should have a BpAcqExtBlkParseFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkReviewFn)(AcqWorkArea *work)
Reviews the extension blocks that have been acquired for this bundle, checking to make sure that all blocks of this type that are required by policy are present. Returns 0 if any blocks are missing, 1 if all required blocks are present, -1 on any system failure.
int (*BpAcqExtBlkDecryptFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Decrypts some other extension block that has been acquired but not yet parsed, nominally using encapsulated ciphersuite information. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if no error in decryption was encountered, -1 on any system failure.
int (*BpAcqExtBlkParseFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Populates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is provided for extension blocks that may be encrypted; a extension block that can never be encrypted should have a BpAcqExtBlkAcquireFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkCheckFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Examines the bundle in work to determine whether or not it is authentic, in the context of the indicated extension block. Return 1 if the block is determined to be inauthentic (this will cause the bundle to be discarded), zero if no inauthenticity is detected, -1 on any system failure.
int (*BpExtBlkRecordFn)(ExtensionBlock *blk, AcqExtBlock *acqblk)
Copies the object member of acqblk to ION database heap space and places the address of that non-volatile object in the object member of blk; also sets size in blk. This function is automatically called when an acquired bundle is accepted for forwarding and/or delivery. Return zero on success, -1 on any system failure.
void (*BpAcqExtBlkClearFn)(AcqExtBlock *acqblk)
Uses MRELEASE to release all ION working memory occupied by the object member of acqblk. This function is automatically called when acquisition of a bundle is completed, whether or not the bundle is accepted. Note that incorrect implementation of this function may result in a working memory leak.
void discardExtensionBlock(AcqExtBlock *blk)
Deletes this block from the bundle acquisition work area prior to the recording of the bundle in the ION database.
void scratchExtensionBlock(ExtensionBlock *blk)
Deletes this block from the bundle after the bundle has been recorded in the ION database.
Object findExtensionBlock(Bundle *bundle, unsigned int type, unsigned char tag1, unsigned char tag2, unsigned char tag3)
On success, returns the address of the ExtensionBlock in bundle for the indicated type and tag values. If no such extension block exists, returns zero.
int serializeExtBlk(ExtensionBlock *blk, char *blockData)
Constructs a BPv7-conformant serialized representation of this extension block in blk->bytes. Returns 0 on success, -1 on an unrecoverable system error.
void suppressExtensionBlock(ExtensionBlock *blk)
Causes blk to be omitted when the bundle to which it is attached is serialized for transmission. This suppression remains in effect until it is reversed by restoreExtensionBlock();
void restoreExtensionBlock(ExtensionBlock *blk)
Reverses the effect of suppressExtensionBlock(), enabling the block to be included when the bundle to which it is attached is serialized.
bp(3)
"},{"location":"man/bpv7/bping/","title":"NAME","text":"bping - Send and receive Bundle Protocol echo bundles.
"},{"location":"man/bpv7/bping/#synopsis","title":"SYNOPSIS","text":"bping [-c count] [-i interval] [-p priority] [-q wait] [-r flags] [-t ttl] srcEID destEID [reporttoEID]
"},{"location":"man/bpv7/bping/#description","title":"DESCRIPTION","text":"bping sends bundles from srcEID to destEID. If the destEID echoes the bundles back (for instance, it is a bpecho endpoint), bping will print the round-trip time. When complete, bping will print statistics before exiting. It is very similar to ping, except it works with the bundle protocol.
bping terminates when one of the following happens: it receives the SIGINT signal (Ctrl+C), it receives responses to all of the bundles it sent, or it has sent all count of its bundles and waited wait seconds.
When bping is executed in a VxWorks or RTEMS environment, its runtime arguments are presented positionally rather than by keyword, in this order: count, interval, priority, wait, flags, TTL, verbosity (a Boolean, defaulting to zero), source EID, destination EID, report-to EID.
Source EID and destination EID are always required.
"},{"location":"man/bpv7/bping/#exit-status","title":"EXIT STATUS","text":"These exit statuses are taken from ping.
\"0\"
bping has terminated normally, and received responses to all the packets it sent.
\"1\"
bping has terminated normally, but it did not receive responses to all the packets it sent.
\"2\"
bping has terminated due to an error. Details should be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv7/bping/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bping/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bping are written to the ION log file ion.log and printed to standard error. Diagnostic messages that don't cause bping to terminate indicate a failure parsing an echo response bundle. This means that destEID isn't an echo endpoint: it's responding with some other bundle message of an unexpected format.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bping bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bping can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bping/#see-also","title":"SEE ALSO","text":"bpecho(1), bptrace(1), bpadmin(1), bp(3), ping(8)
"},{"location":"man/bpv7/bplist/","title":"NAME","text":"bplist - Bundle Protocol (BP) utility for listing queued bundles
"},{"location":"man/bpv7/bplist/#synopsis","title":"SYNOPSIS","text":"bplist [{count | detail} [destination_EID[/priority]]]
"},{"location":"man/bpv7/bplist/#description","title":"DESCRIPTION","text":"bplist is a utility program that reports on bundles that currently reside in the local node, as identified by entries in the local bundle agent's \"timeline\" list.
Either a count of bundles or a detailed list of bundles (noting primary block information together with hex and ASCII dumps of the payload and all extension blocks, in expiration-time sequence) may be requested.
Either all bundles or just a subset of bundles - restricted to bundles for a single destination endpoint, or to bundles of a given level of priority that are all destined for some specified endpoint - may be included in the report.
By default, bplist prints a detailed list of all bundles residing in the local node.
"},{"location":"man/bpv7/bplist/#exit-status","title":"EXIT STATUS","text":"\"0\"
bplist terminated, for reasons noted in the ion.log file.
\"1\"
bplist was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/bplist/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bplist/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bplist/#see-also","title":"SEE ALSO","text":"bpclock(1)
"},{"location":"man/bpv7/bpnmtest/","title":"NAME","text":"bpnmtest - Bundle Protocol (BP) network management statistics test
"},{"location":"man/bpv7/bpnmtest/#synopsis","title":"SYNOPSIS","text":"bpnmtest
"},{"location":"man/bpv7/bpnmtest/#description","title":"DESCRIPTION","text":"bpnmtest simply prints to stdout messages containing the current values of all BP network management tallies, then terminates.
"},{"location":"man/bpv7/bpnmtest/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpnmtest has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bpnmtest/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpnmtest/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bprc/","title":"NAME","text":"bprc - Bundle Protocol management commands file
"},{"location":"man/bpv7/bprc/#description","title":"DESCRIPTION","text":"Bundle Protocol management commands are passed to bpadmin either in a file of text lines or interactively at bpadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the Bundle Protocol management commands are described below.
"},{"location":"man/bpv7/bprc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 bpadmin 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 and the crypto suite BP was compiled with. HINT: combine with e 1 command to log the version number at startup.
1
The initialize command. Until this command is executed, Bundle Protocol is not in operation on the local ION node and most bpadmin commands will fail.
r 'command_text'
The run command. This command will execute command_text as if it had been typed at a console prompt. It is used to, for example, run another administrative program.
s
The start command. This command starts all schemes and all protocols on the local node.
m heapmax max_database_heap_per_acquisition
The manage heap for bundle acquisition command. This command declares the maximum number of bytes of SDR heap space that will be occupied by any single bundle acquisition activity (nominally the acquisition of a single bundle, but this is at the discretion of the convergence-layer input task). All data acquired in excess of this limit will be written to a temporary file pending extraction and dispatching of the acquired bundle or bundles. 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.
m maxcount max_value_of_bundle_ID_sequence_nbr
The manage maximum bundle ID sequence number command. This command sets the maximum value that will be assigned as the sequence number in a bundle ID for any bundle sourced at a node that lacks a synchronized clock (such that the creation time in the ID of every locally sourced bundle is always zero). The default value is -1, i.e., unlimited.
x
The stop command. This command stops all schemes and all protocols on the local node.
w { 0 | 1 | activity_spec }
The BP watch command. This command enables and disables production of a continuous stream of user-selected Bundle Protocol activity indication characters. A watch parameter of \"1\" selects all BP activity indication characters; \"0\" de-selects all BP activity indication characters; any other activity_spec such as \"acz~\" selects all activity indication characters in the string, de-selecting all others. BP will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
a new bundle is queued for forwarding
b bundle is queued for transmission
c bundle is popped from its transmission queue
y bundle is accepted upon arrival
z bundle is queued for delivery to an application
~ bundle is abandoned (discarded) on attempt to forward it
! bundle is destroyed due to TTL expiration
# bundle is queued for re-forwarding due to CL protocol failure
j bundle is placed in \"limbo\" for possible future re-forwarding
k bundle is removed from \"limbo\" and queued for re-forwarding
Note that a slightly amended interpretation should be applied to watch characters printed in the course of multicast transmission. The '~' character, meaning Abandoned (node did not forward this bundle), is printed by a node that is a leaf of the multicast tree, i.e., a node with no children; it cannot forward the bundle because it's got nobody to forward it to. The '!' character, meaning Destroyed (node destroyed a physical copy of a bundle), is printed by a node that has forwarded copies of the bundle to all of its children and no longer needs to retain the original - so it does an immediate permanent bundle destruction just as if the bundle's time to live had expired. Neither condition is anomalous.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a scheme scheme_name 'forwarder_command' 'admin_app_command'
The add scheme command. This command declares an endpoint naming \"scheme\" for use in endpoint IDs, which are structured as URIs: scheme_name:scheme-specific_part. forwarder_command will be executed when the scheme is started on this node, to initiate operation of a forwarding daemon for this scheme. admin_app_command will also be executed when the scheme is started on this node, to initiate operation of a daemon that opens a custodian endpoint identified within this scheme so that it can receive and process custody signals and bundle status reports.
c scheme scheme_name 'forwarder_command' 'admin_app_command'
The change scheme command. This command sets the indicated scheme's forwarder_command and admin_app_command to the strings provided as arguments.
d scheme scheme_name
The delete scheme command. This command deletes the scheme identified by scheme_name. The command will fail if any bundles identified in this scheme are pending forwarding, transmission, or delivery.
i scheme scheme_name
This command will print information (number and commands) about the endpoint naming scheme identified by scheme_name.
l scheme
This command lists all declared endpoint naming schemes.
s scheme scheme_name
The start scheme command. This command starts the forwarder and administrative endpoint tasks for the indicated scheme task on the local node.
x scheme scheme_name
The stop scheme command. This command stops the forwarder and administrative endpoint tasks for the indicated scheme task on the local node.
a endpoint endpoint_ID { q | x } ['recv_script']
The add endpoint command. This command establishes a DTN endpoint named endpoint_ID on the local node. The remaining parameters indicate what is to be done when bundles destined for this endpoint arrive at a time when no application has got the endpoint open for bundle reception. If 'x', then such bundles are to be discarded silently and immediately. If 'q', then such bundles are to be enqueued for later delivery and, if recv_script is provided, recv_script is to be executed.
c endpoint endpoint_ID { q | x } ['recv_script']
The change endpoint command. This command changes the action that is to be taken when bundles destined for this endpoint arrive at a time when no application has got the endpoint open for bundle reception, as described above.
d endpoint endpoint_ID
The delete endpoint command. This command deletes the endpoint identified by endpoint_ID. The command will fail if any bundles are currently pending delivery to this endpoint.
i endpoint endpoint_ID
This command will print information (disposition and script) about the endpoint identified by endpoint_ID.
l endpoint
This command lists all local endpoints, regardless of scheme name.
a protocol protocol_name [protocol_class]
The add protocol command. This command establishes access to the named convergence layer protocol at the local node.
The optional protocol_class argument indicates the reliability of the protocol. The value 1 indicates that the protocol natively supports bundle streaming; currently the only protocol in class 1 is BSSP. The value 2 indicates that the protocol performs no retransmission; an example is UDP. The value 8 (which is the default) indicates that the protocol detects data loss and automatically retransmits data accordingly; an example is TCP. Protocol class need not be specified when protocol_name is bssp, udp, tcp, stcp, brss, brsc, or ltp, as the protocol classes for these well-known protocols are hard-coded in ION.
In earlier versions of ION this command took two additional arguments, payload_bytes_per_frame and overhead_bytes_per_frame. These arguments are deprecated. BP configuration files that include a protocol commands in the old format will be processed correctly; the deprecated arguments will simply be ignored.
d protocol protocol_name
The delete protocol command. This command deletes the convergence layer protocol identified by protocol_name. The command will fail if any ducts are still locally declared for this protocol.
i protocol protocol_name
This command will print information about the convergence layer protocol identified by protocol_name.
l protocol
This command lists all convergence layer protocols that can currently be utilized at the local node.
s protocol protocol_name
The start protocol command. This command starts all induct and outduct tasks for inducts and outducts that have been defined for the indicated CL protocol on the local node.
x protocol protocol_name
The stop protocol command. This command stops all induct and outduct tasks for inducts and outducts that have been defined for the indicated CL protocol on the local node.
a induct protocol_name duct_name 'CLI_command'
The add induct command. This command establishes a \"duct\" for reception of bundles via the indicated CL protocol. The duct's data acquisition structure is used and populated by the \"induct\" task whose operation is initiated by CLI_command at the time the duct is started.
c induct protocol_name duct_name 'CLI_command'
The change induct command. This command changes the command that is used to initiate operation of the induct task for the indicated duct.
d induct protocol_name duct_name
The delete induct command. This command deletes the induct identified by protocol_name and duct_name. The command will fail if any bundles are currently pending acquisition via this induct.
i induct protocol_name duct_name
This command will print information (the CLI command) about the induct identified by protocol_name and duct_name.
l induct [protocol_name]
If protocol_name is specified, this command lists all inducts established locally for the indicated CL protocol. Otherwise it lists all locally established inducts, regardless of protocol.
s induct protocol_name duct_name
The start induct command. This command starts the indicated induct task as defined for the indicated CL protocol on the local node.
x induct protocol_name duct_name
The stop induct command. This command stops the indicated induct task as defined for the indicated CL protocol on the local node.
a outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The add outduct command. This command establishes a \"duct\" for transmission of bundles via the indicated CL protocol. The duct's data transmission structure is serviced by the \"outduct\" task whose operation is initiated by CLO_command at the time the duct is started. A value of zero for max_payload_length indicates that bundles of any size can be accommodated; this is the default.
c outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The change outduct command. This command sets new values for the indicated duct's payload size limit and the command that is used to initiate operation of the outduct task for this duct.
d outduct protocol_name duct_name
The delete outduct command. This command deletes the outduct identified by protocol_name and duct_name. The command will fail if any bundles are currently pending transmission via this outduct.
i outduct protocol_name duct_name
This command will print information (the CLO command) about the outduct identified by protocol_name and duct_name.
l outduct [protocol_name]
If protocol_name is specified, this command lists all outducts established locally for the indicated CL protocol. Otherwise it lists all locally established outducts, regardless of protocol.
s outduct protocol_name duct_name
The start outduct command. This command starts the indicated outduct task as defined for the indicated CL protocol on the local node.
x outduct protocol_name duct_name
The stop outduct command. This command stops the indicated outduct task as defined for the indicated CL protocol on the local node.
a plan endpoint_name [transmission_rate]
The add plan command. This command establishes an egress plan governing transmission to the neighboring node[s] identified by endpoint_name. The plan is functionally enacted by a bpclm(1) daemon dedicated to managing bundles queued for transmission to the indicated neighboring node[s].
NOTE that these \"plan\" commands supersede and generalize the egress plan commands documented in the ipnrc(5) and dtn2rc(5) man pages, which are retained for backward compatibility. The syntax of the egress plan commands consumed by bpadmin is DIFFERENT from that of the commands consumed by ipnadmin and dtn2admin. The endpoint_name identifying an egress plan is normally the node ID for a single node but may instead be \"wild-carded\". That is, when the last character of an endpoint name ID is either '*' or '~' (these two wild-card characters are equivalent for this purpose), the plan applies to all nodes whose IDs are identical to the wild-carded node name up to the wild-card character. For example, a bundle whose destination EID name is \"dtn://foghorn\" would be routed by plans citing the following node IDs: \"dtn://foghorn\", \"dtn://fogh*\", \"dtn://fog~\", \"//*\". When multiple plans are all applicable to the same destination EID, the one citing the longest (i.e., most narrowly targeted) node ID will be applied.
An egress plan may direct that bundles queued for transmission to the node[s] matching endpoint_name be transmitted using one of the convergence-layer protocol \"outducts\" that have been attached to the plan, or instead that those bundles be routed to some other \"gateway\" endpoint (resulting in transmission according to some other egress plan). In the event that both a gateway endpoint and one or more outducts have been declared for a given plan, the gateway declaration prevails.
A transmission_rate may be asserted for an egress plan; this rate is used as the basis for transmission rate control in the absence of applicable contacts (in the node's contact plan, as per ionrc(5)). A transmission rate of zero (absent applicable contacts) disables rate control completely; this is the default.
c plan endpoint_name [transmission_rate]
The change plan command. This command sets a new value for the indicated plan's transmission rate.
d plan endpoint_name
The delete plan command. This command deletes the plan identified by endpoint_name. The command will fail if any bundles are currently pending transmission per this plan.
i plan endpoint_name
This command will print information (the transmission rate) about the plan identified by endpoint_name.
l plan
This command lists all locally established egress plans.
s plan endpoint_name
The start plan command. This command starts the bpclm(1) task for the indicated egress plan.
x plan endpoint_name
The stop plan command. This command stops the bpclm(1) task for the indicated egress plan.
b plan endpoint_name
The block plan command. This command disables transmission of bundles queued for transmission to the indicated node and reforwards all non-critical bundles currently queued for transmission to this node. This may result in some or all of these bundles being enqueued for transmission (actually just retention) to the pseudo-node \"limbo\".
u plan endpoint_name
The unblock plan command. This command re-enables transmission of bundles to the indicated node and reforwards all bundles in \"limbo\" in the hope that the unblocking of this egress plan will enable some of them to be transmitted.
g plan endpoint_name gateway_endpoint_name
The declare gateway command. This command declares the name of the endpoint to which bundles queued for transmission to the node[s] identified by endpoint_name must be re-routed. Declaring gateway_endpoint_name to be the zero-length string \"''\" disables re-routing: bundles will instead be transmitted using the plan's attached convergence-layer protocol outduct[s].
a planduct endpoint_name protocol_name duct_name
The attach outduct command. This command declares that the indicated convergence-layer protocol outduct is now a viable device for transmitting bundles to the node[s] identified by endpoint_name.
d planduct protocol_name duct_name
The detach outduct command. This command declares that the indicated convergence-layer protocol outduct is no longer a viable device for transmitting bundles to the node[s] to which it is currently assigned.
a scheme ipn 'ipnfw' 'ipnadminep'
Declares the \"ipn\" scheme on the local node.
a protocol udp 1400 100 16384
Establishes access to the \"udp\" convergence layer protocol on the local node, estimating the number of payload bytes per ultimate (lowest-layer) frame to be 1400 with 100 bytes of total overhead (BP, UDP, IP, AOS) per lowest-layer frame, and setting the default nominal data rate to be 16384 bytes per second.
r 'ipnadmin flyby.ipnrc'
Runs the administrative program ipnadmin from within bpadmin.
bpadmin(1), ipnadmin(1), dtn2admin(1)
"},{"location":"man/bpv7/bprecvfile/","title":"NAME","text":"bprecvfile - Bundle Protocol (BP) file reception utility
"},{"location":"man/bpv7/bprecvfile/#synopsis","title":"SYNOPSIS","text":"bprecvfile own_endpoint_ID [max_files]
"},{"location":"man/bpv7/bprecvfile/#description","title":"DESCRIPTION","text":"bprecvfile is intended to serve as the counterpart to bpsendfile. It uses bp_receive() to receive bundles containing file content. The content of each bundle is simply written to a file named \"testfileN\" where N is the total number of bundles received since the program began running.
If a max_files value of N (where N > 0) is provided, the program will terminate automatically upon completing its Nth file reception. Otherwise it will run indefinitely; use ^C to terminate the program.
"},{"location":"man/bpv7/bprecvfile/#exit-status","title":"EXIT STATUS","text":"\"0\"
bprecvfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bprecvfile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bprecvfile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
bprecvfile bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't open test file
File system error. bprecvfile terminates.
bprecvfile: can't receive bundle content.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't write to test file
File system error. bprecvfile terminates.
bprecvfile cannot continue.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't handle bundle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bprecvfile/#see-also","title":"SEE ALSO","text":"bpsendfile(1), bp(3)
"},{"location":"man/bpv7/bprecvfile2/","title":"NAME","text":"bprecvfile2 - Bundle Protocol (BP) file reception utility
"},{"location":"man/bpv7/bprecvfile2/#synopsis","title":"SYNOPSIS","text":"bprecvfile own_endpoint_ID [filename]
"},{"location":"man/bpv7/bprecvfile2/#description","title":"DESCRIPTION","text":"This is an updated version of the original bprecvfile utility
bprecvfile is intended to serve as the counterpart to bpsendfile. It uses bp_receive() to receive bundles containing file content. The content of each bundle is simply written to a file named \"filename\". If the filename is not provided on the command line bundles are written to stdout. Use of UNIX pipes is allowed. Note: If filename exists data will be appended to that file. If filename does not exist it will be created. Use ^C to terminate the program.
"},{"location":"man/bpv7/bprecvfile2/#exit-status","title":"EXIT STATUS","text":"\"0\"
bprecvfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bprecvfile2/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bprecvfile2/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
bprecvfile bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't open test file
File system error. bprecvfile terminates.
bprecvfile: can't receive bundle content.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't write to test file
File system error. bprecvfile terminates.
bprecvfile cannot continue.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't handle bundle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bprecvfile2/#see-also","title":"SEE ALSO","text":"bpsendfile(1), bp(3)
"},{"location":"man/bpv7/bpsecadmin/","title":"NAME","text":"bpsecadmin - BP security policy administration interface
"},{"location":"man/bpv7/bpsecadmin/#synopsis","title":"SYNOPSIS","text":"bpsecadmin [ commands_filename ]
"},{"location":"man/bpv7/bpsecadmin/#description","title":"DESCRIPTION","text":"bpsecadmin configures and manages BP security policy on the local computer.
It configures and manages BP security policy on the local computer in response to BP configuration commands found in commands_filename, if provided; if not, bpsecadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from bpsecadmin by entering the command 'h' or '?' at the prompt. The commands are documented in bpsecrc(5).
"},{"location":"man/bpv7/bpsecadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of BP security policy administration.
bpsecadmin
Enter interactive ION security policy administration command entry mode.
bpsecadmin host1.bpsecrc
Execute all configuration commands in host1.bpsecrc, then terminate immediately.
Status and diagnostic messages from bpsecadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which bpsecadmin was run. The log file is typically named ion.log.
See also bpsecrc(5).
"},{"location":"man/bpv7/bpsecadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpsecadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bpsecadmin. Otherwise bpsecadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bpsecadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see bpsecrc(5) for details.
"},{"location":"man/bpv7/bpsecadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpsecadmin/#see-also","title":"SEE ALSO","text":"bpsecrc(5)
"},{"location":"man/bpv7/bpsecrc/","title":"NAME","text":"bpsecrc - BP security policy management commands file
"},{"location":"man/bpv7/bpsecrc/#description","title":"DESCRIPTION","text":"BP security policy management commands are passed to bpsecadmin either in a file of text lines or interactively at bpsecadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. JSON commands may span multiple lines when provided as part of a config file. The formats and effects of the BP security policy management commands are described below.
A parameter identifed as an eid_expr is an \"endpoint ID expression.\" For all commands, whenever the last character of an endpoint ID expression is the wild-card character '*', an applicable endpoint ID \"matches\" this EID expression if all characters of the endpoint ID expression prior to the last one are equal to the corresponding characters of that endpoint ID. Otherwise an applicable endpoint ID \"matches\" the EID expression only when all characters of the EID and EID expression are identical.
At present, ION supports a subset of the proposed \"BPSec\" security protocol specification currently under consideration by the Internet Engineering Steering Group. Since BPSec is not yet a published standard, ION's Bundle Protocol security mechanisms will not necessarily interoperate with those of other BP implementations. This is unfortunate but (we hope) temporary, as BPSec represents a major improvement in bundle security. Future releases of ION will implement the entire BPSec specification.
"},{"location":"man/bpv7/bpsecrc/#commands","title":"COMMANDS","text":"?
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 bpsecadmin 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.
a { event_set : { name : event set name, desc : (opt) description } }
The add event_set command. This command will add a named security operation event set to the local security policy database.
i { event_set : { name : event set name } }
The info event_set command for event sets displays the information the system maintains for a named event set. The security operation events and configured, optional processing actions associated with that event set are shown.
d { event_set : { name : event set name } }
The delete event_set command deletes a named event set from the system. A named event set cannot be deleted if it is referenced by a security policy rule. All security policy rules associated with the named event set must be deleted before the event set itself may be deleted.
l {event_set}
The list event_set command lists the names of all event sets defined in the system.
a { event : { es_ref : event set name, event_id : security operation event ID, actions : [ {id: processing action, (opt.) action parm key, (opt.) parm value}, ... , {id: processing action, (opt.) action parm key, (opt.) parm value} ] } }
The add event command adds security operation event and associated optional processing action(s) to an event set. Multiple processing actions can be specified for a single security operation event.
d { event : { es_ref : event set name, event_id : security operation event ID } }
The delete event command is used to delete optional processing actions from a named event set. This command currently deletes all of the optional processing actions associated with the security operation event provided.
a { policyrule : { desc : (opt.) description, filter : { rule_id : Security policy rule id, role : Security policy role, src : Bundle source, dest : Bundle destination sec_src : Security source tgt : Security target block type, sc_id : Security context ID, }, spec : { svc : Security service, sc_id : Security context ID, sc_parms : [ {SC parm ID, SC parm value }, ... , {SC parm ID, SC parm value } ] }, es_ref : Event set name } }
The add policyrule command adds a policy rule to the system, describing a required security operation and the security policy role of the BPA applying the policy statement. The above command adds a policy rule referencing a named event set to the system.
d { policyrule : { rule_id : Security policy rule ID } }
The delete policyrule command deletes the policy rule identified by its rule ID.
i {policyrule : { rule_id : Security policy rule ID } }
The info policyrule command displays the information for the policy rule matching the provided ID.
f {policyrule : {type : all | best, src : Bundle source, dest : Bundle destination, sec_src : Security source, sc_id : Security context ID, role : Security policy role } }
The find policyrule command finds all policy rules matching the provided criteria when type all is selected, and finds the single policy rule that is determined to be the best match when type best is selected.
l {policyrule}
The list policyrule command lists all policy rules currently defined in the system.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
bpsecadmin(1)
"},{"location":"man/bpv7/bpsendfile/","title":"NAME","text":"bpsendfile - Bundle Protocol (BP) file transmission utility
"},{"location":"man/bpv7/bpsendfile/#synopsis","title":"SYNOPSIS","text":"bpsendfile own_endpoint_ID destination_endpoint_ID file_name [class_of_service [time_to_live (seconds) ]]
"},{"location":"man/bpv7/bpsendfile/#description","title":"DESCRIPTION","text":"bpsendfile uses bp_send() to issue a single bundle to a designated destination endpoint, containing the contents of the file identified by file_name, then terminates. The bundle is sent with no custody transfer requested. When class_of_service is omitted, the bundle is sent at standard priority; for details of the class_of_service parameter, see bptrace(1). time_to_live, if not specified, defaults to 300 seconds (5 minutes). NOTE that time_to_live is specified AFTER class_of_service, rather than before it as in bptrace(1).
"},{"location":"man/bpv7/bpsendfile/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsendfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bpsendfile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpsendfile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
Can't stat the file
Operating system error. Check errtext, correct problem, and rerun.
bpsendfile can't create file ref.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpsendfile can't create ZCO.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpsendfile can't send file in bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpsendfile/#see-also","title":"SEE ALSO","text":"bprecvfile(1), bp(3)
"},{"location":"man/bpv7/bpsink/","title":"NAME","text":"bpsink - Bundle Protocol reception test program
"},{"location":"man/bpv7/bpsink/#synopsis","title":"SYNOPSIS","text":"bpsink ownEndpointId
"},{"location":"man/bpv7/bpsink/#description","title":"DESCRIPTION","text":"bpsink uses Bundle Protocol to receive application data units from a remote bpsource application task. For each application data unit it receives, it prints the ADU's length and -- if length is less than 80 -- its text.
bpsink terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv7/bpsink/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsink has terminated. Any problems encountered during operation will be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv7/bpsink/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpsink/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpsink are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpsink bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't receive payload.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't handle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpsink/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpsource(1), bp(3)
"},{"location":"man/bpv7/bpsource/","title":"NAME","text":"bpsource - Bundle Protocol transmission test shell
"},{"location":"man/bpv7/bpsource/#synopsis","title":"SYNOPSIS","text":"bpsource destinationEndpointId [\"text\"] [-t_TTL_]
"},{"location":"man/bpv7/bpsource/#description","title":"DESCRIPTION","text":"When text is supplied, bpsource simply uses Bundle Protocol to send text to a counterpart bpsink application task that has opened the BP endpoint identified by destinationEndpointId, then terminates.
Otherwise, bpsource offers the user an interactive \"shell\" for testing Bundle Protocol data transmission. bpsource prints a prompt string (\": \") to stdout, accepts a string of text from stdin, uses Bundle Protocol to send the string to a counterpart bpsink application task that has opened the BP endpoint identified by destinationEndpointId, then prints another prompt string and so on. To terminate the program, enter a string consisting of a single exclamation point (!) character.
TTL indicates the number of seconds the bundles may remain in the network, undelivered, before they are automatically destroyed. If omitted, TTL defaults to 300 seconds.
The source endpoint ID for each bundle sent by bpsource is the null endpoint ID, i.e., the bundles are anonymous. All bundles are sent standard priority with no custody transfer and no status reports requested.
"},{"location":"man/bpv7/bpsource/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsource has terminated. Any problems encountered during operation will be noted in the ion.log log file.
The service data units transmitted by bpsource are sequences of text obtained from a file in the current working directory named \"bpsourceAduFile\", which bpsource creates automatically.
"},{"location":"man/bpv7/bpsource/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpsource/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpsource are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
bpsource fgets failed
Operating system error. Check errtext, correct problem, and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpsource can't send ADU
Bundle Protocol service to the remote endpoint has been stopped.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpsource/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpsink(1), bp(3)
"},{"location":"man/bpv7/bpstats/","title":"NAME","text":"bpstats - Bundle Protocol (BP) processing statistics query utility
"},{"location":"man/bpv7/bpstats/#synopsis","title":"SYNOPSIS","text":"bpstats
"},{"location":"man/bpv7/bpstats/#description","title":"DESCRIPTION","text":"bpstats simply logs messages containing the current values of all BP processing statistics accumulators, then terminates.
"},{"location":"man/bpv7/bpstats/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpstats has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bpstats/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpstats/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpstats can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpstats/#see-also","title":"SEE ALSO","text":"ion(3)
"},{"location":"man/bpv7/bpstats2/","title":"NAME","text":"bpstats2 - Bundle Protocol (BP) processing statistics query utility via bundles
"},{"location":"man/bpv7/bpstats2/#synopsis","title":"SYNOPSIS","text":"bpstats2 sourceEID [default destEID] [ct]
"},{"location":"man/bpv7/bpstats2/#description","title":"DESCRIPTION","text":"bpstats2 creates bundles containing the current values of all BP processing statistics accumulators. It creates these bundles when:
\"0\"
bpstats2 has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpstats2 failed to start up or receive bundles. Diagnose the issue reported in the ion.log file and try again.
If the string \"ct\" is appended as the last argument, then statistics bundles will be sent with custody transfer requested.
No configuration files are needed.
"},{"location":"man/bpv7/bpstats2/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpstats2/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpstats2 can't bp_attach().
bpadmin has not yet initialized BP operations.
bpstats2 can't open own endpoint.
Another BP application has opened that endpoint; close it and try again.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpstats2 can't send stats bundle.
Bundle Protocol service to the remote endpoint has been stopped.
Can't send stats: bad dest EID (dest EID)
The destination EID printed is an invalid destination EID. The destination EID may be specified in default destEID or the source EID of the interrogation bundle. Ensure that default destEID is an EID that is valid for ION, and that the interrogator is a source EID that is also a valid destination EID. Note that \"dtn:none\" is not a valid destination EID, but is a valid source EID.
A very simple interrogator is bpchat which can repeatedly interrogate bpstats2 by just striking the enter key.
"},{"location":"man/bpv7/bpstats2/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpstats2/#see-also","title":"SEE ALSO","text":"bpstats(1), bpchat(1)
"},{"location":"man/bpv7/bptrace/","title":"NAME","text":"bptrace - Bundle Protocol (BP) network trace utility
"},{"location":"man/bpv7/bptrace/#synopsis","title":"SYNOPSIS","text":"bptrace own_endpoint_ID destination_endpoint_ID report-to_endpoint_ID TTL class_of_service \"trace_text\" [status_report_flags]
"},{"location":"man/bpv7/bptrace/#description","title":"DESCRIPTION","text":"bptrace uses bp_send() to issue a single bundle to a designated destination endpoint, with status reporting options enabled as selected by the user, then terminates. The status reports returned as the bundle makes its way through the network provide a view of the operation of the network as currently configured.
TTL indicates the number of seconds the trace bundle may remain in the network, undelivered, before it is automatically destroyed.
class_of_service is custody-requested.priority[.ordinal[.unreliable.critical[.data-label]]], where custody-requested must be 0 or 1 (Boolean), priority must be 0 (bulk) or 1 (standard) or 2 (expedited), ordinal must be 0-254, unreliable must be 0 or 1 (Boolean), critical must also be 0 or 1 (Boolean), and data-label may be any unsigned integer. custody-requested is passed in with the bundle transmission request, but if set to 1 it serves only to request the use of reliable convergence-layer protocols; this will have the effect of enabling custody transfer whenever the applicable convergence-layer protocol is bundle-in-bundle encapsulation (BIBE). ordinal is ignored if priority is not 2. Setting class_of_service to \"0.2.254\" or \"1.2.254\" gives a bundle the highest possible priority. Setting unreliable to 1 causes BP to forego convergence-layer retransmission in the event of data loss. Setting critical to 1 causes contact graph routing to forward the bundle on all plausible routes rather than just the \"best\" route it computes; this may result in multiple copies of the bundle arriving at the destination endpoint, but when used in conjunction with priority 2.254 it ensures that the bundle will be delivered as soon as physically possible.
trace_text can be any string of ASCII text; alternatively, if we want to send a file, it can be \"@\" followed by the name of the file.
status_report_flags must be a sequence of status report flags, separated by commas, with no embedded whitespace. Each status report flag must be one of the following: rcv, fwd, dlv, del.
"},{"location":"man/bpv7/bptrace/#exit-status","title":"EXIT STATUS","text":"\"0\"
bptrace has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bptrace/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bptrace/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bptrace can't attach to BP.
bpadmin has not yet initialized BP operations.
bptrace can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
No space for bptrace text.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't create ZCO.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't send message.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bptrace/#see-also","title":"SEE ALSO","text":"bp(3)
"},{"location":"man/bpv7/bptransit/","title":"NAME","text":"bptransit - Bundle Protocol (BP) daemon task for forwarding received bundles
"},{"location":"man/bpv7/bptransit/#synopsis","title":"SYNOPSIS","text":"bptransit
"},{"location":"man/bpv7/bptransit/#description","title":"DESCRIPTION","text":"bptransit is a background \"daemon\" task that is responsible for presenting to ION's forwarding daemons any bundles that were received from other nodes (i.e., bundles whose payloads reside in Inbound ZCO space) and are destined for yet other nodes. In doing so, it migrates these bundles from Inbound buffer space to Outbound buffer space on the same prioritized basis as the insertion of locally sourced outbound bundles.
Management of the bptransit daemon is automatic. It is spawned automatically by bpadmin in response to the 's' command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command.
Whenever a received bundle is determined to have a destination other than the local node, a pointer to that bundle is appended to one of two queues of \"in-transit\" bundles, one for bundles whose forwarding is provisional (depending on the availability of Outbound ZCO buffer space; bundles in this queue are potentially subject to congestion loss) and one for bundles whose forwarding is confirmed. Bundles received via convergence-layer adapters that can sustain flow control, such as STCP, are appended to the \"confirmed\" queue, while those from CLAs that cannot sustain flow control (such as LTP) are appended to the \"provisional\" queue.
bptransit comprises two threads, one for each in-transit queue. The confirmed in-transit thread dequeues bundles from the \"confirmed\" queue and moves them from Inbound to Outbound ZCO buffer space, blocking (if necessary) until space becomes available. The provisional in-transit queue dequeues bundles from the \"provisional\" queue and moves them from Inbound to Outbound ZCO buffer space if Outbound space is available, discarding (\"abandoning\") them if it is not.
"},{"location":"man/bpv7/bptransit/#exit-status","title":"EXIT STATUS","text":"\"0\"
bptransit terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bptransit.
\"1\"
bptransit was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/bptransit/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bptransit/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bptransit can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bptransit/#see-also","title":"SEE ALSO","text":"bpadmin(1)
"},{"location":"man/bpv7/brsccla/","title":"NAME","text":"brsccla - BRSC-based BP convergence layer adapter (input and output) task
"},{"location":"man/bpv7/brsccla/#synopsis","title":"SYNOPSIS","text":"brsccla server_hostname[:server_port_nbr]_own_node_nbr
"},{"location":"man/bpv7/brsccla/#description","title":"DESCRIPTION","text":"BRSC is the \"client\" side of the Bundle Relay Service (BRS) convergence layer protocol for BP. It is complemented by BRSS, the \"server\" side of the BRS convergence layer protocol for BP. BRS clients send bundles directly only to the server, regardless of their final destinations, and the server forwards them to other clients as necessary.
brsccla is a background \"daemon\" task comprising three threads: one that connects to the BRS server, spawns the other threads, and then handles BRSC protocol output by transmitting bundles over the connected socket to the BRS server; one that simply sends periodic \"keepalive\" messages over the connected socket to the server (to assure that local inactivity doesn't cause the connection to be lost); and one that handles BRSC protocol input from the connected server.
The output thread connects to the server's TCP socket at server_hostname and server_port_nbr, sends over the connected socket the client's own_node_nbr (in SDNV representation) followed by a 32-bit time tag and a 160-bit HMAC-SHA1 digest of that time tag, to authenticate itself; checks the authenticity of the 160-bit countersign returned by the server; spawns the keepalive and receiver threads; and then begins extracting bundles from the queues of bundles ready for transmission via BRSC and transmitting those bundles over the connected socket to the server. Each transmitted bundle is preceded by its length, a 32-bit unsigned integer in network byte order. The default value for server_port_nbr, if omitted, is 80.
The reception thread receives bundles over the connected socket and passes them to the bundle protocol agent on the local ION node. Each bundle received on the connection is preceded by its length, a 32-bit unsigned integer in network byte order.
The keepalive thread simply sends a \"bundle length\" value of zero (a 32-bit unsigned integer in network byte order) to the server once every 15 seconds.
brsccla is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. brsccla can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BRSC convergence layer protocol.
"},{"location":"man/bpv7/brsccla/#exit-status","title":"EXIT STATUS","text":"\"0\"
brsccla terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSC protocol.
\"1\"
brsccla terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSC protocol.
No configuration files are needed.
"},{"location":"man/bpv7/brsccla/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/brsccla/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
brsccla can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such brsc induct.
No BRSC induct with duct name matching server_hostname, own_node_nbr, and server_port_nbr has been added to the BP database. Use bpadmin to stop the BRSC convergence-layer protocol, add the induct, and then restart the BRSC protocol.
CLI task is already started for this duct.
Redundant initiation of brsccla.
No such brsc outduct.
No BRSC outduct with duct name matching server_hostname, own_node_nbr, and server_port_nbr has been added to the BP database. Use bpadmin to stop the BRSC convergence-layer protocol, add the outduct, and then restart the BRSC protocol.
Can't connect to server.
Operating system error. Check errtext, correct problem, and restart BRSC.
Can't register with server.
Configuration error. Authentication has failed, probably because (a) the client and server are using different HMAC/SHA1 keys or (b) the clocks of the client and server differ by more than 5 seconds. Update security policy database(s), as necessary, and assure that the clocks are synchronized.
brsccla can't create receiver thread
Operating system error. Check errtext, correct problem, and restart BRSC.
brsccla can't create keepalive thread
Operating system error. Check errtext, correct problem, and restart BRSC.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/brsccla/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), brsscla(1)
"},{"location":"man/bpv7/brsscla/","title":"NAME","text":"brsscla - BRSS-based BP convergence layer adapter (input and output) task
"},{"location":"man/bpv7/brsscla/#synopsis","title":"SYNOPSIS","text":"brsscla local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/brsscla/#description","title":"DESCRIPTION","text":"BRSS is the \"server\" side of the Bundle Relay Service (BRS) convergence layer protocol for BP. It is complemented by BRSC, the \"client\" side of the BRS convergence layer protocol for BP.
brsscla is a background \"daemon\" task that spawns 2*N threads: one that handles BRSS client connections and spawns sockets for continued data interchange with connected clients; one that handles BRSS protocol output by transmitting over those spawned sockets to the associated clients; and two thread for each spawned socket, an input thread to handle BRSS protocol input from the associated connected client and an output thread to forward BRSS protocol output to the associated connected client.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 80.
Each reception thread receives over the socket connection the node number of the connecting client (in SDNV representation), followed by a 32-bit time tag and a 160-bit HMAC-SHA1 digest of that time tag. The receiving thread checks the time tag, requiring that it differ from the current time by no more than BRSTERM (default value 5) seconds. It then recomputes the digest value using the HMAC-SHA1 key named \"node_number.brs\" as recorded in the ION security database (see ionsecrc(5)), requiring that the supplied and computed digests be identical. If all registration conditions are met, the receiving thread sends the client a countersign -- a similarly computed HMAC-SHA1 digest, for the time tag that is 1 second later than the provided time tag -- to assure the client of its own authenticity, then commences receiving bundles over the connected socket. Each bundle received on the connection is preceded by its length, a 32-bit unsigned integer in network byte order. The received bundles are passed to the bundle protocol agent on the local ION node.
Each output thread extracts bundles from the queues of bundles ready for transmission via BRSS to the corresponding connected client and transmits the bundles over the socket to that client. Each transmitted bundle is preceded by its length, a 32-bit unsigned integer in network byte order.
brsscla is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. brsscla can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BRSS convergence layer protocol.
"},{"location":"man/bpv7/brsscla/#exit-status","title":"EXIT STATUS","text":"\"0\"
brsscla terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSS protocol.
\"1\"
brsscla terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSS protocol.
No configuration files are needed.
"},{"location":"man/bpv7/brsscla/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/brsscla/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
brsscla can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such brss induct.
No BRSS induct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the BRSS convergence-layer protocol, add the induct, and then restart the BRSS protocol.
CLI task is already started for this duct.
Redundant initiation of brsscla.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart BRSS.
Can't open TCP socket
Operating system error -- unable to open TCP socket for accepting connections. Check errtext, correct problem, and restart BRSS.
Can't initialize socket (note: must be root for port 80)
Operating system error. Check errtext, correct problem, and restart BRSS.
brsscla can't create sender thread
Operating system error. Check errtext, correct problem, and restart BRSS.
brsscla can't create access thread
Operating system error. Check errtext, correct problem, and restart BRSS.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/brsscla/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), brsccla(1)
"},{"location":"man/bpv7/cgrfetch/","title":"NAME","text":"cgrfetch - Visualize CGR simulations
"},{"location":"man/bpv7/cgrfetch/#synopsis","title":"SYNOPSIS","text":"cgrfetch [OPTIONS] DEST-NODE
"},{"location":"man/bpv7/cgrfetch/#description","title":"DESCRIPTION","text":"cgrfetch uses CGR to simulate sending a bundle from the local node to DEST-NODE. It traces the execution of CGR to generate graphs of the routes that were considered and the routes that were ultimately chosen to forward along. No bundle is sent during the simulation.
A JSON representation of the simulation is output to OUTPUT-FILE. The representation includes parameters of the simulation and a structure for each considered route, which in turn includes calculated parameters for the route and an image of the contact graph.
The dot(1) tool from the Graphviz package is used to generate the contact graph images and is required for cgrfetch(1). The base64(1) tool from coreutils is used to embed the images in the JSON and is also required.
Note that a trace of the route computation logic performed by CGR is printed to stderr; there is currently no cgrfetch option for redirecting this output to a file.
"},{"location":"man/bpv7/cgrfetch/#options","title":"OPTIONS","text":"DEST-NODE
The final destination to route to. To be useful, it should be a node that exists in the contact plan.
-q
Disable trace message output.
-j
Disable JSON output.
-m
Use a minimum-latency extended COS for the bundle. This ends up sending the bundle to all proximate nodes.
-t DISPATCH-OFFSET
Request a dispatch time of DISPATCH-OFFSET seconds from the time the command is run (default: 0).
-e EXPIRATION-OFFSET
Set the bundle expiration time to EXPIRATION-OFFSET seconds from the time the command is run (default: 3600).
-s BUNDLE-SIZE
Set the bundle payload size to BUNDLE-SIZE bytes (default: 0).
-o OUTPUT-FILE
Send JSON to OUTPUT-FILE (default: stdout).
-d PROTO:NAME
Use PROTO as the outduct protocol and NAME as the outduct name (default: udp:*). Use list to list all available outducts.
cgrfetch 8
Simulate CGR with destination node 8 and dispatch time equal to the current time.
cgrfetch 8 -t 60
Do the same with a dispatch time 60 seconds in the future.
cgrfetch -d list
List all available outducts.
dot(1), base64(1)
"},{"location":"man/bpv7/dccpcli/","title":"NAME","text":"dccpcli - DCCP-based BP convergence layer input task
"},{"location":"man/bpv7/dccpcli/#synopsis","title":"SYNOPSIS","text":"dccpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/dccpcli/#description","title":"DESCRIPTION","text":"dccpcli is a background \"daemon\" task that receives DCCP datagrams via a DCCP socket bound to local_hostname and local_port_nbr, extracts bundles from those datagrams, and passes them to the bundle protocol agent on the local ION node.
If not specified, port number defaults to 4556.
Note that dccpcli has no fragmentation support at all. Therefore, the largest bundle that can be sent via this convergence layer is limited to just under the link's MTU (typically 1500 bytes).
The convergence layer input task is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"dccp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. dccpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DCCP convergence layer protocol.
"},{"location":"man/bpv7/dccpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dccpcli.
\"1\"
dccpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dccpcli.
No configuration files are needed.
"},{"location":"man/bpv7/dccpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dccpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such dccp duct.
No DCCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DCCP convergence-layer protocol, add the induct, and then restart the DCCP protocol.
CLI task is already started for this duct.
Redundant initiation of dccpcli.
dccpcli can't get IP address for host.
Operating system error. Check errtext, correct problem, and restart dccpcli.
CLI can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccpcli.
CLI can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccpcli.
dccpcli can't get acquisition work area.
ION system error. Check errtext, correct problem, and restart dccpcli.
dccpcli can't create new thread.
Operating system error. Check errtext, correct problem, and restart dccpcli.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dccpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), dccpclo(1)
"},{"location":"man/bpv7/dccpclo/","title":"NAME","text":"dccpclo - DCCP-based BP convergence layer output task
"},{"location":"man/bpv7/dccpclo/#synopsis","title":"SYNOPSIS","text":"dccpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv7/dccpclo/#description","title":"DESCRIPTION","text":"dccpclo is a background \"daemon\" task that connects to a remote node's DCCP socket at remote_hostname and remote_port_nbr. It then begins extracting bundles from the queues of bundles ready for transmission via DCCP to this remote bundle protocol agent and transmitting those bundles as DCCP datagrams to the remote host.
If not specified, remote_port_nbr defaults to 4556.
Note that dccpclo has no fragmentation support at all. Therefore, the largest bundle that can be sent via this convergence layer is limited to just under the link's MTU (typically 1500 bytes).
dccpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dccpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DCCP convergence layer protocol.
"},{"location":"man/bpv7/dccpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dccpclo.
\"1\"
dccpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dccpclo.
No configuration files are needed.
"},{"location":"man/bpv7/dccpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dccpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No memory for DCCP buffer in dccpclo.
ION system error. Check errtext, correct problem, and restart dccpclo.
No such dccp duct.
No DCCP outduct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DCCP convergence-layer protocol, add the outduct, and then restart dccpclo.
CLO task is already started for this duct.
Redundant initiation of dccpclo.
dccpclo can't get IP address for host.
Operating system error. Check errtext, correct problem, and restart dccpclo.
dccpclo can't create thread.
Operating system error. Check errtext, correct problem, and restart dccpclo.
CLO can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccpclo.
CLO can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccpclo.
CLO send() error on socket.
Operating system error. Check errtext, correct problem, and restart dccpclo.
Bundle is too big for DCCP CLO.
Configuration error: bundles that are too large for DCCP transmission (i.e., larger than the MTU of the link or 65535 bytes--whichever is smaller) are being enqueued for dccpclo. Change routing or use smaller bundles.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dccpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), dccpcli(1)
"},{"location":"man/bpv7/dgrcli/","title":"NAME","text":"dgrcli - DGR-based BP convergence layer reception task
"},{"location":"man/bpv7/dgrcli/#synopsis","title":"SYNOPSIS","text":"dgrcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/dgrcli/#description","title":"DESCRIPTION","text":"dgrcli is a background \"daemon\" task that handles DGR convergence layer protocol input.
The daemon receives DGR messages via a UDP socket bound to local_hostname and local_port_nbr, extracts bundles from those messages, and passes them to the bundle protocol agent on the local ION node. (local_port_nbr defaults to 1113 if not specified.)
dgrcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dgrcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DGR convergence layer protocol.
"},{"location":"man/bpv7/dgrcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgrcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dgrcli.
\"1\"
dgrcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dgrcli.
No configuration files are needed.
"},{"location":"man/bpv7/dgrcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dgrcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dgrcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such dgr induct.
No DGR induct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DGR convergence-layer protocol, add the induct, and then restart the DGR protocol.
CLI task is already started for this engine.
Redundant initiation of dgrcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart DGR.
dgrcli can't open DGR service access point.
DGR system error. Check prior messages in ion.log log file, correct problem, and then stop and restart the DGR protocol.
dgrcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart DGR.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dgrcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/dgrclo/","title":"NAME","text":"dgrclo - DGR-based BP convergence layer transmission task
"},{"location":"man/bpv7/dgrclo/#synopsis","title":"SYNOPSIS","text":"dgrclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv7/dgrclo/#description","title":"DESCRIPTION","text":"dgrclo is a background \"daemon\" task that spawns two threads, one that handles DGR convergence layer protocol input (positive and negative acknowledgments) and a second that handles DGR convergence layer protocol output.
The output thread extracts bundles from the queues of bundles ready for transmission via DGR to a remote bundle protocol agent, encapsulates them in DGR messages, and uses a randomly configured local UDP socket to send those messages to the remote UDP socket bound to remote_hostname and remote_port_nbr. (local_port_nbr defaults to 1113 if not specified.)
The input thread receives DGR messages via the same local UDP socket and uses them to manage DGR retransmission of transmitted datagrams.
dgrclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dgrclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DGR convergence layer protocol.
"},{"location":"man/bpv7/dgrclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgrclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dgrclo.
\"1\"
dgrclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dgrclo.
No configuration files are needed.
"},{"location":"man/bpv7/dgrclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dgrclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dgrclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
CLI task is already started for this engine.
Redundant initiation of dgrclo.
No such dgr outduct.
No DGR outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the DGR convergence-layer protocol, add the outduct, and then restart the DGR protocol.
dgrclo can't open DGR service access point.
DGR system error. Check prior messages in ion.log log file, correct problem, and then stop and restart the DGR protocol.
dgrclo can't create sender thread
Operating system error. Check errtext, correct problem, and restart DGR.
dgrclo can't create receiver thread
Operating system error. Check errtext, correct problem, and restart DGR.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dgrclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/dtn2admin/","title":"NAME","text":"dtn2admin - baseline \"dtn\" scheme administration interface
"},{"location":"man/bpv7/dtn2admin/#synopsis","title":"SYNOPSIS","text":"dtn2admin [ commands_filename ]
"},{"location":"man/bpv7/dtn2admin/#description","title":"DESCRIPTION","text":"dtn2admin configures the local ION node's routing of bundles to endpoints whose IDs conform to the dtn endpoint ID scheme. Endpoint IDs in the dtn scheme are strings of the form \"dtn://node_name/[[~]demux_token]\", where node_name identifies a BP node (often this is the DNS name of the computer on which the node resides) and demux_token normally identifies a specific application processing point. When and only when the terminating demux string (everything after the final '/') does NOT begin with '~', the endpoint ID identifies a singleton endpoint; when the terminating demux string is omitted, the endpoint ID constitutes a node ID. Although the dtn endpoint ID scheme imposes more transmission overhead than the ipn scheme, ION provides support for dtn endpoint IDs to enable interoperation with other implementations of Bundle Protocol.
dtn2admin operates in response to \"dtn\" scheme configuration commands found in the file commands_filename, if provided; if not, dtn2admin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from dtn2admin with the 'h' or '?' commands at the prompt. The commands are documented in dtn2rc(5).
"},{"location":"man/bpv7/dtn2admin/#exit-status","title":"EXIT STATUS","text":"dtn2admin
Enter interactive \"dtn\" scheme configuration command entry mode.
dtn2admin host1.dtn2rc
Execute all configuration commands in host1.dtn2rc, then terminate immediately.
See dtn2rc(5) for details of the DTN scheme configuration commands.
"},{"location":"man/bpv7/dtn2admin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dtn2admin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the dtn2rc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to dtn2admin. Otherwise dtn2admin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
dtn2admin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
dtn2admin can't initialize routing database.
There is no SDR data store for dtn2admin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause dtn2admin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see dtn2rc(5) for details.
"},{"location":"man/bpv7/dtn2admin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dtn2admin/#see-also","title":"SEE ALSO","text":"dtn2rc(5)
"},{"location":"man/bpv7/dtn2adminep/","title":"NAME","text":"dtn2adminep - administrative endpoint task for the \"dtn\" scheme
"},{"location":"man/bpv7/dtn2adminep/#synopsis","title":"SYNOPSIS","text":"dtn2adminep
"},{"location":"man/bpv7/dtn2adminep/#description","title":"DESCRIPTION","text":"dtn2adminep is a background \"daemon\" task that receives and processes administrative bundles (minimally, all bundle status reports) that are sent to the \"dtn\"-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. dtn2adminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the \"dtn\" scheme.
dtn2adminep responds to bundle status reports by logging ASCII text messages describing the reported activity.
"},{"location":"man/bpv7/dtn2adminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtn2adminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dtn2adminep.
\"1\"
dtn2adminep was unable to attach to Bundle Protocol operations or was unable to load the \"dtn\" scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/dtn2adminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dtn2adminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtn2adminep can't attach to BP.
bpadmin has not yet initialized BP operations.
dtn2adminep can't load routing database.
dtn2admin has not yet initialized the \"dtn\" scheme.
dtn2adminep can't get admin EID.
dtn2admin has not yet initialized the \"dtn\" scheme.
dtn2adminep crashed.
An unrecoverable database error was encountered. dtn2adminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dtn2adminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), dtn2admin(1).
"},{"location":"man/bpv7/dtn2fw/","title":"NAME","text":"dtn2fw - bundle route computation task for the \"dtn\" scheme
"},{"location":"man/bpv7/dtn2fw/#synopsis","title":"SYNOPSIS","text":"dtn2fw
"},{"location":"man/bpv7/dtn2fw/#description","title":"DESCRIPTION","text":"dtn2fw is a background \"daemon\" task that pops bundles from the queue of bundle destined for \"dtn\"-scheme endpoints, computes proximate destinations for those bundles, and appends those bundles to the appropriate queues of bundles pending transmission to those computed proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is affected by static routes as configured by dtn2admin(1).
dtn2fw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. dtn2fw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the \"dtn\" scheme.
"},{"location":"man/bpv7/dtn2fw/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtn2fw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dtn2fw.
\"1\"
dtn2fw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dtn2fw.
No configuration files are needed.
"},{"location":"man/bpv7/dtn2fw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dtn2fw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtn2fw can't attach to BP.
bpadmin has not yet initialized BP operations.
dtn2fw can't load routing database.
dtn2admin has not yet initialized the \"dtn\" scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. dtn2fw terminates.
'dtn' scheme is unknown.
The \"dtn\" scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. dtn2fw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. dtn2fw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dtn2fw/#see-also","title":"SEE ALSO","text":"bpadmin(1), dtn2admin(1), bprc(5), dtn2rc(5).
"},{"location":"man/bpv7/dtn2rc/","title":"NAME","text":"dtn2rc - \"dtn\" scheme configuration commands file
"},{"location":"man/bpv7/dtn2rc/#description","title":"DESCRIPTION","text":"\"dtn\" scheme configuration commands are passed to dtn2admin either in a file of text lines or interactively at dtn2admin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
\"dtn\" scheme configuration commands establish static routing rules for forwarding bundles to nodes identified by \"dtn\"-scheme destination endpoints.
Static routes are expressed as plans in the \"dtn\"-scheme routing database. A plan that is established for a given node name associates a routing directive with the named node. Each directive is a string of one of two possible forms:
f endpoint_ID
...or...
x protocol_name/outduct_name
The former form signifies that the bundle is to be forwarded to the indicated endpoint, requiring that it be re-queued for processing by the forwarder for that endpoint (which might, but need not, be identified by another \"dtn\"-scheme endpoint ID). The latter form signifies that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
The node names cited in dtn2rc plans may be \"wild-carded\". That is, when the last character of a plan's node name is either '*' or '~' (these two wild-card characters are equivalent for this purpose), the plan applies to all nodes whose names are identical to the wild-carded node name up to the wild-card character. For example, a bundle whose destination EID is \"dtn://foghorn/x\" would be routed by plans citing the following node names: \"foghorn\", \"fogh*\", \"fog~\", \"*\". When multiple plans are all applicable to the same destination EID, the one citing the longest (i.e., most narrowly targeted) node name will be applied.
The formats and effects of the DTN scheme configuration commands are described below.
"},{"location":"man/bpv7/dtn2rc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 dtn2admin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a plan node_name directive [nominal_xmit_rate]
The add plan command. This command establishes a static route for the bundles destined for the node(s) identified by node_nameID. The nominal_xmit_rate is the assumed rate of transmission to this node in the absence of contact plan information. A nominal_data_rate of zero (the default) in the absence of contact plan information completely disables rate control.
Note that the plan commands consumed by dtn2admin are a simplified shortcut for submitting plan commands as consumed by bpadmin (see bprc(5)). The syntax of these commands is DIFFERENT from that of the more general and more powerful bpadmin commands.
c plan node_nameID [f endpoint_ID] [nominal_xmit_rate]
The change plan command. This command revises the \"via node\" and/or nominal_data_rate of the static route for the node(s) identified by node_nameID. To detach an outduct from the plan, use the \"planduct\" deletion command processed by bpadmin.
d plan node_nameID
The delete plan command. This command deletes the static route for the node(s) identified by node_nameID.
i plan node_nameID
This command will print information about the static route for the node(s) identified by node_nameID.
l plan
This command lists all static routes established in the DTN database for the local node.
a plan bbn2 f ipn:8.41
Declares a static route from the local node to node \"bbn2\". Any bundle destined for any endpoint whose node name is \"bbn2\" will be forwarded to endpoint \"ipn:8.41\".
a plan mitre* x ltp/6
Declares a static route from the local node to any node whose node name begins with \"mitre\". Any bundle destined for any endpoint whose node name begins with \"mitre1\" will be queued for transmission on LTP outduct 6.
dtn2admin(1)
"},{"location":"man/bpv7/hmackeys/","title":"NAME","text":"hmackeys - utility program for generating good HMAC-SHA1 keys
"},{"location":"man/bpv7/hmackeys/#synopsis","title":"SYNOPSIS","text":"hmackeys [ keynames_filename ]
"},{"location":"man/bpv7/hmackeys/#description","title":"DESCRIPTION","text":"hmackeys writes files containing randomized 160-bit key values suitable for use by HMAC-SHA1 in support of Bundle Authentication Block processing, Bundle Relay Service connections, or other functions for which symmetric hash computation is applicable. One file is written for each key name presented to hmackeys; the content of each file is 20 consecutive randomly selected 8-bit integer values, and the name given to each file is simply \"keyname.hmk\".
hmackeys operates in response to the key names found in the file keynames_filename, one name per file text line, if provided; if not, hmackeys prints a simple prompt (:) so that the user may type key names directly into standard input.
When the program is run in interactive mode, either enter 'q' or press ^C to terminate.
"},{"location":"man/bpv7/hmackeys/#exit-status","title":"EXIT STATUS","text":"hmackeys
Enter interactive HMAC/SHA1 key generation mode.
hmackeys host1.keynames
Create a key file for each key name in host1.keynames, then terminate immediately.
No other files are used in the operation of hmackeys.
"},{"location":"man/bpv7/hmackeys/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/hmackeys/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the logfile ion.log:
Can't open keynames file...
The keynames_filename specified in the command line doesn't exist.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/hmackeys/#see-also","title":"SEE ALSO","text":"brsscla(1), ionsecadmin(1)
"},{"location":"man/bpv7/imcadminep/","title":"NAME","text":"imcadminep - administrative endpoint task for the IMC (multicast) scheme
"},{"location":"man/bpv7/imcadminep/#synopsis","title":"SYNOPSIS","text":"imcadminep
"},{"location":"man/bpv7/imcadminep/#description","title":"DESCRIPTION","text":"imcadminep is a background \"daemon\" task that receives and processes administrative bundles (multicast group petitions) that are sent to the IMC-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. imcadminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IMC scheme.
imcadminep responds to multicast group \"join\" and \"leave\" petitions by managing entries in the node's database of multicast groups and their members.
"},{"location":"man/bpv7/imcadminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
imcadminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart imcadminep.
\"1\"
imcadminep was unable to attach to Bundle Protocol operations or was unable to load the IMC scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/imcadminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/imcadminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
imcadminep can't attach to BP.
bpadmin has not yet initialized BP operations.
imcadminep can't load routing database.
imcadmin has not yet initialized the IMC scheme.
imcadminep crashed.
An unrecoverable database error was encountered. imcadminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/imcadminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/imcfw/","title":"NAME","text":"imcfw - bundle route computation task for the IMC scheme
"},{"location":"man/bpv7/imcfw/#synopsis","title":"SYNOPSIS","text":"imcfw
"},{"location":"man/bpv7/imcfw/#description","title":"DESCRIPTION","text":"imcfw is a background \"daemon\" task that pops bundles from the queue of bundle destined for IMC-scheme (Interplanetary Multicast) endpoints, determines which \"relatives\" on the IMC multicast tree to forward the bundles to, and appends those bundles to the appropriate queues of bundles pending transmission to those proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is determined by multicast group membership as resulting from nodes' registration in multicast endpoints (accomplished simply by adding the appropriate endpoint as discussed in bprc(5).
imcfw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. imcfw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IMC scheme.
"},{"location":"man/bpv7/imcfw/#exit-status","title":"EXIT STATUS","text":"\"0\"
imcfw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart imcfw.
\"1\"
imcfw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart imcfw.
No configuration files are needed.
"},{"location":"man/bpv7/imcfw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/imcfw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
imcfw can't attach to BP.
bpadmin has not yet initialized BP operations.
imcfw can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. imcfw terminates.
'imc' scheme is unknown.
The IMC scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. imcfw terminates.
Can't exclude sender from routes.
An unrecoverable database error was encountered. imcfw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. imcfw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/imcfw/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/ipnadmin/","title":"NAME","text":"ipnadmin - Interplanetary Internet (IPN) scheme administration interface
"},{"location":"man/bpv7/ipnadmin/#synopsis","title":"SYNOPSIS","text":"ipnadmin [ commands_filename ]
"},{"location":"man/bpv7/ipnadmin/#description","title":"DESCRIPTION","text":"ipnadmin configures the local ION node's routing of bundles to endpoints whose IDs conform to the ipn endpoint ID scheme. Every endpoint ID in the ipn scheme is a string of the form \"ipn:node_number.service_number\" where node_number is a CBHE \"node number\" and service_number identifies a specific application processing point. When service_number is zero, the endpoint ID constitutes a node ID. All endpoint IDs formed in the ipn scheme identify singleton endpoints.
ipnadmin operates in response to IPN scheme configuration commands found in the file commands_filename, if provided; if not, ipnadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from ipnadmin with the 'h' or '?' commands at the prompt. The commands are documented in ipnrc(5).
"},{"location":"man/bpv7/ipnadmin/#exit-status","title":"EXIT STATUS","text":"ipnadmin
Enter interactive IPN scheme configuration command entry mode.
ipnadmin host1.ipnrc
Execute all configuration commands in host1.ipnrc, then terminate immediately.
See ipnrc(5) for details of the IPN scheme configuration commands.
"},{"location":"man/bpv7/ipnadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ipnadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ipnrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ipnadmin. Otherwise ipnadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ipnadmin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
ipnadmin can't initialize routing database.
There is no SDR data store for ipnadmin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ipnadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see ipnrc(5) for details.
"},{"location":"man/bpv7/ipnadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ipnadmin/#see-also","title":"SEE ALSO","text":"ipnrc(5)
"},{"location":"man/bpv7/ipnadminep/","title":"NAME","text":"ipnadminep - administrative endpoint task for the IPN scheme
"},{"location":"man/bpv7/ipnadminep/#synopsis","title":"SYNOPSIS","text":"ipnadminep
"},{"location":"man/bpv7/ipnadminep/#description","title":"DESCRIPTION","text":"ipnadminep is a background \"daemon\" task that receives and processes administrative bundles (nominally, all bundle status reports) that are sent to the IPN-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. ipnadminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IPN scheme.
ipnadminep responds to bundle status reports by logging ASCII text messages describing the reported activity.
"},{"location":"man/bpv7/ipnadminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
ipnadminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ipnadminep.
\"1\"
ipnadminep was unable to attach to Bundle Protocol operations or was unable to load the IPN scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/ipnadminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ipnadminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ipnadminep can't attach to BP.
bpadmin has not yet initialized BP operations.
ipnadminep can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
ipnadminep crashed.
An unrecoverable database error was encountered. ipnadminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ipnadminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), ipnadmin(1), bprc(5)
"},{"location":"man/bpv7/ipnd/","title":"NAME","text":"ipnd - ION IPND module
"},{"location":"man/bpv7/ipnd/#description","title":"DESCRIPTION","text":"The ipnd daemon is the ION implementation of DTN IP Neighbor Discovery. This module allows the node to send and receive beacon messages using unicast, multicast or broadcast IP addresses. Beacons are used for the discovery of neighbors and may be used to advertise services that are present and available on nodes, such as routing algorithms or CLAs.
ION IPND module is configured using a *.rc configuration file. The name of the configuration file must be passed as the sole command-line argument to ipnd when the daemon is started. Commands are interpreted line by line, with exactly one command per line. The formats and effects of the ION ipnd management commands are described below.
"},{"location":"man/bpv7/ipnd/#usage","title":"USAGE","text":"ipnd config_file_name
"},{"location":"man/bpv7/ipnd/#commands","title":"COMMANDS","text":"1
The initialize command. This must be the first command.
#
Comment line. Lines beginning with # are not interpreted.
e { 1 | 0 }
Echo control. Setting echo to 1 causes all output printed by ipnd to be logged into ion.log. Setting echo to 0 disables this behavior. Default is 1.
m eid eid
Local eid. This command sets the advertised BP endpoint ID by which the node will identify itself in beacon messages.
m announce period { 1 | 0 }
Announce period control. Setting to 1 causes all beacons messages sent to contain beacon period. Setting to 0 disables this behavior. Default is 1.
m announce eid { 1 | 0 }
Announce eid control. Setting to 1 causes all beacons messages sent to contain source eid. Setting to 0 disables this behavior. This should be always set to 1. Default is 1.
m interval unicast interval
Unicast interval. This command sets the beacon messages period on unicast transmissions. Time interval is expressed in seconds. Default is 5.
m interval multicast interval
Multicast interval. This command sets the beacon messages period on multicast transmissions. Time interval is expressed in seconds. Default is 7.
m interval broadcast interval
Broadcastcast interval. This command sets the beacon messages period on broadcast transmissions. Time interval is expressed in seconds. Default is 11.
m multicast ttl ttl
Multicast ttl. This command sets the multicast outgoing beacon messages' time to live, in seconds. Default is 255.
m svcdef id name child_name:child_type ...
Service definition. This command specifies definitions of \"services\", which are dynamically defined beacon message data structures indicating the capabilities of the beacon message sender. id is a service-identifying number in the range 128-255. name is the name of the service type that is being defined. The definition of the structure of the service is a sequence of elements, each of which is a name:type pair. Each child_type must be the name of a standard or previously defined service type. Infinite recursion is supported.
a svcadv name child_name:child_value ...
Service advertising command. This command defines which services will be advertised and with which values. All types of formats for values are supported (e.g. 999, 0345 (octal), 0x999 (hex), -1e-9, 0.32, etc.). For a service that contains only a single element, it is not necessary to provide that element's name. E.g. it is enough to write Booleans:true instead of Booleans:BooleanValues:B:true, as BooleanValues is the only child of Booleans and B is the only child of BooleanValues.
a listen IP_address
Listen socket specification command. This command asserts, in the form IP_address, the IP address of the socket at which the IPND daemon is to listen for incoming beacons; a default port number is used. The address can be an unicast, a multicast or a broadcast address. If a multicast address is provided all the configured unicast addresses will listen for multicast packets in that group. If a broadcast address is provided all the unicast addresses will listen for broadcasted packets.
a destination destination_socket_spec
Destination socket specification command. This command asserts the specification for a socket to which the IPND daemon is to send beacons. It can be an unicast, a multicast or a broadcast address.
s
The start command. This command starts the IPND daemon for the local ION node.
m scvdef 128 FooRouter Seed:SeedVal BaseWeight:WeightVal RootHash:bytes
Defines a new service called FooRouter comprising 3 elements. SeedVal and WeightVal are user defined services that must be already defined.
m svcdef 129 SeedVal Value:fixed16
m svcdef 130 WeightVal Value:fixed16
m svcdef 128 FooRouter Seed:SeedVal BaseWeight:WeightVal RootHash:bytes
m svcdef 150 FixedValuesList F16:fixed16 F32:fixed32 F64:fixed64
m svcdef 131 VariableValuesList U64:uint64 S64:sint64
m svcdef 132 BooleanValues B:boolean
m svcdef 133 FloatValuesList F:float D:double
m svcdef 135 IntegersList FixedValues:FixedValuesList VariableValues:VariableValuesList
m svcdef 136 NumbersList Integers:IntegersList Floats:FloatValuesList
m svcdef 140 HugeService CLAv4:CLA-TCP-v4 Booleans:BooleanValues Numbers:NumbersList FR:FooRouter
a svcadv HugeService CLAv4:IP:10.1.0.10 CLAv4:Port:4444 Booleans:true FR:Seed:0x5432 FR:BaseWeight:13 FR:RootHash:BEEF Numbers:Integers:FixedValues:F16:0x16 Numbers:Integers:FixedValues:F32:0x32 Numbers:Integers:FixedValues:F64:0x1234567890ABCDEF Numbers:Floats:F:0.32 Numbers:Floats:D:-1e-6 Numbers:Integers:VariableValues:U64:18446744073704783380 Numbers:Integers:VariableValues:S64:-4611686018422619668
This shows how to define multiple nested services and how to advertise them.
"},{"location":"man/bpv7/ipnd/#see-also","title":"SEE ALSO","text":"ion(3)
"},{"location":"man/bpv7/ipnfw/","title":"NAME","text":"ipnfw - bundle route computation task for the IPN scheme
"},{"location":"man/bpv7/ipnfw/#synopsis","title":"SYNOPSIS","text":"ipnfw
"},{"location":"man/bpv7/ipnfw/#description","title":"DESCRIPTION","text":"ipnfw is a background \"daemon\" task that pops bundles from the queue of bundle destined for IPN-scheme endpoints, computes proximate destinations for those bundles, and appends those bundles to the appropriate queues of bundles pending transmission to those computed proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is affected by static and default routes as configured by ipnadmin(1) and by contact graphs as managed by ionadmin(1) and rfxclock(1).
ipnfw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. ipnfw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IPN scheme.
"},{"location":"man/bpv7/ipnfw/#exit-status","title":"EXIT STATUS","text":"\"0\"
ipnfw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ipnfw.
\"1\"
ipnfw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart ipnfw.
No configuration files are needed.
"},{"location":"man/bpv7/ipnfw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ipnfw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ipnfw can't attach to BP.
bpadmin has not yet initialized BP operations.
ipnfw can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. ipnfw terminates.
'ipn' scheme is unknown.
The IPN scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. ipnfw terminates.
Can't exclude sender from routes.
An unrecoverable database error was encountered. ipnfw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. ipnfw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ipnfw/#see-also","title":"SEE ALSO","text":"bpadmin(1), ipnadmin(1), bprc(5), ipnrc(5)
"},{"location":"man/bpv7/ipnrc/","title":"NAME","text":"ipnrc - IPN scheme configuration commands file
"},{"location":"man/bpv7/ipnrc/#description","title":"DESCRIPTION","text":"IPN scheme configuration commands are passed to ipnadmin either in a file of text lines or interactively at ipnadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
IPN scheme configuration commands (a) establish egress plans for direct transmission to neighboring nodes that are members of endpoints identified in the \"ipn\" URI scheme and (b) establish static default routing rules for forwarding bundles to specified destination nodes.
The egress plan established for a given node associates a duct expression with that node. Each duct expression is a string of the form \"protocol_name/outduct_name\" signifying that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
Note that egress plans must be established for all neighboring nodes, regardless of whether or not contact graph routing is used for computing dynamic routes to distant nodes. This is by definition: if there isn't an egress plan to a node, it can't be considered a neighbor.
Static default routes are declared as exits in the ipn-scheme routing database. An exit is a range of node numbers identifying a set of nodes for which defined default routing behavior is established. Whenever a bundle is to be forwarded to a node whose number is in the exit's node number range and it has not been possible to compute a dynamic route to that node from the contact schedules that have been provided to the local node and that node is not a neighbor to which the bundle can be directly transmitted, BP will forward the bundle to the gateway node associated with this exit. The gateway node for any exit is identified by an endpoint ID, which might or might not be an ipn-scheme EID; regardless, directing a bundle to the gateway for an exit causes the bundle to be re-forwarded to that intermediate destination endpoint. Multiple exits may encompass the same node number, in which case the gateway associated with the most restrictive exit (the one with the smallest range) is always selected.
Note that \"exits\" were termed \"groups\" in earlier versions of ION. The term \"exit\" has been adopted instead, to minimize any possible confusion with multicast groups. To protect backward compatibility, the keyword \"group\" continues to be accepted by ipnadmin as an alias for the new keyword \"exit\", but the older terminology is deprecated.
Routing and class-of-service overrides may also be managed:
A routing override declares a neighboring node to which all bundles must be forwarded that meet specified criteria. This override is strictly local, affecting only forwarding from the local node, and it is applied before any route computed by CGR or IRR is considered.
A class-of-service override declares the class of service (priority and ordinal and [optionally] quality-of-service flags) that will condition - in terms of order and outduct selection - the forwarding of all bundles that meet specified criteria. Again this override is strictly local, affecting only forwarding from the local node.
The formats and effects of the IPN scheme configuration commands are described below.
"},{"location":"man/bpv7/ipnrc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 ipnadmin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a plan node_nbr duct_expression [nominal_data_rate]
The add plan command. This command establishes an egress plan for the bundles that must be transmitted to the neighboring node identified by node_nbr. The nominal_data_rate is the assumed rate of transmission to this node in the absence of contact plan information. A nominal_data_rate of zero (the default) in the absence of contact plan information completely disables rate control.
Note that the plan commands consumed by ipnadmin are a simplified shortcut for submitting plan commands as consumed by bpadmin (see bprc(5)). The syntax of these commands is DIFFERENT from that of the more general and more powerful bpadmin commands.
c plan node_nbr nominal_data_rate
The change plan command. This command changes the nominal data rate for the indicated plan.
d plan node_nbr
The delete plan command. This command deletes the egress plan for the node identified by node_nbr.
i plan node_nbr
This command will print information about the egress plan for the node identified by node_nbr.
l plan
This command lists all egress plans established in the IPN database for the local node.
a exit first_node_nbr last_node_nbr gateway_endpoint_ID
The add exit command. This command establishes an \"exit\" for static default routing as described above.
c exit first_node_nbr last_node_nbr gateway_endpoint_ID
The change exit command. This command changes the gateway node number for the exit identified by first_node_nbr and last_node_nbr .
d exit first_node_nbr last_node_nbr
The delete exit command. This command deletes the exit identified by first_node_nbr and last_node_nbr.
i exit first_node_nbr last_node_nbr
This command will print information (the gateway endpoint ID) about the exit identified by first_node_nbr and last_node_nbr.
l exit
This command lists all exits defined in the IPN database for the local node.
a rtovrd data_label dest_node_nbr source_node_nbr neighbor
The add rtovrd command. This command cause bundles characterized by data_label, dest_node_nbr (\"all other destinations\" if this node number is zero) and source_node_nbr (\"all other sources\" if this node number is zero) to be forwarded to neighbor. If neighbor is zero, the override will be \"learned\" by ION: the neighbor selected for this bundle, by whatever means, becomes the override for all subsequent matching bundles.
c rtovrd data_label dest_node_nbr source_node_nbr neighbor
The change rtovrd command. This command changes the override neighbor for the override identified by data_label, dest_node_nbr, and source_node_nbr. To cause ION to forget the override, use -1 as neighbor.
a cosovrd data_label dest_node_nbr source_node_nbr priority ordinal [qos_flags]
The add cosovrd command. This command cause bundles characterized by data_label, dest_node_nbr (\"all other destinations\" if this node number is zero) and source_node_nbr (\"all other sources\" if this node number is zero) to have their effective class of service (priority and ordinal and, optionally, additional quality-of-service flags) changed as noted.
c cosovrd data_label dest_node_nbr source_node_nbr priority ordinal [qos_flags]
The change cosovrd command. This command changes the effective class of service (priority and ordinal and, optionally, additional quality-of-service flags) for the override identified by data_label, dest_node_nbr, and source_node_nbr. To cause ION to forget the override, use -1 as priority.
d ovrd data_label dest_node_nbr source_node_nbr
The delete override command. This command deletes all overrides identified by data_label, dest_node_nbr, and source_node_nbr.
i ovrd data_label dest_node_nbr source_node_nbr
This command will print information for all overrides identified by data_label, dest_node_nbr, and source_node_nbr.
l ovrd
This command lists all overrides defined in the IPN database for the local node.
a plan 18 ltp/18
Declares the egress plan to use for transmission from the local node to neighboring node 18. By default, any bundle for which the computed \"next hop\" node is node 18 will be queued for transmission on LTP outduct 18.
a exit 1 999 dtn://stargate
Declares a default route for bundles destined for all nodes whose numbers are in the range 1 through 999 inclusive: absent any other routing decision, such bundles are to be forwarded to \"dtn://stargate\".
ipnadmin(1)
"},{"location":"man/bpv7/lgagent/","title":"NAME","text":"lgagent - ION Load/Go remote agent program
"},{"location":"man/bpv7/lgagent/#synopsis","title":"SYNOPSIS","text":"lgagent own_endpoint_ID
"},{"location":"man/bpv7/lgagent/#description","title":"DESCRIPTION","text":"ION Load/Go is a system for management of an ION-based network, enabling the execution of ION administrative programs at remote nodes. The system comprises two programs, lgsend and lgagent.
The lgagent task on a given node opens the indicated ION endpoint for bundle reception, receives the extracted payloads of Load/Go bundles sent to it by lgsend as run on one or more remote nodes, and processes those payloads, which are the text of Load/Go source files.
Load/Go source file content is limited to newline-terminated lines of ASCII characters. More specifically, the text of any Load/Go source file is a sequence of line sets of two types: file capsules and directives. Any Load/Go source file may contain any number of file capsules and any number of directives, freely intermingled in any order, but the typical structure of a Load/Go source file is simply a single file capsule followed by a single directive.
When lgagent identifies a file capsule, it copies all of the capsule's text lines to a new file that it creates in the current working directory. When lgagent identifies a directive, it executes the directive by passing the text of the directive to the pseudoshell() function (see platform(3)). lgagent processes the line sets of a Load/Go source file in the order in which they appear in the file, so the text of a directive may reference a file that was created as the result of processing a prior file capsule in the same source file.
"},{"location":"man/bpv7/lgagent/#exit-status","title":"EXIT STATUS","text":"\"0\"
Load/Go remote agent processing has terminated.
lgfile contains the Load/Go file capsules and directives that are to be processed.
"},{"location":"man/bpv7/lgagent/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/lgagent/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
lgagent: can't attach to BP.
Bundle Protocol is not running on this computer. Run bpadmin(1) to start BP.
lgagent: can't open own endpoint.
own_endpoint_ID is not a declared endpoint on the local ION node. Run bpadmin(1) to add it.
lgagent: bundle reception failed.
ION system problem. Investigate and correct before restarting.
lgagent cannot continue.
lgagent processing problem. See earlier diagnostic messages for details. Investigate and correct before restarting.
lgagent: no space for bundle content.
ION system problem: have exhausted available SDR data store reserves.
lgagent: can't receive bundle content.
ION system problem: have exhausted available SDR data store reserves.
lgagent: can't handle bundle delivery.
ION system problem. Investigate and correct before restarting.
lgagent: pseudoshell failed.
Error in directive line, usually an attempt to execute a non-existent administration program (e.g., a misspelled program name). Terminates processing of source file content.
A variety of other diagnostics noting source file parsing problems may also be reported. These errors are non-fatal but they terminate the processing of the source file content from the most recently received bundle.
"},{"location":"man/bpv7/lgagent/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/lgagent/#see-also","title":"SEE ALSO","text":"lgsend(1), lgfile(5)
"},{"location":"man/bpv7/lgfile/","title":"NAME","text":"lgfile - ION Load/Go source file
"},{"location":"man/bpv7/lgfile/#description","title":"DESCRIPTION","text":"The ION Load/Go system enables the execution of ION administrative programs at remote nodes:
The lgsend program reads a Load/Go source file from a local file system, encapsulates the text of that source file in a bundle, and sends the bundle to a designated DTN endpoint on the remote node.
An lgagent task running on the remote node, which has opened that DTN endpoint for bundle reception, receives the extracted payload of the bundle -- the text of the Load/Go source file -- and processes it.
Load/Go source file content is limited to newline-terminated lines of ASCII characters. More specifically, the text of any Load/Go source file is a sequence of line sets of two types: file capsules and directives. Any Load/Go source file may contain any number of file capsules and any number of directives, freely intermingled in any order, but the typical structure of a Load/Go source file is simply a single file capsule followed by a single directive.
Each file capsule is structured as a single start-of-capsule line, followed by zero or more capsule text lines, followed by a single end-of-capsule line. Each start-of-capsule line is of this form:
[file_name
Each capsule text line can be any line of ASCII text that does not begin with an opening ([) or closing (]) bracket character.
A text line that begins with a closing bracket character (]) is interpreted as an end-of-capsule line.
A directive is any line of text that is not one of the lines of a file capsule and that is of this form:
!directive_text
When lgagent identifies a file capsule, it copies all of the capsule's text lines to a new file named file_name that it creates in the current working directory. When lgagent identifies a directive, it executes the directive by passing directive_text to the pseudoshell() function (see platform(3)). lgagent processes the line sets of a Load/Go source file in the order in which they appear in the file, so the directive_text of a directive may reference a file that was created as the result of processing a prior file capsule line set in the same source file.
Note that lgfile directives are passed to pseudoshell(), which on a VxWorks platform will always spawn a new task; the first argument in directive_text must be a symbol that VxWorks can resolve to a function, not a shell command. Also note that the arguments in directive_text will be actual task arguments, not shell command-line arguments, so they should never be enclosed in double-quote characters (\"). However, any argument that contains embedded whitespace must be enclosed in single-quote characters (') so that pseudoshell() can parse it correctly.
"},{"location":"man/bpv7/lgfile/#examples","title":"EXAMPLES","text":"Presenting the following lines of source file text to lgsend:
[cmd33.bprc
x protocol ltp
]
!bpadmin cmd33.bprc
should cause the receiving node to halt the operation of the LTP convergence-layer protocol.
"},{"location":"man/bpv7/lgfile/#see-also","title":"SEE ALSO","text":"lgsend(1), lgagent(1), platform(3)
"},{"location":"man/bpv7/lgsend/","title":"NAME","text":"lgsend - ION Load/Go command program
"},{"location":"man/bpv7/lgsend/#synopsis","title":"SYNOPSIS","text":"lgsend command_file_name own_endpoint_ID destination_endpoint_ID
"},{"location":"man/bpv7/lgsend/#description","title":"DESCRIPTION","text":"ION Load/Go is a system for management of an ION-based network, enabling the execution of ION administrative programs at remote nodes. The system comprises two programs, lgsend and lgagent.
The lgsend program reads a Load/Go source file from a local file system, encapsulates the text of that source file in a bundle, and sends the bundle to an lgagent task that is waiting for data at a designated DTN endpoint on the remote node.
To do so, it first reads all lines of the Load/Go source file identified by command_file_name into a temporary buffer in ION's SDR data store, concatenating the lines of the file and retaining all newline characters. Then it invokes the bp_send() function to create and send a bundle whose payload is this temporary buffer, whose destination is destination_endpoint_ID, and whose source endpoint ID is own_endpoint_ID. Then it terminates.
"},{"location":"man/bpv7/lgsend/#exit-status","title":"EXIT STATUS","text":"\"0\"
Load/Go file transmission succeeded.
\"1\"
Load/Go file transmission failed. Examine ion.log to determine the cause of the failure, then re-run.
lgfile contains the Load/Go file capsules and directive that are to be sent to the remote node.
"},{"location":"man/bpv7/lgsend/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/lgsend/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
lgsend: can't attach to BP.
Bundle Protocol is not running on this computer. Run bpadmin(1) to start BP.
lgsend: can't open own endpoint.
own_endpoint_ID is not a declared endpoint on the local ION node. Run bpadmin(1) to add it.
lgsend: can't open file of LG commands: error description
command_file_name doesn't identify a file that can be opened. Correct spelling of file name or file's access permissions.
lgsend: can't get size of LG command file: error description
Operating system problem. Investigate and correct before rerunning.
lgsend: LG cmd file size > 64000.
Load/Go command file is too large. Split it into multiple files if possible.
lgsend: no space for application data unit.
ION system problem: have exhausted available SDR data store reserves.
lgsend: fgets failed: error description
Operating system problem. Investigate and correct before rerunning.
lgsend: can't create application data unit.
ION system problem: have exhausted available SDR data store reserves.
lgsend: can't send bundle.
ION system problem. Investigate and correct before rerunning.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/lgsend/#see-also","title":"SEE ALSO","text":"lgagent(1), lgfile(5)
"},{"location":"man/bpv7/ltpcli/","title":"NAME","text":"ltpcli - LTP-based BP convergence layer input task
"},{"location":"man/bpv7/ltpcli/#synopsis","title":"SYNOPSIS","text":"ltpcli local_node_nbr
"},{"location":"man/bpv7/ltpcli/#description","title":"DESCRIPTION","text":"ltpcli is a background \"daemon\" task that receives LTP data transmission blocks, extracts bundles from the received blocks, and passes them to the bundle protocol agent on the local ION node.
ltpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"ltp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. ltpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the LTP convergence layer protocol.
"},{"location":"man/bpv7/ltpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ltpcli.
\"1\"
ltpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart ltpcli.
No configuration files are needed.
"},{"location":"man/bpv7/ltpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ltpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such ltp duct.
No LTP induct matching local_node_nbr has been added to the BP database. Use bpadmin to stop the LTP convergence-layer protocol, add the induct, and then restart the LTP protocol.
CLI task is already started for this duct.
Redundant initiation of ltpcli.
ltpcli can't initialize LTP.
ltpadmin has not yet initialized LTP operations.
ltpcli can't open client access.
Another task has already opened the client service for BP over LTP.
ltpcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart LTP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ltpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), ltpadmin(1), ltprc(5), ltpclo(1)
"},{"location":"man/bpv7/ltpclo/","title":"NAME","text":"ltpclo - LTP-based BP convergence layer adapter output task
"},{"location":"man/bpv7/ltpclo/#synopsis","title":"SYNOPSIS","text":"ltpclo remote_node_nbr
"},{"location":"man/bpv7/ltpclo/#description","title":"DESCRIPTION","text":"ltpclo is a background \"daemon\" task that extracts bundles from the queues of segments ready for transmission via LTP to the remote bundle protocol agent identified by remote_node_nbr and passes them to the local LTP engine for aggregation, segmentation, and transmission to the remote node.
ltpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. ltpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the LTP convergence layer protocol.
"},{"location":"man/bpv7/ltpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSC protocol.
\"1\"
ltpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSC protocol.
No configuration files are needed.
"},{"location":"man/bpv7/ltpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ltpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such ltp duct.
No LTP outduct with duct name matching remote_node_nbr has been added to the BP database. Use bpadmin to stop the LTP convergence-layer protocol, add the outduct, and then restart the LTP protocol.
CLO task is already started for this duct.
Redundant initiation of ltpclo.
ltpclo can't initialize LTP.
ltpadmin has not yet initialized LTP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ltpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), ltpadmin(1), ltprc(5), ltpcli(1)
"},{"location":"man/bpv7/stcpcli/","title":"NAME","text":"sstcpcli - DTN simple TCP convergence layer input task
"},{"location":"man/bpv7/stcpcli/#synopsis","title":"SYNOPSIS","text":"stcpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/stcpcli/#description","title":"DESCRIPTION","text":"stcpcli is a background \"daemon\" task comprising 1 + N threads: one that handles TCP connections from remote stcpclo tasks, spawning sockets for data reception from those tasks, plus one input thread for each spawned socket to handle data reception over that socket.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 4556.
Each reception thread receives bundles over the associated connected socket. Each bundle received on the connection is preceded by a 32-bit unsigned integer in network byte order indicating the length of the bundle. The received bundles are passed to the bundle protocol agent on the local ION node.
stcpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"stcp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. stcpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the STCP convergence layer protocol.
"},{"location":"man/bpv7/stcpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
stcpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart stcpcli.
\"1\"
stcpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart stcpcli.
No configuration files are needed.
"},{"location":"man/bpv7/stcpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/stcpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
stcpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such stcp duct.
No STCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the STCP convergence-layer protocol, add the induct, and then restart the STCP protocol.
CLI task is already started for this duct.
Redundant initiation of stcpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart STCP.
Can't open TCP socket
Operating system error. Check errtext, correct problem, and restart STCP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart STCP.
stcpcli can't create access thread
Operating system error. Check errtext, correct problem, and restart STCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/stcpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), stcpclo(1)
"},{"location":"man/bpv7/stcpclo/","title":"NAME","text":"stcpclo - DTN simple TCP convergence layer adapter output task
"},{"location":"man/bpv7/stcpclo/#synopsis","title":"SYNOPSIS","text":"stcpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv7/stcpclo/#description","title":"DESCRIPTION","text":"stcpclo is a background \"daemon\" task that connects to a remote node's TCP socket at remote_hostname and remote_port_nbr. It then begins extracting bundles from the queues of bundles ready for transmission via TCP to this remote bundle protocol agent and transmitting those bundles over the connected socket to that node. Each transmitted bundle is preceded by a 32-bit integer in network byte order indicating the length of the bundle.
If not specified, remote_port_nbr defaults to 4556.
stcpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. stcpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the STCP convergence layer protocol.
"},{"location":"man/bpv7/stcpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
stcpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the STCP protocol.
\"1\"
stcpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the STCP protocol.
No configuration files are needed.
"},{"location":"man/bpv7/stcpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/stcpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
stcpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such stcp duct.
No STCP outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the STCP convergence-layer protocol, add the outduct, and then restart the STCP protocol.
CLO task is already started for this duct.
Redundant initiation of stcpclo.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart STCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/stcpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), stcpcli(1)
"},{"location":"man/bpv7/tcpcli/","title":"NAME","text":"tcpcli - DTN TCPCL-compliant convergence layer input task
"},{"location":"man/bpv7/tcpcli/#synopsis","title":"SYNOPSIS","text":"tcpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/tcpcli/#description","title":"DESCRIPTION","text":"tcpcli is a background \"daemon\" task comprising 3 + 2*N threads: an executive thread; a clock thread that periodically attempts to connect to remote TCPCL entities as identified by the tcp outducts enumerated in the bprc(5) file (each of which must specify the hostname[:port_nbr] to connect to); a thread that handles TCP connections from remote TCPCL entities, spawning sockets for data reception from those tasks; plus one input thread and one output thread for each connection, to handle data reception and transmission over that socket.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 4556.
Each time a connection is established, the entities will first exchange contact headers, because connection parameters need to be negotiated. tcpcli records the acknowledgement flags, reactive fragmentation flag, and negative acknowledgements flag in the contact header it receives from its peer TCPCL entity.
Each reception thread receives bundles over the associated connected socket. Each bundle received on the connection is preceded by message type, fragmentation flags, and size represented as an SDNV. The received bundles are passed to the bundle protocol agent on the local ION node.
Similarly, each transmission thread obtains outbound bundles from the local ION node, encapsulates them as noted above, and transmits them over the associated connected socket.
tcpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"tcp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. tcpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the TCP convergence layer protocol.
"},{"location":"man/bpv7/tcpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart tcpcli.
\"1\"
tcpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart tcpcli.
No configuration files are needed.
"},{"location":"man/bpv7/tcpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/tcpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such tcp duct.
No TCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the TCP convergence-layer protocol, add the induct, and then restart the TCP protocol.
CLI task is already started for this duct.
Redundant initiation of tcpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart TCP.
Can't open TCP socket
Operating system error. Check errtext, correct problem, and restart TCP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart TCP.
tcpcli can't create access thread
Operating system error. Check errtext, correct problem, and restart TCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/tcpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/tcpclo/","title":"NAME","text":"tcpclo - TCPCL-compliant convergence layer adapter output task [DEPRECATED]
"},{"location":"man/bpv7/tcpclo/#synopsis","title":"SYNOPSIS","text":"tcpclo
"},{"location":"man/bpv7/tcpclo/#description","title":"DESCRIPTION","text":"tcpclo is deprecated. The outducts for the \"tcp\" convergence-layer adapter are now drained by threads managed within tcpcli.
"},{"location":"man/bpv7/tcpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpclo terminated normally.
No configuration files are needed.
"},{"location":"man/bpv7/tcpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/tcpclo/#diagnostics","title":"DIAGNOSTICS","text":"No diagnostics apply.
"},{"location":"man/bpv7/tcpclo/#see-also","title":"SEE ALSO","text":"tcpcli(1)
"},{"location":"man/bpv7/udpcli/","title":"NAME","text":"udpcli - UDP-based BP convergence layer input task
"},{"location":"man/bpv7/udpcli/#synopsis","title":"SYNOPSIS","text":"udpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/udpcli/#description","title":"DESCRIPTION","text":"udpcli is a background \"daemon\" task that receives UDP datagrams via a UDP socket bound to local_hostname and local_port_nbr, extracts bundles from those datagrams, and passes them to the bundle protocol agent on the local ION node.
If not specified, port number defaults to 4556.
The convergence layer input task is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"udp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. udpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the UDP convergence layer protocol.
"},{"location":"man/bpv7/udpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart udpcli.
\"1\"
udpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart udpcli.
No configuration files are needed.
"},{"location":"man/bpv7/udpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/udpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such udp duct.
No UDP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the UDP convergence-layer protocol, add the induct, and then restart the UDP protocol.
CLI task is already started for this duct.
Redundant initiation of udpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart UDP.
Can't open UDP socket
Operating system error. Check errtext, correct problem, and restart UDP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart UDP.
udpcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart UDP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/udpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), udpclo(1)
"},{"location":"man/bpv7/udpclo/","title":"NAME","text":"udpclo - UDP-based BP convergence layer output task
"},{"location":"man/bpv7/udpclo/#synopsis","title":"SYNOPSIS","text":"udpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv7/udpclo/#description","title":"DESCRIPTION","text":"udpclo is a background \"daemon\" task that extracts bundles from the queues of bundles ready for transmission via UDP to a remote node's UDP socket at remote_hostname and remote_port_nbr, encapsulates those bundles in UDP datagrams, and sends those datagrams to that remote UDP socket.
udpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. udpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the UDP convergence layer protocol.
"},{"location":"man/bpv7/udpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart udpclo.
\"1\"
udpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart udpclo.
No configuration files are needed.
"},{"location":"man/bpv7/udpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/udpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No memory for UDP buffer in udpclo.
ION system error. Check errtext, correct problem, and restart UDP.
No such udp duct.
No UDP outduct with duct name remote_hostname[:<remote_port_nbr>] has been added to the BP database. Use bpadmin to stop the UDP convergence-layer protocol, add the outduct, and then restart the UDP protocol.
CLO task is already started for this engine.
Redundant initiation of udpclo.
CLO can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udpclo.
CLO write() error on socket
Operating system error. Check errtext, correct problem, and restart udpclo.
Bundle is too big for UDP CLA.
Configuration error: bundles that are too large for UDP transmission (i.e., larger than 65535 bytes) are being enqueued for udpclo. Change routing.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/udpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), udpcli(1)
"},{"location":"man/bss/","title":"Index of Man Pages","text":"bss - Bundle Streaming Service library
"},{"location":"man/bss/bss/#synopsis","title":"SYNOPSIS","text":"#include \"bss.h\"\n\ntypedef int (*RTBHandler)(time_t time, unsigned long count, char *buffer, int bufLength);\n\n[see description for available functions]\nThe BSS library supports the streaming of data over delay-tolerant networking (DTN) bundles. The intent of the library is to enable applications that pass streaming data received in transmission time order (i.e., without time regressions) to an application-specific \"display\" function -- notionally for immediate real-time display -- but to store all received data (including out-of-order data) in a private database for playback under user control. The reception and real-time display of in-order data is performed by a background thread, leaving the application's main (foreground) thread free to respond to user commands controlling playback or other application-specific functions.
The application-specific \"display\" function invoked by the background thread must conform to the RTBHandler type definition. It must return 0 on success, -1 on any error that should terminate the background thread. Only on return from this function will the background thread proceed to acquire the next BSS payload.
All data acquired by the BSS background thread is written to a BSS database comprising three files: table, list, and data. The name of the database is the root name that is common to the three files, e.g., db3.tbl, db3.lst, db3.dat would be the three files making up the db3 BSS database. All three files of the selected BSS database must reside in the same directory of the file system.
Several replay navigation functions in the BSS library require that the application provide a navigation state structure of type bssNav as defined in the bss.h header file. The application is not reponsible for populating this structure; it's strictly for the private use of the BSS library.
int bssOpen(char *bssName, char *path, char *eid)
Opens access to a BSS database, to enable data playback. bssName identifies the specific BSS database that is to be opened. path identifies the directory in which the database resides. eid is ignored. On any failure, returns -1. On success, returns zero.
int bssStart(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)
Starts a BSS data acquisition background thread. bssName identifies the BSS database into which data will be acquired. path identifies the directory in which that database resides. eid is used to open the BP endpoint at which the delivered BSS bundle payload contents will be acquired. buffer identifies a data acquisition buffer, which must be provided by the application, and bufLen indicates the length of that buffer; received bundle payloads in excess of this length will be discarded.
handler identifies the display function to which each in-order bundle payload will be passed. The time and count parameters passed to this function identify the received bundle, indicating the bundle's creation timestamp time (in seconds) and counter value. The buffer and bufLength parameters indicate the location into which the bundle's payload was acquired and the length of the acquired payload. handler must return -1 on any unrecoverable system error, 0 otherwise. A return value of -1 from handler will terminate the BSS data acquisition background thread.
On any failure, returns -1. On success, returns zero.
int bssRun(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)
A convenience function that performs both bssOpen() and bssStart(). On any failure, returns -1. On success, returns zero.
void bssClose()
Terminates data playback access to the most recently opened BSS database.
void bssStop()
Terminates the most recently initiated BSS data acquisition background thread.
void bssExit()
A convenience function that performs both bssClose() and bssStop().
long bssRead(bssNav nav, char *data, int dataLen)
Copies the data at the current playback position in the database, as indicated by nav, into data; if the length of the data is in excess of dataLen then an error condition is asserted (i.e., -1 is returned). Note that bssRead() cannot be successfully called until nav has been populated, nominally by a preceding call to bssSeek(), bssNext(), or bssPrev(). Returns the length of data read, or -1 on any error.
long bssSeek(bssNav *nav, time_t time, time_t *curTime, unsigned long *count)
Sets the current playback position in the database, in nav, to the data received in the bundle with the earliest creation time that was greater than or equal to time. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location, or -1 on any error.
long bssSeek_read(bssNav *nav, time_t time, time_t *curTime, unsigned long *count, char *data, int dataLen)
A convenience function that performs bssSeek() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, or -1 on any error.
long bssNext(bssNav *nav, time_t *curTime, unsigned long *count)
Sets the playback position in the database, in nav, to the data received in the bundle with the earliest creation time and ID count greater than that of the bundle at the current playback position. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location (if any), -2 on reaching end of list, or -1 on any error.
long bssNext_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)
A convenience function that performs bssNext() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, -2 on reaching end of list, or -1 on any error.
long bssPrev(bssNav *nav, time_t *curTime, unsigned long *count)
Sets the playback position in the database, in nav, to the data received in the bundle with the latest creation time and ID count earlier than that of the bundle at the current playback position. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location (if any), -2 on reaching end of list, or -1 on any error.
long bssPrev_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)
A convenience function that performs bssPrev() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, -2 on reaching end of list, or -1 on any error.
bp(3)
"},{"location":"man/bss/bssStreamingApp/","title":"NAME","text":"bssStreamingApp - Bundle Streaming Service transmission test program
"},{"location":"man/bss/bssStreamingApp/#synopsis","title":"SYNOPSIS","text":"bssStreamingApp own_endpoint_ID destination_endpoint_ID [class_of_service]
"},{"location":"man/bss/bssStreamingApp/#description","title":"DESCRIPTION","text":"bssStreamingApp uses BSS to send streaming data over BP from own_endpoint_ID to bssrecv listening at destination_endpoint_ID. class_of_service is as specified for bptrace(1); if omitted, bundles are sent at BP's standard priority (1).
The bundles issued by bssStreamingApp all have 65000-byte payloads, where the ASCII representation of a positive integer (increasing monotonically from 0, by 1, throughout the operation of the program) appears at the start of each payload. All bundles are sent with custody transfer requested, with time-to-live set to 1 day. The application meters output by sleeping for 12800 microseconds after issuing each bundle.
Use CTRL-C to terminate the program.
"},{"location":"man/bss/bssStreamingApp/#files","title":"FILES","text":"No configuration files are needed.
"},{"location":"man/bss/bssStreamingApp/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bss/bssStreamingApp/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bss/bssStreamingApp/#see-also","title":"SEE ALSO","text":"bssrecv(1), bss(3)
"},{"location":"man/bss/bssrecv/","title":"NAME","text":"bssrecv - Bundle Streaming Service reception test program
"},{"location":"man/bss/bssrecv/#synopsis","title":"SYNOPSIS","text":"bssrecv
"},{"location":"man/bss/bssrecv/#description","title":"DESCRIPTION","text":"bssrecv uses BSS to acquire streaming data from bssStreamingApp.
bssrecv is a menu-driven interactive test program, run from the operating system shell prompt. The program enables the user to begin and end a session of BSS data acquisition from bssStreamingApp, displaying the data as it arrives in real time; to replay data acquired during the current session; and to replay data acquired during a prior session.
The user must provide values for three parameters in order to initiate the acquisition or replay of data from bssStreamingApp:
BSS database name
All data acquired by the BSS session thread will be written to a BSS \"database\" comprising three files: table, list, and data. The name of the database is the root name that is common to the three files, e.g., db3.tbl, db3.lst, db3.dat would be the three files making up the db3 BSS database.
path name
All three files of the selected BSS database must reside in the same directory of the file system; the path name of that directory is required.
endpoint ID
In order to acquire streaming data issued by bssStreamingApp, the bssrecv session thread must open the BP endpoint to which that data is directed. For this purpose, the ID of that endpoint is needed.
bssrecv offers the following menu options:
bssrecv prompts the user for the three parameter values noted above, then opens the indicated BSS database for replay of the data in that database.
bssrecv prompts the user for the three parameter values noted above, then starts a background session thread to acquire data into the indicated database. Each bundle that is acquired is passed to a display function that prints a single line consisting of N consecutive '*' characters, where N is computed as the data number at the start of the bundle's payload data, modulo 150. Note that the database is not open for replay at this time.
bssrecv prompts the user for the three parameter values noted above, then starts a background session thread to acquire data into the indicated database (displaying the data as described for option 2 above) and also opens the database for replay.
bssrecv closes the indicated BSS database, terminating replay access.
bssrecv terminates the current background session thread. Replay access to the BSS database, if currently open, is not terminated.
bssrecv terminates the current background session thread. Replay access to the BSS database, if currently open, is also terminated.
bssrecv prompts the user for the start and end times bounding the reception interval that is to be replayed, then displays all data within that interval in both forward and reverse time order. The display function performed for this purpose is the same one that is exercised during real-time acquisition of streaming data.
bssrecv terminates.
\"0\"
bssrecv has terminated.
No configuration files are needed.
"},{"location":"man/bss/bssrecv/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bss/bssrecv/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bss/bssrecv/#see-also","title":"SEE ALSO","text":"bssStreamingApp(1), bss(3)
"},{"location":"man/bssp/","title":"Index of Man Pages","text":"bssp - Bundle Streaming Service Protocol (BSSP) communications library
"},{"location":"man/bssp/bssp/#synopsis","title":"SYNOPSIS","text":"#include \"bssp.h\"\n\ntypedef enum\n{\n BsspNoNotice = 0,\n BsspXmitSuccess,\n BsspXmitFailure,\n BsspRecvSuccess\n} BsspNoticeType;\n\n[see description for available functions]\nThe bssp library provides functions enabling application software to use BSSP to send and receive streaming data in bundles.
BSSP is designed to forward streaming data in original transmission order wherever possible but to retransmit data as necessary to ensure that the entire stream is available for playback eventually. To this end, BSSP uses not one but two underlying \"link service\" channels: (a) an unreliable \"best efforts\" channel, for data items that are successfully received upon initial transmission over every extent of the end-to-end path, and (b) a \"reliable\" channel, for data items that were lost at some point, had to be retransmitted, and therefore are now out of order. The BSS library at the destination node supports immediate \"real-time\" display of all data received on the \"best efforts\" channel in transmission order, together with database retention of all data eventually received on the \"reliable\" channel.
The BSSP notion of engine ID corresponds closely to the Internet notion of a host, and in ION engine IDs are normally indistinguishable from node numbers including the node numbers in Bundle Protocol endpoint IDs conforming to the \"ipn\" scheme.
The BSSP notion of client ID corresponds closely to the Internet notion of \"protocol number\" as used in the Internet Protocol. It enables data from multiple applications -- clients -- to be multiplexed over a single reliable link. However, for ION operations we normally use BSSP exclusively for the transmission of Bundle Protocol data, identified by client ID = 1.
int bssp_attach()
Attaches the application to BSSP functionality on the lcoal computer. Returns 0 on success, -1 on any error.
void bssp_detach()
Terminates all access to BSSP functionality on the local computer.
int bssp_engine_is_started()
Returns 1 if the local BSSP engine has been started and not yet stopped, 0 otherwise.
int bssp_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData, int inOrder, BsspSessionId *sessionId)
Sends a client service data unit to the application that is waiting for data tagged with the indicated clientId as received at the remote BSSP engine identified by destinationEngineId.
clientServiceData must be a \"zero-copy object\" reference as returned by ionCreateZco(). Note that BSSP will privately make and destroy its own reference to the client service data object; the application is free to destroy its reference at any time.
inOrder is a Boolean value indicating whether or not the service data item that is being sent is \"in order\", i.e., was originally transmitted after all items that have previously been sent to this destination by this local BSSP engine: 0 if no (meaning that the item must be transmitted using the \"reliable\" channel), 1 if yes (meaning that the item must be transmitted using the \"best-efforts\" channel.
On success, the function populates *sessionId with the source engine ID and the \"session number\" assigned to transmission of this client service data unit and returns zero. The session number may be used to link future BSSP processing events to the affected client service data. bssp_send() returns -1 on any error.
int bssp_open(unsigned int clientId)
Establishes the application's exclusive access to received service data units tagged with the indicated BSSP client service data ID. At any time, only a single application task is permitted to receive service data units for any single client service data ID.
Returns 0 on success, -1 on any error (e.g., the indicated client service is already being held open by some other application task).
int bssp_get_notice(unsigned int clientId, BsspNoticeType *type, BsspSessionId *sessionId, unsigned char *reasonCode, unsigned int *dataLength, Object *data)
Receives notices of BSSP processing events pertaining to the flow of service data units tagged with the indicated client service ID. The nature of each event is indicated by *type. Additional parameters characterizing the event are returned in *sessionId, *reasonCode, *dataLength, and *data as relevant.
The value returned in *data is always a zero-copy object; use the zco_* functions defined in \"zco.h\" to retrieve the content of that object.
When the notice is an BsspRecvSuccess, the ZCO returned in *data contains the content of a single BSSP block.
The cancellation of an export session results in delivery of a BsspXmitFailure notice. In this case, the ZCO returned in *data is a service data unit ZCO that had previously been passed to bssp_send().
bssp_get_notice() always blocks indefinitely until an BSSP processing event is delivered.
Returns zero on success, -1 on any error.
void bssp_interrupt(unsigned int clientId)
Interrupts an bssp_get_notice() invocation. This function is designed to be called from a signal handler; for this purpose, clientId may need to be obtained from a static variable.
void bssp_release_data(Object data)
Releases the resources allocated to hold data, which must be a received client service data unit ZCO.
void bssp_close(unsigned int clientId)
Terminates the application's exclusive access to received service data units tagged with the indicated client service data ID.
bsspadmin(1), bssprc(5), zco(3)
"},{"location":"man/bssp/bsspadmin/","title":"NAME","text":"bsspadmin - Bundle Streaming Service Protocol (BSSP) administration interface
"},{"location":"man/bssp/bsspadmin/#synopsis","title":"SYNOPSIS","text":"bsspadmin [ commands_filename | . ]
"},{"location":"man/bssp/bsspadmin/#description","title":"DESCRIPTION","text":"bsspadmin configures, starts, manages, and stops BSSP operations for the local ION node.
It operates in response to BSSP configuration commands found in the file commands_filename, if provided; if not, bsspadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to bsspadmin -- that is, the ION node's bsspclock task and link service adapter tasks are stopped.
The format of commands for commands_filename can be queried from bsspadmin with the 'h' or '?' commands at the prompt. The commands are documented in bssprc(5).
"},{"location":"man/bssp/bsspadmin/#exit-status","title":"EXIT STATUS","text":"0
Successful completion of BSSP administration.
bsspadmin
Enter interactive BSSP configuration command entry mode.
bsspadmin host1.bssp
Execute all configuration commands in host1.bssp, then terminate immediately.
bsspadmin .
Stop all BSSP operations on the local node.
See bssprc(5) for details of the BSSP configuration commands.
"},{"location":"man/bssp/bsspadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/bsspadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the bssprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bsspadmin. Otherwise bsspadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
bsspadmin can't attach to ION.
There is no SDR data store for bsspadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bsspadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see bssprc(5) for details.
"},{"location":"man/bssp/bsspadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/bsspadmin/#see-also","title":"SEE ALSO","text":"bssprc(5)
"},{"location":"man/bssp/bsspclock/","title":"NAME","text":"bsspclock - BSSP daemon task for managing scheduled events
"},{"location":"man/bssp/bsspclock/#synopsis","title":"SYNOPSIS","text":"bsspclock
"},{"location":"man/bssp/bsspclock/#description","title":"DESCRIPTION","text":"bsspclock is a background \"daemon\" task that periodically performs scheduled BSSP activities. It is spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol, and it is terminated by bsspadmin in response to an 'x' (STOP) command.
Once per second, bsspclock takes the following action:
First it manages the current state of all links (\"spans\"). Specifically, it infers link state changes (\"link cues\") from data rate changes as noted in the RFX database by rfxclock:
If the rate of transmission to a neighbor was zero but is now non-zero, then transmission to that neighbor resumes. The applicable \"buffer empty\" semaphore is given (enabling start of a new transmission session) and the best-efforts and/or reliable \"PDUs ready\" semaphores are given if the corresponding outbound PDU queues are non-empty (enabling transmission of PDUs by the link service output task).
If the rate of transmission to a neighbor was non-zero but is now zero, then transmission to that neighbor is suspended -- i.e., the semaphores triggering transmission will no longer be given.
If the imputed rate of transmission from a neighbor was non-zero but is now zero, then all best-efforts transmission acknowledgment timers affecting transmission to that neighbor are suspended. This has the effect of extending the interval of each affected timer by the length of time that the timers remain suspended.
If the imputed rate of transmission from a neighbor was zero but is now non-zero, then all best-efforts transmission acknowledgment timers affecting transmission to that neighbor are resumed.
Then bsspclock enqueues for reliable transmission all blocks for which the best-efforts transmission acknowledgment timeout interval has now expired but no acknowledgment has yet been received.
"},{"location":"man/bssp/bsspclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
bsspclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart bsspclock.
\"1\"
bsspclock was unable to attach to BSSP protocol operations, probably because bsspadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bssp/bsspclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/bsspclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bsspclock can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
Can't dispatch events.
An unrecoverable database error was encountered. bsspclock terminates.
Can't manage links.
An unrecoverable database error was encountered. bsspclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/bsspclock/#see-also","title":"SEE ALSO","text":"bsspadmin(1), rfxclock(1)
"},{"location":"man/bssp/bssprc/","title":"NAME","text":"bssprc - Bundle Streaming Service Protocol management commands file
"},{"location":"man/bssp/bssprc/#description","title":"DESCRIPTION","text":"BSSP management commands are passed to bsspadmin either in a file of text lines or interactively at bsspadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the BSSP management commands are described below.
"},{"location":"man/bssp/bssprc/#commands","title":"COMMANDS","text":"?
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 bsspadmin 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_nbr_of_sessions
The initialize command. Until this command is executed, BSSP is not in operation on the local ION node and most bsspadmin commands will fail.
The command uses est_max_nbr_of_sessions to configure the hashtable it will use to manage access to transmission sessions that are currently in progress. For optimum performance, est_max_nbr_of_sessions should normally equal or exceed the summation of max_nbr_of_sessions over all spans as discussed below.
a span peer_engine_nbr max_nbr_of_sessions max_block_size 'BE-BSO_command' 'RL-BSO_command [queuing_latency]
The add span command. This command declares that a span of potential BSSP data interchange exists between the local BSSP engine and the indicated (neighboring) BSSP engine.
The max_block_size is expressed as a number of bytes of data. max_block_size is used to configure transmission buffer sizes; as such, it limits client data item size. When exceeded, it causes bssp_send() to fail, and bssp_clo() to shutdown. To restart bssp_clo() without rebooting ION immediately, say, due to on-going data transfer over other convergence layers, one can try to first stop bpadmin with 'x', then stop bsspadmin with 'x', then run ionrestart to repair any issue in the volatile database, then relaunch bssp daemon and then bp daemon using corresponding configuration files. This procedure could temporarily enable resumption of operation until it is safe to reboot ION.
max_nbr_of__sessions constitutes, in effect, the local BSSP engine's retransmission \"window\" for this span. The retransmission windows of the spans impose flow control on BSSP transmission, reducing the chance ofx allocation of all available space in the ION node's data store to BSSP transmission sessions.
BE-BSO_command is script text that will be executed when BSSP is started on this node, to initiate operation of the best-efforts transmission channel task for this span. Note that \" peer_engine_nbr\" will automatically be appended to BE-BSO_command by bsspadmin before the command is executed, so only the link-service-specific portion of the command should be provided in the LSO_command string itself.
RL-BSO_command is script text that will be executed when BSSP is started on this node, to initiate operation of the reliable transmission channel task for this span. Note that \" peer_engine_nbr\" will automatically be appended to RL-BSO_command by bsspadmin 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 block at this node and transmission of an acknowledging PDU, 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 'BE-BSI_command' 'RL-BSI_command'
The add seat command. This command declares that the local BSSP engine can receive BSSP PDUs via the link service input daemons that begin running when 'BE-BSI_command' and 'RL-BSI_command' are executed.
c span peer_engine_nbr max_nbr_of_sessions max_block_size 'BE-BSO_command' 'RL-BSO_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 blocks for this span are pending transmission.
d seat 'BE-BSI_command' 'RL-BSI_command'
The delete span command. This command deletes the seat identified by 'BE-BSI_command' and 'RL-BSI_command'.
i span peer_engine_nbr
This command will print information (all configuration parameters) about the span identified by peer_engine_nbr.
i seat 'BE-BSI_command' 'RL-BSI_command'
This command will print all information (i.e., process ID numbers) about the seat identified by 'BE-BSO_command' and 'RL-BSO_command'.
l span
This command lists all declared BSSP data interchange spans.
l seat
This command lists all declared BSSP data acquisition seats.
s ['BE-BSI_command' 'RL-BSI_command']
The start command. This command starts reliable and best-efforts link service output tasks for all BSSP spans (to remote engines) from the local BSSP engine, and it starts the reliable and best-efforts link service input tasks for the local engine. 'BE-BSI_command' and 'RL-BSI_command' are deprecated but are supported for backward compatibility; if provided, the effect is the same as entering the command \"a seat 'BE-BSI_command' 'RL-BSI_command'\" prior to starting all daemon tasks.
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 BSSP computes the nominal round-trip time for an exchange of data with any remote engine. The default value is 1.
x
The stop command. This command stops all link service input and output tasks for the local BSSP engine.
w { 0 | 1 | <activity_spec> }
The BSSP watch command. This command enables and disables production of a continuous stream of user-selected BSSP activity indication characters. A watch parameter of \"1\" selects all BSSP activity indication characters; \"0\" de-selects all BSSP activity indication characters; any other activity_spec such as \"DF-\" selects the activity indication characters in the string, de-selecting all others. BSSP will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
D bssp send completed
E bssp block constructed for issuance
F bssp block issued
G bssp block popped from best-efforts transmission queue
H positive ACK received for bssp block, session ended
S bssp block received
T bssp block popped from reliable transmission queue
- unacknowledged best-efforts block requeued for reliable transmission
* session canceled locally by sender
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a span 19 20 4096 'udpbso node19.ohio.edu:5001' 'tcpbso node19.ohio.edu:5001'
Declares a data interchange span between the local BSSP engine and the remote engine (ION node) numbered 19. There can be at most 20 concurrent sessions of BSSP transmission activity to this node. Maximum block size for this span is set to 4096 bytes, and the best-efforts and reliable link service output tasks that are initiated when BSSP is started on the local ION node will execute the udpbso and tcpbso programs as indicated.
m ownqtime 2
Sets local queuing delay allowance to 2 seconds.
bsspadmin(1), udpbsi(1), udpbso(1), tcpbsi(1), tcpbso(1)
"},{"location":"man/bssp/tcpbsi/","title":"NAME","text":"tcpbsi - TCP-based reliable link service input task for BSSP
"},{"location":"man/bssp/tcpbsi/#synopsis","title":"SYNOPSIS","text":"tcpbsi {local_hostname | @}[:local_port_nbr]
"},{"location":"man/bssp/tcpbsi/#description","title":"DESCRIPTION","text":"tcpbsi is a background \"daemon\" task that receives TCP stream data via a TCP socket bound to local_hostname and local_port_nbr, extracts BSSP blocks from that stream, and passes them to the local BSSP engine. Host name \"@\" signifies that the host name returned by hostname(1) is to be used as the socket's host name. If not specified, port number defaults to 4556.
The link service input task is spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The link service input task is terminated by bsspadmin in response to an 'x' (STOP) command.
"},{"location":"man/bssp/tcpbsi/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpbsi terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart tcpbsi.
\"1\"
tcpbsi terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bsspadmin to restart tcpbsi.
No configuration files are needed.
"},{"location":"man/bssp/tcpbsi/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/tcpbsi/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpbsi can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
RL-BSI task is already started.
Redundant initiation of tcpbsi.
RL-BSI can't open TCP socket
Operating system error. Check errtext, correct problem, and restart tcpbsi.
RL-BSI can't initialize socket
Operating system error. Check errtext, correct problem, and restart tcpbsi.
tcpbsi can't create receiver thread
Operating system error. Check errtext, correct problem, and restart tcpbsi.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/tcpbsi/#see-also","title":"SEE ALSO","text":"bsspadmin(1), tcpbso(1), udpbsi(1)
"},{"location":"man/bssp/tcpbso/","title":"NAME","text":"tcpbso - TCP-based reliable link service output task for BSSP
"},{"location":"man/bssp/tcpbso/#synopsis","title":"SYNOPSIS","text":"tcpbso {remote_engine_hostname | @}[:remote_port_nbr] remote_engine_nbr
"},{"location":"man/bssp/tcpbso/#description","title":"DESCRIPTION","text":"tcpbso is a background \"daemon\" task that extracts BSSP blocks from the queue of blocks bound for the indicated remote BSSP engine and uses a TCP socket to send them to the indicated TCP port on the indicated host. If not specified, port number defaults to 4556.
Each \"span\" of BSSP data interchange between the local BSSP engine and a neighboring BSSP engine requires its own best-effort and reliable link service output tasks. All link service output tasks are spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol, and they are all terminated by bsspadmin in response to an 'x' (STOP) command.
"},{"location":"man/bssp/tcpbso/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpbso terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart tcpbso.
\"1\"
tcpbso terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bsspadmin to restart tcpbso.
No configuration files are needed.
"},{"location":"man/bssp/tcpbso/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/tcpbso/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpbso can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the BSSP database by bsspadmin.
RL-BSO task is already started for this engine.
Redundant initiation of tcpbso.
RL-BSO can't open TCP socket
Operating system error. Check errtext, correct problem, and restart tcpbso.
RL-BSO can't bind TCP socket
Operating system error. Check errtext, correct problem, and restart tcpbso.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/tcpbso/#see-abso","title":"SEE ABSO","text":"bsspadmin(1), tcpbsi(1), udpbso(1)
"},{"location":"man/bssp/udpbsi/","title":"NAME","text":"udpbsi - UDP-based best-effort link service input task for BSSP
"},{"location":"man/bssp/udpbsi/#synopsis","title":"SYNOPSIS","text":"udpbsi {local_hostname | @}[:local_port_nbr]
"},{"location":"man/bssp/udpbsi/#description","title":"DESCRIPTION","text":"udpbsi is a background \"daemon\" task that receives UDP datagrams via a UDP socket bound to local_hostname and local_port_nbr, extracts BSSP PDUs from those datagrams, and passes them to the local BSSP engine. Host name \"@\" signifies that the host name returned by hostname(1) is to be used as the socket's host name. If not specified, port number defaults to 6001.
The link service input task is spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The link service input task is terminated by bsspadmin in response to an 'x' (STOP) command.
"},{"location":"man/bssp/udpbsi/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpbsi terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart udpbsi.
\"1\"
udpbsi terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bsspadmin to restart udpbsi.
No configuration files are needed.
"},{"location":"man/bssp/udpbsi/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/udpbsi/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpbsi can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
BE-BSI task is already started.
Redundant initiation of udpbsi.
BE-BSI can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udpbsi.
BE-BSI can't initialize socket
Operating system error. Check errtext, correct problem, and restart udpbsi.
udpbsi can't create receiver thread
Operating system error. Check errtext, correct problem, and restart udpbsi.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/udpbsi/#see-also","title":"SEE ALSO","text":"bsspadmin(1), tcpbsi(1), udpbso(1)
"},{"location":"man/bssp/udpbso/","title":"NAME","text":"udpbso - UDP-based best-effort link service output task for BSSP
"},{"location":"man/bssp/udpbso/#synopsis","title":"SYNOPSIS","text":"udpbso {remote_engine_hostname | @}[:remote_port_nbr] txbps remote_engine_nbr
"},{"location":"man/bssp/udpbso/#description","title":"DESCRIPTION","text":"udpbso is a background \"daemon\" task that extracts BSSP PDUs from the queue of PDUs bound for the indicated remote BSSP engine, encapsulates them in UDP datagrams, and sends those datagrams to the indicated UDP port on the indicated host. If not specified, port number defaults to 6001.
The parameter txbps is optional and kept only for backward compatibility with older configuration files. If it is included, it's value is ignored. For context, txbps (transmission rate in bits per second) was used for congestion control but udpbso now derive its data rate from contact graph.
When invoking udpbso through bsspadmin using the start or add seat command, the remote_engine_nbr and txbps should be omitted. BSSP admin daemon will automatically provide the remote_engine_nbr.
Each \"span\" of BSSP data interchange between the local BSSP engine and a neighboring BSSP engine requires its own best-effort and reliable link service output tasks. All link service output tasks are spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol, and they are all terminated by bsspadmin in response to an 'x' (STOP) command.
"},{"location":"man/bssp/udpbso/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpbso terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart udpbso.
\"1\"
udpbso terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bsspadmin to restart udpbso.
No configuration files are needed.
"},{"location":"man/bssp/udpbso/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/udpbso/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpbso can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the BSSP database by bsspadmin.
BE-BSO task is already started for this engine.
Redundant initiation of udpbso.
BE-BSO can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udpbso.
BE-BSO can't bind UDP socket
Operating system error. Check errtext, correct problem, and restart udpbso.
Segment is too big for UDP BSO.
Configuration error: PDUs that are too large for UDP transmission (i.e., larger than 65535 bytes) are being enqueued for udpbso. Use bsspadmin to change maximum block size for this span.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/udpbso/#see-abso","title":"SEE ABSO","text":"bsspadmin(1), tcpbso(1), udpbsi(1)
"},{"location":"man/cfdp/","title":"Index of Man Pages","text":"bpcp - A remote copy utility for delay tolerant networks utilizing NASA JPL's Interplanetary Overlay Network (ION)
"},{"location":"man/cfdp/bpcp/#synopsis","title":"SYNOPSIS","text":"bpcp [-dqr | -v] [-L bundle_lifetime] [-C custody_on/off] [-S class_of_service] [host1:]file1 ... [host2:]file2
"},{"location":"man/cfdp/bpcp/#description","title":"DESCRIPTION","text":"bpcp copies files between hosts utilizing NASA JPL's Interplanetary Overlay Network (ION) to provide a delay tolerant network. File copies from local to remote, remote to local, or remote to remote are permitted. bpcp depends on ION to do any authentication or encryption of file transfers. All covergence layers over which bpcp runs MUST be reliable.
The options are permitted as follows:
** -L** bundle_lifetime
Bundle lifetime in seconds. Default is 86400 seconds (1 day).
** -C** BP_custody
Acceptable values are ON/OFF,YES/NO,1/0. Default is OFF.
** -S** class_of_service
Bundle Protocol Class of Service for this transfer. Available options are:
Default is Standard Priority.
bpcp utilizes CFDP to preform the actual file transfers. This has several important implications. First, ION's CFDP implementation requires that reliable convergence layers be used to transfer the data. Second, file permissions are not transferred. Files will be made executable on copy. Third, symbolic links are ignored for local to remote transfers and their target is copied for remote transfers. Fourth, all hosts must be specified using ION's IPN naming scheme.
In order to preform remote to local transfers or remote to remote transfers, bpcpd must be running on the remote hosts. However, bpcp should NOT be run simultaneously with bpcpd or cfdptest.
"},{"location":"man/cfdp/bpcp/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcp terminated normally.
\"1\"
bpcp terminated abnormally. Check console and the ion.log file for error messages.
No configuration files are needed.
"},{"location":"man/cfdp/bpcp/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/bpcp/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/bpcp/#see-also","title":"SEE ALSO","text":"bpcpd(1), ion(3), cfdptest(1)
"},{"location":"man/cfdp/bpcpd/","title":"NAME","text":"bpcpd - ION Delay Tolerant Networking remote file copy daemon
"},{"location":"man/cfdp/bpcpd/#synopsis","title":"SYNOPSIS","text":"bpcpd [-d | -v]
"},{"location":"man/cfdp/bpcpd/#description","title":"DESCRIPTION","text":"bpcpd is the daemon for bpcp. Together these programs copy files between hosts utilizing NASA JPL's Interplanetary Overlay Network (ION) to provide a delay tolerant network.
The options are permitted as follows:
** -d** Debug output. Repeat for increased verbosity.
** -v** Display version information.
bpcpd must be running in order to copy files from this host to another host (i.e. remote to local). Copies in the other direction (local to remote) do not require bpcpd. Further, bpcpd should NOT be run simultaneously with bpcp or cfdptest.
"},{"location":"man/cfdp/bpcpd/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcpd terminated normally.
\"1\"
bpcpd terminated abnormally. Check console and the ion.log file for error messages.
No configuration files are needed.
"},{"location":"man/cfdp/bpcpd/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/bpcpd/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/bpcpd/#see-also","title":"SEE ALSO","text":"bpcp(1), ion(3), cfdptest(1)
"},{"location":"man/cfdp/bputa/","title":"NAME","text":"bputa - BP-based CFDP UT-layer adapter
"},{"location":"man/cfdp/bputa/#synopsis","title":"SYNOPSIS","text":"bputa
"},{"location":"man/cfdp/bputa/#description","title":"DESCRIPTION","text":"bputa is a background \"daemon\" task that sends and receives CFDP PDUs encapsulated in DTN bundles.
The task is spawned automatically by cfdpadmin in response to the 's' command that starts operation of the CFDP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The UT-layer daemon is terminated by cfdpadmin in response to an 'x' (STOP) command.
"},{"location":"man/cfdp/bputa/#exit-status","title":"EXIT STATUS","text":"\"0\"
bputa terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use cfdpadmin to restart bputa.
\"1\"
bputa terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use cfdpadmin to restart bputa.
No configuration files are needed.
"},{"location":"man/cfdp/bputa/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/bputa/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
CFDP can't attach to BP.
bpadmin has not yet initialized BP protocol operations.
CFDP can't open own endpoint.
Most likely another bputa task is already running. Use cfdpadmin to stop CFDP and restart.
CFDP can't get Bundle Protocol SAP.
Most likely a BP configuration problem. Use bpadmin to stop BP and restart.
bputa can't attach to CFDP.
cfdpadmin has not yet initialized CFDP protocol operations.
bputa can't dequeue outbound CFDP PDU; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
bputa can't send PDU in bundle; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
bputa can't track PDU; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
bputa bundle reception failed.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
bputa can't receive bundle ADU.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
bputa can't handle bundle delivery.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
bputa can't handle inbound PDU.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/bputa/#see-also","title":"SEE ALSO","text":"cfdpadmin(1), bpadmin(1)
"},{"location":"man/cfdp/cfdp/","title":"NAME","text":"cfdp - CCSDS File Delivery Protocol (CFDP) communications library
"},{"location":"man/cfdp/cfdp/#synopsis","title":"SYNOPSIS","text":"#include \"cfdp.h\"\n\ntypedef enum\n{\n CksumTypeUnknown = -1,\n ModularChecksum = 0,\n CRC32CChecksum = 2,\n NullChecksum = 15\n} CfdpCksumType;\n\ntypedef int (*CfdpReaderFn)(int fd, unsigned int *checksum, CfdpCksumType ckType);\n\ntypedef int (*CfdpMetadataFn)(uvast fileOffset, unsigned int recordOffset, unsigned int length, int sourceFileFD, char *buffer);\n\ntypedef enum\n{\n CfdpCreateFile = 0,\n CfdpDeleteFile,\n CfdpRenameFile,\n CfdpAppendFile,\n CfdpReplaceFile,\n CfdpCreateDirectory,\n CfdpRemoveDirectory,\n CfdpDenyFile,\n CfdpDenyDirectory\n} CfdpAction;\n\ntypedef enum\n{\n CfdpNoEvent = 0,\n CfdpTransactionInd,\n CfdpEofSentInd,\n CfdpTransactionFinishedInd,\n CfdpMetadataRecvInd,\n CfdpFileSegmentRecvInd,\n CfdpEofRecvInd,\n CfdpSuspendedInd,\n CfdpResumedInd,\n CfdpReportInd,\n CfdpFaultInd,\n CfdpAbandonedInd\n} CfdpEventType;\n\ntypedef struct\n{\n char *sourceFileName;\n char *destFileName;\n MetadataList messagesToUser;\n MetadataList filestoreRequests;\n CfdpHandler *faultHandlers;\n int unacknowledged;\n unsigned int flowLabelLength;\n unsigned char *flowLabel;\n int recordBoundsRespected;\n int closureRequested;\n} CfdpProxyTask;\n\ntypedef struct\n{\n char *directoryName;\n char *destFileName;\n} CfdpDirListTask;\n\n[see description for available functions]\nThe cfdp library provides functions enabling application software to use CFDP to send and receive files. It conforms to the Class 1 (Unacknowledged) service class defined in the CFDP Blue Book and includes implementations of several standard CFDP user operations.
In the ION implementation of CFDP, the CFDP notion of entity ID is taken to be identical to the BP (CBHE) notion of DTN node number.
CFDP entity and transaction numbers may be up to 64 bits in length. For portability to 32-bit machines, these numbers are stored in the CFDP state machine as structures of type CfdpNumber.
To simplify the interface between CFDP the user application without risking storage leaks, the CFDP-ION API uses MetadataList objects. A MetadataList is a specially formatted SDR list of user messages, filestore requests, or filestore responses. During the time that a MetadataList is pending processing via the CFDP API, but is not yet (or is no longer) reachable from any FDU object, a pointer to the list is appended to one of the lists of MetadataList objects in the CFDP non-volatile database. This assures that any unplanned termination of the CFDP daemons won't leave any SDR lists unreachable -- and therefore un-recyclable -- due to the absence of references to those lists. Restarting CFDP automatically purges any unused MetadataLists from the CFDP database. The \"user data\" variable of the MetadataList itself is used to implement this feature: while the list is reachable only from the database root, its user data variable points to the database root list from which it is referenced; while the list is attached to a File Delivery Unit, its user data is null.
By default, CFDP transmits the data in a source file in segments of fixed size. The user application can override this behavior at the time transmission of a file is requested, by supplying a file reader callback function that reads the file -- one byte at a time -- until it detects the end of a \"record\" that has application significance. Each time CFDP calls the reader function, the function must return the length of one such record (which must be no greater than 65535).
When CFDP is used to transmit a file, a 32-bit checksum must be provided in the \"EOF\" PDU to enable the receiver of the file to assure that it was not corrupted in transit. When an application-specific file reader function is supplied, that function is responsible for updating the computed checksum as it reads each byte of the file; a CFDP library function is provided for this purpose. Two types of file checksums are supported: a simple modular checksum or a 32-bit CRC. The checksum type must be passed through to the CFDP checksum computation function, so it must be provided by (and thus to) the file reader function.
Per-segment metadata may be provided by the user application. To enable this, upon formation of each file data segment, CFDP will invoke the user-provided per-segment metadata composition callback function (if any), a function conforming to the CfdpMetadataFn type definition. The callback will be passed the offset of the segment within the file, the segment's offset within the current record (as applicable), the length of the segment, an open file descriptor for the source file (in case the data must be read in order to construct the metadata), and a 63-byte buffer in which to place the new metadata. The callback function must return the length of metadata to attach to the file data segment PDU (may be zero) or -1 in the event of a general system failure.
The return value for each CFDP \"request\" function (put, cancel, suspend, resume, report) is a reference number that enables \"events\" obtained by calling cfdp_get_event() to be matched to the requests that caused them. Events with reference number set to zero are events that were caused by autonomous CFDP activity, e.g., the reception of a file data segment.
int cfdp_attach()
Attaches the application to CFDP functionality on the local computer. Returns 0 on success, -1 on any error.
int cfdp_entity_is_started()
Returns 1 if the local CFDP entity has been started and not yet stopped, 0 otherwise.
void cfdp_detach()
Terminates all access to CFDP functionality on the local computer.
void cfdp_compress_number(CfdpNumber *toNbr, uvast from)
Converts an unsigned vast number into a CfdpNumber structure, e.g., for use when invoking the cfdp_put() function.
void cfdp_decompress_number(uvast toNbr, CfdpNumber *from)
Converts a numeric value in a CfdpNumber structure to an unsigned vast integer.
void cfdp_update_checksum(unsigned char octet, uvast *offset, unsigned int *checksum, CfdpCksumType ckType)
For use by an application-specific file reader callback function, which must pass to cfdp_update_checksum() the value of each byte (octet) it reads. offset must be octet's displacement in bytes from the start of the file. The checksum pointer is provided to the reader function by CFDP.
MetadataList cfdp_create_usrmsg_list()
Creates a non-volatile linked list, suitable for containing messages-to-user that are to be presented to cfdp_put().
int cfdp_add_usrmsg(MetadataList list, unsigned char *text, int length)
Appends the indicated message-to-user to list.
int cfdp_get_usrmsg(MetadataList list, unsigned char *textBuf, int *length)
Removes from list the first of the remaining messages-to-user contained in the list and delivers its text and length. When the last message in the list is delivered, destroys the list.
void cfdp_destroy_usrmsg_list(MetadataList *list)
Removes and destroys all messages-to-user in list and destroys the list.
MetadataList cfdp_create_fsreq_list()
Creates a non-volatile linked list, suitable for containing filestore requests that are to be presented to cfdp_put().
int cfdp_add_fsreq(MetadataList list, CfdpAction action, char *firstFileName, char *seconfdFIleName)
Appends the indicated filestore request to list.
int cfdp_get_fsreq(MetadataList list, CfdpAction *action, char *firstFileNameBuf, char *secondFileNameBuf)
Removes from list the first of the remaining filestore requests contained in the list and delivers its action code and file names. When the last request in the list is delivered, destroys the list.
void cfdp_destroy_fsreq_list(MetadataList *list)
Removes and destroys all filestore requests in list and destroys the list.
int cfdp_get_fsresp(MetadataList list, CfdpAction *action, int *status, char *firstFileNameBuf, char *secondFileNameBuf, char *messageBuf)
Removes from list the first of the remaining filestore responses contained in the list and delivers its action code, status, file names, and message. When the last response in the list is delivered, destroys the list.
void cfdp_destroy_fsresp_list(MetadataList *list)
Removes and destroys all filestore responses in list and destroys the list.
int cfdp_read_space_packets(int fd, unsigned int *checksum)
This is a standard \"reader\" function that segments the source file on CCSDS space packet boundaries. Multiple small packets may be aggregated into a single file data segment.
int cfdp_read_text_lines(int fd, unsigned int *checksum)
This is a standard \"reader\" function that segments a source file of text lines on line boundaries.
int cfdp_put(CfdpNumber *destinationEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpMetadataFn metadataFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *transactionId)
Sends the file identified by sourceFileName to the CFDP entity identified by destinationEntityNbr. destinationFileName is used to indicate the name by which the file will be catalogued upon arrival at its final destination; if NULL, the destination file name defaults to sourceFileName. If sourceFileName is NULL, it is assumed that the application is requesting transmission of metadata only (as discussed below) and destinationFileName is ignored. Note that both sourceFileName and destinationFileName are interpreted as path names, i.e., directory paths may be indicated in either or both. The syntax of path names is opaque to CFDP; the syntax of sourceFileName must conform to the path naming syntax of the source entity's file system and the syntax of destinationFileName must conform to the path naming syntax of the destination entity's file system.
The byte array identified by utParms, if non-NULL, is interpreted as transmission control information that is to be passed on to the UT layer. The nominal UT layer for ION's CFDP being Bundle Protocol, the utParms array is normally a pointer to a structure of type BpUtParms; see the bp man page for a discussion of the parameters in that structure.
closureLatency is the length of time following transmission of the EOF PDU within which a responding Transaction Finish PDU is expected. If no Finish PDU is requested, this parameter value should be zero.
messagesToUser and filestoreRequests, where non-zero, must be the addresses of non-volatile linked lists (that is, linked lists in ION's SDR database) of CfdpMsgToUser and CfdpFilestoreRequest objects identifying metadata that are intended to accompany the transmitted file. Note that this metadata may accompany a file of zero length (as when sourceFileName is NULL as noted above) -- a transmission of metadata only.
On success, the function populates *transactionID with the source entity ID and the transaction number assigned to this transmission and returns the request number identifying this \"put\" request. The transaction ID may be used to suspend, resume, cancel, or request a report on the progress of this transmission. cfdp_put() returns -1 on any error.
int cfdp_cancel(CfdpTransactionId *transactionId)
Cancels transmission or reception of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, cancellation of a file transmission may have little effect. Returns request number on success, -1 on any error.
int cfdp_suspend(CfdpTransactionId *transactionId)
Suspends transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, suspension of a file transmission may have little effect. Returns request number on success, -1 on any error.
int cfdp_resume(CfdpTransactionId *transactionId)
Resumes transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, resumption of a file transmission may have little effect. Returns request number on success, -1 on any error.
int cfdp_report(CfdpTransactionId *transactionId)
Requests issuance of a report on the transmission or reception progress of the indicated transaction. The report takes the form of a character string that is returned in a CfdpEvent structure; use cfdp_get_event() to receive the event (which may be matched to the request by request number). Returns request number on success, 0 if transaction is unknown, -1 on any error.
int cfdp_get_event(CfdpEventType *type, time_t *time, int *reqNbr, CfdpTransactionId *transactionId, char *sourceFileNameBuf, char *destFileNameBuf, uvast *fileSize, MetadataList *messagesToUser, uvast *offset, unsigned int *length, CfdpCondition *condition, uvast *progress, CfdpFileStatus *fileStatus, CfdpDeliveryCode *deliveryCode, CfdpTransactionId *originatingTransactionId, char *statusReportBuf, MetadataList *filestoreResponses);
Populates return value fields with data from the oldest CFDP event not yet delivered to the application.
cfdp_get_event() always blocks indefinitely until an CFDP processing event is delivered or the function is interrupted by an invocation of cfdp_interrupt().
On application error, returns zero but sets errno to EINVAL. Returns -1 on system failure, zero otherwise.
void cfdp_interrupt()
Interrupts an cfdp_get_event() invocation. This function is designed to be called from a signal handler.
int cfdp_rput(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpNumber *beneficiaryEntityNbr, CfdpProxyTask *proxyTask, CfdpTransactionId *transactionId)
Sends to the indicated respondent entity a \"proxy\" request to perform a file transmission. The transmission is to be subject to the configuration values in proxyTask and the destination of the file is to be the entity identified by beneficiaryEntityNbr.
int cfdp_rput_cancel(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *rputTransactionId, CfdpTransactionId *transactionId)
Sends to the indicated respondent entity a request to cancel a prior \"proxy\" file transmission request as identified by rputTransactionId, which is the value of transactionId that was returned by that earlier proxy transmission request.
int cfdp_get(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpProxyTask *proxyTask, CfdpTransactionId *transactionId)
Same as cfdp_rput except that beneficiaryEntityNbr is omitted; the local entity is the implicit beneficiary of the request.
int cfdp_rls(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpDirListTask *dirListTask, CfdpTransactionId *transactionId)
Sends to the indicated respondent entity a request to prepare a directory listing, save that listing in a file, and send it to the local entity. The request is subject to the configuration values in dirListTask.
int cfdp_preview(CfdpTransactionId *transactionId, uvast offset, unsigned int length, char *buffer);
This function is provided to enable the application to get an advance look at the content of a file that CFDP has not yet fully received. Reads length bytes starting at offset bytes from the start of the file that is the destination file of the transaction identified by transactionID, into buffer. On user error (transaction is nonexistent or is outbound, or offset is beyond the end of file) returns 0. On system failure, returns -1. Otherwise returns number of bytes read.
int cfdp_map(CfdpTransactionId *transactionId, unsigned int *extentCount, CfdpExtent *extentsArray);
This function is provided to enable the application to report on the portions of a partially-received file that have been received and written. Lists the received continuous data extents in the destination file of the transaction identified by transactionID. The extents (offset and length) are returned in the elements of extentsArray; the number of extents returned in the array is the total number of continuous extents received so far, or extentCount, whichever is less. The total number of extents received so far is returned as the new value of extentCount. On system failure, returns -1. Otherwise returns 0.
cfdpadmin(1), cfdprc(5)
"},{"location":"man/cfdp/cfdpadmin/","title":"NAME","text":"cfdpadmin - ION's CCSDS File Delivery Protocol (CFDP) administration interface
"},{"location":"man/cfdp/cfdpadmin/#synopsis","title":"SYNOPSIS","text":"cfdpadmin [ commands_filename | . | ! ]
"},{"location":"man/cfdp/cfdpadmin/#description","title":"DESCRIPTION","text":"cfdpadmin configures, starts, manages, and stops CFDP operations for the local ION node.
It operates in response to CFDP configuration commands found in the file commands_filename, if provided; if not, cfdpadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to cfdpadmin -- that is, the ION node's cfdpclock task and UT layer service task (nominally bputa) are stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's cfdpclock task and UT layer service task (nominally bputa) are restarted.
The format of commands for commands_filename can be queried from cfdpadmin with the 'h' or '?' commands at the prompt. The commands are documented in cfdprc(5).
"},{"location":"man/cfdp/cfdpadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of CFDP administration.
cfdpadmin
Enter interactive CFDP configuration command entry mode.
cfdpadmin host1.cfdprc
Execute all configuration commands in host1.cfdprc, then terminate immediately.
cfdpadmin .
Stop all CFDP operations on the local node.
See cfdprc(5) for details of the CFDP configuration commands.
"},{"location":"man/cfdp/cfdpadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/cfdpadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the cfdprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to cfdpadmin. Otherwise cfdpadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
cfdpadmin can't attach to ION.
There is no SDR data store for cfdpadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause cfdpadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see cfdprc(5) for details.
"},{"location":"man/cfdp/cfdpadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/cfdpadmin/#see-also","title":"SEE ALSO","text":"cfdprc(5)
"},{"location":"man/cfdp/cfdpclock/","title":"NAME","text":"cfdpclock - CFDP daemon task for managing scheduled events
"},{"location":"man/cfdp/cfdpclock/#synopsis","title":"SYNOPSIS","text":"cfdpclock
"},{"location":"man/cfdp/cfdpclock/#description","title":"DESCRIPTION","text":"cfdpclock is a background \"daemon\" task that periodically performs scheduled CFDP activities. It is spawned automatically by cfdpadmin in response to the 's' command that starts operation of the CFDP protocol, and it is terminated by cfdpadmin in response to an 'x' (STOP) command.
Once per second, cfdpclock takes the following action:
First it scans all inbound file delivery units (FDUs). For each one whose check timeout deadline has passed, it increments the check timeout count and resets the check timeout deadline. For each one whose check timeout count exceeds the limit configured for this node, it invokes the Check Limit Reached fault handling procedure.
Then it scans all outbound FDUs. For each one that has been Canceled, it cancels all extant PDU bundles and sets transmission progress to the size of the file, simulating the completion of transmission. It destroys each outbound FDU whose transmission is completed.
"},{"location":"man/cfdp/cfdpclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
cfdpclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use cfdpadmin to restart cfdpclock.
\"1\"
cfdpclock was unable to attach to CFDP protocol operations, probably because cfdpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/cfdp/cfdpclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/cfdpclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
cfdpclock can't initialize CFDP.
cfdpadmin has not yet initialized CFDP protocol operations.
Can't dispatch events.
An unrecoverable database error was encountered. cfdpclock terminates.
Can't manage links.
An unrecoverable database error was encountered. cfdpclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/cfdpclock/#see-also","title":"SEE ALSO","text":"cfdpadmin(1)
"},{"location":"man/cfdp/cfdprc/","title":"NAME","text":"cfdprc - CCSDS File Delivery Protocol management commands file
"},{"location":"man/cfdp/cfdprc/#description","title":"DESCRIPTION","text":"CFDP management commands are passed to cfdpadmin either in a file of text lines or interactively at cfdpadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the CFDP management commands are described below.
"},{"location":"man/cfdp/cfdprc/#commands","title":"COMMANDS","text":"?
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 cfdpadmin 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
The initialize command. Until this command is executed, CFDP is not in operation on the local ION node and most cfdpadmin commands will fail.
a entity> <entity nbr> <rtt> <incstype> <outcstype>
The add entity command. This command will add a new remote CFDP entity to the CFDP management information base. Valid UT protocol names are bp and tcp. Endpoint name is EID for bp, socket spec (IP address:port number) for tcp. RTT is round-trip time, used to set acknowledgement timers. incstype is the type of checksum to use when validating data received from this entity; valid values are 0 (modular checksum), 2 (CRC32C), and 15 (the null checksum). outcstype is the type of checksum to use when computing the checksum for transmitting data to this entity.
c entity> <entity nbr> <rtt> <incstype> <outcstype>
The change entity command. This command will change information associated with an existing entity in the CFDP management information base.
d entity> <entity nbr>
The delete entity command. This command will delete an existing entity from the CFDP management information base.
i [<entity nbr>]
The info command. When entity nbr is provided, this command will print information about the indicated entity. Otherwise this command will print information about the current state of the local CFDP entity, including the current settings of all parameters that can be managed as described below.
s 'UTS command'
The start command. This command starts the UT-layer service task for the local CFDP entity.
m discard { 0 | 1 }
The manage discard command. This command enables or disables the discarding of partially received files upon cancellation of a file reception. The default value is 1;
m requirecrc { 0 | 1 }
The manage CRC data integrity command. This command enables or disables the attachment of CRCs to all PDUs issued by the local CFDP entity. The default value is 0;
m fillchar file_fill_character
The manage fill character command. This command establishes the fill character to use for the portions of an incoming file that have not yet been received. The fill character is normally expressed in hex, e.g., the default value is 0xaa.
m ckperiod check_cycle_period
The manage check interval command. This command establishes the number of seconds following reception of the EOF PDU -- or following expiration of a prior check cycle -- after which the local CFDP will check for completion of a file that is being received. Default value is 86400 (i.e., one day).
m maxtimeouts check_cycle_limit
The manage check limit command. This command establishes the number of check cycle expirations after which the local CFDP entity will invoke the check cycle expiration fault handler upon expiration of a check cycle. Default value is 7.
m maxevents event_queue_limit
The manage event queue limit command. This command establishes the maximum number of unread service indications (CFDP \"events\") that may be queued up for delivery at any time. When the events queue length exceeds this figure, events are simply deleted (in decreasing age order, oldest first) until the the limit is no longer exceeded. Default value is 20.
m maxtrnbr max_transaction_number
The manage transaction numbers command. This command establishes the largest possible transaction number used by the local CFDP entity for file transmission transactions. After this number has been used, the transaction number assigned to the next transaction will be 1. The default value is 999999999.
m segsize max_bytes_per_file_data_segment
The manage segment size command. This command establishes the number of bytes of file data in each file data PDU transmitted by the local CFDP entity in the absence of an application-supplied reader function. The default value is 65000.
m inactivity inactivity_period
The manage inactivity period command. This command establishes the number of seconds that a CFDP file transfer is allowed to go idle before being canceled for inactivity. The default is one day.
x
The stop command. This command stops the UT-layer service task for the local CFDP engine.
w { 0 | 1 | <activity_spec> }
The CFDP watch command. This command enables and disables production of a continuous stream of user-selected CFDP activity indication characters. A watch parameter of \"1\" selects all CFDP activity indication characters; \"0\" de-selects all CFDP activity indication characters; any other activity_spec such as \"p\" selects all activity indication characters in the string, de-selecting all others. CFDP will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
p CFDP PDU transmitted
q CFDP PDU received
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
m requirecrc 1
Initiates attachment of CRCs to all subsequently issued CFDP PDUs.
cfdpadmin(1), bputa(1)
"},{"location":"man/cfdp/cfdptest/","title":"NAME","text":"cfdptest - CFDP test shell for ION
"},{"location":"man/cfdp/cfdptest/#synopsis","title":"SYNOPSIS","text":"cfdptest [ commands_filename ]
"},{"location":"man/cfdp/cfdptest/#description","title":"DESCRIPTION","text":"cfdptest provides a mechanism for testing CFDP file transmission. It can be used in either scripted or interactive mode. All bundles containing CFDP PDUs are sent with custody transfer requested and with all bundle status reporting disabled.
When scripted with commands_filename, cfdptest operates in response to CFDP management commands contained in the provided commands file. Each line of text in the file is interpreted as a single command comprising several tokens: a one-character command code and, in most cases, one or more command arguments of one or more characters. The commands configure and initiate CFDP file transmission operations.
If no file is specified, cfdptest instead offers the user an interactive \"shell\" for command entry. cfdptest prints a prompt string (\": \") to stdout, accepts strings of text from stdin, and interprets each string as a command.
The supported cfdptest commands (whether interactive or scripted) are as follows:
?
The help command. This will display a listing of the commands and their formats. It is the same as the h command.
h
An alternate form of the help command.
z [<number of seconds to pause>]
The pause command. When cfdptest is running in interactive mode, this command causes the console input processing thread to pause the indicated number of seconds (defaulting to 1) before processing the next command. This is provided for use in test scripting.
d <destination CFDP entity ID number>
The destination command. This command establishes the CFDP entity to which the next file transmission operation will be directed. CFDP entity numbers in ION are, by convention, the same as BP node numbers.
f <source file path name>
The from command. This command identifies the file that will be transmitted when the next file transmission operation is commanded.
t <destination file path name>
The to command. This command provides the name for the file that will be created at the receiving entity when the next file transmission operation is commanded.
l <lifetime in seconds>
The time-to-live command. This command establishes the time-to-live for all subsequently issued bundles containing CFDP PDUs. If not specified, the default value 86400 (1 day) is used.
p <priority>
The priority command. This command establishes the priority (class of service) for all subsequently issued bundles containing CFDP PDUs. Valid values are 0, 1, and 2. If not specified, priority is 1.
o <ordinal>
The ordinal command. This command establishes the \"ordinal\" (sub-priority within priority 2) for all subsequently issued bundles containing CFDP PDUs. Valid values are 0-254. If not specified, ordinal is 0.
m <mode>
The mode command. This command establishes the transmission mode (\"best-effort\" or assured) for all subsequently issued bundles containing CFDP PDUs. Valid values are 0 (assured, reliable, with reliability provided by a reliable DTN convergence layer protocol), 1 (best-effort, unreliable), and 2 (assured, reliable, but with reliability provided by BP custody transfer). If not specified, transmission mode is 0.
a <latency in seconds>
The closure latency command. This command establishes the transaction closure latency for all subsequent file transmission operations. When it is set to zero, the file transmission is \"open loop\" and the CFDP transaction at the sending entity finishes when the EOF is sent. Otherwise, the receiving CFDP entity is being asked to send a \"Finished\" PDU back to the sending CFDP entity when the transaction finishes at the receiving entity. Normally the transaction finishes at the sending entity only when that Finished PDU is received. However, when closure latency seconds elapse following transmission of the EOF PDU prior to receipt of the Finished PDU, the transaction finishes immediately with a Check Timer fault.
n { 0 | 1 }
The segment metadata command. This command controls the insertion of sample segment metadata -- a string representation of the current time -- in every file data segment PDU. A value of 1 enables segment metadata insertion, while a value of 0 disables it.
g <srrflags>
The srrflags command. This command establishes the BP status reporting that will be requested for all subsequently issued bundles containing CFDP PDUs. srrflags must be a status reporting flags string as defined for bptrace(1): a sequence of status report flags, separated by commas, with no embedded whitespace. Each status report flag must be one of the following: rcv, ct, fwd, dlv, del.
c <criticality>
The criticality command. This command establishes the criticality for all subsequently issued bundles containing CFDP PDUs. Valid values are 0 (not critical) and 1 (critical). If not specified, criticality is 0.
r <action code nbr> <first path name> <second path name>
The filestore request command. This command adds a filestore request to the metadata that will be issued when the next file transmission operation is commanded. Action code numbers are:
u '<message text>'
The user message command. This command adds a user message to the metadata that will be issued when the next file transmission operation is commanded.
&
The send command. This command initiates file transmission as configured by the most recent preceding d, f, t, and a commands.
|
The get command. This command causes a request for file transmission to the local node, subject to the parameters provided by the most recent preceding f, t, and a commands, to be sent to the entity identified by the most recent preceding d command.
NOTE that 'get' in CFDP is implemented very differently from 'send'. The 'send' operation is a native element of the CFDP protocol. The 'get' operation is implemented by sending to the responding entity a standardized sequence of message-to-user messages in a Metadata PDU - the user application at the responding entity receives those messages and initiates a 'send' to accomplish transmission of the file. This means that 'send' can succeed even if no user application is running at the remote node, but 'get' cannot.
^
The cancel command. This command cancels the most recently initiated file transmission.
%
The suspend command. This command suspends the most recently initiated file transmission.
$
The resume command. This command resumes the most recently initiated file transmission.
#
The report command. This command reports on the most recently initiated file transmission.
q
The quit command. Terminates the cfdptest program.
cfdptest in interactive mode also spawns a CFDP event handling thread. The event thread receives CFDP service indications and simply prints lines of text to stdout to announce them.
NOTE that when cfdptest runs in scripted mode it does not spawn an event handling thread, which makes it possible for the CFDP events queue to grow indefinitely unless some other task consumes and reports on the events. One simple solution is to run an interactive cfdptest task in background, simply to keep the event queue cleared, while scripted non-interactive cfdptest tasks are run in the foreground.
"},{"location":"man/cfdp/cfdptest/#exit-status","title":"EXIT STATUS","text":"\"0\"
cfdptest has terminated. Any problems encountered during operation will be noted in the ion.log log file.
See above for details on valid commands_filename commands.
"},{"location":"man/cfdp/cfdptest/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/cfdptest/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by cfdptest are written to the ION log file ion.log.
Can't open command file...
The file identified by commands_filename doesn't exist.
cfdptest can't initialize CFDP.
cfdpadmin has not yet initialized CFDP operations.
Can't put FDU.
The attempt to initiate file transmission failed. See the ION log for additional diagnostic messages from the CFDP library.
Failed getting CFDP event.
The attempt to retrieve a CFDP service indication failed. See the ION log for additional diagnostic messages from the CFDP library.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/cfdptest/#see-also","title":"SEE ALSO","text":"cfdpadmin(1), cfdp(3)
"},{"location":"man/cfdp/tcputa/","title":"NAME","text":"tcputa - TCP/IP-based CFDP UT-layer adapter
"},{"location":"man/cfdp/tcputa/#synopsis","title":"SYNOPSIS","text":"tcputa
"},{"location":"man/cfdp/tcputa/#description","title":"DESCRIPTION","text":"tcputa is a background \"daemon\" task that sends and receives CFDP PDUs via a TCP/IP socket.
The task is spawned automatically by cfdpadmin in response to the 's' command that starts operation of the CFDP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The UT-layer daemon is terminated by cfdpadmin in response to an 'x' (STOP) command.
"},{"location":"man/cfdp/tcputa/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcputa terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use cfdpadmin to restart tcputa.
\"1\"
tcputa terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use cfdpadmin to restart tcputa.
No configuration files are needed.
"},{"location":"man/cfdp/tcputa/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/tcputa/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcputa can't attach to CFDP.
cfdpadmin has not yet initialized CFDP protocol operations.
tcputa can't dequeue outbound CFDP PDU; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
tcputa can't track PDU; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
tcputa can't handle inbound PDU.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/tcputa/#see-also","title":"SEE ALSO","text":"cfdpadmin(1), bpadmin(1)
"},{"location":"man/dgr/","title":"Index of Man Pages","text":"dgr - Datagram Retransmission system library
"},{"location":"man/dgr/dgr/#synopsis","title":"SYNOPSIS","text":"#include \"dgr.h\"\n\n[see description for available functions]\nThe DGR library is an alternative implementation of a subset of LTP, intended for use over UDP/IP in the Internet; unlike ION's canonical LTP implementation it includes a congestion control mechanism that interprets LTP block transmission failure as an indication of network congestion (not data corruption) and reduces data transmission rate in response.
As such, DGR differs from many reliable-UDP systems in two main ways:
It uses adaptive timeout interval computation techniques\n borrowed from TCP to try to avoid introducing congestion\n into the network.\n\n It borrows the concurrent-session model of transmission\n from LTP (and ultimately from CFDP), rather than waiting\n for one datagram to be acknowledged before sending the next,\n to improve bandwidth utilization.\nAt this time DGR is interoperable with other implementations of LTP only when each block it receives is transmitted in a single LTP data segment encapsulated in a single UDP datagram. More complex LTP behavior may be implemented in the future.
int dgr_open(uvast ownEngineId, unsigned int clientSvcId, unsigned short ownPortNbr, unsigned int ownIpAddress, char *memmgrName, Dgr *dgr, DgrRC *rc)
Establishes the application's access to DGR communication service.
ownEngineId is the sending LTP engine ID that will characterize segments issued by this DGR service access point. In order to prevent erroneous system behavior, never assign the same LTP engine ID to any two interoperating DGR SAPs.
clientSvcId identifies the LTP client service to which all LTP segments issued by this DGR service access point will be directed.
ownPortNbr is the port number to use for DGR service. If zero, a system-assigned UDP port number is used.
ownIpAddress is the Internet address of the network interface to use for DGR service. If zero, this argument defaults to the address of the interface identified by the local machine's host name.
memmgrName is the name of the memory manager (see memmgr(3)) to use for dynamic memory management in DGR. If NULL, defaults to the standard system malloc() and free() functions.
dgr is the location in which to store the service access pointer that must be supplied on subsequent DGR function invocations.
rc is the location in which to store the DGR return code resulting from the attempt to open this service access point (always DgrOpened).
On any failure, returns -1. On success, returns zero.
void dgr_getsockname(Dgr dgr, unsigned short *portNbr, unsigned int *ipAddress)
States the port number and IP address of the UDP socket used for this DGR service access point.
void dgr_close(Dgr dgr)
Reverses dgr_open(), releasing resources where possible.
int dgr_send(Dgr dgr, unsigned short toPortNbr, unsigned int toIpAddress, int notificationFlags, char *content, int length, DgrRC *rc)
Sends the indicated content, of length as indicated, to the remote DGR service access point identified by toPortNbr and toIpAddress. The message will be retransmitted as necessary until either it is acknowledged or DGR determines that it cannot be delivered.
notificationFlags, if non-zero, is the logical OR of the notification behaviors requested for this datagram. Available behaviors are DGR_NOTE_FAILED (a notice of datagram delivery failure will issued if delivery of the datagram fails) and DGR_NOTE_ACKED (a notice of datagram delivery success will be issued if delivery of the datagram succeeds). Notices are issued via dgr_receive() that is, the thread that calls dgr_receive() on this DGR service access point will receive these notices interspersed with inbound datagram contents.
length of content must be greater than zero and may be as great as 65535, but lengths greater than 8192 may not be supported by the local underlying UDP implementation; to minimize the chance of data loss when transmitting over the internet, length should not exceed 512.
rc is the location in which to store the DGR return code resulting from the attempt to send the content.
On any failure, returns -1 and sets *rc to DgrFailed. On success, returns zero.
int dgr_receive(Dgr dgr, unsigned short *fromPortNbr, unsigned int *fromIpAddress, char *content, int *length, int *errnbr, int timeoutSeconds, DgrRC *rc)
Delivers the oldest undelivered DGR event queued for delivery.
DGR events are of two type: (a) messages received from a remote DGR service access point and (b) notices of previously sent messages that DGR has determined either have been or cannot be delivered, as requested in the notificationFlags parameters provided to the dgr_send() calls that sent those messages.
In the former case, dgr_receive() will place the content of the inbound message in content, its length in length, and the IP address and port number of the sender in fromIpAddress and fromPortNbr, and it will set *rc to DgrDatagramReceived and return zero.
In the latter case, dgr_receive() will place the content of the affected outbound message in content and its length in length and return zero. If the event being reported is a delivery success, then DgrDatagramAcknowledged will be placed in *rc. Otherwise, DgrDatagramNotAcknowledged will be placed in *rc and the relevant errno (if any) will be placed in *errnbr.
The content buffer should be at least 65535 bytes in length to enable delivery of the content of the received or delivered/undeliverable message.
timeoutSeconds controls blocking behavior. If timeoutSeconds is DGR_BLOCKING (i.e., -1), dgr_receive() will not return until (a) there is either an inbound message to deliver or an outbound message delivery result to report, or (b) the function is interrupted by means of dgr_interrupt(). If timeoutSeconds is DGR_POLL (i.e., zero), dgr_receive() returns immediately; if there is currently no inbound message to deliver and no outbound message delivery result to report, the function sets *rc to DgrTimedOut and returns zero. For any other positive value of timeoutSeconds, dgr_receive() returns after the indicated number of seconds have lapsed (in which case the returned value of *rc is DgrTimedOut), or when there is a message to deliver or a delivery result to report, or when the function is interrupted by means of dgr_interrupt(), whichever occurs first. When the function returns due to interruption by dgr_interrupt(), the value placed in *rc is DgrInterrupted instead of DgrDatagramReceived.
rc is the location in which to store the DGR return code resulting from the attempt to receive content.
On any I/O error or other unrecoverable system error, returns -1. Otherwise always returns zero, placing DgrFailed in *rc and writing a failure message in the event of an operating error.
void dgr_interrupt(Dgr dgr)
Interrupts a dgr_receive() invocation that is currently blocked. Designed to be called from a signal handler; for this purpose, dgr may need to be obtained from a static variable.
ltp(3), file2dgr(1), dgr2file(1)
"},{"location":"man/dgr/dgr2file/","title":"NAME","text":"dgr2file - DGR reception test program
"},{"location":"man/dgr/dgr2file/#synopsis","title":"SYNOPSIS","text":"dgr2file
"},{"location":"man/dgr/dgr2file/#description","title":"DESCRIPTION","text":"dgr2file uses DGR to receive multiple copies of the text of a file transmitted by file2dgr, writing each copy of the file to the current working directory. The name of each file written by dgr2file is file_copy_cycleNbr, where cycleNbr is initially zero and is increased by 1 every time dgr2file closes the file it is currently writing and opens a new one.
Upon receiving a DGR datagram from file2dgr, dgr2file extracts the content of the datagram (either a line of text from the file that is being transmitted by file2dgr or else an EOF string indicating the end of that file). It appends each extracted line of text to the local copy of that file that dgr2file is currently writing. When the extracted datagram content is an EOF string (the ASCII text \"*** End of the file ***\"), dgr2file closes the file it is writing, increments cycleNbr, opens a new copy of the file for writing, and prints the message \"working on cycle cycleNbr.\"
dgr2file always receives datagrams at port 2101.
"},{"location":"man/dgr/dgr2file/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgr2file has terminated.
No configuration files are needed.
"},{"location":"man/dgr/dgr2file/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dgr/dgr2file/#diagnostics","title":"DIAGNOSTICS","text":"can't open dgr service
Operating system error. Check errtext, correct problem, and rerun.
can't open output file
Operating system error. Check errtext, correct problem, and rerun.
dgr_receive failed
Operating system error. Check errtext, correct problem, and rerun.
can't write to output file
Operating system error. Check errtext, correct problem, and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dgr/dgr2file/#see-also","title":"SEE ALSO","text":"file2dgr(1), dgr(3)
"},{"location":"man/dgr/file2dgr/","title":"NAME","text":"file2dgr - DGR transmission test program
"},{"location":"man/dgr/file2dgr/#synopsis","title":"SYNOPSIS","text":"file2dgr remoteHostName fileName [nbrOfCycles]
"},{"location":"man/dgr/file2dgr/#description","title":"DESCRIPTION","text":"file2dgr uses DGR to send nbrOfCycles copies of the text of the file named fileName to the dgr2file process running on the computer identified by remoteHostName. If not specified (or if less than 1), nbrOfCycles defaults to 1. After sending all lines of the file, file2dgr sends a datagram containing an EOF string (the ASCII text \"*** End of the file ***\") before reopening the file and starting transmission of the next copy.
When all copies of the file have been sent, file2dgr prints a performance report:
Bytes sent = I<byteCount>, usec elapsed = I<elapsedTime>.\n\n Sending I<dataRate> bits per second.\n\"0\"
file2dgr has terminated.
No configuration files are needed.
"},{"location":"man/dgr/file2dgr/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dgr/file2dgr/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by file2dgr are written to the ION log file ion.log.
Can't open dgr service.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't open input file
Operating system error. Check errtext, correct problem, and rerun.
Can't acquire DGR working memory.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't reopen input file
Operating system error. Check errtext, correct problem, and rerun.
Can't read from input file
Operating system error. Check errtext, correct problem, and rerun.
dgr_send failed.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dgr/file2dgr/#see-also","title":"SEE ALSO","text":"file2dgr(1), dgr(3)
"},{"location":"man/dtpc/","title":"Index of Man Pages","text":"dtpc - Delay-Tolerant Payload Conditioning (DTPC) communications library
"},{"location":"man/dtpc/dtpc/#synopsis","title":"SYNOPSIS","text":"#include \"dtpc.h\"\n\n[see description for available functions]\nThe dtpc library provides functions enabling application software to use Delay-Tolerant Payload Conditioning (DTPC) when exchanging information over a delay-tolerant network. DTPC is an application service protocol, running in a layer immediately above Bundle Protocol, that offers delay-tolerant support for several end-to-end services to applications that may require them. These services include delivery of application data items in transmission (rather than reception) order; detection of reception gaps in the sequence of transmitted application data items, with end-to-end negative acknowledgment of the missing data; end-to-end positive acknowledgment of successfully received data; end-to-end retransmission of missing data, driven either by negative acknowledgment or timer expiration; suppression of duplicate application data items; aggregation of small application data items into large bundle payloads, to reduce bundle protocol overhead; and application-controlled elision of redundant data items in aggregated payloads, to improve link utiliization.
int dptc_attach( )
Attaches the application to DTPC functionality on the local computer. Returns 0 on success, -1 on any error.
void dptc_detach( )
Terminates all access to DTPC functionality on the local computer.
int dtpc_entity_is_started( )
Returns 1 if the local DTPC entity has been started and not yet stopped, 0 otherwise.
int dtpc_open(unsigned int topicID, DtpcElisionFn elisionFn, DtpcSAP *dtpcsapPtr)
Establishes the application as the sole authorized client for posting and receiving application data items on topic topicID within the local BP node. On success, the service access point for posting and receiving such data items is placed in *dtpcsapPtr, the elision callback function elisionFn (if not NULL) is associated with this topic, and 0 is returned. Returns -1 on any error.
int dtpc_send(unsigned int profileID, DtpcSAP sap, char *destEid, unsigned int maxRtx, unsigned int aggrSizeLimit, unsigned int aggrTimeLimit, int lifespan, BpAncillaryData *ancillaryData, unsigned char srrFlags, BpCustodySwitch custodySwitch, char *reportToEid, int classOfService, Object item, unsigned int length)
Inserts an application data item into an outbound DTPC application data unit destined for destEid.
Transmission of that outbound ADU will be subject to the profile identified by profileID, as asserted by dtpcadmin(1), if profileID is non-zero. In that case, maxRtx, aggrSizeLimit, aggrTimeLimit, lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService are ignored.
If profileID is zero then the profile asserted by dtpcadmin(1) that matches maxRtx, aggrSizeLimit, aggrTimeLimit, lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService will govern transmission of the ADU, unless no such profile has been asserted, in which case dtpc_send() returns 0 indicating user error.
maxRtx is the maximum number of times any single DTPC ADU transmitted subject to the indicated profile may be retransmitted by the DTPC entity. If maxRtx is zero, then the DTPC transport service features (in-order delivery, end-to-end acknowledgment, etc.) are disabled for this profile.
aggrSizeLimit is the size threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrSizeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
aggrTimeLimit is the time threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrTimeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService are as defined for bp_send (see bp(3)).
item must be an object allocated within ION's SDR \"heap\", and length must be the length of that object. The item will be inserted into the outbound ADU's list of data items posted for the topic associated with sap, and the elision callback function declared for sap (if any, and if the applicable profile does not disable transmission optimization features) will be invoked immediately after insertion of the application data item but before DTPC makes any decision on whether or not to initiate transmission of the outbound ADU.
The function returns 1 on success, 0 on any user application error, -1 on any system error.
int dtpc_receive(DtpcSAP sap, DtpcDelivery *dlvBuffer, int timeoutSeconds)
Receives a single DTPC application data item, or reports on some failure of DTPC reception activity.
The \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one application data item on the topic associated with sap has not yet been delivered to the SAP, then the payload of the oldest such item will be returned in dlvBuffer->item and dlvBuffer->result will be set to PayloadPresent. If there is no such item, dtpc_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is DTPC_POLL (i.e., zero) and no application data item is awaiting delivery, or if timeoutSeconds is greater than zero but no item arrives before timeoutSeconds have elapsed, then dlvBuffer->result will be set to ReceptionTimedOut. If timeoutSeconds is DTPC_BLOCKING (i.e., -1) then bp_receive() blocks until either an item arrives or the function is interrupted by an invocation of dtpc_interrupt().
dlvBuffer->result will be set to ReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer->result will be set to DtpcServiceStopped in the event that DTPC service has been terminated on the local node.
The application data item delivered in the DTPC delivery structure, if any, will be an object allocated within ION's SDR \"heap\"; the length of that object will likewise be provided in the DtpcDelivery structure.
Be sure to call dtpc_release_delivery() after every successful invocation of dtpc_receive().
The function returns 0 on success, -1 on any error.
void dtpc_interrupt(DtpcSAP sap)
Interrupts a dtpc_receive() invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, sap may need to be obtained from a static variable.
void dtpc_release_delivery(DtpcDelivery *dlvBuffer)
Releases resources allocated to the indicated DTPC delivery.
void dtpc_close(DtpcSAP sap)
Removes the application as the sole authorized client for posting and receiving application data items on the topic indicated in sap within the local BP node. The application relinquishes its ability to send and receive application data items on the indicated topic.
dtpcadmin(1), dtpcrc(5), bp(3)
"},{"location":"man/dtpc/dtpcadmin/","title":"NAME","text":"dtpcadmin - Delay-Tolerant Payload Conditioning (DTPC) administration interface
"},{"location":"man/dtpc/dtpcadmin/#synopsis","title":"SYNOPSIS","text":"dtpcadmin [ commands_filename | . ]
"},{"location":"man/dtpc/dtpcadmin/#description","title":"DESCRIPTION","text":"dtpcadmin configures, starts, manages, and stops DTPC operations for the local ION node.
It operates in response to DTPC configuration commands found in the file commands_filename, if provided; if not, dtpcadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to dtpcadmin -- that is, the ION node's dtpcclock task and dtpcd task are stopped.
The format of commands for commands_filename can be queried from dtpcadmin with the 'h' or '?' commands at the prompt. The commands are documented in dtpcrc(5).
"},{"location":"man/dtpc/dtpcadmin/#exit-status","title":"EXIT STATUS","text":"0
Successful completion of DTPC administration.
dtpcadmin
Enter interactive DTPC configuration command entry mode.
dtpcadmin host1.dtpc
Execute all configuration commands in host1.dtpc, then terminate immediately.
dtpcadmin .
Stop all DTPC operations on the local node.
See dtpcrc(5) for details of the DTPC configuration commands.
"},{"location":"man/dtpc/dtpcadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the dtpcrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to dtpcadmin. Otherwise dtpcadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
dtpcadmin can't attach to ION.
There is no SDR data store for dtpcadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause dtpcadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see dtpcrc(5) for details.
"},{"location":"man/dtpc/dtpcadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcadmin/#see-also","title":"SEE ALSO","text":"dtpcrc(5)
"},{"location":"man/dtpc/dtpcclock/","title":"NAME","text":"dtpcclock - DTPC daemon task for managing scheduled events
"},{"location":"man/dtpc/dtpcclock/#synopsis","title":"SYNOPSIS","text":"dtpcclock
"},{"location":"man/dtpc/dtpcclock/#description","title":"DESCRIPTION","text":"dtpcclock is a background \"daemon\" task that periodically performs scheduled DTPC activities. It is spawned automatically by dtpcadmin in response to the 's' command that starts operation of the DTPC protocol, and it is terminated by dtpcadmin in response to an 'x' (STOP) command.
Once per second, dtpcclock takes the following action:
First it executes all DTPC events scheduled to occur at any time up to the current moment:
DTPC ADUs for which an expected positive acknowledgment has not yet arrived are retransmitted.
Received DTPC ADUs whose time to live has elapsed are deleted.
Then dtpcclock increases the ages of all DTPC ADUs pending transmission and initiates transmission of each such ADU whose age now equals or exceeds its aggregation time limit.
"},{"location":"man/dtpc/dtpcclock/#exit-status","title":"EXIT STATUS","text":"0
dtpcclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use dtpcadmin to restart dtpcclock.
1
dtpcclock was unable to attach to DTPC protocol operations, probably because dtpcadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/dtpc/dtpcclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtpcclock can't initialize DTPC.
dtpcadmin has not yet initialized DTPC protocol operations.
Can't send finished adu.
An unrecoverable database error was encountered. dtpcclock terminates.
Can't stop aggregation for adu.
An unrecoverable database error was encountered. dtpcclock terminates.
Could not scan outbound Adus
An unrecoverable database error was encountered. dtpcclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcclock/#see-also","title":"SEE ALSO","text":"dtpcadmin(1)
"},{"location":"man/dtpc/dtpcd/","title":"NAME","text":"dtpcd - DTPC daemon task for receiving and processing DTPC ADUs in bundles
"},{"location":"man/dtpc/dtpcd/#synopsis","title":"SYNOPSIS","text":"dtpcd
"},{"location":"man/dtpc/dtpcd/#description","title":"DESCRIPTION","text":"dtpcd is a background \"daemon\" task that manages the reception and processing of DTPC protocol data units. It receives the payloads of bundles destined for the \"ipn\"-scheme endpoint whose node number is the number of the local node and whose service number is the DTPC_RECV_SVC_NBR (129 as of the time of this writeng).
DTPC protocol data units are of two types: application data units (ADUs, i.e., aggregations of application data items) and acknowledgments. Each acknowledgment is interpreted as authorization to release the buffer space occupied by the node's local copy of the acknowledged ADU. Each ADU is parsed into its constituent application data items, which are then delivered to the applications awaiting them, and when required a DTPC end-to-end acknowledgment PDU is returned to the DTPC PDU sender.
"},{"location":"man/dtpc/dtpcd/#exit-status","title":"EXIT STATUS","text":"0
dtpcd terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use dtpcadmin to restart dtpcd.
1
dtpcd terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use dtpcadmin to restart dtpcd.
No configuration files are needed.
"},{"location":"man/dtpc/dtpcd/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcd/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
DTPC can't open own 'send' endpoint.
Bundle protocol agent has not been started. See ion(3).
dtpcd can't attach to DTPC.
dtpcadmin has not yet initialized DTPC protocol operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcd/#see-also","title":"SEE ALSO","text":"dtpcadmin(1), ion(3)
"},{"location":"man/dtpc/dtpcrc/","title":"NAME","text":"dtpcrc - Delay-Tolerant Payload Conditioning management commands file
"},{"location":"man/dtpc/dtpcrc/#description","title":"DESCRIPTION","text":"DTPC management commands are passed to dtpcadmin either in a file of text lines or interactively at dtpcadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the DTPC management commands are described below.
"},{"location":"man/dtpc/dtpcrc/#commands","title":"COMMANDS","text":"?
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 dtpcadmin 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
The initialize command. Until this command is executed, DTPC is not in operation on the local ION node and most dtpcadmin commands will fail.
a profile profileID maxRtx aggrSizeLimit aggrTimeLimit TTL class_of_service report_to_endpointID [statusReportFlags]
The add profile command. This command notes the definition of a single DPTC transmission profile. A transmission profile asserts the BP and DTPC configuration parameter values that will be applied to all application data items (encapsulated in DTPC application data units and transmitted in bundles) that are issued subject to this profile. Transmission profiles are globally defined; all transmission profiles must be provided, with identical parameter values, to all inter-communicating DTPC protocol entities.
profileID must be the positive integer that uniquely defines the profile.
maxRtx is the maximum number of times any single DTPC ADU transmitted subject to the indicated profile may be retransmitted by the DTPC entity. If maxRtx is zero, then the DTPC transport service features (in-order delivery, end-to-end acknowledgment, etc.) are disabled for this profile.
aggrSizeLimit is the size threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrSizeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
aggrTimeLimit is the time threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrTimeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
class_of_service is the class-of-service string as defined for bptrace(1).
report_to_endpointID identifies the BP endpoint to which all status reports generated from bundles transmitted subject to this profile will be sent.
statusReportFlags, if present, must be a sequence of status report flags, separated by commas, with no embedded whitespace. Each status report flag must be one of the following: rcv, ct, fwd, dlv, del.
d profile profileId
The delete profile command. This command erases the definition of the DTPC transmission profile identified by profileId.
i profile profileId
This command will print information (all configuration parameters) about the profile identified by profileId.
l profile
This command lists all known DTPC transmission profiles.
s
The start command. This command starts the DTPC clock and daemon tasks for the local BP node.
x
The stop command. This command stops all DTPC tasks and notifies all DTPC applications that DTPC service has been stopped.
w { 0 | 1 | <activity_spec> }
The DTPC watch command. This command enables and disables production of a continuous stream of user-selected DTPC activity indication characters. A watch parameter of \"1\" selects all DTPC activity indication characters; \"0\" de-selects all DTPC activity indication characters; any other activity_spec such as \"o<r>\" selects all activity indication characters in the string, de-selecting all others. DTPC will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
o new aggregator created for profile and destination endpoint
\\< new ADU aggregation initiated
r application data item added to aggregation
\\> aggregation complete, outbound ADU created
- outbound ADU sent via BP
l ADU end-to-end acknowledgment sent
m ADU deleted due to TTL expiration
n ADU queued for retransmission
i inbound ADU collector created
u inbound ADU received
v ADU sequence gap detected
? inbound ADU discarded
* ADU sequence gap deleted due to impending ADU TTL expiration
$ inbound ADU collector reset
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a profile 5 6 1000000 5 3600 0.1 dtn:none
Notes the definition of DTPC transmission profile 5: transport services are enabled, with an end-to-end retransmission limit of 5; transmission optimization service is enabled, initiating bundle transmission whenever the aggregation of data items queued for transmission subject to this profile exceeds one million bytes or is more than five seconds old; the transmitted bundles will have one-hour lifetime, will not be subject to custody transfer, will be sent at \"standard\" priority, and will not be tracked by any bundle status report production.
dtpcadmin(1), bptrace(1)
"},{"location":"man/dtpc/dtpcreceive/","title":"NAME","text":"dtpcreceive - Delay-Tolerant Payload Conditioning reception test program
"},{"location":"man/dtpc/dtpcreceive/#synopsis","title":"SYNOPSIS","text":"dtpcreceive topic_ID
"},{"location":"man/dtpc/dtpcreceive/#description","title":"DESCRIPTION","text":"dtpcreceive uses DTPC to acquire application data items on topic topic_ID sent by dtpcsend. Upon termination it prints the total number of application data items received and the mean rate of application data transmission.
Use CTRL-C to terminate the program.
"},{"location":"man/dtpc/dtpcreceive/#exit-status","title":"EXIT STATUS","text":"0
dtpcreceive has terminated.
No configuration files are needed.
"},{"location":"man/dtpc/dtpcreceive/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcreceive/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcreceive/#see-also","title":"SEE ALSO","text":"dtpcsend(1), dtpc(3)
"},{"location":"man/dtpc/dtpcsend/","title":"NAME","text":"dtpcsend - Delay-Tolerant Payload Conditioning transmission test program
"},{"location":"man/dtpc/dtpcsend/#synopsis","title":"SYNOPSIS","text":"dtpcsend nbr_of_cycles rate payload_size topic_ID profile_ID destination_endpoint
"},{"location":"man/dtpc/dtpcsend/#description","title":"DESCRIPTION","text":"dtpcsend uses DTPC to send nbr_of_cycles application data items of payload_size bytes each on topic topic_ID to destination_endpoint using transmission profile profile_ID at rate bits per second.
rate must be between 1000 and 200 million bits per second.
payload_size must be between 2 and 1 million bytes. To use application data item sizes chosen at random from the range 1 to 65536, specify payload_size = 1.
NOTE that dtpcsend invokes an elision function that removes from the outbound DTPC aggregate ADU all records that are of the same size as the first record in that aggregation. This means that specifying any payload size other than 1 that is less than the configured DTPC aggregation size limit will cause DTPC to issue ADUs only when the aggregation time limit is exceeded, and each such ADU will always contain only a single record.
Use CTRL-C to terminate the program.
"},{"location":"man/dtpc/dtpcsend/#files","title":"FILES","text":"No configuration files are needed.
"},{"location":"man/dtpc/dtpcsend/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcsend/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcsend/#see-also","title":"SEE ALSO","text":"dtpcreceive(1), dtpc(3)
"},{"location":"man/ici/","title":"Index of Man Pages","text":"file2sdr - SDR data ingestion test program
"},{"location":"man/ici/file2sdr/#synopsis","title":"SYNOPSIS","text":"file2sdr configFlags fileName
"},{"location":"man/ici/file2sdr/#description","title":"DESCRIPTION","text":"file2sdr stress-tests SDR data ingestion by repeatedly writing all text lines of the file named fileName to one of a series of non-volatile linked lists created in a test SDR data store named \"testsdr_configFlags_\". By incorporating the data store configuration into the name (e.g., \"testsdr14\") we make it relatively easy to perform comparative testing on SDR data stores that are identical aside from their configuration settings.
The operation of file2sdr is cyclical: a new linked list is created each time the program finishes copying the file's text lines and starts over again. If you use ^C to terminate file2sdr and then restart it, the program resumes operation at the point where it left off.
After writing each line to the current linked list, file2sdr gives a semaphore to indicate that the list is now non-empty. This is mainly for the benefit of the complementary test program sdr2file(1).
At the end of each cycle file2sdr appends a final EOF line to the current linked list, containing the text \"*** End of the file ***\", and prints a brief performance report:
Processing I<lineCount> lines per second.\n\"0\"
file2sdr has terminated.
No configuration files are needed.
"},{"location":"man/ici/file2sdr/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/file2sdr/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by file2sdr are written to the ION log file ion.log.
Can't use sdr.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create semaphore.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
SDR transaction failed.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't open input file
Operating system error. Check errtext, correct problem, and rerun.
Can't reopen input file
Operating system error. Check errtext, correct problem, and rerun.
Can't read from input file
Operating system error. Check errtext, correct problem, and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/file2sdr/#see-also","title":"SEE ALSO","text":"sdr2file(1), sdr(3)
"},{"location":"man/ici/file2sm/","title":"NAME","text":"file2sm - shared-memory linked list data ingestion test program
"},{"location":"man/ici/file2sm/#synopsis","title":"SYNOPSIS","text":"file2sm fileName
"},{"location":"man/ici/file2sm/#description","title":"DESCRIPTION","text":"file2sm stress-tests shared-memory linked list data ingestion by repeatedly writing all text lines of the file named fileName to a shared-memory linked list that is the root object of a PSM partition named \"file2sm\".
After writing each line to the linked list, file2sm gives a semaphore to indicate that the list is now non-empty. This is mainly for the benefit of the complementary test program sm2file(1).
The operation of file2sm is cyclical. After copying all text lines of the source file to the linked list, file2sm appends an EOF line to the linked list, containing the text \"*** End of the file ***\", and prints a brief performance report:
Processing I<lineCount> lines per second.\nThen it reopens the source file and starts appending the file's text lines to the linked list again.
"},{"location":"man/ici/file2sm/#exit-status","title":"EXIT STATUS","text":"\"0\"
file2sm has terminated.
No configuration files are needed.
"},{"location":"man/ici/file2sm/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/file2sm/#diagnostics","title":"DIAGNOSTICS","text":"Can't attach to shared memory
Operating system error. Check errtext, correct problem, and rerun.
Can't manage shared memory.
PSM error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create shared memory list.
smlist error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create semaphore.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't open input file
Operating system error. Check errtext, correct problem, and rerun.
Can't reopen input file
Operating system error. Check errtext, correct problem, and rerun.
Can't read from input file
Operating system error. Check errtext, correct problem, and rerun.
Ran out of memory.
Nominal behavior. sm2file is not extracting data from the linked list quickly enough to prevent it from growing to consume all memory allocated to the test partition.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/file2sm/#see-also","title":"SEE ALSO","text":"sm2file(1), smlist(3), psm(3)
"},{"location":"man/ici/ion/","title":"NAME","text":"ion - Interplanetary Overlay Network common definitions and functions
"},{"location":"man/ici/ion/#synopsis","title":"SYNOPSIS","text":"#include \"ion.h\"\n\n[see description for available functions]\nThe Interplanetary Overlay Network (ION) software distribution is an implementation of Delay-Tolerant Networking (DTN) architecture as described in Internet RFC 4838. It is designed to enable inexpensive insertion of DTN functionality into embedded systems such as robotic spacecraft. The intent of ION deployment in space flight mission systems is to reduce cost and risk in mission communications by simplifying the construction and operation of automated digital data communication networks spanning space links, planetary surface links, and terrestrial links.
The ION distribution comprises the following software packages:
ici (Interplanetary Communication Infrastructure), a set of general-purpose libraries providing common functionality to the other packages.
ltp (Licklider Transmission Protocol), a core DTN protocol that provides transmission reliability based on delay-tolerant acknowledgments, timeouts, and retransmissions.
dgr (Datagram Retransmission), a library that enables data to be transmitted via UDP with reliability comparable to that provided by TCP. DGR is an alternative implementation of LTP, designed for use within an internet.
bssp (Bundle Streaming Service Protocol), a protocol that supports delay-tolerant data streaming. BSSP delivers data in transmission order with minimum latency but possibly with omissions, for immediate display, and at the same time it delivers the same data reliably in background so that the streamed data can be \"rewound\" for possibly improved presentation.
bp (Bundle Protocol), a core DTN protocol that provides delay-tolerant forwarding of data through a network in which continuous end-to-end connectivity is never assured, including support for delay-tolerant dynamic routing. The Bundle Protocol (BP) specification is defined in Internet RFC 5050.
ams (Asynchronous Message Service), cfdp (CCSDS File Delivery Protocol), dtpc (Delay-Tolerant Payload Conditioning), and bss (Bundle Streaming Service), application-layer services that are not part of the DTN architecture but utilize underlying DTN protocols.
Taken together, the packages included in the ION software distribution constitute a communication capability characterized by the following operational features:
Reliable conveyance of data over a DTN, i.e., a network in which it might never be possible for any node to have reliable information about the detailed current state of any other node.
Built on this capability, reliable distribution of short messages to multiple recipients (subscribers) residing in such a network.
Management of traffic through such a network.
Facilities for monitoring the performance of the network.
Robustness against node failure.
Portability across heterogeneous computing platforms.
High speed with low overhead.
Easy integration with heterogeneous underlying communication infrastructure, ranging from Internet to dedicated spacecraft communication links.
While most of the ici package consists of libraries providing functionality that may be of general utility in any complex embedded software system, the functions and macros described below are specifically designed to support operations of ION's delay-tolerant networking protocol stack.
TIMESTAMPBUFSZ
This macro returns the recommended size of a buffer that is intended to contain a timestamp in ION-standard format:
yyyy/mm/dd-hh:mm:ss\nint ionAttach()
Attaches the invoking task to ION infrastructure as previously established by running the ionadmin utility program. Returns zero on success, -1 on any error.
void ionDetach()
Detaches the invoking task from ION infrastructure. In particular, releases handle allocated for access to ION's non-volatile database. NOTE, though, that ionDetach() has no effect when the invoking task is running in a non-memory-protected environment, such as VxWorks, where all ION resource access variables are shared by all tasks: no single task could detach without crashing all other ION tasks.
void ionProd(uvast fromNode, uvast toNode, unsigned int xmitRate, unsigned int owlt)
This function is designed to be called from an operating environment command or a fault protection routine, to enable operation of a node to resume when all of its scheduled contacts are in the past (making it impossible to use a DTN communication contact to assert additional future communication contacts). The function asserts a single new unidirectional contact conforming to the arguments provided, including the applicable one-way light time, with start time equal to the current time (at the moment of execution of the function) and end time equal to the start time plus 2 hours. The result of executing the function is written to the ION log using standard ION status message logging functions.
NOTE that the ionProd() function must be invoked twice in order to establish bidirectional communication.
void ionTerminate()
Shuts down the entire ION node, terminating all daemons. The state of the node is retained in the node's SDR heap.
int ionStartAttendant(ReqAttendant *attendant)
Initializes the semaphore in attendant so that it can be used for blocking ZCO space requisitions by ionRequestZcoSpace(). Returns 0 on success, -1 on any error.
void ionPauseAttendant(ReqAttendant *attendant)
\"Ends\" the semaphore in attendant so that the task that is blocked on taking it is interrupted and may respond to an error or shutdown condition.
void ionResumeAttendant(ReqAttendant *attendant)
Reinitializes the semaphore in attendant so that it can again be used for blocking ZCO space requisitions.
void ionStopAttendant(ReqAttendant *attendant)
Destroys the semaphore in attendant, preventing a potential resource leak.
int ionRequestZcoSpace(ZcoAcct acct, vast fileSpaceNeeded, vast bulkSpaceNeeded, vast heapSpaceNeeded, unsigned char coarsePriority, unsigned char finePriority, ReqAttendant *attendant, ReqTicket *ticket)
Lodges a request for ZCO space in the pool identified by acct. If the requested space can be provided immediately, it is reserved for use by the calling task. Otherwise, if attendant is non-NULL then the request is queued for service when space becomes available. In any case, *ticket is set to the address of a \"ticket\" referencing this request. The status of the request can be interrogated by calling ionSpaceAwarded(). If this function returns 1 (True) then ZCO space may be consumed immediately and the ticket must then be destroyed by a call to ionShred(). Otherwise, if an attendant was provided, then the calling task should pend on the semaphore in attendant and upon successfully taking the semaphore it must consume the requested ZCO space and then ionShred() the ticket. Otherwise the request for ZCO space has been definitively denied and, as always, the ticket must by destroyed by an invocation of ionShred(). Returns 0 on success, -1 on any failure.
int ionSpaceAwarded(ReqTicket *ticket)
Returns 1 if ticket is for a ZCO space request that has been serviced (ZCO space has been reserved per this request), 0 otherwise.
void ionShred(ReqTicket *ticket)
Dismisses the reservation of ZCO space (if any) requested by the call to ionRequestZcoSpace() that returned ticket. Calling ionShred() indicates either that the requested space was reserved (i.e., the request was \"serviced\") and has been claimed (consumed by the appending of a ZCO extent) or that the request has been canceled. Note that failure to promptly (within 3 seconds of reception) ionShred() the ticket for a service request will be interpreted as refusal of the reserved ZCO space, resulting in that space being made available for use by other tasks.
Object ionCreateZco(ZcoMedium source, Object location, vast offset, vast length, unsigned char coarsePriority, unsigned char finePriority, ZcoAcct acct, ReqAttendant *attendant)
This function provides a \"blocking\" implementation of admission control in ION. Like zco_create(), it constructs a zero-copy object (see zco(3)) that contains a single extent of source data residing at location in source, of which the first offset bytes are omitted and the next length bytes are included. But unlike zco_create(), ionCreateZco() can be configured to block (rather than return an immediate error indication) so long as the total amount of space in source that is available for new ZCO formation is less than length. ionCreateZco() operates by calling ionRequestZcoSpace(), then pending on the semaphore in attendant as necessary before creating the ZCO. ionCreateZco() returns when either (a) space has become available and the ZCO has been created, in which case the location of the ZCO is returned, or (b) the function has failed (in which case ((Object) -1) is returned), or (c) either attendant was null and sufficient space for the first extent of the ZCO was not immediately available or else the function was interrupted by ionPauseAttendant() before space for the ZCO became available (in which case 0 is returned).
vast ionAppendZcoExtent(Object zco, ZcoMedium source, Object location, vast offset, vast length, unsigned char coarsePriority, unsigned char finePriority, ReqAttendant *attendant)
Similar to ionCreateZco() except that instead of creating a new ZCO it appends an additional extent to an existing ZCO. Returns -1 on failure, 0 on interruption by ionPauseAttendant() or if attendant was NULL and sufficient space for the extent was not immediately available, length on success.
char *getIonVersionNbr()
Returns the name of the ION version installed on the local machine.
Sdr getIonsdr()
Returns a pointer to the SDR management object, previously acquired by calling ionAttach(), or zero on any error.
PsmPartition getIonwm()
Returns a pointer to the ION working memory partition, previously acquired by calling ionAttach(), or zero on any error.
int getIonMemoryMgr()
Returns the memory manager ID for operations on ION's working memory partition, previously acquired by calling ionAttach(), or -1 on any error.
int ionLocked();
Returns 1 if the calling task is the owner of the current SDR transaction. Assuring that ION is locked while related critical operations are performed is essential to the avoidance of race conditions.
uvast getOwnNodeNbr()
Returns the Bundle Protocol node number identifying this node, as declared when ION was initialized by ionadmin.
time_t getCtime()
Returns the current calendar (i.e., Unix epoch) time, as computed from local clock time and the computer's current offset from UTC (due to clock drift, not due to time zone difference; the utcdelta) as managed from ionadmin.
int ionClockIsSynchronized()
Returns 1 if the computer on which the local ION node is running has a synchronized clock , i.e., a clock that reports the current calendar (i.e., Unix epoch) time as a value that differs from the correct calendar time by an interval approximately equal to the currently asserted offset from UTC due to clock drift; returns zero otherwise.
If the machine's clock is synchronized then its reported values (as returned by getCtime()) can safely be used as the creation times of new bundles and the expiration time of such a bundle can accurately be computed as the sum of the bundle's creation time and time to live. If not, then the creation timestamp time of new bundles sourced at the local ION node must be zero and the creation timestamp sequence numbers must increase monotonically forever, never rolling over to zero.
void writeTimestampLocal(time_t timestamp, char *timestampBuffer)
Expresses the time value in timestamp as a local timestamp string in ION-standard format, as noted above, in timestampBuffer.
void writeTimestampUTC(time_t timestamp, char *timestampBuffer)
Expresses the time value in timestamp as a UTC timestamp string in ION-standard format, as noted above, in timestampBuffer.
time_t readTimestampLocal(char *timestampBuffer, time_t referenceTime)
Parses the local timestamp string in timestampBuffer and returns the corresponding calendar (i.e., Unix epoch) time value (as would be returned by time(2)), or zero if the timestamp string cannot be parsed successfully. The timestamp string is normally expected to be an absolute expression of local time in ION-standard format as noted above. However, a relative time expression variant is also supported: if the first character of timestampBuffer is '+' then the remainder of the string is interpreted as a count of seconds; the sum of this value and the time value in referenceTime is returned.
time_t readTimestampUTC(char *timestampBuffer, time_t referenceTime)
Same as readTimestampLocal() except that if timestampBuffer is not a relative time expression then it is interpreted as an absolute expression of UTC time in ION-standard format as noted above.
ION uses writeMemo(), putErrmsg(), and putSysErrmsg() to log several different types of standardized status messages.
Informational messages
These messages are generated to inform the user of the occurrence of events that are nominal but significant, such as the controlled termination of a daemon or the production of a congestion forecast. Each informational message has the following format:
{_yyyy/mm/dd hh:mm:ss_} \\[i\\] _text_\nWarning messages
These messages are generated to inform the user of the occurrence of events that are off-nominal but are likely caused by configuration or operational errors rather than software failure. Each warning message has the following format:
{_yyyy/mm/dd hh:mm:ss_} \\[?\\] _text_\nDiagnostic messages
These messages are produced by calling putErrmsg() or putSysErrmsg(). They are generated to inform the user of the occurrence of events that are off-nominal and might be due to errors in software. The location within the ION software at which the off-nominal condition was detected is indicated in the message:
{_yyyy/mm/dd hh:mm:ss_} at line _nnn_ of _sourcefilename_, _text_ (_argument_)\nNote that the argument portion of the message (including its enclosing parentheses) will be provided only when an argument value seems potentially helpful in fault analysis.
Bundle Status Report (BSR) messages
A BSR message informs the user of the arrival of a BSR, a Bundle Protocol report on the status of some bundle. BSRs are issued in the course of processing bundles for which one or more status report request flags are set, and they are also issued when bundles for which custody transfer is requested are destroyed prior to delivery to their destination endpoints. A BSR message is generated by ipnadminep upon reception of a BSR. The time and place (node) at which the BSR was issued are indicated in the message:
{_yyyy/mm/dd hh:mm:ss_} \\[s\\] (_sourceEID_)/_creationTimeSeconds_:_counter_/_fragmentOffset_ status _flagsByte_ at _time_ on _endpointID_, '_reasonString_'.\nCommunication statistics messages
A network performance report is a set of eight communication statistics messages, one for each of eight different types of network activity. A report is issued every time contact transmission or reception starts or stops, except when there is no activity of any kind on the local node since the prior report. When a report is issued, statistic messages are generated to summarize all network activity detected since the prior report, after which all network activity counters and accumulators are reset to zero.
NOTE also that the bpstats utility program can be invoked to issue an interim network performance report at any time. Issuance of interim status reports does not cause network activity counters and accumulators to be reset to zero.
Statistics messages have the following format:
{_yyyy/mm/dd hh:mm:ss_} \\[x\\] _xxx_ from _tttttttt_ to _TTTTTTTT_: (0) _aaaa_ _bbbbbbbbbb_ (1) _cccc_ _dddddddddd_ (2) _eeee_ _ffffffffff_ (+) _gggg_ _hhhhhhhhhh_\nxxx indicates the type of network activity that the message is reporting on. Statistics for eight different types of network activity are reported:
src
This message reports on the bundles sourced at the local node during the indicated interval.
fwd
This message is about routing; it reports on the number of bundles queued for forwarding to neighboring nodes as selected by the routing procedure. When a bundle must be re-forwarded due to convergence-layer transmission failure it is counted a second time here.
xmt
This message reports on the bundles passed to the convergence layer protocol(s) for transmission from this node. Again, a re-forwarded bundle that is then re-transmitted at the convergence layer is counted a second time here.
rcv
This message reports on the bundles from other nodes that were received at the local node.
dlv
This message reports on the bundles delivered to applications via endpoints on the local node.
ctr
This message reports on the custody refusal signals received at the local node.
rfw
This message reports on bundles for which convergence-layer transmission failed at this node, causing the bundles to be re-forwarded.
exp
This message reports on the bundles destroyed at this node due to TTL expiration.
tttttttt and TTTTTTTT indicate the start and end times of the interval for which statistics are being reported, expressed in yyyy/mm/dd-hh:mm:ss format. TTTTTTTT is the current time and tttttttt is the time of the prior report.
Each of the four value pairs following the colon (:) reports on the number of bundles counted for the indicated type of network activity, for the indicated traffic flow, followed by the sum of the sizes of the payloads of all those bundles. The four traffic flows for which statistics are reported are \"(0)\" the priority-0 or \"bulk\" traffic, \"(1)\" the priority-1 \"standard\" traffic, \"(2)\" the priority-2 \"expedited\" traffic, and \"(+)\" the total for all classes of service.
Free-form messages
Other status messages are free-form, except that date and time are always noted just as for the documented status message types.
ionadmin(1), rfxclock(1), bpstats(1), llcv(3), lyst(3), memmgr(3), platform(3), psm(3), sdr(3), zco(3), ltp(3), bp(3), cfdp(3), ams(3), bss(3)
"},{"location":"man/ici/ionadmin/","title":"NAME","text":"ionadmin - ION node administration interface
"},{"location":"man/ici/ionadmin/#synopsis","title":"SYNOPSIS","text":"ionadmin [ commands_filename | . | ! ]
"},{"location":"man/ici/ionadmin/#description","title":"DESCRIPTION","text":"ionadmin configures, starts, manages, and stops the ION node on the local computer.
It configures the node and sets (and reports on) global operational settings for the DTN protocol stack on the local computer in response to ION configuration commands found in commands_filename, if provided; if not, ionadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to ionadmin -- that is, the ION node's rfxclock task is stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's rfxclock task is restarted.
The format of commands for commands_filename can be queried from ionadmin by entering the command 'h' or '?' at the prompt. The commands are documented in ionrc(5).
Note that ionadmin always computes a congestion forecast immediately before exiting. The result of this forecast -- maximum projected occupancy of the DTN protocol traffic allocation in ION's SDR database -- is retained for application flow control purposes: if maximum projected occupancy is the entire protocol traffic allocation, then a message to this effect is logged and no new bundle origination by any application will be accepted until a subsequent forecast that predicts no congestion is computed. (Congestion forecasts are constrained by horizon times, which can be established by commands issued to ionadmin. One way to re-enable data origination temporarily while long-term traffic imbalances are being addressed is to declare a congestion forecast horizon in the near future, before congestion would occur if no adjustments were made.)
"},{"location":"man/ici/ionadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of ION node administration.
ionadmin
Enter interactive ION configuration command entry mode.
ionadmin host1.ion
Execute all configuration commands in host1.ion, then terminate immediately.
Status and diagnostic messages from ionadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which ionadmin was run. The log file is typically named ion.log.
See also ionconfig(5) and ionrc(5).
"},{"location":"man/ici/ionadmin/#environment","title":"ENVIRONMENT","text":"Environment variables ION_NODE_LIST_DIR and ION_NODE_WDNAME can be used to enable the operation of multiple ION nodes on a single workstation computer. See section 2.1.3 of the ION Design and Operations Guide for details.
"},{"location":"man/ici/ionadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ionadmin. Otherwise ionadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
ionadmin SDR definition failed.
A node initialization command was executed, but an SDR database already exists for the indicated node. It is likely that an ION node is already running on this computer or that destruction of a previously started the previous ION node was incomplete. For most ION installations, incomplete node destruction can be repaired by (a) killing all ION processes that are still running and then (b) using ipcrm to remove all SVr4 IPC objects owned by ION.
ionadmin can't get SDR parms.
A node initialization command was executed, but the ion_config_filename passed to that command contains improperly formatted commands. Please see ionconfig(5) for further details.
Various errors that don't cause ionadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see ionrc(5) for details.
"},{"location":"man/ici/ionadmin/#bugs","title":"BUGS","text":"If the ion_config_filename parameter passed to a node initialization command refers to a nonexistent filename, then ionadmin uses default values are used rather than reporting an error in the command line argument.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionadmin/#see-also","title":"SEE ALSO","text":"ionrc(5), ionconfig(5)
"},{"location":"man/ici/ioncbor/","title":"NAME","text":"cbor - ION library for encoding and decoding CBOR data representations
"},{"location":"man/ici/ioncbor/#synopsis","title":"SYNOPSIS","text":"#include \"cbor.h\"\nION's \"cbor\" library implements a subset of the Concise Binary Object Representation (CBOR) standard, RFC 7049; only those data types used in ION code are implemented. Unlike other CBOR implementations, ION CBOR is specifically intended for compatibility with zero-copy objects, i.e., the data being decoded need not all be in a memory buffer.
For all functions, *cursor is a pointer to the location in the CBOR coding buffer at which bytes are to be encoded or decoded. This pointer is automatically advanced as the encoding or decoding operation is performed.
Most of the ION CBOR decoding functions entail the decoding of unsigned integers. The invoking code may require that an integer representation have a specific size by indicating the integer size \"class\" that is required. Class -1 indicates that an integer of any size is acceptable; the other classes (0, 1, 2, 4, 8) indicate the number of bytes of integer data that MUST follow the integers initial byte.
int cbor_encode_integer(uvast value, unsigned char **cursor)
Represent this value in an integer of the smallest possible integer class. Cursor is automatically advanced. Returns number of bytes written.
int cbor_encode_fixed_int(uvast value, int class, unsigned char **cursor)
Represent this value in an integer of the indicated class. Cursor is automatically advanced. Returns number of bytes written, 0 on encoding error.
int cbor_encode_byte_string(unsigned char *value, uvast size, unsigned char **cursor)
size is the number of bytes to write. If value is NULL, only the size of the byte string is written; otherwise the byte string itself is written as well. Cursor is advanced by the number of bytes written in either case. Returns number of bytes written.
int cbor_encode_text_string(char *value, uvast size, unsigned char **cursor)
size is the number of bytes to write. If value is NULL, only the size of the text string is written; otherwise the text string itself is written as well. Cursor is advanced by the number of bytes written in either case. Returns number of bytes written.
int cbor_encode_array_open(uvast size, unsigned char **cursor)
If size is ((uvast) -1), the array is of indefinite size; otherwise size indicates the number of items in the array. Cursor is automatically advanced. Returns number of bytes written.
int cbor_encode_break(unsigned char **cursor)
Break code is written at the indicated location. Cursor is automatically advanced. Returns number of bytes written (always 1).
int cbor_decode_initial_byte(unsigned char **cursor, unsigned int *bytesBuffered, int *majorType, int *additionalInfo)
This function just extracts major type and additional info from the byte identified by cursor. Cursor is automatically advanced. Returns number of bytes decoded (always 1) or 0 on decoding error (e.g., no byte to decode).
int cbor_decode_integer( uvast *value, int class, unsigned char **cursor, unsigned int *bytesBuffered)
If class is CborAny, any class of data item is accepted; otherwise only an integer data item of the indicated class is accepted. Cursor is automatically advanced. Returns number of bytes read, 0 on decoding error (e.g., integer is of the wrong class).
int cbor_decode_byte_string(unsigned char *value, uvast *size, unsigned char **cursor, unsigned int *bytesBuffered)
Initial value of size is the maximum allowable size of the decoded byte string; the actual number of bytes in the byte string (which, NOTE, is less than the number of bytes read) is returned in size. If value is non-NULL, the decoded byte string is copied into value and cursor is automatically advanced to the end of the byte string; otherwise, cursor is advanced only to the beginning of the byte string. Returns number of bytes read, 0 on decoding error (e.g., byte string exceeds maximum size).
int cbor_decode_text_string(char *value, uvast *size, unsigned char **cursor, unsigned int *bytesBuffered)
Initial value of size is the maximum allowable size of the decoded text string; the actual number of bytes in the text string (which, NOTE, is less than the number of bytes read) is returned in size. If value is non-NULL, the decoded text string is copied into value and cursor is automatically advanced to the end of the text string; otherwise, cursor is advanced only to the beginning of the text string. Returns number of bytes read, 0 on decoding error (e.g., text string exceeds maximum size).
int cbor_decode_array_open(uvast *size, unsigned char **cursor, unsigned int *bytesBuffered)
If size is zero, any array is accepted and the actual size of the decoded array is returned in size; ((uvast) -1) is returned in size if the array is of indefinite size. If size is ((uvast) -1), only an array of indefinite length is accepted. Otherwise, size indicates the required number of items in the array. Cursor is automatically advanced. Returns number of bytes read, 0 on decoding error (such as wrong number of items).
int cbor_decode_break(unsigned char **cursor, unsigned int *bytesBuffered)
Break code is read from the indicated location. Cursor is automatically advanced. Returns number of bytes read, 0 on decoding error (e.g., no break character at this location).
ionconfig - ION node configuration parameters file
"},{"location":"man/ici/ionconfig/#description","title":"DESCRIPTION","text":"ION node configuration parameters are passed to ionadmin in a file of parameter name/value pairs:
parameter_name parameter_value
Any line of the file that begins with a '#' character is considered a comment and is ignored.
ionadmin supplies default values for any parameters for which no value is provided in the node configuration parameters file.
The applicable parameters are as follows:
sdrName
This is the character string by which this ION node's SDR database will be identified. (Note that the SDR database infrastructure enables multiple databases to be constructed on a single host computer.) The default value is \"ion\".
sdrWmSize
This is the size of the block of dynamic memory that will be reserved as private working memory for the SDR system itself. A block of system memory of this size will be allocated (e.g., by malloc()) at the time the SDR system is initialized on the host computer. The default value is 1000000 (1 million bytes).
configFlags
This is the bitwise \"OR\" (i.e., the sum) of the flag values that characterize the SDR database to use for this ION node. The default value is 13 (that is, SDR_IN_DRAM | SDR_REVERSIBLE | SDR_BOUNDED). The SDR configuration flags are documented in detail in sdr(3). To recap:
SDR_IN_DRAM (1)
The SDR is implemented in a region of shared memory. [Possibly with write-through to a file, for fault tolerance.]
SDR_IN_FILE (2)
The SDR is implemented as a file. [Possibly cached in a region of shared memory, for faster data retrieval.]
SDR_REVERSIBLE (4)
Transactions in the SDR are written ahead to a log, making them reversible.
SDR_BOUNDED (8)
SDR heap updates are not allowed to cross object boundaries.
heapKey
This is the shared-memory key by which the pre-allocated block of shared dynamic memory to be used as heap space for this SDR can be located, if applicable. The default value is -1, i.e., not specified and not applicable.
pathName
This is the fully qualified path name of the directory in which are located (a) the file to be used as heap space for this SDR (which will be created, if it doesn't already exist), in the event that the SDR is to be implemented in a file, and (b) the file to be used to log the database updates of each SDR transaction, in the event that transactions in this SDR are to be reversible. The default value is /tmp.
heapWords
This is the number of words (of 32 bits each on a 32-bit machine, 64 bits each on a 64-bit machine) of nominally non-volatile storage to use for ION's SDR database. If the SDR is to be implemented in shared memory and no heapKey is specified, a block of shared memory of this size will be allocated (e.g., by malloc()) at the time the node is created. If the SDR is to be implemented in a file and no file named ion.sdr exists in the directory identified by pathName, then a file of this name and size will be created in this directory and initialized to all binary zeroes. The default value is 250000 words (1 million bytes on a 32-bit computer).
logSize
This is the number of bytes of shared memory to use for ION's SDR transaction log. If zero (the default), the transaction log is written to a file rather than to memory. If the log is to be implemented in shared memory and no logKey is specified, a block of shared memory of this size will be allocated (e.g., by malloc()) at the time the node is created.
logKey
This is the shared-memory key by which the pre-allocated block of shared dynamic memory to be used for the transaction log for this SDR can be located, if applicable. The default value is -1, i.e., not specified and not applicable.
wmKey
This is the shared-memory key by which this ION node's working memory will be identified. The default value is 65281.
wmAddress
This is the address of the block of dynamic memory -- volatile storage, which is not expected to persist across a system reboot -- to use for this ION node's working memory. If zero, the working memory block will be allocated from system memory (e.g., by malloc()) at the time the local ION node is created. The default value is zero.
wmSize
This is the size of the block of dynamic memory that will be used for this ION node's working memory. If wmAddress is zero, a block of system memory of this size will be allocated (e.g., by malloc()) at the time the node is created. The default value is 5000000 (5 million bytes).
configFlags 1
heapWords 2500000
heapKey -1
pathName /usr/ion
wmSize 5000000
wmAddress 0
"},{"location":"man/ici/ionconfig/#see-also","title":"SEE ALSO","text":"ionadmin(1)
"},{"location":"man/ici/ioncrc/","title":"NAME","text":"crc - ION library for computing several types of checksums.
"},{"location":"man/ici/ioncrc/#synopsis","title":"SYNOPSIS","text":"#include \"crc.h\"\nION's \"crc\" library implements functions for computing four types of checksums: X.25 (16-bit), bzip2 (32-bit), CRC32 (32-bit), and CRC32C (32-bit).
All checksum computation functions were provided by Antara Teknik, LLC.
uint16_t ion_CRC16_1021_X25(const char *data, uint32_t dLen, uint16_t crc)
Computes the CRC16 value for poly 0x1021. data points to the data block over which the checksum value is to be computed, len must be the length of that data block, and crc is the current value of the checksum that is being incrementally computed over a multi-block extent of data (zero for the first block of this extent, or if this block is the entire extent).
uint32_t ion_CRC32_04C11DB7_bzip2(const char *data, uint32_t dLen, uint32_t crc)
Computes the bzip2 CRC32 checksum value for poly 0x04c11db7. data points to the data block over which the checksum value is to be computed, len must be the length of that data block, and crc is the current value of the checksum that is being incrementally computed over a multi-block extent of data (zero for the first block of this extent, or if this block is the entire extent).
uint32_t ion_CRC32_04C11DB7(const char *data, uint32_t dLen, uint32_t crc)
Computes the ISO-HDLC CRC32 value for poly 0x04c11db7. data points to the data block over which the checksum value is to be computed, len must be the length of that data block, and crc is the current value of the checksum that is being incrementally computed over a multi-block extent of data (zero for the first block of this extent, or if this block is the entire extent).
uint32_t ion_CRC32_1EDC6F41_C(const char *data, uint32_t dLen, uint32_t crc)
Computes the CRC32C value for poly 0x1edc6f41. data points to the data block over which the checksum value is to be computed, len must be the length of that data block, and crc is the current value of the checksum that is being incrementally computed over a multi-block extent of data (zero for the first block of this extent, or if this block is the entire extent).
ionlog - utility for redirecting stdin to the ION log file
"},{"location":"man/ici/ionlog/#synopsis","title":"SYNOPSIS","text":"ionlog
"},{"location":"man/ici/ionlog/#description","title":"DESCRIPTION","text":"The ionlog program simply reads lines of text from stdin and uses writeMemo to copy them into the ion.log file. It terminates when it reaches EOF in stdin.
"},{"location":"man/ici/ionlog/#exit-status","title":"EXIT STATUS","text":"\"0\"
ionlog has terminated successfully.
No configuration files are needed.
"},{"location":"man/ici/ionlog/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/ionlog/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ionlog unable to attach to ION.
Probable operations error: ION appears not to be initialized, in which case there is no point in running ionlog.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionlog/#see-also","title":"SEE ALSO","text":"amslogprt(1)
"},{"location":"man/ici/ionrc/","title":"NAME","text":"ionrc - ION node management commands file
"},{"location":"man/ici/ionrc/#description","title":"DESCRIPTION","text":"ION node management commands are passed to ionadmin either in a file of text lines or interactively at ionadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the ION node management commands are described below.
"},{"location":"man/ici/ionrc/#time-representation","title":"TIME REPRESENTATION","text":"For many ION node management commands, time values must be passed as arguments. Every time value may be represented in either of two formats. Absolute time is expressed as:
yyyy/mm/dd-hh:mm:ss
Relative time (a number of seconds following the current reference time, which defaults to the current time at the moment ionadmin began execution but which can be overridden by the at command described below) is expressed as:
+ss
"},{"location":"man/ici/ionrc/#commands","title":"COMMANDS","text":"?
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 ionadmin 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 node_number [ { ion_config_filename | '.' | '' } ]
The initialize command. Until this command is executed, the local ION node does not exist and most ionadmin commands will fail.
The command configures the local node to be identified by node_number, a CBHE node number which uniquely identifies the node in the delay-tolerant network. It also configures ION's data space (SDR) and shared working-memory region. For this purpose it uses a set of default settings if no argument follows node_number or if the argument following node_number is ''; otherwise it uses the configuration settings found in a configuration file. If configuration file name '.' is provided, then the configuration file's name is implicitly \"hostname.ionconfig\"; otherwise, ion_config_filename is taken to be the explicit configuration file name. Please see ionconfig(5) for details of the configuration settings.
For example:
1 19 ''\nwould initialize ION on the local computer, assigning the local ION node the node number 19 and using default values to configure the data space and shared working-memory region.
@ time
The at command. This is used to set the reference time that will be used for interpreting relative time values from now until the next revision of reference time. Note that the new reference time can be a relative time, i.e., an offset beyond the current reference time.
^ region_number
The region command. This is used to select the region to which all ensuing \"contact\" operations (until this execution of ionadmin terminates, or until the next region command is processed) pertain. A region is an arbitarily managed set of nodes that customarily are able to use contact graph routing to compute forwarding routes among themselves, and which consequently share a common contact plan. As such, there is a one-to-one correspondence between regions and contact plans, so in effect the region command is used to switch between contact plans. Regions are notionally quite small sets (on the order of 16-32 nodes) because contact graph routing is computationally intensive.
Information regarding up to two (2) regions may be managed at any single node.
By default, region number 1 (the \"universal\" region) is selected.
! [0 | 1]
\"Announce\" control. Setting the announce flag to 1 causes contact plan updates (contact add/change/delete, range add/delete) to be multicast to all other nodes in the region in addition to being processed at the local node. Setting the announce flag to 0 disables this behavior.
a contact start_time stop_time source_node dest_node xmit_data_rate [confidence]
The add contact command. This command schedules a period of data transmission from source_node to dest_node. The period of transmission will begin at start_time and end at stop_time, and the rate of data transmission will be xmit_data_rate bytes/second. Our confidence in the contact defaults to 1.0, indicating that the contact is scheduled - not that non-occurrence of the contact is impossible, just that occurrence of the contact is planned and scheduled rather than merely imputed from past node behavior. In the latter case, confidence indicates our estimation of the likelihood of this potential contact.
The period of time between the start and stop times of a contact is termed the contact's \"interval\". The intervals of scheduled contacts are not allowed to overlap.
Commands pertaining to three different types of contact can be intermixed within an .ionrc file that defines a contact plan.
1 Registration
When start_time is \"-1\", the contact signifies the \"registration\" of a node in the region corresponding to the contact plan of which this contact is a part. In this case, source_node and dest_node must be identical and non-zero. A registration contact simply affirms the source node's permanent membership in this region, persisting even during periods when the node is able neither to send nor to receive data. When inserted into the contact plan, the contact's start and stop times are both automatically set to the maximum POSIX time, its data rate is set to zero, and its confidence value is set to 1.0.
2 Hypothetical
When stop_time is \"0\", the contact is \"hypothetical\". A hypothetical contact is an anticipated opportunity for the local node to transmit data to, or receive data from, some potentially neighboring node in the same region. The nature of that contact is completely unknown; if and when the contact occurs, the hypothetical contact will be transformed into a \"discovered\" contact for the duration of the opportunity, after which it will revert to being hypothetical. source_node and dest_node must NOT be identical, and one or the other must identify the local node. When inserted into the contact plan, the contact's start time is automatically set to zero, its stop time is set to the maximum POSIX time, its data rate is set to zero, and its confidence value is set to 0.0.
3 Scheduled
Otherwise, the contact is \"scheduled\". A scheduled contact is a managed opportunity to transmit data between nodes, as inferred (for example) from a spacecraft or ground station operating plan. start_time must be less than stop_time and data_rate and confidence must both be greater than zero.
c contact start_time source_node dest_node xmit_data_rate [confidence]
The change contact command. This command changes the data transmission rate and possibly our level of confidence in the scheduled period of data transmission from source_node to dest_node starting at start_time. Registration and hypothetical contacts cannot be changed.
d contact start_time source_node dest_node
The delete contact command. This command deletes the contact from source_node to dest_node starting at start_time. To delete all scheduled contacts between some pair of nodes, use '*' as start_time. To delete a registration contact, use \"-1\" as start_time. To delete a hypothetical contact, use \"0\" as start_time.
i contact start_time source_node dest_node
This command will print information (stop time, data rate, confidence) about the scheduled period of transmission from source_node to dest_node that starts at start_time.
l contact
This command lists all contacts in the contact plan for the selected region.
b contact
The brief contacts command. This command writes a file of commands that will recreate the current list of contacts, for the selected region, in the node's ION database. The name of the file will be \"contacts.region_number.ionrc\".
a range start_time stop_time one_node the_other_node distance
The add range command. This command predicts a period of time during which the distance from one_node to the_other_node will be constant to within one light second. The period will begin at start_time and end at stop_time, and the distance between the nodes during that time will be distance light seconds.
NOTE that the ranges declared by these commands are directional. ION does not automatically assume that the distance from node A to node B is the same as the distance from node B to node A. While this symmetry is certainly true of geographic distance, the range that concerns ION is the latency in propagating a signal from one node to the other; this latency may be different in different directions because (for example) the signal from B to A might need to be forwarded along a different convergence-layer network path from the one used for the signal from A to B.
For this reason, the range identification syntax for this command is asymmetrical: ION interprets an add range command in which the node number of the first cited node is numerically less than that of the second cited node as implicitly declaring the same distance in the reverse direction (the normal case) UNLESS a second range command is present that cites the same two nodes in the opposite order, which overrides the implicit declaration. A range command in which the node number of the first cited node is numerically greater than that of the second cited node implies ABSOLUTELY NOTHING about the distance in the reverse direction.
d range start_time one_node the_other_node
The delete range command. This command deletes the predicted period of constant distance between one_node and the_other_node starting at start_time. To delete all ranges between some pair of nodes, use '*' as start_time.
NOTE that the range identification syntax for this command is asymmetrical, much as described for the add range command described above. ION interprets a delete range command in which the node number of the first cited node is numerically less than that of the second cited node as implicitly requesting deletion of the range in the opposite direction as well. A delete range command in which the node number of the first cited node is numerically greater than that of the second cited node deletes only the range in that direction; the asserted range in the opposite direction is unaffected.
i range start_time one_node the_other_node
This command will print information (the stop time and range) about the predicted period of constant distance between one_node and the_other_node that starts at start_time.
l range
This command lists all predicted periods of constant distance.
b range
The brief ranges command. This command writes a file of commands that will recreate the current list of ranges in the node's ION database. The file's name will be \"ranges.ionrc\".
m utcdelta local_time_sec_after_UTC
This management command sets ION's understanding of the current difference between correct UTC time and the localtime equivalent of the current calendar (i.e., Unix epoch) time as reported by the clock for the local ION node's computer. This delta is automatically applied to locally obtained time values whenever ION needs to know the current time. For machines that are synchronized by NTP, the value of this delta should be 0, the default.
Note that the purpose of the UTC delta is not to correct for time zone differences (which operating systems often do natively) but rather to compensate for error (drift) in clocks, particularly spacecraft clocks. The hardware clock on a spacecraft might gain or lose a few seconds every month, to the point at which its understanding of the current time - as reported out by the operating system and converted to UTC - might differ significantly from the actual value of UTC as reported by authoritative clocks on Earth. To compensate for this difference without correcting the clock itself (which can be difficult and dangerous), ION simply adds the UTC delta to the calendar time reported by the operating system.
Note that this means that setting the UTC delta is not a one-time node configuration activity but rather an ongoing node administration chore, because a drifting clock typically keeps on drifting.
m clockerr known_maximum_clock_error
This management command sets ION's understanding of the accuracy of the scheduled start and stop times of planned contacts, in seconds. The default value is 1. When revising local data transmission and reception rates, ionadmin will adjust contact start and stop times by this interval to be sure not to send bundles that arrive before the neighbor expects data arrival or to discard bundles that arrive slightly before they were expected.
m clocksync [ { 1 | 0 } ]
This management command reports whether or not the computer on which the local ION node is running has a synchronized clock, as discussed in the description of the ionClockIsSynchronized() function (ion(3)).
If a Boolean argument is provided when the command is executed, the characterization of the machine's clock is revised to conform with the asserted value. The default value is 1.
m production planned_data_production_rate
This management command sets ION's expectation of the mean rate of continuous data origination by local BP applications throughout the period of time over which congestion forecasts are computed, in bytes per second. For nodes that function only as routers this variable will normally be zero. A value of -1, which is the default, indicates that the rate of local data production is unknown; in that case local data production is not considered in the computation of congestion forecasts.
m consumption planned_data_consumption_rate
This management command sets ION's expectation of the mean rate of continuous data delivery to local BP applications throughout the period of time over which congestion forecasts are computed, in bytes per second. For nodes that function only as routers this variable will normally be zero. A value of -1, which is the default, indicates that the rate of local data consumption is unknown; in that case local data consumption is not considered in the computation of congestion forecasts.
m inbound heap_occupancy_limit [file_system_occupancy_limit]
This management command sets the maximum number of megabytes of storage space in ION's SDR non-volatile heap, and/or in the local file system, that can be used for the storage of inbound zero-copy objects. A value of -1 for either limit signifies \"leave unchanged\". The default heap limit is 30% of the SDR data space's total heap size. The default file system limit is 1 Terabyte.
m outbound heap_occupancy_limit [file_system_occupancy_limit]
This management command sets the maximum number of megabytes of storage space in ION's SDR non-volatile heap, and/or in the local file system, that can be used for the storage of outbound zero-copy objects. A value of -1 for either limit signifies \"leave unchanged\". The default heap limit is 30% of the SDR data space's total heap size. The default file system limit is 1 Terabyte.
m search max_free_blocks_to_search_through
This management command sets the limit on the number of free blocks the heap space allocation function will search through in the nominal free space bucket, looking for a sufficiently large free block, before giving up and switching to the next higher non-empty free space bucket. The default value is 0, which yields the highest memory management speed but may leave heap space under-utilized: data objects may be stored in unnecessarily large heap space blocks. Increasing the value of the heap space search limit will manage space more efficiently - with less waste - but more slowly.
m horizon { 0 | end_time_for_congestion_forecasts }
This management command sets the end time for computed congestion forecasts. Setting congestion forecast horizon to zero sets the congestion forecast end time to infinite time in the future: if there is any predicted net growth in bundle storage space occupancy at all, following the end of the last scheduled contact, then eventual congestion will be predicted. The default value is zero, i.e., no end time.
m alarm 'congestion_alarm_command'
This management command establishes a command which will automatically be executed whenever ionadmin predicts that the node will become congested at some future time. By default, there is no alarm command.
m usage
This management command simply prints ION's current data space occupancy (the number of megabytes of space in the SDR non-volatile heap and file system that are occupied by inbound and outbound zero-copy objects), the total zero-copy-object space occupancy ceiling, and the maximum level of occupancy predicted by the most recent ionadmin congestion forecast computation.
r 'command_text'
The run command. This command will execute command_text as if it had been typed at a console prompt. It is used to, for example, run another administrative program.
s
The start command. This command starts the rfxclock task on the local ION node.
x
The stop command. This command stops the rfxclock task on the local ION node.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
@ 2008/10/05-11:30:00
Sets the reference time to 1130 (UTC) on 5 October 2008.
a range +1 2009/01/01-00:00:00 1 2 12
Predicts that the distance between nodes 1 and 2 (endpoint IDs ipn:1.0 and ipn:2.0) will remain constant at 12 light seconds over the interval that begins 1 second after the reference time and ends at the end of calendar year 2009.
a contact +60 +7260 1 2 10000
Schedules a period of transmission at 10,000 bytes/second from node 1 to node 2, starting 60 seconds after the reference time and ending exactly two hours (7200 seconds) after it starts.
ionadmin(1), rfxclock(1), ion(3)
"},{"location":"man/ici/ionsecadmin/","title":"NAME","text":"ionsecadmin - ION global security database management interface
"},{"location":"man/ici/ionsecadmin/#synopsis","title":"SYNOPSIS","text":"ionsecadmin [ commands_filename ]
"},{"location":"man/ici/ionsecadmin/#description","title":"DESCRIPTION","text":"ionsecadmin configures and manages the ION security database on the local computer.
It configures and manages the ION security database on the local computer in response to ION configuration commands found in commands_filename, if provided; if not, ionsecadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from ionsecadmin by entering the command 'h' or '?' at the prompt. The commands are documented in ionsecrc(5).
"},{"location":"man/ici/ionsecadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of ION security database administration.
ionsecadmin
Enter interactive ION security policy administration command entry mode.
ionsecadmin host1.ionsecrc
Execute all configuration commands in host1.ionsecrc, then terminate immediately.
Status and diagnostic messages from ionsecadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which ionsecadmin was run. The log file is typically named ion.log.
See also ionsecrc(5).
"},{"location":"man/ici/ionsecadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/ionsecadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ionsecadmin. Otherwise ionsecadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ionsecadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see ionsecrc(5) for details.
"},{"location":"man/ici/ionsecadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionsecadmin/#see-also","title":"SEE ALSO","text":"ionsecrc(5)
"},{"location":"man/ici/ionsecrc/","title":"NAME","text":"ionsecrc - ION security database management commands file
"},{"location":"man/ici/ionsecrc/#description","title":"DESCRIPTION","text":"ION security database management commands are passed to ionsecadmin either in a file of text lines or interactively at ionsecadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the ION security database management commands are described below.
"},{"location":"man/ici/ionsecrc/#commands","title":"COMMANDS","text":"?
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 ionsecadmin 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
The initialize command. Until this command is executed, the local ION node has no security database and most ionsecadmin commands will fail.
a key key_name file_name
The add key command. This command adds a named key value to the security database. The content of file_name is taken as the value of the key. Named keys can be referenced by other elements of the security database.
c key key_name file_name
The change key command. This command changes the value of the named key, obtaining the new key value from the content of file_name.
d key key_name
The delete key command. This command deletes the key identified by name.
i key key_name
This command will print information about the named key, i.e., the length of its current value.
l key
This command lists all keys in the security database.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a key BABKEY ./babkey.txt
Adds a new key named \"BABKEY\" whose value is the content of the file \"./babkey.txt\".
ionsecadmin(1)
"},{"location":"man/ici/ionunlock/","title":"NAME","text":"ionunlock - utility for unlocking a locked ION node
"},{"location":"man/ici/ionunlock/#synopsis","title":"SYNOPSIS","text":"ionunlock [sdr_name]
"},{"location":"man/ici/ionunlock/#description","title":"DESCRIPTION","text":"The ionunlock program is designed to be run when some ION thread has terminated while it is the owner of the node's system mutex, i.e., while in the midst of an SDR transaction. IT MUST NEVER BE RUN AT ANY OTHER TIME as it will totally corrupt a node that is not locked up. The program simply declares itself to be the owner of the incomplete transaction and cancels it, enabling the rest of the system to resume operations.
If omitted, sdr_name defaults to \"ion\".
"},{"location":"man/ici/ionunlock/#exit-status","title":"EXIT STATUS","text":"\"0\"
ionunlock has terminated successfully.
\"1\"
ionunlock has terminated unsuccessfully. See diagnostic messages in the ion.log log file for details.
No configuration files are needed.
"},{"location":"man/ici/ionunlock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/ionunlock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't initialize the SDR system.
Probable operations error: ION appears not to be initialized, in which case there is no point in running ionunlock.
Can't start using SDR.
ION system error. See earlier diagnostic messages posted to ion.log for details. In this event it is unlikely that ionunlock can be run successfully, and it is also unlikely that it would have any effect if it did run successfully.
ionunlock unnecessary; exiting.
Either the indicated SDR is not initialized or it is not currently stuck in a transaction.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionunlock/#see-also","title":"SEE ALSO","text":"ionxnowner(1), sdrmend(1), sdr(3)
"},{"location":"man/ici/ionxnowner/","title":"NAME","text":"ionxnowner - report on which threads are initiating SDR transactions
"},{"location":"man/ici/ionxnowner/#synopsis","title":"SYNOPSIS","text":"ionxnowner [interval [count [echo]]]
"},{"location":"man/ici/ionxnowner/#description","title":"DESCRIPTION","text":"For count interations (defaulting to 1), ionxnowner prints the process ID and thread ID of the thread that currently \"owns\" the local node's SDR data store (i.e., started the current transaction), then sleeps interval seconds (minimum 1). If the optional echo parameter is set to 1, then the transaction owner message is logged as well as printed to the console.
"},{"location":"man/ici/ionxnowner/#exit-status","title":"EXIT STATUS","text":"\"0\"
ionxnowner has terminated.
No configuration files are needed.
"},{"location":"man/ici/ionxnowner/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/ionxnowner/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to ION.
ION system error. See earlier diagnostic messages posted to ion.log for details.
Can't access SDR.
ION system error. See earlier diagnostic messages posted to ion.log for details.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionxnowner/#see-also","title":"SEE ALSO","text":"ionunlock(1), sdr(3), psmwatch(1)
"},{"location":"man/ici/llcv/","title":"NAME","text":"llcv - library for manipulating linked-list condition variable objects
"},{"location":"man/ici/llcv/#synopsis","title":"SYNOPSIS","text":"#include \"llcv.h\"\n\ntypedef struct llcv_str\n{\n Lyst list;\n pthread_mutex_t mutex;\n pthread_cond_t cv;\n} *Llcv;\n\ntypedef int (*LlcvPredicate)(Llcv);\n\n[see description for available functions]\nA \"linked-list condition variable\" object (LLCV) is an inter-thread communication mechanism that pairs a process-private linked list in memory with a condition variable as provided by the pthreads library. LLCVs echo in thread programming the standard ION inter-process or inter-task communication model that pairs shared-memory semaphores with linked lists in shared memory or shared non-volatile storage. As in the semaphore/list model, variable-length messages may be transmitted; the resources allocated to the communication mechanism grow and shrink to accommodate changes in data rate; the rate at which messages are issued is completely decoupled from the rate at which messages are received and processed. That is, there is no flow control, no blocking, and therefore no possibility of deadlock or \"deadly embrace\". Traffic spikes are handled without impact on processing rate, provided sufficient memory is provided to accommodate the peak backlog.
An LLCV comprises a Lyst, a mutex, and a condition variable. The Lyst may be in either private or shared memory, but the Lyst itself is not shared with other processes. The reader thread waits on the condition variable until signaled by a writer that some condition is now true. The standard Lyst API functions are used to populate and drain the linked list. In order to protect linked list integrity, each thread must call llcv_lock() before operating on the Lyst and llcv_unlock() afterwards. The other llcv functions merely effect flow signaling in a way that makes it unnecessary for the reader to poll or busy-wait on the Lyst.
Llcv llcv_open(Lyst list, Llcv llcv)
Opens an LLCV, initializing as necessary. The list argument must point to an existing Lyst, which may reside in either private or shared dynamic memory. llcv must point to an existing llcv_str management object, which may reside in either static or dynamic (private or shared) memory -- but NOT in stack space. Returns llcv on success, NULL on any error.
void llcv_lock(Llcv llcv)
Locks the LLCV's Lyst so that it may be updated or examined safely by the calling thread. Fails silently on any error.
void llcv_unlock(Llcv llcv)
Unlocks the LLCV's Lyst so that another thread may lock and update or examine it. Fails silently on any error.
int llcv_wait(Llcv llcv, LlcvPredicate cond, int microseconds)
Returns when the Lyst encapsulated within the LLCV meets the indicated condition. If microseconds is non-negative, will return -1 and set errno to ETIMEDOUT when the indicated number of microseconds has passed, if and only if the indicated condition has not been met by that time. Negative values of the microseconds argument other than LLCV_BLOCKING (defined as -1) are illegal. Returns -1 on any error.
void llcv_signal(Llcv llcv, LlcvPredicate cond)
Locks the indicated LLCV's Lyst; tests (evaluates) the indicated condition with regard to that LLCV; if the condition is true, signals to the waiting reader on this LLCV (if any) that the Lyst encapsulated in the indicated LLCV now meets the indicated condition; and unlocks the Lyst.
void llcv_signal_while_locked(Llcv llcv, LlcvPredicate cond)
Same as llcv_signal() except does not lock the Llcv's mutex before signalling or unlock afterwards. For use when the Llcv is already locked; prevents deadlock.
void llcv_close(Llcv llcv)
Destroys the indicated LLCV's mutex and condition variable. Fails silently (and has no effect) if a reader is currently waiting on the Llcv.
int llcv_lyst_is_empty(Llcv Llcv)
A built-in \"convenience\" predicate, for use when calling llcv_wait(), llcv_signal(), or llcv_signal_while_locked(). Returns true if the length of the indicated LLCV's encapsulated Lyst is zero, false otherwise.
int llcv_lyst_not_empty(Llcv Llcv)
A built-in \"convenience\" predicate, for use when calling llcv_wait(), llcv_signal(), or llcv_signal_while_locked(). Returns true if the length of the LLCV's encapsulated Lyst is non-zero, false otherwise.
lyst(3)
"},{"location":"man/ici/lyst/","title":"NAME","text":"lyst - library for manipulating generalized doubly linked lists
"},{"location":"man/ici/lyst/#synopsis","title":"SYNOPSIS","text":"#include \"lyst.h\"\n\ntypedef int (*LystCompareFn)(void *s1, void *s2);\ntypedef void (*LystCallback)(LystElt elt, void *userdata);\n\n[see description for available functions]\nThe \"lyst\" library uses two types of objects, Lyst objects and LystElt objects. A Lyst knows how many elements it contains, its first and last elements, the memory manager used to create/destroy the Lyst and its elements, and how the elements are sorted. A LystElt knows its content (normally a pointer to an item in memory), what Lyst it belongs to, and the LystElts before and after it in that Lyst.
Lyst lyst_create(void)
Create and return a new Lyst object without any elements in it. All operations performed on this Lyst will use the allocation/deallocation functions of the default memory manager \"std\" (see memmgr(3)). Returns NULL on any failure.
Lyst lyst_create_using(unsigned memmgrId)
Create and return a new Lyst object without any elements in it. All operations performed on this Lyst will use the allocation/deallocation functions of the specified memory manager (see memmgr(3)). Returns NULL on any failure.
void lyst_clear(Lyst list)
Clear a Lyst, i.e. free all elements of list, calling the Lyst's deletion function if defined, but without destroying the Lyst itself.
void lyst_destroy(Lyst list)
Destroy a Lyst. Will free all elements of list, calling the Lyst's deletion function if defined.
void lyst_compare_set(Lyst list, LystCompareFn compareFn)
LystCompareFn lyst_compare_get(Lyst list)
Set/get comparison function for specified Lyst. Comparison functions are called with two Lyst element data pointers, and must return a negative integer if first is less than second, 0 if both are equal, and a positive integer if first is greater than second (i.e., same return values as strcmp(3)). The comparison function is used by the lyst_insert(), lyst_search(), lyst_sort(), and lyst_sorted() functions.
void lyst_direction_set(Lyst list, LystSortDirection direction)
Set sort direction (either LIST_SORT_ASCENDING or LIST_SORT_DESCENDING) for specified Lyst. If no comparison function is set, then this controls whether new elements are added to the end or beginning (respectively) of the Lyst when lyst_insert() is called.
void lyst_delete_set(Lyst list, LystCallback deleteFn, void *userdata)
Set user deletion function for specified Lyst. This function is automatically called whenever an element of the Lyst is deleted, to perform any user-required processing. When automatically called, the deletion function is passed two arguments: the element being deleted and the userdata pointer specified in the lyst_delete_set() call.
void lyst_insert_set(Lyst list, LystCallback insertFn, void *userdata)
Set user insertion function for specified Lyst. This function is automatically called whenever a Lyst element is inserted into the Lyst, to perform any user-required processing. When automatically called, the insertion function is passed two arguments: the element being inserted and the userdata pointer specified in the lyst_insert_set() call.
unsigned long lyst_length(Lyst list)
Return the number of elements in the Lyst.
LystElt lyst_insert(Lyst list, void *data)
Create a new element whose content is the pointer value data and insert it into the Lyst. Uses the Lyst's comparison function to select insertion point, if defined; otherwise adds the new element at the beginning or end of the Lyst, depending on the Lyst sort direction setting. Returns a pointer to the newly created element, or NULL on any failure.
LystElt lyst_insert_first(Lyst list, void *data)
LystElt lyst_insert_last(Lyst list, void *data)
Create a new element and insert it at the beginning/end of the Lyst. If these functions are used when inserting elements into a Lyst with a defined comparison function, then the Lyst may get out of order and future calls to lyst_insert() can put new elements in unpredictable locations. Returns a pointer to the newly created element, or NULL on any failure.
LystElt lyst_insert_before(LystElt element, void *data)
LystElt lyst_insert_after(LystElt element, void *data)
Create a new element and insert it before/after the specified element. If these functions are used when inserting elements into a Lyst with a defined comparison function, then the Lyst may get out of order and future calls to lyst_insert() can put new elements in unpredictable locations. Returns a pointer to the newly created element, or NULL on any failure.
void lyst_delete(LystElt element)
Delete the specified element from its Lyst and deallocate its memory. Calls the user delete function if defined.
LystElt lyst_first(Lyst list)
LystElt lyst_last(Lyst list)
Return a pointer to the first/last element of a Lyst.
LystElt lyst_next(LystElt element)
LystElt lyst_prev(LystElt element)
Return a pointer to the element following/preceding the specified element.
LystElt lyst_search(LystElt element, void *searchValue)
Find the first matching element in a Lyst starting with the specified element. Returns NULL if no matches are found. Uses the Lyst's comparison function if defined, otherwise searches from the given element to the end of the Lyst.
Lyst lyst_lyst(LystElt element)
Return the Lyst to which the specified element belongs.
void* lyst_data(LystElt element)
void* lyst_data_set(LystElt element, void *data)
Get/set the pointer value content of the specified Lyst element. The set routine returns the element's previous content, and the delete function is not called. If the lyst_data_set() function is used on an element of a Lyst with a defined comparison function, then the Lyst may get out of order and future calls to lyst_insert() can put new elements in unpredictable locations.
void lyst_sort(Lyst list)
Sort the Lyst based on the current comparison function and sort direction. A stable insertion sort is used that is very fast when the elements are already in order.
int lyst_sorted(Lyst list)
Determine whether or not the Lyst is sorted based on the current comparison function and sort direction.
void lyst_apply(Lyst list, LystCallback applyFn, void *userdata)
Apply the function applyFn automatically to each element in the Lyst. When automatically called, applyFn is passed two arguments: a pointer to an element, and the userdata argument specified in the call to lyst_apply(). applyFn should not delete or reorder the elements in the Lyst.
memmgr(3), psm(3)
"},{"location":"man/ici/memmgr/","title":"NAME","text":"memmgr - memory manager abstraction functions
"},{"location":"man/ici/memmgr/#synopsis","title":"SYNOPSIS","text":"#include \"memmgr.h\"\n\ntypedef void *(* MemAllocator)\n (char *fileName, int lineNbr, size_t size);\ntypedef void (* MemDeallocator)\n (char *fileName, int lineNbr, void * blk);\ntypedef void *(* MemAtoPConverter) (unsigned int address);\ntypedef unsigned int (* MemPtoAConverter) (void * pointer);\n\nunsigned int memmgr_add (char *name,\n MemAllocator take, \n MemDeallocator release, \n MemAtoPConverter AtoP, \n MemPtoAConverter PtoA);\nint memmgr_find (char *name);\nchar *memmgr_name (int mgrId);\nMemAllocator memmgr_take (int mgrId);\nMemDeallocator memmgr_release (int mgrId);\nMemAtoPConverter memmgr_AtoP (int mgrId);\nMemPtoAConverter memmgr_PtoA (int mgrId;\n\nint memmgr_open (int memKey,\n unsigned long memSize,\n char **memPtr,\n int *smId,\n char *partitionName,\n PsmPartition *partition,\n int *memMgr,\n MemAllocator afn,\n MemDeallocator ffn,\n MemAtoPConverter apfn,\n MemPtoAConverter pafn);\nvoid memmgr_destroy (int smId,\n PsmPartition *partition);\n\"memmgr\" is an abstraction layer for administration of memory management. It enables multiple memory managers to coexist in a single application. Each memory manager specification is required to include pointers to a memory allocation function, a memory deallocation function, and functions for translating between local memory pointers and \"addresses\", which are abstract memory locations that have private meaning to the manager. The allocation function is expected to return a block of memory of size \"size\" (in bytes), initialized to all binary zeroes. The fileName and lineNbr arguments to the allocation and deallocation functions are expected to be the values of __FILE__ and __LINE__ at the point at which the functions are called; this supports any memory usage tracing via sptrace(3) that may be implemented by the underlying memory management system.
Memory managers are identified by number and by name. The identifying number for a memory manager is an index into a private, fixed-length array of up to 8 memory manager configuration structures; that is, memory manager number must be in the range 0-7. However, memory manager numbers are assigned dynamically and not always predictably. To enable multiple applications to use the same memory manager for a given segment of shared memory, a memory manager may be located by a predefined name of up to 15 characters that is known to all the applications.
The memory manager with manager number 0 is always available; its name is \"std\". Its memory allocation function is calloc(), its deallocation function is free(), and its pointer/address translation functions are merely casts.
unsigned int memmgr_add(char *name, MemAllocator take, MemDeallocator release, MemAtoPConverter AtoP, MemPtoAConverter PtoA)
Add a memory manager to the memory manager array, if not already defined; attempting to add a previously added memory manager is not considered an error. name is the name of the memory manager. take is a pointer to the manager's memory allocation function; release is a pointer to the manager's memory deallocation function. AtoP is a pointer to the manager's function for converting an address to a local memory pointer; PtoA is a pointer to the manager's pointer-to-address converter function. Returns the memory manager ID number assigned to the named manager, or -1 on any error.
NOTE: memmgr_add() is NOT thread-safe. In a multithreaded execution image (e.g., VxWorks), all memory managers should be loaded before any subordinate threads or tasks are spawned.
int memmgr_find(char *name)
Return the memmgr ID of the named manager, or -1 if not found.
char *memmgr_name(int mgrId)
Return the name of the manager given by mgrId.
MemAllocator memmgr_take(int mgrId)
Return the allocator function pointer for the manager given by mgrId.
memDeallocator memmgr_release(int mgrId)
Return the deallocator function pointer for the manager given by mgrId.
MemAtoPConverter memmgr_AtoP(int mgrId)
Return the address-to-pointer converter function pointer for the manager given by mgrId.
MemPtoAConverter memmgr_PtoA(int mgrId)
Return the pointer-to-address converter function pointer for the manager given by mgrId.
int memmgr_open(int memKey, unsigned long memSize, char **memPtr, int *smId, char *partitionName, PsmPartition *partition, int *memMgr, MemAllocator afn, MemDeallocator ffn, MemAtoPConverter apfn, MemPtoAConverter pafn);
memmgr_open() opens one avenue of access to a PSM managed region of shared memory, initializing as necessary.
In order for multiple tasks to share access to this memory region, all must cite the same memkey and partitionName when they call memmgr_open(). If shared access is not necessary, then memKey can be SM_NO_KEY and partitionName can be any valid partition name.
If it is known that a prior invocation of memmgr_open() has already initialized the region, then memSize can be zero and memPtr must be NULL. Otherwise memSize is required and the required value of memPtr depends on whether or not the memory that is to be shared and managed has already been allocated (e.g., it's a fixed region of bus memory). If so, then the memory pointer variable that memPtr points to must contain the address of that memory region. Otherwise, *memPtr must contain NULL.
memmgr_open() will allocate system memory as necessary and will in any case return the address of the shared memory region in *memPtr.
If the shared memory is newly allocated or otherwise not yet under PSM management, then memmgr_open() will invoke psm_manage() to manage the shared memory region. It will also add a catalogue for the managed shared memory region as necessary.
If memMgr is non-NULL, then memmgr_open() will additionally call memmgr_add() to establish a new memory manager for this managed shared memory region, as necessary. The index of the applicable memory manager will be returned in memMgr. If that memory manager is newly created, then the supplied afn, ffn, apfn, and pafn functions (which can be written with reference to the memory manager index value returned in memMgr) have been established as the memory management functions for local private access to this managed shared memory region.
Returns 0 on success, -1 on any error.
void memmgr_destroy(int smId, PsmPartition *partition);
memmgr_destroy() terminates all access to a PSM managed region of shared memory, invoking psm_erase() to destroy the partition and sm_ShmDestroy() to destroy the shared memory object.
/* this example uses the calloc/free memory manager, which is\n * called \"std\", and is always defined in memmgr. */\n\n #include \"memmgr.h\"\n\n main() \n {\n int mgrId;\n MemAllocator myalloc;\n MemDeallocator myfree;\n char *newBlock;\n\n mgrId = memmgr_find(\"std\");\n myalloc = memmgr_take(mgrId);\n myfree = memmgr_release(mgrId);\n ...\n\n newBlock = myalloc(5000);\n ...\n myfree(newBlock);\n }\npsm(3)
"},{"location":"man/ici/owltsim/","title":"NAME","text":"owltsim - one-way light time transmission delay simulator
"},{"location":"man/ici/owltsim/#synopsis","title":"SYNOPSIS","text":"owltsim config_filename [-v]
"},{"location":"man/ici/owltsim/#description","title":"DESCRIPTION","text":"owltsim delays delivery of data between pairs of ION nodes by specified lengths of time, simulating the signal propagation delay imposed by distance between the nodes.
Its operation is configured by delay simulation configuration lines in the file identified by config_filename. A pair of threads is created for each line in the file: one that receives UDP datagrams on a specified port and queues them in a linked list, and a second that later removes queued datagrams from the linked list and sends them on to a specified UDP port on a specified network host.
Each configuration line must be of the following form:
to from my_port# dest_host dest_port# owlt modulus
to identifies the receiving node.
This parameter is purely informational, intended to make owltsim's printed messages more helpful to the user.
from identifies the sending node.
A value of '*' may be used to indicate \"all nodes\". Again, this parameter is purely informational, intended to make owltsim's printed messages more helpful to the user.
my_port# identifies owltsim's receiving port for this traffic.
modulus controls the artificial random data loss imposed on this traffic by owltsim.
A value of '0' specifies \"no imposed data loss\". Any modulus value N > 0 causes owltsim to randomly drop (i.e., not transmit upon expiration of the delay interval) one out of every N packets. Any modulus value N < 0 causes owltsim to deterministically drop every (0 - N)th packet.
The optional -v (\"verbose\") parameter causes owltsim to print a message whenever it receives, sends, or drops (due to artificial random data loss) a datagram.
Note that error conditions may cause one delay simulation (a pair of threads) to terminate without terminating any others.
owltsim is designed to run indefinitely. To terminate the program, just use control-C to kill it.
"},{"location":"man/ici/owltsim/#exit-status","title":"EXIT STATUS","text":"Here is a sample owltsim configuration file:
This file indicates that owltsim will receive on port 5502 the ION traffic from node 2 that is destined for node 7, which will receive it at port 5001 on the computer named ptl07.jpl.nasa.gov; 75 seconds of delay (simulating a distance of 75 light seconds) will be imposed on this transmission activity, and owltsim will not simulate any random data loss.
In the reverse direction, owltsim will receive on port 5507 the ION traffic from node 7 that is destined for node 2, which will receive it at port 5001 on the computer named ptl02.jpl.nasa.gov; 75 seconds of delay will again be imposed on this transmission activity, and owltsim will randomly discard (i.e., not transmit upon expiration of the transmission delay interval) one datagram out of every 16 received at this port.
"},{"location":"man/ici/owltsim/#files","title":"FILES","text":"Not applicable.
"},{"location":"man/ici/owltsim/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/owltsim/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be printed to stdout:
owltsim can't open configuration file
The program terminates.
owltsim failed on fscanf
Failure on reading the configuration file. The program terminates.
owltsim stopped malformed config file line line_number.
Failure on parsing the configuration file. The program terminates.
owltsim can't spawn receiver thread
The program terminates.
owltsim out of memory.
The program terminates.
owltsim can't open reception socket
The program terminates.
owltsim can't initialize reception socket
The program terminates.
owltsim can't open transmission socket
The program terminates.
owltsim can't initialize transmission socket
The program terminates.
owltsim can't spawn timer thread
The program terminates.
owltsim can't acquire datagram
Datagram transmission failed. This causes the threads for the affected delay simulation to terminate, without terminating any other threads.
owltsim failed on send
Datagram transmission failed. This causes the threads for the affected delay simulation to terminate, without terminating any other threads.
at time owltsim LOST a dg of length length from sending node destined for receiving node due to ECONNREFUSED.
This is an informational message. Due to an apparent bug in Internet protocol implementation, transmission of a datagram on a connected UDP socket occasionally fails. owltsim does not attempt to retransmit the affected datagram.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/owltsim/#see-also","title":"SEE ALSO","text":"udplsi(1), udplso(1)
"},{"location":"man/ici/owlttb/","title":"NAME","text":"owlttb - one-way light time transmission delay simulator
"},{"location":"man/ici/owlttb/#synopsis","title":"SYNOPSIS","text":"owlttb own_uplink_port# own_downlink_port# dest_uplink_IP_address dest_uplink_port# dest_downlink_IP_address dest_downlink_port# owlt_sec. [-v]
"},{"location":"man/ici/owlttb/#description","title":"DESCRIPTION","text":"owlttb delays delivery of data between an NTTI and a NetAcquire box (or two, one for uplink and one for downlink) by a specified length of time, simulating the signal propagation delay imposed by distance between the nodes.
Its operation is configured by the command-line parameters, except that the delay interval itself may be changed while the program is running. owlttb offers a command prompt (:), and when a new value of one-way light time is entered at this prompt the new delay interval takes effect immediately.
The optional -v (\"verbose\") parameter causes owlttb to print a message whenever it receives, sends, or discards (due to absence of a connected downlink client) a segment of TCP traffic.
owlttb is designed to run indefinitely. To terminate the program, just use control-C to kill it or enter \"q\" at the prompt.
"},{"location":"man/ici/owlttb/#exit-status","title":"EXIT STATUS","text":"Here is a sample owlttb command:
This command indicates that owlttb will accept an uplink traffic connection on port 2901, forwarding the received uplink traffic to port 10001 on the NetAcquire box at 137.7.8.19, and it will accept a downlink traffic connection on port 2902, delivering over that connection all downlink traffic that it receives from connecting to port 10002 on the NetAcquire box at 137.7.8.19. 75 seconds of delay (simulating a distance of 75 light seconds) will be imposed on this transmission activity.
"},{"location":"man/ici/owlttb/#files","title":"FILES","text":"Not applicable.
"},{"location":"man/ici/owlttb/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/owlttb/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be printed to stdout:
owlttb can't spawn uplink thread
The program terminates.
owlttb can't spawn uplink sender thread
The program terminates.
owlttb can't spawn downlink thread
The program terminates.
owlttb can't spawn downlink receiver thread
The program terminates.
owlttb can't spawn downlink sender thread
The program terminates.
owlttb fgets failed
The program terminates.
owlttb out of memory.
The program terminates.
owlttb lost uplink client.
This is an informational message. The NTTI may reconnect at any time.
owlttb lost downlink client
This is an informational message. The NTTI may reconnect at any time.
owlttb can't open TCP socket to NetAcquire
The program terminates.
owlttb can't connect TCP socket to NetAcquire
The program terminates.
owlttb write() error on socket
The program terminates if it was writing to NetAcquire; otherwise it simply recognizes that the client NTTI has disconnected.
owlttb read() error on socket
The program terminates.
owlttb can't open uplink dialup socket
The program terminates.
owlttb can't initialize uplink dialup socket
The program terminates.
owlttb can't open downlink dialup socket
The program terminates.
owlttb can't initialize downlink dialup socket
The program terminates.
owlttb accept() failed
The program terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/platform/","title":"NAME","text":"platform - C software portability definitions and functions
"},{"location":"man/ici/platform/#synopsis","title":"SYNOPSIS","text":"#include \"platform.h\"\n\n[see description for available functions]\nplatform is a library of functions that simplify the porting of software written in C. It provides an API that enables application code to access the resources of an abstract POSIX-compliant \"least common denominator\" operating system -- typically a large subset of the resources of the actual underlying operating system.
Most of the functionality provided by the platform library is aimed at making communication code portable: common functions for shared memory, semaphores, and IP sockets are provided. The implementation of the abstract O/S API varies according to the actual operating system on which the application runs, but the API's behavior is always the same; applications that invoke the platform library functions rather than native O/S system calls may forego some O/S-specific capability, but they gain portability at little if any cost in performance.
Differences in word size among platforms are implemented by values of the SPACE_ORDER macro. \"Space order\" is the base 2 log of the number of octets in a word: for 32-bit machines the space order is 2 (2^2 = 4 octets per word), for 64-bit machines it is 3 (2^3 = 8 octets per word).
A consistent platform-independent representation of large integers is useful for some applications. For this purpose, platform defines new types vast and uvast (unsigned vast) which are consistently defined to be 64-bit integers regardless of the platform's native word size.
The platform.h header file #includes many of the most frequently needed header files: sys/types.h, errno.h, string.h, stdio.h, sys/socket.h, signal.h, dirent.h, netinet/in.h, unistd.h, stdlib.h, sys/time.h, sys/resource.h, malloc.h, sys/param.h, netdb.h, sys/uni.h, and fcntl.h. Beyond this, platform attempts to enhance compatibility by providing standard macros, type definitions, external references, or function implementations that are missing from a few supported O/S's but supported by all others. Finally, entirely new, generic functions are provided to establish a common body of functionality that subsumes significantly different O/S-specific capabilities.
"},{"location":"man/ici/platform/#platform-compatibility-patches","title":"PLATFORM COMPATIBILITY PATCHES","text":"The platform library \"patches\" the APIs of supported O/S's to guarantee that all of the following items may be utilized by application software:
The strchr(), strrchr(), strcasecmp(), and strncasecmp() functions.\n\nThe unlink(), getpid(), and gettimeofday() functions.\n\nThe select() function.\n\nThe FD_BITMAP macro (used by select()).\n\nThe MAXHOSTNAMELEN macro.\n\nThe NULL macro.\n\nThe timer_t type definition.\nThe generic macros and functions in this section may be used in place of comparable O/S-specific functions, to enhance the portability of code. (The implementations of these macros and functions are no-ops in environments in which they are inapplicable, so they're always safe to call.)
FDTABLE_SIZE
The FDTABLE_SIZE macro returns the total number of file descriptors defined for the process (or VxWorks target).
ION_PATH_DELIMITER
The ION_PATH_DELIMITER macro returns the ASCII character -- either '/' or '\\' -- that is used as a directory name delimiter in path names for the file system used by the local platform.
oK(expression)
The oK macro simply casts the value of expression to void, a way of handling function return codes that are not meaningful in this context.
CHKERR(condition)
The CHKERR macro is an \"assert\" mechanism. It causes the calling function to return -1 immediately if condition is false.
CHKZERO(condition)
The CHKZERO macro is an \"assert\" mechanism. It causes the calling function to return 0 immediately if condition is false.
CHKNULL(condition)
The CHKNULL macro is an \"assert\" mechanism. It causes the calling function to return NULL immediately if condition is false.
CHKVOID(condition)
The CHKVOID macro is an \"assert\" mechanism. It causes the calling function to return immediately if condition is false.
void snooze(unsigned int seconds)
Suspends execution of the invoking task or process for the indicated number of seconds.
void microsnooze(unsigned int microseconds)
Suspends execution of the invoking task or process for the indicated number of microseconds.
void getCurrentTime(struct timeval *time)
Returns the current local time (ctime, i.e., Unix epoch time) in a timeval structure (see gettimeofday(3C)).
void isprintf(char *buffer, int bufSize, char *format, ...)
isprintf() is a safe, portable implementation of snprintf(); see the snprintf(P) man page for details. isprintf() differs from snprintf() in that it always NULL-terminates the string in buffer, even if the length of the composed string would equal or exceed bufSize. Buffer overruns are reported by log message; unlike snprintf(), isprintf() returns void.
size_t istrlen(const char *sourceString, size_t maxlen)
istrlen() is a safe implementation of strlen(); see the strlen(3) man page for details. istrlen() differs from strlen() in that it takes a second argument, the maximum valid length of sourceString. The function returns the number of non-NULL characters in sourceString preceding the first NULL character in sourceString, provided that a NULL character appears somewhere within the first maxlen characters of sourceString; otherwise it returns maxlen.
char *istrcpy(char *buffer, char *sourceString, int bufSize)
istrcpy() is a safe implementation of strcpy(); see the strcpy(3) man page for details. istrcpy() differs from strcpy() in that it takes a third argument, the total size of the buffer into which sourceString is to be copied. istrcpy() always NULL-terminates the string in buffer, even if the length of sourceString string would equal or exceed bufSize (in which case sourceString is truncated to fit within the buffer).
char *istrcat(char *buffer, char *sourceString, int bufSize)
istrcat() is a safe implementation of strcat(); see the strcat(3) man page for details. istrcat() differs from strcat() in that it takes a third argument, the total size of the buffer for the string that is being aggregated. istrcat() always NULL-terminates the string in buffer, even if the length of sourceString string would equal or exceed the sum of bufSize and the length of the string currently occupying the buffer (in which case sourceString is truncated to fit within the buffer).
char *igetcwd(char *buf, size_t size)
igetcwd() is normally just a wrapper around getcwd(3). It differs from getcwd(3) only when FSWWDNAME is defined, in which case the implementation of igetcwd() must be supplied in an included file named \"wdname.c\"; this adaptation option accommodates flight software environments in which the current working directory name must be configured rather than discovered at run time.
void isignal(int signbr, void (*handler)(int))
isignal() is a portable, simplified interface to signal handling that is functionally indistinguishable from signal(P). It assures that reception of the indicated signal will interrupt system calls in SVR4 fashion, even when running on a FreeBSD platform.
void iblock(int signbr)
iblock() simply prevents reception of the indicated signal by the calling thread. It provides a means of controlling which of the threads in a process will receive the signal cited in an invocation of isignal().
int ifopen(const char *fileName, int flags, int pmode)
ifopen() is a portable function for opening \"regular\" files. It operates in exactly the same way as open() except that it fails (returning -1) if fileName does not identify a regular file, i.e., it's a directory, a named pipe, etc.
NOTE that ION also provides iopen() which is nothing more than a portable wrapper for open(). iopen() can be used to open a directory, for example.
char *igets(int fd, char *buffer, int buflen, int *lineLen)
igets() reads a line of text, delimited by a newline character, from fd into buffer and writes a NULL character at the end of the string. The newline character itself is omitted from the NULL-terminated text line in buffer; if the newline is immediately preceded by a carriage return character (i.e., the line is from a DOS text file), then the carriage return character is likewise omitted from the NULL-terminated text line in buffer. End of file is interpreted as an implicit newline, terminating the line. If the number of characters preceding the newline is greater than or equal to buflen, only the first (buflen - 1) characters of the line are written into buffer. On error the function sets *lineLen to -1 and returns NULL. On reading end-of-file, the function sets *lineLen to zero and returns NULL. Otherwise the function sets *lineLen to the length of the text line in buffer, as if from strlen(3), and returns buffer.
int iputs(int fd, char *string)
iputs() writes to fd the NULL-terminated character string at string. No terminating newline character is appended to string by iputs(). On error the function returns -1; otherwise the function returns the length of the character string written to fd, as if from strlen(3).
vast strtovast(char *string)
Converts the leading characters of string, skipping leading white space and ending at the first subsequent character that can't be interpreted as contributing to a numeric value, to a vast integer and returns that integer.
uvast strtouvast(char *string)
Same as strtovast() except the result is an unsigned vast integer value.
void findToken(char **cursorPtr, char **token)
Locates the next non-whitespace lexical token in a character array, starting at *cursorPtr. The function NULL-terminates that token within the array and places a pointer to the token in *token. Also accommodates tokens enclosed within matching single quotes, which may contain embedded spaces and escaped single-quote characters. If no token is found, *token contains NULL on return from this function.
void *acquireSystemMemory(size_t size)
Uses memalign() to allocate a block of system memory of length size, starting at an address that is guaranteed to be an integral multiple of the size of a pointer to void, and initializes the entire block to binary zeroes. Returns the starting address of the allocated block on success; returns NULL on any error.
int createFile(const char *name, int flags)
Creates a file of the indicated name, using the indicated file creation flags. This function provides common file creation functionality across VxWorks and Unix platforms, invoking creat() under VxWorks and open() elsewhere. For return values, see creat(2) and open(2).
unsigned int getInternetAddress(char *hostName)
Returns the IP address of the indicated host machine, or zero if the address cannot be determined.
char *getInternetHostName(unsigned int hostNbr, char *buffer)
Writes the host name of the indicated host machine into buffer and returns buffer, or returns NULL on any error. The size of buffer should be (MAXHOSTNAMELEN + 1).
int getNameOfHost(char *buffer, int bufferLength)
Writes the first (bufferLength - 1) characters of the host name of the local machine into buffer. Returns 0 on success, -1 on any error.
unsigned int getAddressOfHost()
Returns the IP address for the host name of the local machine, or 0 on any error.
void parseSocketSpec(char *socketSpec, unsigned short *portNbr, unsigned int *hostNbr)
Parses socketSpec, extracting host number (IP address) and port number from the string. socketSpec is expected to be of the form \"{ @ | hostname }[:<portnbr>]\", where @ signifies \"the host name of the local machine\". If host number can be determined, writes it into *hostNbr; otherwise writes 0 into *hostNbr. If port number is supplied and is in the range 1024 to 65535, writes it into *portNbr; otherwise writes 0 into *portNbr.
void printDottedString(unsigned int hostNbr, char *buffer)
Composes a dotted-string (xxx.xxx.xxx.xxx) representation of the IPv4 address in hostNbr and writes that string into buffer. The length of buffer must be at least 16.
char *getNameOfUser(char *buffer)
Writes the user name of the invoking task or process into buffer and returns buffer. The size of buffer must be at least L_cuserid, a constant defined in the stdio.h header file. Returns buffer.
int reUseAddress(int fd)
Makes the address that is bound to the socket identified by fd reusable, so that the socket can be closed and immediately reopened and re-bound to the same port number. Returns 0 on success, -1 on any error.
int makeIoNonBlocking(int fd)
Makes I/O on the socket identified by fd non-blocking; returns -1 on failure. An attempt to read on a non-blocking socket when no data are pending, or to write on it when its output buffer is full, will not block; it will instead return -1 and cause errno to be set to EWOULDBLOCK.
int watchSocket(int fd)
Turns on the \"linger\" and \"keepalive\" options for the socket identified by fd. See socket(2) for details. Returns 0 on success, -1 on any failure.
void closeOnExec(int fd)
Ensures that fd will NOT be open in any child process fork()ed from the invoking process. Has no effect on a VxWorks platform.
The functions in this section offer platform-independent capabilities for reporting on processing exceptions.
The underlying mechanism for ICI's exception reporting is a pair of functions that record error messages in a privately managed pool of static memory. These functions -- postErrmsg() and postSysErrmsg() -- are designed to return very rapidly with no possibility of failing, themselves. Nonetheless they are not safe to call from an interrupt service routing (ISR). Although each merely copies its text to the next available location in the error message memory pool, that pool is protected by a mutex; multiple processes might be queued up to take that mutex, so the total time to execute the function is non-deterministic.
Built on top of postErrmsg() and postSysErrmsg() are the putErrmsg() and putSysErrmsg() functions, which may take longer to return. Each one simply calls the corresponding \"post\" function but then calls the writeErrmsgMemos() function, which calls writeMemo() to print (or otherwise deliver) each message currently posted to the pool and then destroys all of those posted messages, emptying the pool.
Recommended general policy on using the ICI exception reporting functions (which the functions in the ION distribution libraries are supposed to adhere to) is as follows:
In the implementation of any ION library function or any ION\n task's top-level driver function, any condition that prevents\n the function from continuing execution toward producing the\n effect it is designed to produce is considered an \"error\".\n\n Detection of an error should result in the printing of an\n error message and, normally, the immediate return of whatever\n return value is used to indicate the failure of the function\n in which the error was detected. By convention this value\n is usually -1, but both zero and NULL are appropriate\n failure indications under some circumstances such as object\n creation.\n\n The CHKERR, CHKZERO, CHKNULL, and CHKVOID macros are used to\n implement this behavior in a standard and lexically terse\n manner. Use of these macros offers an additional feature:\n for debugging purposes, they can easily be configured to\n call sm_Abort() to terminate immediately with a core dump\n instead of returning a error indication. This option is\n enabled by setting the compiler parameter CORE_FILE_NEEDED\n to 1 at compilation time.\n\n In the absence of either any error, the function returns a\n value that indicates nominal completion. By convention this\n value is usually zero, but under some circumstances other\n values (such as pointers or addresses) are appropriate\n indications of nominal completion. Any additional information\n produced by the function, such as an indication of \"success\",\n is usually returned as the value of a reference argument.\n [Note, though, that database management functions and the\n SDR hash table management functions deviate from this rule:\n most return 0 to indicate nominal completion but functional\n failure (e.g., duplicate key or object not found) and return\n 1 to indicate functional success.]\n\n So when returning a value that indicates nominal completion\n of the function -- even if the result might be interpreted\n as a failure at a higher level (e.g., an object identified\n by a given string is not found, through no failure of the\n search function) -- do NOT invoke putErrmsg().\n\n Use putErrmsg() and putSysErrmsg() only when functions are\n unable to proceed to nominal completion. Use writeMemo()\n or writeMemoNote() if you just want to log a message.\n\n Whenever returning a value that indicates an error:\n\n If the failure is due to the failure of a system call\n or some other non-ION function, assume that errno\n has already been set by the function at the lowest\n layer of the call stack; use putSysErrmsg (or\n postSysErrmsg if in a hurry) to describe the nature\n of the activity that failed. The text of the error\n message should normally start with a capital letter\n and should NOT end with a period.\n\n Otherwise -- i.e., the failure is due to a condition\n that was detected within ION -- use putErrmsg (or\n postErrmg if pressed for time) to describe the nature\n of the failure condition. This will aid in tracing\n the failure through the function stack in which the\n failure was detected. The text of the error message\n should normally start with a capital letter and should\n end with a period.\n\n When a failure in a called function is reported to \"driver\"\n code in an application program, before continuing or exiting\n use writeErrmsgMemos() to empty the message pool and print a\n simple stack trace identifying the failure.\nchar *system_error_msg( )
Returns a brief text string describing the current system error, as identified by the current value of errno.
void setLogger(Logger usersLoggerName)
Sets the user function to be used for writing messages to a user-defined \"log\" medium. The logger function's calling sequence must match the following prototype:
void usersLoggerName(char *msg);\nThe default Logger function simply writes the message to standard output.
void writeMemo(char *msg)
Writes one log message, using the currently defined message logging function.
void writeMemoNote(char *msg, char *note)
Writes a log message like writeMemo(), accompanied by the user-supplied context-specific text in note.
void writeErrMemo(char *msg)
Writes a log message like writeMemo(), accompanied by text describing the current system error.
char *itoa(int value)
Returns a string representation of the signed integer in value, nominally for immediate use as an argument to putErrmsg(). [Note that the string is constructed in a static buffer; this function is not thread-safe.]
char *utoa(unsigned int value)
Returns a string representation of the unsigned integer in value, nominally for immediate use as an argument to putErrmsg(). [Note that the string is constructed in a static buffer; this function is not thread-safe.]
void postErrmsg(char *text, char *argument)
Constructs an error message noting the name of the source file containing the line at which this function was called, the line number, the text of the message, and -- if not NULL -- a single textual argument that can be used to give more specific information about the nature of the reported failure (such as the value of one of the arguments to the failed function). The error message is appended to the list of messages in a privately managed pool of static memory, ERRMSGS_BUFSIZE bytes in length.
If text is NULL or is a string of zero length or begins with a newline character (i.e., *text == '\\0' or '\\n'), the function returns immediately and no error message is recorded.
The errmsgs pool is designed to be large enough to contain error messages from all levels of the calling stack at the time that an error is encountered. If the remaining unused space in the pool is less than the size of the new error message, however, the error message is silently omitted. In this case, provided at least two bytes of unused space remain in the pool, a message comprising a single newline character is appended to the list to indicate that a message was omitted due to excessive length.
void postSysErrmsg(char *text, char *arg)
Like postErrmsg() except that the error message constructed by the function additionally contains text describing the current system error. text is truncated as necessary to assure that the sum of its length and that of the description of the current system error does not exceed 1021 bytes.
int getErrmsg(char *buffer)
Copies the oldest error message in the message pool into buffer and removes that message from the pool, making room for new messages. Returns zero if the message pool cannot be locked for update or there are no more messages in the pool; otherwise returns the length of the message copied into buffer. Note that, for safety, the size of buffer should be ERRMSGS_BUFSIZE.
Note that a returned error message comprising only a single newline character always signifies an error message that was silently omitted because there wasn't enough space left on the message pool to contain it.
void writeErrmsgMemos( )
Calls getErrmsg() repeatedly until the message pool is empty, using writeMemo() to log all the messages in the pool. Messages that were omitted due to excessive length are indicated by logged lines of the form \"[message omitted due to excessive length]\".
void putErrmsg(char *text, char *argument)
The putErrmsg() function merely calls postErrmsg() and then writeErrmsgMemos().
void putSysErrmsg(char *text, char *arg)
The putSysErrmsg() function merely calls postSysErrmsg() and then writeErrmsgMemos().
void discardErrmsgs( )
Calls getErrmsg() repeatedly until the message pool is empty, discarding all of the messages.
void printStackTrace( )
On Linux machines only, uses writeMemo() to print a trace of the process's current execution stack, starting with the lowest level of the stack and proceeding to the main() function of the executable.
Note that (a) printStackTrace() is only implemented for Linux platforms at this time; (b) symbolic names of functions can only be printed if the -rdynamic flag was enabled when the executable was linked; (c) only the names of non-static functions will appear in the stack trace.
For more complete information about the state of the executable at the time the stack trace snapshot was taken, use the Linux addr2line tool. To do this, cd into a directory in which the executable file resides (such as /opt/bin) and submit an addr2line command as follows:
addr2line -e _name\\_of\\_executable_ _stack\\_frame\\_address_\nwhere both name_of_executable and stack_frame_address are taken from one of the lines of the printed stack trace. addr2line will print the source file name and line number for that stack frame.
The functions in this section offer platform-independent capabilities for recording \"watch\" characters indicating the occurrence of protocol events. See bprc(5), ltprc(5), cfdprc(5), etc. for details of the watch character production options provided by the protocol packages.
void setWatcher(Watcher usersWatcherName)
Sets the user function to be used for recording watch characters to a user-defined \"watch\" medium. The watcher function's calling sequence must match the following prototype:
void usersWatcherName(char token);\nThe default Watcher function simply writes the token to standard output.
void iwatch(char token)
Records one \"watch\" character, using the currently defined watch character recording function.
The functions in this section encode and decode SDNVs, portable variable-length numeric variables that expand to whatever size is necessary to contain the values they contain. SDNVs are used extensively in the BP and LTP libraries.
void encodeSdnv(Sdnv *sdnvBuffer, uvast value)
Determines the number of octets of SDNV text needed to contain the value, places that number in the length field of the SDNV buffer, and encodes the value in SDNV format into the first length octets of the text field of the SDNV buffer.
int decodeSdnv(uvast *value, unsigned char *sdnvText)
Determines the length of the SDNV located at sdnvText and returns this number after extracting the SDNV's value from those octets and storing it in value. Returns 0 if the encoded number value will not fit into an unsigned vast integer.
The functions in this section perform simple arithmetic operations on unsigned Scalar objects -- structures encapsulating large positive integers in a machine-independent way. Each Scalar comprises two integers, a count of units [ranging from 0 to (2^30 - 1), i.e., up to 1 gig] and a count of gigs [ranging from 0 to (2^31 -1)]. A Scalar can represent a numeric value up to 2 billion billions, i.e., 2 million trillions.
void loadScalar(Scalar *scalar, signed int value)
Sets the value of scalar to the absolute value of value.
void increaseScalar(Scalar *scalar, signed int value)
Adds to scalar the absolute value of value.
void reduceScalar(Scalar *scalar, signed int value)
Adds to scalar the absolute value of value.
void multiplyScalar(Scalar *scalar, signed int value)
Multiplies scalar by the absolute value of value.
void divideScalar(Scalar *scalar, signed int value)
Divides scalar by the absolute value of value.
void copyScalar(Scalar *to, Scalar *from)
Copies the value of from into to.
void addToScalar(Scalar *scalar, Scalar *increment)
Adds increment (a Scalar rather than a C integer) to scalar.
void subtractFromScalar(Scalar *scalar, Scalar *decrement)
Subtracts decrement (a Scalar rather than a C integer) from scalar.
int scalarIsValid(Scalar *scalar)
Returns 1 if the arithmetic performed on scalar has not resulted in overflow or underflow.
int scalarToSdnv(Sdnv *sdnv, Scalar *scalar)
If scalar points to a valid Scalar, stores the value of scalar in sdnv; otherwise sets the length of sdnv to zero.
int sdnvToScalar(Scalar *scalar, unsigned char *sdnvText)
If sdnvText points to a sequence of bytes that, when interpreted as the text of an Sdnv, has a value that can be represented in a 61-bit unsigned binary integer, then this function stores that value in scalar and returns the detected Sdnv length. Otherwise returns zero.
Note that Scalars and Sdnvs are both representations of potentially large unsigned integer values. Any Scalar can alternatively be represented as an Sdnv. However, it is possible for a valid Sdnv to be too large to represent in a Scalar.
The functions in this section provide platform-independent management of mutexes for synchronizing operations of threads or tasks in a common private address space.
int initResourceLock(ResourceLock *lock)
Establishes an inter-thread lock for use in locking some resource. Returns 0 if successful, -1 if not.
void killResourceLock(ResourceLock *lock)
Deletes the resource lock referred to by lock.
void lockResource(ResourceLock *lock)
Checks the state of lock. If the lock is already owned by a different thread, the call blocks until the other thread relinquishes the lock. If the lock is unowned, it is given to the current thread and the lock count is set to 1. If the lock is already owned by this thread, the lock count is incremented by 1.
void unlockResource(ResourceLock *lock)
If called by the current owner of lock, decrements lock's lock count by 1; if zero, relinquishes the lock so it may be taken by other threads. Care must be taken to make sure that one, and only one, unlockResource() call is issued for each lockResource() call issued on a given resource lock.
The functions in this section provide platform-independent management of IPC mechanisms for synchronizing operations of threads, tasks, or processes that may occupy different address spaces but share access to a common system (nominally, processor) memory.
NOTE that this is distinct from the VxWorks \"VxMP\" capability enabling tasks to share access to bus memory or dual-ported board memory from multiple processors. The \"platform\" system will support IPC devices that utilize this capability at some time in the future, but that support is not yet implemented.
int sm_ipc_init( )
Acquires and initializes shared-memory IPC management resources. Must be called before any other shared-memory IPC function is called. Returns 0 on success, -1 on any failure.
void sm_ipc_stop( )
Releases shared-memory IPC management resources, disabling the shared-memory IPC functions until sm_ipc_init() is called again.
int sm_GetUniqueKey( )
Some of the \"sm_\" (shared memory) functions described below associate new communication objects with key values that uniquely identify them, so that different processes can access them independently. Key values are typically defined as constants in application code. However, when a new communication object is required for which no specific need was anticipated in the application, the sm_GetUniqueKey() function can be invoked to obtain a new, arbitrary key value that is known not to be already in use.
sm_SemId sm_SemCreate(int key, int semType)
Creates a shared-memory semaphore that can be used to synchronize activity among tasks or processes residing in a common system memory but possibly multiple address spaces; returns a reference handle for that semaphore, or SM_SEM_NONE on any failure. If key refers to an existing semaphore, returns the handle of that semaphore. If key is the constant value SM_NO_KEY, automatically obtains an unused key. On VxWorks platforms, semType determines the order in which the semaphore is given to multiple tasks that attempt to take it while it is already taken: if set to SM_SEM_PRIORITY then the semaphore is given to tasks in task priority sequence (i.e., the highest-priority task waiting for it receives it when it is released), while otherwise (SM_SEM_FIFO) the semaphore is given to tasks in the order in which they attempted to take it. On all other platforms, only SM_SEM_FIFO behavior is supported and semType is ignored.
int sm_SemTake(sm_SemId semId)
Blocks until the indicated semaphore is no longer taken by any other task or process, then takes it. Return 0 on success, -1 on any error.
void sm_SemGive(sm_SemId semId)
Gives the indicated semaphore, so that another task or process can take it.
void sm_SemEnd(sm_SemId semId)
This function is used to pass a termination signal to whatever task is currently blocked on taking the indicated semaphore, if any. It sets to 1 the \"ended\" flag associated with this semaphore, so that a test for sm_SemEnded() will return 1, and it gives the semaphore so that the blocked task will have an opportunity to test that flag.
int sm_SemEnded(sm_SemId semId)
This function returns 1 if the \"ended\" flag associated with the indicated semaphore has been set to 1; returns zero otherwise. When the function returns 1 it also gives the semaphore so that any other tasks that might be pended on the same semaphore are also given an opportunity to test it and discover that it has been ended.
void sm_SemUnend(sm_SemId semId)
This function is used to reset an ended semaphore, so that a restarted subsystem can reuse that semaphore rather than delete it and allocate a new one.
int sm_SemUnwedge(sm_SemId semId, int timeoutSeconds)
Used to release semaphores that have been taken but never released, possibly because the tasks or processes that took them crashed before releasing them. Attempts to take the semaphore; if this attempt does not succeed within timeoutSeconds seconds (providing time for normal processing to be completed, in the event that the semaphore is legitimately and temporarily locked by some task), the semaphore is assumed to be wedged. In any case, the semaphore is then released. Returns 0 on success, -1 on any error.
void sm_SemDelete(sm_SemId semId)
Destroys the indicated semaphore.
sm_SemId sm_GetTaskSemaphore(int taskId)
Returns the ID of the semaphore that is dedicated to the private use of the indicated task, or SM_SEM_NONE on any error.
This function implements the concept that for each task there can always be one dedicated semaphore, which the task can always use for its own purposes, whose key value may be known a priori because the key of the semaphore is based on the task's ID. The design of the function rests on the assumption that each task's ID, whether a VxWorks task ID or a Unix process ID, maps to a number that is out of the range of all possible key values that are arbitrarily produced by sm_GetUniqueKey(). For VxWorks, we assume this to be true because task ID is a pointer to task state in memory which we assume not to exceed 2GB; the unique key counter starts at 2GB. For Unix, we assume this to be true because process ID is an index into a process table whose size is less than 64K; unique keys are formed by shifting process ID left 16 bits and adding the value of an incremented counter which is always greater than zero.
int sm_ShmAttach(int key, int size, char **shmPtr, int *id)
Attaches to a segment of memory to which tasks or processes residing in a common system memory, but possibly multiple address spaces, all have access.
This function registers the invoking task or process as a user of the shared memory segment identified by key. If key is the constant value SM_NO_KEY, automatically sets key to some unused key value. If a shared memory segment identified by key already exists, then size may be zero and the value of *shmPtr is ignored. Otherwise the size of the shared memory segment must be provided in size and a new shared memory segment is created in a manner that is dependent on *shmPtr: if *shmPtr is NULL then size bytes of shared memory are dynamically acquired, allocated, and assigned to the newly created shared memory segment; otherwise the memory located at shmPtr is assumed to have been pre-allocated and is merely assigned to the newly created shared memory segment.
On success, stores the unique shared memory ID of the segment in *id for possible future destruction, stores a pointer to the segment's assigned memory in *shmPtr, and returns 1 (if the segment is newly created) or 0 (otherwise). Returns -1 on any error.
void sm_ShmDetach(char *shmPtr)
Unregisters the invoking task or process as a user of the shared memory starting at shmPtr.
void sm_ShmDestroy(int id)
Destroys the shared memory segment identified by id, releasing any memory that was allocated when the segment was created.
int sm_TaskIdSelf( )
Returns the unique identifying number of the invoking task or process.
int sm_TaskExists(int taskId)
Returns non-zero if a task or process identified by taskId is currently running on the local processor, zero otherwise.
void *sm_TaskVar(void **arg)
Posts or retrieves the value of the \"task variable\" belonging to the invoking task. Each task has access to a single task variable, initialized to NULL, that resides in the task's private state; this can be convenient for passing task-specific information to a signal handler, for example. If arg is non-NULL, then *arg is posted as the new value of the task's private task variable. In any case, the value of that task variable is returned.
void sm_TaskSuspend( )
Indefinitely suspends execution of the invoking task or process. Helpful if you want to freeze an application at the point at which an error is detected, then use a debugger to examine its state.
void sm_TaskDelay(int seconds)
Same as snooze(3).
void sm_TaskYield( )
Relinquishes CPU temporarily for use by other tasks.
int sm_TaskSpawn(char *name, char *arg1, char *arg2, char *arg3, char *arg4, char *arg5, char *arg6, char *arg7, char *arg8, char *arg9, char *arg10, int priority, int stackSize)
Spawns/forks a new task/process, passing it up to ten command-line arguments. name is the name of the function (VxWorks) or executable image (UNIX) to be executed in the new task/process.
For UNIX, name must be the name of some executable program in the $PATH of the invoking process.
For VxWorks, name must be the name of some function named in an application-defined private symbol table (if PRIVATE_SYMTAB is defined) or the system symbol table (otherwise). If PRIVATE_SYMTAB is defined, the application must provide a suitable adaptation of the symtab.c source file, which implements the private symbol table.
\"priority\" and \"stackSize\" are ignored under UNIX. Under VxWorks, if zero they default to the values in the application-defined private symbol table if provided, or otherwise to ICI_PRIORITY (nominally 100) and 32768 respectively.
Returns the task/process ID of the new task/process on success, or -1 on any error.
void sm_TaskKill(int taskId, int sigNbr)
Sends the indicated signal to the indicated task or process.
void sm_TaskDelete(int taskId)
Terminates the indicated task or process.
void sm_Abort()
Terminates the calling task or process. If not called while ION is in flight configuration, a stack trace is printed or a core file is written.
int pseudoshell(char *script)
Parses script into a command name and up to 10 arguments, then passes the command name and arguments to sm_TaskSpawn() for execution. The sm_TaskSpawn() function is invoked with priority and stack size both set to zero, causing default values (possibly from an application-defined private symbol table) to be used. Tokens in script are normally whitespace-delimited, but a token that is enclosed in single-quote characters (') may contain embedded whitespace and may contain escaped single-quote characters (\"\\'\"). On any parsing failure returns -1; otherwise returns the value returned by sm_TaskSpawn().
Compiling an application that uses \"platform\":
Just be sure to \"#include \"platform.h\"\" at the top of each source file that includes any platform function calls.
Linking/loading an application that uses \"platform\":
a. In a Solaris environment, link with these libraries:\n\n -lplatform -socket -nsl -posix4 -c\n\nb. In a Linux environment, simply link with platform:\n\n -lplatform\n\nc. In a VxWorks environment, use\n\n ld 1, 0, \"libplatform.o\"\n\n to load platform on the target before loading applications.\ngettimeofday(3C)
"},{"location":"man/ici/psm/","title":"NAME","text":"psm - Personal Space Management
"},{"location":"man/ici/psm/#synopsis","title":"SYNOPSIS","text":"#include \"psm.h\"\n\ntypedef enum { Okay, Redundant, Refused } PsmMgtOutcome;\ntypedef unsigned long PsmAddress;\ntypedef struct psm_str\n{\n char *space;\n int freeNeeded;\n struct psm_str *trace;\n int traceArea[3];\n} PsmView, *PsmPartition;\n\n[see description for available functions]\nPSM is a library of functions that support personal space management, that is, user management of an application-configured memory partition. PSM is designed to be faster and more efficient than malloc/free (for details, see the DETAILED DESCRIPTION below), but more importantly it provides a memory management abstraction that insulates applications from differences in the management of private versus shared memory.
PSM is often used to manage shared memory partitions. On most operating systems, separate tasks that connect to a common shared memory partition are given the same base address with which to access the partition. On some systems (such as Solaris) this is not necessarily the case; an absolute address within such a shared partition will be mapped to different pointer values in different tasks. If a pointer value is stored within shared memory and used without conversion by multiple tasks, segment violations will occur.
PSM gets around this problem by providing functions for translating between local pointer values and relative addresses within the shared memory partition. For complete portability, applications which store addresses in shared memory should store these addresses as PSM relative addresses and convert them to local pointer values before using them. The PsmAddress data type is provided for this purpose, along with the conversion functions psa() and psp().
int psm_manage(char *start, unsigned int length, char *name, PsmPartition *partitionPointer, PsmMgtOutcome *outcome)
Puts the length bytes of memory at start under PSM management, associating this memory partition with the identifying string name (which is required and which can have a maximum string length of 31). PSM can manage any contiguous range of addresses to which the application has access, typically a block of heap memory returned by a malloc call.
Every other PSM API function must be passed a pointer to a local \"partition\" state structure characterizing the PSM-managed memory to which the function is to be applied. The partition state structure itself may be pre-allocated in static or local (or shared) memory by the application, in which case a pointer to that structure must be passed to psm_manage() as the value of *partitionPointer; if *partitionPointer is null, psm_manage() will use malloc() to allocate this structure dynamically from local memory and will store a pointer to the structure in *partitionPointer.
psm_manage() formats the managed memory as necessary and returns -1 on any error, 0 otherwise. The outcome to the attempt to manage memory is placed in outcome. An outcome of Redundant means that the memory at start is already under PSM management with the same name and size. An outcome of Refused means that PSM was unable to put the memory at start under PSM management as directed; a diagnostic message was posted to the message pool (see discussion of putErrmsg() in platform(3)).
char *psm_name(PsmPartition partition)
Returns the name associated with the partition at the time it was put under management.
char *psm_space(PsmPartition partition)
Returns the address of the space managed by PSM for partition. This function is provided to enable the application to do an operating-system release (such as free()) of this memory when the managed partition is no longer needed. NOTE that calling psm_erase() or psm_unmanage() [or any other PSM function, for that matter] after releasing that space is virtually guaranteed to result in a segmentation fault or other seriously bad behavior.
void *psp(PsmPartition partition, PsmAddress address)
address is an offset within the space managed for the partition. Returns the conversion of that offset into a locally usable pointer.
PsmAddress psa(PsmPartition partition, void *pointer)
Returns the conversion of pointer into an offset within the space managed for the partition.
PsmAddress psm_malloc(PsmPartition partition, unsigned int length)
Allocates a block of memory from the \"large pool\" of the indicated partition. (See the DETAILED DESCRIPTION below.) length is the size of the block to allocate; the maximum size is 1/2 of the total address space (i.e., 2G for a 32-bit machine). Returns NULL if no free block could be found. The block returned is aligned on a doubleword boundary.
void psm_panic(PsmPartition partition)
Forces the \"large pool\" memory allocation algorithm to hunt laboriously for free blocks in buckets that may not contain any. This setting remains in force for the indicated partition until a subsequent psm_relax() call reverses it.
void psm_relax(PsmPartition partition)
Reverses psm_panic(). Lets the \"large pool\" memory allocation algorithm return NULL when no free block can be found easily.
PsmAddress psm_zalloc(PsmPartition partition, unsigned int length)
Allocates a block of memory from the \"small pool\" of the indicated partition, if possible; if the requested block size -- length -- is too large for small pool allocation (which is limited to 64 words, i.e., 256 bytes for a 32-bit machine), or if no small pool space is available and the size of the small pool cannot be increased, then allocates from the large pool instead. Small pool allocation is performed by an especially speedy algorithm, and minimum space is consumed in memory management overhead for small-pool blocks. Returns NULL if no free block could be found. The block returned is aligned on a word boundary.
void psm_free(PsmPartition partition, PsmAddress block)
Frees for subsequent re-allocation the indicated block of memory from the indicated partition. block may have been allocated by either psm_malloc() or psm_zalloc().
int psm_set_root(PsmPartition partition, PsmAddress root)
Sets the \"root\" word of the indicated partition (a word at a fixed, private location in the PSM bookkeeping data area) to the indicated value. This function is typically useful in a shared-memory environment, such as a VxWorks address space, in which a task wants to retrieve from the indicated partition some data that was inserted into the partition by some other task; the partition root word enables multiple tasks to navigate the same data in the same PSM partition in shared memory. The argument is normally a pointer to something like a linked list of the linked lists that populate the partition; in particular, it is likely to be an object catalog (see psm_add_catlg()). Returns 0 on success, -1 on any failure (e.g., the partition already has a root object, in which case psm_erase_root() must be called before psm_set_root()).
PsmAddress psm_get_root(PsmPartition partition)
Retrieves the current value of the root word of the indicated partition.
void psm_erase_root(PsmPartition partition)
Erases the current value of the root word of the indicated partition.
PsmAddress psm_add_catlg(PsmPartition partition)
Allocates space for an object catalog in the indicated partition and establishes the new catalog as the partition's root object. Returns 0 on success, -1 on any error (e.g., the partition already has some other root object).
int psm_catlg(PsmPartition partition, char *objName, PsmAddress objLocation)
Inserts an entry for the indicated object into the catalog that is the root object for this partition. The length of objName cannot exceed 32 bytes, and objName must be unique in the catalog. Returns 0 on success, -1 on any error.
int psm_uncatlg(PsmPartition partition, char *objName)
Removes the entry for the named object from the catalog that is the root object for this partition, if that object is found in the catalog. Returns 0 on success, -1 on any error.
int psm_locate(PsmPartition partition, char *objName, PsmAddress *objLocation, PsmAddress *entryElt)
Places in *objLocation the address associated with objName in the catalog that is the root object for this partition and places in *entryElt the address of the list element that points to this catalog entry. If name is not found in catalog, set *entryElt to zero. Returns 0 on success, -1 on any error.
void psm_usage(PsmPartition partition, PsmUsageSummary *summary)
Loads the indicated PsmUsageSummary structure with a snapshot of the indicated partition's usage status. PsmUsageSummary is defined by:
typedef struct {\n char partitionName[32];\n unsigned int partitionSize;\n unsigned int smallPoolSize;\n unsigned int smallPoolFreeBlockCount[SMALL_SIZES];\n unsigned int smallPoolFree;\n unsigned int smallPoolAllocated;\n unsigned int largePoolSize;\n unsigned int largePoolFreeBlockCount[LARGE_ORDERS];\n unsigned int largePoolFree;\n unsigned int largePoolAllocated;\n unsigned int unusedSize;\n} PsmUsageSummary;\nvoid psm_report(PsmUsageSummary *summary)
Sends to stdout the content of summary, a snapshot of a partition's usage status.
void psm_unmanage(PsmPartition partition)
Terminates local PSM management of the memory in partition and destroys the partition state structure *partition, but doesn't erase anything in the managed memory; PSM management can be re-established by a subsequent call to psm_manage().
void psm_erase(PsmPartition partition)
Unmanages the indicated partition and additionally discards all information in the managed memory, preventing re-management of the partition.
If PSM_TRACE is defined at the time the PSM source code is compiled, the system includes built-in support for simple tracing of memory usage: memory allocations are logged, and memory deallocations are matched to logged allocations, \"closing\" them. This enables memory leaks and some other kinds of memory access problems to be readily investigated.
int psm_start_trace(PsmPartition partition, int traceLogSize, char *traceLogAddress)
Begins an episode of PSM memory usage tracing. traceLogSize is the number of bytes of shared memory to use for trace activity logging; the frequency with which \"closed\" trace log events must be deleted will vary inversely with the amount of memory allocated for the trace log. traceLogAddress is normally NULL, causing the trace system to allocate traceLogSize bytes of shared memory dynamically for trace logging; if non-NULL, it must point to traceLogSize bytes of shared memory that have been pre-allocated by the application for this purpose. Returns 0 on success, -1 on any failure.
void psm_print_trace(PsmPartition partition, int verbose)
Prints a cumulative trace report and current usage report for partition. If verbose is zero, only exceptions (notably, trace log events that remain open -- potential memory leaks) are printed; otherwise all activity in the trace log is printed.
void psm_clear_trace(PsmPartition partition)
Deletes all closed trace log events from the log, freeing up memory for additional tracing.
void psm_stop_trace(PsmPartition partition)
Ends the current episode of PSM memory usage tracing. If the shared memory used for the trace log was allocated by psm_start_trace(), releases that shared memory.
For an example of the use of psm, see the file psmshell.c in the PSM source directory.
"},{"location":"man/ici/psm/#users-guide","title":"USER'S GUIDE","text":"Compiling a PSM application
Just be sure to \"#include \"psm.h\"\" at the top of each source file that includes any PSM function calls.
Linking/loading a PSM application
a. In a UNIX environment, link with libpsm.a.
b. In a VxWorks environment, use
ld 1, 0, \"libpsm.o\"\nto load PSM on the target before loading any PSM applications.
Typical usage:
a. Call psm_manage() to initiate management of the partition.
b. Call psm_malloc() (and/or psm_zalloc()) to allocate space in the partition; call psm_free() to release space for later re-allocation.
c. When psm_malloc() returns NULL and you're willing to wait a while for a more exhaustive free block search, call psm_panic() before retrying psm_malloc(). When you're no longer so desperate for space, call psm_relax().
d. To store a vital pointer in the single predefined location in the partition that PSM reserves for this purpose, call psm_set_root(); to retrieve that pointer, call psm_get_root().
e. To get a snapshot of the current configuration of the partition, call psm_usage(). To print this snapshot to stdout, call psm_report().
f. When you're done with the partition but want to leave it in its current state for future re-management (e.g., if the partition is in shared memory), call psm_unmanage(). If you're done with the partition forever, call psm_erase().
PSM supports user management of an application-configured memory partition. The partition is functionally divided into two pools of variable size: a \"small pool\" of low-overhead blocks aligned on 4-byte boundaries that can each contain up to 256 bytes of user data, and a \"large pool\" of high-overhead blocks aligned on 8-byte boundaries that can each contain up to 2GB of user data.
Space in the small pool is allocated in any one of 64 different block sizes; each possible block size is (4i + n) where i is a \"block list index\" from 1 through 64 and n is the length of the PSM overhead information per block [4 bytes on a 32-bit machine]. Given a user request for a block of size q where q is in the range 1 through 256 inclusive, we return the first block on the j'th small-pool free list where j = (q - 1) / 4. If there is no such block, we increase the size of the small pool [incrementing its upper limit by (4 * (j + 1)) + n], initialize the increase as a free block from list j, and return that block. No attempt is made to consolidate physically adjacent blocks when they are freed or to bisect large blocks to satisfy requests for small ones; if there is no free block of the requested size and the size of the small pool cannot be increased without encroaching on the large pool (or if the requested size exceeds 256), we attempt to allocate a large-pool block as described below. The differences between small-pool and large-pool blocks are transparent to the user, and small-pool and large-pool blocks can be freely intermixed in an application.
Small-pool blocks are allocated and freed very rapidly, and space overhead consumption is small, but capacity per block is limited and space assigned to small-pool blocks of a given size is never again available for any other purpose. The small pool is designed to satisfy requests for allocation of a stable overall population of small, volatile objects such as List and ListElt structures (see lyst(3)).
Space in the large pool is allocated from any one of 29 buckets, one for each power of 2 in the range 8 through 2G. The size of each block can be expressed as (n + 8i + m) where i is any integer in the range 1 through 256M, n is the size of the block's leading overhead area [8 bytes on a 32-bit machine], and m is the size of the block's trailing overhead area [also 8 bytes on a 32-bit machine]. Given a user request for a block of size q where q is in the range 1 through 2G inclusive, we first compute r as the smallest multiple of 8 that is greater than or equal to q. We then allocate the first block in bucket t such that 2 ** (t + 3) is the smallest power of 2 that is greater than r [or, if r is a power of 2, the first block in bucket t such that 2 ** (t + 3) = r]. That is, we try to allocate blocks of size 8 from bucket 0 [2**3 = 8], blocks of size 16 from bucket 1 [2**4 = 16], blocks of size 24 from bucket 2 [2**5 = 32, 32 > 24], blocks of size 32 from bucket 2 [2**5 = 32], and so on. t is the first bucket whose free blocks are ALL guaranteed to be at least as large as r; bucket t - 1 may also contain some blocks that are as large as r (e.g., bucket 1 will contain blocks of size 24 as well as blocks of size 16), but we would have to do a possibly time consuming sequential search through the free blocks in that bucket to find a match, because free blocks within a bucket are stored in no particular order.
If bucket t is empty, we allocate the first block from the first non-empty bucket corresponding to a greater power of two; if all eligible bucket are empty, we increase the size of the large pool [decrementing its lower limit by (r + 16)], initialize the increase as a free block and \"free\" it, and try again. If the size of the large pool cannot be increased without encroaching on the small pool, then if we are desperate we search sequentially through all blocks in bucket t - 1 (some of which may be of size r or greater) and allocate the first block that is big enough, if any. Otherwise, no block is returned.
Having selected a free block to allocate, we remove the allocated block from the free list, split off as a new free block all bytes in excess of (r + 16) bytes [unless that excess is too small to form a legal-size block], and return the remainder to the user. When a block is freed, it is automatically consolidated with the physically preceding block (if that block is free) and the physically subsequent block (if that block is free).
Large-pool blocks are allocated and freed quite rapidly; capacity is effectively unlimited; space overhead consumption is very high for extremely small objects but becomes an insignificant fraction of block size as block size increases. The large pool is designed to serve as a general-purpose heap with minimal fragmentation whose overhead is best justified when used to store relatively large, long-lived objects such as image packets.
The general goal of this memory allocation scheme is to satisfy memory management requests rapidly and yet minimize the chance of refusing a memory allocation request when adequate unused space exists but is inaccessible (because it is fragmentary or is buried as unused space in a block that is larger than necessary). The size of a small-pool block delivered to satisfy a request for q bytes will never exceed q + 3 (alignment), plus 4 bytes of overhead. The size of a large-pool block delivered to satisfy a request for q bytes will never exceed q + 7 (alignment) + 20 (the maximum excess that can't be split off as a separate free block), plus 16 bytes of overhead.
Neither the small pool nor the large pool ever decrease in size, but large-pool space previously allocated and freed is available for small-pool allocation requests if no small-pool space is available. Small-pool space previously allocated and freed cannot easily be reassigned to the large pool, though, because blocks in the large pool must be physically contiguous to support defragmentation. No such reassignment algorithm has yet been developed.
"},{"location":"man/ici/psm/#see-also","title":"SEE ALSO","text":"lyst(3)
"},{"location":"man/ici/psmshell/","title":"NAME","text":"psmshell - PSM memory management test shell
"},{"location":"man/ici/psmshell/#synopsis","title":"SYNOPSIS","text":"psmshell partition_size
"},{"location":"man/ici/psmshell/#description","title":"DESCRIPTION","text":"psmshell allocates a region of partition_size bytes of system memory, places it under PSM management, and offers the user an interactive \"shell\" for testing various PSM management functions.
psmshell prints a prompt string (\": \") to stdout, accepts a command from stdin, executes the command (possibly printing a diagnostic message), then prints another prompt string and so on.
The locations of objects allocated from the PSM-managed region of memory are referred to as \"cells\" in psmshell operations. That is, when an object is to be allocated, a cell number in the range 0-99 must be specified as the notional \"handle\" for that object, for use in future commands.
The following commands are supported:
h
The help command. Causes psmshell to print a summary of available commands. Same effect as the ? command.
?
Another help command. Causes psmshell to print a summary of available commands. Same effect as the h command.
m cell_nbr size
The malloc command. Allocates a large-pool object of the indicated size and associates that object with cell_nbr.
z cell_nbr size
The zalloc command. Allocates a small-pool object of the indicated size and associates that object with cell_nbr.
p cell_nbr
The print command. Prints the address (i.e., the offset within the managed block of memory) of the object associated with cell_nbr.
f cell_nbr
The free command. Frees the object associated with cell_nbr, returning the space formerly occupied by that object to the appropriate free block list.
u
The usage command. Prints a partition usage report, as per psm_report(3).
q
The quit command. Frees the allocated system memory in the managed block and terminates psmshell.
\"0\"
psmshell has terminated.
No configuration files are needed.
"},{"location":"man/ici/psmshell/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/psmshell/#diagnostics","title":"DIAGNOSTICS","text":"IPC initialization failed.
ION system error. Investigate, correct problem, and try again.
psmshell: can't allocate space; quitting.
Insufficient available system memory for selected partition size.
psmshell: can't allocate test variables; quitting.
Insufficient available system memory for selected partition size.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/psmshell/#see-also","title":"SEE ALSO","text":"psm(3)
"},{"location":"man/ici/psmwatch/","title":"NAME","text":"psmwatch - PSM memory partition activity monitor
"},{"location":"man/ici/psmwatch/#synopsis","title":"SYNOPSIS","text":"psmwatch shared_memory_key memory_size partition_name interval count [ verbose ]
"},{"location":"man/ici/psmwatch/#description","title":"DESCRIPTION","text":"For count interations, psmwatch sleeps interval seconds and then invokes the psm_print_trace() function (see psm(3)) to report on PSM dynamic memory management activity in the PSM-managed shared memory partition identified by shared_memory_key during that interval. If the optional verbose parameter is specified, the printed PSM activity trace will be verbose as described in psm(3).
To prevent confusion, the specified memory_size and partition_name are compared to those declared when this shared memory partition was initially managed; if they don't match, psmwatch immediately terminates.
If interval is zero, psmwatch merely prints a current usage summary for the indicated shared-memory partition and terminates.
psmwatch is helpful for detecting and diagnosing memory leaks. For debugging the ION protocol stack:
shared_memory_key
Normally \"65281\", but might be overridden by the value of wmKey in the .ionconfig file used to configure the node under study.
memory_size
As given by the value of wmKey in the .ionconfig file used to configure the node under study. If this value is not stated in the .ionconfig file, the default value is \"5000000\".
partition_name
Always \"ionwm\".
\"0\"
psmwatch has terminated.
No configuration files are needed.
"},{"location":"man/ici/psmwatch/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/psmwatch/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to psm.
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 start trace.
Insufficient ION working memory to contain trace information. Reinitialize ION with more memory.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/psmwatch/#see-also","title":"SEE ALSO","text":"psm(3), sdrwatch(1)
"},{"location":"man/ici/rfxclock/","title":"NAME","text":"rfxclock - ION daemon task for managing scheduled events
"},{"location":"man/ici/rfxclock/#synopsis","title":"SYNOPSIS","text":"rfxclock
"},{"location":"man/ici/rfxclock/#description","title":"DESCRIPTION","text":"rfxclock is a background \"daemon\" task that periodically applies scheduled changes in node connectivity and range to the ION node's database. It is spawned automatically by ionadmin in response to the 's' command that starts operation of the ION node infrastructure, and it is terminated by ionadmin in response to an 'x' (STOP) command.
Once per second, rfxclock takes the following action:
For each neighboring node that has been refusing custody of bundles sent to it to be forwarded to some destination node, to which no such bundle has been sent for at least N seconds (where N is twice the one-way light time from the local node to this neighbor), rfxclock turns on a probeIsDue flag authorizing transmission of the next such bundle in hopes of learning that this neighbor is now able to accept custody.
Then rfxclock purges the database of all range and contact information that is no longer applicable, based on the stop times of the records.
Finally, rfxclock applies to the database all range and contact information that is currently applicable, i.e., those records whose start times are before the current time and whose stop times are in the future.
"},{"location":"man/ici/rfxclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
rfxclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ionadmin to restart rfxclock.
\"1\"
rfxclock was unable to attach to the local ION node, probably because ionadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/ici/rfxclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/rfxclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
rfxclock can't attach to ION.
ionadmin has not yet initialized the ION database.
Can't apply ranges.
An unrecoverable database error was encountered. rfxclock terminates.
Can't apply contacts.
An unrecoverable database error was encountered. rfxclock terminates.
Can't purge ranges.
An unrecoverable database error was encountered. rfxclock terminates.
Can't purge contacts.
An unrecoverable database error was encountered. rfxclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/rfxclock/#see-also","title":"SEE ALSO","text":"ionadmin(1)
"},{"location":"man/ici/sdr/","title":"NAME","text":"sdr - Simple Data Recorder library
"},{"location":"man/ici/sdr/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\n[see below for available functions]\nSDR is a library of functions that support the use of an abstract data recording device called an \"SDR\" (\"simple data recorder\") for persistent storage of data. The SDR abstraction insulates software not only from the specific characteristics of any single data storage device but also from some kinds of persistent data storage and retrieval chores. The underlying principle is that an SDR provides standardized support for user data organization at object granularity, with direct access to persistent user data objects, rather than supporting user data organization only at \"file\" granularity and requiring the user to implement access to the data objects accreted within those files.
The SDR library is designed to provide some of the same kinds of directory services as a file system together with support for complex data structures that provide more operational flexibility than files. (As an example of this flexibility, consider how much easier and faster it is to delete a given element from the middle of a linked list than it is to delete a range of bytes from the middle of a text file.) The intent is to enable the software developer to take maximum advantage of the high speed and direct byte addressability of a non-volatile flat address space in the management of persistent data. The SDR equivalent of a \"record\" of data is simply a block of nominally persistent memory allocated from this address space. The SDR equivalent of a \"file\" is a collection object. Like files, collections can have names, can be located by name within persistent storage, and can impose structure on the data items they encompass. But, as discussed later, SDR collection objects can impose structures other than the strict FIFO accretion of records or bytes that characterizes a file.
The notional data recorder managed by the SDR library takes the form of a single array of randomly accessible, contiguous, nominally persistent memory locations called a heap. Physically, the heap may be implemented as a region of shared memory, as a single file of predefined size, or both -- that is, the heap may be a region of shared memory that is automatically mirrored in a file.
SDR services that manage SDR data are provided in several layers, each of which relies on the services implemented at lower levels:
At the highest level, a cataloguing service enables retrieval of persistent objects by name.
Services that manage three types of persistent data collections are provided for use both by applications and by the cataloguing service: linked lists, self-delimiting tables (which function as arrays that remember their own dimensions), and self-delimiting strings (short character arrays that remember their lengths, for speedier retrieval).
Basic SDR heap space management services, analogous to malloc() and free(), enable the creation and destruction of objects of arbitrary type.
Farther down the service stack are memcpy-like low-level functions for reading from and writing to the heap.
Protection of SDR data integrity across a series of reads and writes is provided by a transaction mechanism.
SDR persistent data are referenced in application code by Object values and Address values, both of which are simply displacements (offsets) within SDR address space. The difference between the two is that an Object is always the address of a block of heap space returned by some call to sdr_malloc(), while an Address can refer to any byte in the address space. That is, an Address is the SDR functional equivalent of a C pointer in DRAM, and some Addresses point to Objects.
Before using SDR services, the services must be loaded to the target machine and initialized by invoking the sdr_initialize() function and the management profiles of one or more SDR's must be loaded by invoking the sdr_load_profile() function. These steps are normally performed only once, at application load time.
An application gains access to an SDR by passing the name of the SDR to the sdr_start_using() function, which returns an Sdr pointer. Most other SDR library functions take an Sdr pointer as first argument.
All writing to an SDR heap must occur during a transaction that was initiated by the task issuing the write. Transactions are single-threaded; if task B wants to start a transaction while a transaction begun by task A is still in progress, it must wait until A's transaction is either ended or cancelled. A transaction is begun by calling sdr_begin_xn(). The current transaction is normally ended by calling the sdr_end_xn() function, which returns an error return code value in the event that any serious SDR-related processing error was encountered in the course of the transaction. Transactions may safely be nested, provided that every level of transaction activity that is begun is properly ended.
The current transaction may instead be cancelled by calling sdr_cancel_xn(), which is normally used to indicate that some sort of serious SDR-related processing error has been encountered. Canceling a transaction reverses all SDR update activity performed up to that point within the scope of the transaction -- and, if the canceled transaction is an inner, nested transaction, all SDR update activity performed within the scope of every outer transaction encompassing that transaction and every other transaction nested within any of those outer transactions -- provided the SDR was configured for transaction reversibility. When an SDR is configured for reversibility, all heap write operations performed during a transaction are recorded in a log file that is retained until the end of the transaction. Each log file entry notes the location at which the write operation was performed, the length of data written, and the content of the overwritten heap bytes prior to the write operation. Canceling the transaction causes the log entries to be read and processed in reverse order, restoring all overwritten data. Ending the transaction, on the other hand, simply causes the log to be discarded.
If a log file exists at the time that the profile for an SDR is loaded (typically during application initialization), the transaction that was being logged is automatically canceled and reversed. This ensures that, for example, a power failure that occurs in the middle of a transaction will never wreck the SDR's data integrity: either all updates issued during a given transaction are reflected in the current dataspace content or none are.
As a further measure to protect SDR data integrity, an SDR may additionally be configured for object bounding. When an SDR is configured to be \"bounded\", every heap write operation is restricted to the extent of a single object allocated from heap space; that is, it's impossible to overwrite part of one object by writing beyond the end of another. To enable the library to enforce this mechanism, application code is prohibited from writing anywhere but within the extent of an object that either (a) was allocated from managed heap space during the same transaction (directly or indirectly via some collection management function) or (b) was staged -- identified as an update target -- during the same transaction (again, either directly or via some collection management function).
Note that both transaction reversibility and object bounding consume processing cycles and inhibit performance to some degree. Determining the right balance between operational safety and processing speed is left to the user.
Note also that, since SDR transactions are single-threaded, they can additionally be used as a general mechanism for simply implementing \"critical sections\" in software that is already using SDR for other purposes: the beginning of a transaction marks the start of code that can't be executed concurrently by multiple tasks. To support this use of the SDR transaction mechanism, the additional transaction termination function sdr_exit_xn() is provided. sdr_exit_xn() simply ends a transaction without either signaling an error or checking for errors. Like sdr_cancel_xn(), sdr_exit_xn() has no return value; unlike sdr_cancel_xn(), it assures that ending an inner, nested transaction does not cause the outer transaction to be aborted and backed out. But this capability must be used carefully: the protection of SDR data integrity requires that transactions which are ended by sdr_exit_xn() must not encompass any SDR update activity whatsoever.
The heap space management functions of the SDR library are adapted directly from the Personal Space Management (psm) function library. The manual page for psm(3) explains the algorithms used and the rationale behind them. The principal difference between PSM memory management and SDR heap management is that, for performance reasons, SDR reserves the \"small pool\" for its own use only; all user data space is allocated from the \"large pool\", via the sdr_malloc() function.
"},{"location":"man/ici/sdr/#return-values-and-error-handling","title":"RETURN VALUES AND ERROR HANDLING","text":"Whenever an SDR function call fails, a diagnostic message explaining the failure of the function is recorded in the error message pool managed by the \"platform\" system (see the discussion of putErrmsg() in platform(3)).
The failure of any function invoked in the course of an SDR transaction causes all subsequent SDR activity in that transaction to fail immediately. This can streamline SDR application code somewhat: it may not be necessary to check the return value of every SDR function call executed during a transaction. If the sdr_end_xn() call returns zero, all updates performed during the transaction must have succeeded.
"},{"location":"man/ici/sdr/#system-administration-functions","title":"SYSTEM ADMINISTRATION FUNCTIONS","text":"int sdr_initialize(int wmSize, char *wmPtr, int wmKey, char *wmName)
Initializes the SDR system. sdr_initialize() must be called once every time the computer on which the system runs is rebooted, before any call to any other SDR library function.
This function attaches to a pool of shared memory, managed by PSM (see psm(3), that enables SDR library operations. If the SDR system is to access a common pool of shared memory with one or more other systems, the key of that shared memory segment must be provided in wmKey and the PSM partition name associated with that memory segment must be provided in wmName; otherwise wmKey must be zero and wmName must be NULL, causing sdr_initialize() to assign default values. If a shared memory segment identified by the effective value of wmKey already exists, then wmSize may be zero and the value of wmPtr is ignored. Otherwise the size of the shared memory pool must be provided in wmSize and a new shared memory segment is created in a manner that is dependent on wmPtr: if wmPtr is NULL then wmSize bytes of shared memory are dynamically acquired, allocated, and assigned to the newly created shared memory segment; otherwise the memory located at wmPtr is assumed to have been pre-allocated and is merely assigned to the newly created shared memory segment.
sdr_initialize() also creates a semaphore to serialize access to the SDR system's private array of SDR profiles.
Returns 0 on success, -1 on any failure.
void sdr_wm_usage(PsmUsageSummary *summary)
Loads summary with a snapshot of the usage of the SDR system's private working memory. To print the snapshot, use psm_report(). (See psm(3).)
void sdr_shutdown( )
Ends all access to all SDRs (see sdr_stop_using()), detaches from the SDR system's working memory (releasing the memory if it was dynamically allocated by sdr_initialize()), and destroys the SDR system's private semaphore. After sdr_shutdown(), sdr_initialize() must be called again before any call to any other SDR library function.
int sdr_load_profile(char *name, int configFlags, long heapWords, int heapKey, int logSize, int logKey, char *pathName, char *restartCmd, unsigned int restartLatency)
Loads the profile for an SDR into the system's private list of SDR profiles. Although SDRs themselves are persistent, SDR profiles are not: in order for an application to access an SDR, sdr_load_profile() must have been called to load the profile of the SDR since the last invocation of sdr_initialize().
name is the name of the SDR, required for any subsequent sdr_start_using() call.
configFlags specifies the configuration of the SDR, the bitwise \"or\" of some combination of the following:
SDR_IN_DRAM
SDR dataspace is implemented as a region of shared memory.
SDR_IN_FILE
SDR dataspace is implemented as a file.
SDR_REVERSIBLE
SDR transactions are logged and are reversed if canceled.
SDR_BOUNDED
Heap updates are not allowed to cross object boundaries.
heapWords specifies the size of the heap in words; word size depends on machine architecture, i.e., a word is 4 bytes on a 32-bit machine, 8 bytes on a 64-bit machine. Note that each SDR prepends to the heap a \"map\" of predefined, fixed size. The total amount of space occupied by an SDR dataspace in memory and/or in a file is the sum of the size of the map plus the product of word size and heapWords.
heapKey is ignored if configFlags does not include SDR_IN_DRAM. It should normally be SM_NO_KEY, causing the shared memory region for the SDR dataspace to be allocated dynamically and shared using a dynamically selected shared memory key. If specified, heapKey must be a shared memory key identifying a pre-allocated region of shared memory whose length is equal to the total SDR dataspace size, shared via the indicated key.
logSize specifies the maximum size of the transaction log (in bytes) if and only if the log is to be written to memory rather than to a file; otherwise it must be zero. logKey is ignored if logSize is zero. It should normally be SM_NO_KEY, causing the shared memory region for the transaction log to be allocated dynamically and shared using a dynamically selected shared memory key. If specified, logKey must be a shared memory key identifying a pre-allocated region of shared memory whose length is equal to logSize, shared via the indicated key.
pathName is ignored if configFlags includes neither SDR_REVERSIBLE nor SDR_IN_FILE. It is the fully qualified name of the directory into which the SDR's log file and/or dataspace file will be written. The name of the log file (if any) will be \"<sdrname>.sdrlog\". The name of the dataspace file (if any) will be \"<sdrname>.sdr\"; this file will be automatically created and filled with zeros if it does not exist at the time the SDR's profile is loaded.
If a cleanup task must be run whenever a transaction is reversed, the command to execute this task must be provided in restartCmd and the number of seconds to wait for this task to finish before resuming operations must be provided in restartLatency. If restartCmd is NULL or restartLatency is zero then no cleanup task will be run upon transaction reversal.
Returns 0 on success, -1 on any error.
int sdr_reload_profile(char *name, int configFlags, long heapWords, int heapKey, int logSize, int logKey, char *pathName, char *restartCmd, unsigned int restartLatency)
For use when the state of an SDR is thought to be inconsistent, perhaps due to crash of a program that had a transaction open. Unloads the profile for the SDR, forcing the reversal of any transaction that is currently in progress when the SDR's profile is re-loaded. Then calls sdr_load_profile() to re-load the profile for the SDR. Same return values as sdr_load_profile.
Sdr sdr_start_using(char *name)
Locates SDR profile by name and returns a handle that can be used for all functions that operate on that SDR. On any failure, returns NULL.
char *sdr_name(Sdr sdr)
Returns the name of the sdr.
long sdr_heap_size(Sdr sdr)
Returns the total size of the SDR heap, in bytes.
void sdr_stop_using(Sdr sdr)
Terminates access to the SDR via this handle. Other users of the SDR are not affected. Frees the Sdr object.
void sdr_abort(Sdr sdr)
Terminates the task. In flight configuration, also terminates all use of the SDR system by all tasks.
void sdr_destroy(Sdr sdr)
Ends all access to this SDR, unloads the SDR's profile, and erases the SDR from memory and file system.
int sdr_begin_xn(Sdr sdr)
Initiates a transaction. Returns 1 on success, 0 on any failure. Note that transactions are single-threaded; any task that calls sdr_begin_xn() is suspended until all previously requested transactions have been ended or canceled.
int sdr_in_xn(Sdr sdr)
Returns 1 if called in the course of a transaction, 0 otherwise.
void sdr_exit_xn(Sdr sdr)
Simply abandons the current transaction, ceasing the calling task's lock on ION. Must not be used if any dataspace modifications were performed during the transaction; sdr_end_xn() must be called instead, to commit those modifications.
void sdr_cancel_xn(Sdr sdr)
Cancels the current transaction. If reversibility is enabled for the SDR, canceling a transaction reverses all heap modifications performed during that transaction.
int sdr_end_xn(Sdr sdr)
Ends the current transaction. Returns 0 if the transaction completed without any error; returns -1 if any operation performed in the course of the transaction failed, in which case the transaction was automatically canceled.
void sdr_read(Sdr sdr, char *into, Address from, int length)
Copies length characters at from (a location in the indicated SDR) to the memory location given by into. The data are copied from the shared memory region in which the SDR resides, if any; otherwise they are read from the file in which the SDR resides.
void sdr_peek(sdr, variable, from)
sdr_peek() is a macro that uses sdr_read() to load variable from the indicated address in the SDR dataspace; the size of variable is used as the number of bytes to copy.
void sdr_write(Sdr sdr, Address into, char *from, int length)
Copies length characters at from (a location in memory) to the SDR heap location given by into. Can only be performed during a transaction, and if the SDR is configured for object bounding then heap locations into through (into + (length - 1)) must be within the extent of some object that was either allocated or staged within the same transaction. The data are copied both to the shared memory region in which the SDR resides, if any, and also to the file in which the SDR resides, if any.
void sdr_poke(sdr, into, variable)
sdr_poke() is a macro that uses sdr_write() to store variable at the indicated address in the SDR dataspace; the size of variable is used as the number of bytes to copy.
char *sdr_pointer(Sdr sdr, Address address)
Returns a pointer to the indicated location in the heap - a \"heap pointer\" - or NULL if the indicated address is invalid. NOTE that this function cannot be used if the SDR does not reside in a shared memory region.
Providing an alternative to using sdr_read() to retrieve objects into local memory, sdr_pointer() can help make SDR-based applications run very quickly, but it must be used WITH GREAT CAUTION! Never use a direct pointer into the heap when not within a transaction, because you will have no assurance at any time that the object pointed to by that pointer has not changed (or is even still there). And NEVER de-reference a heap pointer in order to write directly into the heap: this makes transaction reversal impossible. Whenever writing to the SDR, always use sdr_write().
Address sdr_address(Sdr sdr, char *pointer)
Returns the address within the SDR heap of the indicated location, which must be (or be derived from) a heap pointer as returned by sdr_pointer(). Returns zero if the indicated location is not greater than the start of the heap mirror. NOTE that this function cannot be used if the SDR does not reside in a shared memory region.
void sdr_get(sdr, variable, heap_pointer)
sdr_get() is a macro that uses sdr_read() to load variable from the SDR address given by heap_pointer; heap_pointer must be (or be derived from) a heap pointer as returned by sdr_pointer(). The size of variable is used as the number of bytes to copy.
void sdr_set(sdr, heap_pointer, variable)
sdr_set() is a macro that uses sdr_write() to store variable at the SDR address given by heap_pointer; heap_pointer must be (or be derived from) a heap pointer as returned by sdr_pointer(). The size of variable is used as the number of bytes to copy.
Object sdr_malloc(Sdr sdr, unsigned long size)
Allocates a block of space from the of the indicated SDR's heap. size is the size of the block to allocate; the maximum size is 1/2 of the maximum address space size (i.e., 2G for a 32-bit machine). Returns block address if successful, zero if block could not be allocated.
Object sdr_insert(Sdr sdr, char *from, unsigned long size)
Uses sdr_malloc() to obtain a block of space of size size and, if this allocation is successful, uses sdr_write() to copy size bytes of data from memory at from into the newly allocated block. Returns block address if successful, zero if block could not be allocated.
Object sdr_stow(sdr, variable)
sdr_stow() is a macro that uses sdr_insert() to insert a copy of variable into the dataspace. The size of variable is used as the number of bytes to copy.
int sdr_object_length(Sdr sdr, Object object)
Returns the number of bytes of heap space allocated to the application data at object.
void sdr_free(Sdr sdr, Object object)
Frees for subsequent re-allocation the heap space occupied by object.
void sdr_stage(Sdr sdr, char *into, Object from, int length)
Like sdr_read(), this function will copy length characters at from (a location in the heap of the indicated SDR) to the memory location given by into. Unlike sdr_get(), sdr_stage() requires that from be the address of some allocated object, not just any location within the heap. sdr_stage(), when called from within a transaction, notifies the SDR library that the indicated object may be updated later in the transaction; this enables the library to retrieve the object's size for later reference in validating attempts to write into some location within the object. If length is zero, the object's size is privately retrieved by SDR but none of the object's content is copied into memory.
long sdr_unused(Sdr sdr)
Returns number of bytes of heap space not yet allocated to either the large or small objects pool.
void sdr_usage(Sdr sdr, SdrUsageSummary *summary)
Loads the indicated SdrUsageSummary structure with a snapshot of the SDR's usage status. SdrUsageSummary is defined by:
typedef struct\n{\n char sdrName[MAX_SDR_NAME + 1];\n unsigned int dsSize;\n unsigned int smallPoolSize;\n unsigned int smallPoolFreeBlockCount[SMALL_SIZES];\n unsigned int smallPoolFree;\n unsigned int smallPoolAllocated;\n unsigned int largePoolSize;\n unsigned int largePoolFreeBlockCount[LARGE_ORDERS];\n unsigned int largePoolFree;\n unsigned int largePoolAllocated;\n unsigned int unusedSize;\n} SdrUsageSummary;\nvoid sdr_report(SdrUsageSummary *summary)
Sends to stdout a printed summary of the SDR's usage status.
int sdr_heap_depleted(Sdr sdr)
A Boolean function: returns 1 if the total available space in the SDR's heap (small pool free, large pool free, and unused) is less than 1/16 of the total size of the heap. Otherwise returns zero.
If SDR_TRACE is defined at the time the SDR source code is compiled, the system includes built-in support for simple tracing of SDR heap space usage: heap space allocations are logged, and heap space deallocations are matched to logged allocations, \"closing\" them. This enables heap space leaks and some other kinds of SDR heap access problems to be readily investigated.
int sdr_start_trace(Sdr sdr, int traceLogSize, char *traceLogAddress)
Begins an episode of SDR heap space usage tracing. traceLogSize is the number of bytes of shared memory to use for trace activity logging; the frequency with which \"closed\" trace log events must be deleted will vary inversely with the amount of memory allocated for the trace log. traceLogAddress is normally NULL, causing the trace system to allocate traceLogSize bytes of shared memory dynamically for trace logging; if non-NULL, it must point to traceLogSize bytes of shared memory that have been pre-allocated by the application for this purpose. Returns 0 on success, -1 on any failure.
void sdr_print_trace(Sdr sdr, int verbose)
Prints a cumulative trace report and current usage report for sdr. If verbose is zero, only exceptions (notably, trace log events that remain open -- potential SDR heap space leaks) are printed; otherwise all activity in the trace log is printed.
void sdr_clear_trace(Sdr sdr)
Deletes all closed trace log events from the log, freeing up memory for additional tracing.
void sdr_stop_trace(Sdr sdr)
Ends the current episode of SDR heap space usage tracing. If the shared memory used for the trace log was allocated by sdr_start_trace(), releases that shared memory.
The SDR catalogue functions are used to maintain the catalogue of the names, types, and addresses of objects within an SDR. The catalogue service includes functions for creating, deleting and finding catalogue entries and a function for navigating through catalogue entries sequentially.
void sdr_catlg(Sdr sdr, char *name, int type, Object object)
Associates object with name in the indicated SDR's catalogue and notes the type that was declared for this object. type is optional and has no significance other than that conferred on it by the application.
The SDR catalogue is flat, not hierarchical like a directory tree, and all names must be unique. The length of name is limited to 15 characters.
Object sdr_find(Sdr sdr, char *name, int *type)
Locates the Object associated with name in the indicated SDR's catalogue and returns its address; also reports the catalogued type of the object in *type if type is non-NULL. Returns zero if no object is currently catalogued under this name.
void sdr_uncatlg(Sdr sdr, char *name)
Dissociates from name whatever object in the indicated SDR's catalogue is currently catalogued under that name.
Object sdr_read_catlg(Sdr sdr, char *name, int *type, Object *object, Object previous_entry)
Used to navigate through catalogue entries sequentially. If previous_entry is zero, reads the first entry in the indicated SDR's catalogue; otherwise, reads the next catalogue entry following the one located at previous_entry. In either case, returns zero if no such catalogue entry exists; otherwise, copies that entry's name, type, and catalogued object address into name, *type, and *object, and then returns the address of the catalogue entry (which may be used as previous_entry in a subsequent call to sdr_read_catlg()).
Compiling an SDR application
Just be sure to \"#include \"sdr.h\"\" at the top of each source file that includes any SDR function calls.
For UNIX applications, link with \"-lsdr\".
Loading an SDR application (VxWorks)
ld < \"libsdr.o\"\nAfter the library has been loaded, you can begin loading SDR applications.
sdrlist(3), sdrstring(3), sdrtable(3)
"},{"location":"man/ici/sdr2file/","title":"NAME","text":"sdr2file - SDR data extraction test program
"},{"location":"man/ici/sdr2file/#synopsis","title":"SYNOPSIS","text":"sdr2file configFlags
"},{"location":"man/ici/sdr2file/#description","title":"DESCRIPTION","text":"sdr2file stress-tests SDR data extraction by retrieving and deleting all text file lines inserted into a test SDR data store named \"testsdr_configFlags_\" by the complementary test program file2sdr(1).
The operation of sdr2file echoes the cyclical operation of file2sdr: each linked list created by file2sdr is used to create in the current working directory a copy of file2sdr's original source text file. The name of each file written by sdr2file is file_copy_cycleNbr, where cycleNbr identifies the linked list from which the file's text lines were obtained.
sdr2file may catch up with the data ingestion activity of file2sdr, in which case it blocks (taking the file2sdr test semaphore) until the linked list it is currently draining is no longer empty.
"},{"location":"man/ici/sdr2file/#exit-status","title":"EXIT STATUS","text":"\"0\"
sdr2file has terminated.
No configuration files are needed.
"},{"location":"man/ici/sdr2file/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/sdr2file/#diagnostics","title":"DIAGNOSTICS","text":"Can't use sdr.
ION system error. Check for diagnostics in the ION log file ion.log.
Can't create semaphore.
ION system error. Check for diagnostics in the ION log file ion.log.
SDR transaction failed.
ION system error. Check for diagnostics in the ION log file ion.log.
Can't open output file
Operating system error. Check errtext, correct problem, and rerun.
can't write to output file
Operating system error. Check errtext, correct problem, and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/sdr2file/#see-also","title":"SEE ALSO","text":"file2sdr(1), sdr(3)
"},{"location":"man/ici/sdrhash/","title":"NAME","text":"sdrhash - Simple Data Recorder hash table management functions
"},{"location":"man/ici/sdrhash/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\nObject sdr_hash_create (Sdr sdr, int keyLength,\n int estNbrOfEntries,\n int meanSearchLength);\nint sdr_hash_insert (Sdr sdr, Object hash, char *key,\n Address value, Object *entry);\nint sdr_hash_delete_entry (Sdr sdr, Object entry);\nint sdr_hash_entry_value (Sdr sdr, Object hash, Object entry);\nint sdr_hash_retrieve (Sdr sdr, Object hash, char *key,\n Address *value, Object *entry);\nint sdr_hash_count (Sdr sdr, Object hash);\nint sdr_hash_revise (Sdr sdr, Object hash, char *key,\n Address value);\nint sdr_hash_remove (Sdr sdr, Object hash, char *key,\n Address *value);\nint sdr_hash_destroy (Sdr sdr, Object hash);\nThe SDR hash functions manage hash table objects in an SDR.
Hash tables associate values with keys. A value is always in the form of an SDR Address, nominally the address of some stored object identified by the associated key, but the actual significance of a value may be anything that fits into a long. A key is always an array of from 1 to 255 bytes, which may have any semantics at all.
Keys must be unique; no two distinct entries in an SDR hash table may have the same key. Any attempt to insert a duplicate entry in an SDR hash table will be rejected.
All keys must be of the same length, and that length must be declared at the time the hash table is created. Invoking a hash table function with a key that is shorter than the declared length will have unpredictable results.
An SDR hash table is an array of linked lists. The location of a given value in the hash table is automatically determined by computing a \"hash\" of the key, dividing the hash by the number of linked lists in the array, using the remainder as an index to the corresponding linked list, and then sequentially searching through the list entries until the entry with the matching key is found.
The number of linked lists in the array is automatically computed at the time the hash table is created, based on the estimated maximum number of entries you expect to store in the table and the mean linked list length (i.e., mean search time) you prefer. Increasing the maximum number of entries in the table and decreasing the mean linked list length both tend to increase the amount of SDR heap space occupied by the hash table.
Object sdr_hash_create(Sdr sdr, int keyLength, int estNbrOfEntries, int meanSearchLength)
Creates an SDR hash table. Returns the SDR address of the new hash table on success, zero on any error.
int sdr_hash_insert(Sdr sdr, Object hash, char *key, Address value, Object *entry)
Inserts an entry into the hash table identified by hash. On success, places the address of the new hash table entry in entry and returns zero. Returns -1 on any error.
int sdr_hash_delete_entry(Sdr sdr, Object entry)
Deletes the hash table entry identified by entry. Returns zero on success, -1 on any error.
Address sdr_hash_entry_value(Sdr sdr, Object hash, Object entry)
Returns the value of the hash table entry identified by entry.
int sdr_hash_retrieve(Sdr sdr, Object hash, char *key, Address *value, Object *entry)
Searches for the value associated with key in this hash table, storing it in value if found. If the entry matching key was found, places the address of the hash table entry in entry and returns 1. Returns zero if no such entry exists, -1 on any other failure.
int sdr_hash_count(Sdr sdr, Object hash)
Returns the number of entries in the hash table identified by hash.
int sdr_hash_revise(Sdr sdr, Object hash, char *key, Address value)
Searches for the hash table entry matching key in this hash table, replacing the associated value with value if found. Returns 1 if the entry matching key was found, zero if no such entry exists, -1 on any other failure.
int sdr_hash_remove(Sdr sdr, Object hash, char *key, Address *value)
Searches for the hash table entry matching key in this hash table; if the entry is found, stores its value in value, deletes the entry, and returns 1. Returns zero if no such entry exists, -1 on any other failure.
void sdr_hash_destroy(Sdr sdr, Object hash);
Destroys hash, destroying all entries in all linked lists of the array and destroying the hash table array structure itself. DO NOT use sdr_free() to destroy a hash table, as this would leave the hash table's content allocated yet unreferenced.
sdr(3), sdrlist(3), sdrtable(3)
"},{"location":"man/ici/sdrlist/","title":"NAME","text":"sdrlist - Simple Data Recorder list management functions
"},{"location":"man/ici/sdrlist/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\ntypedef int (*SdrListCompareFn)(Sdr sdr, Address eltData, void *argData);\ntypedef void (*SdrListDeleteFn)(Sdr sdr, Object elt, void *argument);\n\n[see description for available functions]\nThe SDR list management functions manage doubly-linked lists in managed SDR heap space. The functions manage two kinds of objects: lists and list elements. A list knows how many elements it contains and what its start and end elements are. An element knows what list it belongs to and the elements before and after it in the list. An element also knows its content, which is normally the SDR Address of some object in the SDR heap. A list may be sorted, which speeds the process of searching for a particular element.
Object sdr_list_create(Sdr sdr)
Creates a new list object in the SDR; the new list object initially contains no list elements. Returns the address of the new list, or zero on any error.
void sdr_list_destroy(Sdr sdr, Object list, SdrListDeleteFn fn, void *arg)
Destroys a list, freeing all elements of list. If fn is non-NULL, that function is called once for each freed element; when called, fn is passed the Address that is the element's data and the argument pointer passed to sdr_list_destroy().
Do not use sdr_free to destroy an SDR list, as this would leave the elements of the list allocated yet unreferenced.
int sdr_list_length(Sdr sdr, Object list)
Returns the number of elements in the list, or -1 on any error.
void sdr_list_user_data_set(Sdr sdr, Object list, Address userData)
Sets the \"user data\" word of list to userData. Note that userData is nominally an Address but can in fact be any value that occupies a single word. It is typically used to point to an SDR object that somehow characterizes the list as a whole, such as a name.
Address sdr_list_user_data(Sdr sdr, Object list)
Returns the value of the \"user data\" word of list, or zero on any error.
Object sdr_list_insert(Sdr sdr, Object list, Address data, SdrListCompareFn fn, void *dataBuffer)
Creates a new list element whose data value is data and inserts that element into the list. If fn is NULL, the new list element is simply appended to the list; otherwise, the new list element is inserted after the last element in the list whose data value is \"less than or equal to\" the data value of the new element (in dataBuffer) according to the collating sequence established by fn. Returns the address of the newly created element, or zero on any error.
Object sdr_list_insert_first(Sdr sdr, Object list, Address data)
Object sdr_list_insert_last(Sdr sdr, Object list, Address data)
Creates a new element and inserts it at the front/end of the list. This function should not be used to insert a new element into any ordered list; use sdr_list_insert() instead. Returns the address of the newly created list element on success, or zero on any error.
Object sdr_list_insert_before(Sdr sdr, Object elt, Address data)
Object sdr_list_insert_after(Sdr sdr, Object elt, Address data)
Creates a new element and inserts it before/after the specified list element. This function should not be used to insert a new element into any ordered list; use sdr_list_insert() instead. Returns the address of the newly created list element, or zero on any error.
void sdr_list_delete(Sdr sdr, Object elt, SdrListDeleteFn fn, void *arg)
Delete elt from the list it is in. If fn is non-NULL, that function will be called upon deletion of elt; when called, that function is passed the Address that is the list element's data value and the arg pointer passed to sdr_list_delete().
Object sdr_list_first(Sdr sdr, Object list)
Object sdr_list_last(Sdr sdr, Object list)
Returns the address of the first/last element of list, or zero on any error.
Object sdr_list_next(Sdr sdr, Object elt)
Object sdr_list_prev(Sdr sdr, Object elt)
Returns the address of the element following/preceding elt in that element's list, or zero on any error.
Object sdr_list_search(Sdr sdr, Object elt, int reverse, SdrListCompareFn fn, void *dataBuffer);
Search a list for an element whose data matches the data in dataBuffer, starting at the indicated initial list element. If the compare function is non-NULL, the list is assumed to be sorted in the order implied by that function and the function is automatically called once for each element of the list until it returns a value that is greater than or equal to zero (where zero indicates an exact match and a value greater than zero indicates that the list contains no matching element); each time compare is called it is passed the Address that is the element's data value and the dataBuffer value passed to sm_list_search(). If reverse is non-zero, then the list is searched in reverse order (starting at the indicated initial list element) and the search ends when compare returns a value that is less than or equal to zero. If compare is NULL, then the entire list is searched (in either forward or reverse order, as directed) until an element is located whose data value is equal to ((Address) dataBuffer). Returns the address of the matching element if one is found, 0 otherwise.
Object sdr_list_list(Sdr sdr, Object elt)
Returns the address of the list to which elt belongs, or 0 on any error.
Address sdr_list_data(Sdr sdr, Object elt)
Returns the Address that is the data value of elt, or 0 on any error.
Address sdr_list_data_set(Sdr sdr, Object elt, Address data)
Sets the data value for elt to data, replacing the original value. Returns the original data value for elt, or 0 on any error. The original data value for elt may or may not have been the address of an object in heap data space; even if it was, that object was NOT deleted.
Warning: changing the data value of an element of an ordered list may ruin the ordering of the list.
When inserting elements or searching a list, the user may optionally provide a compare function of the form:
int user_comp_name(Sdr sdr, Address eltData, void *dataBuffer);\nWhen provided, this function is automatically called by the sdrlist function being invoked; when the function is called it is passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, dataBuffer, which is nominally the address in local memory of some other item in the same format. The user-supplied function normally compares some key values of the two data items and returns 0 if they are equal, an integer less than 0 if eltData's key value is less than that of dataBuffer, and an integer greater than 0 if eltData's key value is greater than that of dataBuffer. These return values will produce a list in ascending order. If the user desires the list to be in descending order, the function must reverse the signs of these return values.
When deleting an element or destroying a list, the user may optionally provide a delete function of the form:
void user_delete_name(Sdr sdr, Address eltData, void *argData)\nWhen provided, this function is automatically called by the sdrlist function being invoked; when the function is called it is passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, argData, which if non-NULL is normally the address in local memory of a data item providing context for the list element deletion. The user-supplied function performs any application-specific cleanup associated with deleting the element, such as freeing the element's content data item and/or other SDR heap space associated with the element.
"},{"location":"man/ici/sdrlist/#see-also","title":"SEE ALSO","text":"lyst(3), sdr(3), sdrstring(3), sdrtable(3), smlist(3)
"},{"location":"man/ici/sdrmend/","title":"NAME","text":"sdrmend - SDR corruption repair utility
"},{"location":"man/ici/sdrmend/#synopsis","title":"SYNOPSIS","text":"sdrmend sdr_name config_flags heap_words heap_key path_name [restartCmd restartLatency]
"},{"location":"man/ici/sdrmend/#description","title":"DESCRIPTION","text":"The sdrmend program simply invokes the sdr_reload_profile() function (see sdr(3)) to effect necessary repairs in a potentially corrupt SDR, e.g., due to the demise of a program that had an SDR transaction in progress at the moment it crashed.
Note that sdrmend need not be run to repair ION's data store in the event of a hardware reboot: restarting ION will automatically reload the data store's profile. sdrmend is needed only when it is desired to repair the data store without requiring all ION software to terminate and restart.
"},{"location":"man/ici/sdrmend/#exit-status","title":"EXIT STATUS","text":"\"0\"
sdrmend has terminated successfully.
\"1\"
sdrmend has terminated unsuccessfully. See diagnostic messages in the ion.log log file for details.
No configuration files are needed.
"},{"location":"man/ici/sdrmend/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/sdrmend/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't initialize the SDR system.
Probable operations error: ION appears not to be initialized, in which case there is no point in running sdrmend.
Can't reload profile for SDR.
ION system error. See earlier diagnostic messages posted to ion.log for details. In this event it is unlikely that sdrmend can be run successfully, and it is also unlikely that it would have any effect if it did run successfully.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/sdrmend/#see-also","title":"SEE ALSO","text":"ionunlock(1), sdr(3), ionadmin(1)
"},{"location":"man/ici/sdrstring/","title":"NAME","text":"sdrstring - Simple Data Recorder string functions
"},{"location":"man/ici/sdrstring/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\nObject sdr_string_create (Sdr sdr, char *from);\nObject sdr_string_dup (Sdr sdr, Object from);\nint sdr_string_length (Sdr sdr, Object string);\nint sdr_string_read (Sdr sdr, char *into, Object string);\nSDR strings are used to record strings of up to 255 ASCII characters in the heap space of an SDR. Unlike standard C strings, which are terminated by a zero byte, SDR strings record the length of the string as part of the string object.
To store strings longer than 255 characters, use sdr_malloc() and sdr_write() instead of these functions.
Object sdr_string_create(Sdr sdr, char *from)
Creates a \"self-delimited string\" in the heap of the indicated SDR, allocating the required space and copying the indicated content. from must be a standard C string for which strlen() must not exceed 255; if it does, or if insufficient SDR space is available, 0 is returned. Otherwise the address of the newly created SDR string object is returned. To destroy, just use sdr_free().
Object sdr_string_dup(Sdr sdr, Object from)
Creates a duplicate of the SDR string whose address is from, allocating the required space and copying the original string's content. If insufficient SDR space is available, 0 is returned. Otherwise the address of the newly created copy of the original SDR string object is returned. To destroy, use sdr_free().
int sdr_string_length(Sdr sdr, Object string)
Returns the length of the indicated self-delimited string (as would be returned by strlen()), or -1 on any error.
int sdr_string_read(Sdr sdr, char *into, Object string)
Retrieves the content of the indicated self-delimited string into memory as a standard C string (NULL terminated). Length of into should normally be SDRSTRING_BUFSZ (i.e., 256) to allow for the largest possible SDR string (255 characters) plus the terminating NULL. Returns length of string (as would be returned by strlen()), or -1 on any error.
sdr(3), sdrlist(3), sdrtable(3), string(3)
"},{"location":"man/ici/sdrtable/","title":"NAME","text":"sdrtable - Simple Data Recorder table management functions
"},{"location":"man/ici/sdrtable/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\nObject sdr_table_create (Sdr sdr, int rowSize, int rowCount);\nint sdr_table_user_data_set (Sdr sdr, Object table, Address userData);\nAddress sdr_table_user_data (Sdr sdr, Object table);\nint sdr_table_dimensions (Sdr sdr, Object table, int *rowSize, \n int *rowCount);\nint sdr_table_stage (Sdr sdr, Object table);\nAddress sdr_table_row (Sdr sdr, Object table, \n unsigned int rowNbr);\nint sdr_table_destroy (Sdr sdr, Object table);\nThe SDR table functions manage table objects in the SDR. An SDR table comprises N rows of M bytes each, plus optionally one word of user data (which is nominally the address of some other object in the SDR's heap space). When a table is created, the number of rows in the table and the length of each row are specified; they remain fixed for the life of the table. The table functions merely maintain information about the table structure and its location in the SDR and calculate row addresses; other SDR functions such as sdr_read() and sdr_write() are used to read and write the contents of the table's rows. In particular, the format of the rows of a table is left entirely up to the user.
Object sdr_table_create(Sdr sdr, int rowSize, int rowCount)
Creates a \"self-delimited table\", comprising rowCount rows of rowSize bytes each, in the heap space of the indicated SDR. Note that the content of the table, a two-dimensional array, is a single SDR heap space object of size (rowCount x rowSize). Returns the address of the new table on success, zero on any error.
void sdr_table_user_data_set(Sdr sdr, Object table, Address userData)
Sets the \"user data\" word of table to userData. Note that userData is nominally an Address but can in fact be any value that occupies a single word. It is typically used to point to an SDR object that somehow characterizes the table as a whole, such as an SDR string containing a name.
Address sdr_table_user_data(Sdr sdr, Object table)
Returns the value of the \"user data\" word of table, or zero on any error.
void sdr_table_dimensions(Sdr sdr, Object table, int *rowSize, int *rowCount)
Reports on the row size and row count of the indicated table, as specified when the table was created.
void sdr_table_stage(Sdr sdr, Object table)
Stages table so that the array it encapsulates may be updated; see the discussion of sdr_stage() in sdr(3). The effect of this function is the same as:
sdr_stage(sdr, NULL, (Object) sdr_table_row(sdr, table, 0), 0)\nAddress sdr_table_row(Sdr sdr, Object table, unsigned int rowNbr)
Returns the address of the rowNbr_th row of _table, for use in reading or writing the content of this row; returns -1 on any error.
void sdr_table_destroy(Sdr sdr, Object table)
Destroys table, releasing all bytes of all rows and destroying the table structure itself. DO NOT use sdr_free() to destroy a table, as this would leave the table's content allocated yet unreferenced.
sdr(3), sdrlist(3), sdrstring(3)
"},{"location":"man/ici/sdrwatch/","title":"NAME","text":"sdrwatch - SDR non-volatile data store activity monitor
"},{"location":"man/ici/sdrwatch/#synopsis","title":"SYNOPSIS","text":"sdrwatch sdr_name [ -t | -s | -r | -z ] [interval [count [ verbose ]]]
"},{"location":"man/ici/sdrwatch/#description","title":"DESCRIPTION","text":"For count interations (defaulting to 1), sdrwatch sleeps interval seconds and then performs the SDR operation indicated by the specified mode: 's' to print statistics, 'r' to reset statistics, 'z' to print ZCO space utilization, 't' (the default) to call the sdr_print_trace() function (see sdr(3)) to report on SDR data storage management activity in the SDR data store identified by sdr_name during that interval. If the optional verbose parameter is specified, the printed SDR activity trace will be verbose as described in sdr(3).
If interval is zero, sdrwatch just performs the indicated operation once (for 't', it merely prints a current usage summary for the indicated data store) and terminates.
sdrwatch is helpful for detecting and diagnosing storage space leaks. For debugging the ION protocol stack, sdr_name is normally \"ion\" but might be overridden by the value of sdrName in the .ionconfig file used to configure the node under study.
"},{"location":"man/ici/sdrwatch/#exit-status","title":"EXIT STATUS","text":"\"0\"
sdrwatch has terminated.
No configuration files are needed.
"},{"location":"man/ici/sdrwatch/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/sdrwatch/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to sdr.
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 start trace.
Insufficient ION working memory to contain trace information. Reinitialize ION with more memory.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/sdrwatch/#see-also","title":"SEE ALSO","text":"sdr(3), psmwatch(1)
"},{"location":"man/ici/sm2file/","title":"NAME","text":"sm2file - shared-memory linked list data extraction test program
"},{"location":"man/ici/sm2file/#synopsis","title":"SYNOPSIS","text":"sm2file
"},{"location":"man/ici/sm2file/#description","title":"DESCRIPTION","text":"sm2file stress-tests shared-memory linked list data extraction by retrieving and deleting all text file lines inserted into a shared-memory linked list that is the root object of a PSM partition named \"file2sm\".
The operation of sm2file echoes the cyclical operation of file2sm: the EOF lines inserted into the linked list by file2sm punctuate the writing of files that are copies of file2sm's original source text file. The name of each file written by sm2file is file_copy_cycleNbr, where cycleNbr is, in effect, the count of EOF lines encountered in the linked list up to the point at which the writing of this file began.
sm2file may catch up with the data ingestion activity of file2sm, in which case it blocks (taking the file2sm test semaphore) until the linked list is no longer empty.
"},{"location":"man/ici/sm2file/#exit-status","title":"EXIT STATUS","text":"\"0\"
sm2file has terminated.
No configuration files are needed.
"},{"location":"man/ici/sm2file/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/sm2file/#diagnostics","title":"DIAGNOSTICS","text":"can't attach to shared memory
Operating system error. Check errtext, correct problem, and rerun.
Can't manage shared memory.
PSM error. Check for earlier diagnostics describing the cause of the error; correct problem and rerun.
Can't create shared memory list.
PSM error. Check for earlier diagnostics describing the cause of the error; correct problem and rerun.
Can't create semaphore.
ION system error. Check for earlier diagnostics describing the cause of the error; correct problem and rerun.
Can't open output file
Operating system error. Check errtext, correct problem, and rerun.
can't write to output file
Operating system error. Check errtext, correct problem, and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/sm2file/#see-also","title":"SEE ALSO","text":"file2sm(1), smlist(3), psm(3)
"},{"location":"man/ici/smlist/","title":"NAME","text":"smlist - shared memory list management library
"},{"location":"man/ici/smlist/#synopsis","title":"SYNOPSIS","text":"#include \"smlist.h\"\n\ntypedef int (*SmListCompareFn)\n (PsmPartition partition, PsmAddress eltData, void *argData);\ntypedef void (*SmListDeleteFn)\n (PsmPartition partition, PsmAddress elt, void *argument);\n\n[see description for available functions]\nThe smlist library provides functions to create, manipulate and destroy doubly-linked lists in shared memory. As with lyst(3), smlist uses two types of objects, list objects and element objects. However, as these objects are stored in shared memory which is managed by psm(3), pointers to these objects are carried as PsmAddress values. A list knows how many elements it contains and what its first and last elements are. An element knows what list it belongs to and the elements before and after it in its list. An element also knows its content, which is normally the PsmAddress of some object in shared memory.
PsmAddress sm_list_create(PsmPartition partition)
Create a new list object without any elements in it, within the memory segment identified by partition. Returns the PsmAddress of the list, or 0 on any error.
void sm_list_unwedge(PsmPartition partition, PsmAddress list, int interval)
Unwedge, as necessary, the mutex semaphore protecting shared access to the indicated list. For details, see the explanation of the sm_SemUnwedge() function in platform(3).
int sm_list_clear(PsmPartition partition, PsmAddress list, SmListDeleteFn delete, void *argument);
Empty a list. Frees each element of the list. If the delete function is non-NULL, that function is called once for each freed element; when called, that function is passed the PsmAddress of the list element and the argument pointer passed to sm_list_clear(). Returns 0 on success, -1 on any error.
int sm_list_destroy(PsmPartition partition, PsmAddress list, SmListDeleteFn delete, void *argument);
Destroy a list. Same as sm_list_clear(), but additionally frees the list structure itself. Returns 0 on success, -1 on any error.
int sm_list_user_data_set(PsmPartition partition, PsmAddress list, PsmAddress userData);
Set the value of a user data variable associated with the list as a whole. This value may be used for any purpose; it is typically used to store the PsmAddress of a shared memory block containing data (e.g., state data) which the user wishes to associate with the list. Returns 0 on success, -1 on any error.
PsmAddress sm_list_user_data(PsmPartition partition, PsmAddress list);
Return the value of the user data variable associated with the list as a whole, or 0 on any error.
int sm_list_length(PsmPartition partition, PsmAddress list);
Return the number of elements in the list.
PsmAddress sm_list_insert(PsmPartition partition, PsmAddress list, PsmAddress data, SmListCompareFn compare, void *dataBuffer);
Create a new list element whose data value is data and insert it into the given list. If the compare function is NULL, the new list element is simply appended to the list; otherwise, the new list element is inserted after the last element in the list whose data value is \"less than or equal to\" the data value of the new element (in dataBuffer) according to the collating sequence established by compare. Returns the PsmAddress of the new element, or 0 on any error.
PsmAddress sm_list_insert_first(PsmPartition partition, PsmAddress list, PsmAddress data);
PsmAddress sm_list_insert_last(PsmPartition partition, PsmAddress list, PsmAddress data);
Create a new list element and insert it at the start/end of a list. Returns the PsmAddress of the new element on success, or 0 on any error. Disregards any established sort order in the list.
PsmAddress sm_list_insert_before(PsmPartition partition, PsmAddress elt, PsmAddress data);
PsmAddress sm_list_insert_after(PsmPartition partition, PsmAddress elt, PsmAddress data);
Create a new list element and insert it before/after a given element. Returns the PsmAddress of the new element on success, or 0 on any error. Disregards any established sort order in the list.
int sm_list_delete(PsmPartition partition, PsmAddress elt, SmListDeleteFn delete, void *argument);
Delete an element from a list. If the delete function is non-NULL, that function is called upon deletion of elt; when called, that function is passed the PsmAddress of the list element and the argument pointer passed to sm_list_delete(). Returns 0 on success, -1 on any error.
PsmAddress sm_list_first(PsmPartition partition, PsmAddress list);
PsmAddress sm_list_last(PsmPartition partition, PsmAddress list);
Return the PsmAddress of the first/last element in list, or 0 on any error.
PsmAddress sm_list_next(PsmPartition partition, PsmAddress elt);
PsmAddress sm_list_prev(PsmPartition partition, PsmAddress elt);
Return the PsmAddress of the element following/preceding elt in that element's list, or 0 on any error.
PsmAddress sm_list_search(PsmPartition partition, PsmAddress elt, SmListCompareFn compare, void *dataBuffer);
Search a list for an element whose data matches the data in dataBuffer. If the compare function is non-NULL, the list is assumed to be sorted in the order implied by that function and the function is automatically called once for each element of the list until it returns a value that is greater than or equal to zero (where zero indicates an exact match and a value greater than zero indicates that the list contains no matching element); each time compare is called it is passed the PsmAddress that is the element's data value and the dataBuffer value passed to sm_list_search(). If compare is NULL, then the entire list is searched until an element is located whose data value is equal to ((PsmAddress) dataBuffer). Returns the PsmAddress of the matching element if one is found, 0 otherwise.
PsmAddress sm_list_list(PsmPartition partition, PsmAddress elt);
Return the PsmAddress of the list to which elt belongs, or 0 on any error.
PsmAddress sm_list_data(PsmPartition partition, PsmAddress elt);
Return the PsmAddress that is the data value for elt, or 0 on any error.
PsmAddress sm_list_data_set(PsmPartition partition, PsmAddress elt, PsmAddress data);
Set the data value for elt to data, replacing the original value. Returns the original data value for elt, or 0 on any error. The original data value for elt may or may not have been the address of an object in memory; even if it was, that object was NOT deleted.
Warning: changing the data value of an element of an ordered list may ruin the ordering of the list.
A user normally creates an element and adds it to a list by doing the following:
1
obtaining a shared memory block to contain the element's data;
2
converting the shared memory block's PsmAddress to a character pointer;
3
using that pointer to write the data into the shared memory block;
4
calling one of the sm_list_insert functions to create the element structure (which will include the shared memory block's PsmAddress) and insert it into the list.
When inserting elements or searching a list, the user may optionally provide a compare function of the form:
int user_comp_name(PsmPartition partition, PsmAddress eltData, \n void *dataBuffer);\nWhen provided, this function is automatically called by the smlist function being invoked; when the function is called it is passed the content of a list element (eltData, nominally the PsmAddress of an item in shared memory) and an argument, dataBuffer, which is nominally the address in local memory of some other item in the same format. The user-supplied function normally compares some key values of the two data items and returns 0 if they are equal, an integer less than 0 if eltData's key value is less than that of dataBuffer, and an integer greater than 0 if eltData's key value is greater than that of dataBuffer. These return values will produce a list in ascending order. If the user desires the list to be in descending order, the function must reverse the signs of these return values.
When deleting an element or destroying a list, the user may optionally provide a delete function of the form:
void user_delete_name(PsmPartition partition, PsmAddress elt, void *argData)\nWhen provided, this function is automatically called by the smlist function being invoked; when the function is called it is passed the address of a list element (elt and an argument, argData, which if non-NULL is normally the address in local memory of a data item providing context for the list element deletion. The user-supplied function performs any application-specific cleanup associated with deleting the element, such as freeing the element's content data item and/or other memory associated with the element.
"},{"location":"man/ici/smlist/#example","title":"EXAMPLE","text":"For an example of the use of smlist, see the file smlistsh.c in the utils directory of ICI.
"},{"location":"man/ici/smlist/#see-also","title":"SEE ALSO","text":"lyst(3), platform(3), psm(3)
"},{"location":"man/ici/smlistsh/","title":"NAME","text":"smlistsh - shared-memory linked list test shell
"},{"location":"man/ici/smlistsh/#synopsis","title":"SYNOPSIS","text":"smlistsh partition_size
"},{"location":"man/ici/smlistsh/#description","title":"DESCRIPTION","text":"smlistsh attaches to a region of system memory (allocating it if necessary, and placing it under PSM management as necessary) and offers the user an interactive \"shell\" for testing various shared-memory linked list management functions.
smlistsh prints a prompt string (\": \") to stdout, accepts a command from stdin, executes the command (possibly printing a diagnostic message), then prints another prompt string and so on.
The following commands are supported:
h
The help command. Causes smlistsh to print a summary of available commands. Same effect as the ? command.
?
Another help command. Causes smlistsh to print a summary of available commands. Same effect as the h command.
k
The key command. Computes and prints an unused shared-memory key, for possible use in attaching to a shared-memory region.
+ key_value size
The attach command. Attaches smlistsh to a region of shared memory. key_value identifies an existing shared-memory region, in the event that you want to attach to an existing shared-memory region (possibly created by another smlistsh process running on the same computer). To create and attach to a new shared-memory region that other processes can attach to, use a key_value as returned by the key command and supply the size of the new region. If you want to create and attach to a new shared-memory region that is for strictly private use, use -1 as key and supply the size of the new region.
-
The detach command. Detaches smlistsh from the region of shared memory it is currently using, but does not free any memory.
n
The new command. Creates a new shared-memory list to operate on, within the currently attached shared-memory region. Prints the address of the list.
s list_address
The share command. Selects an existing shared-memory list to operate on, within the currently attached shared-memory region.
a element_value
The append command. Appends a new list element, containing element_value, to the list on which smlistsh is currently operating.
p element_value
The prepend command. Prepends a new list element, containing element_value, to the list on which smlistsh is currently operating.
w
The walk command. Prints the addresses and contents of all elements of the list on which smlistsh is currently operating.
f element_value
The find command. Finds the list element that contains element_value, within the list on which smlistsh is currently operating, and prints the address of that list element.
d element_address
The delete command. Deletes the list element located at element_address.
r
The report command. Prints a partition usage report, as per psm_report(3).
q
The quit command. Detaches smlistsh from the region of shared memory it is currently using (without freeing any memory) and terminates smlistsh.
\"0\"
smlistsh has terminated.
No configuration files are needed.
"},{"location":"man/ici/smlistsh/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/smlistsh/#diagnostics","title":"DIAGNOSTICS","text":"No diagnostics apply.
"},{"location":"man/ici/smlistsh/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/smlistsh/#see-also","title":"SEE ALSO","text":"smlist(3)
"},{"location":"man/ici/smrbt/","title":"NAME","text":"smrbt - shared-memory red-black tree management library
"},{"location":"man/ici/smrbt/#synopsis","title":"SYNOPSIS","text":"#include \"smrbt.h\"\n\ntypedef int (*SmRbtCompareFn)\n (PsmPartition partition, PsmAddress nodeData, void *dataBuffer);\ntypedef void (*SmRbtDeleteFn)\n (PsmPartition partition, PsmAddress nodeData, void *argument);\n\n[see description for available functions]\nThe smrbt library provides functions to create, manipulate and destroy \"red-black\" balanced binary trees in shared memory. smrbt uses two types of objects, rbt objects and node objects; as these objects are stored in shared memory which is managed by psm(3), pointers to these objects are carried as PsmAddress values. An rbt knows how many nodes it contains and what its root node is. An node knows what rbt it belongs to and which nodes are its parent and (up to 2) children. A node also knows its content, which is normally the PsmAddress of some object in shared memory.
PsmAddress sm_rbt_create(PsmPartition partition)
Create a new rbt object without any nodes in it, within the memory segment identified by partition. Returns the PsmAddress of the rbt, or 0 on any error.
void sm_rbt_unwedge(PsmPartition partition, PsmAddress rbt, int interval)
Unwedge, as necessary, the mutex semaphore protecting shared access to the indicated rbt. For details, see the explanation of the sm_SemUnwedge() function in platform(3).
int sm_rbt_clear(PsmPartition partition, PsmAddress rbt, SmRbtDeleteFn delete, void *argument);
Frees every node of the rbt, leaving the rbt empty. If the delete function is non-NULL, that function is called once for each freed node; when called, that function is passed the PsmAddress that is the node's data and the argument pointer passed to sm_rbt_clear(). Returns 0 on success, -1 on any error.
void sm_rbt_destroy(PsmPartition partition, PsmAddress rbt, SmRbtDeleteFn delete, void *argument);
Destroy an rbt. Frees all nodes of the rbt as in sm_rbt_clear(), then frees the rbt structure itself.
int sm_rbt_user_data_set(PsmPartition partition, PsmAddress rbt, PsmAddress userData);
Set the value of a user data variable associated with the rbt as a whole. This value may be used for any purpose; it is typically used to store the PsmAddress of a shared memory block containing data (e.g., state data) which the user wishes to associate with the rbt. Returns 0 on success, -1 on any error.
PsmAddress sm_rbt_user_data(PsmPartition partition, PsmAddress rbt);
Return the value of the user data variable associated with the rbt as a whole, or 0 on any error.
int sm_rbt_length(PsmPartition partition, PsmAddress rbt);
Return the number of nodes in the rbt.
PsmAddress sm_rbt_insert(PsmPartition partition, PsmAddress rbt, PsmAddress data, SmRbtCompareFn compare, void *dataBuffer);
Create a new rbt node whose data value is data and insert it into rbt. The nodes of an rbt are ordered by their notional \"key\" values; for this purpose, no two nodes may have the same key value. The key value of a node is assumed to be some function of the content of dataBuffer, which is assumed to be a representation in memory of the data value indicated by data, and that function must be implicit in the compare function, which must not be NULL. The new rbt node is inserted into the rbt in a tree location that preserves order in the tree, according to the collating sequence established by compare, and also ensures that no path (from root to leaf) in the tree is more than twice as long as any other path. This makes searching the tree for a given data value quite rapid even if the number of nodes in the tree is very large. Returns the PsmAddress of the new node, or 0 on any error.
void sm_rbt_delete(PsmPartition partition, PsmAddress rbt, SmRbtCompareFn compare, void *dataBuffer, SmRbtDeleteFn delete, void *argument);
Delete a node from rbt. compare must be the same function that was used to insert the node: the tree must be dynamically re-balanced upon node deletion, and the compare function and the data value of the node that is to be deleted (as represented in memory in dataBuffer) are required for this purpose. (Since the function descends the tree in search of the matching node anyway, in order to preserve balance, the address of the node itself is not needed.)
If the delete function is non-NULL, that function is called upon deletion of the indicated node. When called, that function is passed the PsmAddress that is the node's data value and the argument pointer passed to sm_rbt_delete().
NOTE that this function does something highly devious to avoid extra tree-balancing complexity when node is deleted. For details, see the code, but the main point is that deleting a node WILL MOVE NODES WITHIN THE TREE. After the deletion, the next node may not be the one that would have been reported if you passed the to-be-deleted node to sm_rbt_next() before calling sm_rbt_delete(). This is important: do not apply updates (no insertions, and especially no deletions) while you are traversing a red-black tree sequentially. If you do, the result will not be what you expect.
PsmAddress sm_rbt_first(PsmPartition partition, PsmAddress rbt);
PsmAddress sm_rbt_last(PsmPartition partition, PsmAddress rbt);
Return the PsmAddress of the first/last node in rbt, or 0 on any error.
PsmAddress sm_rbt_next(PsmPartition partition, PsmAddress node);
PsmAddress sm_rbt_prev(PsmPartition partition, PsmAddress node);
Return the PsmAddress of the node following/preceding node in that node's rbt, or 0 on any error.
NOTE that the red-black tree node insertion and deletion functions WILL MOVE NODES WITHIN THE TREE. This is important: do not apply updates (no insertions, and especially no deletions) while you are traversing a red-black tree sequentially, using sm_rbt_next() or sm_rbt_prev(). If you do, the result will not be what you expect.
PsmAddress sm_rbt_search(PsmPartition partition, PsmAddress rbt, SmRbtCompareFn compare, void *dataBuffer, PsmAddress *successor);
Search rbt for a node whose data matches the data in dataBuffer. compare must be the same function that was used to insert all nodes into the tree. The tree is searched until a node is found whose data value is \"equal\" (according to compare) to the data value represented in memory in dataBuffer, or until it is known that there is no such node in the tree. If the matching node is found, the PsmAddress of that node is returned and *successor is set to zero. Otherwise, zero is returned and *successor is set to the PsmAddress of the first node in the tree whose key value is greater than the key value of dataBuffer, according to compare, or to zero if there is no such successor node.
PsmAddress sm_rbt_rbt(PsmPartition partition, PsmAddress node);
Return the PsmAddress of the rbt to which node belongs, or 0 on any error.
PsmAddress sm_rbt_data(PsmPartition partition, PsmAddress node);
Return the PsmAddress that is the data value for node, or 0 on any error.
A user normally creates an node and adds it to a rbt by doing the following:
1
obtaining a shared memory block to contain the node's data;
2
converting the shared memory block's PsmAddress to a character pointer;
3
using that pointer to write the data into the shared memory block;
4
calling the sm_rbt_insert function to create the node structure (which will include the shared memory block's PsmAddress) and insert it into the rbt.
When inserting or deleting nodes or searching a rbt, the user must provide a compare function of the form:
int user_comp_name(PsmPartition partition, PsmAddress node, \n void *dataBuffer);\nThis function is automatically called by the smrbt function being invoked; when the function is called it is passed the data content of an rbt node (node, nominally the PsmAddress of an item in shared memory) and an argument, dataBuffer, which is nominally the address in local memory of some other data item in the same format. The user-supplied function normally compares some key values of the two data items and returns 0 if they are equal, an integer less than 0 if node's key value is less than that of dataBuffer, and an integer greater than 0 if node's key value is greater than that of dataBuffer. These return values will produce an rbt in ascending order.
When deleting an node or destroying a rbt, the user may optionally provide a delete function of the form:
void user_delete_name(PsmPartition partition, PsmAddress node, \n void *argData)\nWhen provided, this function is automatically called by the smrbt function being invoked; when the function is called it is passed the content of a rbt node (node, nominally the PsmAddress of an item in shared memory) and an argument, argData, which if non-NULL is normally the address in local memory of a data item providing context for the rbt node deletion. The user-supplied function performs any application-specific cleanup associated with deleting the node, such as freeing the node's content data item and/or other memory associated with the node.
"},{"location":"man/ici/smrbt/#example","title":"EXAMPLE","text":"For an example of the use of smrbt, see the file smrbtsh.c in the utils directory of ICI.
"},{"location":"man/ici/smrbt/#see-also","title":"SEE ALSO","text":"smrbtsh(1), platform(3), psm(3)
"},{"location":"man/ici/smrbtsh/","title":"NAME","text":"smrbtsh - shared-memory red-black tree test shell
"},{"location":"man/ici/smrbtsh/#synopsis","title":"SYNOPSIS","text":"smrbtsh [command_file_name]
"},{"location":"man/ici/smrbtsh/#description","title":"DESCRIPTION","text":"smrbtsh allocates a region of shared system memory, attaches to that region, places it under PSM management, creates a temporary \"test\" red-black tree in that memory region, and executes a series of shared-memory red-black tree commands that exercise various tree access and management functions.
If command_file_name is provided, then the commands in the indicated file are executed and the program then terminates. Upon termination, the shared memory region allocated to smrbtsh is detached and destroyed.
Otherwise, smrbtsh offers the user an interactive \"shell\" for testing the smrbt functions in a conversational manner: smrbtsh prints a prompt string (\": \") to stdout, accepts a command from stdin, executes the command (possibly printing a diagnostic message), then prints another prompt string and so on. Upon execution of the 'q' command, the program terminates.
The following commands are supported:
h
The help command. Causes smrbtsh to print a summary of available commands. Same effect as the ? command.
?
Another help command. Causes smrbtsh to print a summary of available commands. Same effect as the h command.
s [seed_value]
The seed command. Seeds random data value generator, which is used to generate node values when the r command is used. If seed_value is omitted, uses current time (as returned by time(1)) as seed value.
r [count]
The random command. Inserts count new nodes into the red-black tree, using randomly selected unsigned long integers as the data values of the nodes; count defaults to 1 if omitted.
i data_value
The insert command. Inserts a single new node into the red-black tree, using data_value as the data value of the node.
f data_value
The find command. Finds the rbt node whose value is data_value, within the red-black tree, and prints the address of that node. If the node is not found, prints address zero and prints the address of the successor node in the tree.
d data_value
The delete command. Deletes the rbt node whose data value is data_value.
p
The print command. Prints the red-black tree, using indentation to indicate descent along paths of the tree.
Note: this function is supported only if the smrbt library was built with compilation flag -DSMRBT_DEBUG=1.
k
The check command. Examines the red-black tree, noting the first violation of red-black structure rules, if any.
Note: this function is supported only if the smrbt library was built with compilation flag -DSMRBT_DEBUG=1.
l
The list command. Lists all nodes in the red-black tree in traversal order, noting any nodes whose data values are not in ascending numerical order.
q
The quit command. Detaches smrbtsh from the region of shared memory it is currently using, destroys that shared memory region, and terminates smrbtsh.
\"0\"
smrbtsh has terminated.
No configuration files are needed.
"},{"location":"man/ici/smrbtsh/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/smrbtsh/#diagnostics","title":"DIAGNOSTICS","text":"No diagnostics apply.
"},{"location":"man/ici/smrbtsh/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/smrbtsh/#see-also","title":"SEE ALSO","text":"smrbt(3)
"},{"location":"man/ici/zco/","title":"NAME","text":"zco - library for manipulating zero-copy objects
"},{"location":"man/ici/zco/#synopsis","title":"SYNOPSIS","text":"#include \"zco.h\"\n\ntypedef enum\n{\n ZcoInbound = 0,\n ZcoOutbound = 1,\n ZcoUnknown = 2\n} ZcoAcct;\n\ntypedef enum\n{\n ZcoFileSource = 1,\n ZcoBulkSource = 2,\n ZcoObjSource = 3,\n ZcoSdrSource = 4,\n ZcoZcoSource = 5\n} ZcoMedium;\n\ntypedef void (*ZcoCallback)(ZcoAcct);\n\n[see description for available functions]\n\"Zero-copy objects\" (ZCOs) are abstract data access representations designed to minimize I/O in the encapsulation of application source data within one or more layers of communication protocol structure. ZCOs are constructed within the heap space of an SDR to which implementations of all layers of the stack must have access. Each ZCO contains information enabling access to the source data objects, together with (a) a linked list of zero or more \"extents\" that reference portions of these source data objects and (b) linked lists of protocol header and trailer capsules that have been explicitly attached to the ZCO since its creation. The concatenation of the headers (in ascending stack sequence), source data object extents, and trailers (in descending stack sequence) is what is to be transmitted or has been received.
Each source data object may be either a file (identified by pathname stored in a \"file reference\" object in SDR heap) or an item in mass storage (identified by item number, with implementation-specific semantics, stored in a \"bulk reference\" object in SDR heap) or an object in SDR heap space (identified by heap address stored in an \"object reference\" object in SDR heap) or an array of bytes in SDR heap space (identified by heap address). Each protocol header or trailer capsule indicates the length and the address (within SDR heap space) of a single protocol header or trailer at some layer of the stack. Note that the source data object for each ZCO extent is specified indirectly, by reference to a content lien reference structure that refers to a heap space object, mass storage item, or file; the reference structures contain the actual locations of the source data together with reference counts, enabling any number of \"clones\" of a given ZCO extent to be constructed without consuming additional resources. These reference counts ensure that the reference structures and the source data items they refer to are deleted automatically when (and only when) all ZCO extents that reference them have been deleted.
Note that the safety of shared access to a ZCO is protected by the fact that the ZCO resides in SDR heap space and therefore cannot be modified other than in the course of an SDR transaction, which serializes access. Moreover, extraction of data from a ZCO may entail the reading of file-based source data extents, which may cause file progress to be updated in one or more file reference objects in the SDR heap. For this reason, all ZCO \"transmit\" and \"receive\" functions must be performed within SDR transactions.
Note also that ZCO can more broadly be used as a general-purpose reference counting system for non-volatile data objects, where a need for such a system is identified.
The total volume of file system space, mass storage space, and SDR heap space that may be occupied by inbound and (separately) outbound ZCO extents are system configuration parameters that may be set by ZCO library functions. Those limits are enforced when extents are appended to ZCOs: total inbound and outbound ZCO file space, mass storage, and SDR heap occupancy are updated continuously as ZCOs are created and destroyed, and the formation of a new extent is prohibited when the length of the extent exceeds the difference between the applicable limit and the corresponding current occupancy total. Doing separate accounting for inbound and outbound ZCOs enables inbound ZCOs to be formed (for data reception purposes) even when the total current volume of outbound ZCOs has reached its limit, and vice versa.
void zco_register_callback(ZcoCallback notify)
This function registers the \"callback\" function that the ZCO system will invoke every time a ZCO is destroyed, making ZCO file, bulk, and/or heap space available for the formation of new ZCO extents. This mechanism can be used, for example, to notify tasks that are waiting for ZCO space to be made available so that they can resume some communication protocol procedure.
void zco_unregister_callback( )
This function simply unregisters the currently registered callback function for ZCO destruction.
Object zco_create_file_ref(Sdr sdr, char *pathName, char *cleanupScript, ZcoAcct acct)
Creates and returns a new file reference object, which can be used as the source data extent location for creating a ZCO whose source data object is the file identified by pathName. cleanupScript, if not NULL, is invoked at the moment the last ZCO that cites this file reference is destroyed [normally upon delivery either down to the \"ZCO transition layer\" of the protocol stack or up to a ZCO-capable application]. A zero-length string is interpreted as implicit direction to delete the referenced file when the file reference object is destroyed. Maximum length of cleanupScript is 255. acct must be ZcoInbound or ZcoOutbound, depending on whether the first ZCO that will reference this object will be inbound or outbound. Returns SDR location of file reference object on success, 0 on any error.
Object zco_revise_file_ref(Sdr sdr, Object fileRef, char *pathName, char *cleanupScript)
Changes the pathName and cleanupScript of the indicated file reference. The new values of these fields are validated as for zco_create_file_ref(). Returns 0 on success, -1 on any error.
char *zco_file_ref_path(Sdr sdr, Object fileRef, char *buffer, int buflen)
Retrieves the pathName associated with fileRef and stores it in buffer, truncating it to fit (as indicated by buflen) and NULL-terminating it. On success, returns buffer; returns NULL on any error.
int zco_file_ref_xmit_eof(Sdr sdr, Object fileRef)
Returns 1 if the last octet of the referenced file (as determined at the time the file reference object was created) has been read by ZCO via a reader with file offset tracking turned on. Otherwise returns zero.
void zco_destroy_file_ref(Sdr sdr, Object fileRef)
If the file reference object residing at location fileRef within the indicated Sdr is no longer in use (no longer referenced by any ZCO), destroys this file reference object immediately. Otherwise, flags this file reference object for destruction as soon as the last reference to it is removed.
Object zco_create_bulk_ref(Sdr sdr, unsigned long item, vast length, ZcoAcct acct)
Creates and returns a new bulk reference object, which can be used as the source data extent location for creating a ZCO whose source data object is the mass storage item of length length identified by item (the semantics of which are implementation-dependent). Note that the referenced item is automatically destroyed at the time that the last ZCO that cites this bulk reference is destroyed (normally upon delivery either down to the \"ZCO transition layer\" of the protocol stack or up to a ZCO-capable application). acct must be ZcoInbound or ZcoOutbound, depending on whether the first ZCO that will reference this object will be inbound or outbound. Returns SDR location of bulk reference object on success, 0 on any error.
void zco_destroy_bulk_ref(Sdr sdr, Object bulkRef)
If the bulk reference object residing at location bulkRef within the indicated Sdr is no longer in use (no longer referenced by any ZCO), destroys this bulk reference object immediately. Otherwise, flags this bulk reference object for destruction as soon as the last reference to it is removed.
Object zco_create_obj_ref(Sdr sdr, Object object, vast length, ZcoAcct acct)
Creates and returns a new object reference object, which can be used as the source data extent location for creating a ZCO whose source data object is the SDR heap object of length length identified by object. Note that the referenced object is automatically freed at the time that the last ZCO that cites this object reference is destroyed (normally upon delivery either down to the \"ZCO transition layer\" of the protocol stack or up to a ZCO-capable application). acct must be ZcoInbound or ZcoOutbound, depending on whether the first ZCO that will reference this object will be inbound or outbound. Returns SDR location of object reference object on success, 0 on any error.
void zco_destroy_obj_ref(Sdr sdr, Object objRef)
If the object reference object residing at location objRef within the indicated Sdr is no longer in use (no longer referenced by any ZCO), destroys this object reference object immediately. Otherwise, flags this object reference object for destruction as soon as the last reference to it is removed.
void zco_status(Sdr sdr)
Uses the ION logging function to write a report of the current contents of the ZCO space accounting database.
vast zco_get_file_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of file system space bytes occupied by ZCOs (inbound or outbound) created in this Sdr.
void zco_set_max_file_occupancy(Sdr sdr, vast occupancy, ZcoAcct acct)
Declares the total number of file system space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
vast zco_get_max_file_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of file system space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
int zco_enough_file_space(Sdr sdr, vast length, ZcoAcct acct)
Returns 1 if the total remaining file system space available for ZCOs (inbound or outbound) in this Sdr is greater than length. Returns 0 otherwise.
vast zco_get_bulk_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of mass storage space bytes occupied by ZCOs (inbound or outbound) created in this Sdr.
void zco_set_max_bulk_occupancy(Sdr sdr, vast occupancy, ZcoAcct acct)
Declares the total number of mass storage space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
vast zco_get_max_bulk_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of mass storage space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
int zco_enough_bulk_space(Sdr sdr, vast length, ZcoAcct acct)
Returns 1 if the total remaining mass storage space available for ZCOs (inbound or outbound) in this Sdr is greater than length. Returns 0 otherwise.
vast zco_get_heap_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of SDR heap space bytes occupied by ZCOs (inbound or outbound) created in this Sdr.
void zco_set_max_heap_occupancy(Sdr sdr, vast occupancy, ZcoAcct acct)
Declares the total number of SDR heap space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
vast zco_get_max_heap_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of SDR heap space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
int zco_enough_heap_space(Sdr sdr, vast length, ZcoAcct acct)
Returns 1 if the total remaining SDR heap space available for ZCOs (inbound or outbound) in this Sdr is greater than length. Returns 0 otherwise.
int zco_extent_too_large(Sdr sdr, ZcoMedium source, vast length, ZcoAcct acct)
Returns 1 if the total remaining space available for ZCOs (inbound or outbound) is NOT enough to contain a new extent of the indicated length in the indicated source medium. Returns 0 otherwise.
int zco_get_aggregate_length(Sdr sdr, Object location, vast offset, vast length, vast *fileSpaceOccupied, vast *bulkSpaceOccupied, vast *heapSpaceOccupied)
Populates *fileSpaceOccupied, *bulkSpaceOccupied, and *heapSpaceOccupied with the total number of ZCO space bytes occupied by the extents of the zco at location, from offset to offset + length. If offset isn't the start of an extent or offset + length isn't the end of an extent, returns -1 in all three fields.
Object zco_create(Sdr sdr, ZcoMedium firstExtentSourceMedium, Object firstExtentLocation, vast firstExtentOffset, vast firstExtentLength, ZcoAcct acct)
Creates a new inbound or outbound ZCO. firstExtentLocation and firstExtentLength must either both be zero (indicating that zco_append_extent() will be used to insert the first source data extent later) or else both be non-zero. If firstExtentLocation is non-zero, then (a) firstExtentLocation must be the SDR location of a file reference object, bulk reference object, object reference object, SDR heap object, or ZCO, depending on the value of firstExtentSourceMedium, and (b) firstExtentOffset indicates how many leading bytes of the source data object should be skipped over when adding the initial source data extent to the new ZCO. A negative value for firstExtentLength indicates that the extent is already known not to be too large for the available ZCO space, and the actual length of the extent is the additive inverse of this value. On success, returns the SDR location of the new ZCO. Returns 0 if there is insufficient ZCO space for creation of the new ZCO; returns ((Object) -1) on any error.
int zco_append_extent(Sdr sdr, Object zco, ZcoMedium sourceMedium, Object location, vast offset, vast length)
Appends the indicated source data extent to the indicated ZCO, as described for zco_create(). Both the location and length of the source data must be non-zero. A negative value for length indicates that the extent is already known not to be too large for the available ZCO space, and the actual length of the extent is the additive inverse of this value. For constraints on the value of location, see zco_create(). Returns length on success, 0 if there is insufficient ZCO space for creation of the new source data extent, -1 on any error.
int zco_prepend_header(Sdr sdr, Object zco, char *header, vast length)
void zco_discard_last_trailer(Sdr sdr, Object zco)
These functions attach and remove the ZCO's headers and trailers. header and trailer are assumed to be arrays of octets, not necessarily text. Attaching a header or trailer causes it to be written to the SDR. The prepend and append functions return 0 on success, -1 on any error.
Object zco_header_text(Sdr sdr, Object zco, int skip, vast *length)
Skips over the first skip headers of zco and returns the address of the text of the next header, placing the length of the header's text in *length. Returns 0 on any error.
Object zco_trailer_text(Sdr sdr, Object zco, int skip, vast *length)
Skips over the first skip trailers of zco and returns the address of the text of the next trailer, placing the length of the trailer's text in *length. Returns 0 on any error.
void zco_destroy(Sdr sdr, Object zco)
Destroys the indicated Zco. This reduces the reference counts for all files and SDR objects referenced in the ZCO's extents, resulting in the freeing of SDR objects and (optionally) the deletion of files as those reference count drop to zero.
void zco_bond(Sdr sdr, Object zco)
Converts all headers and trailers of the indicated Zco to source data extents. Use this function to ensure that known header and trailer data are included when the ZCO is cloned.
int zco_revise(Sdr sdr, Object zco, vast offset, char *buffer, vast length)
Writes the contents of buffer, for length length, into zco at offset offset. Returns 0 on success, -1 on any error.
Object zco_clone(Sdr sdr, Object zco, vast offset, vast length)
Creates a new ZCO whose source data is a copy of a subset of the source data of the referenced ZCO. This procedure is required whenever it is necessary to process the ZCO's source data in multiple different ways, for different purposes, and therefore the ZCO must be in multiple states at the same time. Portions of the source data extents of the original ZCO are copied as necessary, but no header or trailer capsules are copied. Returns SDR location of the new ZCO on success, (Object) -1 on any error.
vast zco_clone_source_data(Sdr sdr, Object toZco, Object fromZco, vast offset, vast length)
Appends to toZco a copy of a subset of the source data of fromZCO. Portions of the source data extents of fromZCO are copied as necessary. Returns total data length cloned, or -1 on any error.
vast zco_length(Sdr sdr, Object zco)
Returns length of entire ZCO, including all headers and trailers and all source data extents. This is the size of the object that would be formed by concatenating the text of all headers, trailers, and source data extents into a single serialized object.
vast zco_source_data_length(Sdr sdr, Object zco)
Returns length of entire ZCO minus the lengths of all attached header and trailer capsules. This is the size of the object that would be formed by concatenating the text of all source data extents (including those that are presumed to contain header or trailer text attached elsewhere) into a single serialized object.
ZcoAcct zco_acct(Sdr sdr, Object zco)
Returns an indicator as to whether zco is inbound or outbound.
void zco_start_transmitting(Object zco, ZcoReader *reader)
Used by underlying protocol layer to start extraction of an outbound ZCO's bytes (both from header and trailer capsules and from source data extents) for \"transmission\" -- i.e., the copying of bytes into a memory buffer for delivery to some non-ZCO-aware protocol implementation. Initializes reading at the first byte of the total concatenated ZCO object. Populates reader, which is used to keep track of \"transmission\" progress via this ZCO reference.
Note that this function can be called multiple times to restart reading at the start of the ZCO. Note also that multiple ZcoReader objects may be used concurrently, by the same task or different tasks, to advance through the ZCO independently.
void zco_track_file_offset(ZcoReader *reader)
Turns on file offset tracking for this reader.
vast zco_transmit(Sdr sdr, ZcoReader *reader, vast length, char *buffer)
Copies length as-yet-uncopied bytes of the total concatenated ZCO (referenced by reader) into buffer. If buffer is NULL, skips over length bytes without copying. Returns the number of bytes copied (or skipped) on success, 0 on any file access error, -1 on any other error.
void zco_start_receiving(Object zco, ZcoReader *reader)
Used by overlying protocol layer to start extraction of an inbound ZCO's bytes for \"reception\" -- i.e., the copying of bytes into a memory buffer for delivery to a protocol header parser, to a protocol trailer parser, or to the ultimate recipient (application). Initializes reading of headers, source data, and trailers at the first byte of the concatenated ZCO objects. Populates reader, which is used to keep track of \"reception\" progress via this ZCO reference and is required.
vast zco_receive_headers(Sdr sdr, ZcoReader *reader, vast length, char *buffer)
Copies length as-yet-uncopied bytes of presumptive protocol header text from ZCO source data extents into buffer. If buffer is NULL, skips over length bytes without copying. Returns number of bytes copied (or skipped) on success, 0 on any file access error, -1 on any other error.
void zco_delimit_source(Sdr sdr, Object zco, vast offset, vast length)
Sets the computed offset and length of actual source data in the ZCO, thereby implicitly establishing the total length of the ZCO's concatenated protocol headers as offset and the location of the ZCO's innermost protocol trailer as the sum of offset and length. Offset and length are typically determined from the information carried in received presumptive protocol header text.
vast zco_receive_source(Sdr sdr, ZcoReader *reader, vast length, char *buffer)
Copies length as-yet-uncopied bytes of source data from ZCO extents into buffer. If buffer is NULL, skips over length bytes without copying. Returns number of bytes copied (or skipped) on success, 0 on any file access error, -1 on any other error.
vast zco_receive_trailers(Sdr sdr, ZcoReader *reader, vast length, char *buffer)
Copies length as-yet-uncopied bytes of trailer data from ZCO extents into buffer. If buffer is NULL, skips over length bytes without copying. Returns number of bytes copied (or skipped) on success, 0 on any file access error, -1 on any other error.
void zco_strip(Sdr sdr, Object zco)
Deletes all source data extents that contain only header or trailer data and adjusts the offsets and/or lengths of all remaining extents to exclude any known header or trailer data. This function is useful when handling a ZCO that was received from an underlying protocol layer rather than from an overlying application or protocol layer; use it before starting the transmission of the ZCO to another node or before enqueuing it for reception by an overlying application or protocol layer.
sdr(3)
"},{"location":"man/ltp/","title":"Index of Man Pages","text":"dccplsi - DCCP-based LTP link service input task
"},{"location":"man/ltp/dccplsi/#synopsis","title":"SYNOPSIS","text":"dccplsi {local_hostname | @}[:local_port_nbr]
"},{"location":"man/ltp/dccplsi/#description","title":"DESCRIPTION","text":"dccplsi is a background \"daemon\" task that receives DCCP datagrams via a DCCP socket bound to local_hostname and local_port_nbr, extracts LTP segments from those datagrams, and passes them to the local LTP engine. Host name \"@\" signifies that the host name returned by hostname(1) is to be used as the socket's host name. If not specified, port number defaults to 1113.
The link service input task is spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The link service input task is terminated by ltpadmin in response to an 'x' (STOP) command.
"},{"location":"man/ltp/dccplsi/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccplsi terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart dccplsi.
\"1\"
dccplsi terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart dccplsi.
No configuration files are needed.
"},{"location":"man/ltp/dccplsi/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/dccplsi/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccplsi can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
LSI task is already started.
Redundant initiation of dccplsi.
LSI can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccplsi.
LSI can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccplsi.
LSI can't create listener thread.
Operating system error. Check errtext, correct problem, and restart dccplsi.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/dccplsi/#see-also","title":"SEE ALSO","text":"ltpadmin(1), dccplso(1), owltsim(1)
"},{"location":"man/ltp/dccplso/","title":"NAME","text":"dccplso - DCCP-based LTP link service output task
"},{"location":"man/ltp/dccplso/#synopsis","title":"SYNOPSIS","text":"dccplso {remote_engine_hostname | @}[:remote_port_nbr] remote_engine_nbr
"},{"location":"man/ltp/dccplso/#description","title":"DESCRIPTION","text":"dccplso is a background \"daemon\" task that extracts LTP segments from the queue of segments bound for the indicated remote LTP engine, encapsulates them in DCCP datagrams, and sends those datagrams to the indicated DCCP port on the indicated host. If not specified, port number defaults to 1113.
Each \"span\" of LTP data interchange between the local LTP engine and a neighboring LTP engine requires its own link service output task, such as dccplso. All link service output tasks are spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol, and they are all terminated by ltpadmin in response to an 'x' (STOP) command.
"},{"location":"man/ltp/dccplso/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccplso terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart dccplso.
\"1\"
dccplso terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart dccplso.
No configuration files are needed.
"},{"location":"man/ltp/dccplso/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/dccplso/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccplso can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the LTP database by ltpadmin.
LSO task is already started for this engine.
Redundant initiation of dccplso.
LSO can't create idle thread.
Operating system error. Check errtext, correct problem, and restart dccplso.
LSO can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccplso.
LSO can't connect DCCP socket.
Remote host's dccplsi isn't listening or has terminated. Restart dccplsi on the remote host and then restart dccplso.
Segment is too big for DCCP LSO.
Configuration error: segments that are too large for DCCP transmission (i.e., larger than 65535 bytes) are being enqueued for dccplso. Use ltpadmin to change maximum segment size for this span.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/dccplso/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpmeter(1), dccplsi(1), owltsim(1)
"},{"location":"man/ltp/ltp/","title":"NAME","text":"ltp - Licklider Transmission Protocol (LTP) communications library
"},{"location":"man/ltp/ltp/#synopsis","title":"SYNOPSIS","text":"#include \"ltp.h\"\n\ntypedef enum\n{\n LtpNoNotice = 0,\n LtpExportSessionStart,\n LtpXmitComplete,\n LtpExportSessionCanceled,\n LtpExportSessionComplete,\n LtpRecvGreenSegment,\n LtpRecvRedPart,\n LtpImportSessionCanceled\n} LtpNoticeType;\n\n[see description for available functions]\nThe ltp library provides functions enabling application software to use LTP to send and receive information reliably over a long-latency link. It conforms to the LTP specification as documented by the Delay-Tolerant Networking Research Group of the Internet Research Task Force.
The LTP notion of engine ID corresponds closely to the Internet notion of a host, and in ION engine IDs are normally indistinguishable from node numbers including the node numbers in Bundle Protocol endpoint IDs conforming to the \"ipn\" scheme.
The LTP notion of client ID corresponds closely to the Internet notion of \"protocol number\" as used in the Internet Protocol. It enables data from multiple applications -- clients -- to be multiplexed over a single reliable link. However, for ION operations we normally use LTP exclusively for the transmission of Bundle Protocol data, identified by client ID = 1.
int ltp_attach()
Attaches the application to LTP functionality on the lcoal computer. Returns 0 on success, -1 on any error.
void ltp_detach()
Terminates all access to LTP functionality on the local computer.
int ltp_engine_is_started()
Returns 1 if the local LTP engine has been started and not yet stopped, 0 otherwise.
int ltp_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData, unsigned int redLength, LtpSessionId *sessionId)
Sends a client service data unit to the application that is waiting for data tagged with the indicated clientId as received at the remote LTP engine identified by destinationEngineId.
clientServiceData must be a \"zero-copy object\" reference as returned by ionCreateZco(). Note that LTP will privately make and destroy its own reference to the client service data object; the application is free to destroy its reference at any time.
redLength indicates the number of leading bytes of data in clientServiceData that are to be sent reliably, i.e., with selective retransmission in response to explicit or implicit negative acknowledgment as necessary. All remaining bytes of data in clientServiceData will be sent as \"green\" data, i.e., unreliably. If redLength is zero, the entire client service data unit will be sent unreliably. If the entire client service data unit is to be sent reliably, redLength may be simply be set to LTP_ALL_RED (i.e., -1).
On success, the function populates *sessionId with the source engine ID and the \"session number\" assigned to transmission of this client service data unit and returns zero. The session number may be used to link future LTP processing events, such as transmission cancellation, to the affected client service data. ltp_send() returns -1 on any error.
int ltp_open(unsigned int clientId)
Establishes the application's exclusive access to received service data units tagged with the indicated client service data ID. At any time, only a single application task is permitted to receive service data units for any single client service data ID.
Returns 0 on success, -1 on any error (e.g., the indicated client service is already being held open by some other application task).
int ltp_get_notice(unsigned int clientId, LtpNoticeType *type, LtpSessionId *sessionId, unsigned char *reasonCode, unsigned char *endOfBlock, unsigned int *dataOffset, unsigned int *dataLength, Object *data)
Receives notices of LTP processing events pertaining to the flow of service data units tagged with the indicated client service ID. The nature of each event is indicated by *type. Additional parameters characterizing the event are returned in *sessionId, *reasonCode, *endOfBlock, *dataOffset, *dataLength, and *data as relevant.
The value returned in *data is always a zero-copy object; use the zco_* functions defined in \"zco.h\" to retrieve the content of that object.
When the notice is an LtpRecvGreenSegment, the ZCO returned in *data contains the content of a single LTP green segment. Reassembly of the green part of some block from these segments is the responsibility of the application.
When the notice is an LtpRecvRedPart, the ZCO returned in *data contains the red part of a possibly aggregated block. The ZCO's content may therefore comprise multiple service data objects. Extraction of individual service data objects from the aggregated block is the responsibility of the application. A simple way to do this is to prepend the length of the service data object to the object itself (using zco_prepend_header) before calling ltp_send, so that the receiving application can alternate extraction of object lengths and objects from the delivered block's red part.
The cancellation of an export session may result in delivery of multiple LtpExportSessionCanceled notices, one for each service data unit in the export session's (potentially) aggregated block. The ZCO returned in *data for each such notice is a service data unit ZCO that had previously been passed to ltp_send().
ltp_get_notice() always blocks indefinitely until an LTP processing event is delivered.
Returns zero on success, -1 on any error.
void ltp_interrupt(unsigned int clientId)
Interrupts an ltp_get_notice() invocation. This function is designed to be called from a signal handler; for this purpose, clientId may need to be obtained from a static variable.
void ltp_release_data(Object data)
Releases the resources allocated to hold data, which must be a received client service data ZCO.
void ltp_close(unsigned int clientId)
Terminates the application's exclusive access to received service data units tagged with the indicated client service data ID.
ltpadmin(1), ltprc(5), zco(3)
"},{"location":"man/ltp/ltpadmin/","title":"NAME","text":"ltpadmin - ION Licklider Transmission Protocol (LTP) administration interface
"},{"location":"man/ltp/ltpadmin/#synopsis","title":"SYNOPSIS","text":"ltpadmin [ commands_filename | . | ! ]
"},{"location":"man/ltp/ltpadmin/#description","title":"DESCRIPTION","text":"ltpadmin configures, starts, manages, and stops LTP operations for the local ION node.
It operates in response to LTP configuration commands found in the file commands_filename, if provided; if not, ltpadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to ltpadmin -- that is, the ION node's ltpclock task, ltpmeter tasks, and link service adapter tasks are stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's ltpclock task, ltpmeter tasks, and link service adapter tasks are restarted.
The format of commands for commands_filename can be queried from ltpadmin with the 'h' or '?' commands at the prompt. The commands are documented in ltprc(5).
"},{"location":"man/ltp/ltpadmin/#exit-status","title":"EXIT STATUS","text":"ltpadmin
Enter interactive LTP configuration command entry mode.
ltpadmin host1.ltp
Execute all configuration commands in host1.ltp, then terminate immediately.
ltpadmin .
Stop all LTP operations on the local node.
See ltprc(5) for details of the LTP configuration commands.
"},{"location":"man/ltp/ltpadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ltprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ltpadmin. Otherwise ltpadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ltpadmin can't attach to ION.
There is no SDR data store for ltpadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ltpadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see ltprc(5) for details.
"},{"location":"man/ltp/ltpadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpadmin/#see-also","title":"SEE ALSO","text":"ltpmeter(1), ltprc(5)
"},{"location":"man/ltp/ltpclock/","title":"NAME","text":"ltpclock - LTP daemon task for managing scheduled events
"},{"location":"man/ltp/ltpclock/#synopsis","title":"SYNOPSIS","text":"ltpclock
"},{"location":"man/ltp/ltpclock/#description","title":"DESCRIPTION","text":"ltpclock is a background \"daemon\" task that periodically performs scheduled LTP activities. It is spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol, and it is terminated by ltpadmin in response to an 'x' (STOP) command.
Once per second, ltpclock takes the following action:
First it manages the current state of all links (\"spans\"). In particular, it checks the age of the currently buffered session block for each span and, if that age exceeds the span's configured aggregation time limit, gives the \"buffer full\" semaphore for that span to initiate block segmentation and transmission by ltpmeter.
In so doing, it also infers link state changes (\"link cues\") from data rate changes as noted in the RFX database by rfxclock:
If the rate of transmission to a neighbor was zero but is now non-zero, then transmission to that neighbor is unblocked. The applicable \"buffer empty\" semaphore is given if no outbound block is being constructed (enabling start of a new transmission session) and the \"segments ready\" semaphore is given if the outbound segment queue is non-empty (enabling transmission of segments by the link service output task).
If the rate of transmission to a neighbor was non-zero but is now zero, then transmission to that neighbor is blocked -- i.e., the semaphores triggering transmission will no longer be given.
If the imputed rate of transmission from a neighbor was non-zero but is now zero, then all timers affecting segment retransmission to that neighbor are suspended. This has the effect of extending the interval of each affected timer by the length of time that the timers remain suspended.
If the imputed rate of transmission from a neighbor was zero but is now non-zero, then all timers affecting segment retransmission to that neighbor are resumed.
Then ltpclock retransmits all unacknowledged checkpoint segments, report segments, and cancellation segments whose computed timeout intervals have expired.
"},{"location":"man/ltp/ltpclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart ltpclock.
\"1\"
ltpclock was unable to attach to LTP protocol operations, probably because ltpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/ltp/ltpclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpclock can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
Can't dispatch events.
An unrecoverable database error was encountered. ltpclock terminates.
Can't manage links.
An unrecoverable database error was encountered. ltpclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpclock/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpmeter(1), rfxclock(1)
"},{"location":"man/ltp/ltpcounter/","title":"NAME","text":"ltpcounter - LTP reception test program
"},{"location":"man/ltp/ltpcounter/#synopsis","title":"SYNOPSIS","text":"ltpcounter client_ID [max_nbr_of_bytes]
"},{"location":"man/ltp/ltpcounter/#description","title":"DESCRIPTION","text":"ltpcounter uses LTP to receive service data units flagged with client service number client_ID from a remote ltpdriver client service process. When the total number of bytes of client service data it has received exceeds max_nbr_of_bytes, it terminates and prints reception and cancellation statistics. If max_nbr_of_bytes is omitted, the default limit is 2 billion bytes.
While receiving data, ltpcounter prints a 'v' character every 5 seconds to indicate that it is still alive.
"},{"location":"man/ltp/ltpcounter/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpcounter has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
ltpcounter was unable to start, because it could not attach to the LTP protocol on the local node or could not open access to client service clientId.
In the former case, run ltpadmin to start LTP and try again.
In the latter case, some other client service task has already opened access to client service clientId. If no such task is currently running (e.g., it crashed while holding the client service open), use ltpadmin to stop and restart the LTP protocol.
No configuration files are needed.
"},{"location":"man/ltp/ltpcounter/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpcounter/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by ltpcounter are written to the ION log file ion.log.
ltpcounter can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
ltpcounter can't open client access.
Another task has opened access to service client clientId and has not yet relinquished it.
Can't get LTP notice.
LTP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpcounter/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpdriver(1), ltp(3)
"},{"location":"man/ltp/ltpdriver/","title":"NAME","text":"ltpdriver - LTP transmission test program
"},{"location":"man/ltp/ltpdriver/#synopsis","title":"SYNOPSIS","text":"ltpdriver remoteEngineNbr clientId nbrOfCycles greenLength [ totalLength]
"},{"location":"man/ltp/ltpdriver/#description","title":"DESCRIPTION","text":"ltpdriver uses LTP to send nbrOfCycles service data units of length indicated by totalLength, of which the trailing greenLength bytes are sent unreliably, to the ltpcounter client service process for client service number clientId attached to the remote LTP engine identified by remoteEngineNbr. If omitted, length defaults to 60000. If length is 1, the sizes of the transmitted service data units will be randomly selected multiples of 1024 in the range 1024 to 62464.
Whenever the size of the transmitted service data unit is less than or equal to greenLength, the entire SDU is sent unreliably.
When all copies of the file have been sent, ltpdriver prints a performance report.
"},{"location":"man/ltp/ltpdriver/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpdriver has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
ltpdriver was unable to start, because it could not attach to the LTP protocol on the local node. Run ltpadmin to start LTP, then try again.
The service data units transmitted by ltpdriver are sequences of text obtained from a file in the current working directory named \"ltpdriverAduFile\", which ltpdriver creates automatically.
"},{"location":"man/ltp/ltpdriver/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpdriver/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by ltpdriver are written to the ION log file ion.log.
ltpdriver can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
Can't create ADU file
Operating system error. Check errtext, correct problem, and rerun.
Error writing to ADU file
Operating system error. Check errtext, correct problem, and rerun.
ltpdriver can't create file ref.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
ltpdriver can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
ltpdriver can't send message.
LTP span to the remote engine has been stopped.
ltp_send failed.
LTP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpdriver/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpcounter(1), ltp(3)
"},{"location":"man/ltp/ltpmeter/","title":"NAME","text":"ltpmeter - LTP daemon task for aggregating and segmenting transmission blocks
"},{"location":"man/ltp/ltpmeter/#synopsis","title":"SYNOPSIS","text":"ltpmeter remote_engine_nbr
"},{"location":"man/ltp/ltpmeter/#description","title":"DESCRIPTION","text":"ltpmeter is a background \"daemon\" task that manages the presentation of LTP segments to link service output tasks. Each \"span\" of LTP data interchange between the local LTP engine and a neighboring LTP engine requires its own ltpmeter task. All ltpmeter tasks are spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol, and they are all terminated by ltpadmin in response to an 'x' (STOP) command.
ltpmeter waits until its span's current transmission block (the data to be transmitted during the transmission session that is currently being constructed) is ready for transmission, then divides the data in the span's block buffer into segments and enqueues the segments for transmission by the span's link service output task (giving the segments semaphore to unblock the link service output task as necessary), then reinitializes the span's block buffer and starts another session (giving the \"buffer empty\" semaphore to unblock the client service task -- nominally ltpclo, the LTP convergence layer output task for Bundle Protocol -- as necessary).
ltpmeter determines that the current transmission block is ready for transmission by waiting until either (a) the aggregate size of all service data units in the block's buffer exceeds the aggregation size limit for this span or (b) the length of time that the first service data unit in the block's buffer has been awaiting transmission exceeds the aggregation time limit for this span. The \"buffer full\" semaphore is given when ION (either the ltp_send() function or the ltpclock daemon) determines that one of these conditions is true; ltpmeter simply waits for this semaphore to be given.
The initiation of a new session may also be blocked: the total number of transmission sessions that the local LTP engine may have open at a single time is limited (this is LTP flow control), and while the engine is at this limit no new sessions can be started. Availability of a session from the session pool is signaled by the \"session\" semaphore, which is given whenever a session is completed or canceled.
"},{"location":"man/ltp/ltpmeter/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpmeter terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart ltpmeter.
\"1\"
ltpmeter terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart ltpmeter.
No configuration files are needed.
"},{"location":"man/ltp/ltpmeter/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpmeter/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpmeter can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the LTP database by ltpadmin.
ltpmeter task is already started for this engine.
Redundant initiation of ltpmeter.
ltpmeter can't start new session.
An unrecoverable database error was encountered. ltpmeter terminates.
Can't take bufClosedSemaphore.
An unrecoverable database error was encountered. ltpmeter terminates.
Can't create extents list.
An unrecoverable database error was encountered. ltpmeter terminates.
Can't post ExportSessionStart notice.
An unrecoverable database error was encountered. ltpmeter terminates.
Can't finish session.
An unrecoverable database error was encountered. ltpmeter terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpmeter/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpclock(1)
"},{"location":"man/ltp/ltprc/","title":"NAME","text":"ltprc - Licklider Transmission Protocol management commands file
"},{"location":"man/ltp/ltprc/#description","title":"DESCRIPTION","text":"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.
"},{"location":"man/ltp/ltprc/#commands","title":"COMMANDS","text":"?
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.
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.
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).
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.
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.
ltpadmin(1), udplsi(1), udplso(1)
"},{"location":"man/ltp/ltpsecadmin/","title":"NAME","text":"ltpsecadmin - LTP security policy administration interface
"},{"location":"man/ltp/ltpsecadmin/#synopsis","title":"SYNOPSIS","text":"ltpsecadmin [ commands_filename ]
"},{"location":"man/ltp/ltpsecadmin/#description","title":"DESCRIPTION","text":"ltpsecadmin configures and manages LTP security policy on the local computer.
It configures and manages LTP security policy on the local computer in response to LTP configuration commands found in commands_filename, if provided; if not, ltpsecadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from ltpsecadmin by entering the command 'h' or '?' at the prompt. The commands are documented in ltpsecrc(5).
"},{"location":"man/ltp/ltpsecadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of LTP security policy administration.
ltpsecadmin
Enter interactive LTP security policy administration command entry mode.
ltpsecadmin host1.ltpsecrc
Execute all configuration commands in host1.ltpsecrc, then terminate immediately.
Status and diagnostic messages from ltpsecadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which ltpsecadmin was run. The log file is typically named ion.log.
See also ltpsecrc(5).
"},{"location":"man/ltp/ltpsecadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpsecadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ltpsecadmin. Otherwise ltpsecadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ltpsecadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see ltpsecrc(5) for details.
"},{"location":"man/ltp/ltpsecadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpsecadmin/#see-also","title":"SEE ALSO","text":"ltpsecrc(5)
"},{"location":"man/ltp/ltpsecrc/","title":"NAME","text":"ltpsecrc - LTP security policy management commands file
"},{"location":"man/ltp/ltpsecrc/#description","title":"DESCRIPTION","text":"LTP security policy management commands are passed to ltpsecadmin either in a file of text lines or interactively at ltpsecadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the LTP security policy management commands are described below.
"},{"location":"man/ltp/ltpsecrc/#commands","title":"COMMANDS","text":"?
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 ltpsecadmin 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.
a ltprecvauthrule ltp_engine_id ciphersuite_nbr [key_name]
The add ltprecvauthrule command. This command adds a rule specifying the manner in which LTP segment authentication will be applied to LTP segments received from the indicated LTP engine.
A segment from the indicated LTP engine will only be deemed authentic if it contains an authentication extension computed via the ciphersuite identified by ciphersuite_nbr using the applicable key value. If ciphersuite_nbr is 255 then the applicable key value is a hard-coded constant and key_name must be omitted; otherwise key_name is required and the applicable key value is the current value of the key named key_name in the local security policy database.
Valid values of ciphersuite_nbr are:
0: HMAC-SHA1-80\n1: RSA-SHA256\n255: NULL\nc ltprecvauthrule ltp_engine_id ciphersuite_nbr [key_name]
The change ltprecvauthrule command. This command changes the parameters of the LTP segment authentication rule for the indicated LTP engine.
d ltprecvauthrule ltp_engine_id
The delete ltprecvauthrule command. This command deletes the LTP segment authentication rule for the indicated LTP engine.
i ltprecvauthrule ltp_engine_id
This command will print information (the LTP engine id, ciphersuite number, and key name) about the LTP segment authentication rule for the indicated LTP engine.
l ltprecvauthrule
This command lists all LTP segment authentication rules in the security policy database.
a ltpxmitauthrule ltp_engine_id ciphersuite_nbr [key_name]
The add ltpxmitauthrule command. This command adds a rule specifying the manner in which LTP segments transmitted to the indicated LTP engine must be signed.
Signing a segment destined for the indicated LTP engine entails computing an authentication extension via the ciphersuite identified by ciphersuite_nbr using the applicable key value. If ciphersuite_nbr is 255 then the applicable key value is a hard-coded constant and key_name must be omitted; otherwise key_name is required and the applicable key value is the current value of the key named key_name in the local security policy database.
Valid values of ciphersuite_nbr are:
0: HMAC\\_SHA1-80\n1: RSA\\_SHA256\n255: NULL\nc ltpxmitauthrule ltp_engine_id ciphersuite_nbr [key_name]
The change ltpxmitauthrule command. This command changes the parameters of the LTP segment signing rule for the indicated LTP engine.
d ltpxmitauthrule ltp_engine_id
The delete ltpxmitauthrule command. This command deletes the LTP segment signing rule for the indicated LTP engine.
i ltpxmitauthrule ltp_engine_id
This command will print information (the LTP engine id, ciphersuite number, and key name) about the LTP segment signing rule for the indicated LTP engine.
l ltpxmitauthrule
This command lists all LTP segment signing rules in the security policy database.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
ltpsecadmin(1)
"},{"location":"man/ltp/sda/","title":"NAME","text":"sda - LTP Service Data Aggregation (SDA) library
"},{"location":"man/ltp/sda/#synopsis","title":"SYNOPSIS","text":"#include \"sda.h\"\n\ntypedef vast (*SdaDelimiterFn)(unsigned int clientId, unsigned char *buffer, vast bufferLength);\n\ntypedef int (*SdaHandlerFn)(uvast sourceEngineId, unsigned int clientId, Object clientServiceData);\n\n[see description for available functions]\nThe sda library provides functions enabling application software to use LTP more efficiently, by aggregating multiple small client service data units into larger LTP client service data items. This reduces overhead somewhat, but more importantly it reduces the volume of positive and negative LTP acknowledgment traffic by sending more data in fewer LTP blocks -- because LTP acknowledgments are issued on a per-block basis.
The library relies on the application to detect the boundaries between aggregated service data units in each received LTP client service data item; the application must provide an SdaDelimiterFn function for this purpose. An SDA delimiter function inspects the client service data bytes in buffer - some portion of an LTP service data block, of length bufferLength - to determine the length of the client service data unit at the start of the buffer; data unit client service ID is provided to aid in this determination. The function returns that length if the determination was successful, zero if there is no valid client service data item at the start of the buffer, -1 on any system failure.
The sda library similarly relies on the application to process the service data units identified in this manner; the application must provide an SdaHandlerFn function for this purpose. An SDA handler function is provided with the ID of the LTP engine that sent the service data unit, the client ID characterizing the service data unit, and the service data unit itself; the service data unit is presented as a Zero-Copy Object (ZCO). The handler function must return -1 on any system error, zero otherwise.
int sda_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData);
Sends a client service data unit to an application, identified by clientId, at the LTP engine identified by destinationEngineId. clientServiceData must be a \"zero-copy object\" reference as returned by ionCreateZco(). Note that SDA will privately make and destroy its own reference to the client service data; the application is free to destroy its reference at any time. Note that the client service data unit will always be sent reliably (i.e., \"red\").
Also note that sda_run() must be executing in order for sda_send to be performed.
Returns 0 on success, -1 on any system failure.
int sda_run(SdaDelimiterFn delimiter, SdaHandlerFn handler);
sda_run() executes an infinite loop that receives LTP client service data items, calls delimiter to determine the length of each client service data unit in each item, and passes those client service data units to the handler function. To terminate the loop, call sda_interrupt(). Note that sda_send() can only be executed while the sda_run() loop is still executing.
Returns 0 on success, -1 on any system failure.
void sda_interrupt();
Interrupts sda_run().
sdatest(1), zco(3)
"},{"location":"man/ltp/sdatest/","title":"NAME","text":"sdatest - LTP service data aggreggation test program
"},{"location":"man/ltp/sdatest/#synopsis","title":"SYNOPSIS","text":"sdatest [remoteEngineNbr]
"},{"location":"man/ltp/sdatest/#description","title":"DESCRIPTION","text":"sdatest tests LTP service data aggregation (SDA).
Each instance of the program can run either as a sender and receiver or as a receiver only. For sending, sdatest starts a background thread that offers a command-line prompt and accepts strings of text for transmission. It uses SDA to aggregate the strings into LTP service data items for LTP client ID 2, which is SDA. The strings (SDA data units) are delimited by terminating NULLs, and they are all identified by SDA client ID number 135.
For reception, sdatest listens for LTP traffic for client 2. When it receives an LTP Service data item (in an LTP block), it parses out all of the SDA data units aggregated in that data item and prints them to stdout.
Use ^C to terminate sdatest.
"},{"location":"man/ltp/sdatest/#exit-status","title":"EXIT STATUS","text":"\"0\"
sdatest has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
sdatest was unable to start. See the ion.log file for details.
No files are used by sdatest.
"},{"location":"man/ltp/sdatest/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/sdatest/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by sdatest are written to the ION log file ion.log.
"},{"location":"man/ltp/sdatest/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/sdatest/#see-also","title":"SEE ALSO","text":"sda(3)
"},{"location":"man/ltp/udplsi/","title":"NAME","text":"udplsi - UDP-based LTP link service input task
"},{"location":"man/ltp/udplsi/#synopsis","title":"SYNOPSIS","text":"udplsi {local_hostname | @}[:local_port_nbr]
"},{"location":"man/ltp/udplsi/#description","title":"DESCRIPTION","text":"udplsi is a background \"daemon\" task that receives UDP datagrams via a UDP socket bound to local_hostname and local_port_nbr, extracts LTP segments from those datagrams, and passes them to the local LTP engine. Host name \"@\" signifies that the host name returned by hostname(1) is to be used as the socket's host name. If not specified, port number defaults to 1113.
The link service input task is spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The link service input task is terminated by ltpadmin in response to an 'x' (STOP) command.
"},{"location":"man/ltp/udplsi/#exit-status","title":"EXIT STATUS","text":"\"0\"
udplsi terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart udplsi.
\"1\"
udplsi terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart udplsi.
No configuration files are needed.
"},{"location":"man/ltp/udplsi/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/udplsi/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udplsi can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
LSI task is already started.
Redundant initiation of udplsi.
LSI can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udplsi.
LSI can't initialize socket
Operating system error. Check errtext, correct problem, and restart udplsi.
LSI can't create receiver thread
Operating system error. Check errtext, correct problem, and restart udplsi.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/udplsi/#see-also","title":"SEE ALSO","text":"ltpadmin(1), udplso(1), owltsim(1)
"},{"location":"man/ltp/udplso/","title":"NAME","text":"udplso - UDP-based LTP link service output task
"},{"location":"man/ltp/udplso/#synopsis","title":"SYNOPSIS","text":"udplso {remote_engine_hostname | @}[:remote_port_nbr] remote_engine_nbr
"},{"location":"man/ltp/udplso/#description","title":"DESCRIPTION","text":"udplso is a background \"daemon\" task that extracts LTP segments from the queue of segments bound for the indicated remote LTP engine, encapsulates them in UDP datagrams, and sends those datagrams to the indicated UDP port on the indicated host. If not specified, port number defaults to 1113.
Each \"span\" of LTP data interchange between the local LTP engine and a neighboring LTP engine requires its own link service output task, such as udplso. All link service output tasks are spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol, and they are all terminated by ltpadmin in response to an 'x' (STOP) command.
"},{"location":"man/ltp/udplso/#exit-status","title":"EXIT STATUS","text":"\"0\"
udplso terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart udplso.
\"1\"
udplso terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart udplso.
No configuration files are needed.
"},{"location":"man/ltp/udplso/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/udplso/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udplso can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the LTP database by ltpadmin.
LSO task is already started for this engine.
Redundant initiation of udplso.
LSO can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udplso.
LSO can't connect UDP socket
Operating system error. Check errtext, correct problem, and restart udplso.
Segment is too big for UDP LSO.
Configuration error: segments that are too large for UDP transmission (i.e., larger than 65535 bytes) are being enqueued for udplso. Use ltpadmin to change maximum segment size for this span.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/udplso/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpmeter(1), udplsi(1), owltsim(1)
"},{"location":"man/nm/","title":"Index of Man Pages","text":"nm_agent - Network Management Agent implementing the Asynchronous Management Protocol (AMP)
"},{"location":"man/nm/nm_agent/#synopsis","title":"SYNOPSIS","text":"nm_agent <agent eid> manager eid
"},{"location":"man/nm/nm_agent/#description","title":"DESCRIPTION","text":"Starts the network management agent listening on agent eid and communicating with a remote manager at manager eid
"},{"location":"man/nm/nm_agent/#see-also","title":"SEE ALSO","text":"Asynchronous Management Protocol
nm_mgr(1)
"},{"location":"man/nm/nm_mgr/","title":"NAME","text":"nm_mgr - Network Management server implementing the Asynchronous Management Protocol (AMP)
"},{"location":"man/nm/nm_mgr/#synopsis","title":"SYNOPSIS","text":"nm_mgr [options] manager eid
The following options may be specified to customize behavior. Use \"nm_mgr --help\" for full usage information:
-A
Startup directly in the alternative Automator UI mode. This mode is designed to provide a consistent line-based interface suitable for automated scripting. Type ? when active for usage details.
-l
If specified, enable file-based logging of Manager Activity on startup. This can be toggled at any time from the main menu of the UI.
If logging is not enabled, the following arguments have no affect until enabled in UI.
-d
Log each agent to a different directory.
-L #
Specify maximum number of entries (reports+tables) per file before rotating.
-D DIR
NM logs will be placed in this directory.
-r
Log all received reports to file in text format (as shown in UI).
-t
Log all received tables to file in text format (as shown in UI).
-T
Log all transmitted message as ASCII-encoded CBOR HEX strings.
-R
Log all received messages as ASCII-encoded CBOR HEX strings.
Starts the nm_mgr application listening on mgr eid for messages from nm_agent clients. Specify \"--help\" for full usage information.
An agent will automatically attempt to register with it's configured manager on startup. Agents may also be added manually through the managers UI.
The manager provides a text based UI as its primary interface. The UI provides capabilities to list, register, or delete agents. It can view received reports and tables, and be used to send commands (ARIs) to registered agents.
An experimental REST API is available if built with the configuration option \"--enable-rest\". The default configuration will be accessible at http://localhost:8089/nm/api.
"},{"location":"man/nm/nm_mgr/#see-also","title":"SEE ALSO","text":"Asynchronous Management Protocol
nm_agent(1)
"},{"location":"man/restart/","title":"Index of Man Pages","text":"ionrestart - ION node restart utility
"},{"location":"man/restart/ionrestart/#synopsis","title":"SYNOPSIS","text":"ionrestart
"},{"location":"man/restart/ionrestart/#description","title":"DESCRIPTION","text":"ionrestart is a utility task that is executed automatically when an ION transaction fails, provided transaction reversibility is enabled (see ionconfig(5)). It should never need to be executed from the command line.
When an ION transaction is reversed, all changes made to the SDR non-volatile heap in the course of the transaction are backed out but changes made to ION's working memory are not. (Forward logging of these changes to enable automatic reversal on these relatively rare occasions is judged to impose too much continuous processing overhead to be cost-justified.) Because the state of working memory is thereupon in conflict with information in the heap, ionrestart is automatically invoked to reload all of working memory; because this would obviously threaten the stability of all running ION tasks, ionrestart gracefully terminates the tasks of the node (not only ION daemons but also applications), then reloads working memory from the recovered heap, and finally restarts the ION daemons. Applications that receive termination indications from ionrestart may choose to sleep for a few seconds and then automatically re-initialize their own operations.
ionrestart will attempt to restart all core ION protocols including LTP, BP, and CFDP, but any protocols which were not operating at the time of the transaction reversal are not restarted. Also, protocols that ionrestart has not yet been adapted to cleanly terminate and restart (including, at the time of this writing, BSSP and DPTC) are not restarted.
"},{"location":"man/restart/ionrestart/#exit-status","title":"EXIT STATUS","text":"\"0\"
ionrestart terminated normally.
\"1\"
ionrestart failed, for reasons noted in the ion.log file; the task terminated.
No configuration files are used beyond those required for normal ION node initialization.
"},{"location":"man/restart/ionrestart/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/restart/ionrestart/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/restart/ionrestart/#see-also","title":"SEE ALSO","text":"ionadmin(1), ltpadmin(1), bpadmin(1), cfdpadmin(1)
"},{"location":"man/tc/","title":"Index of Man Pages","text":"dtka - Delay-Tolerant Key Administration (DTKA) daemon
"},{"location":"man/tc/dtka/#synopsis","title":"SYNOPSIS","text":"dtka
dtka is a delay-tolerant public key infrastructure (PKI) system, built on the Trusted Collective (TC) application framework. Each DTKA daemon generates public/private key pairs and uses the TC framework to distribute public keys securely and to receive the public keys generated and distributed by other DTKA daemons. For an overview of TC, see the tc(3) manual page.
"},{"location":"man/tc/dtka/#description","title":"DESCRIPTION","text":"The DTKA system provides a trustworthy mechanism for delay-tolerant distribution of public keys, enabling ION's BP and LTP implementations to utilize asymmetric cryptography to ensure the integrity and/or confidentiality of data exchange as necessary. (Discussion of asymmetric cryptography is beyond the scope of this manual page.)
A central principle of DTKA is that keys have effective times which condition their applicability. For example, the public key that must be used to encrypt a bundle payload destined for a given node is the public key (asserted by that node) whose associated effective time is greatest among all of that node's public keys whose associated effective times are less than or equal to the creation time of the bundle. Effective times enable keys to be distributed far in advance of the times at which they will be used, which is what makes DTKA delay-tolerant: when the time arrives at which a node needs a given key, the key is already in place.
The dtka daemon is responsible for periodically generating, on behalf of a given DTN node, public/private key pairs that will be effective at times in the future.
The first public key generated by a given DTN node's dtka daemon is distributed by means of an application-specific DTKA initialization procedure. The procedure may be an out-of-band mechanism by which the initializing node's public key is generated and submitted to the DTKA authority while the user node is under the physical control of the DTKA authority's administrator. Alternatively, the initializing node's public key may be submitted to the DTKA authority by some other DTN node whose dtka daemon is known to the DTKA authority and is trusted, in which case that node utilizes the TC framework on behalf of the initializing node.
Each subsequently generated public key is signed in the node's applicable private key and is submitted directly to the DTKA authority by means of the TC framework.
Public key revocations, generated by the DTKA authority's administrator, are submitted in the same way as assertions of new public keys.
NOTE that dtka utilizes functions provided by cryptography software that is not distributed with ION. To indicate that this supporting software has been installed, set the compiler flag -DCRYPTO_SOFTWARE_INSTALLED when compiling this program. Absent that flag setting at compile time, the dtka daemon's generateKeyPair() function does nothing.
"},{"location":"man/tc/dtka/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtka terminated, for reasons noted in the ion.log file.
\"1\"
dtka was unable to attach to TC client functionality, possibly because tcc is not running.
The dtkaadmin utility is used to configure the operation of the dtka daemon; see the dtkarc(5) man page for details.
"},{"location":"man/tc/dtka/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/dtka/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/dtka/#see-also","title":"SEE ALSO","text":"dtkaadmin(1), dtkarc(5), tc(3), tcc(1), tccadmin(1), tccrc(5)
"},{"location":"man/tc/dtkaadmin/","title":"NAME","text":"dtkaadmin - DTKA user function administration interface
"},{"location":"man/tc/dtkaadmin/#synopsis","title":"SYNOPSIS","text":"dtkaadmin [ commands_filename ]
"},{"location":"man/tc/dtkaadmin/#description","title":"DESCRIPTION","text":"dtkaadmin configures and manages the DTKA administration database for the local ION node, enabling the node to utilize the services of the Trusted Collective for Delay-Tolerant Key Administration.
It configures and manages that database in response to DTKA configuration commands found in commands_filename, if provided; if not, dtkaadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from dtkaadmin by entering the command 'h' or '?' at the prompt. The commands are documented in dtkarc(5).
"},{"location":"man/tc/dtkaadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of DTKA configuration.
dtkaadmin
Enter interactive DTKA configuration command entry mode.
dtkaadmin host1.karc
Execute all configuration commands in host1.karc, then terminate immediately.
Status and diagnostic messages from dtkaadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which dtkaadmin was run. The log file is typically named ion.log.
See also dtkarc(5).
"},{"location":"man/tc/dtkaadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/dtkaadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the dtkarc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to dtkaadmin. Otherwise dtkaadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause dtkaadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see dtkarc(5) for details.
"},{"location":"man/tc/dtkaadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/dtkaadmin/#see-also","title":"SEE ALSO","text":"dtka(1), dtkarc(5)
"},{"location":"man/tc/dtkarc/","title":"NAME","text":"dtkarc - DTKA user configuration commands file
"},{"location":"man/tc/dtkarc/#description","title":"DESCRIPTION","text":"DTKA user configuration commands are passed to dtkaadmin either in a file of text lines or interactively at dtkaadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the DTKA user function administration commands are described below.
"},{"location":"man/tc/dtkarc/#commands","title":"COMMANDS","text":"?
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 dtkaadmin to be logged as well as sent to stdout. Setting echo to 0 disables this behavior.
1
The initialize command. Until this command is executed, the DTKA user function is not in operation on the local ION node and most dtkaadmin commands will fail.
i
The info This command will print information about the current state of the local node's DTKA user function, including the current settings of all parameters that can be managed as described below.
m keygentime time
The manage key generation time command. This command sets the time at which the node will next generate a public/private key pair and multicast the public key. The command is not needed in normal operations, because future key generation times are computed automatically as key pairs are generated. time must be in yyyy/mm/dd-hh:mm:ss format.
m interval key_pair_generation_interval
The manage key pair generation interval command. This interval, expressed as a number of seconds, controls the period on which the DTKA user function will generate new public/private key pairs. The default value is 604800 (one week).
m leadtime key_pair_effectivenes_lead_time
The manage key pair effectivenes lead time command. This interval, expressed as a number of seconds, controls the length of time after the time of key pair generation at which the key pair will become effective. The default value is 345600 (four days).
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
m interval 3600
Asserts that the DTKA function will generate a new key pair every 3600 seconds (one hour).
dtkaadmin(1)
"},{"location":"man/tc/tc/","title":"NAME","text":"tc - the Trusted Collective system for Delay-Tolerant Networking
"},{"location":"man/tc/tc/#synopsis","title":"SYNOPSIS","text":"#include \"tcc.h\"\n\n[see description for available functions]\nThe TC system provides a trustworthy framework for delay-tolerant distribution of information that is of critical importance - that is, information that must be made available as needed and must not be corrupt - but is not confidential. As such it accomplishes some of the same objectives as are accomplished by \"servers\" in the Internet.
A central principle of TC is that items of critical information may have effective times which condition their applicability. For example, a change in rules restricting air travel will typically be scheduled to take effect on some stated date in the near future. Effective times enable critical information to be distributed far in advance of the time at which it will be needed, which is what makes TC delay-tolerant: when the time arrives at which a node needs a given item of critical information, the information is already in place. No query/response exchange is necessary.
The TC framework for a given TC application comprises (a) a collective authority, which should include several geographically distributed \"authority\" nodes, and (b) \"client\" nodes which utilize the services of the collective authority, possibly including the key authority nodes themselves. The framework is designed to convey to every participating client node the critical information submitted to the collective authority by all other participating client nodes, in a trustworthy manner, prior to the times at which those items of information become effective. It operates as follows.
The user function of a given TC application generates records containing critical information and issues those records as the application data units forming the payloads of BP bundles. The destination of each such bundle is the multicast group designated for receivers of the records of that application. The members of that multicast group are the authority nodes of the application's collective authority.
The records are delivered to the tcarecv daemons of the authority nodes. Each such daemon validates the received records and inserts all valid records in its authority node's private database of pending records.
Periodically, the tcacompile daemons of all authority nodes in the application's collective authority simultaneously compile bulletins of all records recently received from user nodes. (A TC bulletin is simply an array of contiguous TC records.) These daemons then all issue their bulletins as the application data units forming the payloads of BP bundles. The destination of each such bundle is the multicast group designated for receivers of the bulletins of that application. The members of that multicast group are, again, the authority nodes of the application's collective authority. In addition, each tcacompile daemon spawns one tcapublish process that is assigned the task of processing the bulletins compiled by all authority nodes during this iteration of the compilation cycle.
The bulletins are delivered to the tcapublish processes of all authority nodes in the application's collective authority. The tcapublish processes then compute a common consensus bulletin, which includes all recently asserted records that all of the authority nodes have received and found valid.
Each tcapublish process then computes a hash for the consensus bulletin and erasure-codes the bulletin, producing a list of code blocks; the hashes and lists of blocks will be identical for all key authority nodes. It then issues a small subset of those code blocks as the application data units forming the payloads of BP bundles. The destination of each such bundle is the multicast group designated for receivers of the code blocks of the application. The members of that multicast group are the tcc (that is, TC client) daemons serving the application's user nodes. The subsets of the block list issued by all tcapublish daemons are different, but each code block is tagged with the common bulletin hash.
The code blocks are delivered to the tcc daemons of all of the application's user nodes, each of which uses the received code blocks to reassemble the consensus bulletin. Code blocks with differing bulletin hashes are not used to reassemble the same bulletin, and the erasure coding of the bulletin prevents failure to receive all code blocks from preventing reassembly of the complete bulletin. When a consensus bulletin has been successfully reassembled, the records in the bulletin are delivered to the user function.
The tcaboot and tcaadmin utilities are used to configure the collective authority of a given TC application; the tccadmin utility is used to configure TC client functionality for a given TC application on a given user node.
The TC library functions provided to TC application user software are described below.
int tc_serialize(char *buffer, unsigned int buflen, uvast nodeNbr, time_t effectiveTime, time_t assertionTime, unsigned short datLength, unsigned char *datValue)
Forms in buffer a serialized TC record, ready for transmission as a BP application data unit, that contains the indicated node number, effective time, assertion time, application data length, and application data. Returns the length of the record, or -1 on any missing arguments.
int tcc_getBulletin(int blocksGroupNbr, char **bulletinContent, int *length)
Places in *bulletinContent a pointer to an ION private working memory buffer containing the content of the oldest previously unhandled received TC bulletin for the application identified by blocksGroupNbr. Returns 0 on success, -1 on any system failure. A returned buffer length of 0 indicates that the function was interrupted and must be repeated.
Note that the calling function MUST MRELEASE the bulletin content buffer when processing is complete. Failure to do so will introduce a memory leak.
int tc_deserialize(char **buffer, int *buflen, unsigned short maxDatLength, uvast *nodeNbr, time_t *effectiveTime, time_t *assertionTime, unsigned short *datLength, unsigned char *datValue)
Parses out of the bulletin in buffer the data elements of a single serialized TC record: node number, effective time, assertion time, application data length, and application data. Returns -1 on any missing arguments, 0 on any record malformation, record length otherwise.
tcaboot(1), tcaadmin(1), tcarecv(1), tcacompile(1), tcapublish(1), tccadmin(1), tcc(1)
"},{"location":"man/tc/tcaadmin/","title":"NAME","text":"tcaadmin - Trusted Collective (TC) authority administration interface
"},{"location":"man/tc/tcaadmin/#synopsis","title":"SYNOPSIS","text":"tcaadmin blocks_group_number [ commands_filename ]
"},{"location":"man/tc/tcaadmin/#description","title":"DESCRIPTION","text":"tcaadmin configures and manages the Trusted Collective authority databases for TC applications on the local ION node, enabling the node to function as a member of one or more collective authorities.
The first command-line argument to tcaadmin is blocksGroupNumber, which identifies the specific TC application to which all commands submitted to this instance of tcaadmin will apply. A TC application is uniquely identified by the group number of the Bundle Protocol multicast group comprising all nodes hosting TC clients that subscribe to TC \"blocks\" published for that application.
tcaadmin configures and manages a TC authority database in response to authority configuration commands found in commands_filename, if provided; if not, tcaadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from tcaadmin by entering the command 'h' or '?' at the prompt. The commands are documented in tcarc(5).
"},{"location":"man/tc/tcaadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of TC authority administration.
tcaadmin 203
Enter interactive TC authority administration command entry mode for application 203.
tcaadmin 203 host1.tcarc
Apply the application-203 configuration commands in host1.tcarc, then terminate immediately.
Status and diagnostic messages from tcaadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which tcaadmin was run. The log file is typically named ion.log.
See also tcarc(5).
"},{"location":"man/tc/tcaadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcaadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the tcarc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to tcaadmin. Otherwise tcaadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause tcaadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see tcarc(5) for details.
"},{"location":"man/tc/tcaadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcaadmin/#see-also","title":"SEE ALSO","text":"tcacompile(1), tcapublish(1), tcarecv(1), tcarc(5)
"},{"location":"man/tc/tcaboot/","title":"NAME","text":"tcaboot - Trusted Collective (TC) authority initialization utility
"},{"location":"man/tc/tcaboot/#synopsis","title":"SYNOPSIS","text":"tcaboot multicast_group_number_for_TC_bulletins multicast_group_number_for_TC_records number_of_authorities_in_collective K R [ delay ]
"},{"location":"man/tc/tcaboot/#description","title":"DESCRIPTION","text":"tcaboot writes a TC authority administration command file that initializes a TC authority database. The file, named \"boot.tcarc\", is written to the current working directory. It simply contains two authority configuration commands that initialize the TC authority database for the TC application and then set the initial bulletin compilation time for this authority to the current ctime plus delay seconds. If omitted, delay defaults to 5. The other command-line arguments for tcaboot are discussed in the descriptions of application initialization commands for tcaadmin; see the tcarc(5) manual page for details.
"},{"location":"man/tc/tcaboot/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful generation of TC authority initialization file.
tcaboot 210 209 6 50 .2
Writes a boot.tcarc file that initializes the local node's TC authority database as indicated and sets the next bulletin compilation time to the current time plus 5 seconds.
tcaboot 210 209 6 50 .2 90
Writes a boot.tcarc file that initializes the local node's TC authority database as indicated and sets the next bulletin compilation time to the current time plus 90 seconds.
No files apply.
"},{"location":"man/tc/tcaboot/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcaboot/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the log file:
Can't open cmd file
tcaboot is unable to create a file named boot.tcarc for the indicated reason, a system error.
Can't write to cmd file
tcaboot is unable to write to boot.tcarc for the indicated reason, a system error.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcaboot/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tcarc(5)
"},{"location":"man/tc/tcacompile/","title":"NAME","text":"tcacompile - Trusted Collective daemon task for compiling critical information bulletins
"},{"location":"man/tc/tcacompile/#synopsis","title":"SYNOPSIS","text":"tcacompile blocks_group_number
"},{"location":"man/tc/tcacompile/#description","title":"DESCRIPTION","text":"tcacompile is a background \"daemon\" task that periodically generates new proposed bulletins of recent critical information records and multicasts those bulletins to all nodes in the collective authority for the TC application identified by blocks_group_number. It is spawned automatically by tcaadmin in response to the 's' command that starts operation of the TC authority function for this application on the local node, and it is terminated by tcaadmin in response to an 'x' (STOP) command.
"},{"location":"man/tc/tcacompile/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcacompile terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use tcaadmin to restart tcacompile.
\"1\"
tcacompile was unable to attach to TC authority operations, probably because tcaadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/tc/tcacompile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcacompile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcacompile can't attach to tca system.
tcaadmin has not yet initialized the authority database for this TC application.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcacompile/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tc(3), tcarc(5)
"},{"location":"man/tc/tcapublish/","title":"NAME","text":"tcapublish - Trusted Collective authority task that publishes consensus critical information bulletins
"},{"location":"man/tc/tcapublish/#synopsis","title":"SYNOPSIS","text":"tcapublish blocks_group_number
"},{"location":"man/tc/tcapublish/#description","title":"DESCRIPTION","text":"tcapublish is a background task that completes the processing of a single iteration of the bulletin publication cycle for the collective authority function of the TC application identified by blocks_group_number on the local node. To do so, it receives proposed bulletins multicast by tcacompile daemons, resolves differences among the received bulletins to arrive at a consensus bulletin, computes a hash for the consensus bulletin, erasure-codes the consensus bulletin, and multicasts that subset of the resulting code blocks that is allocated to the local node according to the local node's assigned position in the authority array of the application's collective authority. It is spawned automatically by the local node's tcacompile daemon for the indicated application, at the time that daemon publishes its own proposed bulletin for this iteration of the bulletin compilation cycle; it terminates immediately after it has finished publishing code blocks.
"},{"location":"man/tc/tcapublish/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcapublish terminated, for reasons noted in the ion.log file.
\"1\"
tcapublish was unable to attach to TC authority operations, probably because tcaadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/tc/tcapublish/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcapublish/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcapublish can't attach to DTKA.
tcaadmin has not yet initialized the authority database for this TC application.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcapublish/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tc(3), tcauthrc(5)
"},{"location":"man/tc/tcarc/","title":"NAME","text":"tcarc - Trusted Collective authority configuration commands file
"},{"location":"man/tc/tcarc/#description","title":"DESCRIPTION","text":"TC authority configuration commands are passed to tcaadmin either in a file of text lines or interactively at tcaadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the TC authority configuration commands are described below.
"},{"location":"man/tc/tcarc/#commands","title":"COMMANDS","text":"?
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 tcaadmin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
1 multicast_group_number_for_TC_bulletins multicast_group_number_for_TC_records number_of_authorities_in_collective K R
The initialize command. Until this command is executed, the authority function for the selected TC application is not in operation on the local ION node and most tcaadmin commands will fail.
K is the mandated diffusion for the selected TC application, i.e., the number of blocks into which each bulletin of published TC information is divided for transmission.
R is the mandated redundancy for the selected TC application, i.e., the percentage of blocks issued per bulletin that will be parity blocks rather than extents of the bulletin itself.
i
The info This command will print information about the current state of the authority function for the selected TC application on the local node, including the current settings of all parameters that can be managed as described below.
s
The start command. This command starts the tcarecv and tcacompile daemons of the authority function for the selected TC application on the local node.
m compiletime time
The manage compile time command. This command sets the time at which the authority function for the selected TC application on this node will next compile a bulletin. The command is not needed in normal operations, because future compile times are computed automatically as bulletins are compiled. time must be in yyyy/mm/dd-hh:mm:ss format.
m interval bulletin_compilation_interval
The manage bulletin compilation interval command. This interval, expressed as a number of seconds, controls the period on which the authority function for the selected TC appliction on this node will compile new key information bulletins. The default value is 3600 (one hour).
m grace bulletin_consensus_grace_time
The manage bulletin consensus grace time command. This interval, expressed as a number of seconds, controls the length of time the authority function for the selected TC application on this node will wait after publishing a bulletin before computing a consensus bulletin; this parameter is intended to relax the degree to which the system clocks of all members of the collective authority for this TC application must be in agreement. The default value is 60 (1 minute).
+ authority_array_index node_number
This command asserts that the trusted Nth member of the collective authority for the selected TC application, where N is the authority_array_index value, is the node identified by node_number.
- authority_array_index
This command asserts that the Nth member of the collective authority for the selected TC application, where N is the authority_array_index value, is no longer trusted; bulletins received from this collective authority member must be discarded.
a node_number
This command adds the node identified by node_number to the list of nodes hosting authorized_clients for the selected TC application. Once this list has been populated, TC records for this application that are received from clients residing on nodes that are not in the list are automatically discarded by the authority function residing on the local node.
d node_number
This command deletes the node identified by node_number from the list of nodes hosting authorized_clients for the selected TC application.
l
This command lists all nodes currently hosting authorized_clients for the selected TC application.
x
The stop command. This command stops the tcarecv and tcacompile daemons of the authority function for the selected TC application on the local node.
Asserts that node 6913 is now member 3 of the collective authority for the selected application.
tcaadmin(1), dtka(3)
"},{"location":"man/tc/tcarecv/","title":"NAME","text":"tcarecv - Trusted Collective daemon task for receiving newly generated records of critical information
"},{"location":"man/tc/tcarecv/#synopsis","title":"SYNOPSIS","text":"tcarecv blocks_group_number
"},{"location":"man/tc/tcarecv/#description","title":"DESCRIPTION","text":"tcarecv is a background \"daemon\" task that receives new critical information records multicast by user nodes of the TC application identified by blocks_group_number. It records those assertions in a database for future processing by tcacompile. It is spawned automatically by tcaadmin in response to the 's' command that starts operation of the TC authority function for this application on the local node, and it is terminated by tcaadmin in response to an 'x' (STOP) command.
"},{"location":"man/tc/tcarecv/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcarecv terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use tcaadmin to restart tcarecv.
\"1\"
tcarecv was unable to attach to DTKA operations, probably because tcaadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/tc/tcarecv/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcarecv/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcarecv can't attach to DTKA.
tcaadmin has not yet initialized the authority database for this TC application.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcarecv/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tc(3), tcarc(5)
"},{"location":"man/tc/tcc/","title":"NAME","text":"tcc - Trusted Collective client daemon task for handling bulletins from a collective authority
"},{"location":"man/tc/tcc/#synopsis","title":"SYNOPSIS","text":"tcc blocks_group_number
"},{"location":"man/tc/tcc/#description","title":"DESCRIPTION","text":"tcc is a background \"daemon\" task that receives code blocks multicast by the authority nodes of the collective authority for the TC application identified by blocks_group_number. It reassembles bulletins from compatible code blocks and delivers those bulletins to the application's user function on the local node.
"},{"location":"man/tc/tcc/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcc terminated, for reasons noted in the ion.log file.
\"1\"
tcc was unable to attach to TC client operations, possibly because the TC client database for this application has not yet been initialized by tcaadmin.
No configuration files are needed.
"},{"location":"man/tc/tcc/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcc/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcc can't attach to tcc system.
tcaadmin has not yet initialized the TC client database for this application.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcc/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tcarc(5)
"},{"location":"man/tc/tccadmin/","title":"NAME","text":"tccadmin - DTKA node administration interface
"},{"location":"man/tc/tccadmin/#synopsis","title":"SYNOPSIS","text":"tccadmin blocks_group_number [ commands_filename ]
"},{"location":"man/tc/tccadmin/#description","title":"DESCRIPTION","text":"tccadmin configures and manages the Trusted Collecive client databases for TC applications on the local ION node, enabling the node to utilize the services of one or more collective authorities.
The first command-line argument to tccadmin is blocksGroupNumber, which identifies the specific TC application to which all commands submitted to this instance of tccadmin will apply. A TC application is uniquely identified by the group number of the Bundle Protocol multicast group comprising all nodes hosting TC clients that subscribe to TC \"blocks\" published for that application.
tccadmin configures and manages a TC client database in response to client configuration commands found in commands_filename, if provided; if not, tccadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from tccadmin by entering the command 'h' or '?' at the prompt. The commands are documented in tccrc(5).
"},{"location":"man/tc/tccadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of TC client administration.
tccadmin
Enter interactive TC client administration command entry mode.
tccadmin host1.karc
Execute all configuration commands in host1.karc, then terminate immediately.
Status and diagnostic messages from tccadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which tccadmin was run. The log file is typically named ion.log.
See also tccrc(5).
"},{"location":"man/tc/tccadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tccadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the tccrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to tccadmin. Otherwise tccadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause tccadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see tccrc(5) for details.
"},{"location":"man/tc/tccadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tccadmin/#see-also","title":"SEE ALSO","text":"tcc(1), tccrc(5)
"},{"location":"man/tc/tccrc/","title":"NAME","text":"tccrc - Trusted Collective client configuration commands file
"},{"location":"man/tc/tccrc/#description","title":"DESCRIPTION","text":"TC client configuration commands are passed to tccadmin either in a file of text lines or interactively at tccadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the TC client configuration commands are described below.
"},{"location":"man/tc/tccrc/#commands","title":"COMMANDS","text":"?
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 tccadmin 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 withe 1 command to log the version number at startup.
h
The help command. This will display a listing of the commands and their formats. It is the same as the h command.
1 number_of_authorities_in_collective [ K [ R ]]
The initialize command. Until this command is executed, the client daemon for the selected TC application is not in operation on the local ION node and most tccadmin commands will fail.
K is the mandated diffusion for the selected TC application, i.e., the number of blocks into which each bulletin of published TC information is divided for transmission.
R is the mandated redundancy for the selected TC application, i.e., the percentage of blocks issued per bulletin that will be parity blocks rather than extents of the bulletin itself.
i
The info This command will print information about the current state of the client daemon for the selected TC application on the local node, i.e., the identities of the TC authority nodes that the client daemon recognizes.
s
The start command. This command starts the client daemon (tcc) for the selected TC application.
m authority authority_array_index node_number
This command asserts that the Nth member of the collective authority for the selected TC application, where N is the authority_array_index value, is the node identified by node_number.
x
The stop command. This command stops the client daemon (tcc) for the selected TC application.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
m authority 3 6913
Asserts that node 6913 is member 3 of the collective authority for the selected application.
tccadmin(1)
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Interplanetary Overlay Network (ION)","text":""},{"location":"#ion-description","title":"\ud83d\udef0\ufe0f ION Description","text":"Interplanetary Overlay Network (ION) is an implementation of the DTN architecture, as described in Internet RFC 4838 (version 6) and RFC 9171 (version 7), that is intended to be usable in both embedded environments including spacecraft flight computers as well as ground systems. It includes modular software packages implementing Bundle Protocol version 6 (BPv6) and version 7 (BPv7), Licklider Transmission Protocol (LTP), Bundle Streaming Service (BSS), DTN-based CCSDS File Delivery Protocol (CFDP), Asynchronous Message Service (AMS), and several other DTN services and prototypes. ION is currently the baseline implementation for science instruments on the International Space Station (ISS) and the gateway node (ION Gateway) that provides relay services for command/telemetry and science data download.
Here you will find videos of the Interplanetary Overlay Network courses and presentation materials.
DTN Development/Deployment Kit is an ISO image of an Ubuntu virtual machine, pre-configured with ION and a GUI virtualization environment. It contains a number of pre-built scenarios (network topologies) to demonstrate various features of ION software. ( currently the DevKit is undergoing upgrade to BPv7, release date is TBD.)
"},{"location":"#application-domains-of-dtn-and-ion","title":"\ud83d\udce1 Application Domains of DTN and ION","text":"git clone https://github.com/nasa-jpl/ION-DTN.git\nION is licensed under the MIT License. Please see the LICENSE file for details.
"},{"location":"#important-papers-on-ion-and-dtn","title":"\ud83d\udcda Important Papers on ION and DTN","text":"For a list of key DTN and ION-related publications, please refer to the List-of-Papers page.
"},{"location":"AMS-Programmer-Guide/","title":"AMS Programmer's Guide","text":"Version 3.0
Sky DeBaun, Jet Propulsion Laboratory, California Institute of Technology
Document Change Log
Ver No. Date Affected Description Comments 2.2 Sept 2010 3.0 June 2023 All Updates and Corrections"},{"location":"AMS-Programmer-Guide/#purpose-and-scope","title":"Purpose and Scope","text":"The Consultative Committee for Space Data Systems' (CCSDS) Asynchronous Message Service (AMS) is a communication architecture for data systems. It is designed to allow mission system modules to operate as if they were isolated, each producing and consuming mission information without explicit knowledge of the other active modules. This self-configuring communication relationship minimizes complexity in the development and operation of modular data systems.
AMS is the foundation of a system that can be described as a 'society' of largely autonomous, interoperating modules. These modules can adapt over time in response to changing mission objectives, functional upgrades of modules, and recovery from individual module failures. The primary objective of AMS is to reduce mission cost and risk by providing a standard, reusable infrastructure for information exchange among data system modules. This infrastructure is designed to be user-friendly, highly automated, flexible, robust, scalable, and efficient.
Notably, AMS provides a publication and subscription service for both terrestrial and extraterrestrial communications, utilizing the Interplanetary Overlay Network (ION). This service ensures a seamless and efficient communication system that can adapt dynamically to various missions.
"},{"location":"AMS-Programmer-Guide/#definitions","title":"Definitions","text":"Within the context of this document the following definitions apply:
A continuum is a closed set of entities that utilize AMS for purposes of communication among themselves. Each continuum is identified by a continuum name and corresponding non-negative continuum number. The continuum name that is the character string of length zero indicates \"all known continua\" or \"any known continuum\", whichever is less restrictive in the context in which this continuum name is used; the reserved continuum number zero corresponds to this continuum name.
An application is a data system implementation, typically taking the form of a set of source code text files, that relies on AMS procedures to accomplish its purposes. Each application is identified by an application name.
An authority is an administrative entity or persona that may have responsibility for the configuration and operation of an application. Each authority is identified by an authority name.
A venture is an instance of an application, i.e., a functioning projection of the application -- for which some authority is responsible -- onto a set of one or more running computers.
A message is an octet array of known size which, when copied from the memory of one module of a venture to that of another (exchanged), conveys information that can further the purposes of that venture.
The content of a message is the array of zero or more octets embedded in the message containing the specific information that the message conveys.
A role is some part of the functionality of an application. Each role is identified by a role name and corresponding non-negative role number. The role name that is the character string of length zero indicates 'all roles' or 'any role', whichever is less restrictive in the context in which the role name is used; the reserved role number zero corresponds to this role name. The role name \"RAMS '' identifies Remote AMS (RAMS) gateway functionality as discussed below; the reserved role number 1 corresponds to this role name.
A module (of some mission data system) is a communicating entity that implements some part of the functionality of some AMS venture -- that is, performs some application role -- by, among other activities, exchanging messages with other modules. Associated with each module is the name of the role it performs within the application. [Note that multiple modules may perform the same role in an application, so the role name of a module need not uniquely identify the module within its message space.] In order to accomplish AMS message exchange a module generates AMS service requests and consumes AMS service indications; the module that is the origin of a given AMS service request or the destination of a given AMS service indication is termed the operative module.
A message space is the set of all of the modules of one AMS venture that are members of a single AMS continuum; that is, a message space is the intersection of a venture and a continuum. Each message space is uniquely identified within that continuum by the combination of the name of the application and the name of the authority that is responsible for the venture, and by a corresponding venture number greater than zero. [Note that unique naming of continua enables multiple message spaces that are in different continua but are identified by the same application and authority names to be concatenated via Remote AMS (discussed below) into a single venture.]
A unit (i.e., a unit of organization) is an identified subset of the organizational hierarchy of the modules of one AMS venture, declared during venture configuration as specified by the responsible authority for that venture. Each unit is uniquely identified within the venture by unit name and corresponding non-negative unit number. The root unit of a venture is the unit that is coterminous with the venture itself; its unit name is the character string that is of length zero, and the reserved unit number zero corresponds to this unit name. A unit whose name is identical to the first N bytes -- where N is greater than or equal to zero -- of the name of another unit of the same message space is said to contain that other unit. The membership of a unit that is contained by another unit is a subset of the membership of the containing unit.
A cell is the set of all modules that are members of one unit of a given venture and are also members of a given continuum; that is, it is the intersection of a unit and a continuum. Since each unit is a subset of a venture, each cell is necessarily a subset of the message space for that venture in that continuum. Each cell is uniquely identified within its message space by its unit's name and number. The root cell of a message space is coterminous with the message space itself. A cell contains some other cell only if its unit contains that other cell's unit. A cell may be an empty set; that is, in a given continuum there may be no modules that are members of the cell's unit. The registered membership of a cell is the set of all modules in the cell that are not members of any other cell which does not contain that cell^1^. [Note that the root cell contains every other cell in the message space, and every module in the message space is therefore a member -- though not necessarily a registered member -- of the root cell.]
The domain of an AMS service request is the set of modules to which the request pertains. It comprises all of the modules that are members of the venture in which the operative module is itself a member, with the following exceptions:
The subject number (or subject) of a message is an integer embedded in the message that indicates the general nature of the information the message conveys, in the context of the AMS venture within which the message is exchanged. A subject name is a text string that serves as the symbolic representation of some subject number.
To send a message is to cause it to be copied to the memory of a specified module. To publish a message on a specified subject is to cause it to be sent to one or more implicitly specified modules, namely, all those that have requested copies of all messages on the specified subject. To announce a message is to cause it to be sent to one or more implicitly specified modules, namely, all those modules that are located within a specified continuum (or all continua), are members of a specified unit (possibly the root unit) and that perform a specified role in the application (possibly \"any role\").
A subscription is a statement requesting that one copy of every message published on some specified subject by any module in the subscription's domain be sent to the subscribing module; the domain of a subscription is the domain of the AMS service request that established the subscription.
^1^ For example, if cell A contains cells B and C, and cell C contains cells D and E, any nodes in C that are not in either D or E are in the registered membership of cell C. Those nodes are also members of cell A, but because they are in cell C -- which does not contain cell A -- they are not in cell A's registered membership.
An invitation is a statement of the manner in which messages on some specified subject may be sent to the inviting module by modules in the domain of the invitation; the invitation's domain is the domain of the AMS service request that established the invitation.
"},{"location":"AMS-Programmer-Guide/#overview","title":"Overview","text":""},{"location":"AMS-Programmer-Guide/#general","title":"General","text":"A data system based on AMS has the following characteristics:
a. Any module may be introduced into the system at any time. That is, the order in which system modules commence operation is immaterial; a module never needs to establish an explicit a priori communication \"connection\" or \"channel\" to any other module in order to pass messages to it or receive messages from it.
b. Any module may be removed from the system at any time without inhibiting the ability of any other module to continue sending and receiving messages. That is, the termination of any module, whether planned or unplanned, only causes the termination of other modules that have been specifically designed to terminate in this event.
c. When a module must be upgraded to an improved version, it may be terminated and its replacement may be started at any time; there is no need to interrupt operations of the system as a whole.
d. When the system as a whole must terminate, the order in which the system's modules cease operation is immaterial.
AMS-based systems are highly robust, lacking any innate single point of failure and tolerant of unplanned module termination. At the same time, communication within an AMS-based system can be rapid and efficient:
e. Messages are exchanged directly between modules rather than through any central message dispatching nexus.
f. Messages are automatically conveyed using the \"best\" (typically -- though not necessarily -- the fastest) underlying transport service to which the sending and receiving modules both have access. For example, messages between two ground system modules running in different computers on a common LAN would likely be conveyed via TCP/IP, while messages between modules running on two flight processors connected to a common bus memory board might be conveyed via a shared-memory message queue.
g. Finally, AMS is designed to be highly scalable: partitioning message spaces into units enables a venture to comprise hundreds or thousands of cooperating modules without significant impact on application performance.
AMS message exchange is fundamentally asynchronous, akin to a \"postal\" system. An AMS module, after sending a message, can continue its functions without waiting for a reply.
While message exchange is asynchronous, AMS provides a mechanism for linking reply messages to their original context. This is achieved by including a context number in the original message. The reply message automatically echoes this context number, allowing the original sender to link the reply to the application activity that triggered the initial message. This creates a pseudo-synchronous communication flow. The specific mechanism for establishing this link is implementation-dependent.
In some cases, true message synchrony may be necessary, requiring a module to suspend operations until a reply is received. AMS supports this communication model when required.
The majority of message exchange in an AMS-based system follows a \"publish-subscribe\" model. A module announces its subscription to a specific subject using AMS procedures. From that point, any published message on that subject is automatically delivered to all subscribing modules. This model simplifies application development and integration, allowing each module to plug into a data \"grid\" and exchange data without detailed knowledge of other modules.
However, there may be instances where a module needs to send a message privately to a specific module, such as in reply to a published message. AMS also supports this communication model when necessary.
"},{"location":"AMS-Programmer-Guide/#architectural-elements","title":"Architectural Elements","text":"The architectural elements involved in the asynchronous message service protocol are depicted as below:
Figure 1: Architectural Elements of AMS
All AMS communication is conducted among three types of communicating entities: modules (defined earlier), registrars, and configuration servers.
A registrar is a communicating entity that catalogs information regarding the registered membership of a single unit of a message space. It responds to queries for this information, and it updates this information as changes are announced.
A configuration server is a communicating entity that catalogs information regarding the message spaces established within some AMS continuum, specifically the locations of the registrars of all units of all message spaces. It responds to queries for this information, and it updates this information as changes are announced.
"},{"location":"AMS-Programmer-Guide/#overview-of-interactions","title":"Overview of Interactions","text":"AMS, best characterized as a messaging \"middleware\" protocol, operates between the Transport and Application layers of the OSI protocol stack model. It relies on underlying Transport-layer protocols for actual message copying from sender to receiver and for transmitting meta-AMS (or MAMS) messages for dynamic self-configuration of AMS message spaces.
In any AMS continuum, a common transport service, termed the Primary Transport Service (PTS), is used for MAMS traffic by all entities involved in the operations of all message spaces. The PTS, being universally available, can also be used for application message exchange among all modules in a continuum. However, in some cases, performance can be improved by using Supplementary Transport Services (STSs), especially when modules share access to a convenient communication medium like a shared-memory message queue.
Supplementary Transport Services (STSs) are performance-optimizing transport services used in the Asynchronous Message Service (AMS) for message exchange between modules that share access to a particularly convenient communication medium, such as a shared-memory message queue. While the Primary Transport Service (PTS) is universally available for message exchange, STSs can be employed to enhance application performance in certain scenarios (see CCSDS Blue Book Recommended Standard 735.1-B-1 \"Asynchronous Message Service\" for additional information).
A module's network location for receiving messages via a given transport service is its delivery point for that service. A module may have multiple delivery points, each characterized by the same service mode. For a given service mode, the list of all delivery points providing that mode to a module, ranked in descending order of preference (typically network performance), is termed the delivery vector for that service mode, for that module.
See \"Primary Transport Services\" below for additional information.
Every message space in AMS always includes at least one unit, the root unit, and each module is registered within a unit. In the simplest case, all modules reside in the root unit. Each unit is served by a single registrar, which monitors the health of all registered modules and propagates six types of message space configuration changes.
Registrars themselves register with the configuration server for the continuum containing the message space. A list of all potential network locations for the configuration server, ranked in descending order of preference, must be well-known and included in the AMS management information bases (MIBs) accessible to all registrars. Each continuum must always have an operational configuration server at one of these locations to enable registration of registrars and modules.
All registrars and modules of the same message space must register through the same configuration server.
Each module has a single meta-AMS delivery point (MAPD) for receiving MAMS messages. A new module joins a message space by registering within a unit, announcing its role name and MAPD to the unit's registrar. However, the module cannot have hard-coded information about the registrar's communication details, as these can change.
Therefore, the first step in registering a new module is contacting the configuration server at one of its known network locations. These locations, listed in descending order of preference, are included in the AMS Management Information Bases (MIBs) accessible to all application modules. The configuration server then provides the new module with the contact details for its registrar.
The module obtains a unique module number from the registrar and completes registration. The registrar ensures that all other modules in the message space learn the new module's role name, module number, and MAPD. These modules, in turn, announce their own details to the new module.
Maintaining accurate knowledge of a message space configuration is crucial for application purposes and resource efficiency. Each registrar must promptly detect the termination of modules in its unit's registered membership. While a module under application control notifies its registrar upon termination, a module that crashes or is powered off does not. To address this, each module sends a \"heartbeat\" message to its registrar every few seconds (see comment #3 at top of amscommon.h for additional details). The registrar interprets three consecutive missing heartbeats as a module termination.
Upon detecting a module's termination, either overt or imputed from heartbeat failure, the registrar informs all other modules in the unit's registered membership and, through other registrars, all modules in the message space.
When termination is imputed from a heartbeat failure, the registrar attempts to notify the presumed terminated module. If the module is still running, it terminates immediately upon receiving this message, minimizing system confusion due to other application behavior triggered by the imputed termination.
Each registrar not only monitors the heartbeats of all modules in its unit's registered membership but also issues its own heartbeats to those modules. If a module detects three consecutive missing registrar heartbeats, it assumes the registrar has crashed. The module then re-queries the configuration server to determine the new network location of the registrar and resumes exchanging heartbeats.
This assumption is reasonable because the configuration server also monitors registrar heartbeats on a slightly shorter cycle. If the configuration server detects three consecutive missing registrar heartbeats, it takes action to restart the registrar, possibly on a different host. Therefore, by the time the registrar's modules detect its crash, it should already be running again.
Since the module heartbeat interval is two seconds (see N4 in amscommon.h), the registrar will receive heartbeat messages from every running module in the unit's registered membership within the first six seconds after restart. This allows the registrar to accurately know the unit's configuration. This accurate configuration information must be delivered to new modules at startup, enabling them to orient a newly-restarted registrar if it crashes. Therefore, during the first six seconds after the registrar starts, it only accepts MAMS messages from modules already registered in the unit. This prevents the risk of delivering incorrect information to a new module.
A configuration server, like any other component, can also fail or be rebooted. Each registrar interprets three consecutive missing configuration server heartbeats as an indication of a crash. Upon detecting such a crash, the registrar cycles through all the known network locations for the continuum's configuration server, attempting to re-establish communication after the server's restart, possibly at an alternate network location. New modules attempting to register will also cycle through network locations seeking a restarted configuration server and will be unable to contact their registrars, and therefore unable to register, until they find one. However, application message exchange and subscription management activity among existing modules and registrars are not affected by this infrastructure failure.
Upon the configuration server's restart at one of its known network locations, all registrars will eventually find it and re-announce themselves, enabling newly registering application modules to successfully register.
In certain failure scenarios, multiple configuration servers may operate concurrently for a brief period, such as when a perceived failure is caused by a transient network connectivity issue rather than an actual server crash. To resolve this, each running configuration server periodically sends an \"I am running\" MAMS message to every lower-ranking configuration server network location in the known list of configuration server locations. If a configuration server receives such a message, it immediately terminates. All registrars and modules communicating with it will detect its disappearance and search again for the highest-ranking reachable configuration server, eventually restoring orderly operations in the continuum.
Finally, every registrar can optionally be configured to re-advertise to the entire message space the detailed configuration of its unit's registered membership (all active modules, all subscriptions and invitations) at some user-specified frequency, e.g., once per minute. This capability is referred to as configuration resync. Configuration resync of course generates additional message traffic, and it may be unnecessary in extremely simple or extremely stable operating environments. But it does ensure that every change in application message space configuration will eventually be propagated to every module in the message space, even if some MAMS messages are lost and even if an arbitrary number of registrars had crashed at the time the change occurred.
Taken together, these measures make AMS applications relatively fault tolerant:
a. When a module crashes, its registrar detects the loss of heartbeat within three heartbeat intervals and notifies the rest of the message space. Application message transmission everywhere is unaffected.When a registrar crashes, its configuration server detects the loss of heartbeat within three heartbeat intervals and takes action to restart the registrar. During the time that the unit has no registrar, transmission of application messages among modules of the message space is unaffected, but the heartbeat failures of crashed modules are not detected and reconfiguration messages originating in the unit's registered membership (registrations, terminations, subscription and invitation assertions, and subscription and invitation cancellations) are not propagated to any modules. However, after the registrar is restarted it will eventually detect the losses of heartbeat from all crashed modules and will issue obituaries to the message space, and if configuration resync is enabled it will eventually re- propagate the lost reconfiguration messages.
b. When a configuration server crashes, all new registration activity will come to a standstill. But no application modules fail (at least, not because of communication failure), and on restart of the configuration server the registration of new modules eventually resumes.
AMS can be configured to confine service access to application modules that can prove they are authorized to participate. For this purpose, asymmetric MAMS encryption may be used as follows:
a. The AMS MIB exposed to the configuration server contains a list of all applications for which registration service may be offered, identified by application name. Associated with each application name is the AMS public encryption key for that application.
b. The AMS MIB exposed to every registrar in each message space contains a list of all functional role names defined for the message space's application; this list limits the role names under which modules may register in that message space. Associated with each role name is the AMS public encryption key for the application module(s) that may register in that role.
c. The AMS MIBs exposed to all registrars and application modules in the message space contain the AMS public encryption key of the configuration server.
d. The AMS MIBs exposed to the configuration server and to all registrars and application modules in the message space contain the private encryption keys that are relevant to those entities.
As described later, this information is used to authenticate registrar registration and exclude spurious registrars from the message space, to authenticate module registration attempts and deny registration to unauthorized application modules, and to assure the authenticity, confidentiality, and integrity of MAMS traffic exchanged between modules and their registrars.
In addition, the confidentiality and integrity of AMS message exchange may be protected at subject granularity. The AMS MIB exposed to each module of a given message space may contain, for any subset of the message subjects (identified by name and number) used in the message space's application:
e. a list of the role names of all modules that are authorized senders of messages on this subject;
f. a list of the role names of all modules that are authorized receivers of messages on this subject;
g. encryption parameters, including a symmetric encryption key, enabling encryption of messages on this subject.
This information may be used to support secure transmission of messages on selected subjects.
Note*, though, that the JPL implementation of AMS does not implement* any of the cryptographic algorithms that are required to support these security features.
The structure of the content of messages on a given subject is application-specific; message content structure is not defined by the AMS protocol. However, the AMS MIB exposed to all modules of a given message space will contain, for each message subject (identified by name and number) used in the message space:
a. a description of this message subject, discussing the semantics of this type of message;
b. a detailed specification of the structure of the content of messages on this subject;
c. optionally, a specification of the manner in which a correctly assembled message is marshaled for network transmission in a platform-neutral manner and, on reception, un-marshaled into a format that is suitable for processing by the application.
When AMS is requested to send a message on a given subject, the message content that is presented for transmission is always in a format that is suitable for processing by the application. In the event that this format is not suitable for network transmission in a platform-neutral manner, as indicated by the presence in the MIB of a marshaling specification for this subject, AMS will marshal the message content as required before transmitting the message.
When AMS receives a message on a subject for which a marshaling specification is present in the MIB, AMS will un-marshal the message content into a format that is suitable for processing by the application before delivering the message.
Message subjects, as noted earlier, are integers with application-defined semantics. This minimizes the cost of including subject information (in effect, message type) in every message, and it makes processing simpler and faster: subscription and invitation information are recorded in arrays that are indexed by subject number.
This implementation choice, however, requires that message management control arrays be large enough to accommodate the largest subject numbers used in the application. The use of extremely large subject numbers would therefore cause these arrays to consume significant amounts of memory. In general, it is best for an AMS application to use the smallest subject numbers possible, starting with 1.
AMS' asynchronous message issuance model allows for a high degree of concurrency in the operations of data system modules. This means that a module can issue a message without suspending its operation until a response is received. This feature also largely insulates applications from variations in signal propagation time across the AMS continuum.
However, some critical MAMS (Multicast AMS) communication is unavoidably synchronous. For instance, a newly registering module must wait for responses from the configuration server and the registrar before it can proceed with application activity. Therefore, the core AMS protocol is best suited for operational contexts with generally uninterrupted network connectivity and relatively small and predictable signal propagation times, such as the Internet or a stand-alone local area network. It is typically advantageous for all entities within a single AMS continuum to operate within such a \"low-latency\" environment
AMS application messages can be exchanged between modules in different AMS continua using the Remote AMS (RAMS) procedures. These procedures are executed by special-purpose application modules known as RAMS gateways. Each RAMS gateway interfaces with two communication environments: the AMS message space it serves and the RAMS network, which is a mesh or tree of mutually aware RAMS gateways. This network enables AMS messages produced in one message space to be forwarded to other message spaces within the same venture.. RAMS gateways operate as follows:
a. RAMS gateways operate by opening private RAMS network communication channels to the RAMS gateways of other message spaces within the same venture. These interconnected gateways use these communication channels to forward message petition assertions and cancellations among themselves.
b. Each RAMS gateway subscribes locally to all subjects that are of interest in any of the linked message spaces.
c. When a RAMS gateway receives a message on any of these subjects, it uses the RAMS network to forward the message to every other linked RAMS gateway whose message space contains at least one module that has subscribed to messages on that subject.
d. On receiving a message the RAMS gateway module forwards the message to any subscribers in its own message space.
The RAMS protocol allows for the free flow of published application messages across deep space links while ensuring efficient utilization of those links. Only a single copy of any message is ever transmitted on any RAMS grid communication channel, regardless of how many subscribers will receive copies when the message reaches its destination.
RAMS operations generalize the AMS architecture as shown in Figure 2 below.
Figure 2 General AMS application structure
This extension of the publish/subscribe model to inter-continuum communications is invisible to application modules. Application functionality is unaffected by these details of network configuration, and the only effects on behavior being those intrinsic to variability in message propagation latency.
It's important to note that the nature of the RAMS network communication channels depends on the implementation of the RAMS network. To communicate over the RAMS network for a given venture, each RAMS gateway must know the RAMS network location, expressed as an endpoint in the protocol used to implement the RAMS network.
Also, only AMS application messages are propagated across continuum boundaries by RAMS. Modules are never notified of registrations, subscriptions, and invitations that occur in remote continua. The purpose of RAMS is to limit traffic on the scarce link resources supporting inter-continuum communication to the minimum necessary for successful operation of the venture. MAMS message traffic within a message space is required to enable the operation of the message space, but venture-wide application message exchange can readily be provided without propagating MAMS messages to remote continua.
"},{"location":"AMS-Programmer-Guide/#the-jpl-implementation","title":"The JPL Implementation","text":"JPL's implementation of AMS has the following components:
The codebase, written in C, relies on a shared library, ICI. This library supports other JPL implementations, like CFDP and the DTN Bundle Protocol. ICI includes a \"platform\" portability layer, easing code compilation and execution in environments like Linux, vxWorks, and Interix.
ICI also includes its own dynamic memory management system, called \"PSM\", which provides dynamic management of a privately allocated block of memory. This may be useful in environments such as spacecraft flight software where the dynamic management of system memory (malloc, free) cannot be tolerated. Use of PSM by AMS is optional.
An AMS application program, linked with libams, uses the ams_register function to instantiate an AMS module registered within a specified unit of a specified message space. Once registration is accomplished, the application may commence inviting, subscribing to, publishing, announcing, sending, and replying to messages.
This AMS implementation is multi-threaded. The process of registration starts a pair of POSIX threads, or pthreads, which manage timing and MAMS events in the background. Additionally, another pthread is started to receive MAMS messages via the primary transport service and add them to the MAMS event queue. This queue also includes MAMS message transmission requests. For each transport service that the module can receive AMS messages from, one more pthread is started. These threads receive AMS messages and add them to the AMS event queue, combining them with \"discovery\" events added by the MAMS event handling thread.
The general structure of an AMS module, then, is as shown in Figure 3 below.
Figure 3 AMS module structure
The application program has the option to start another thread to manage AMS events. This thread automatically calls event-type-specific callback functions, leaving the main application thread free to respond to non-AMS events, such as mouse events or keyboard input. The application code can also add application-specific events to the AMS event queue, potentially with higher priority than any queued AMS messages. However, to prevent certain types of unusual application behavior, the main application thread is not allowed to receive and handle any AMS events while the background AMS event handling thread is running.
"},{"location":"AMS-Programmer-Guide/#primary-transport-services","title":"Primary Transport Services","text":"As shipped, AMS currently includes support for two underlying transport services: TCP, and DGR (Datagram Retransmission, a UDP-based system that includes congestion control and retransmission-based reliability). Although TCP is faster than DGR, its connection-based architecture makes it unsuitable as a primary transport service: all MAMS message traffic is conveyed via connectionless DGR.
"},{"location":"AMS-Programmer-Guide/#installation","title":"Installation","text":"AMS source is provided in the ION distribution (a gzipped tarfile containing AMS and all supporting ION packages: ici, dgr, ltp, and bp, etc.).
The following two installation methods are provided.
"},{"location":"AMS-Programmer-Guide/#automake","title":"Automake","text":"This method automatically compiles and links all required executables, installs them, and copies ION library headers to the relevant system path(s) on your system.Use the following command sequence in the unzipped ION source directory (Linux).
./configure\nmake\nsudo make install\nsudo ldconfig\nNote: if support for the expat XML parsing library is required see 4.3 \"Support for the Expat XML Parsing Library\" below
"},{"location":"AMS-Programmer-Guide/#make","title":"Make","text":"This alternate installation method installs all ION packages (if run from ION root directory), or installs individual ION packages as follows
Note that for both install methods (e.g. on Linux) the default configuration used in the ION makefiles is as follows:
If you want a different configuration, you'll need to modify the makefiles accordingly (e.g. see the OPT variable in 2b above).
"},{"location":"AMS-Programmer-Guide/#support-for-the-expat-xml-parsing-library","title":"Support for the Expat XML Parsing Library","text":"The expat open-source XML parsing library is required by AMS only if MIBs use the XML format (see man amsxml and man amsrc for additional information).
Note that Linux environments typically have expat built in, but for VxWorks installations it is necessary to download and install expat prior to installing AMS.
To build ION with support for expat use the following flag during the .configure step of installation (see 4.1 \"Automake\" above):
./configure --with-expat
The AMS daemon program amsd can function as the configuration server for a continuum, as the registrar for one cell of a specified message space, or both. To run it, enter a command of the following form at a terminal window prompt:
amsd mib_source_name eid_spec
or
amsd mib_source_name eid_spec application_name authority_name unit_name
The former form of the command starts amsd as a configuration server only.
mib_source_name is as discussed in the documentation of ams_register below; it enables amsd to run.
eid_spec is a string that specifies the IP address and port that amsd must establish in order to receive MAMS messages in its capacity as a configuration server. See man amsd for more information.
When the latter form of the amsd command is used, the daemon is configured to function as the registrar for the indicated message space unit. If the value \".\" (period character) is supplied for eid_spec, then the daemon will [only] function as a registrar. Otherwise the daemon will function as both configuration server and registrar; this option can be useful when operating a simple, stand-alone message space, such as a demo.
"},{"location":"AMS-Programmer-Guide/#c-application-programming-interface","title":"\"C\" Application Programming Interface","text":"The AMS application programming interface is defined by the header file ams.h, which must be #included at the beginning of any AMS application program source file.
See section 9 'Application Development Guide' for compilation and linkage instructions.
"},{"location":"AMS-Programmer-Guide/#type-and-macro-definitions","title":"Type and Macro Definitions","text":"#define THIS_CONTINUUM (-1)\n#define ALL_CONTINUA (0)\n#define ANY_CONTINUUM (0)\n#define ALL_SUBJECTS (0)\n#define ANY_SUBJECT (0)\n#define ALL_ROLES (0)\n#define ANY_ROLE (0)\n\ntypedef enum\n{\nAmsArrivalOrder = 0, AmsTransmissionOrder\n} AmsSequence;\n\ntypedef enum\n{\nAmsBestEffort = 0, AmsAssured\n} AmsDiligence;\n\ntypedef enum\n{\nAmsMsgUnary = 0, AmsMsgQuery, AmsMsgReply, AmsMsgNone\n} AmsMsgType;\n\ntypedef struct amssapst *AmsModule; typedef struct amsevtst *AmsEvent;\n\n/* AMS event types. */\n#define AMS_MSG_EVT 1\n#define TIMEOUT_EVT 2\n#define NOTICE_EVT 3\n#define USER_DEFINED_EVT 4\n\n\ntypedef enum\n{\nAmsRegistrationState, AmsInvitationState, AmsSubscriptionState\n} AmsStateType;\n\ntypedef enum\n{\nAmsStateBegins = 1, AmsStateEnds\n} AmsChangeType;\n\ntypedef void (*AmsMsgHandler)(AmsModule module, void *userData, AmsEvent *eventRef, int continuumNbr, int unitNbr,\nint moduleNbr, int subjectNbr,\nint contentLength, char *content,\nint context, AmsMsgType msgType, int priority);\n\ntypedef void (*AmsRegistrationHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr, int roleNbr);\n\ntypedef void (*AmsUnregistrationHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr);\n\ntypedef void (*AmsInvitationHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr,\nint domainRoleNbr,\nint domainContinuumNbr, int domainUnitNbr,\nint subjectNbr, int priority,\nunsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence);\n\ntypedef void (*AmsDisinvitationHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr,\nint domainRoleNbr,\nint domainContinuumNbr, int domainUnitNbr,\nint subjectNbr);\n\ntypedef void (*AmsSubscriptionHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr,\nint domainRoleNbr,\nint domainContinuumNbr, int domainUnitNbr,\nint subjectNbr, int priority,\nunsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence);\n\ntypedef void (*AmsUnsubscriptionHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int unitNbr,\nint moduleNbr,\nint domainRoleNbr,\nint domainContinuumNbr, int domainUnitNbr,\nint subjectNbr);\n\ntypedef void (*AmsUserEventHandler)(AmsModule module,\nvoid *userData, AmsEvent *eventRef, int code,int dataLength, char *data);\n\ntypedef void (*AmsMgtErrHandler)(void *userData, AmsEvent *eventRef);\ntypedef struct\n{\nAmsMsgHandler msgHandler;\nvoid *msgHandlerUserData;\nAmsRegistrationHandler registrationHandler;\nvoid *registrationHandlerUserData; AmsUnregistrationHandler unregistrationHandler;\nvoid *unregistrationHandlerUserData;\nAmsInvitationHandler invitationHandler;\nvoid *invitationHandlerUserData; AmsDisinvitationHandler disinvitationHandler;\nvoid *disinvitationHandlerUserData; AmsSubscriptionHandler subscriptionHandler;\nvoid *subscriptionHandlerUserData; AmsUnsubscriptionHandler unsubscriptionHandler;\nvoid *unsubscriptionHandlerUserData;\nAmsUserEventHandler userEventHandler;\nvoid *userEventHandlerUserData;\nAmsMgtErrHandler errHandler;\nvoid *errHandlerUserData;\n} AmsEventMgt;\n\n/* Predefined term values for ams_query and ams_get_event. */ \n#define AMS_POLL (0) /* Return immediately. */ \n#define AMS_BLOCKING (-1) /* Wait forever. */\nint ams_register(char *mibSource, char *tsorder, char *applicationName, char *authorityName, char *unitName, char *roleName, AmsModule\n*module);\nThis function is used to initiate the application's participation as a module in the message space identified by specified application and authority names, within the local AMS continuum.
mibSource indicates the location of the Management Information Base (MIB) information that will enable the proposed new module to participate in its chosen message space. Nominally it is the name of an XML file in the current working directory; if NULL, mibSource defaults to roleName.xml. (A future version of loadmib.c might load MIB information from an ICI \"sdr\" database rather than from a file.)
tsorder is the applicable overriding transport service selection order string. This capability is not yet fully supported; for now, tsorder should always be NULL.
applicationName identifies the AMS application within which the proposed new module is designed to function. The application must be declared in the MIB.
authorityName, together with applicationName, identifies the message space in which the new module proposes to register. The message space must be declared in the MIB.
unitName identifies the cell, within the specified message space, in which the new module proposes to register. The unit must be declared in the MIB for ventures containing the specified message space, and a registrar for this cell of this message space must currently be running in order for the ams_register function to succeed.
roleName identifies the functional role that the proposed new module is designed to perform within the indicated application. The role must be declared in the MIB for that application, and its name will serve as the name of the module.
module points to the variable in which the applicable AMS service access point will be returned upon successful registration of the new module.
The function returns 0 on success, -1 on any error.
The application thread that invoked ams_register is assumed by AMS to be the main application thread for the module, or \"prime thread\". Following successful completion of ams_register all threads of the application process may commence invoking AMS services -- inviting messages, publishing messages, etc. -- except that only the prime thread may receive AMS events, e.g., process incoming messages.
int ams_get_module_nbr(AmsModule module);\nThe function returns the unique identifying number (within its chosen cell) assigned to the indicated module as a result of successful registration.
int ams_get_unit_nbr(AmsModule module);\nThe function returns the number that uniquely (within the message space) identifies the cell in which the module registered. The combination of unit number and module number uniquely identifies the module within its message space.
int ams_set_event_mgr(AmsModule module, AmsEventMgt\n *rules);\nThe function starts a background \"event manager\" thread that automatically receives and processes all AMS events (messages, notices of message space configuration change, etc.) enqueued for the indicated module.
The thread processes each event according to the indicated rules structure; any event for which a NULL callback function is provided is simply discarded. For details of the rules structure and prototype definitions for the callback functions that the rules point to, see 6.1 above. Some notes on this interface:
While the event manager thread is running, the prime thread is prohibited from receiving any AMS events itself, i.e., ams_get_event will always fail.
Only the prime thread may call ams_set_event_mgr. The function returns 0 on success, -1 on any error.
void ams_remove_event_mgr(AmsModule module);\nint ams_unregister(AmsModule module);\nOnly the prime thread may call ams_unregister. The function returns 0 on success, -1 on any error.
"},{"location":"AMS-Programmer-Guide/#message-subscription-and-invitation","title":"Message Subscription and Invitation","text":" int ams_invite (AmsModule module, int roleNbr, int\n continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char\n flowLabel, AmsSequence sequence, AmsDiligence diligence);\nmodule must be a valid AMS service access point as returned from ams_register.
roleNbr identifies the role that constrains the invitation: only messages from modules registered as performing the indicated role are included in this invitation. If zero, indicates \"all modules\".
continuumNbr identifies the continuum that constrains the invitation: only messages from modules operating within the indicated continuum are included in this invitation. If -1, indicates \"the local continuum\". If zero, indicates \"all continua\".
unitNbr identifies the unit that constrains the invitation: only messages from modules registered in cells identified by the indicated number -- or in cells that are contained within such cells -- are included in this invitation. A reminder: cell zero is the \"root cell\", encompassing the entire message space.
subjectNbr identifies the subject that constrains the invitation: only messages on the indicated subject are included in this invitation.
priority indicates the level of priority (from 1 to 15, where 1 is the highest priority indicating greatest urgency) at which the inviting module prefers that messages responding to this invitation be sent.
flowLabel specifies the flow label (a number from 1 to 255, which AMS may pass through to transport service adapters for quality-of-service specification purposes) that the inviting module asks issuing modules to cite when sending messages in response to this invitation. Flow label 0 signifies \"no flow label.\"
sequence indicates the minimum level of transmission order preservation that the inviting module requires for messages responding to this invitation.
diligence indicates the minimum level of reliability (based on acknowledgement and retransmission) that the inviting module requires for messages responding to this invitation.
The function returns 0 on success, -1 on any error. When successful, it causes the invitation to be propagated automatically to all modules in the inviting module's own message space.
int ams_disinvite (AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr);\nThis function terminates the module's prior invitation for messages on a specified subject under specified conditions. roleNbr, continuumNbr, unitNbr, and subjectNbr must be identical to those that characterized the invitation that is to be terminated. The function returns 0 on success, -1 on any error. When successful, it causes cancellation of the invitation to be propagated automatically to all modules in the inviting module's own message space.
int ams_subscribe (AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence);\nThis function establishes the module's request to receive a copy of every future message published on a specified subject, under specified conditions, and states the quality of service at which the module would prefer those messages to be sent. Subscriptions are implicitly constrained by venture number: only messages from modules registered in messages spaces characterized by the same application and authority names as the message space in which the subscribing module itself is registered are included in any subscription.
module must be a valid AMS service access point as returned from ams_register.
roleNbr identifies the role that constrains the subscription: only messages from modules registered as performing the indicated role are included in this subscription. If zero, indicates \"all modules\".
continuumNbr identifies the continuum that constrains the subscription: only messages from modules operating within the indicated continuum are included in this subscription. If -1, indicates \"the local continuum\". If zero, indicates \"all continua\".
unitNbr identifies the unit that constrains the subscription: only messages from modules registered in cells identified by the indicated number -- or in cells that are contained within such cells -- are included in this subscription. A reminder: cell zero is the \"root cell\", encompassing the entire message space.
subjectNbr identifies the subject that constrains the subscription: only messages on the indicated subject are included in this subscription. subjectNbr may be zero to indicate that messages published on all subjects are requested; in this case, continuumNbr must be -1.
priority indicates the level of priority (from 1 to 15, where 1 is the highest priority indicating greatest urgency) at which the subscribing module prefers that messages responding to this subscription be sent.
flowLabel specifies the flow label (a number from 1 to 255, which AMS may pass through to transport service adapters for quality-of-service specification purposes) that the subscribing module asks issuing modules to cite when publishing messages in response to this subscription. Flow label 0 signifies \"no flow label.\"
sequence indicates the minimum level of transmission order preservation that the subscribing module requires for messages responding to this subscription.
diligence indicates the minimum level of reliability (based on acknowledgement and retransmission) that the subscribing module requires for messages responding to this subscription.
The function returns 0 on success, -1 on any error. When successful, it causes the subscription to be propagated automatically to all modules in the subscribing module's own message space.
int ams_unsubscribe (AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr);\nThis function terminates the module's prior subscription to messages on a specified subject under specified conditions. roleNbr, continuumNbr, unitNbr, and subjectNbr must be identical to those that characterized the subscription that is to be terminated. The function returns 0 on success, -1 on any error. When successful, it causes cancellation of the subscription to be propagated automatically to all modules in the subscribing module's own message space.
"},{"location":"AMS-Programmer-Guide/#configuration-lookup","title":"Configuration Lookup","text":" int ams_lookup_unit_nbr (AmsModule module, char\n *unitName);\n int ams_lookup_role_nbr (AmsModule module, char\n *roleName);\n int ams_lookup_subject_nbr (AmsModule module, char\n *subjectName);\n int ams_lookup_continuum_nbr (AmsModule module, char\n *continuumName);\n char * ams_lookup_unit_name (AmsModule module, int\n unitNbr);\n char * ams_lookup_role_name (AmsModule module, int\n roleNbr);\n char * ams_lookup_subject_name (AmsModule module, int\n subjectNbr);\n char * ams_lookup_continuum_name (AmsModule module, int\n continuumNbr);\n char * ams_get_role_name (AmsModule module, int unitNbr,\n int moduleNbr);\n Lyst ams_list_msgspaces (AmsModule module);\n int ams_subunit_of (AmsModule module, int argUnitNbr, int\n refUnitNbr);\n int ams_get_continuum_nbr ();\n int ams_continuum_is_neighbor (int continuumNbr);\n int ams_rams_net_is_tree (AmsModule module);\n int ams_publish (AmsModule module, int subjectNbr, int\n priority, unsigned char flowLabel, int contentLength, char *content,\n int context);\npriority may be any value from 1 to 15, overriding the priority preference(s) asserted by the subscriber(s), or it may be zero indicating \"use each subscriber's preferred priority.\" flowLabel may be any value from 1 to 255, overriding the flow label preference(s) asserted by the subscriber(s), or it may be zero indicating \"use each subscriber's preferred flow label.\"
The function returns 0 on success, -1 on any error.
int ams_send (AmsModule module, int continuumNbr, int\n unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char\n flowLabel, int contentLength, char *content, int context);\nIf continuumNbr is -1, the local continuum is inferred.
priority may be any value from 1 to 15, overriding the priority preference asserted by the destination module, or it may be zero indicating \"use the destination module's preferred priority.\" flowLabel may be any value from 1 to 255, overriding the flow label preference asserted by the destination module, or it may be zero indicating \"use the destination module's preferred flow label.\"
The function returns 0 on success, -1 on any error.
int ams_query (AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context, int term, AmsEvent *event);\nThe function returns 0 on success, -1 on any error.
int ams_reply (AmsModule module, AmsEvent msg, int\n subjectNbr, int priority, unsigned char flowLabel, int contentLength,\n char *content);\nThe function returns 0 on success, -1 on any error.
int ams_announce (AmsModule module, int roleNbr, int\n continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char\n flowLabel, int contentLength, char *content, int context);\ncontinuumNbr indicates \"the local continuum\"; a value of zero indicates \"all continua\".
priority may be any value from 1 to 15, overriding the priority preference(s) asserted by the destination module(s), or it may be zero indicating \"use each destination module's preferred priority.\" flowLabel may be any value from 1 to 255, overriding the flow label preference(s) asserted by the destination module(s), or it may be zero indicating \"use each destination module's preferred flow label.\"
The function returns 0 on success, -1 on any error.
"},{"location":"AMS-Programmer-Guide/#event-including-message-reception","title":"Event (Including Message) Reception","text":"int ams_get_event (AmsModule module, int term, AmsEvent\n *event);\nThe function returns 0 on success, -1 on any error. Following acquisition of an event, the application program should:
int ams_get_event_type (AmsEvent event);\n int ams_parse_msg (AmsEvent event, int *continuumNbr,\n int *unitNbr, int *moduleNbr, int *subjectNbr, int *contentLength, char **content,\n int *context, AmsMsgType *msgType, int *priority, unsigned char *flowLabel);\nint ams_parse_notice (AmsEvent event, AmsStateType\n *state, AmsChangeType *change, int *unitNbr, int *moduleNbr, int *roleNbr, int *domainContinuumNbr, int *domainUnitNbr, int *subjectNbr, int *priority, unsigned char *flowLabel, AmsSequence *sequence, AmsDiligence *diligence);\nstate and change indicate the nature of the change.
unitNbr and moduleNbr identify the module to which the change pertains.
roleNbr is provided in the event that the change is the registration of a new module (in which case it indicates the functional nature of the new module) or is a subscription, unsubscription, invitation, or disinvitation (in which case it indicates the role constraining the subscription or invitation).
For a notice of subscription, unsubscription, invitation, or disinvitation:
For a notice of subscription or invitation, priority, flowLabel, sequence, and diligence indicate the quality of service requested by the module for this subscription or invitation.
Returns 0 unless one or more of the arguments provided to the function are NULL, in which case the function returns -1.
int ams_parse_user_event (AmsEvent event, int *code, int *dataLength, char **data);\n int ams_recycle_event (AmsEvent event);\n int ams_post_user_event (AmsModule module, int\n userEventCode, int userEventDataLength, char *userEventData, int\n priority);\npriority may be any value from 0 to 16. Note that this enables the application to post an event to itself that is guaranteed to be of higher priority than any message -- assuring that it will be processed before any message that is currently enqueued or that arrives in the future -- or, alternatively, to post an event that is guaranteed to be of lower priority than any message and will therefore only be processed during a lull in message reception.
Returns 0 on success, -1 on any error.
"},{"location":"AMS-Programmer-Guide/#remote-ams","title":"Remote AMS","text":"The JPL implementation of Remote AMS comprises a library (librams.c) and a sample RAMS gateway program (ramsTest.c) that uses that library.
"},{"location":"AMS-Programmer-Guide/#library","title":"Library","text":"The RAMS library implements a very simple API, which is defined by the header file
rams.h and comprises just a single function:
int rams_run (char *mibSource, char *tsorder, char\n *applicationName, char *authorityName, char *unitName, char\n *roleName, int lifetime);\nNote that the priority assigned to any DTN bundle that conveys a published or privately sent AMS message over the RAMS network will be computed as a function of the flow label specified at the time the message was originally published or sent. If no overriding flow label was specified, then the bundle priority will be 1 (standard). Otherwise, the number represented by the two low-order bits of the flow label will be used as the bundle priority and two \"extended class of service\" parameters will be derived from the next two higher-order bits of the flow label: bit 5 (the 3^rd^-lowest-order bit) will be used as the value of the \"minimum latency\" flag, with a value of 1 indicating that the bundle is critical, and bit 4 (the 4^th^-lowest-order bit) will be used as the value of the \"best-effort\" flag, with a value of 1 indicating that the bundle should be sent over an unacknowledged convergence-layer protocol. All bundles issued by the RAMS gateway that don't carry AMS messages will be assigned bundle priority 1.
This function runs indefinitely until it fails or is interrupted by a SIGINT signal. Returns -1 on any failure, 0 on normal termination.
"},{"location":"AMS-Programmer-Guide/#ramsgate","title":"ramsgate","text":"The sample RAMS gateway program ramsgate provides basic RAMS gateway functionality. To run it, enter a command of the following form at a terminal window prompt:
ramsgate *application_name authority_name_name lifetime*\n [*memory_size* [*memory_manager_name*]]\nNote that ramsgate relies on the ION implementation of DTN; be sure an ION node is operating on the local computer before starting ramsgate. (See the ION Design and Operations Guide for details.)
To terminate operation of the gateway process, just use CTRL-C to interrupt the program.
"},{"location":"AMS-Programmer-Guide/#management-information-base","title":"Management Information Base","text":"In order to operate correctly, every AMS application process -- and amsd as well -- must initially load Management Information Base (MIB) values that are universally consistent.
Currently this is accomplished automatically during registration: MIB value declaration commands in XML format are read from a file, parsed, and processed automatically.
"},{"location":"AMS-Programmer-Guide/#mib-file-syntax","title":"MIB file syntax","text":"The elements of the XML files used to load AMS MIBs are as follows: [ams_mib_load] : contains a series of MIB load commands.
Attributes: none
[ams_mib_init] : command that initializes the MIB. Attributes:
continuum_nbr: the number identifying the local continuum ptsname: the name of the primary transport service
[ams_mib_add] : contains a series of elements that add items to the MIB.
Attributes: none
[continuum] :
Attributes:
nbr: the number that identifies this continuum name: the name that identifies this continuum
neighbor: a Boolean indication (\"1\" or \"0\") of whether or not this is a neighboring continuum [If omitted, the continuum is by default assumed to be a neighbor -- that is, an implicit neighbor=\"1\" attribute is the default.]
desc: a brief textual description of this continuum
[csendpoint] : configuration server endpoint specification (i.e., network location of configuration server)
Attributes:
epspec: PTS-specific endpoint specification string (to be more fully documented in a later edition of this [Programmer's Guide] )
[application] : defines an application Attributes:
name: name of application
[venture] : defines a venture (an instance of an application) Attributes:
[nbr]: the number that identifies this venture
[appname]: the name of the application served by this venture
[authname]: the name of the authority responsible for this instance of this application
[net_config]: the configuration (\"mesh\" or \"tree\") of the RAMS network comprising all AMS continua that participate in this venture. If omitted, the RAMS network configuration is by default assumed to be a mesh.
[gweid]: a string identifying the endpoint for the local continuum's RAMS gateway within the RAMS network for this venture; default is \"bp@ipn:local_continuum_nbr.venture_nbr\"
root_cell_resync_period: the period (expressed as a count of registrar heartbeats) on which the configuration of the root unit of this venture will automatically be resynchronized. If omitted or set to zero, automatic resync is disabled within the root unit.
[role] : defines a role within a venture Attributes:
[nbr]: the number that identifies this role
[name]: the name that identifies this role
[subject] : defines a message subject within a venture Attributes:
[nbr]: the number that identifies this subject
[name]: the name that identifies this subject
[desc]: a brief textual description of this message subject
[element] : defines one of the elements (fields) of a message on a given subject (note that elements must be defined in the order in which they appear in the message, without omission)
Attributes:
[type]: a number that specifies the data type of this element (1 = long, 2 = int, 3 = short, 4 = char, 5 = string)
[name]: the name that identifies this element
[desc]: a brief textual description of this message field. [unit] : defines a unit of a venture
Attributes:
[nbr]: the number that identifies this unit name: the name that identifies this unit
[resync_period]: the period (expressed as a count of registrar heartbeats) on which the configuration of this unit will automatically be resynchronized. If omitted or set to zero, automatic resync is disabled within this unit.
[msgspace] : identifies a remote continuum that contains a message space that is part of this venture
[Attributes]:
[nbr]: the number that identifies the continuum containing this message space
[gweid]: a string identifying the endpoint for the indicated continuum's RAMS gateway, within the RAMS network for this venture; default is \"bp@ipn:continuum_nbr.venture_nbr\"
neighbor: Signifies adjacency of the message space with the parent continuum using a Boolean value (i.e. 1 is adjacent, 0 is non-adjacent). Note that in this context message space is analogous to continuum. If the neighbor attribute is omitted the default value is 1.
"},{"location":"AMS-Programmer-Guide/#a-sample-mib","title":"A Sample MIB","text":"<?xml version=\"1.0\" standalone=\"yes\"?>\n<ams_mib_load>\n<ams_mib_init continuum_nbr=\"1\" ptsname=\"dgr\"/>\n<ams_mib_add>\n<continuum nbr=\"2\" name=\"gsfc\"\" desc=\"Goddard Space Flight Center\"/>\n<csendpoint epspec=\"amroc.net:2502\"/>\n<application name=\"demo\"/>\n<venture nbr=\"9\" appname=\"demo\" authname=\"test\" >\n<role nbr=\"2\" name=\"shell\"/>\n<role nbr=\"3\" name=\"log\"/>\n<role nbr=\"4\" name=\"pitch\"/>\n<role nbr=\"5\" name=\"catch\"/>\n<role nbr=\"6\" name=\"benchs\"/>\n<role nbr=\"7\" name=\"benchr\"/>\n<subject nbr=\"1\" name=\"text\" desc=\"ASCII text\"/>\n<subject nbr=\"2\" name=\"noise\" desc=\"more ASCII text\"/>\n<subject nbr=\"3\" name=\"bench\" desc=\"numbered messages\"/>\n<unit nbr=\"1\" name=\"orbiters\"/>\n<unit nbr=\"2\" name=\"orbiters.near\"/>\n<unit nbr=\"3\" name=\"orbiters.far\"/>\n<msgspace nbr=\"2\" neighbor=1/>\n</venture>\n</ams_mib_add>\n</ams_mib_load>\nAMS applications (i.e. \"modules\") are custom software built using AMS' application programming interface (API). These AMS modules serve as the interfaces between AMS and mission-specific processes or applications.
"},{"location":"AMS-Programmer-Guide/#overview_1","title":"Overview","text":"A general overview of the required steps follows this sequence:
Applications created with the API must be compiled with links to ION's dynamic libraries.
The following two-step build procedure provides an example of how this works (note that the default path for installed ION library files (Linux) is used: /usr/local/lib/):
gcc -g -Wall -Werror -Dlinux -DUDPTS -DTCPTS -DDGRTS -DNOEXPAT -fPIC -DSPACE_ORDER=3 -I../library -I../include -I../rams -I/usr/local/include -c your_module_name.c\n\ngcc -g -Wall -Werror -Dlinux -DUDPTS -DTCPTS -DDGRTS -DNOEXPAT -fPIC -DSPACE_ORDER=3 -I../library -I../include -I../rams -I/usr/local/include -o your_module_name your_module_name.o -L./lib -L/usr/local/lib -lams -ldgr -lici -lpthread -lm*\nApplications must self-register with an AMS registrar. To facilitate this the following information is required by the application (i.e. using the ams_register() function):
Given this requirement, it may be useful (but not necessary) for the application to accept command line arguments.
An example command to start a custom AMS module might look like the following:
./your_module_name ' ' your_module_mib_role_name amsdemo test\nFollows is the complete source code for 'amshello', a simple Unix-based AMS application installed alongside AMS. It is a complete distributed system comprising two AMS application modules that functions as follows.
When the amshello program starts it fork()s into two processes, a \"pitcher\" and a \"catcher\". Both processes then register as modules in the root cell of an \"amsdemo/test\" message space. The catcher invites messages on subject \"text\" and waits for the first such message to arrive. The pitcher waits for an invitation to send messages of subject \"text\" and, when it arrives, sends one such message and terminates. When the catcher receives the message it prints the text of the message and then terminates.
To run the 'amshello' demonstration application the following 2 steps are required.
Important points regarding the above amsd command (see man amsd for additional details):
/*\namshello.c\n\"Hello world\" demonstration using AMS - Unix platform (only)\n\nCopyright (c) 2023, California Institute of Technology. \nSky DeBaun, Jet Propulsion Laboratory.\n\n\nThis program assumes the following conditions---------------\n1.) ION is running\n2.) An AMS Registrar is running \n3.) An AMS Configuration Server is running \n4.) An MIB configuration file has been created and is specified for use (see note below)\n\n*NOTE: the following command completes steps 2, 3, and 4 above (run this command after other ION processes start, then run the \u2018amshello\u2019 command from terminal to run the program):\n\namsd @ @ amsdemo test \"\" &\n\n\n*/\n\n#include \"ams.h\"\n\nstatic int runPitcher()\n{\n AmsModule me;\n AmsEvent evt;\n AmsStateType state;\n AmsChangeType change;\n int zn, nn, rn, dcn, dzn, sn, pr, textlen;\n unsigned char fl;\n AmsSequence sequence;\n AmsDiligence diligence;\n char buffer[80];\n\n isprintf(buffer, sizeof buffer, \"Hello from process %d\", (int) getpid());\n textlen = strlen(buffer) + 1;\n\n //register pitch module using default in-memory MIB (i.e. using the @)\n oK(ams_register(\"@\", NULL, \"amsdemo\", \"test\", \"\", \"pitch\", &me));\n\n while (1)\n {\n if (ams_get_event(me, AMS_BLOCKING, &evt) < 0) \n{\nreturn 0;\n}\nelse\n{\n ams_parse_notice(evt, &state, &change, &zn, &nn, &rn, &dcn,\n &dzn, &sn, &pr, &fl, &sequence, &diligence);\n ams_recycle_event(evt);\n}\n\n if (state == AmsInvitationState && sn == 1)\n {\n printf(\"Process %d sending: '%s'\\n\", (int) getpid(), buffer);\n fflush(stdout);\n ams_send(me, -1, zn, nn, 1, 0, 0, textlen, buffer, 0);\n ams_unregister(me); \nreturn 0;\n }\n }\n}\n\nstatic int runCatcher()\n{\n AmsModule me;\n AmsEvent evt;\n int cn, zn, nn, sn, len, ct, pr;\n unsigned char fl;\n AmsMsgType mt;\n char *txt;\n\n //register catch module using default in-memory MIB (i.e. @)\n oK(ams_register(\"@\", NULL, \"amsdemo\", \"test\", \"\", \"catch\", &me));\n ams_invite(me, 0, 0, 0, 1, 8, 0, AmsArrivalOrder, AmsAssured);\n\n while (1)\n {\n if (ams_get_event(me, AMS_BLOCKING, &evt) < 0) return 0;\n if (ams_get_event_type(evt) == AMS_MSG_EVT) break;\n else ams_recycle_event(evt);\n }\n\n ams_parse_msg(evt, &cn, &zn, &nn, &sn, &len, &txt, &ct, &mt, &pr, &fl);\n printf(\"Process %d received: '%s'\\n\", (int) getpid(), txt); fflush(stdout);\n ams_recycle_event(evt); ams_unregister(me); return 0;\n}\n\n\nint main(void) \n{\n pid_t pid = fork();\n\n if (pid == -1) {\n fprintf(stderr, \"Failed to create child process.\\n\");\n return EXIT_FAILURE;\n }\n\n if (pid == 0)\n //child process runs transmitter----------------------\n runPitcher();\n else \n {\n //parent process runs receiver------------------------\n runCatcher();\n }\n\n return 0;\n}\nThe research described in this publication was carried out at the Jet Propulsion Laboratory, California Institute of Technology, under a contract with the National Aeronautics and Space Administration.
"},{"location":"BP-Service-API/","title":"BP Service API","text":"This tutorial goes over the basic user APIs for developing application software to take advantage of the Bundle Protocol (BP) services provided by ION.
"},{"location":"BP-Service-API/#pre-requisite","title":"Pre-requisite","text":"For a user-developed software to utilize BP services provided by ION, there are two pre-requisite conditions: (1) ION services must be properly configured and already running in a state ready to provide BP services, and (2) BP libraries and header files must be installed and linked to the user application.
"},{"location":"BP-Service-API/#check-ion-installation-bp-version","title":"Check ION Installation & BP Version","text":"A simple way to check if ION is installed in the host is to determine the installation location of ION, one can execute which ionadmin and it will show the directory where ionadmin is currently located:
$ which ionadmin\n/usr/local/bin/ionadmin\nIf ionadmin is not found, it means either ION was not built or not properly installed in the execution path. If ionadmin is found, run it and provide the command v at the : prompt to determine the installed ION software version. For example:
$ ionadmin\n: v\nION-OPEN-SOURCE-4.1.2\nQuit ionadmin by command q. Quitting ionadmin will not terminate any ION and BP services, it simply ends ION's user interface for configuration query and management. If you see warning messages such as those shown below when quitting ionadmin, then it confirms that ION is actually not running at the moment. There are no software error:
: q\nat line 427 of ici/library/platform_sm.c, Can't get shared memory segment: Invalid argument (0)\nat line 312 of ici/library/memmgr.c, Can't open memory region.\nat line 367 of ici/sdr/sdrxn.c, Can't open SDR working memory.\nat line 513 of ici/sdr/sdrxn.c, Can't open SDR working memory.\nat line 963 of ici/library/ion.c, Can't initialize the SDR system.\nStopping ionadmin.\nYou can also run bpversion to determine the version of Bundle Protocol built in the host:
$ bpversion\nbpv7\nOnce it is determined that ION has been installed, a user may want to determine whether BP service is running by checking for the presence of various BP daemons and shared memory/semaphores, which are created by ION for interprocess communications among the various the BP service daemons.
To check if BP service is running, you can list current running processes using ps -aux command and inspect if you see the following BP service daemons:
rfxclock - background daemon that schedules ION network configuration eventsbpclm - background daemon that selects and meters data transmission to outbound convergence layersbpclock - background daemon that schedule BP level eventsbptransit - daemon to move inbound traffic to outbound queue for forwardingipnfw - BP IPN scheme-specific bundle routing daemonipnadminep - IPN scheme-specific administrative end-point daemonYou can find more details about these daemons in the manual pages. You may also see daemons related to other activate modules. For example, if the LTP engine is active in the system, you will see the following daemons:
ltpclockltpdelivltpmeterudplsoudplsiltpcliltpcloTo further vary that BP service is running, you can check for presence of ION shared memory and semaphores:
------ Shared Memory Segments --------\nkey shmid owner perms bytes nattch status \n0x0000ee02 47 userIon 666 641024 13 \n0x0000ff00 48 userIon 666 50000000 13 \n0x93de0005 49 userIon 666 1200002544 13 \n0x0000ff01 50 userIon 666 500000000 13 \n\n------ Semaphore Arrays --------\nkey semid owner perms nsems \n0x0000ee01 23 userIon 666 1 \n0x18020001 24 userIon 666 250 \nIn this example, the shared memory and semaphore keys for the SDR heap space (shmid 49) and the semaphorebase (semid 24) are created using a random key generated from the process ID of ionadmin and they will vary each time ION is instantiated. This is specific to SVR4 semaphore, which is the default for ION 4.1.2. However, starting with ION 4.1.3, the default semaphore will switch to POSIX semaphore and the output will be different. The other memory and semaphore keys listed in this example are typical default values, but they too, can be changed through ionconfig files.
If ION is installed but not running (either you see no shared memory or don't see the BP service daemons) you can restart ION. Before restarting ION, run ionstop to clear all remaining orphaned processes/shared memory allocations in case the previous instance of BP service was not properly shutdown or has suffered a crash. Here is an example of the output you may see:
$ ionstop\nIONSTOP will now stop ion and clean up the node for you...\ncfdpadmin .\nStopping cfdpadmin.\nbpv7\nbpadmin .\nStopping bpadmin.\nltpadmin .\nStopping ltpadmin.\nionadmin .\nStopping ionadmin.\nbsspadmin .\nBSSP not initialized yet.\nStopping bsspadmin.\nThis is a single-ION instance configuration. Run killm.\nkillm\nSending TERM to acsadmin lt-acsadmin acslist lt-acslist aoslsi lt-aoslsi aoslso lt-aoslso bibeadmin lt-bibeadmin bibeclo lt-bibeclo bpadmin lt-bpadmin bpcancel lt-bpcancel bpchat lt-bpchat bpclm lt-bpclm bpclock lt-bpclock bpcounter lt-bpcounter bpdriver lt-bpdriver bpecho lt-bpecho bping lt-bping bplist lt-bplist bpnmtest lt-bpnmtest bprecvfile lt-bprecvfile bpsecadmin lt-bpsecadmin bpsendfile lt-bpsendfile bpsink lt-bpsink bpsource lt-bpsource bpstats lt-bpstats bpstats2 lt-bpstats2 bptrace lt-bptrace bptransit lt-bptransit brsccla lt-brsccla brsscla lt-brsscla bsscounter lt-bsscounter bssdriver lt-bssdriver bsspadmin lt-bsspadmin bsspcli lt-bsspcli bsspclo lt-bsspclo bsspclock lt-bsspclock bssrecv lt-bssrecv bssStreamingApp lt-bssStreamingApp cgrfetch lt-cgrfetch cpsd lt-cpsd dccpcli lt-dccpcli dccpclo lt-dccpclo dccplsi lt-dccplsi dccplso lt-dccplso dgr2file lt-dgr2file dgrcli lt-dgrcli dgrclo lt-dgrclo dtka lt-dtka dtkaadmin lt-dtkaadmin dtn2admin lt-dtn2admin dtn2adminep lt-dtn2adminep dtn2fw lt-dtn2fw dtpcadmin lt-dtpcadmin dtpcclock lt-dtpcclock dtpcd lt-dtpcd dtpcreceive lt-dtpcreceive dtpcsend lt-dtpcsend file2dgr lt-file2dgr file2sdr lt-file2sdr file2sm lt-file2sm file2tcp lt-file2tcp file2udp lt-file2udp hmackeys lt-hmackeys imcadmin lt-imcadmin imcadminep lt-imcadminep imcfw lt-imcfw ionadmin lt-ionadmin ionexit lt-ionexit ionrestart lt-ionrestart ionsecadmin lt-ionsecadmin ionunlock lt-ionunlock ionwarn lt-ionwarn ipnadmin lt-ipnadmin ipnadminep lt-ipnadminep ipnd lt-ipnd ipnfw lt-ipnfw lgagent lt-lgagent lgsend lt-lgsend ltpadmin lt-ltpadmin ltpcli lt-ltpcli ltpclo lt-ltpclo ltpclock lt-ltpclock ltpcounter lt-ltpcounter ltpdeliv lt-ltpdeliv ltpdriver lt-ltpdriver ltpmeter lt-ltpmeter ltpsecadmin lt-ltpsecadmin nm_agent lt-nm_agent nm_mgr lt-nm_mgr owltsim lt-owltsim owlttb lt-owlttb psmshell lt-psmshell psmwatch lt-psmwatch ramsgate lt-ramsgate rfxclock lt-rfxclock sdatest lt-sdatest sdr2file lt-sdr2file sdrmend lt-sdrmend sdrwatch lt-sdrwatch sm2file lt-sm2file smlistsh lt-smlistsh smrbtsh lt-smrbtsh stcpcli lt-stcpcli stcpclo lt-stcpclo tcaadmin lt-tcaadmin tcaboot lt-tcaboot tcacompile lt-tcacompile tcapublish lt-tcapublish tcarecv lt-tcarecv tcc lt-tcc tccadmin lt-tccadmin tcp2file lt-tcp2file tcpbsi lt-tcpbsi tcpbso lt-tcpbso tcpcli lt-tcpcli tcpclo lt-tcpclo udp2file lt-udp2file udpbsi lt-udpbsi udpbso lt-udpbso udpcli lt-udpcli udpclo lt-udpclo udplsi lt-udplsi udplso lt-udplso amsbenchr lt-amsbenchr amsbenchs lt-amsbenchs amsd lt-amsd amshello lt-amshello amslog lt-amslog amslogprt lt-amslogprt amsshell lt-amsshell amsstop lt-amsstop bputa lt-bputa cfdpadmin lt-cfdpadmin cfdpclock lt-cfdpclock cfdptest lt-cfdptest bpcp lt-bpcp bpcpd lt-bpcpd ...\nSending KILL to the processes...\nChecking if all processes ended...\nDeleting shared memory to remove SDR...\nKillm completed.\nION node ended. Log file: ion.log\nAt this point run ps -aux or ipcs to verify that ION has terminated completely.
When ION is not running, you can performance a simple unit test to verify ION is build properly.
Navigate to the root directory of the ION source code, cd into the tests folder and then execute a bping test using the command:
./runtest bping\nYou can watch the terminal output ION restarting itself and executing a loopback ping. When successful it will indicate at the end of the test:
TEST PASSED!\n\npassed: 1\n bping\n\nfailed: 0\n\nskipped: 0\n\nexcluded by OS type: 0\n\nexcluded by BP version: 0\n\nobsolete tests: 0\nThe standard ./configure; make; sudo make install; sudo ldconfig process should automatically install the BP libraries under /usr/local/lib and the relevant header files under /usr/local/include unless ION is specifically configured to a different customized install location through the ./configure script during the compilation process. Here is a list of libraries and header files you should find there:
$ cd /usr/local/lib\n$ ls\nlibamp.a libbp.so.0.0.0 libcgr.a libdtpc.la libmbedcrypto.so.7 libtc.so.0.0.0 libudpcla.a\nlibamp.la libbss.a libcgr.la libdtpc.so libmbedtls.a libtcaP.a libudpcla.la\nlibamp.so libbss.la libcgr.so libdtpc.so.0 libmbedtls.so libtcaP.la libudpcla.so\nlibamp.so.0 libbss.so libcgr.so.0 libdtpc.so.0.0.0 libmbedtls.so.14 libtcaP.so libudpcla.so.0\nlibamp.so.0.0.0 libbss.so.0 libcgr.so.0.0.0 libici.a libmbedx509.a libtcaP.so.0 libudpcla.so.0.0.0\nlibampAgentADM.a libbss.so.0.0.0 libdgr.a libici.la libmbedx509.so libtcaP.so.0.0.0 libudplsa.a\nlibampAgentADM.la libbssp.a libdgr.la libici.so libmbedx509.so.1 libtcc.a libudplsa.la\nlibampAgentADM.so libbssp.la libdgr.so libici.so.0 libstcpcla.a libtcc.la libudplsa.so\nlibampAgentADM.so.0 libbssp.so libdgr.so.0 libici.so.0.0.0 libstcpcla.la libtcc.so libudplsa.so.0\nlibampAgentADM.so.0.0.0 libbssp.so.0 libdgr.so.0.0.0 libltp.a libstcpcla.so libtcc.so.0 libudplsa.so.0.0.0\nlibams.a libbssp.so.0.0.0 libdtka.a libltp.la libstcpcla.so.0 libtcc.so.0.0.0 libzfec.a\nlibams.la libcfdp.a libdtka.la libltp.so libstcpcla.so.0.0.0 libtcpbsa.a libzfec.la\nlibbp.a libcfdp.la libdtka.so libltp.so.0 libtc.a libtcpbsa.la libzfec.so\nlibbp.la libcfdp.so libdtka.so.0 libltp.so.0.0.0 libtc.la libtcpbsa.so libzfec.so.0\nlibbp.so libcfdp.so.0 libdtka.so.0.0.0 libmbedcrypto.a libtc.so libtcpbsa.so.0 libzfec.so.0.0.0\nlibbp.so.0 libcfdp.so.0.0.0 libdtpc.a libmbedcrypto.so libtc.so.0 libtcpbsa.so.0.0.0\n\n\n$ cd /usr/local/include\n$ ls\nams.h bpsec_instr.h cfdpops.h eureka.h llcv.h platform.h rfc9173_utils.h sdrhash.h sdrxn.h tcaP.h\nbcb_aes_gcm_sc.h bpsec_util.h crypto.h icinm.h ltp.h platform_sm.h rfx.h sdrlist.h smlist.h tcc.h\nbib_hmac_sha2_sc.h bss.h dgr.h ion.h lyst.h psa sci.h sdrmgt.h smrbt.h tccP.h\nbp.h bssp.h dtka.h ion_test_sc.h mbedtls psm.h sda.h sdrstring.h sptrace.h zco.h\nbpsec_asb.h cfdp.h dtpc.h ionsec.h memmgr.h radix.h sdr.h sdrtable.h tc.h\nIn this document, we assume that ION was build and installed via the ./configure installation process using the full open-source codebase and with the standard set of options.
The location and content of the library and header directories shown above included non-BP modules and may not match exactly with what you have especially if you have built ION with features options enabled via ./configure or used a manual/custom Makefile, or built ION from the ion-core package instead.
Once you are confidant that ION has been properly built and installed in the system, you can start BP service by launching ION. To do this, please consult the various tutorials under Configuration.
After launching ION, you can verify BP service status in the same manner as described in previous section.
"},{"location":"BP-Service-API/#bp-service-api-reference","title":"BP Service API Reference","text":""},{"location":"BP-Service-API/#header","title":"Header","text":"#include \"bp.h\"\nFunction Prototype
int bp_attach( )\nParameters
Return Value
Example Call
if (bp_attach() < 0)\n{\n printf(\"Can't attach to BP.\\n\");\n /* user inser error handling code */\n}\nDescription
Typically the bp_attach() call is made at the beginning of a user's application to attach to BP Service provided by ION in the host machine. This code checks for a negative return value.
bp_attach() automatically calls the ICI API ion_attach() when necessary, so there is no need to call them separately. In addition to gaining access to ION's SDR, which is what ion_attach() provides, bp_attach() also gains access to the Bundle Protocol's state information and database. For user application that interacts with the Bundle Protocol, bp_attach() is the entry point to ION.
Function Prototype
Sdr bp_get_sdr()\nParameters
Return Value
NULL: any errorExample Call
/* declare SDR handle */\nSdr sdr;\n\n/* get SDR handle */\nsdr = bp_get_sdr();\n\n/* user check sdr for NULL \n * and handle error */\nDescription
Returns handle for the SDR data store used for BP, to enable creation and interrogation of bundle payloads (application data units). Since the SDR handle is needed by many APIs, this function is typically executed early in the user's application in order to access other BP services.
"},{"location":"BP-Service-API/#bp_detach","title":"bp_detach","text":"Function Prototype
void bp_detach( )\nParameters
Return Value
Description
Terminates all access to BP functionality for the invoking process.
"},{"location":"BP-Service-API/#bp_open","title":"bp_open","text":"Function Prototype
int bp_open(char *eid, BpSAP *ionsapPtr)\nParameters
*eid: name of the endpoint*ionsapPtr: pointer to variable in which address of BP service access point will be returnedReturn Value
Example Call
if (bp_open(ownEid, &sap) < 0)\n{\n putErrmsg(\"bptrace can't open own endpoint.\", ownEid);\n\n /* user's error handling function here */\n}\nDescription
Opens the application's access to the BP endpoint identified by the string at eid, so that the application can take delivery of bundles destined for the indicated endpoint. This SAP can also be used for sending bundles whose source is the indicated endpoint.
Please note that all bundles sent via this SAP will be subject to immediate destruction upon transmission, i.e., no bundle addresses will be returned by bp_send for use in tracking, suspending/resuming, or cancelling transmission of these bundles.
On success, places a value in *ionsapPtr that can be supplied to future bp function invocations.
NOTE: To allow for bp_send to return a bundle address for tracking purpose, please use bp_open_source instead.
Function Prototype
int bp_open_source(char *eid, BpSAP *ionsapPtr, int detain)\nParameters
*eid: name of the endpoint*ionsapPtr: pointer to variable in which address of BP service access point will be returneddetain: indicator as to whether or not bundles sourced using this BpSAP should be detained in storage until explicitly releasedReturn Value
Example Call
if (bp_open_source(ownEid, &txSap, 1) < 0)\n{\n putErrmsg(\"can't open own 'send' endpoint.\", ownEid);\n\n /* user error handling routine here */\n}\nDescription
Opens the application's access to the BP endpoint identified by eid, so that the application can send bundles whose source is the indicated endpoint. If and only if the value of detain is non-zero, citing this SAP in an invocation of bp_send() will cause the address of the newly issued bundle to be returned for use in tracking, suspending/resuming, or cancelling transmission of this bundle.
USE THIS FEATURE WITH GREAT CARE: such a bundle will continue to occupy storage resources until it is explicitly released by an invocation of bp_release() or until its time to live expires, so bundle detention increases the risk of resource exhaustion. (If the value of detain is zero, all bundles sent via this SAP will be subject to immediate destruction upon transmission.)
On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
"},{"location":"BP-Service-API/#bp_send","title":"bp_send","text":"Function Prototype
int bp_send(BpSAP sap, char *destEid, char *reportToEid, \n int lifespan, int classOfService, BpCustodySwitch custodySwitch, \n unsigned char srrFlags, int ackRequested, \n BpAncillaryData *ancillaryData, Object adu, Object *newBundle)\nParameters
sap: the source endpoint for the bundle, provided by the bp_open call.*destEid: identifies the destination endpoint for the bundle.reportToEid: identifies the endpoint to which any status reports pertaining to this bundle will be sent; if NULL, defaults to the source endpoint.lifespan: is the maximum number of seconds that the bundle can remain in-transit (undelivered) in the network prior to automatic deletion.classOfService: is simply priority for now: BP_BULK_PRIORITY, BP_STD_PRIORITY, or BP_EXPEDITED_PRIORITY. If class-of-service flags are defined in a future version of Bundle Protocol, those flags would be OR'd with priority.custodySwitch: indicates whether or not custody transfer is requested for this bundle and, if so, whether or not the source node itself is required to be the initial custodian. The valid values are SourceCustodyRequired, SourceCustodyOptional, NoCustodyRequired. Note that custody transfer is possible only for bundles that are uniquely identified, so it cannot be requested for bundles for which BP_MINIMUM_LATENCY is requested, since BP_MINIMUM_LATENCY may result in the production of multiple identical copies of the same bundle. Similarly, custody transfer should never be requested for a \"loopback\" bundle, i.e., one whose destination node is the same as the source node: the received bundle will be identical to the source bundle, both residing in the same node, so no custody acceptance signal can be applied to the source bundle and the source bundle will remain in storage until its TTL expires.srrFlags: if non-zero, is the logical OR of the status reporting behaviors requested for this bundle: BP_RECEIVED_RPT, BP_CUSTODY_RPT, BP_FORWARDED_RPT, BP_DELIVERED_RPT, BP_DELETED_RPT.ackRequested: is a Boolean parameter indicating whether or not the recipient application should be notified that the source application requests some sort of application-specific end-to-end acknowledgment upon receipt of the bundle.ancillaryData: if not NULL, is used to populate the Extended Class Of Service block for this bundle. The block's ordinal value is used to provide fine-grained ordering within \"expedited\" traffic: ordinal values from 0 (the default) to 254 (used to designate the most urgent traffic) are valid, with 255 reserved for custody signals. The value of the block's flags is the logical OR of the applicable extended class-of-service flags:BP_MINIMUM_LATENCY designates the bundle as \"critical\" for the\npurposes of Contact Graph Routing.\n\nBP_BEST_EFFORT signifies that non-reliable convergence-layer protocols, as\navailable, may be used to transmit the bundle. Notably, the bundle may be\nsent as \"green\" data rather than \"red\" data when issued via LTP.\n\nBP_DATA_LABEL_PRESENT signifies whether or not the value of _dataLabel_\nin _ancillaryData_ must be encoded into the ECOS block when the bundle is\ntransmitted.\nNOTE: For Bundle Protocol v7, no Extended Class of Service, or equivalent, has been standardized yet. This capability, however, has been retained from BPv6 and is available to BPv7 implementation in ION.
adu: is the \"application data unit\" that will be conveyed as the payload of the new bundle. adu must be a \"zero-copy object\" (ZCO). To ensure orderly access to transmission buffer space for all applications, adu must be created by invoking ionCreateZco(), which may be configured either to block so long as insufficient ZCO storage space is available for creation of the requested ZCO or to fail immediately if insufficient ZCO storage space is available.Return Value
Example Call
if (bp_send(sap, destEid, reportToEid, ttl, priority,\n custodySwitch, srrFlags, 0, &ancillaryData,\n traceZco, &newBundle) <= 0)\n{\n putErrmsg(\"bptrace can't send file in bundle.\",\n fileName);\n\n /* user error handling code goes here */\n}\nDescription
Sends a bundle to the endpoint identified by destEid, from the source endpoint as provided to the bp_open() call that returned sap.
When sap is NULL, the transmitted bundle is anonymous, i.e., the source of the bundle is not identified. This is legal, but anonymous bundles cannot be uniquely identified; custody transfer and status reporting therefore cannot be requested for an anonymous bundle.
The function returns 1 on success, 0 on user error, -1 on any system error.
If 0 is returned, then an invalid argument value was passed to bp_send(); a message to this effect will have been written to the log file.
If 1 is returned, then either the destination of the bundle was \"dtn:none\" (the bit bucket) or the ADU has been accepted and queued for transmission in a bundle. In the latter case, if and only if sap was a reference to a BpSAP returned by an invocation of bp_open_source() that had a non-zero value in the detain parameter, then newBundle must be non-NULL and the address of the newly created bundle within the ION database is placed in newBundle. This address can be used to track, suspend/resume, or cancel transmission of the bundle.
"},{"location":"BP-Service-API/#bp_track","title":"bp_track","text":"Function Prototype
int bp_track(Object bundle, Object trackingElt)\nParameters
bundle: the bundle object data structuretrackingElt: an sdrlist element managed by the user's applicationReturn Value
Example Call
/* a lyst of bundles in SDR */\nObject bundleList;\n\n/* a bundle object in SDR */\nObject bundleObject;\n\nbundleElt = sdr_list_insert_last(sdr, bundleList,\n bundleObject);\nif (bp_track(outAdu.bundleObj, bundleElt) < 0)\n{\n sdr_cancel_xn(sdr);\n putErrmsg(\"Can't track bundle.\", NULL);\n\n /* user error handling code goes here */\n}\nThe bundleList is managed via the sdr_list library of APIs.
Description
Adds trackingElt to the list of \"tracking\" references in bundle. trackingElt must be the address of an SDR list element -- whose data is the address of this same bundle -- within some list of bundles that is privately managed by the application. Upon destruction of the bundle this list element will automatically be deleted, thus removing the bundle from the application's privately managed list of bundles. This enables the application to keep track of bundles that it is operating on without risk of inadvertently de-referencing the address of a nonexistent bundle.
Function Prototype
void bp_untrack(Object bundle, Object trackingElt)\nParameters
bundle: the bundle object data structuretrackingElt: an sdrlist element managed by the user's applicationReturn Value
Description
Removes trackingElt from the list of \"tracking\" references in bundle, if it is in that list. Does not delete trackingElt itself.
Function Prototype
int bp_suspend(Object bundle)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Suspends transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or if the bundle is already suspended. Otherwise, reverses the enqueuing of the bundle to its selected transmission outduct and places it in the \"limbo\" queue until the suspension is lifted by calling bp_resume. Returns 0 on success, -1 on any error.
"},{"location":"BP-Service-API/#bp_resume","title":"bp_resume","text":"Function Prototype
int bp_resume(Object bundle)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Terminates suspension of transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or is not suspended. Otherwise, removes the bundle from the \"limbo\" queue and queues it for route re-computation and re-queuing. Returns 0 on success, -1 on any error.
"},{"location":"BP-Service-API/#bp_cancel","title":"bp_cancel","text":"Function Prototype
int bp_cancel(Object bundle)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Cancels transmission of bundle. If the indicated bundle is currently queued for forwarding, transmission, or retransmission, it is removed from the relevant queue and destroyed exactly as if its Time To Live had expired. Returns 0 on success, -1 on any error.
"},{"location":"BP-Service-API/#bp_release","title":"bp_release","text":"Function Prototype
int bp_release(Object bundle)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Releases a detained bundle for destruction when all retention constraints have been removed. After a detained bundle has been released, the application can no longer track, suspend/resume, or cancel its transmission. Returns 0 on success, -1 on any error.
NOTE: for bundles sent through an bundle protocol end-point which is opened via bp_open_source with detain set to non-zero value, they will not be destroyed, even after successful transmissions, until time-to-live has expired or explicitly released via bp_release.
Function Prototype
int bp_receive(BpSAP sap, BpDelivery *dlvBuffer, int timeoutSeconds)\nParameters
sap: the source endpoint for the bundle, provided by the bp_open call*dlvBuffer: a pointer to a BpDelivery structure used to return the received bundle and/or outcome of receptiontimoutSeconds: a reception timer in secondsReturn Value
Example Call
if (bp_receive(state.sap, &dlv, BP_BLOCKING) < 0)\n{\n putErrmsg(\"bpsink bundle reception failed.\", NULL);\n\n /* user code to handle error or timeout*/\n}\nIn this example, BP_BLOCKING is set to -1, that means that the call will block forever until a bundle is received, unless interrupted bp_interrupt.
Description
Receives a bundle, or reports on some failure of bundle reception activity.
The \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one bundle destined for the endpoint for which this SAP is opened has not yet been delivered to the SAP, then the payload of the oldest such bundle will be returned in dlvBuffer->adu and dlvBuffer->result will be set to BpPayloadPresent. If there is no such bundle, bp_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is BP_POLL (i.e., zero) and no bundle is awaiting delivery, or if timeoutSeconds is greater than zero but no bundle arrives before timeoutSeconds have elapsed, then dlvBuffer->result will be set to BpReceptionTimedOut. If timeoutSeconds is BP_BLOCKING (i.e., -1) then bp_receive() blocks until either a bundle arrives or the function is interrupted by an invocation of bp_interrupt().
dlvBuffer->result will be set to BpReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer->result will be set to BpEndpointStopped in the event that the operation of the indicated endpoint has been terminated.
The application data unit delivered in the data delivery structure, if any, will be a \"zero-copy object\" reference. Use zco reception functions (see zco(3)) to read the content of the application data unit.
Be sure to call bp_release_delivery() after every successful invocation of bp_receive().
The function returns 0 on success, -1 on any error.
"},{"location":"BP-Service-API/#bp_interrupt","title":"bp_interrupt","text":"Function Prototype
void bp_interrupt(BpSAP sap)\nParameters
bundle: a bundle object in the SDRReturn Value
Description
Interrupts a bp_receive() invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, sap may need to be obtained from a static variable.
Function Prototype
void bp_release_delivery(BpDelivery *dlvBuffer, int releaseAdu)\nParameters
*dlvBuffer: a pointer to a BpDelivery structure used to return the received bundle and/or outcome of receptionreleaseAdu: a Boolean parameter: if non-zero, the ADU ZCO reference in dlvBuffer (if any) is destroyed.Return Value
Description
Releases resources allocated to the indicated delivery by dlvBuffer, which is returned by bp_receive. releaseAdu is a Boolean parameter: if non-zero, the ADU ZCO reference in dlvBuffer (if any) is destroyed, causing the ZCO itself to be destroyed if no other references to it remain.
Function Prototype
void bp_close(BpSAP sap)\nParameters
sap: the source endpoint for the bundle, provided by the bp_open or bp_open_source callReturn Value
Description
Terminates the application's access to the BP endpoint identified by the eid cited by the indicated service access point. The application relinquishes its ability to take delivery of bundles destined for the indicated endpoint and to send bundles whose source is the indicated endpoint.
"},{"location":"BP-Service-API/#walk-through-of-bpsourcec","title":"Walk Through ofbpsource.c","text":"TO BE UPDATED.
"},{"location":"BP-Service-API/#compiling-and-linking","title":"Compiling and Linking","text":""},{"location":"BP-Service-API/#zero-copy-object-zco-types","title":"Zero-copy Object (ZCO) Types","text":"We have shown that the way to hand user data from an application to BP is via a zero-copy object (ZCO).
In general there are two types of ZCO that is relevant to a user.
bpsource.cbpdriver.cThe following tools are available to you after ION is built:
Daemon and Configuration
Simple Sending and Receiving
Testing and Benchmarking
It is important to note that, by default, the administrative programs will all trigger the creation of a log file called\u00a0ion.log\u00a0in the directory where the program is called. This means that write-access in your current working directory is required. The log file itself will contain the expected log information from administrative daemons, but it will also contain error reports from simple applications such as\u00a0bpsink. This is important to note since the BP applications may not be reporting all error information to stdout or stderr.
"},{"location":"Basic-Configuration-File-Tutorial/#starting-the-ion-daemon","title":"Starting the ION Daemon","text":"A script has been created which allows a more streamlined configuration and startup of an ION node. This script is called\u00a0ionstart, and it has the following syntax. Don't run it yet; we still have to configure it!
ionstart -I <filename>
filename: This is the name for configuration file which the script will attempt to use for the various configuration commands. The script will perform a sanity check on the file, splitting it into command sections appropriate for each of the administration programs.
Configuration information (such as routes, connections, etc) can be specified one of two ways for any of the individual administration programs:
(Recommended) Creating a configuration file and passing it to\u00a0ionadmin,\u00a0bpadmin,\u00a0ipnadmin...\u00a0either directly or via the\u00a0ionstart\u00a0helper script. Manually typing configuration commands into the terminal for each administration program.
You can find appropriate commands in the following sections.
"},{"location":"Basic-Configuration-File-Tutorial/#configuration-files-overview","title":"Configuration Files Overview","text":"There are five configuration files about which you should be aware.
The first,\u00a0ionadmin's configuration file, assigns an identity (node number) to the node, optionally configures the resources that will be made available to the node, and specifies contact bandwidths and one-way transmission times. Specifying the \"contact plan\" is important in deep-space scenarios where the bandwidth must be managed and where acknowledgments must be timed according to propagation delays. It is also vital to the function of contact-graph routing.
The second,\u00a0ltpadmin's configuration file, specifies spans, transmission speeds, and resources for the Licklider Transfer Protocol convergence layer.
The third,\u00a0ipnadmin's configuration file, maps endpoints at \"neighboring\" (topologically adjacent, directly reachable) nodes to convergence-layer addresses. Our examples use TCP/IP and LTP (over IP/UDP), so it maps endpoint IDs to IP addresses. This file populates the ION analogue to an ARP cache for the \"ipn\" naming scheme.
The fourth,\u00a0bpadmin's configuration file, specifies all of the open endpoints for delivery on your local end and specifies which convergence layer protocol(s) you intend to use. With the exception of LTP, most convergence layer adapters are fully configured in this file.
The fifth,\u00a0dtn2admin's configuration file, populates the ION analogue to an ARP cache for the \"dtn\" naming scheme.
"},{"location":"Basic-Configuration-File-Tutorial/#the-ion-configuration-file","title":"The ION Configuration File","text":"Given to\u00a0ionadmin\u00a0either as a file or from the daemon command line, this file configures contacts for the ION node. We will assume that the local node's identification number is 1.
This file specifies contact times and one-way light times between nodes. This is useful in deep-space scenarios: for instance, Mars may be 20 light-minutes away, or 8. Though only some transport protocols make use of this time (currently, only LTP), it must be specified for all links nonetheless. Times may be relative (prefixed with a + from current time) or absolute. Absolute times, are in the format\u00a0yyyy/mm/dd-hh:mm:ss. By default, the contact-graph routing engine will make bundle routing decisions based on the contact information provided.
The configuration file lines are as follows:
1 1 ''
This command will initialize the ion node to be node number 1.
1\u00a0refers to this being the initialization or ''first'' command. 1\u00a0specifies the node number of this ion node. (IPN node 1). ''\u00a0specifies the name of a file of configuration commands for the node's use of shared memory and other resources (suitable defaults are applied if you leave this argument as an empty string).
s
This will start the ION node. It mostly functions to officially \"start\" the node in a specific instant; it causes all of ION's protocol-independent background daemons to start running.
a contact +1 +3600 1 1 100000
specifies a transmission opportunity for a given time duration between two connected nodes (or, in this case, a loopback transmission opportunity).
a\u00a0adds this entry in the configuration table. contact\u00a0specifies that this entry defines a transmission opportunity. +1\u00a0is the start time for the contact (relative to when the\u00a0s\u00a0command is issued). +3600\u00a0is the end time for the contact (relative to when the\u00a0s\u00a0command is issued). 1\u00a0is the source node number. 1\u00a0is the destination node number. 100000\u00a0is the maximum rate at which data is expected to be transmitted from the source node to the destination node during this time period (here, it is 100000 bytes / second).
a range +1 +3600 1 1 1
specifies a distance between nodes, expressed as a number of light seconds, where each element has the following meaning:
a\u00a0adds this entry in the configuration table. range\u00a0declares that what follows is a distance between two nodes. +1\u00a0is the earliest time at which this is expected to be the distance between these two nodes (relative to the time\u00a0s\u00a0was issued). +3600\u00a0is the latest time at which this is still expected to be the distance between these two nodes (relative to the time\u00a0s\u00a0was issued). 1\u00a0is one of the two nodes in question. 1\u00a0is the other node. 1\u00a0is the distance between the nodes, measured in light seconds, also sometimes called the \"one-way light time\" (here, one light second is the expected distance).
m production 1000000
specifies the maximum rate at which data will be produced by the node.
m\u00a0specifies that this is a management command. production\u00a0declares that this command declares the maximum rate of data production at this ION node. 1000000\u00a0specifies that at most 1000000 bytes/second will be produced by this node.
m consumption 1000000
specifies the maximum rate at which data can be consumed by the node.
m\u00a0specifies that this is a management command. consumption\u00a0declares that this command declares the maximum rate of data consumption at this ION node. 1000000\u00a0specifies that at most 1000000 bytes/second will be consumed by this node.
This will make a final configuration file\u00a0host1.ionrc\u00a0which looks like this:
1 1 ''\ns\na contact +1 +3600 1 1 100000\na range +1 +3600 1 1 1\nm production 1000000\nm consumption 1000000\nGiven to\u00a0ltpadmin\u00a0as a file or from the command line, this file configures the LTP engine itself. We will assume the local IPN node number is 1; in ION, node numbers are used as the LTP engine numbers.
1 32
This command will initialize the LTP engine:
1\u00a0refers to this being the initialization or ''first'' command. 32\u00a0is an estimate of the maximum total number of LTP ''block'' transmission sessions - for all spans - that will be concurrently active in this LTP engine. It is used to size a hash table for session lookups.
a span 1 32 32 1400 10000 1 'udplso localhost:1113'
This command defines an LTP engine 'span':
a\u00a0indicates that this will add something to the engine.
span\u00a0indicates that an LTP span will be added.
1\u00a0is the engine number for the span, the number of the remote engine to which LTP segments will be transmitted via this span. In this case, because the span is being configured for loopback, it is the number of the local engine, i.e., the local node number. This will have to match an outduct in Section\u00a02.6.
32\u00a0specifies the maximum number of LTP ''block'' transmission sessions that may be active on this span. The product of the mean block size and the maximum number of transmission sessions is effectively the LTP flow control ''window'' for this span: if it's less than the bandwidth delay product for traffic between the local LTP engine and this spa's remote LTP engine then you'll be under-utilizing that link. We often try to size each block to be about one second's worth of transmission, so to select a good value for this parameter you can simply divide the span's bandwidth delay product (data rate times distance in light seconds) by your best guess at the mean block size.
The second\u00a032specifies the maximum number of LTP ''block'' reception sessions that may be active on this span. When data rates in both directions are the same, this is usually the same value as the maximum number of transmission sessions.
1400\u00a0is the number of bytes in a single segment. In this case, LTP runs atop UDP/IP on ethernet, so we account for some packet overhead and use 1400.
1000\u00a0is the LTP aggregation size limit, in bytes. LTP will aggregate multiple bundles into blocks for transmission. This value indicates that the block currently being aggregated will be transmitted as soon as its aggregate size exceeds 10000 bytes.
1\u00a0is the LTP aggregation time limit, in seconds. This value indicates that the block currently being aggregated will be transmitted 1 second after aggregation began, even if its aggregate size is still less than the aggregation size limit.
'udplso localhost:1113'\u00a0is the command used to implement the link itself. The link is implemented via UDP, sending segments to the localhost Internet interface on port 1113 (the IANA default port for LTP over UDP).
s 'udplsi localhost:1113'
Starts the ltp engine itself:
s\u00a0starts the ltp engine.
'udplsi localhost:1113'\u00a0is the link service input task. In this case, the input ''duct' is a UDP listener on the local host using port 1113.
This means that the entire configuration file\u00a0host1.ltprc\u00a0looks like this:
1 32\na span 1 32 32 1400 10000 1 'udplso localhost:1113'\ns 'udplsi localhost:1113'\nGiven to\u00a0bpadmin\u00a0either as a file or from the daemon command line, this file configures the endpoints through which this node's Bundle Protocol Agent (BPA) will communicate. We will assume the local BPA's node number is 1; as for LTP, in ION node numbers are used to identify bundle protocol agents.
1
This initializes the bundle protocol:
1\u00a0refers to this being the initialization or ''first'' command.
a scheme ipn 'ipnfw' 'ipnadminep'
This adds support for a new Endpoint Identifier (EID) scheme:
a\u00a0means that this command will add something.
scheme\u00a0means that this command will add a scheme.
ipn\u00a0is the name of the scheme to be added.
'ipnfw'\u00a0is the name of the IPN scheme's forwarding engine daemon.
'ipnadminep'\u00a0is the name of the IPN scheme's custody transfer management daemon.
a endpoint ipn:1.0 q
This command establishes this BP node's membership in a BP endpoint:
a\u00a0means that this command will add something.
endpoint\u00a0means that this command adds an endpoint.
ipn\u00a0is the scheme name of the endpoint.
1.0\u00a0is the scheme-specific part of the endpoint. For the IPN scheme the scheme-specific part always has the form\u00a0nodenumber:servicenumber. Each node must be a member of the endpoint whose node number is the node's own node number and whose service number is 0, indicating administrative traffic.
q\u00a0means that the behavior of the engine, upon receipt of a new bundle for this endpoint, is to queue it until an application accepts the bundle. The alternative is to silently discard the bundle if no application is actively listening; this is specified by replacing\u00a0q\u00a0with\u00a0x.
a endpoint ipn:1.1 q
a endpoint ipn:1.2 q
These specify two more endpoints that will be used for test traffic.
a protocol ltp 1400 100
This command adds support for a convergence-layer protocol:
a\u00a0means that this command will add something.
protocol\u00a0means that this command will add a convergence-layer protocol.
ltp\u00a0is the name of the convergence-layer protocol.
1400\u00a0is the estimated size of each convergence-layer protocol data unit (in bytes); in this case, the value is based on the size of a UDP/IP packet on Ethernet.
100\u00a0is the estimated size of the protocol transmission overhead (in bytes) per convergence-layer procotol data unit sent.
a induct ltp 1 ltpcli
This command adds an induct, through which incoming bundles can be received from other nodes:
a\u00a0means that this command will add something.
induct\u00a0means that this command will add an induct.
ltp\u00a0is the convergence layer protocol of the induct.
1\u00a0is the identifier of the induct, in this case the ID of the local LTP engine.
ltpcli\u00a0is the name of the daemon used to implement the induct.
a outduct ltp 1 ltpclo
This command adds an outduct, through which outgoing bundles can be sent to other nodes:
a\u00a0means that this command will add something.
outduct\u00a0means that this command will add an outduct.
ltp\u00a0is the convergence layer protocol of the outduct.
1\u00a0is the identifier of the outduct, the ID of the convergence-layer protocol induct of some remote node. See Section\u00a02.5\u00a0for remote LTP engine IDs.
ltpclo\u00a0is the name of the daemon used to implement the outduct.
s
This command starts the bundle engine including all daemons for the inducts and outducts.
That means that the entire configuration file\u00a0host1.bprc\u00a0looks like this:
1\na scheme ipn 'ipnfw' 'ipnadminep'\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\na protocol ltp 1400 100\na induct ltp 1 ltpcli\na outduct ltp 1 ltpclo\ns\nAs noted earlier, this file is used to build ION's analogue to an ARP cache, a table of ''egress plans.'' It specifies which outducts to use in order to forward bundles to the local node's neighbors in the network. Since we only have one outduct, for forwarding bundles to one place (the local node), we only have one egress plan.
a plan 1 ltp/1
This command defines an egress plan for bundles to be transmitted to the local node:
a\u00a0means this command adds something.
plan\u00a0means this command adds an egress plan.
1\u00a0is the node number of the remote node. In this case, that is the local node's own node number; we're configuring for loopback.
ltp/1\u00a0is the identifier of the outduct through which to transmit bundles in order to convey them to this ''remote'' node.
This means that the entire configuration file\u00a0host1.ipnrc\u00a0looks like this:
a plan 1 ltp/1
Assuming no errors occur with the configuration above, we are now ready to test loopback communications. In one terminal, we have to run the start script (the one we said that you would have to have earlier). It's right here, in case you forgot to write it down:
ionstart -i host1.ionrc -l host1.ltprc -b host1.bprc -p host1.ipnrc
This command will run the appropriate administration programs, in order, with the appropriate configuration files. Don't worry that the command is lengthy and unwieldly; we will show you how to make a more clean single configuration file later.
Once the daemon is started, run:
bpsink ipn:1.1
This will begin listening on the Endpoint ID with the\u00a0endpoint_number\u00a01 on\u00a0service_number\u00a01, which is used for testing.
Now open another terminal and run the command:
bpsource ipn:1.1
This will begin sending messages you type to the Endpoint ID\u00a0ipn:1.1, which is currently being listened to by\u00a0bpsink. Type messages into\u00a0bpsource, press enter, and see if they are reported by\u00a0bpsink.
If so, you're ready for bigger and better things. If not, check the following:
Do you have write permissions for your current directory? If not, you will not be able to start the daemon as it has to write out to the ion.log file. Are your config files exactly as specified, except for IP address changes? Are you running it on one of our supported platforms? Currently, those are the only supported distributions.
If you are still having problems, you can ask for help on the ION users' list or file an ION bug report.
"},{"location":"Basic-Configuration-File-Tutorial/#stopping-the-daemon","title":"Stopping the Daemon","text":"As the daemon launches many ducts and helper applications, it can be complicated to turn it all off. To help this, we provided a script. The script similar to\u00a0ionstart\u00a0exists called\u00a0ionstop, which tears down the ion node in one step. You can call it like so:
ionstop
After stopping the daemon, it can be restarted using the same procedures as outlined above. Do remember that the ion.log file is still present, and will just keep growing as you experiment with ION.
IMPORTANT:\u00a0The user account that runs ionstart\u00a0must also run ionstop. If that account does not, no other accounts can successfully start the daemon, as the shared memory vital to ION's functionality will already be occupied.
"},{"location":"Basic-Configuration-File-Tutorial/#more-advanced-usage","title":"More Advanced Usage","text":"Detailed documentation of ION and its applications are available via the man pages. It is suggested that you start with\u00a0man ion\u00a0, as this is an overview man page listing all available ION packages.
"},{"location":"Basic-Configuration-File-Tutorial/#ionscript-for-simplified-configuration-files","title":"Ionscript for Simplified Configuration Files","text":"The most difficult and cumbersome method of starting an ION node is to manually run the various administration programs in order, manually typing configuration commands all the way. It is much more efficient and less error-prone to place the configuration commands into a configuration file and using that as input to the administration program, but this is still cumbersome as you must type in each administration program in order. The\u00a0ionstart\u00a0program will automatically execute the appropriate administration programs with their respective configuration files in order. Unfortunately, as seen in the previous sections,\u00a0the command is lengthy. This is why the\u00a0ionscript\u00a0script was added to make things even easier.
The ionscript\u00a0will basically concatenate the configuration files into one large file. The format of this large configuration file is simply to bookend configuration sections with the lines:\u00a0## begin PROGRAM\u00a0and\u00a0## end PROGRAM, where\u00a0PROGRAM\u00a0is the name of the administration program for which the configuration commands should be sent (such as\u00a0ionadmin, bpadmin, ipnadmin).
To create a single file\u00a0host1.rc\u00a0out of the various configuration files defined in the previous section, run this command:
ionscript -i host1.ionrc -p host1.ipnrc -l host1.ltprc -b host1.bprc -O host1.rc
The command can also be used to split the large\u00a0host1.rc\u00a0into the individual configuration files (so long as the large file is formatted correctly). Just run this command to revert the process:
ionscript -i host1.ionrc -p host1.ipnrc -l host1.ltprc -b host1.bprc -I host1.rc
This isn't very practical in this specific case (as you already have the individual files) but if you start with a single configuration file, this can be helpful.
Once you have a single configuration file, starting the ION node is a single command:
ionstart -I host1.rc
Note that\u00a0ionstart\u00a0and\u00a0ionscript\u00a0require\u00a0sed\u00a0and\u00a0awk, but those are almost universally available on Unix-based systems. The two scripts will always sanity-check the large configuration file to ensure that it interprets the bookend lines correctly- and it will warn you of any errors you have made in the file. Consult the USAGE for each script for further help, by attempting to run the script with no arguments or the\u00a0-h\u00a0argument.
"},{"location":"Basic-Configuration-File-Tutorial/#examples-of-network-configurations","title":"Examples of Network Configurations","text":"For a simple single-node ION configuration - running multiple instances of ION in the same host, see the tutorial here.
For a two-node configuration, see the tutorial here.
For a multi-hop and also multi-network configuration, see this page.
"},{"location":"CLA-API/","title":"Convergence Layer Adaptor - APIs","text":"ION currently provides several CLAs, include LTP, TCP, UDP, STCP. However, it is possible to develop a customized CLA using ION's API. This document will describe the basic set of API used to develop a customized CLA.
"},{"location":"CLA-API/#cla-apis","title":"CLA APIs","text":""},{"location":"CLA-API/#header","title":"Header","text":"#include \"bpP.h\"\nFunction Prototype
extern int bpDequeue(VOutduct *vduct,\n Object *outboundZco,\n BpAncillaryData *ancillaryData,\n int stewardship);\nThis function is invoked by a convergence-layer output adapter (outduct) daemon to get a bundle that it is to transmit to some remote convergence-layer input adapter (induct) daemon.
The function first pops the next (only) outbound bundle from the queue of outbound bundles for the indicated duct. If no such bundle is currently waiting for transmission, it blocks until one is [or until the duct is closed, at which time the function returns zero without providing the address of an outbound bundle ZCO].
On obtaining a bundle, bpDequeue does DEQUEUE processing on the bundle's extension blocks; if this processing determines that the bundle is corrupt, the function returns zero while providing 1 (a nonsense address) in *bundleZco as the address of the outbound bundle ZCO. The CLO should handle this result by simply calling bpDequeue again.
bpDequeue then catenates (serializes) the BP header information (primary block and all extension blocks) in the bundle and prepends that serialized header to the source data of the bundle's payload ZCO. Then it returns the address of that ZCO in *bundleZco for transmission at the convergence layer (possibly entailing segmentation that would be invisible to BP).
Requested quality of service for the bundle is provided in *ancillaryData so that the requested QOS can be mapped to the QOS features of the convergence-layer protocol. For example, this is where a request for custody transfer is communicated to BIBE when the outduct daemon is one that does BIBE transmission. The stewardship argument controls the disposition of the bundle following transmission. Any value other than zero indicates that the outduct daemon is one that performs \"stewardship\" procedures. An outduct daemon that performs stewardship procedures will disposition the bundle as soon as the results of transmission at the convergence layer are known, by calling one of two functions: either bpHandleXmitSuccess or else bpHandleXmitFailure. A value of zero indicates that the outduct daemon does not perform stewardship procedures and will not disposition the bundle following transmission; instead, the bpDequeue function itself will assume that transmission at the convergence layer will be successful and will disposition the bundle on that basis.
Return Values
Function Prototype
extern int bpHandleXmitSuccess(Object zco);\nThis function is invoked by a convergence-layer output adapter (an outduct) on detection of convergence- layer protocol transmission success. It causes the serialized (catenated) outbound bundle in zco to be destroyed, unless some constraint (such as local delivery of a copy of the bundle) requires that bundle destruction be deferred.
Return Values
Function Prototype
extern int bpHandleXmitFailure(Object zco);\nThis function is invoked by a convergence-layer output adapter (an outduct) on detection of a convergence- layer protocol transmission error. It causes the serialized (catenated) outbound bundle in zco to be queued up for re-forwarding.
Return Values
extern AcqWorkArea *bpGetAcqArea(VInduct *vduct);\nAllocates a bundle acquisition work area for use in acquiring inbound bundles via the indicated duct. This is typically invoked just once at the beginning of a CLA process initialization
Return Value
NULL: on any failureextern void bpReleaseAcqArea(AcqWorkArea *workArea);\nReleases dynamically allocated bundle acquisition work area. This should be called before shutting down a CLA process.
Return Value
NULL: on any failureextern int bpBeginAcq( AcqWorkArea *workArea,\n int authentic,\n char *senderEid);\nThis function is invoked by a convergence-layer input adapter to initiate acquisition of a new bundle via the indicated workArea. It initializes deserialization of an array of bytes constituting a single transmitted bundle. The \"authentic\" Boolean and \"senderEid\" string are knowledge asserted by the convergence-layer input adapter invoking this function: an assertion of authenticity of the data being acquired (e.g., per knowledge that the data were received via a physically secure medium) and, if non-NULL, an EID characterizing the node that send this inbound bundle.
Return Values
extern int bpContinueAcq( AcqWorkArea *workArea,\n char *bytes,\n int length,\n ReqAttendant *attendant,\n unsigned char priority);\nThis function continues acquisition of a bundle as initiated by an invocation of bpBeginAcq(). To do so, it appends the indicated array of bytes, of the indicated length, to the byte array that is encapsulated in workArea.
bpContinueAcq is an alternative to bpLoadAcq, intended for use by convergence-layer adapters that incrementally acquire portions of concatenated bundles into byte-array buffers. The function transparently creates a zero-copy object for acquisition of the bundle, if one does not already exist, and appends \"bytes\" to the source data of that ZCO.
The behavior of bpContinueAcq when currently available space for zero- copy objects is insufficient to contain this increment of bundle source data depends on the value of \"attendant\". If \"attendant\" is NULL, then bpContinueAcq will return 0 but will flag the acquisition work area for refusal of the bundle due to resource exhaustion (congestion). Otherwise, (i.e., \"attendant\" points to a ReqAttendant structure, which MUST have already been initialized by ionStartAttendant()), bpContinueAcq will block until sufficient space is available or the attendant is paused or the function fails, whichever occurs first.
\"priority\" is normally zero, but for the TCPCL convergence-layer receiver threads it is very high (255) because any delay in allocating space to an extent of TCPCL data delays the processing of TCPCL control messages, potentially killing TCPCL performance.
Return Values
extern void bpCancelAcq( AcqWorkArea *workArea);\nCancels acquisition of a new bundle via the indicated workArea, destroying the bundle acquisition ZCO of workArea.
"},{"location":"CLA-API/#bpendacq","title":"bpEndAcq","text":"extern int bpEndAcq( AcqWorkArea *workArea);\nReturn Value
1: on success, the bundle has been fully acquired and dispatched (that is, queued for delivery and/or forwarding). In this case, the invoking convergence- layer input adapter should simply continue with the next cycle of bundle acquisition, i.e., it should call bpBeginAcq().
0: on any failure pertaining only to this bundle. The failure is transient, applying only to the bundle that is currently being acquired. In this case, the current bundle acquisition has failed but BP itself can continue; the invoking convergence-layer input adapter should simply continue with the next cycle of bundle acquisition just as if the return code had been 1.
-1: on any other (i.e., system) failure.
extern int bpLoadAcq( AcqWorkArea *workArea,\n Object zco);\nbpLoadAcq is an alternative to bpContinueAcq, intended for use by convergence-layer adapters that natively acquire concatenated bundles into zero-copy objects such as LTP.
Return Value
This section is under construction
"},{"location":"Configure-Multiple-Network-Interfaces/","title":"Configure ION for Multiple Network Interfaces","text":"Lab testing of ION-based DTN network often uses only a single network. However, during deployment or operational testing, ION network must operate over multiple networks. To clarify how to configure ION, we consider the following hypothetical network configuration.
The basic topology is illustrated here:
+-------+ protocol a protocol b +-------+\n | | | |\n | SC1 +-----+ +--->+ MOC1 |\n | 21 | | | | 24 |\n +-------+ | +-------+ | +-------+\n +---->+ +----+\n rfnet | GS | gsnet\n +---->+ 23 +----+\n +-------+ | +-------+ | +-------+\n | | | | | |\n | SC2 +-----+ +--->+ MOC2 |\n | 22 | | 25 |\n +-------+ +-------+\n\nsubnet: 192.168.100.0/24 subnet:192.168.200.0/24\nrfnet (192.168.100.0/24) and gsnet (192.168.200.0/24).rfnet is protocol A and in gsnet, protocol B.ION associates each neighbor with an convergence layer protocol and an outduct. With the exception of UDP convergence layer, each outduct is associated with an induct as well.
When there are multiple neighbors using the same convergence layer protocol, only one induct is used to 'pair' with multiple outducts of the same protocol.
If neighbors using the same protocol are all within the same network, then the induct is associated with the IP address of the ION node on that particular network.
If the neighbors using the same protocol are from multiple networks, then the induct will need to be associated with INADDR_ANY, 0.0.0.0:port defined for protocols such as TCP, UDP, and STCP.
For LTP, however, multiple inducts can be defined for each network using the IP address of each network separately, and the induct for a network is called seat (see manual page for ltprc).
In this case, SC1 and SC2 communicates with GS using LTP, while MOC1 and MOC2 communicate with GS using TCP. The port we used is 4556.
For GS, it defines TCP in this manner in the .bprc file:
a protocol tcp\n\na induct tcp 192.168.200.23:4556 tcpcli\n\na outduct tcp 192.168.200.24:4556 tcpclo\na outduct tcp 192.168.200.25:4556 tcpclo\n\na plan ipn:24.0\na planduct ipn:24.0 tcp 192.168.200.24:4556\na planduct ipn:25.0 tcp 192.168.200.25:4556\nThere is only induct for the two outducts. Since node 23, 24, and 25 are in the 192.168.200.0/24 subnet, the induct for 23 can simply use its statically assigned IP address of 192.168.200.23:4556.
For MOC1, TCP is specified in this manner in the .bprc file:
a protocol tcp\n\na induct tcp 192.168.200.24:4556 tcpcli\n\na outduct tcp 192.168.200.23:4556 tcpclo\n\na plan ipn:23.0\n\na planduct ipn:23.0 tcp 192.168.200.23:4556\nSince MOC1 has only 1 neighbor and uses TCP, the induct/outduct and egress plans are very much the standard configuration we see typically in a single network configuration.
Similar configuration can be written for MOC2.
For LTP, the configuration for GS is:
# in bprc file\na protocol ltp\n\na induct ltp 23 ltpcli\n\na outduct ltp 21 ltpclo\na outduct ltp 22 ltpclo\n\na plan ipn:21.0 \na plan ipn:22.0\n\na planduct ipn:21.0 ltp 21\na planduct ipn:22.0 ltp 22\n\n# in .ltprc file\na span 21 100 100 1482 100000 1 'udplso 192.168.100.21:1113'\na span 22 100 100 1482 100000 1 'udplso 192.168.100.22:1113'\na seat 'udplsi 192.168.100.23:1113'\n\ns\nFor ltp, a single induct is specified for the 192.168.100.0/24 subnet using the a seat (add seat) command. The older syntax is s 'udplsi 192.168.100.23:1113', which works only for the case of a single network and port combination. However, when extending LTP to multiple seats (inducts) when there are multiple networks or when there are multiple ports, the seat command offers the flexibility to support more complex configurations.
The syntax for LTP/STCP is identical, except replacing tcp with stcp, tcpcli and tcpclo with stcpcli and stcpclo in the configuration files.
When runing TCP or STCP over both networks, the only change is that for the GS node, the induct definitions in .bprc are replaced by:
a induct tcp 0.0.0.0:4556 tcpcli and a induct stcp 0.0.0.0:4556 tcpcli
When running LTP over both networks, the only key difference is that in the .ltprc file for the GS node, two seats are defined:
a span 21 100 100 1482 100000 1 'udplso 192.168.100.21:1113'\na span 22 100 100 1482 100000 1 'udplso 192.168.100.22:1113'\na span 24 100 100 1482 100000 1 'udplso 192.168.200.24:1113'\na span 25 100 100 1482 100000 1 'udplso 192.168.200.25:1113'\na seat 'udplsi 192.168.100.23:1113'\na seat 'udplsi 192.168.200.23:1113'\n\ns\nOf course the bprc file must also be updated to add reflect the additional LTP neighbors, but that extension is straightforward so we will not be listing them here.
"},{"location":"Configure-Multiple-Network-Interfaces/#use-of-contact-graph","title":"Use of Contact Graph","text":"For ION, the use contact graph is optional when there is one hop. In that case, the data rate, normally defined in the contact graph, is provided through commands plan command in .bprc file.
When contact graph is present, the information in the contact graph supersedes the data rate specified in the plan command.
If there are no contact graph and the data rate is either 0 or omitted in the plan command, then there is no bundle level throttling of data.
exit command","text":"When no contact graph is provided, only immediate neighbor can exchange data. If relay operation is stil desired, an exit command can be used. In the case of the topology presented earlier, the node GS can be a gateway between the rfnet and gsnet. So GS can be added as an exit node for identified pair of source-destination.
ION offers software developer a set of standard interface for adding extensions to Bundle Protocol without modifying the core BP source code. This capability can be used to implement both standardized bundle extension blocks or user-specific extension blocks.
ION's interface for extending the Bundle Protocol enables the definition of external functions that insert extension blocks into outbound bundles (either before or after the payload block), parse and record extension blocks in inbound bundles, and modify extension blocks at key points in bundle processing. All extension-block handling is statically linked into ION at build time, but the addition of an extension never requires that any standard ION source code be modified.
Standard structures for recording extension blocks -- both in transient storage memory during bundle acquisition (AcqExtBlock) and in persistent storage [the ION database] during subsequent bundle processing (ExtensionBlock) -- are defined in the bei.h header file. In each case, the extension block structure comprises a block type code, block processing flags, possibly a list of EID references, an array of bytes (the serialized form of the block, for transmission), the length of that array, optionally an extension-specific opaque object whose structure is designed to characterize the block in a manner that's convenient for the extension processing functions, and the size of that object.
"},{"location":"Extension-Block-Interface/#extension-definition-extesniondef-extensiondefs","title":"Extension Definition:ExtesnionDef & extensionDefs","text":"The definition of each extension is asserted in an ExtensionDef structure, also as defined in the bei.h header file.
/**\n * \\struct ExtensionDef\n * \\brief Defines the callbacks used to process extension blocks.\n *\n * ExtensionDef defines the callbacks for production and acquisition\n * of a single type of extension block, identified by block type name\n * and number.\n */\ntypedef struct\n{\n char name[32]; /** Name of extension */\n BpBlockType type; /** Block type */\n\n /* Production callbacks. */\n\n BpExtBlkOfferFn offer; /** Offer */\n BpExtBlkSerializeFn serialize; /** Serialize */\n BpExtBlkProcessFn process[5]; /** Process */\n BpExtBlkReleaseFn release; /** Release */\n BpExtBlkCopyFn copy; /** Copy */\n\n /* Acquisition callbacks. */\n\n BpAcqExtBlkAcquireFn acquire; /** Acquire */\n BpAcqExtReviewFn review; /** Review */\n BpAcqExtBlkDecryptFn decrypt; /** Decrypt */\n BpAcqExtBlkParseFn parse; /** Parse */\n BpAcqExtBlkCheckFn check; /** Check */\n BpExtBlkRecordFn record; /** Record */\n BpAcqExtBlkClearFn clear; /** Clear */\n} ExtensionDef;\nEach ExtensionDef must supply:
The name of the extension. (Used in some diagnostic messages.)
The extension's block type code.
A pointer to an offer function.
A pointer to a function to be called when forwarding a bundle containing this sort of block.
A pointer to a function to be called when taking custody of a bundle containing this sort of block.
A pointer to a function to be called when enqueuing for transmission a bundle containing this sort of block.
A pointer to a function to be called when a convergence-layer adapter dequeues a bundle containing this sort of block, before serializing it.
A pointer to a function to be called immediately before a convergence-layer adapter transmits a bundle containing this sort of block, after the bundle has been serialized.
A pointer to a release function.
A pointer to a copy function.
A pointer to an acquire function.
A pointer to a review function.
A pointer to a decrypt function.
A pointer to a parse function.
A pointer to a check function.
A pointer to a record function.
A pointer to a clear function.
All extension definitions must be coded into an array of ExtensionDef structures named extensionDefs.
"},{"location":"Extension-Block-Interface/#extensionspec-specification-for-producing-an-extension-block","title":"ExtensionSpec - specification for producing an extension block","text":"/* ExtensionSpec provides the specification for producing an\n * outbound extension block: block definition (identified by\n * block type number), a formulation tag whose semantics are\n * block-type-specific, and applicable CRC type. */\n\ntypedef struct\n{\n BpBlockType type; /* Block type */\n unsigned char tag; /* Extension-specific */\n BpCrcType crcType; /* Type of CRC on block */\n} ExtensionSpec;\nAn array of ExtensionSpec structures named extensionSpecs is also required. Each ExtensionSpec provides the specification for producing an outbound extension block:
The order of appearance of extension specifications in the extensionSpecs array determines the order in which extension blocks will be inserted into locally sourced bundles.
"},{"location":"Extension-Block-Interface/#procedure-to-extend-the-bundle-protocol","title":"Procedure to Extend the Bundle Protocol","text":"The standard extensionDefs array -- which is empty -- is in the noextensions.c prototype source file. The procedure for extending the Bundle Protocol in ION is as follows:
Specify -DBP_EXTENDED in the Makefile's compiler command line when building the libbpP.c library module.
Create a copy of the prototype extensions file, named \"bpextensions.c\", in a directory that is made visible to the Makefile's libbpP.c compilation command line (by a -I parameter).
In the \"external function declarations\" area of \"bpextensions.c\", add \"extern\" function declarations identifying the functions that will implement your extension (or extensions).
Add one or more ExtensionDef structure initialization lines to the extensionDefs array, referencing those declared functions.
Add one or more ExtensionSpec structure initialization lines to the extensionSpecs array, referencing those extension definitions.
Develop the implementations of the extension implementation functions in one or more new source code files.
Add the object file or files for the new extension implementation source file (or files) to the Makefile's command line for linking libbpP.so.
The function pointers supplied in each ExtensionDef must conform to the following specifications.
NOTE that any function that modifies the bytes member of an ExtensionBlock or AckExtBlock must set the corresponding length to the new length of the bytes array, if changed.
int (*BpExtBlkOfferFn)(ExtensionBlock *blk, Bundle *bundle)\nPopulates all fields of the indicated ExtensionBlock structure for inclusion in the indicated outbound bundle. This function is automatically called when a new bundle is locally sourced or upon acquisition of a remotely sourced bundle that does not contain an extension block of this type. The values of the extension block are typically expected to be a function of the state of the bundle, but this is extension-specific. If it is not appropriate to offer an extension block of this type as part of this bundle, then the size, length, object, and bytes members of blk must all be set to zero. If it is appropriate to offer such a block but no internal object representing the state of the block is needed, the object and size members of blk must be set to zero. The type, blkProcFlags, and dataLength members of blk must be populated by the implementation of the \"offer\" function, but the length and bytes members are typically populated by calling the BP library function serializeExtBlk(), which must be passed the block to be serialized (with type, blkProcFlags and dataLength already set), a Lyst of EID references (two list elements -- offsets -- per EID reference, if applicable; otherwise NULL), and a pointer to the extension-specific block data. The block's bytes array and object (if present) must occupy space allocated from the ION database heap. Return zero on success, -1 on any system failure.
int (*BpExtBlkProcessFn)(ExtensionBlock *blk, Bundle *bundle, void *context)\nPerforms some extension-specific transformation of the data encapsulated in blk based on the state of bundle. The transformation to be performed will typically vary depending on whether the identified function is the one that is automatically invoked upon forwarding the bundle, upon taking custody of the bundle, upon enqueuing the bundle for transmission, upon removing the bundle from the transmission queue, or upon transmitting the serialized bundle. The context argument may supply useful supplemental information; in particular, the context provided to the ON_DEQUEUE function will comprise the name of the protocol for the duct from which the bundle has been dequeued, together with the EID of the neighboring node endpoint to which the bundle will be directly transmitted when serialized. The block-specific data in blk is located within bytes immediately after the header of the extension block; the length of the block's header is the difference between length and dataLength. Whenever the block's blkProcFlags, EID extensions, and/or block-specific data are altered, the serializeExtBlk() function should be called again to recalculate the size of the extension block and rebuild the bytes array. Return zero on success, -1 on any system failure.
void (*BpExtBlkReleaseFn)(ExtensionBlock *blk)\nReleases all ION database space occupied by the object member of blk. This function is automatically called when a bundle is destroyed. Note that incorrect implementation of this function may result in a database space leak.
int (*BpExtBlkCopyFn)(ExtensionBlock *newblk, ExtensionBlock *oldblk)\nCopies the object member of oldblk to ION database heap space and places the address of that new non-volatile object in the object member of newblk, also sets size in newblk. This function is automatically called when two copies of a bundle are needed, e.g., in the event that it must both be delivered to a local client and also fowarded to another node. Return zero on success, -1 on any system failure.
int (*BpAcqExtBlkAcquireFn)(AcqExtBlock *acqblk, AcqWorkArea *work)\nPopulates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is only to be provided for extension blocks that are never encrypted; a extension block that may be encrypted should have a BpAcqExtBlkParseFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkReviewFn)(AcqWorkArea *work)\nReviews the extension blocks that have been acquired for this bundle, checking to make sure that all blocks of this type that are required by policy are present. Returns 0 if any blocks are missing, 1 if all required blocks are present, -1 on any system failure.
int (*BpAcqExtBlkDecryptFn)(AcqExtBlock *acqblk, AcqWorkArea *work)\nDecrypts some other extension block that has been acquired but not yet parsed, nominally using encapsulated ciphersuite information. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if no error in decryption was encountered, -1 on any system failure.
int (*BpAcqExtBlkParseFn)(AcqExtBlock *acqblk, AcqWorkArea *work)\nPopulates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is provided for extension blocks that may be encrypted; a extension block that can never be encrypted should have a BpAcqExtBlkAcquireFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkCheckFn)(AcqExtBlock *acqblk, AcqWorkArea *work)\nExamines the bundle in work to determine whether or not it is authentic, in the context of the indicated extension block. Return 1 if the block is determined to be inauthentic (this will cause the bundle to be discarded), zero if no inauthenticity is detected, -1 on any system failure.
int (*BpExtBlkRecordFn)(ExtensionBlock *blk, AcqExtBlock *acqblk)\nCopies the object member of acqblk to ION database heap space and places the address of that non-volatile object in the object member of blk; also sets size in blk. This function is automatically called when an acquired bundle is accepted for forwarding and/or delivery. Return zero on success, -1 on any system failure.
void (*BpAcqExtBlkClearFn)(AcqExtBlock *acqblk)\nUses MRELEASE to release all ION working memory occupied by the object member of acqblk. This function is automatically called when acquisition of a bundle is completed, whether or not the bundle is accepted. Note that incorrect implementation of this function may result in a working memory leak.
"},{"location":"Extension-Block-Interface/#utility-functions-for-extension-processing","title":"Utility Functions for Extension Processing","text":"void discardExtensionBlock(AcqExtBlock *blk)\nDeletes this block from the bundle acquisition work area prior to the recording of the bundle in the ION database.
void scratchExtensionBlock(ExtensionBlock *blk)\nDeletes this block from the bundle after the bundle has been recorded in the ION database.
Object findExtensionBlock(Bundle *bundle, unsigned int type, unsigned char tag1, unsigned char tag2, unsigned char tag3)\nOn success, returns the address of the ExtensionBlock in bundle for the indicated type and tag values. If no such extension block exists, returns zero.
int serializeExtBlk(ExtensionBlock *blk, char *blockData)\nConstructs a BPv7-conformant serialized representation of this extension block in blk->bytes. Returns 0 on success, -1 on an unrecoverable system error.
void suppressExtensionBlock(ExtensionBlock *blk)\nCauses blk to be omitted when the bundle to which it is attached is serialized for transmission. This suppression remains in effect until it is reversed by restoreExtensionBlock();
void restoreExtensionBlock(ExtensionBlock *blk)\nReverses the effect of suppressExtensionBlock(), enabling the block to be included when the bundle to which it is attached is serialized.
"},{"location":"ICI-API/","title":"Interplanetary Communications Infrastructure (ICI) APIs","text":"This section will focus on a subset of ICI APIs that enables an external application to create, manipulate, and access data objects inside ION's SDR.
"},{"location":"ICI-API/#ici-apis","title":"ICI APIs","text":""},{"location":"ICI-API/#header","title":"Header","text":"#include \"ion.h\"\n#define MTAKE(size) allocFromIonMemory(__FILE__, __LINE__, size)\n#define MRELEASE(addr) releaseToIonMemory(__FILE__, __LINE__, addr)\nallocFromIonMemory and releaseToIonMemory, the functional equivalent of malloc and free for ION. The allocated memory space comes from the ION working memory, which has been pre-allocated during the ION configuration.Function Prototype
extern int ionAttach();\nParameters
Return Value
Example Call
if (ionAttach() < 0)\n{\n putErrmsg(\"bpadmin can't attach to ION.\", NULL);\n\n /* User calls error handling routine. */\n}\nDescription
Attached is the invoking task to ION infrastructure as previously established by running the ionadmin utility program. After successful execution, the handle to the ION SDR can be obtained by a separate API call. putErrmsg is an ION logging API, which will be described later in this document.
Function Prototype
extern void ionDetach();\nParameters
Return Value
Example Call
ionDetach();\nDescription
Detaches the invoking task from ION infrastructure. In particular, releases handle allocated for access to ION's non-volatile database.
"},{"location":"ICI-API/#ionterminate","title":"ionTerminate","text":"Function Prototype
extern void ionTerminate();\nParameters
Return Value
Example Call
ionTerminate();\nDescription
Shuts down the entire ION node, terminating all daemons. The state of the SDR will be destroyed during the termination process, even if the SDR heap is implemented in a non-volatile storage, such as a file.
"},{"location":"ICI-API/#ionstartattendant","title":"ionStartAttendant","text":"Function Prototype
extern int ionStartAttendant(ReqAttendant *attendant);\nParameters
*attendant: pointer to a ReqAttendant structure that will be initialized by this function.typedef struct\n{\n sm_SemId semaphore;\n} ReqAttendant;\nReturn Value
Example Call
if (ionStartAttendant(&attendant))\n{\n putErrmsg(\"Can't initialize blocking transmission.\", NULL);\n\n /* user implemented error handling routine */\n}\nDescription
Initializes the semaphore in attendant to block a pending ZCO space request. This is necessary to ensure that the invoking task cannot inject data into the Bundle Protocol Agent until SDR space has been allocated.
Function Prototype
extern void ionStopAttendant(ReqAttendant *attendant);\nParameters
*attendant: pointer to a ReqAttendant structure that will be destroyed by this function.Return Value
Example Call
ionStopAttendant(&attendant);\nDescription
Destroys the semaphore in attendant, preventing a potential resource leak. This is typically called at the end of a BP application after all user data have been injected into the SDR.
Function Prototype
void ionPauseAttendant(ReqAttendant *attendant)\nParameters
*attendant: pointer to a ReqAttendant structure.Return Value
Example Call
ionStopAttendant(&attendant);\nDescription
\"Ends\" the semaphore in attendant so that the task blocked on taking it is interrupted and may respond to an error or shutdown condition. This may be required when trying to quit a blocked user application while acquiring ZCO space.
"},{"location":"ICI-API/#ioncreatezco","title":"ionCreateZco","text":"Function Prototype
extern Object ionCreateZco( ZcoMedium source,\n Object location,\n vast offset,\n vast length,\n unsigned char coarsePriority,\n unsigned char finePriority,\n ZcoAcct acct,\n ReqAttendant *attendant);\nParameters
Source: the type of ZCO to be created. Each source data object may be either a file, a \"bulk\" item in mass storage, an object in SDR heap space (identified by heap address stored in an \"object reference\" object in SDR heap), an array of bytes in SDR heap space (identified by heap address), or another ZCO.
typedef enum\n{\n ZcoFileSource = 1,\n ZcoBulkSource = 2,\n ZcoObjSource = 3,\n ZcoSdrSource = 4,\n ZcoZcoSource = 5\n} ZcoMedium;\nlocation: the location in the heap where a single extent of source data resides. The user application usually places this data via sdr_malloc(), which will be discussed later.offset: the offset within the source data object where the first byte of the ZCO should be placed.length: the length of the ZCO to be created.coarsePriority: this sets the bundle's Class of Service (COS) as an inherited feature from BPv6. Although COS is not specified in BPv7, ION API supports this feature when creating ZCOs. From the lowest to the highest priorities, it can be set to the following values:BP_BULK_PRIORITY (value =0)BP_STD_PRIORITY (value = 1), or BP_EXPEDITED_PRIORITY (value = 2)finePriority: this is inherited from BPv6 COS and is the finer grain priority level (level 0 to 254) within the BP_STD_PRIORITY class. The default value is 0.acct: The accounting category for the ZCO, which is either ZcoInbound (0), ZcoOutbound (1), or ZcoUnknown (2). If a ZCO is created for transmission to another node, this parameter is typically set to ZcoOutbound.*attendant: the semaphore that blocks the return of the function until the necessary resources have been allocated in the SDR for the ZCOReturn Value
((Object) -1): the function has failed0: either the attendant was NULL and sufficient space for the first extent of the ZCO was not immediately available, or the function was interrupted by ionPauseAttendant before space for the ZCO became available.Example Call
SdrObject bundleZco;\n\nbundleZco = ionCreateZco(ZcoSdrSource, extent, 0, lineLength,\n BP_STD_PRIORITY, 0, ZcoOutbound, &attendant);\nif (bundleZco == 0 || bundleZco == (Object) ERROR)\n{\n putErrmsg(\"Can't create ZCO extent.\", NULL);\n /* user implemented error handling routine goes here */\n}\nDescription
This function provides a \"blocking\" implementation of admission control in ION. Like zco_create(), it constructs a zero-copy object (see zco(3)) that contains a single extent of source data residing at a location in the source, of which the initial offset number of bytes are omitted and the subsequent length bytes are included. By providing an attendant semaphore, initialized by ionStartAttendant, ionCreateZco() can be executed as a blocking call so long as the total amount of space in the source available for new ZCO formation is less than the length. ionCreateZco() operates by calling ionRequestZcoSpace, then pending on the semaphore in attendant as necessary before creating the ZCO and then populating it with the user's data.
SDR persistent data are referenced by object and address values in the application code, simply displacements (offsets) within the SDR address space. The difference between the two is that an Object is always the address of a block of heap space returned by some call to sdr_malloc, while an Address can refer to any byte in the SDR address space. An Address is the SDR functional equivalent of a C pointer; some Addresses point to actual Objects.
The number of SDR-related APIs is significant, and most are used by ION internally. Fortunately, there are only a few APIs that an external application will likely need to use. The following list of the most commonly used APIs is drawn from the Database I/O and the Heap Space Management API categories.
"},{"location":"ICI-API/#header_1","title":"Header","text":"#include \"sdr.h\"\nFunction Prototype
Object sdr_malloc(Sdr sdr, unsigned long size)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachsize: size of the block to allocateReturn Value
Example Call
CHKZERO(sdr_begin_xn(sdr));\nextent = sdr_malloc(sdr, lineLength);\nif (extent)\n{\n sdr_write(sdr, extent, text, lineLength);\n}\n\nif (sdr_end_xn(sdr) < 0)\n{\n putErrmsg(\"No space for ZCO extent.\", NULL);\n bp_detach();\n return 0;\n}\nIn this example, a 'critical section' has been implemented by API calls: sdr_begin_xn and sdr_end_xn. The critical section ensures that the SDR is not altered while the space allocation is in progress. These APIs will be explained later in this document. The sdr_write API is used to write data into the space acquired by sdr_malloc.
It may seem strange that failing to allocate space or write the data into the allocated space relies on checking the return value of sdr_end_xn instead of sdr_malloc and sdr_write functions. This is because when sdr_end_xn returns a negative value, it indicates that an SDR transaction was already terminated, which occurs when sdr_malloc or sdr_write fails. So, this is a convenient way to detect the failure of two calls simultaneously by checking the sdr_end_xn call return value.
Description
Allocates a block of space from the indicated SDR's heap. The maximum size is 1/2 of the maximum address space size (i.e., 2G for a 32-bit machine). Returns block address if successful, zero if block could not be allocated.
"},{"location":"ICI-API/#sdr_insert","title":"sdr_insert","text":"Function Prototype
Object sdr_insert(Sdr sdr, char *from, unsigned long size)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attach*from: pointer to the location where several bytes (specified by size) of data are to be copied into the allocated space in the SDRsize: size of the block to allocateReturn Value
Example Call
CHKZERO(sdr_begin_xn(sdr));\nextent = sdr_insert(sdr, text, lineLength);\nif (sdr_end_xn(sdr) < 0)\n{\n putErrmsg(\"No space for ZCO extent.\", NULL);\n bp_detach();\n return 0;\n}\nDescription
This function combines the action of sdr_malloc and sdr_write. It first uses sdr_malloc to obtain a block of space, and if this allocation is successful, it uses sdr_write to copy size bytes of data from memory into the newly allocated block.
Function Prototype
Object sdr_stow(sdr, variable)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachvariable: the variable whose value is to be inserted into an SDR spaceReturn Value
Description
sdr_stow is a macro that uses sdr_insert to insert a copy of a variable into the dataspace. The size of the variable is used as the number of bytes to copy.
Function Prototype
int sdr_object_length(Sdr sdr, Object object)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachobject: the location of an application data objectReturn Value
Description
Returns the number of bytes of heap space allocated to the application data at object.
"},{"location":"ICI-API/#sdr_free","title":"sdr_free","text":"Function Prototype
void sdr_free(Sdr sdr, Object object)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachobject: the location of an application data ObjectReturn Value
Description
Frees the heap space occupied by an object at object. The space freed are put back into the SDR memory pool and will become available for subsequent re-allocation.
"},{"location":"ICI-API/#sdr_read","title":"sdr_read","text":"Function Prototype
void sdr_read(Sdr sdr, char *into, Address from, int length)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attach*into: the location in memory data should be read intofrom: this is a location in the SDR heaplength: this is the size to be readReturn Value
Description
Copies length characters from (a location in the indicated SDR) to the memory location given by into. The data are copied from the shared memory region in which the SDR resides, if any; otherwise, they are read from the file in which the SDR resides.
"},{"location":"ICI-API/#sdr_stage","title":"sdr_stage","text":"Function Prototype
void sdr_stage(Sdr sdr, char *into, Object from, int length)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attach*into: the location in memory data should be read intofrom: this is a location in the SDR heap which is occupied by an allocated objectlength: this is the size to be readReturn Value
Description
Like sdr_read, this function will copy length characters from (a location in the heap of the indicated SDR) to the memory location given by into. Unlike sdr_get, sdr_stage requires that from be the address of some allocated object, not just any location within the heap. sdr_stage, when called from within a transaction, notifies the SDR library that the indicated object may be updated later in the transaction; this enables the library to retrieve the object's size for later reference in validating attempts to write into some location within the object. If the length is zero, the object's size is privately retrieved by SDR, but none of the object's content is copied into memory.
sdr_get is a macro that uses sdr_read to load variables from the SDR address given by heap_pointer; heap_pointer must be (or be derived from) a heap pointer as returned by sdr_pointer. The size of the variable is used as the number of bytes to copy.
Function Prototype
void sdr_write(Sdr sdr, Address into, char *from, int length)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attach*into: the location in the SDR heap where data should be written intofrom: this is a location in memory where data should copied fromlength: this is the size to be writtenReturn Value
Description
Like sdr_read, this function will copy length characters from (a location in the heap of the indicated SDR) to the memory location given by into. Unlike sdr_get, sdr_stage requires that from be the address of some allocated object, not just any location within the heap. sdr_stage, when called from within a transaction, notifies the SDR library that the indicated object may be updated later in the transaction; this enables the library to retrieve the object's size for later reference in validating attempts to write into some location within the object. If length is zero, the object's size is privately retrieved by SDR but none of the object's content is copied into memory.
sdr_get is a macro that uses sdr_read to load variables from the SDR address given by heap_pointer; heap_pointer must be (or be derived from) a heap pointer as returned by sdr_pointer. The size of the variable is used as the number of bytes to copy.
The following APIs manage transactions by implementing a critical section in which SDR content cannot be modified.
"},{"location":"ICI-API/#header_2","title":"Header","text":"#include \"sdrxn.h\"\nFunction Prototype
int sdr_begin_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Initiates a transaction. Returns 1 on success, 0 on any failure. Note that transactions are single-threaded; any task that calls sdr_begin_xn is suspended until all previously requested transactions have been ended or canceled.
Function Prototype
int sdr_in_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Returns 1 if called in the course of a transaction, 0 otherwise.
"},{"location":"ICI-API/#sdr_exit_xn","title":"sdr_exit_xn","text":"Function Prototype
void sdr_exit_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Simply abandons the current transaction, ceasing the calling task's lock on ION. MUST NOT be used if any dataspace modifications were performed during the transaction; sdr_end_xn must be called instead to commit those modifications.
Function Prototype
void sdr_cancel_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Cancels the current transaction. If reversibility is enabled for the SDR, canceling a transaction reverses all heap modifications performed during that transaction.
"},{"location":"ICI-API/#sdr_end_xn","title":"sdr_end_xn","text":"Function Prototype
int sdr_end_xn(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
Description
Ends the current transaction. Returns 0 if the transaction was completed without any error; returns -1 if any operation performed in the course of the transaction failed, in which case the transaction was automatically canceled.
"},{"location":"ICI-API/#sdr-list-management-apis","title":"SDR List management APIs","text":"The SDR list management functions manage doubly-linked lists in managed SDR heap space. The functions manage two kinds of objects: lists and list elements. A list knows how many elements it contains and what its start and end elements are. An element knows what list it belongs to and the elements before and after it in the list. An element also knows its content, which is normally the SDR Address of some object in the SDR heap. A list may be sorted, which speeds the process of searching for a particular element.
"},{"location":"ICI-API/#header_3","title":"Header","text":"#include \"sdr.h\"\n\ntypedef int (*SdrListCompareFn)(Sdr sdr, Address eltData, void *argData);\ntypedef void (*SdrListDeleteFn)(Sdr sdr, Object elt, void *argument);\nUSAGE
When inserting elements or searching a list, the user may optionally provide a compare function of the form:
int user_comp_name(Sdr sdr, Address eltData, void *dataBuffer);\nWhen provided, this function is automatically called by the sdrlist function being invoked; when the function is called, it is passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, dataBuffer, which is nominally the address in the local memory of some other item in the same format. The user-supplied function normally compares some key values of the two data items. It returns 0 if they are equal, an integer less than 0 if eltData's key value is less than that of dataBuffer, and an integer greater than 0 if eltData's key value is greater than that of dataBuffer. These return values will produce a list in ascending order. If the user desires the list to be in descending order, the function must reverse the signs of these return values.
When deleting an element or destroying a list, the user may optionally provide a delete function of the form:
void user_delete_name(Sdr sdr, Address eltData, void *argData)\nWhen provided, this function is automatically called by the sdrlist function being invoked; when the function is called, it is passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, argData, which if non-NULL is normally the address in the local memory of a data item providing context for the list element deletion. The user-supplied function performs any application-specific cleanup associated with deleting the element, such as freeing the element's content data item and/or other SDR heap space associated with the element.
"},{"location":"ICI-API/#sdr_list_insert_first","title":"sdr_list_insert_first","text":""},{"location":"ICI-API/#sdr_list_insert_last","title":"sdr_list_insert_last","text":"Function Prototype
Object sdr_list_insert_first(Sdr sdr, Object list, Address data)\nObject sdr_list_insert_last(Sdr sdr, Object list, Address data)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a listdata: an address in SDRReturn Value
address of newly created element: success0: any errorDescription
Creates a new element and inserts it at the front/end of the list. This function should not be used to insert a new element into any ordered list; use sdr_list_insert() instead.
Function Prototype
Object sdr_list_create(Sdr sdr)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachReturn Value
address of newly created list: Success0: any errorDescription
Creates a new list object in the SDR; the new list object initially contains no list elements. Returns the address of the new list or zero on any error.
"},{"location":"ICI-API/#sdr_list_length","title":"sdr_list_length","text":"Function Prototype
int sdr_list_length(Sdr sdr, Object list)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDRReturn Value number of elements in the list: Success *-1`: any error
Description
Returns the number of elements in the list, or -1 on any error.
"},{"location":"ICI-API/#sdr_list_destroy","title":"sdr_list_destroy","text":"Function Prototype
void sdr_list_destroy(Sdr sdr, Object list, SdrListDeleteFn fn, void *arg)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDR to be destroyedfn: a sdrlist delete functionarg: arguments passed to the delete functionReturn Value
Description
Destroys a list, freeing all elements of the list. If fn is non-NULL, that function is called once for each freed element; when called, fn is passed the Address that is the element's data, and the argument pointer is passed to sdr_list_destroy. See the manual page for sdrlist for details on the form of the delete function sdrlist.
Do not use sdr_free to destroy an SDR list, as this would leave the elements of the list allocated yet unreferenced.
"},{"location":"ICI-API/#sdr_list_user_data_set","title":"sdr_list_user_data_set","text":"Function Prototype
void sdr_list_user_data_set(Sdr sdr, Object list, Address userData)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDR to be destroyeduserData: a single word which is a SDR addressReturn Value
Description
Sets the \"user data\" word of list to userData. Note that userData is nominally an Address but can be any value that occupies a single word. It is typically used to point to an SDR object that somehow characterizes the list as a whole, such as a name.
"},{"location":"ICI-API/#sdr_list_user_data","title":"sdr_list_user_data","text":"Function Prototype
Address sdr_list_user_data(Sdr sdr, Object list)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDR to be destroyedReturn Value
value of the \"user data\" word of list: Success0: any errorDescription
Returns the value of the \"user data\" word of list, or zero on any error.
"},{"location":"ICI-API/#sdr_list_insert","title":"sdr_list_insert","text":"Function Prototype
Object sdr_list_insert(Sdr sdr, Object list, Address data, SdrListCompareFn fn, void *dataBuffer)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: a list in SDR to be destroyeddata: address in SDRfn: a sdrlist compare functiondataBuffer: data pass to the compare functionReturn Value
value of the \"user data\" word of list: Success0: any errorDescription
Creates a new list element whose data value is data and inserts that element into the list. If fn is NULL, the new list element is simply appended to the list; otherwise, the new list element is inserted after the last element in the list whose data value is \"less than or equal to\" the data value of the new element (in dataBuffer) according to the collating sequence established by fn. Returns the address of the newly created element or zero on any error.
"},{"location":"ICI-API/#sdr_list_insert_before","title":"sdr_list_insert_before","text":""},{"location":"ICI-API/#sdr_list_insert_after","title":"sdr_list_insert_after","text":"Function Prototype
Object sdr_list_insert_before(Sdr sdr, Object elt, Address data)\nObject sdr_list_insert_after(Sdr sdr, Object elt, Address data)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: an element of a list in the SDRdata: an address in SDRReturn Value
address of the newly created list element: success0: any errorDescription
Creates a new element and inserts it before/after the specified list element. This function should not be used to insert a new element into an ordered list; use sdr_list_insert instead. Returns the address of the newly created list element or zero on any error.
Function Prototype
void sdr_list_delete(Sdr sdr, Object elt, SdrListDeleteFn fn, void *arg)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: an element of a list in the SDRfn: a sdr list delete function*arg: argument passed to the delete functionReturn Value
Description
Delete elt from the list it is in. If fn is non-NULL, that function will be called upon deletion of elt; when called, that function is passed the Address that is the list element's data value and the arg pointer passed to sdr_list_delete.
Function Prototype
Object sdr_list_first(Sdr sdr, Object list)\nObject sdr_list_last(Sdr sdr, Object list)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachlist: address of a list in the SDRReturn Value
address to the first/last element: success0: any errorDescription
Returns the address of the first/last element of the list, or zero on any error.
"},{"location":"ICI-API/#sdr_list_next","title":"sdr_list_next","text":""},{"location":"ICI-API/#sdr_list_prev","title":"sdr_list_prev","text":"Function Prototype
Object sdr_list_next(Sdr sdr, Object elt)\nObject sdr_list_prev(Sdr sdr, Object elt)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistReturn Value
address to the element following/preceding the element provided: success0: any errorDescription
Returns the address of the element following/preceding elt in that element's list or zero on any error.
"},{"location":"ICI-API/#sdr_list_search","title":"sdr_list_search","text":"Function Prototype
Object sdr_list_search(Sdr sdr, Object elt, int reverse, SdrListCompareFn fn, void *dataBuffer);\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistreverse: order of searchfn: a sdrlist compare function*dataBuffer: address of data to be used for searchReturn Value
address to the matching element: success0: any errorDescription
Search a list for an element whose data matches the data in dataBuffer, starting at the indicated initial list element.
If the compare function is non-NULL, the list is assumed to be sorted in the order implied by that function, and the function is automatically called once for each element of the list until it returns a value that is greater than or equal to zero (where zero indicates an exact match and a value greater than zero indicates that the list contains no matching element); each time compare is called it is passed the Address that is the element's data value and the dataBuffer value passed to sm_list_search(). If the reverse is non-zero, then the list is searched in reverse order (starting at the indicated initial list element), and the search ends when the compare function returns a value that is less than or equal to zero. If the compare function is NULL, then the entire list is searched (in either forward or reverse order, as directed) until an element is located whose data value is equal to ((Address) dataBuffer). Returns the address of the matching element if one is found, 0 otherwise.
"},{"location":"ICI-API/#sdr_list_list","title":"sdr_list_list","text":"Function Prototype
Object sdr_list_list(Sdr sdr, Object elt)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistReturn Value
address to the list to which elt belongs: success0: any errorDescription
Returns the address of the list to which elt belongs, or 0 on any error.
"},{"location":"ICI-API/#sdr_list_data","title":"sdr_list_data","text":"Function Prototype
Address sdr_list_data(Sdr sdr, Object elt)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistReturn Value
address that is the data value of elt: success0: any errorDescription
Returns the Address that is the data value of elt, or 0 on any error.
"},{"location":"ICI-API/#sdr_list_data_set","title":"sdr_list_data_set","text":"Function Prototype
Address sdr_list_data_set(Sdr sdr, Object elt, Address data)\nParameters
sdr: handle to the ION SDR obtained through ionAttach or bp_attachelt: address of an element in a sdrlistdata: address of data in SDRReturn Value
original data value of elt: success0: any errorDescription
Sets the data value for elt to data, replacing the original value. Returns the original data value for elt, or 0 on any error. The original data value for elt may or may not have been the address of an object in heap data space; even if it was, that object was NOT deleted.
Warning: changing the data value of an element of an ordered list may ruin the ordering of the list.
"},{"location":"ICI-API/#other-less-used-ici-apis","title":"Other less used ICI APIs","text":"There are many other less frequently used APIs. Please see the manual pages for the following:
ion, sdr, sdrlist, platform, lyst, psm, memmgr, sdrstring, sdrtable, and smlist.
This section covers interfaces for users to access the following four DTN application-level services provided by ION:
The CFDP library provides functions enabling application software to use CFDP to send and receive files. It conforms to the Class 1 (Unacknowledged) service class defined in the CFDP Blue Book and includes several standard CFDP user operations implementations.
In the ION implementation of CFDP, the CFDP notion of entity ID is identical to the BP (CBHE) notion of DTN node number used in ION.
CFDP entity and transaction numbers may be up to 64 bits in length. For portability to 32-bit machines, these numbers are stored in the CFDP state machine as structures of type CfdpNumber.
To simplify the interface between CFDP and the user application without risking storage leaks, the CFDP-ION API uses MetadataList objects. A MetadataList is a specially formatted SDR list of user messages, filestore requests, or filestore responses. During the time that a MetadataList is pending processing via the CFDP APIs, but is not yet (or is no longer) reachable from any FDU object, a pointer to the list is appended to one of the lists of MetadataList objects in the CFDP non-volatile database. This assures that any unplanned termination of the CFDP daemons won't leave any SDR lists unreachable - and therefore un-recyclable - due to the absence of references to those lists. Restarting CFDP will automatically purge any unused MetadataLists from the CFDP database. The \"user data\" variable of the MetadataList itself is used to implement this feature: while the list is reachable only from the database root, its user data variable points to the database root list from which it is referenced. In contrast, the list is attached to a File Delivery Unit; its user data is NULL.
CFDP transmits the data in a source file in fixed-sized segments by default. The user application can override this behavior at the time transmission of a file is requested by supplying a file reader callback function that reads the file - one byte at a time - until it detects the end of a \"record\" that has application significance. Each time CFDP calls the reader function, the function must return the length of one such record (not greater than 65535).
When CFDP is used to transmit a file, a 32-bit checksum must be provided in the \"EOF\" PDU to enable the receiver of the file to ensure that it was not corrupted in transit. When supplied with an application-specific file reader function, it updates the computed checksum as it reads each file byte; a CFDP library function is provided. Two types of file checksums are supported: a simple modular checksum or a 32-bit CRC. The checksum type must be passed through to the CFDP checksum computation function, so it must be provided by (and thus to) the file reader function.
The user application may provide per-segment metadata. To enable this, upon formation of each file data segment, CFDP will invoke the user-provided per-segment metadata composition callback function (if any), a function conforming to the CfdpMetadataFn type definition. The callback will be passed the offset of the segment within the file, the segment's offset within the current record (as applicable), the length of the segment, an open file descriptor for the source file (in case the data must be read to construct the metadata), and a 63-byte buffer in which to place the new metadata. The callback function must return the metadata length to attach to the file data segment PDU (may be zero) or -1 in case of a general system failure.
The return value for each CFDP \"request\" function (put, cancel, suspend, resume, report) is a reference number that enables \"events\" obtained by calling cfdp_get_event() to be matched to the requests that caused them. Events with a reference number set to zero were caused by autonomous CFDP activity, e.g., the reception of a file data segment.
#include \"cfdp.h\"\n\ntypedef enum\n{\n CksumTypeUnknown = -1,\n ModularChecksum = 0,\n CRC32CChecksum = 2,\n NullChecksum = 15\n} CfdpCksumType;\n\ntypedef int (*CfdpReaderFn)(int fd, unsigned int *checksum, CfdpCksumType ckType);\n\ntypedef int (*CfdpMetadataFn)(uvast fileOffset, unsigned int recordOffset, unsigned int length, int sourceFileFD, char *buffer);\n\ntypedef enum\n{\n CfdpCreateFile = 0,\n CfdpDeleteFile,\n CfdpRenameFile,\n CfdpAppendFile,\n CfdpReplaceFile,\n CfdpCreateDirectory,\n CfdpRemoveDirectory,\n CfdpDenyFile,\n CfdpDenyDirectory\n} CfdpAction;\n\ntypedef enum\n{\n CfdpNoEvent = 0,\n CfdpTransactionInd,\n CfdpEofSentInd,\n CfdpTransactionFinishedInd,\n CfdpMetadataRecvInd,\n CfdpFileSegmentRecvInd,\n CfdpEofRecvInd,\n CfdpSuspendedInd,\n CfdpResumedInd,\n CfdpReportInd,\n CfdpFaultInd,\n CfdpAbandonedInd\n} CfdpEventType;\n\ntypedef struct\n{\n char *sourceFileName;\n char *destFileName;\n MetadataList messagesToUser;\n MetadataList filestoreRequests;\n CfdpHandler *faultHandlers;\n int unacknowledged;\n unsigned int flowLabelLength;\n unsigned char *flowLabel;\n int recordBoundsRespected;\n int closureRequested;\n} CfdpProxyTask;\n\ntypedef struct\n{\n char *directoryName;\n char *destFileName;\n} CfdpDirListTask;\nint cfdp_attach()\nAttaches the application to CFDP functionality on the local computer.
Return Value
int cfdp_entity_is_started()\nReturn Value * 1: if the local CFDP entity has been started and not yet stopped * 0: otherwise
"},{"location":"ION-Application-Service-Interface/#cfdp_detach","title":"cfdp_detach","text":"void cfdp_detach()\nTerminates all access to CFDP functionality on the local computer.
"},{"location":"ION-Application-Service-Interface/#cfdp_compress_number","title":"cfdp_compress_number","text":"void cfdp_compress_number(CfdpNumber *toNbr, uvast from)\nConverts an unsigned vast number into a CfdpNumber structure, e.g., for use when invoking the cfdp_put() function.
"},{"location":"ION-Application-Service-Interface/#cfdp_decompress_number","title":"cfdp_decompress_number","text":"void cfdp_decompress_number(uvast toNbr, CfdpNumber *from)\nConverts a numeric value in a CfdpNumber structure to an unsigned vast integer.
"},{"location":"ION-Application-Service-Interface/#cfdp_update_checksum","title":"cfdp_update_checksum","text":"void cfdp_update_checksum(unsigned char octet, uvast *offset, unsigned int *checksum, CfdpCksumType ckType)\nFor use by an application-specific file reader callback function, which must pass to cfdp_update_checksum() the value of each byte (octet) it reads. offset must be octet's displacement in bytes from the start of the file. The checksum pointer is provided to the reader function by CFDP.
"},{"location":"ION-Application-Service-Interface/#cfdp_create_usrmsg_list","title":"cfdp_create_usrmsg_list","text":"MetadataList cfdp_create_usrmsg_list()\nCreates a non-volatile linked list, suitable for containing messages-to-user that are to be presented to cfdp_put().
"},{"location":"ION-Application-Service-Interface/#cfdp_add_usrmsg","title":"cfdp_add_usrmsg","text":"int cfdp_add_usrmsg(MetadataList list, unsigned char *text, int length)\nAppends the indicated message-to-user to list.
"},{"location":"ION-Application-Service-Interface/#cfdp_get_usrmsg","title":"cfdp_get_usrmsg","text":"int cfdp_get_usrmsg(MetadataList list, unsigned char *textBuf, int *length)\nRemoves from list the first of the remaining messages-to-user contained in the list and delivers its text and length. When the last message in the list is delivered, destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_destroy_usrmsg_list","title":"cfdp_destroy_usrmsg_list","text":"void cfdp_destroy_usrmsg_list(MetadataList *list)\nRemoves and destroys all messages-to-user in list and destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_create_fsreq_list","title":"cfdp_create_fsreq_list","text":"MetadataList cfdp_create_fsreq_list()\nCreates a non-volatile linked list, suitable for containing filestore requests that are to be presented to cfdp_put().
"},{"location":"ION-Application-Service-Interface/#cfdp_add_fsreq","title":"cfdp_add_fsreq","text":"int cfdp_add_fsreq(MetadataList list, CfdpAction action, char *firstFileName, char *seconfdFIleName)\nAppends the indicated filestore request to list.
"},{"location":"ION-Application-Service-Interface/#cfdp_get_fsreq","title":"cfdp_get_fsreq","text":"int cfdp_get_fsreq(MetadataList list, CfdpAction *action, char *firstFileNameBuf, char *secondFileNameBuf)\nRemoves from list the first of the remaining filestore requests contained in the list and delivers its action code and file names. When the last request in the list is delivered, destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_destroy_fsreq_list","title":"cfdp_destroy_fsreq_list","text":"void cfdp_destroy_fsreq_list(MetadataList *list)\nRemoves and destroys all filestore requests in list and destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_get_fsresp","title":"cfdp_get_fsresp","text":"int cfdp_get_fsresp(MetadataList list, CfdpAction *action, int *status, char *firstFileNameBuf, char *secondFileNameBuf, char *messageBuf)\nRemoves from list the first of the remaining filestore responses contained in the list and delivers its action code, status, file names, and message. When the last response in the list is delivered, it destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_destroy_fsresp_list","title":"cfdp_destroy_fsresp_list","text":"void cfdp_destroy_fsresp_list(MetadataList *list)\nRemoves and destroys all filestore responses in list and destroys the list.
"},{"location":"ION-Application-Service-Interface/#cfdp_read_space_packets","title":"cfdp_read_space_packets","text":"int cfdp_read_space_packets(int fd, unsigned int *checksum)\nThis is a standard \"reader\" function that segments the source file on CCSDS space packet boundaries. Multiple small packets may be aggregated into a single file data segment.
"},{"location":"ION-Application-Service-Interface/#cfdp_read_text_lines","title":"cfdp_read_text_lines","text":"int cfdp_read_text_lines(int fd, unsigned int *checksum)\nThis is a standard \"reader\" function that segments a source file of text lines on line boundaries.
"},{"location":"ION-Application-Service-Interface/#cfdp_put","title":"cfdp_put","text":"int cfdp_put(CfdpNumber *destinationEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpMetadataFn metadataFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *transactionId)\nSends the file identified by sourceFileName to the CFDP entity identified by destinationEntityNbr. destinationFileName is used to indicate the name by which the file will be catalogued upon arrival at its final destination; if NULL, the destination file name defaults to sourceFileName. If sourceFileName is NULL, it is assumed that the application is requesting transmission of metadata only (as discussed below) and destinationFileName is ignored. Note that both sourceFileName and destinationFileName are interpreted as path names, i.e., directory paths may be indicated in either or both. The syntax of path names is opaque to CFDP; the syntax of sourceFileName must conform to the path naming syntax of the source entity's file system and the syntax of destinationFileName must conform to the path naming syntax of the destination entity's file system.
The byte array identified by utParms, if non-NULL, is interpreted as transmission control information that is to be passed on to the UT layer. The nominal UT layer for ION's CFDP being Bundle Protocol, the utParms array is normally a pointer to a structure of type BpUtParms; see the bp man page for a discussion of the parameters in that structure.
closureLatency is the length of time following transmission of the EOF PDU within which a responding Transaction Finish PDU is expected. If no Finish PDU is requested, this parameter value should be zero.
messagesToUser and filestoreRequests, where non-zero, must be the addresses of non-volatile linked lists (that is, linked lists in ION's SDR database) of CfdpMsgToUser and CfdpFilestoreRequest objects identifying metadata that are intended to accompany the transmitted file. Note that this metadata may accompany a file of zero length (as when sourceFileName is NULL as noted above) -- a transmission of metadata only.
Return Value
*transactionID with the source entity ID and the transaction number assigned to this transmission and returns the request number identifying this \"put\" request. The transaction ID may be used to suspend, resume, cancel, or request a report on the progress of this transmission. int cfdp_cancel(CfdpTransactionId *transactionId)\nCancels transmission or reception of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, cancellation of a file transmission may have little effect.
Return Value * request number: on success * -1: on any error
"},{"location":"ION-Application-Service-Interface/#cfdp_suspend","title":"cfdp_suspend","text":"int cfdp_suspend(CfdpTransactionId *transactionId)\nSuspends transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, suspension of a file transmission may have little effect.
Return Value * request number: on success * -1: on any error
"},{"location":"ION-Application-Service-Interface/#cfdp_resume","title":"cfdp_resume","text":"int cfdp_resume(CfdpTransactionId *transactionId)\nResumes transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, resumption of a file transmission may have little effect.
Return Value * request number: on success * -1: on any error
"},{"location":"ION-Application-Service-Interface/#cfdp_report","title":"cfdp_report","text":"int cfdp_report(CfdpTransactionId *transactionId)\nRequests issuance of a report on the transmission or reception progress of the indicated transaction. The report takes the form of a character string that is returned in a CfdpEvent structure; use cfdp_get_event() to receive the event (which may be matched to the request by request number).
Return Value * request number: on success * 0: if the transaction ID is unknown * -1: on any error
"},{"location":"ION-Application-Service-Interface/#cfdp_get_event","title":"cfdp_get_event","text":"int cfdp_get_event(CfdpEventType *type, time_t *time, int *reqNbr, CfdpTransactionId *transactionId, char *sourceFileNameBuf, char *destFileNameBuf, uvast *fileSize, MetadataList *messagesToUser, uvast *offset, unsigned int *length, CfdpCondition *condition, uvast *progress, CfdpFileStatus *fileStatus, CfdpDeliveryCode *deliveryCode, CfdpTransactionId *originatingTransactionId, char *statusReportBuf, MetadataList *filestoreResponses);\nPopulates return value fields with data from the oldest CFDP event not yet delivered to the application. cfdp_get_event() blocks indefinitely until a CFDP processing event is delivered or the function is interrupted by an invocation of cfdp_interrupt().
Return Value * 0: on success -OR- on application error, returns zero but sets errno to EINVAL. * -1: on system failure
"},{"location":"ION-Application-Service-Interface/#cfdp_interrupt","title":"cfdp_interrupt","text":"void cfdp_interrupt()\nInterrupts an cfdp_get_event() invocation. This function is designed to be called from a signal handler.
"},{"location":"ION-Application-Service-Interface/#cfdp_rput","title":"cfdp_rput","text":"int cfdp_rput(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpNumber *beneficiaryEntityNbr, CfdpProxyTask *proxyTask, CfdpTransactionId *transactionId)\nSends to the indicated respondent entity a \"proxy\" request to perform a file transmission. The transmission is to be subject to the configuration values in proxyTask and the destination of the file is to be the entity identified by beneficiaryEntityNbr.
int cfdp_rput_cancel(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *rputTransactionId, CfdpTransactionId *transactionId)\nSends to the indicated respondent entity a request to cancel a prior \"proxy\" file transmission request as identified by rputTransactionId, which is the value of transactionId that was returned by that earlier proxy transmission request.
"},{"location":"ION-Application-Service-Interface/#cfdp_get","title":"cfdp_get","text":"int cfdp_get(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpProxyTask *proxyTask, CfdpTransactionId *transactionId)\nSame as cfdp_rput except that beneficiaryEntityNbr is omitted; the local entity is the implicit beneficiary of the request.
"},{"location":"ION-Application-Service-Interface/#cfdp_rls","title":"cfdp_rls","text":"int cfdp_rls(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpDirListTask *dirListTask, CfdpTransactionId *transactionId)\nSends to the indicated respondent entity a request to prepare a directory listing, save that listing in a file, and send it to the local entity. The request is subject to the configuration values in dirListTask.
int cfdp_preview(CfdpTransactionId *transactionId, uvast offset, unsigned int length, char *buffer);\nThis function enables the application to get an advanced look at the content of a file that CFDP has not yet fully received. Reads length bytes starting at offset bytes from the start of the file that is the destination file of the transaction identified by transactionID, into buffer.
Return Value * number of bytes read: on success * 0: on user error (transaction is nonexistent or is outbound, or offset is beyond the end of file) * -1: on system failure
"},{"location":"ION-Application-Service-Interface/#cfdp_map","title":"cfdp_map","text":"int cfdp_map(CfdpTransactionId *transactionId, unsigned int *extentCount, CfdpExtent *extentsArray);\nThis function enables the application to report on the portions of a partially-received file that have been received and written. Lists the received continuous data extents in the destination file of the transaction identified by transactionID. The extents (offset and length) are returned in the elements of extentsArray; the number of extents returned in the array is the total number of continuous extents received so far, or extentCount, whichever is less.
Return Value * 0: on success, the total number of extents received so far is reported through extentCount * -1: on system failure, returns -1
cfdptest","text":"ION provides application CFDP test program called cfdptest, which installed as part of regular ION build/install process and can be invoked from terminal this way:
cfdptest\nThe shell program present a ':' prompt for interactive mode commanding. You can type 'h' to see a list of available commands.
One can also feed a sequence of commands to cfdptest non-interactively such that you will not see the stdout of the program. This is useful for running automated tests.
cfdptest [file_containing_cfdptest_commands]\nA third way to use cfdptest is to feed command scripts but allows the interactive responses to be displayed in stdout:
cfdptest < [file_containing_cfdptest_commands]\nThe cfdptest.c source code is also provided as a code examples on how write applications using the CFDP APIs. The cfdptest command set can be found in the manual pages here.
this section is work-in-progress
"},{"location":"ION-Application-Service-Interface/#bundle-streaming-service-bss","title":"Bundle Streaming Service (BSS)","text":"The BSS library supports the streaming of data over delay-tolerant networking (DTN) bundles. The intent of the library is to enable applications that pass streaming data received in transmission time order (i.e., without time regressions) to an application-specific \"display\" function -- notionally for immediate real-time display -- but to store all received data (including out-of-order data) in a private database for playback under user control. The reception and real-time display of in-order data is performed by a background thread, leaving the application's main (foreground) thread free to respond to user commands controlling playback or other application-specific functions.
The application-specific \"display\" function invoked by the background thread must conform to the RTBHandler type definition. It must return 0 on success, -1 on any error that should terminate the background thread. Only on return from this function will the background thread proceed to acquire the next BSS payload.
All data acquired by the BSS background thread is written to a BSS database comprising three files: table, list, and data. The name of the database is the root name that is common to the three files, e.g., db3.tbl, db3.lst, db3.dat would be the three files making up the db3 BSS database. All three files of the selected BSS database must reside in the same directory of the file system.
Several replay navigation functions in the BSS library require that the application provide a navigation state structure of type bssNav as defined in the bss.h header file. The application is not reponsible for populating this structure; it's strictly for the private use of the BSS library.
"},{"location":"ION-Application-Service-Interface/#bundle-streaming-service-bss-bundle-streaming-service-protocol-bssp-cla","title":"Bundle Streaming Service (BSS) & Bundle Streaming Service Protocol (BSSP CLA)","text":"The Bundle Streaming Service (BSS) and the Bundle Streaming Service Protocol (BSSP) CLA are independent modules.
The BSSP CLA is designed to emulate a connection between two DTN neighboring nodes characterized by two delivery mechanisms: (a) a minimal delay, unreliable channel (physical or logical), and (b) a potentially delayed, but reliable channel. The minimal delay channel is emulated by transpot UDP (with a timer mechanism added) and the reliable channel is emulated via TCP transport.
A DTN user mission may decide to use a single CCSDS AOS or TM downlink with LTP CLA running on top as its reliability mechanism. In that case, it can directly use the LTP CLA in ION and interface it with the CCSDS framing protocol which could be implemented by the mission's avionic system or the radio.
However, it is also possible that a mission may utilize different types of transports, for example, using multiple downlinks via S, X, Ka-band or optical, each with different reliability mechanism (or not). Alternatively, a flight system may also use commercial communications services with differentiated delays and levels of reliability. In such case, BSSP can be used to approximate such configuration in a lab environment for prototyping and testing the impact on streaming data delivery, until the actual CLAs are implemented and tested.
The Bundle Streaming Service, on the other hand, is an application-level service that can be used with any underlying CLAs to handle both realtime and delayed, in-order playback of streaming data including video, audio, and telemetry. When the user scenario is appropriate, BSS can certainly be used over BSSP CLA, but that is not a requirement.
"},{"location":"ION-Application-Service-Interface/#bss-apis","title":"BSS APIs","text":"The following section describes the BSS library APIs.
"},{"location":"ION-Application-Service-Interface/#bssopen","title":"bssOpen","text":"int bssOpen(char *bssName, char *path, char *eid)\nint bssStart(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)\nStarts a BSS data acquisition background thread. bssName identifies the BSS database into which data will be acquired. path identifies the directory in which that database resides. eid is used to open the BP endpoint at which the delivered BSS bundle payload contents will be acquired. buffer identifies a data acquisition buffer, which must be provided by the application, and bufLen indicates the length of that buffer; received bundle payloads in excess of this length will be discarded.
handler identifies the display function to which each in-order bundle payload will be passed. The time and count parameters passed to this function identify the received bundle, indicating the bundle's creation timestamp time (in seconds) and counter value. The buffer and bufLength parameters indicate the location into which the bundle's payload was acquired and the length of the acquired payload. handler must return -1 on any unrecoverable system error, 0 otherwise. A return value of -1 from handler will terminate the BSS data acquisition background thread.
On any failure, returns -1. On success, returns zero.
"},{"location":"ION-Application-Service-Interface/#bssrun","title":"bssRun","text":"int bssRun(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)\nA convenience function that performs both bssOpen() and bssStart(). On any failure, returns -1. On success, returns zero.
"},{"location":"ION-Application-Service-Interface/#bssclose","title":"bssClose","text":"void bssClose()\nvoid bssStop()\nTerminates the most recently initiated BSS data acquisition background thread.
"},{"location":"ION-Application-Service-Interface/#bssexit","title":"bssExit","text":"void bssExit()\nA convenience function that performs both bssClose() and bssStop().
"},{"location":"ION-Application-Service-Interface/#bssread","title":"bssRead","text":"long bssRead(bssNav nav, char *data, int dataLen)\nCopies the data at the current playback position in the database, as indicated by nav, into data; if the length of the data is in excess of dataLen then an error condition is asserted (i.e., -1 is returned). Note that bssRead() cannot be successfully called until nav has been populated, nominally by a preceding call to bssSeek(), bssNext(), or bssPrev(). Returns the length of data read, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssseek","title":"bssSeek","text":"long bssSeek(bssNav *nav, time_t time, time_t *curTime, unsigned long *count)\nSets the current playback position in the database, in nav, to the data received in the bundle with the earliest creation time that was greater than or equal to time. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssseek_read","title":"bssSeek_read","text":"long bssSeek_read(bssNav *nav, time_t time, time_t *curTime, unsigned long *count, char *data, int dataLen)\nA convenience function that performs bssSeek() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssnext","title":"bssNext","text":"long bssNext(bssNav *nav, time_t *curTime, unsigned long *count)\nSets the playback position in the database, in nav, to the data received in the bundle with the earliest creation time and ID count greater than that of the bundle at the current playback position. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location (if any), -2 on reaching end of list, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssnext_read","title":"bssNext_read","text":"long bssNext_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)\nA convenience function that performs bssNext() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, -2 on reaching end of list, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssprev","title":"bssPrev","text":"long bssPrev(bssNav *nav, time_t *curTime, unsigned long *count)\nSets the playback position in the database, in nav, to the data received in the bundle with the latest creation time and ID count earlier than that of the bundle at the current playback position. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location (if any), -2 on reaching end of list, or -1 on any error.
"},{"location":"ION-Application-Service-Interface/#bssprev_read","title":"bssPrev_read","text":"long bssPrev_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)\nA convenience function that performs bssPrev() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, -2 on reaching end of list, or -1 on any error
"},{"location":"ION-Application-Service-Interface/#asynchronous-messaging-service-ams-apis","title":"Asynchronous Messaging Service (AMS) APIs","text":"This section is under construction.
"},{"location":"ION-Application-Service-Interface/#delay-tolerant-payload-conditioning-dtpc-communications-library","title":"Delay-Tolerant Payload Conditioning (DTPC) communications library","text":""},{"location":"ION-Application-Service-Interface/#description","title":"Description","text":"The dtpc library provides functions enabling application software to use Delay-Tolerant Payload Conditioning (DTPC) when exchanging information over a delay-tolerant network. DTPC is an application service protocol, running in a layer immediately above Bundle Protocol, that offers delay-tolerant support for several end-to-end services to applications that may require them. These services include delivery of application data items in transmission (rather than reception) order; detection of reception gaps in the sequence of transmitted application data items, with end-to-end negative acknowledgment of the missing data; end-to-end positive acknowledgment of successfully received data; end-to-end retransmission of missing data, driven either by negative acknowledgment or timer expiration; suppression of duplicate application data items; aggregation of small application data items into large bundle payloads, to reduce bundle protocol overhead; and application-controlled elision of redundant data items in aggregated payloads, to improve link utiliization.
"},{"location":"ION-Application-Service-Interface/#dtpc-apis","title":"DTPC APIs","text":"int dptc_attach( )\nvoid dptc_detach( )\nTerminates all access to DTPC functionality on the local computer.
int dtpc_entity_is_started( )\nint dtpc_open(unsigned int topicID, DtpcElisionFn elisionFn, DtpcSAP *dtpcsapPtr)\nEstablishes the application as the sole authorized client for posting and receiving application data items on topic topicID within the local BP node. On success, the service access point for posting and receiving such data items is placed in *dtpcsapPtr, the elision callback function elisionFn (if not NULL) is associated with this topic, and 0 is returned. Returns -1 on any error.
int dtpc_send(unsigned int profileID, DtpcSAP sap, char *destEid, unsigned int maxRtx, unsigned int aggrSizeLimit, unsigned int aggrTimeLimit, int lifespan, BpAncillaryData *ancillaryData, unsigned char srrFlags, BpCustodySwitch custodySwitch, char *reportToEid, int classOfService, Object item, unsigned int length)\nTransmission of that outbound ADU will be subject to the profile identified by profileID, as asserted by dtpcadmin(1), if profileID is non-zero. In that case, maxRtx, aggrSizeLimit, aggrTimeLimit, lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService are ignored.
If profileID is zero then the profile asserted by dtpcadmin(1) that matches maxRtx, aggrSizeLimit, aggrTimeLimit, lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService will govern transmission of the ADU, unless no such profile has been asserted, in which case dtpc_send() returns 0 indicating user error.
maxRtx is the maximum number of times any single DTPC ADU transmitted subject to the indicated profile may be retransmitted by the DTPC entity. If maxRtx is zero, then the DTPC transport service features (in-order delivery, end-to-end acknowledgment, etc.) are disabled for this profile.
aggrSizeLimit is the size threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrSizeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
aggrTimeLimit is the time threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrTimeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService are as defined for bp_send (see bp(3)).
item must be an object allocated within ION's SDR \"heap\", and length must be the length of that object. The item will be inserted into the outbound ADU's list of data items posted for the topic associated with sap, and the elision callback function declared for sap (if any, and if the applicable profile does not disable transmission optimization features) will be invoked immediately after insertion of the application data item but before DTPC makes any decision on whether or not to initiate transmission of the outbound ADU.
The function returns 1 on success, 0 on any user application error, -1 on any system error.
int dtpc_receive(DtpcSAP sap, DtpcDelivery *dlvBuffer, int timeoutSeconds)\nThe \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one application data item on the topic associated with sap has not yet been delivered to the SAP, then the payload of the oldest such item will be returned in dlvBuffer-__item_ and dlvBuffer-__result_ will be set to PayloadPresent. If there is no such item, dtpc_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is DTPC_POLL (i.e., zero) and no application data item is awaiting delivery, or if timeoutSeconds is greater than zero but no item arrives before timeoutSeconds have elapsed, then dlvBuffer-__result_ will be set to ReceptionTimedOut. If timeoutSeconds is DTPC_BLOCKING (i.e., -1) then bp_receive() blocks until either an item arrives or the function is interrupted by an invocation of dtpc_interrupt().
dlvBuffer-__result_ will be set to ReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer-__result_ will be set to DtpcServiceStopped in the event that DTPC service has been terminated on the local node.
The application data item delivered in the DTPC delivery structure, if any, will be an object allocated within ION's SDR \"heap\"; the length of that object will likewise be provided in the DtpcDelivery structure.
Be sure to call dtpc_release_delivery() after every successful invocation of dtpc_receive().
The function returns 0 on success, -1 on any error.
void dtpc_interrupt(DtpcSAP sap)\nvoid dtpc_release_delivery(DtpcDelivery *dlvBuffer)\nvoid dtpc_close(DtpcSAP sap)\nThe following coding guidelines apply to all software delivered as part of the Interplanetary Overlay Network (ION) distribution, except:
Every process should return an exit code on termination. * On normal termination, the exit code should be 0. * On abnormal or error termination, the exit code should be a non-zero number in the range 1-255. * In this case the code should be 1 unless specific codes are used to distinguish between different kinds of errors.
"},{"location":"ION-Coding-Guide/#function-design-guidelines","title":"Function Design Guidelines","text":"All file I/O should be performed using POSIX functions rather than the buffered I/O functions fopen, fread, fseek, etc. This is because buffered I/O entails the dynamic allocation of system memory, which some missions may prohibit in flight software.
The iputs function provided in platform.c should be used in place of fputs, and the igets function should be used in place of fgets. Rather than fscanf, use igets and sscanf; rather than fprintf, use isprintf and iputs.
All varargs-based string composition should be performed using isprintf rather than sprintf, to minimize the chance of overrunning string composition buffers. (isprintf is similar to snprintf. Since VxWorks 5.4 does not support snprintf, isnprintf is included in platform.c.)
Similarly, all string copying should be performed using istrcpy rather than strcpy, strncpy, and strcat.
The isignal function should be used instead of signal; it ensures that reception of a signal will always interrupt system calls in SVR4 fashion even when running on a FreeBSD platform.
The iblock function provides a simple, portable means of preventing reception of the indicated signal by the calling thread.
Data objects larger than 1024 bytes should not be declared in stack space. This is to * Minimize complaints by Coverity, and * Minimize the chance of overrunning allocated stack space when running on a VxWorks platform.
Static variables that must be made globally accessible should be declared within external functions, rather than declared as external variables. This is per the JPL C Coding Standard, but it also has the useful property of providing an easy way to track all access to a global static variable in gdb: you just set a breakpoint at the start of the function in which the variable is declared.
In the implementation of any ION library function or any ION task\u2019s top-level driver function, any condition that prevents the function from continuing execution toward producing the effect it is designed to produce is considered an \u201cerror\u201d.
Detection of an error should result in the printing of an error message and, normally, the immediate return of whatever return value is used to indicate the failure of the function in which the error was detected.
By convention this value is usually -1, but both zero and NULL are appropriate failure indications under some circumstances such as object creation.
The CHKERR, CHKZERO, CHKNULL, and CHKVOID macros are used to implement this behavior in a standard and lexically terse manner. Use of these macros offers an additional feature: for debugging purposes, they can easily be configured to call sm_Abort() to terminate immediately with a core dump instead of returning a error indication. This option is enabled by setting the compiler parameter CORE_FILE_NEEDED to 1 at compilation time.
In the absence of any error, the function returns a value that indicates nominal completion. By convention this value is usually zero, but under some circumstances other values (such as pointers or addresses) are appropriate indications of nominal completion. Any additional information produced by the function, such as an indication of \u201csuccess\u201d, is usually returned as the value of a reference argument.
However, database management functions and the SDR hash table management functions deviate from this rule: most return 0 to indicate nominal completion but functional failure (e.g., duplicate key or object not found) and return 1 to indicate functional success.
Whenever returning a value that indicates an error: * If the failure is due to the failure of a system call or some other non-ION function, assu=me that errno has already been set by the function at the lowest layer of the call stack; use putSysErrmsg (or postSysErrmsg if in a hurry) as described below. * Otherwise \u2013 i.e., the failure is due to a condition that was detected within ION \u2013use putErrmsg (or postErrmg if pressed for time) as described below; this will aid in tracing the failure through the function stack in which the failure was detected.
When a failure in a called function is reported to \u201cdriver\u201d code in an application program, before continuing or exiting use writeErrmsgMemos() to empty the message pool and print a simple stack trace identifying the failure.
Calling code may choose to ignore the error indication returned by a function (e.g., when an error returned by an sdr function is subsumed by a future check of the error code returned by sdr_end_xn). To do so without incurring the wrath of a static analysis tool, pass the entire function call as the sole argument to the oK macro; the macro operates on the return code, casting it to (void) and thus placating static analysis.
To write a simple status message, use writeMemo. To write a status message and annotate that message with some other context-dependent string, use writeMemoNote. (The itoa and utoa functions may be used to express signed and unsigned integer values, respectively, as strings for this purpose.) Note that adhering to ION\u2019s conventions for tagging status messages will simplify any automated status message processing that the messages might be delivered to, i.e., the first four characters of the status message should be as follows:
To write a simple diagnostic message, use putErrmsg; the source file name and line number will automatically be inserted into the message text, and a context-dependent string may be provided. (Again the itoa and utoa functions may be helpful here.) The diagnostic message should normally begin with a capital letter and end with a period.
To write a diagnostic message in response to the failure of a system call or some other non-ION function that sets errno, use putSysErrmsg instead. In this case, the diagnostic message should normally begin with a capital letter and not end with a period.
This page contains guidelines for programming in the C language.
"},{"location":"ION-Coding-Guide/#naming-conventions","title":"Naming Conventions","text":"Names of global variables, local variables, structure fields, and function arguments are in mixed upper and lower case, without embedded underscores, and beginning with a lowercase letter.
int numItems;\nvoid computeSomething(int firstArg, int secondArg);\n extern int ltp_open(unsigned long clientId);\n#define SYMBOLIC_CONSTANT 5\nUnions are not used.
Typedef names are in mixed upper and lower case, with the first token capitalized. Type names are never the same as the structure or enum tags for the structures and enums that they name.
typedef struct gloplist_str\n{\nint thing1;\nint thing2;\n} GlopList;\nNo line of source text is ever more than 80 characters long. When the length of a line of code exceeds 80 characters, the line of code is wrapped across two or more lines of text. Whenever the point at which the text must be wrapped is within a literal, a newline character () is inserted at the wrap point and the continuation of the literal begins in the first column of the next text line. Otherwise, each continuation line is normally indented two tab stops from the first text line of the long line of code; when indenting just one tab stop (rather than two) seems to make the code more readable, indenting one tab stop is okay. When a single meaningful clause of a source code line must be wrapped across multiple lines of text, each text line after the first line in that clause is normally indented one additional tab stop.
In the declaration of a function or variable, the type name and function/variable name are normally separated by a single tab. They may be separated by multiple tabs when this is necessary in order to have the variable names in multiple consecutive variable declarations line up, which is always preferred.
Functions are written with the return type, function name, and arguments as a single line of code, subject to the code line wrapping guidelines given above. The opening brace of the function definition appears in the first column of the next line.
The opening brace of a structure definition likewise appears in the first column of the next line after the structure name.
A control statement (starting with if, else, while, or switch) begins a new line of code. The opening brace for the control statement always appears on the next line, at the same indentation as the control statement keyword.
The first line of code appearing after an opening brace (whether for a structure definition, for a function definition, or in the scope of a control statement) always appears on the next line, indented one tab stop. From that point on, every subsequent line of code is indented the same number of tabs as the preceding line of code, subject to the code line wrapping guidelines given above.
Every closing brace always appears in the same column as the corresponding opening brace.
Every closing brace is always followed by a single blank line, except when it is immediately followed either by another closing brace (which will be indented one less tab stop) or by an else (which will be indented by the same number of tab stops as the closing brace and, therefore, the corresponding if).
static void computeSomething(int numItems, Item *items)\n{\n unsigned int x;\n int i;\n\n while (x > 0)\n {\n x--;\n }\n\n for (i = 0; i < numItems; i++)\n {\n x += items[i].field1;\n }\n\n if (numItems == 0)\n {\n doThis();\n }\n else\n {\n doThat();\n }\n}\nThe case labels in switch statements line up with the braces. Every case (or default) label in the switch, after the first case, is preceded by a blank line. Cases which do not include a break or return statement either contain no code at all or else end with a comment along the lines of:
/* Intentional fall-through to next case. */\nFor example:\nswitch (ch)\n{\ncase 'A':\n.\n.\n.\nbreak;\n\ncase 'B':\ncase 'C':\n.\n.\n.\nbreak;\n\ncase 'D':\n.\n.\n.\n/* Intentionally falls through. */\n\ncase 'E':\n.\n.\n.\nbreak;\n\ndefault:\n.\n.\n.\nbreak;\n}\nComments are so rare and valuable that we hesitate to risk discouraging them by overly constraining their format. In general, comments should be inserted in such a way as to be as easy as possible to read in relevant context. The multi-line comment formatting performed automatically by vim is particularly acceptable.
/* Here is the beginning of an extremely long comment, so long\n * that it has to wrap over two lines of source code text. */\nUse \u2013 and write \u2013 thread-safe library functions where possible. E.g., normally prefer strtok_r() to strtok().
Avoid writing non-portable code, e.g., prefer POSIX library calls to OS-specific library calls.
Template for \".c\" files
1 2 3 4 5 6 7 \n123456789012345678901234567890123456789012345678901234567890123456789012\n/*\n platform_sm.c: platform-dependent implementation of common\n functions, to simplify porting.\n\n Author: Alan Schlutsmeyer, JPL\n\n Copyright 1997, California Institute of Technology.\n ALL RIGHTS RESERVED. U.S. Government sponsorship\n acknowledged.\n */\nEach file should have a header comment like the one shown above.
#include <stdio.h>\n#include <locallib.h>\n#include \"appheader.h\"\n .\n .\n .\n.h files are included just after the header. System-provided headers should be specified with angle brackets; ION-provided headers should be specified with double-quotes.
#define SYMBOLIC_CONSTANT 5\nNext, symbolic constants and macros (if any) are defined. They normally go first, because they might be used in the definitions of data types and static variables. However, symbolic constants and macros may be inserted later in the source text if that will improve the readability of the file.
typedef struct fb_str\n{\n int field1;\n in field2;\n} Foobar;\nData types are defined next because they might be used by static variables.
static int numFoobars = 0; /* Number of foobars in the program. */\n .\n .\n .\nGlobal functions used only within the program should be declared static. Public function prototypes should be in a header file; the definitions of those functions, with their headers, are included in the corresponding .c file. Low-level functions, such as commonly-used utility functions, appear first in the .c file. They are followed by the functions that call those functions directly, followed by higher-level-functions that call those functions, and so on.
Template for \".h\" Files
1 2 3 4 5 6 7 \n123456789012345678901234567890123456789012345678901234567890123456789012\n/*\n platform_sm.h: portable definitions of types and functions.\n\n Author: Alan Schlutsmeyer, JPL\n\n Copyright 1997, California Institute of Technology.\n ALL RIGHTS RESERVED. U.S. Government sponsorship\n acknowledged.\n */\nEach header file begins with a standard header comment like the one shown above.
#ifndef _PLATFORM_SM_H_\n#define _PLATFORM_SM_H_\nEach header file must have an \"include\" guard.
#include \"platform.h\"\n .\n .\n .\n#ifdef __cplusplus\nextern \"C\" {\n#endif\nNext come declarations of various sorts, followed by the ends of the C++ and \u201cinclude\u201d guards.
#ifdef __cplusplus\n}\n#endif\n\n#endif\nNothing should go after the \"#endif\" of the include guard.
"},{"location":"ION-Config-File-Templates/","title":"Available Configuration File Templates","text":"The following configurations can be downloaded (see file attachment)
These configuration files are provided to give you a basic functional setup; they may not be sufficient to support all features and throughput performance you want to achieve for your network. So please use them as a template and apply update as necessary.
"},{"location":"ION-Deployment-Guide/","title":"ION Deployment Guide","text":"Version 4.1.3
Jay Gao, Jet Propulsion Laboratory, California Institute of Technology
Sky DeBaun, Jet Propulsion Laboratory, California Institute of Technology
Document Change Log
Ver No. Date Description Note V4.1.3 11/6/2023 Add LTP Performance Test Converted to markd down V4.1.2 1/5/2023 Added notes on SDR file and CGRM"},{"location":"ION-Deployment-Guide/#overview","title":"Overview","text":"The effort required to deploy the Interplanetary Overlay Network (ION) software in an operational setting may vary widely depending on the scope of the deployment and the degree to which the required ION functionality coincides with the capability provided by default in the software as distributed. This effort will be expended in two general phases: initial infusion and ongoing operation.
"},{"location":"ION-Deployment-Guide/#infusion","title":"Infusion","text":"Even in the best case, some minimal degree of configuration will be required. Many elements of ION behavior are managed at run time by decisions recorded in ION's protocol state databases, as populated by a variety of administration utility programs. Others are managed at compile time by means of compiler command-line switches selected when the software is built. These compile-time configuration options are described in the Configuration section below.
In some cases, mission-specific behavior that goes beyond the options built into ION must be enabled during ION deployment. The intent of the ION design is to minimize -- to eliminate, if possible -- any need to modify ION source code in order to enable mission-specific behavior. Two general strategies are adopted for this purpose.
First, ION includes a number of conditionally defined functions that can be cleanly replaced with mission-specific alternative source code by setting a compiler command-line switch at build time. Setting such a switch causes the mission-specific source code, written in C, to be simply included within the standard ION source code at the time of compilation.
Second, more generally it is always possible to add new application executables, new startup/shutdown/monitor/control utilities or scripts, and even entirely new route computation systems, BP convergence-layer adapters, and/or LTP link service adapters without ever altering the distributed ION source code. A few rough guidelines for making these kinds of modifications are described in the Adaptation section below.
Finally, in rare cases it may be necessary to execute ION in an operating-system environment to which it has not yet been ported. Guidance for porting ION to new platforms will be provided in a future edition of this Deployment Guide.
"},{"location":"ION-Deployment-Guide/#operation","title":"Operation","text":"On an ongoing basis, an ION deployment may require reconfiguration from time to time and/or may require troubleshooting to resolve performance or stability problems. Some suggestions for reconfiguration and troubleshooting procedures are offered in the Operation section below.
"},{"location":"ION-Deployment-Guide/#configuration","title":"Configuration","text":""},{"location":"ION-Deployment-Guide/#configuring-the-ici-module","title":"Configuring the \"ici\" module","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DFSWSOURCE or --DSM_SEMBASEKEY=0xff13), will alter the functionality of ION as noted below.
PRIVATE_SYMTAB
This option causes ION to be built for VxWorks 5.4 or RTEMS with reliance on a small private local symbol table that is accessed by means of a function named sm_FindFunction. Both the table and the function definition are, by default, provided by the symtab.c source file, which is automatically included within the platform_sm.c source when this option is set. The table provides the address of the top-level function to be executed when a task for the indicated symbol (name) is to be spawned, together with the priority at which that task is to execute and the amount of stack space to be allocated to that task.
PRIVATE_SYMTAB is defined by default for RTEMS but not for VxWorks 5.4.
Absent this option, ION on VxWorks 5.4 must successfully execute the VxWorks symFindByName function in order to spawn a new task. For this purpose the entire VxWorks symbol table for the compiled image must be included in the image, and task priority and stack space allocation must be explicitly specified when tasks are spawned.
FSWLOGGER
This option causes the standard ION logging function, which simply writes all ION status messages to a file named ion.log in the current working directory, to be replaced (by #include) with code in the source file fswlogger.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
FSWCLOCK
This option causes the invocation of the standard time function within getUTCTime (in ion.c) to be replaced (by #include) with code in the source file fswutc.c, which might for example invoke a mission-specific function to read a value from the spacecraft clock. A file of this name must be in the inclusion path for the compiler.
FSWWDNAME
This option causes the invocation of the standard getcwd function within cfdpInit (in libcfdpP.c) to be replaced (by #include) with code in the source file wdname.c, which must in some way cause the mission-specific value of current working directory name to be copied into cfdpdbBuf.workingDirectoryName. A file of this name must be in the inclusion path for the compiler.
FSWSYMTAB
If the PRIVATE_SYMTAB option is also set, then the FSWSYMTAB option causes the code in source file mysymtab.c to be included in platform_sm.c in place of the default symbol table access implementation in symtab.c. A file named mysymtab.c must be in the inclusion path for the compiler.
FSWSOURCE
This option simply causes FSWLOGGER, FSWCLOCK, FSWWDNAME, and FSWSYMTAB all to be set.
GDSLOGGER
This option causes the standard ION logging function, which simply writes all ION status messages to a file named ion.log in the current working directory, to be replaced (by #include) with code in the source file gdslogger.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
GDSSOURCE
This option simply causes GDSLOGGER to be set.
TRACKRFXEVENTS
This option causes user-written code, in a file named rfxtracker.c, to be executed every time the rfxclock daemon dispatches a schedule RFX event such as the start or end of a transmission contact. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
ION_OPS_ALLOC=*xx*
This option specifies the percentage of the total non-volatile storage space allocated to ION that is reserved for protocol operational state information, i.e., is not available for the storage of bundles or LTP segments. The default value is 40.
ION_SDR_MARGIN=*xx*
This option specifies the percentage of the total non-volatile storage space allocated to ION that is reserved simply as margin, for contingency use. The default value is 20.
The sum of ION_OPS_ALLOC and ION_SDR_MARGIN defines the amount of non-volatile storage space that is sequestered at the time ION operations are initiated: for purposes of congestion forecasting and prevention of resource oversubscription, this sum is subtracted from the total size of the SDR \"heap\" to determine the maximum volume of space available for bundles and LTP segments. Data reception and origination activities fail whenever they would cause the total amount of data store space occupied by bundles and segments to exceed this limit.
HEAP_PTRS
This is an optimization option for the SDR non-volatile data management system: when set, it enables the value of any variable in the SDR heap to be accessed directly by means of a pointer into the dynamic memory that is used as the data store storage medium, rather than by reading the variable into a location in local stack memory. Note that this option must not be enabled if the data store is configured for file storage only, i.e., if the SDR_IN_DRAM flag was set to zero at the time the data store was created by calling sdr_load_profile. See the ionconfig(5) man page in Appendix A for more information.
NO_SDR_TRACE
This option causes non-volatile storage utilization tracing functions to be omitted from ION when the SDR system is built. It disables a useful debugging option but reduces the size of the executable software.
NO_PSM_TRACE
This option causes memory utilization tracing functions to be omitted from ION when the PSM system is built. It disables a useful debugging option but reduces the size of the executable software.
IN_FLIGHT
This option controls the behavior of ION when an unrecoverable error is encountered.
If it is set, then when an unrecoverable error is encountered the status message \"Unrecoverable SDR error\" is logged and the SDR non-volatile storage management system is globally disabled: the current data store access transaction is ended and (provided transaction reversibility is enabled) rolled back, and all ION tasks terminate.
Otherwise, the ION task that encountered the error is simply aborted, causing a core dump to be produced to support debugging.
SM_SEMKEY=0x*XXXX*
This option overrides the default value (0xee01) of the identifying \"key\" used in creating and locating the global ION shared-memory system mutex.
SVR4_SHM
This option causes ION to be built using svr4 shared memory as the pervasive shared-memory management mechanism. svr4 shared memory is selected by default when ION is built for any platform other than MinGW (for which File Mapping objects are used), VxWorks 5.4, or RTEMS. (For the latter two operating systems all memory is shared anyway, due to the absence of a protected-memory mode.)
POSIX1B_SEMAPHORES
This option causes ION to be built using POSIX semaphores as the pervasive semaphore mechanism. POSIX semaphores are selected by default when ION is built for RTEMS but are otherwise not used or supported; this option enables the default to be overridden.
SVR4_SEMAPHORES
This option causes ION to be built using svr4 semaphores as the pervasive semaphore mechanism. svr4 semaphores are selected by default when ION is built for any platform other than MinGW (for which Windows event objects are used), VxWorks 5.4 (for which VxWorks native semaphores are the default choice), or RTEMS (for which POSIX semaphores are the default choice).
SM_SEMBASEKEY=0x*XXXX*
This option overrides the default value (0xee02) of the identifying \"key\" used in creating and locating the global ION shared-memory semaphore database, in the event that svr4 semaphores are used.
SEMMNI=*xxx*
This option declares to ION the total number of svr4 semaphore sets provided by the operating system, in the event that svr4 semaphores are used. It overrides the default value, which is 128. (Changing this value typically entails rebuilding the O/S kernel.)
SEMMSL=*xxx*
This option declares to ION the maximum number of semaphores in each svr4 semaphore set, in the event that svr4 semaphores are used. It overrides the default value, which is 250. (Changing this value typically entails rebuilding the O/S kernel.)
SEMMNS=*xxx*
This option declares to ION the total number of svr4 semaphores that the operating system can support; the maximum possible value is SEMMNI x SEMMSL. It overrides the default value, which is 32000. (Changing this value typically entails rebuilding the O/S kernel.)
Note that this option is also supported in the MinGW (Windows) port of ION, with the same default value; changing this value does not involve an operating system modification.
ION_NO_DNS
This option causes the implementation of a number of Internet socket I/O operations to be omitted for ION. This prevents ION software from being able to operate over Internet connections, but it prevents link errors when ION is loaded on a spacecraft where the operating system does not include support for these functions.
ERRMSGS_BUFSIZE=*xxxx*
This option set the size of the buffer in which ION status messages are constructed prior to logging. The default value is 4 KB.
SPACE_ORDER=*x*
This option declares the word size of the computer on which the compiled ION software will be running: it is the base-2 log of the number of bytes in an address. The default value is 2, i.e., the size of an address is 2^2^ = 4 bytes. For a 64-bit machine, SPACE_ORDER must be declared to be 3, i.e., the size of an address is 2^3^ = 8 bytes.
NO_SDRMGT
This option enables the SDR system to be used as a data access transaction system only, without doing any dynamic management of non-volatile data. With the NO_SDRMGT option set, the SDR system library can (and in fact must) be built from the sdrxn.c source file alone.
DOS_PATH_DELIMITER
This option causes ION_PATH_DELIMITER to be set to '\\' (backslash), for use in the construction of path names. The default value of ION_PATH_DELIMITER is '/' (forward slash, as is used in Unix-like operating systems).
"},{"location":"ION-Deployment-Guide/#configuring-the-ltp-module","title":"Configuring the \"ltp\" module","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DUDP_MULTISEND, will alter the functionality of LTP as noted below.
UDP_MULTISEND
The UDP_MULTISEND option can improve LTP performance by sharply reducing system call overhead: multiple LTP segments encapsulated in UDP datagrams may be transmitted with a single sendmmsg() call rather than multiple sendmsg() calls. This reduces the cost of sending LTP blocks in small segments, which in turn can limit IP fragmentation for LTP traffic.
Note that sendmmsg() has no built-in rate control and offers no opportunity to exercise the rate control algorithm that minimizes UDP congestion loss in non-MULTISEND LTP. In order to achieve similar reduction in UDP congestion loss, a node that receives data sent by sendmmsg() may need to be configured for larger socket buffers. The sysctl operating system utility may be used for this purpose, setting new values for net.core.rmem_max and _default and net.core.wmem_max and _default.
Note also that not all operating systems support the sendmmsg() system call. ION currently enables UDP_MULTISEND only for flavors of Linux other than bionic.
MULTISEND_SEGMENT_SIZE
By default, ION LTP in UDP_MULTISEND mode will always limit LTP segment size to 1450 so that every segment may be encapsulated in an IP packet whose size does not exceed the standard Ethernet frame size. For networks in which the MTU is known to be larger, this parameter may be overridden at compile time.
MULTISEND_BATCH_LIMIT
By default, the maximum number of UDP datagrams that ION LTP in UDP_MULTISEND mode will send in a single sendmmsg() call is automatically computed as the block aggregation size threshold divided by the maximum segment size; that is, normally the amount of data sent per sendmmsg() call is about one LTP block. This parameter may be overridden at compile time.
MULTIRECV_BUFFER_COUNT
In UDP_MULTISEND mode, ION LTP will also use recvmmsg() to receive multiple LTP segments (encapsulated in UDP datagrams) in a single system call. By default, 127 segment reception buffers (each one large enough to receive a single LTP segment of maximum size) are reserved for this purpose. This parameter may be overridden at compile time.
"},{"location":"ION-Deployment-Guide/#configuring-the-bp-module","title":"Configuring the \"bp\" module","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DION_NOSTATS or --DBRSTERM=60), will alter the functionality of BP as noted below.
TargetFFS
Setting this option adapts BP for use with the TargetFFS flash file system on the VxWorks operating system. TargetFFS apparently locks one or more system semaphores so long as a file is kept open. When a BP task keeps a file open for a sustained interval, subsequent file system access may cause a high-priority non-BP task to attempt to lock the affected semaphore and therefore block; in this event, the priority of the BP task may automatically be elevated by the inversion safety mechanisms of VxWorks. This \"priority inheritance\" can result in preferential scheduling for the BP task -- which does not need it -- at the expense of normally higher-priority tasks, and can thereby introduce runtime anomalies. BP tasks should therefore close files immediately after each access when running on a VxWorks platform that uses the TargetFFS flash file system. The TargetFFS compile-time option ensures that they do so.
MULTIDUCTS
It is possible for multiple outducts to be attached to a single egress plan, enabling some bundles to be forwarded to a neighboring node using one outduct while others are forwarded using another. Selection of the outduct to use for the forwarding of a given bundle is a function of the bpclm \"convergence-layer manager\" daemon; each of a given node's egress plans is managed by a single bpclm task. The default outduct selection algorithm exercised by bpclm can be overridden by means of the MULTIDUCTS compile-time configuration option. Setting the -DMULTIDUCTS switch causes the standard outduct configuration logic in the outductSelected() function of bpclm.c to be replaced (by #include) with code in the source file named selectcla.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
The implementation of outductSelected() in ION bpv7 implementation differs somewhat from that in the bpv6 implementation. The content of a very simple selectcla.c file for a node deploying bpv7 might look like this:
if (bundle-\\>destination.ssp.ipn.serviceNbr == 99)\n{\n if (strcmp(protocol-\\>name, \"bssp\") == 0)\n {\n return 1; /\\* Use a BSSP outduct for this bundle. \\*/\n }\n}\nNote that any element of the state of the bundle may be used to select an outduct based on any element of the state of the outduct. The intent is for ION to be able to accommodate virtually any mission-defined algorithm for selecting among communication channels between topologically adjacent BP nodes.
BRSTERM=*xx*
This option sets the maximum number of seconds by which the current time at the BRS server may exceed the time tag in a BRS authentication message from a client; if this interval is exceeded, the authentication message is presumed to be a replay attack and is rejected. Small values of BRSTERM are safer than large ones, but they require that clocks be more closely synchronized. The default value is 5.
ION_NOSTATS
Setting this option prevents the logging of bundle processing statistics in status messages.
KEEPALIVE_PERIOD=*xx*
This option sets the number of seconds between transmission of keep-alive messages over any TCP or BRS convergence-layer protocol connection. The default value is 15.
ION_BANDWIDTH_RESERVED
Setting this option overrides strict priority order in bundle transmission, which is the default. Instead, bandwidth is shared between the priority-1 and priority-0 queues on a 2:1 ratio whenever there is no priority-2 traffic.
"},{"location":"ION-Deployment-Guide/#configuring-the-ams-module","title":"Configuring the \"ams\" module","text":"Defining the following macros, by setting parameters that are provided to the C compiler (for example, -DNOEXPAT or --DAMS_INDUSTRIAL), will alter the functionality of AMS as noted below.
NOEXPAT
Setting this option adapts AMS to expect MIB information to be presented to it in \"amsrc\" syntax (see the amsrc(5) man page) rather than in XML syntax (as described in the amsxml(5) man page), normally because the expat XML interpretation system is not installed. Note that the default syntax for AMS MIB information is now amsrc syntax so the -DNOEXPAT switch is rarely needed.
AMS_INDUSTRIAL
Setting this option adapts AMS to an \"industrial\" rather than safety-critical model for memory management. By default, the memory acquired for message transmission and reception buffers in AMS is allocated from limited ION working memory, which is fixed at ION start-up time; this limits the rate at which AMS messages may be originated and acquired. When --DAMS_INDUSTRIAL is set at compile time, the memory acquired for message transmission and reception buffers in AMS is allocated from system memory, using the familiar malloc() and free() functions; this enables much higher message traffic rates on machines with abundant system memory where flight software constraints on dynamic system memory allocation are not applicable.
"},{"location":"ION-Deployment-Guide/#configuring-the-cfdp-module","title":"Configuring the \"cfdp\" module","text":"Defining the following macro, by setting a parameter that is provided to the C compiler (i.e., --DTargetFFS), will alter the functionality of CFDP as noted below.
TargetFFS
Setting this option adapts CFDP for use with the TargetFFS flash file system on the VxWorks operating system. TargetFFS apparently locks one or more system semaphores so long as a file is kept open. When a CFDP task keeps a file open for a sustained interval, subsequent file system access may cause a high-priority non-CFDP task to attempt to lock the affected semaphore and therefore block; in this event, the priority of the CFDP task may automatically be elevated by the inversion safety mechanisms of VxWorks. This \"priority inheritance\" can result in preferential scheduling for the CFDP task -- which does not need it -- at the expense of normally higher-priority tasks, and can thereby introduce runtime anomalies. CFDP tasks should therefore close files immediately after each access when running on a VxWorks platform that uses the TargetFFS flash file system. The TargetFFS compile-time option assures that they do so.
"},{"location":"ION-Deployment-Guide/#initialization","title":"Initialization","text":"ION requires several runtime configuration settings to be defined at the time a node is initialized. Most notable are the settings for the Admin functions of ION. ION provides a variety of administration utilities including ionadmin, ionsecadmin, ltpadmin, bsspadmin, bpadmin, ipnadmin, and cfdpadmin. Each of the corresponding modules that is to be used at runtime will need to be configured. The commands that perform these configuration tasks are normally presented to the admin utility in an admin configuration file.
In the Linux environment, two different styles of configuration files are possible. Both styles are accepted by the \"ionstart\" program that installs as part of the official release, an AWK program. The first style requires that all configuration commands for all in-use admins will be stored in one file. This single file is sectioned off internally to separate the commands of each admin. The ionstart program accepts this single configuration file's name as a parameter, parses this file looking for sectioned-off areas for each possible admin function, and then uses the commands within these sections to configure the corresponding modules.
The other style requires that each admin will have its own distinct configuration file. The ionstart program consumes these files as guided by command line switches and parameters identifying each configuration file.
"},{"location":"ION-Deployment-Guide/#runtime-parameters","title":"Runtime Parameters","text":"Some ION configuration parameters are declared only at node initialization time; they cannot later be revised. In particular, the ionadmin \"1\" (the numeral one) initialization command must be executed just once, before any other configuration command is processed. The first parameter to this command is required and is a numeric value that indicates the node number of the DTN node being configured. The second parameter to this command is optional; if present, it must provide the full pathname of a local file of immutable configuration parameter values:
wmKey (integer)\nwmSize (integer)\nwmAddress (integer)\nsdrName (string)\n\nsdrWmSize (integer)\n# bit pattern in integer form, e.g., 3 for 00000011\nconfigFlags 3\nheapWords (integer)\nheapKey (integer)\npathName (string)\nThis path name should NOT be enclosed in any type of quotation marks. The file is a text file with 2 fields per line; lines are processed in sequence. The first field on each line holds one of the parameter identifier text strings as shown above. The second field holds the value that will be placed into the identified parameter. Make sure that the data type specified in the second field matches the type expected.
For documentation on these parameters, see the ionconfig(5) man page.
"},{"location":"ION-Deployment-Guide/#configflags","title":"configFlags","text":"The configFlags entry controls several features of the Simple Data Recorder (SDR).\u00a0 There are several flags of interest:
#define SDR_IN_DRAM\u00a0\u00a0\u00a0\u00a0 1\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 /*\u00a0\u00a0Write to & read from memory.\u00a0 */\n#define SDR_IN_FILE\u00a0\u00a0\u00a0\u00a0 2\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 /*\u00a0\u00a0Write file; read file if nec. */\n#define SDR_REVERSIBLE\u00a0 4\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 /*\u00a0\u00a0Transactions may be reversed.\u00a0*/\nSDR_IN_DRAM is required for normal ION operation and should virtually always be specified.
When SDR_REVERSIBLE is specified, SDR transactions that fail (e.g., due to memory allocation failure) are rolled back, allowing transactions to fail gracefully without corrupting the ION databases.\u00a0 If the flag is not supplied, failed transactions will cause an immediate task failure and, where supported, a core dump.\u00a0 This feature is intended only as an aid to debugging; in operations ION should normally be configured with reversible transactions.\u00a0 When transaction reversibility is enabled, ION creates & manages a log file in the directory named by \"pathName\" which must be writable by ION and which tracks the SDR changes and supports rollback to the last consistent state.\u00a0 The filesystem for this directory should be high-performance; a ramdisk is usually ideal.\u00a0 The maximum size of the logfile is dependent upon the largest transaction in the SDR, and is therefore of a size on the same order of magnitude as the largest bundle. NOTE that if the directory named by \"pathname\" does not exist then transaction reversibility will be disabled automatically; a message to this effect will be written to the ION log file.
When SDR_IN_FILE is specified, ION creates a file in the \"pathName\" directory, which is maintained as a copy of the SDR heap in DRAM; whenever the SDR heap in memory is modified, the changes are also written to the sdr heap file.\u00a0 Thus the heap file is always the same size as the in-memory heap. Again, if the directory named by \"pathname\" does not exist then retention of the ION SDR heap in a file will be disabled automatically; a message to this effect will be written to the ION log file. NOTE that
SDR_IN_FILE may have the adverse effect of slowing down all SDR transactions, which can significantly impact transmission, relay, and reception speed of ION. Users should conduct performance testing to ensure that keeping SDR in file can still achieve the operational performance expected.SDR_IN_FILE option is that in the case of ION shutdown due to power reset where the state of SDR is not corrupted, it is possible to start ION with the SDR file and resume data transfer operations such as LTP transaction. However, if ION shuts down due to an internal error, then it is not recommended to keep the SDR file when restarting ION, as the SDR state is not certain to be without corruption.When ION stores a bundle, it typically holds part of the bundle part in memory (heap) as determined by the maxheap parameter in bprc. The default value is about 650 bytes. The rest of the payload is placed into file reference. Also a bundle, before transmission, kept its header and extensions inside a data structure for quick look up and manipulations; the bundle is serialized into a chunk of octet according to the standard just prior to transmission. Therefore, when a bundle is stored in an ION node, part of its footprint is in the 'heap' and part of it is in the 'working memory.'
Test shows that leaving the maxHeap parameter to its default value, a bundle uses about 1.5KB of space in heap and about 100-150 Byte in working memory. Adding a 200% margin, we recommend that following relationship between heapWords and wmSize:
wmSize = 3 x heapWords x 8 x 0.4 / 10\nwhere 3 is the margin, 8 is the number of octets per word, 0.4 accounts for the fact that inbound and outbound heap space is only 40% of the heap, and 10 accounts for the empirically estimated 10:1 ratio between heap and working memory footprints per bundle.
Many ION runtime configuration parameters can be declared at node initialization and later revised dynamically, either by passing supplementary configuration files to the admin utilities or by exercising the admin utilities in interactive mode.
For documentation on the admin commands, see the man pages. The man page names are in the form of <xxx>rc, where <xxx> gets replaced by the specific module name (bp, dtn2, ion, ionsec, ipn, ltp, bssp, cfdp). The directories in which to find these files are: ./ici/doc/pod5, ./ltp/doc/pod5, ./bssp/doc/pod5, ./bp/doc/pod5, and ./cfdp/doc/pod5.
Normally the instantiation of ION on a given computer establishes a single ION node on that computer, for which hard-coded values of wmKey and sdrName (see ionconfig(5)) are used in common by all executables to assure that all elements of the system operate within the same state space. For some purposes, however, it may be desirable to establish multiple ION nodes on a single workstation. (For example, constructing an entire self-contained DTN network on a single machine may simplify some kinds of regression testing.) ION supports this configuration option as follows:
ION_NODE_LIST_DIR is defined in the environment of every participating ION process. Moreover, the value assigned to this variable must be the same text string in the environments of all participating ION processes. That value must be the name (preferably, fully qualified) of the directory in which the ION multi-node database file \"ion_nodes\" will reside.ION_NODE_LIST_DIR makes it possible to establish up to one ION node per directory rather than just one ION node on the computer. When ionadmin is used to establish a node, the ionInitialize() function will get that node's wmKey and sdrName from the .ionconfig file, use them to allocate working memory and create the SDR data store, and then write a line to the ion_nodes file noting the nodeNbr, wmKey, sdrName, and wdName for the node it just initialized. wdName is the current working directory in which ionadmin was running at the time it called ionInitialize(); it is the directory within which the node resides.sdrWmSize or default. If any later ION instance launched with sdrWmSize exceeding the first ION instance, it will result in crash upon launch. It is further recommended that all ION instances running simultaneously on a single host should set their sdrWmSize the same.Included in the root directory of the ION distribution is a bash script named ionstop. This script executes each of the \"admin\" utilities and instructs each subsystem to exit, by supplying the dummy command file name \".\". Once all of the utilities have exited, the script calls another script named killm (likewise located in the root directory of ion-open-source). The killm script first tries to kill all ION processes by name, then tries to destroy all of the shared-memory resources allocated to ION at the time the node was created.
There are also many \"local\" versions of ionstop script, stored in test subdirectories out of which one or multiple ION instances were launched on the same host. These local versions of ionstop script differ from the ionstop script in the root directory in that it usually contains (a) additional, customized scripts to clean up test artifacts such as ion.log, sdr file, received test files, and temporarily acquisition files for LTP and BP that remained after a test is completed and (b) it generally does not execute kilim, which will kill all ION processes, not just the ones related to the ION instance being terminated.
If you invoke the ionstop script that is part of the ION root directory, it does not clean up test artifacts or other products created during operation and if it detects that there are multiple ION instances running in the same host, it will NOT execute killm. In that case, the user is advised to always check that all processes are terminated properly and that the shared memory is cleared appropriately.
When running ionstop, various administrative programs will process a dummy command file \".\" that signals shutdown. It will first check the value of the environment variable ION_NODE_WDNAME, defined in the current shell, to determine which instance of ION must be taken down. The ION instance that was shutdown does not depend on the current directory the shell is in. Therefore it is possible to use either the ionstop script provided in ION's root directory or a local, customized version to shutdown an individual ION instance.
If you are having trouble shutting an ION node down, see the notes on \"Destroying a Node\" later in this Guide.
It has been pointed out that if you are running ION in a Docker container inside a Kubernetes pod, the system is likely to assign process ID 1 to one of the ION processes at startup; since process 1 cannot be killed, the ionstop script can't complete and your node will not be cleanly destroyed. One solution seems to be to usedumb-init for the docker container.
To make this work, you may have to override your entry point in the manifest file used by the Kubectl \"apply\" command.
"},{"location":"ION-Deployment-Guide/#example-configuration-files","title":"Example Configuration Files","text":""},{"location":"ION-Deployment-Guide/#ion-node-number-cross-reference","title":"ION Node Number Cross-reference","text":"When you define a DTN node, you do so using ionadmin and its Initialize command (using the token '1'). This node is then referenced by its node number throughout the rest of the configuration file.
## begin ionadmin \n1 1 /home/spwdev/cstl/ion-configs/23/badajoz/3node-udp-ltp/badajoz.ionconfig\ns\n\na contact +1 +86400 25 25 50000000\na contact +1 +84600 25 101 50000000\na contact +1 +84600 25 1 50000000\n\na contact +1 +86400 101 25 50000000\na contact +1 +86400 101 101 50000000\na contact +1 +86400 101 1 50000000\n\na contact +1 +86400 1 25 50000000\na contact +1 +86400 1 101 50000000\na contact +1 +86400 1 1 50000000\n\n\na range +1 +86400 25 25 1\na range +1 +86400 25 101 10\na range +1 +86400 25 1 10\n\na range +1 +86400 101 25 10\na range +1 +86400 101 101 1\na range +1 +86400 101 1 10\n\na range +1 +86400 1 25 10\na range +1 +86400 1 101 10\na range +1 +86400 1 1 1\n\nm production 50000000\nm consumption 50000000\n\n## end ionadmin\n##########################################################################\n## begin ltpadmin \n1 32\n\na span 25 1 1 1400 1400 1 'udplso 192.168.1.25:1113 1000000000'\na span 101 1 1 1400 1400 1 'udplso 192.168.1.101:1113 1000000000'\na span 1 1 1 1400 1400 1 'udplso 192.168.1.1:1113 1000000000'\n\ns 'udplsi 192.168.1.1:1113'\n\n## end ltpadmin \n##########################################################################\n## begin bpadmin \n1\n\na scheme ipn 'ipnfw' 'ipnadminep'\n\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n\na protocol ltp 1400 100\na protocol tcp 1400 100\n\na outduct ltp 25 ltpclo\na outduct ltp 101 ltpclo\na outduct ltp 1 ltpclo\n\na induct ltp 1 ltpcli\n\ns\n## end bpadmin\n##########################################################################\n## begin ipnadmin\n\na plan 25 ltp/25\na plan 101 ltp/101\na plan 1 ltp/1\n\n## end ipnadmin \nThe \"ipn\" scheme for URI formation is generally used to form the endpoint IDs of endpoints in an ION deployment. Any transmission using endpoints formed in the \"ipn\" scheme will have endpoints IDs of this form:
ipn:nodenumber.servicenumber
The Add Scheme command on line 51 below specifies that the \"ipn\" endpoint naming scheme is supported; the names of three endpoints formed in this scheme are shown in lines 53 thru 55.
The two remaining parameters on this command are used to define the software functions that will act as data forwarder and administrative data receiver.
"},{"location":"ION-Deployment-Guide/#the-bpadmin-add-scheme-command","title":"The bpadmin Add Scheme command","text":"a scheme scheme_name forwarder_command admin_app_command
The add scheme command. This command declares an endpoint naming scheme for use in endpoint IDs, which are structured as URIs: scheme_name:scheme-specific_part. forwarder_command will be executed when the scheme is started on this node, to initiate operation of a forwarding daemon for this scheme. admin_app_command will also be executed when the scheme is started on this node, to initiate operation of a daemon that opens an administrative endpoint identified within this scheme so that it can receive and process custody signals and bundle status reports.
Starting at line 71, the egress plans are defined. These determine the outducts by which data are sent to nodes that are topologically adjacent to the current node in the DTN-based network.
"},{"location":"ION-Deployment-Guide/#the-ipnadmin-add-plan-command","title":"The ipnadmin Add Plan command","text":"a plan node_nbr default_duct_expression
The add plan command. This command establishes an egress plan for the bundles that must be transmitted to the neighboring node identified by node_nbr. Each duct expression is a string of the form
protocol_name outduct_name
signifying that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
"},{"location":"ION-Deployment-Guide/#ltp-parameters-cross-reference","title":"LTP Parameters Cross-reference","text":"The ltpadmin utility allows the features of the LTP protocol to become available. For details of the LTP protocol, see RFC 5325.
The first command that must be issued to ltpadmin is the Initialize command (see line number 38 below, the command token is the '1' (one)). The sole parameter passed to this command is est_max_export_sessions.
"},{"location":"ION-Deployment-Guide/#the-ltpadmin-initialize-command","title":"The ltpadmin Initialize command","text":"This command uses est_max_export_sessions to configure the hash table 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 this parameter and 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.
- Essentially, the \"max export sessions\" must be >= the total number of export sessions on all the spans. If it is expected that new spans will be added during an ION session, then max export sessions figure should be large enough to cover the maximum # of sessions possible.
- Next to be defined are the Spans. They define the interconnection between two LTP engines. There are many parameters associated with the Spans.
"},{"location":"ION-Deployment-Guide/#the-ltpadmin-add-span-command","title":"The ltpadmin Add Span command","text":"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 the 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. max_segment_size specifies the largest LTP segment that this span will produce.
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 limit, aggregation into this block must cease and the block must be segmented and transmitted. When numerous small bundles are outbound, they are aggregated into a block of at least this size instead of being sent individually.
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. When a small number of small bundles are outbound, they are collected until this time limit is met, whereupon the aggregated quantity is sent as a single, larger block.
max_export_sessions constitutes the size of the local LTP engine's retransmission window for this span. The retransmission windows of the spans impose flow control on LTP transmission, preventing the allocation of all available space in the ION node's data store to LTP transmission sessions.
The max_import_sessions parameter is simply the neighboring engine's own value for the corresponding export session parameter.
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 is 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.
Additional notes:
- A \"session block\" is filled by outbound bundles until its aggregation size threshold is reached, or its aggregation time limit is reached, whereupon it is output as a series of segments (of size bounded by max_segment_size). This series of segments is reliably transferred via a LTP protocol session with the remote node, one session per block. By adjusting the size of the session block, the rate of arrival of response segments from the remote node can be controlled. Assuming a bundle rate sufficient to fill the session block, a large session block size means a lot of LTP segments per session (good for a high-rate return, low-rate forward link situation). A small session block size means the number of segments per session is smaller and the LTP protocol will complete the block transfer more quickly because the number of segment retries is generally smaller.
- A good starting point for a configuration is to set the aggregation size threshold to the number of bytes that will typically be transmitted in one second, so that blocks are typically clocked out about once per second. The maximum number of export sessions then should be at least the total number of seconds in the round-trip time for traffic on this LTP span, to prevent transmission from being blocked due to inability to start another session while waiting for the LTP acknowledgment that can end one of the current sessions.
- The multiplicity of session blocks permits bundles to stream; while one session block is being transmitted, a second can be filled (and itself transmitted) before the first is completed. By increasing the number of blocks, high latency links can be filled to capacity (provided there is adequate bandwidth available in the return direction for the LTP acknowledgments). But it is desirable to reduce the max_export_sessions to a value where \"most\" of the sessions are employed because each session allocates an increment of buffer memory from the SDR whether it is used or not.
- When a session block is transmitted, it is emitted as a series of back-to-back LTP segments that are simply queued for transmission; LTP does not meter segment issuance in any way. The underlying link layer is expected to pop segments from the queue and transmit them at the current rate as indicated in the contact plan. The udplso task does limit the task's rate of segment transmission over UDP/IP to the transmission rate declared in the contact plan, reducing the incidence of UDP congestion loss.
- Note that an LTP session can only be concluded (enabling space occupied by the block to be recycled) when all segments have been successfully received -- or retransmission limits have been reached and the session is canceled. High bit error rates on the link correlate to high rates of data loss when segments are large and/or blocks comprise large numbers of segments; this typically results in larger numbers of NACK/retransmit cycles, retarding session completion. When bit error rates are high, LTP performance can be improved by reducing segment size and/or aggregation size threshold.
"},{"location":"ION-Deployment-Guide/#the-ltpadmin-start-command","title":"The ltpadmin Start command","text":"s 'LSI command'
This command starts link service output tasks for all LTP spans (to remote engines) from the local LTP engine, and it starts the link service input task for the local engine.
The sole command on line number 44 below starts two main operations within LTP. The first of these operations starts all of the link service output tasks, the ones defined for each LTP span (see the LSO_command parameter of the Add Span command). In this example, each task instantiates the same function (named 'udplso'). Each 'udplso' needs a destination for its transmissions and these are defined as hostname or IP Address (192.168.1.1) and port number (nominally 1113, the pre-defined default port number for all LTP traffic).
The second operation started by this command is to instantiate the link service input task. In this instance, the task is named \"udplsi\". It is through this task that all LTP input traffic will be received. Similar to the output tasks, the input task also needs definition of the interface on which LTP traffic will arrive, namely hostname or IP address (192.168.1.1) and port number (1113). If it is necessary for udplsi to listen on multiple network interfaces simultaneously, \\'udplsi 0.0.0.0[:port]\\' can be invoked. This instructs udplsi to listen to the UDP broadcast address, which aggregates traffic from all available network interfaces, including localhost.
Once the LTP engine has been defined, initialized and started, we need a definition as to how data gets routed to the Convergence Layer Adaptors. Defining a protocol via bpadmin is the first step in that process.
"},{"location":"ION-Deployment-Guide/#the-bpadmin-add-protocol-command","title":"The bpadmin Add Protocol command","text":"a protocol protocol_name payload_bytes_per_frame overhead_bytes_per_frame
The \"add protocol\" command. This command establishes access to the named convergence layer protocol at the local node. As noted earlier, the payload_bytes_per_frame and overhead_bytes_per_frame arguments were previously used in calculating the estimated transmission capacity consumption of each bundle, to aid in route computation and congestion forecasting; in later versions of ION they are not needed and may be omitted.
Once the protocol has been defined, it can be used to define ducts, both inducts and outducts, as seen in lines 76 thru 80 below. The Add \"duct\" commands associate a protocol (in this case, LTP) with individual node numbers (in this case, 25, 101 and 1) and a task designed to handle the appropriate Convergence Layer output operations. A similar scenario applies for the induct where the LTP protocol and node number 13 get connected with \"ltpcli\" as the input Convergence Layer function.
"},{"location":"ION-Deployment-Guide/#the-bpadmin-add-outduct-and-add-induct-commands","title":"The bpadmin Add Outduct and Add Induct commands","text":"a outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The \"add outduct\" command. This command establishes a duct for transmission of bundles via the indicated CL protocol. The duct's data transmission structure is serviced by the outduct task whose operation is initiated by CLO_command at the time the duct is started. max_payload_length, if specified, causes ION to fragment bundles issued via this outduct (as necessary) to ensure that all such bundles have payloads that are no larger than max_payload_length.
a induct protocol_name duct_name 'CLI_command'
The \"add induct\" command. This command establishes a duct for reception of bundles via the indicated CL protocol. The duct's data acquisition structure is used and populated by the induct task whose operation is initiated by CLI_command at the time the duct is started.
Note that only a single induct is needed for all bundle reception via any single protocol at any single node, and in fact ION may operate poorly if multiple inducts are established for any single protocol. For any induct whose duct name includes an IP address, use IP address 0.0.0.0 (INADDR_ANY) if the machine on which the node resides is multihomed and you want the node to be reachable via all of the machine's network interfaces.
Once all of this has been defined, the last piece needed is the egress plan -- namely how do packets get transmitted to DTN nodes that are the local node's \"neighbors\" in the topology of the network.
As you can see from line numbers 6 thru 29, the only network neighbor to node 1 is node 101. Node 25 has not been defined (because the commands in lines 8, 14, 21 and 27 have been commented). In line numbers 15 and 16, we see that the only destinations for data beginning at node 1 are nodes 101 and 1 (a loopback as such). Therefore, in order to get data from node 1 to node 25, our only choice is to send data to node 101. Out best hope of reaching node 25 is that the configurations for node 101 define a connection to node 25 (either a one-hop direct connection, or more multi-hop assumptions). This is where egress plans come into play.
On line numbers 87 thru 89, this configuration defines the only choices that can be made regarding destinations. For a destination of node 25, which is not a neighbor, all node 1 can do is pass the data to its only neighbor, namely node 101; the \"exit\" command enables this operation. For destinations of nodes 101 and 1, the scenario is pretty simple.
"},{"location":"ION-Deployment-Guide/#the-ipnadmin-add-exit-command","title":"The ipnadmin Add Exit command","text":"a exit first_node_nbr last_node_nbr gateway_endpoint_ID
The \"add exit\" command. This command establishes an \"exit\" for static routing. An exit is an association of some defined routing behavior with some range of node numbers identifying a set of nodes. Whenever a bundle is to be forwarded to a node whose number is in the exit's node number range and it has not been possible to compute a dynamic route to that node from the contact schedules that have been provided to the local node and that node is not a neighbor to which the bundle can be directly transmitted, BP will forward the bundle to the gateway node associated with this exit.
"},{"location":"ION-Deployment-Guide/#the-ipnadmin-add-plan-command_1","title":"The ipnadmin Add Plan command","text":"a plan node_nbr duct_expression [nominal_data_rate]
The \"add plan\" command. This command establishes an egress plan for the bundles that must be transmitted to the neighboring node identified by node_nbr.
Each duct expression is a string of the form
protocol_name outduct_name
signifying that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
The duct expression used in these examples has \"ltp\" being the protocol name and 101 and 1 being the outduct names.
"},{"location":"ION-Deployment-Guide/#ipnadmins-plan-commands-have-been-superseded-by-bpadmin","title":"ipnadmin's \"plan\" commands have been superseded by bpadmin","text":"As of ION 4.1.0, bprc's \"plan\" and \"planduct\" commands supersede and generalize the egress plan commands documented in the ipnrc(5) and dtn2rc(5) man pages, which are [retained for backward compatibility]. The syntax of the egress plan commands consumed by bpadmin is DIFFERENT from that of the commands consumed by ipnadmin and dtn2admin. Please see the man page for bprc (5) for details.
"},{"location":"ION-Deployment-Guide/#bundle-in-bundle-encapsulation","title":"Bundle-in-Bundle Encapsulation","text":"For some purposes it may be helpful to encapsulate a bundle inside another bundle -- that is, to let the serialized representation of a bundle be part of the payload of another bundle. This mechanism is called \"Bundle-in-Bundle Encapsulation\" (BIBE) and is defined in Internet Draft draft-burleigh-dtn-bibect-00.txt (which will likely be renamed at some point and ideally will become an IETF standards-track Request For Comments in due course).
"},{"location":"ION-Deployment-Guide/#introduction-to-bibe","title":"Introduction to BIBE","text":"By way of overview, here is an excerpt from that document:
Each BP node that conforms to the BIBE specification provides a BIBE convergence-layer adapter (CLA) that is implemented within the administrative element of the BP node's application agent. Like any convergence-layer adapter, the BIBE CLA provides:
The BIBE CLA performs these services by:
Bundle-in-bundle encapsulation may have broad utility, but the principal motivating use case is the deployment of \"cross domain solutions\" in secure communications. Under some circumstances a bundle may arrive at a node that is on the frontier of a region of network topology in which augmented security is required, from which the bundle must egress at some other designated node. In that case, the bundle may be encapsulated within a bundle to which the requisite additional BP Security (BPSEC) extension block(s) can be attached, whose source is the point of entry into the insecure region (the \"security source\") and whose destination is the point of egress from the insecure region (the \"security destination\").
Note that:
The protocol includes a mechanism for recovery from loss of an encapsulating bundle, called \"custody transfer\". This mechanism is adapted from the custody transfer procedures described in the experimental Bundle Protocol specification developed by the Delay-Tolerant Networking Research group of the Internet Research Task Force and documented in RFC 5050. Custody transfer is a convention by which the loss or corruption of BIBE encapsulating bundles can be mitigated by the exchange of other bundles, which are termed \"custody signals\".
BIBE is implemented in ION, but configuring ION nodes to employ BIBE is not as simple as one might think. That is because BIBE functions as both a BP application and a convergence-layer adapter; coercing the Bundle Protocol to function in both capacities, offering services to itself at two different layers of the protocol stack, requires careful configuration.
"},{"location":"ION-Deployment-Guide/#configuring-bibe-in-ion","title":"Configuring BIBE in ION","text":"Like any convergence-layer protocol, BIBE is used to copy a bundle from one BP node (the sending node) to another node (the receiving node), over one segment of the end-to-end path from the bundle's source node to its destination node. Somewhat confusingly, in BIBE the copying of the bundle is accomplished by issuing a second encapsulating bundle, which has its own source node and destination node:
Each pair of sending and receiving nodes can be thought of as a \"tunnel\" which requires specific configuration. These tunnels constitute the communication relationships that must be implemented as \"outducts\" in ION.
"},{"location":"ION-Deployment-Guide/#bclas","title":"BCLAs","text":"While the node IDs of the source and destination nodes of encapsulating bundles are necessary parameters for BIBE transmission, they are not sufficient: encapsulating bundles are characterized by quality of service, lifetime, etc., just like other bundles. For this purpose we use an additional BIBE administration utility program -- bibeadmin -- that consumes a file of .bprc commands; these commands add, revise, and delete BIBE convergence layer adapter objects (bclas) that are managed in a BIBE database. For example:
a bcla ipn:3.0 20 20 300 2 128
This command adds a bcla identified by \"ipn:3.0\" -- the ID of the destination node of all encapsulating bundles formed according to this bcla -- which asserts that the expected latency for each encapsulating bundle to reach this destination node is 20 seconds, the expected latency for a responding custody signal bundle is likewise 20 seconds, the encapsulating bundle's time-to-live is 300 seconds, its class of service is 2 (expedited), and its ordinal sub-priority is 128.
Note that other configuration elements may also be implicitly associated with this bcla. For example, BPSEC security rules may map this BIBE source/destination node pair to security block configurations that will pertain to all encapsulating bundles formed according to this bcla.
"},{"location":"ION-Deployment-Guide/#ducts","title":"Ducts","text":"Since BIBE is a convergence-layer protocol, each BIBE tunnel must be configured by means of BP administration (bpadmin) using .bprc commands; BIBE must be added as a protocol, the local node must be added as the BIBE induct, and each supported BIBE tunnel must be added as a BIBE outduct. For example:
a protocol bibe\na induct bibe \\* ''\na outduct bibe ipn:4.0 'bibeclo ipn:3.0'\nThe \"a outduct\" command states that the BIBE outduct (tunnel) identified by node ID \"ipn:4.0\" (the receiving node) is serviced by a BIBE convergence-layer output daemon operating according to the bcla identified by \"ipn:3.0\" as described above. The destination node ipn:3.0 is responsible for forwarding each extracted (encapsulated) bundle to the receiving node ipn:4.0. The sending node and the source node of the encapsulating bundles are both, implicitly, the local node.
Note that for most convergence-layer adapters the node ID of the receiving node for a given outduct is implicit; for example, an stcp outduct explicitly identifies only the socket address of the receiving node's socket -- that is, the convergence-layer protocol endpoint ID -- not the node ID of the receiving node. BIBE differs only in that the convergence-layer protocol endpoint ID is, explicitly, the node ID of the receiving node, simply because BP is being used as the convergence-layer protocol.
"},{"location":"ION-Deployment-Guide/#plans","title":"Plans","text":"In order to cause bundles to be conveyed to a specified receiving node via a BIBE outduct, that outduct must be associated with that node in an egress plan. For example, in the .ipnrc file:
a plan ipn:4.0 bibe/ipn:4.0\na plan ipn:3.0 stcp/91.7.31.134:4546\nThe first command asserts that all bundles destined for node \"ipn:4.0\" are to be forwarded using BIBE outduct \"ipn:4.0\". The second asserts that all bundles destined for node \"ipn:3.0\" (here, all BIBE encapsulating bundles formed according to the bcla identified by \"ipn:3.0\") are to be forwarded using the stcp outduct connected to TCP socket \"91.7.31.134:4546\".
"},{"location":"ION-Deployment-Guide/#contacts","title":"Contacts","text":"Finally, in order for data to flow to receiving node ipn:4.0 via the bibe/ipn:4.0 outduct, a contact object must be added to the contact plan enabling the transmissions:
a contact +0 +1000000000 2 4 100000
This command states that data flow from node 2 (here, the local node) to node 4 (the receiving node) is continuously enabled, but the rate of transmission is limited to 100,000 bytes per second.
"},{"location":"ION-Deployment-Guide/#overrides","title":"Overrides","text":"Under some circumstances, successful forwarding of BIBE bundles requires that outduct overrides be applied. See the biberc(5) man page for details.
"},{"location":"ION-Deployment-Guide/#adaptations","title":"Adaptations","text":""},{"location":"ION-Deployment-Guide/#error-logging","title":"Error Logging","text":"ION contains a flexible system that allows its code to display errors in several different ways. At the core of this system is a typedef that defines a data type named \"Logger\" (with upper case \"L\") that is a function variable that accepts a character pointer (string) parameter and returns a value of type void.
typedef void (* Logger)(char *);
In ION, there is one variable defined to be of this type. Its identifier is \"logger\" (with lower case \"L\") and it is initialized to a value of \"logToStdout\". The function \"logToStdout\" is defined and its contents cause the string parameter to be printed to the stdout device. Therefore, any call to the function variable \"logger\" will have same effects as a call to the function \"logToStdout\".
However, remember that \"logger\" is a variable and is allowed to change its value to that of other functions that accept string parameters and return void. This is how ION allows for flexibility in logging errors.
At startup, ION makes a call to \"ionRedirectMemos\". This function makes a call to \"setLogger\" which eventually changes the value of the \"logger\" variable. The new value of the variable named \"logger\" is \"writeMemoToIonLog\". This function writes strings to a file named \"ion.log\".
It is through this mechanism that any calls to the functions \"writeMemo\", \"writeMemoNote\" or \"writeErrMemo\" eventually pass their parameters to the function \"writeMemoToIonLog\". This is how the Linux-based ION's operate.
Check out the FSWLOGGER macro option as documented in section 2.1.1 of the Design Guide.
"},{"location":"ION-Deployment-Guide/#memory-allocation","title":"Memory Allocation","text":"What types of memory does ION use and how is memory allocated/controlled?
For an introductory description of the memory resources used by ION, see Section 1.5 of the ION Design and Operation guide entitled \"Resource Management in ION\".
Section 1.5 of the Design and Operation guide makes reference to parameters called \"wmSize\" and \"heapWords\". Discussion on these and all of the parameters can be found in this document under the section entitled \"Runtime Parameters\".
ION allocates its large blocks of memory via calls to malloc. Should the need ever arise to place these large blocks of memory at known, fixed addresses, it would be possible to modify the function memalign, in the file platform.c. A better approach would be to create a shared-memory segment for each pre-allocated memory block (possibly using ION's sm_ShmAttach() function to do this) and pass the applicable shared-memory key values to ION at startup, in the \"heapKey\" and/or \"wmKey\" runtime parameters.
Any code that references the function \"sm_ShmAttach\" will be looking to acquire some block of memory. These would include the Space Management Trace features and standalone programs such as \"file2sm\", \"sm2file\" and \"smlistsh\".
"},{"location":"ION-Deployment-Guide/#testing-known-issues","title":"Testing & Known Issues","text":""},{"location":"ION-Deployment-Guide/#factors-affecting-ltp-testing-over-udp","title":"Factors Affecting LTP Testing Over UDP","text":"Terrestrial testing of LTP during the prototype and initial system integration phases often relies on using the UDP protocol because it is readily available on most terrestrial computing systems. ION's udplso and udplsi programs provide the basic capability to flow LTP traffic between two hosts on the internet. To increase the fidelity of LTP testing, short of directly utilizing actual radio systems, customized software or hardware can be added to the data path. This addition aims to introduce longer delays and data corruption/loss in a controlled manner.
However, testing LTP over UDP can yield unpredictable results due to several factors. Understanding these factors is essential for accurate analysis and troubleshooting:
"},{"location":"ION-Deployment-Guide/#udps-inherent-unreliability","title":"UDP's Inherent Unreliability","text":"UDP lacks a built-in mechanism for retransmitting lost packets. Consequently, the rate at which packets are lost can fluctuate significantly. This inherent unreliability of UDP may affect the performance and reliability tests of LTP, as LTP relies on UDP for transport.
"},{"location":"ION-Deployment-Guide/#kernel-buffering-and-ip-fragment-reassembly","title":"Kernel Buffering and IP Fragment Reassembly","text":"The ability of the operating system kernel to buffer and reassemble IP fragments plays a critical role, especially if an LTP segment exceeds the Maximum Transmission Unit (MTU) size. The efficiency of this process can vary based on:
External testing tools, either customized software or WAN emulators, are often used to simulate network conditions or impairments but may also impact the fidelity of testing by exaggerating the delay differences between different traffic streams, including UDP fragments, when improperly configured, and further complicate the interpretation of LTP performance results over UDP.
"},{"location":"ION-Deployment-Guide/#operation_1","title":"Operation","text":"ION is generally optimized for continuous operational use rather than research. In practice, this means that a lot more attention, both in the code and in the documentation, has been paid to the care and feeding of an existing ION-based network than to the problem of setting up a new network in the first place. (The unspoken expectation is that you're only going to do it once anyway.)
Unfortunately this can make ION somewhat painful for new users to work with. The notes in this section are aimed at reducing this pain, at least a little.
"},{"location":"ION-Deployment-Guide/#wrong-profile-for-this-sdr","title":"\"Wrong profile for this SDR\"","text":"ION is based on shared access to a common data store in memory (and/or in a file), and the objects in that data store are intended to persist across multiple restarts of network activity in a continuously operational network. That's okay for Space Station operations, but it's not helpful while you're still struggling to get the network running in the first place. For this purpose you are probably creating and destroying one or more nodes repetitively.
A key concept:
Each time you run the standard ionstart script provided with ION, you are creating a new network from scratch. To minimize confusion, be sure to clear out the old data store first.
If you don't wipe out the old system before trying to start the new one, then either you will pick up where you left off in testing the old system (and any endpoints, ducts, etc. you try to add will be rejected as duplicates) or -- in the event that you have changed something fundamental in the configuration, or are using an entirely different configuration file -- you'll see the \"Wrong profile for this SDR\" message and won't be able to continue at all.
"},{"location":"ION-Deployment-Guide/#destroying-a-node","title":"Destroying a node","text":"In most cases the ionstop script should terminate the node for you. Invoke it once for every node of your network. To verify that you're starting from a clean slate, run the ipcs command after ionstop: the list of Semaphore Arrays should be empty. If it's not, you've got one or more leftover processes from the previous network still running; use ps ax to find them and kill -9 to get rid of them. The process names to look for are:
Then run the killm script again to make sure the node's shared-memory resources have been released; run ipcs again to verify, and review your leftover processes again if those resources still haven't been released.
An additional wrinkle: if you configure ION to manage your ION data store in a file as well as (or instead of) managing it in shared memory, then in addition to calling killm to destroy the semaphores and the copy of the data store that resides in shared memory, you also need to delete the data store file; this destroys the copy of the data store that resides in the file system. If the data store isn't deleted, then when you restart ION using your standard configuration file the file-system copy of the data store will automatically be reloaded into shared memory and all the config file commands that create new schemes, endpoints, etc. will fail, because they're still in the data store that you were using before.
Another habit that can be helpful: whenever you restart ION from scratch, delete all the ion.log files in all of the directories in which you're configuring your ION nodes. This isn't mandatory -- ION will happily append new log messages to existing log files, and the messages are time-tagged anyway, so it's always possible to work out what happened when. But starting fresh with new log files removes a lot of clutter so that it's easy to see exactly what's happening in this particular iteration of your network research. ION will create new log files automatically if they don't exist; if there's something particularly interesting in the log from a prior system, copy that log file with a different name so you can come back to it if you need to.
"},{"location":"ION-Deployment-Guide/#no-such-directory-disabling-heap-residence-in-file","title":"\"No such directory; disabling heap residence in file...\"","text":"This message just means that the directory whose name you've provided as the value of pathName in the ION configuration file does not exist, and therefore the ION operations that rely on being able to write files in that directory are disabled. It's strictly informative; nearly everything in ION will work just fine even if this message is printed every time you run.
But if you do care about transaction reversibility, for example, or if you just want to get rid of the annoying message, simply create the directory that is named in pathName (it can be any path name you like) and make sure it's world-writable. The ionconfig(5) man page discusses this parameter and others that affect the fundamental character of the system you're configuring.
"},{"location":"ION-Deployment-Guide/#cant-find-ion-security-database","title":"\"Can't find ION security database\"","text":"These messages are just warnings, but they are annoying. We're still struggling to work out a way to support bundle security protocol as fully and readily as possible but still let people run ION without it, if they want, without too much hassle.
For now, the best answer might be to insert the following lines into each host.rc file immediately after the \"##end ionadmin\" line. They should create an empty ION security database on each host, which should shut down all those warnings:
## begin ionsecadmin\n1\n## end ionsecadmin\nSeveral key elements of ION (notably LTP transmission and bundle expiration) rely on the clocks of all nodes in the network being synchronized to within a few seconds. NTP is a good way to accomplish this, if you've got access to an NTP server. If you can't get your clocks synchronized, stick to the TCP or UDP convergence-layer adapters, don't count on using contact graph routing, and use long lifetimes on all bundles to prevent premature bundle expiration.
"},{"location":"ION-Deployment-Guide/#node-numbers","title":"Node numbers","text":"In ION we always use the same numeric value for LTP (and BSSP) engine number and BP node number -- and for CFDP entity number and AMS continuum number as well. The idea is that a given ION node has a single identifying number, which by convention we use wherever a protocol endpoint identifier is needed for any local protocol agent. This is not a DTN or CCSDS requirement, but it doesn't violate any of the protocol specifications and it does marginally simplify both implementation and configuration.
"},{"location":"ION-Deployment-Guide/#duct-names","title":"Duct names","text":"The bprc(5) man page explains the general format of the commands for adding convergence-layer inducts and outducts, but it doesn't provide the syntax for duct names, since duct name syntax is different for different CL protocols. Here's a summary of duct name syntax for the CL protocols supported as of ION 3.6.1:
Here are some other points to bear in mind as you debug your ION node configuration:
In this section, we present LTP throughput measurements collected on different computing platforms. The goal of these tests is to provide a set of data points that give ION users a sense of the achievable LTP throughput for a given level of computing resources, ranging from single-board computers (SBC) to medium-level or high-end servers connected via 10Gbps Ethernet. We made no attempt to match any particular user's computing environment in this test. Users must exercise their own good engineering sense when generalizing and applying these data points to make predictions regarding the performance of their own systems. The users are encouraged to install ION on the target platform and configure ION - using some of the configuration recommendations in this report - when conducting their own tests.
Since our focus is to explore the speed limitation caused by software processing within ION, we try to eliminate external factors that can slow down throughput, such as a poor network connection or other processing-intensive software running concurrently on the host machine that compete for CPU cycles, etc. We also eliminated the impact of round-trip delay and packet error by testing LTP over a high-speed, low-error, direct Ethernet connection between two LTP peers.
"},{"location":"ION-Deployment-Guide/#considerations-for-configuration","title":"Considerations for Configuration","text":"Given that LTP is designed for space links, not terrestrial links, LTP segment sizes much larger than typical terrestrial network MTUs (nominally 1,500 to 9,000 bytes) are considered in our testing. For LTP configuration in space, the CCSDS Packet Encapsulation service enables LTP segments of variable sizes to be transmitted over different CCSDS space link protocols.
Most of our testing was conducted with the SDR in DRAM (configuration 1) to achieve higher data processing speed. However, we did collect data on several cases where reversibility and SDR object boundness checks were turned on.
In the interest of efficiency, we also favor selecting larger bundles, potentially much larger than the LTP aggregation block size. In previous TCPCL testing, it was observed that a larger bundle size improves throughput since more data can be transferred per logical operation. For the same reason, we believe that a larger bundle size will improve LTP performance.
ION performs bundle-level metering to throttle the speed with which data is presented to LTP engines for transmission. The throttle rate is set by the contact plan and should not exceed the line rate of the physical Ethernet connection. In many cases, we configure ION with a contact plan rate that is lower than the Ethernet line rate to allow BP/LTP to operate as fast as possible without creating a destructive level of congestion. To facilitate better testing, we also use the bpdriver utility program with the \\'i\\' option to control the source data injection rate. For some tests, we find data metering unnecessary, and ION can buffer and handle local congestion and deliver the maximum possible throughput.
NOTE: The results presented here are based on System V semaphore. Recent upgrade and testing of a POSIX semaphore approach indicated a substantial performance increase to ION, and that result will be published in the next release of this document.
As stated earlier, our goal is to test the ION processing rate limitation, not the host system\\'s memory availability. Therefore, we configure ION SDR with a generous amount of heap and working memory to ensure that data storage is not a limiting factor.
Now, we present our test cases.
"},{"location":"ION-Deployment-Guide/#test-case-1-mid-grade-linux-server-with-direct-ethernet-connection","title":"Test Case 1: Mid-grade Linux Server with Direct Ethernet Connection","text":"B = byte
b = bit
M = mega
K = kilo
G = giga
ION Configuration:
Hardware Specification and Operating System:
Throughput Measured:
ION Configuration:
Hardware Specification and Operating System:
Throughput Measured:
In this test case, we considered several SDR configuration combinations and assessed their impact.
We do not include the \"SDR in file\" or any combination with that since file operation will slow down performance significantly.
Base ION Memory Configuration
BP/LTP Configuration
The following is representational of .ltprc file on both nodes
1 50
Contact Plan Data Rate (1 Gb/sec)
Hardware Specification and Operating System:
Network link reported by iperf as follows (PTL Orange Testbed)
UDP: 1.35 GB/sec
Throughput Measured
General observation is that SDR boundedness checks (each write operation must ensure that the location where data is written is occupied by an object of the same size of the write operation) introduce about 11% of throughput degradation. Adding reversibility will substantially slow down the system since the reversibility, by default, saves transaction operations record in a file until the transaction is complete or until when the transaction is canceled and must be reversed. Although it is possible to store transaction record in ION's working memory, we didn't consider this case in our testing due to time constraint.
"},{"location":"ION-Deployment-Guide/#test-case-4-10gbps-physical-ethernet-study-with-2012-xeon-sandy-bridge","title":"Test Case 4: 10Gbps Physical Ethernet Study (with 2012 Xeon Sandy Bridge)","text":"In this 10Gbps case study, we measured LTP performance between two machines physically connected by a 10Gbps Ethernet switch. Initial testing with iperf showed that although the physical connection was 10Gbps, the actual throughput maxed out at 2.5Gbps. Improved throughput was attained by increasing the kernel buffer sizes to 8MB. Additionally, increasing the MTU (Maximum Transmission Unit) size from 1500 to 9600 resolved some caching issues seen at the receiving node.
UDP Configuration Details
The following kernel buffer size settings were used to enable full utilization of the 10Gbps Ethernet on the host machine. These are provided for your reference. Depending on your host system's configuration, you may not need to adjust any parameters to make sure the full capacity of the Ethernet connection is achievable. Even in cases where you do find it necessary to make such adjustments, the actual parameters values may not be the same.
To resolve the caching issue, which allows the LTP engine to clean up after the test quickly, we set the MTU to 9600. This is not strictly required but we find it helpful when the MTU is set to 9600 Bytes instead of the typical value of 1500 Bytes (we observed improved LTP session cleanup times with the higher MTU). After applying these updates, iperf testing showed 9.9Gbps throughput on the Ethernet connection between the two hosts.
Test Network Details
The test network consists of 2 host machines physically connected via 10 Gb Network Interface Card
Hardware
ION Memory Configuration Details
LTP Configuration Details
Throughput Measurement
The first series of tests provided some insights into the impact of bundle size on throughput. In general, using a larger bundle size allows ION to transfer more data per logical operation since the overhead of a bundle is relatively fixed regardless of the size of the payload. In our tests, we controlled the size of all bundles injected into ION for LTP transfer. In real operations, bundle size will vary, but for bulk data transfer, the user is generally able to dictate the size of the bundle it sends. To avoid processing smaller bundles individually (which occurs in real operations), we turned on LTP block aggregation and set the size to 64KB.
Figure 1: LTP Throughput as a Function of Bundle Size
In Figure 1, we can immediately observe that bundle size has a significant impact on LTP throughput. This is because the bundle is the basic unit of an LTP block. When LTP block aggregation is turned on, a block may consist of one or multiple bundles. When LTP block aggregation is not applied, each block is one bundle. When the bundle size is less than the aggregation size, LTP will accumulate several bundles before creating a block. While this will limit LTP overhead, the use of small bundles still has an impact on the bundle protocol level processing, both before LTP transmission and during post-LTP-reception reconstruction. Therefore, as we can see, when the bundle size is dropped below the LTP aggregation threshold, the throughput is still impacted by bundle size.
While it may seem that the aggregation size limit does not have a strong impact on throughput, it does for long delay-bandwidth space links, where it dictates the maximum number of import/export sessions that ION must support simultaneously. That will be another investigation for a future study. For now, we focus solely on testing the limit of ION\\'s data processing speed in a low latency lab environment.
We also conducted a second series of tests to look at the impact of LTP segment sizes on throughput. The results are in Figure 2 below.
Figure 2: Impact of LTP Segment Size on Throughput
In this test, we looked at bundle sizes that are 1MB or lower, with segment sizes ranging from 64KB to 1,500 bytes. Again, we observed that segment size has a stronger impact on throughput when it is less than 10% of the bundle size; once it goes above 10%, the impact is noticeably diminished. This has to do with the fact that each segment levies a minimal amount of logical operation. Using a large segment size can help reduce LTP processing overhead. However, since the segment is LTP\\'s standard protocol data unit and it determines the vulnerability/likelihood of data loss (large segments expose more data to loss due to corruption), it is not advised to arbitrarily increase the segment size in a real flight environment with a substantial data loss probability. The key point here is to illustrate that the choice of segment size can impact the processing overhead and speed of LTP.
"},{"location":"ION-Deployment-Guide/#impact-of-variable-bundles-size","title":"Impact of variable bundles size","text":"In real life operation, we expect the users to generate a wide mixture of large and small bundles. Although we don't have a commonly agreed on \"profile\" of how a typical DTN user will generate bundles, it is nonetheless valuable for us to get a sense of how BP/LTP in ION would perform when handling bundles of random sizes.
For a quick study, we leveraged the same 2.1GHz Xeon Sandy Bridge processor configuration with 1MB LTP aggregation limit and injected bundles whose payload size is a uniformly distributed random value between 1024 bytes and 62464 bytes. We found that the throughput is approximately 260Mbps for segment size of 9600 B, and 300Mbps when segment size is increased to 64,000B. For the second test, we increased the bundle size ranges to be between 1KB and 1MB, the measured throughput is 2.08Gbps.
This performance is higher than we expected. For the same amount of data delivery, using 1MB bundle vs an average of 31KB per bundle (uniform between 1K and 62K) would increase bundle process overhead by a factor of 32. Holding all other parameters constant, the 300Mbps throughput is only a factor of 9.6 lower compared to the 1MB bundle case with throughput of 2.9Gbps. The 32-fold increase of bundle overhead didn't result in a 32-fold reduction of speed. The reason for this better-than-expected result is, we believe, due to the use of LTP block aggregation. Similarly, for the second test, we increased the average bundle overhead by a factor 2, but the data rate reduction is only about 29 percent. By keeping the block aggregation to 1MB, we keep the number of LTP sessions and handshaking overhead low, which mitigated some of the impact of the presence of smaller bundles.
Our initial assessment is that the mixed use of larger and smaller bundles will reduce throughput but not as substantially as one would expect based on a linear interpolation of the bundle processing overhead. The use of LTP block aggregation can maintain a higher efficiency under such circumstances. Additional investigation in this area will be conducted and reported in the near future.
"},{"location":"ION-Deployment-Guide/#summary-of-ltp-throughput-test-results","title":"Summary of LTP Throughput Test Results","text":"We conducted a series of tests, documenting the performance of BP/LTP for a range of hardware and ION configuration options. At the lower end, we tested two stock Raspberry Pi 4B single-board computers running ION 4.1.2 and achieved 60 Mbps one-way data transfer without any hardware or OS optimization. At the higher end of our tests, we measured ION performance between two Linux servers (see spec in Test Case 4; 2012 era Xeon Sandy Bridge Processors) and showed that ION's BP/LTP implementation can support up to 3.7Gbps throughput over a 10Gbps Ethernet physical connection. We also presented a discussion on the performance trades regarding various LTP configuration parameters.
We hope that these data points will provide users with a sense of how to configure ION, BP, and LTP to achieve the highest possible throughput on their own systems. We acknowledge that these tests focus on exploring the performance envelope of ION\\'s data processing speed and do not emulate specific flight configurations, nor do they cover long round-trip delay and high error rate space links. For specific link conditions and computing the recommended LTP settings, please consult the LTP Configuration Tool spreadsheet provided with each ION open-source package.
"},{"location":"ION-Deployment-Guide/#acknowledgment","title":"Acknowledgment","text":"Some of the technology described in this Deployment Guide was developed at the Jet Propulsion Laboratory, California Institute of Technology, under a contract with the National Aeronautics and Space Administration.
Copyright \u00a9 2021 California Institute of Technology
The ION team would like to acknowledge the following individuals for contributed to the earlier versions of this Guide: Jane Marquart, NASA; Greg Menke, Columbus; Larry Shackelford, Microtel LLC; Scott Burleigh (retired), Jet Propulsion Laboratory, California Institute of Technology
"},{"location":"ION-Design-and-API-Overview/","title":"ION Design and API Overview","text":""},{"location":"ION-Design-and-API-Overview/#basic-philosophy","title":"Basic Philosophy","text":"The development of ION began in the early 2000's, focusing on flight systems running Real-time Operating System (RTOS) with minimum resources under strict control. While these constraints might be somewhat relaxed for modern embedded systems, ION's lightweight, modular, and portable traits remain desirable to both flight and ground systems today:
Hard Memory Allocation Limits: ION operates within a host-specified memory allocation, managing dynamic allocation internally via a private memory management system. This approach ensures efficient use of the allocated memory resources.
Modular and Robust Operation: ION's design allows individual modules to start, stop, re-build, or possibly be replaced independently. This modular structure is implemented through separate daemons and libraries, enhancing system resilience. In a process crash, data in the process's queues/buffers can be preserved in the non-volatile SDR, preventing data loss.
Efficient Resource Utilization: ION is optimized for environments with limited memory, storage, and processing resources. It avoids duplicate data copies during multi-stage processing by utilizing Zero-Copy Objects (ZCO) in shared memory space for fast hand-off between modules. This method, while more complex, ensures rapid data handling. Additionally, BP and CLA services operate as background daemons to minimize competition with critical spacecraft functions during nominal, high-stress, and off-nominal events.
Independence from Native IP Socket Support: ION employs software abstraction to decouple socket-based programming from its core functionalities. This allows ION to interface the Bundle Protocol and CLAs with various underlying communication systems, such as CCSDS space links, radio communications systems, or customized processing chains that are not IP-based.
Portability and Minimal Footprint for Static Linking: ION prioritizes portability and minimal resource footprint by building its function libraries. This approach supports static linking through the ION-core package for a specific set of modules. It reduces dependency on external libraries, thereby mitigating the risk of interference from unexercised or non-required code segments that cannot be removed from the libraries. This design also avoids potential compatibility issues between the target system\u2019s build environment and those of externally sourced libraries.
"},{"location":"ION-Design-and-API-Overview/#ion-modules","title":"ION Modules","text":"The BP Service API document shows the default installation location of various libraries and daemons. Interactions with these daemons rely on various APIs made available through the libraries. The following diagram shows ION's modular architecture:
ION provides four application-layer services that utilize the underlying DTN protocols. These services are:
ION provides BP services based on Bundle Protocol v6 and Bundle Protocol v7, BPSec (Bundle Protocol Security), and the Interplanetary Internet (IPN) naming scheme. In addition, it offers several standardized convergence layer adaptors, namely:
ION also provides UDP-based Underlying Communication Protocol (UCP) to support testing of the LTP CLA in terrestrial systems.
ION also supports the AMS (Asynchronous Management Architecture) by implementing both an Asynchronous Management Protocol (AMP) Agent and Manager and the associated Application Data Model (ADM) that describes both common and ION-specific DTN network management state information and commands.
The entire ION software suite operates within a prescribed memory space. It is privately managed by ION's ICI infrastructure library functions for space allocation/deallocation, data I/O, and linked list and zero-copy object (ZCO) management. There are two types of data storage: working memory to facilitate data processing and heap in the SDR designed to store state information and data that should persist through a power cycle when implemented on a non-volatile storage medium. ION's APIs are exposed to the user through a set of C header files associated with each module's library.
"},{"location":"ION-Design-and-API-Overview/#modular-packaging-ion-core","title":"Modular Packaging - ION Core","text":"Due to the highly modular design of ION, it is possible to build a streamlined package that contains only the modules required for a specific system to maximize resource efficiency and reduce V&V costs. ION-Core 4.1.2b package offers the ability to selectively build different sets of CLAs and bundle extensions blocks, targeting either 32-bit or 64-bit operating systems.
"},{"location":"ION-Design-and-API-Overview/#ion-apis","title":"ION APIs","text":"For software development, ION provides several sets of APIs for interacting with services/daemons of the underlying DTN protocols, as shown below:
ION APIs can be roughly categorized as follows:
Version 4.1.3 JPL D-48259
Document Change Log
Ver No. Date Description Note V4.1.3 12/08 /2023 converted to MarkDown V4.0.1 11/20/2020 ION 4.0.1 V3.6.2 11/19/2018 ION 3.6.2 release features Skipped V3.6.1. V3.6 12/31/2017 ION 3.6 release features Skipped V3.5. V3.4 3/28/2016 ION 3.4 release features V3.3 3/4/2015 ION 3.3 release features V3.2 12/17/2013 ION 3.2 release features V3.1 9/28/2012 ION 3.1 release features V3.0 3/22/2012 Align with ION 3.0 release V1.13 10/13/2011 Updates for Source Forge Release V1.12 6/11/2010 Updates for second open source release (2.2) V1.11 12/11/2009 BRS updates, multi-node config V1.10 10/23/2009 Final additions prior to DINET 2 experiment V1.9 6/29/2009 Add updates for DINET 2, including CFDP, ionsec V1.8 2/6/2009 Update discussion of Contact Graph Routing; document status msg formats V1.7 12/1/2008 Add documentation for OWLT simulator, BP extension V1.6 10/03/2008 Add documentation of sm_SemUnend V1.5 09/20/2008 Revisions requested SQA V1.4 07/31/2008 Add a section on optimizing ION-based network; tuning V1.3 07/08/2008 Revised some details of CGR V1.2 05/24/2008 Revised man pages for bptrace, ltprc, bprc. V1.1 05/18/2008 Some additional diagrams V1.0 04/28/2008 Initial version of ION design and ops manual"},{"location":"ION-Guide/#design","title":"Design","text":"The Interplanetary Overlay Network (ION) software distribution is an implementation of Delay-Tolerant Networking (DTN) architecture as described in Internet RFC 4838. It is designed to enable inexpensive insertion of DTN functionality into embedded systems such as robotic spacecraft. The intent of ION deployment in space flight mission systems is to reduce cost and risk in mission communications by simplifying the construction and operation of automated digital data communication networks spanning space links, planetary surface links, and terrestrial links.
A comprehensive overview of DTN is beyond the scope of this document. Very briefly, though, DTN is a digital communication networking technology that enables data to be conveyed between two communicating entities automatically and reliably even if one or more of the network links in the end-to-end path between those entities is subject to very long signal propagation latency and/or prolonged intervals of unavailability.
The DTN architecture is much like the architecture of the Internet, except that it is one layer higher in the familiar ISO protocol \"stack\". The DTN analog to the Internet Protocol (IP), called \"Bundle Protocol\" (BP), is designed to function as an \"overlay\" network protocol that interconnects \"internets\" -- including both Internet-structured networks and also data paths that utilize only space communication links as defined by the Consultative Committee for Space Data Systems (CCSDS) -- in much the same way that IP interconnects \"subnets\" such as those built on Ethernet, SONET, etc. By implementing the DTN architecture, ION provides communication software configured as a protocol stack that looks like this:
Figure 1 DTN protocol stack
Data traversing a DTN are conveyed in DTN bundles -- which are functionally analogous to IP packets -- between BP endpoints which are functionally analogous to sockets. Multiple BP endpoints may be accessed at a single DTN node -- functionally analogous to a network interface card -- and multiple nodes may reside on the same computer just as a single computer (host or router) in the Internet may have multiple network interface cards.
BP endpoints are identified by Universal Record Identifiers (URIs), which are ASCII text strings of the general form:
scheme_name:scheme_specific_part
For example:
dtn://topquark.caltech.edu/mail
But for space flight communications this general textual representation might impose more transmission overhead than missions can afford. For this reason, ION is optimized for networks of endpoints whose IDs conform more narrowly to the following scheme:
ipn:node_number.service_number
This enables them to be abbreviated to pairs of unsigned binary integers via a technique called Compressed Bundle Header Encoding (CBHE). CBHE-conformant BP endpoint IDs (EIDs) are not only functionally similar to Internet socket addresses but also structurally similar: node numbers are roughly analogous to Internet node numbers (IP addresses), in that they typically identify the flight or ground data system computers on which network software executes, and service numbers are roughly analogous to TCP and UDP port numbers.
More generally, the node numbers in CBHE-conformant BP endpoint IDs are one manifestation of the fundamental ION notion of network node number: in the ION architecture there is a natural one-to-one mapping not only between node numbers and BP endpoint node numbers but also between node numbers and:
Starting with version 3.1 of ION, this endpoint naming rule is experimentally extended to accommodate bundle multicast, i.e., the delivery of copies of a single transmitted bundle to multiple nodes at which interest in that bundle's payload has been expressed. Multicast in ION -- \"Interplanetary Multicast\" (IMC) -- is accomplished by simply issuing a bundle whose destination endpoint ID conforms to the following scheme:
imc:group_number.service_number
A copy of the bundle will automatically be delivered at every node that has registered in the destination endpoint.
(Note: for now, the operational significance of a given group number must be privately negotiated among ION users. If this multicast mechanism proves useful, IANA may at some point establish a registry for IMC group numbers. Also note that a new mechanism for bundle multicast is introduced in ION 4.0.1, along with support for Bundle Protocol version 7. This new mechanism vastly simplifies bundle multicast; chiefly, the imcadmin utility is deprecated.)
"},{"location":"ION-Guide/#structure-and-function","title":"Structure and function","text":"The ION distribution comprises the following software packages:
ams (Asynchronous Message Service), an application-layer service that is not part of the DTN architecture but utilizes underlying DTN protocols. AMS comprises three protocols supporting the distribution of brief messages within a network:
The core AAMS (Application AMS) protocol, which does message distribution on both the publish/subscribe model and the client/server model, as required by the application.
Taken together, the packages included in the ION software distribution constitute a communication capability characterized by the following operational features:
Management of traffic through such a network, taking into consideration:
requirements for data security
A DTN implementation intended to function in an interplanetary network environment -- specifically, aboard interplanetary research spacecraft separated from Earth and from one another by vast distances -- must operate successfully within two general classes of design constraints: link constraints and processor constraints.
All communications among interplanetary spacecraft are, obviously, wireless. Less obviously, those wireless links are generally slow and are usually asymmetric.
The electrical power provided to on-board radios is limited and antennae are relatively small, so signals are weak. This limits the speed at which data can be transmitted intelligibly from an interplanetary spacecraft to Earth, usually to some rate on the order of 256 Kbps to 6 Mbps.
The electrical power provided to transmitters on Earth is certainly much greater, but the sensitivity of receivers on spacecraft is again constrained by limited power and antenna mass allowances. Because historically the volume of command traffic that had to be sent to spacecraft was far less than the volume of telemetry the spacecraft were expected to return, spacecraft receivers have historically been engineered for even lower data rates from Earth to the spacecraft, on the order of 1 to 2 Kbps.
As a result, the cost per octet of data transmission or reception is high and the links are heavily subscribed. Economical use of transmission and reception opportunities is therefore important, and transmission is designed to enable useful information to be obtained from brief communication opportunities: units of transmission are typically small, and the immediate delivery of even a small part (carefully delimited) of a large data object may be preferable to deferring delivery of the entire object until all parts have been acquired.
The computing capability aboard a robotic interplanetary spacecraft is typically quite different from that provided by an engineering workstation on Earth. In part this is due, again, to the limited available electrical power and limited mass allowance within which a flight computer must operate. But these factors are exacerbated by the often intense radiation environment of deep space. In order to minimize errors in computation and storage, flight processors must be radiation-hardened and both dynamic memory and non-volatile storage (typically flash memory) must be radiation-tolerant. The additional engineering required for these adaptations takes time and is not inexpensive, and the market for radiation-hardened spacecraft computers is relatively small; for these reasons, the latest advances in processing technology are typically not available for use on interplanetary spacecraft, so flight computers are invariably slower than their Earth-bound counterparts. As a result, the cost per processing cycle is high and processors are heavily subscribed; economical use of processing resources is very important.
The nature of interplanetary spacecraft operations imposes a further constraint. These spacecraft are wholly robotic and are far beyond the reach of mission technicians; hands-on repairs are out of the question. Therefore the processing performed by the flight computer must be highly reliable, which in turn generally means that it must be highly predictable. Flight software is typically required to meet \"hard\" real-time processing deadlines, for which purpose it must be run within a hard real-time operating system (RTOS).
One other implication of the requirement for high reliability in flight software is that the dynamic allocation of system memory may be prohibited except in certain well-understood states, such as at system start-up. Unrestrained dynamic allocation of system memory introduces a degree of unpredictability into the overall flight system that can threaten the reliability of the computing environment and jeopardize the health of the vehicle.
"},{"location":"ION-Guide/#design-principles","title":"Design Principles","text":"The design of the ION software distribution reflects several core principles that are intended to address these constraints.
Figure 2 ION inter-task communication
Since ION must run on flight processors, it had to be designed to function successfully within an RTOS. Many real-time operating systems improve processing determinism by omitting the support for protected-memory models that is provided by Unix-like operating systems: all tasks have direct access to all regions of system memory. (In effect, all tasks operate in kernel mode rather than in user mode.) ION therefore had to be designed with no expectation of memory protection.
But universally shared access to all memory can be viewed not only as a hazard but also as an opportunity. Placing a data object in shared memory is an extremely efficient means of passing data from one software task to another.
ION is designed to exploit this opportunity as fully as possible. In particular, virtually all inter-task data interchange in ION follows the model shown in Figure 2:
Semaphore operations are typically extremely fast, as is the storage and retrieval of data in memory, so this inter-task data interchange model is suitably efficient for flight software.
Given ION's orientation toward the shared memory model, a further strategy for processing efficiency offers itself: if the data item appended to a linked list is merely a pointer to a large data object, rather than a copy, then we can further reduce processing overhead by eliminating the cost of byte-for-byte copying of large objects.
Moreover, in the event that multiple software elements need to access the same large object at the same time, we can provide each such software element with a pointer to the object rather than its own copy (maintaining a count of references to assure that the object is not destroyed until all elements have relinquished their pointers). This serves to reduce somewhat the amount of memory needed for ION operations.
The efficiency of inter-task communications based on shared memory makes it practical to distribute ION processing among multiple relatively simple pipelined tasks rather than localize it in a single, somewhat more complex daemon. This strategy has a number of advantages:
The clear interfaces between tasks simplify the implementation of flow control measures to prevent uncontrolled resource consumption.
Portability
Designs based on these kinds of principles are foreign to many software developers, who may be far more comfortable in development environments supported by protected memory. It is typically much easier, for example, to develop software in a Linux environment than in VxWorks 5.4. However, the Linux environment is not the only one in which ION software must ultimately run.
Consequently, ION has been designed for easy portability. POSIX\u2122 API functions are widely used, and differences in operating system support that are not concealed within the POSIX abstractions are mostly encapsulated in two small modules of platform-sensitive ION code. The bulk of the ION software runs, without any source code modification whatsoever, equally well in Linux\u2122 (Red Hat\u00ae, Fedora\u2122, and Ubuntu\u2122, so far), FreeBSD\u00ae, Solaris\u00ae 9, Microsoft Windows (the MinGW environment), OS/X\u00ae, VxWorks\u00ae 5.4, and RTEMS\u2122, on both 32-bit and 64-bit processors. Developers may compile and test ION modules in whatever environment they find most convenient.
"},{"location":"ION-Guide/#organizational-overview","title":"Organizational Overview","text":"Two broad overviews of the organization of ION may be helpful at this point. First, here is a summary view of the main functional dependencies among ION software elements:
Figure 3 ION software functional dependencies
That is, BP and LTP invoke functions provided by the sdr, zco, psm, and platform elements of the ici package, in addition to functions provided by the operating system itself; the zco functions themselves also invoke sdr, psm, and platform functions; and so on.
Second, here is a summary view of the main line of data flow in ION's DTN protocol implementations:
Figure 4 Main line of ION data flow
Note that data objects residing in shared memory, many of them in a nominally non-volatile SDR data store, constitute the central organizing principle of the design. Here as in other diagrams showing data flow in this document:
A few notes on this main line data flow:
Finally, note that the data flow shown here represents the sustained operational configuration of a node that has been successfully instantiated on a suitable computer. The sequence of operations performed to reach this configuration is not shown. That startup sequence will necessarily vary depending on the nature of the computing platform and the supporting link services. Broadly, the first step normally is to run the ionadmin utility program to initialize the data management infrastructure required by all elements of ION. Following this initialization, the next steps normally are (a) any necessary initialization of link service protocols, (b) any necessary initialization of convergence-layer protocols (e.g., LTP -- the ltpadmin utility program), and finally (c) initialization of the Bundle Protocol by means of the bpadmin utility program. BP applications should not try to commence operation until BP has been initialized.
"},{"location":"ION-Guide/#resource-management-in-ion","title":"Resource Management in ION","text":"Successful Delay-Tolerant Networking relies on retention of bundle protocol agent state information -- including protocol traffic that is awaiting a transmission opportunity -- for potentially lengthy intervals. The nature of that state information will fluctuate rapidly as the protocol agent passes through different phases of operation, so efficient management of the storage resources allocated to state information is a key consideration in the design of ION.
Two general classes of storage resources are managed by ION: volatile \"working memory\" and non-volatile \"heap\".
ION's \"working memory\" is a fixed-size pool of shared memory (dynamic RAM) that is allocated from system RAM at the time the bundle protocol agent commences operation. Working memory is used by ION tasks to store temporary data of all kinds: linked lists, red-black trees, transient buffers, volatile databases, etc. All intermediate data products and temporary data structures that ought not to be retained in the event of a system power cycle are written to working memory.
Data structures residing in working memory may be shared among ION tasks or may be created and managed privately by individual ION tasks. The dynamic allocation of working memory to ION tasks is accomplished by the Personal Space Management (PSM) service, described later. All of the working memory for any single ION bundle protocol agent is managed as a single PSM \"partition\". The size of the partition is specified in the wmSize parameter of the ionconfig file supplied at the time ION is initialized.
ION's \"heap\" is a fixed-size pool of notionally non-volatile storage that is likewise allocated at the time the bundle protocol agent commences operation. This notionally non-volatile space may occupy a fixed-size pool of shared memory (dynamic RAM, which might or might not be battery-backed), or it may occupy only a single fixed-size file in the file system, or it may occupy both. In the latter case, all heap data are written both to memory and to the file but are read only from memory; this configuration offers the reliable non-volatility of file storage coupled with the high performance of retrieval from dynamic RAM.
We characterize ION's heap storage as \"notionally\" non-volatile because the heap may be configured to reside only in memory (or, for that matter, in a file that resides in the file system of a RAM disk). When the heap resides only in memory, its contents are truly non-volatile only if that memory is battery-backed. Otherwise heap storage is in reality as volatile as working memory: heap contents will be lost upon a system power cycle (which may in fact be the preferred behavior for any given deployment of ION). However, the heap should not be thought of as \\\"memory\\\" even when it in fact resides only in DRAM, just as a disk device should not be thought of as \\\"memory\\\" even when it is in fact a RAM disk.
{width=\"4.738575021872266in\" height=\"3.338542213473316in\"}
Figure 5 ION heap space use
The ION heap is used for storage of data that (in at least some deployments) would have to be retained in the event of a system power cycle to ensure the correct continued operation of the node. For example, all queues of bundles awaiting route computation, transmission, or delivery reside in the node's heap. So do the non-volatile databases for all of the protocols implemented within ION, together with all of the node's persistent configuration parameters.
The dynamic allocation of heap space to ION tasks is accomplished by the Simple Data Recorder (SDR) service, described later. The entire heap for any single ION bundle protocol agent is managed as a single SDR \"data store\".
Space within the ION heap is apportioned as shown in Figure 5. The total number of bytes of storage space in the heap is computed as the product of the size of a \"word\" on the deployment platform (normally the size of a pointer) multiplied by the value of the heapWords parameter of the ionconfig file supplied at the time ION is initialized. Of this total, 20% is normally reserved as margin and another 40% is normally reserved for various infrastructure operations. (Both of these percentages are macros that may be overridden at compile time.) The remainder is available for storage of protocol state data in the form of \"zero-copy objects\", described later. At any given moment, the data encapsulated in a zero-copy object may \"belong\" to any one of the protocols in the ION stack (AMS, CFDP, BP, LTP), depending on processing state; the available heap space is a single common resource to which all of the protocols share concurrent access.
Because the heap is used to store queues of bundles awaiting processing, blocks of LTP data awaiting transmission or reassembly, etc., the heap for any single ION node must be large enough to contain the maximum volume of such data that the node will be required to retain during operations. Demand for heap space is substantially mitigated if most of the application data units passed to ION for transmission are file-resident, as the file contents themselves need not be copied into the heap. In general, however, computing the optimum ION heap size for a given deployment remains a research topic.
"},{"location":"ION-Guide/#package-overviews","title":"Package Overviews","text":""},{"location":"ION-Guide/#interplanetary-communication-infrastructure-ici","title":"Interplanetary Communication Infrastructure (ICI)","text":"The ICI package in ION provides a number of core services that, from ION's point of view, implement what amounts to an extended POSIX-based operating system. ICI services include the following:
1. Platform
The platform system contains operating-system-sensitive code that enables ICI to present a single, consistent programming interface to those common operating system services that multiple ION modules utilize. For example, the platform system implements a standard semaphore abstraction that may invisibly be mapped to underlying POSIX semaphores, SVR4 IPC semaphores, Windows Events, or VxWorks semaphores, depending on which operating system the package is compiled for. The platform system also implements a standard shared-memory abstraction, enabling software running on operating systems both with and without memory protection to participate readily in ION's shared-memory-based computing environment.
2. Personal Space Management (PSM)
Although sound flight software design may prohibit the uncontrolled dynamic management of system memory, private management of assigned, fixed blocks of system memory is standard practice. Often that private management amounts to merely controlling the reuse of fixed-size rows in static tables, but such techniques can be awkward and may not make the most efficient use of available memory. The ICI package provides an alternative, called PSM, which performs high-speed dynamic allocation and recovery of variable-size memory objects within an assigned memory block of fixed size. A given PSM-managed memory block may be either private or shared memory.
3. Memmgr
The static allocation of privately-managed blocks of system memory for different purposes implies the need for multiple memory management regimes, and in some cases a program that interacts with multiple software elements may need to participate in the private shared-memory management regimes of each. ICI's memmgr system enables multiple memory managers -- for multiple privately-managed blocks of system memory -- to coexist within ION and be concurrently available to ION software elements.
4. Lyst
The lyst system is a comprehensive, powerful, and efficient system for managing doubly-linked lists in private memory. It is the model for a number of other list management systems supported by ICI; as noted earlier, linked lists are heavily used in ION inter-task communication.
5. Llcv
The llcv (Linked-List Condition Variables) system is an inter-thread communication abstraction that integrates POSIX thread condition variables (vice semaphores) with doubly-linked lists in private memory.
6. Smlist
Smlist is another doubly-linked list management service. It differs from lyst in that the lists it manages reside in shared (rather than private) DRAM, so operations on them must be semaphore-protected to prevent race conditions.
7. SmRbt
The SmRbt service provides mechanisms for populating and navigating \"red/black trees\" (RBTs) residing in shared DRAM. RBTs offer an alternative to linked lists: like linked lists they can be navigated as queues, but locating a single element of an RBT by its \"key\" value can be much quicker than the equivalent search through an ordered linked list.
8. Simple Data Recorder (SDR)
SDR is a system for managing non-volatile storage, built on exactly the same model as PSM. Put another way, SDR is a small and simple \"persistent object\" system or \"object database\" management system. It enables straightforward management of linked lists (and other data structures of arbitrary complexity) in non-volatile storage, notionally within a single file whose size is pre-defined and fixed.
SDR includes a transaction mechanism that protects database integrity by ensuring that the failure of any database operation will cause all other operations undertaken within the same transaction to be backed out. The intent of the system is to assure retention of coherent protocol engine state even in the event of an unplanned flight computer reboot in the midst of communication activity.
9. Sptrace
The sptrace system is an embedded diagnostic facility that monitors the performance of the PSM and SDR space management systems. It can be used, for example, to detect memory \"leaks\" and other memory management errors.
10. Zco
ION's zco (zero-copy objects) system leverages the SDR system's storage flexibility to enable user application data to be encapsulated in any number of layers of protocol without copying the successively augmented protocol data unit from one layer to the next. It also implements a reference counting system that enables protocol data to be processed safely by multiple software elements concurrently -- e.g., a bundle may be both delivered to a local endpoint and, at the same time, queued for forwarding to another node -- without requiring that distinct copies of the data be provided to each element.
11. Rfx
The ION rfx (R/F Contacts) system manages lists of scheduled communication opportunities in support of a number of LTP and BP functions.
12. Ionsec
The IONSEC (ION security) system manages information that supports the implementation of security mechanisms in the other packages: security policy rules and computation keys.
"},{"location":"ION-Guide/#licklider-transmission-protocol-ltp","title":"Licklider Transmission Protocol (LTP)","text":"The ION implementation of LTP conforms fully to RFC 5326, but it also provides two additional features that enhance functionality without affecting interoperability with other implementations:
In the ION stack, LTP serves effectively the same role that is performed by an LLC protocol (such as IEEE 802.2) in the Internet architecture, providing flow control and retransmission-based reliability between topologically adjacent bundle protocol agents.
All LTP session state is safely retained in the ION heap for rapid recovery from a spacecraft or software fault.
"},{"location":"ION-Guide/#bundle-protocol-bp","title":"Bundle Protocol (BP)","text":"The ION implementation of BP conforms fully to RFC 5050, including support for the following standard capabilities:
The system also provides three additional features that enhance functionality without affecting interoperability with other implementations:
In addition, ION BP includes a system for computing dynamic routes through time-varying network topology assembled from scheduled, bounded communication opportunities. This system, called \"Contact Graph Routing,\" is described later in this Guide.
In short, BP serves effectively the same role that is performed by IP in the Internet architecture, providing route computation, forwarding, congestion avoidance, and control over quality of service.
All bundle transmission state is safely retained in the ION heap for rapid recovery from a spacecraft or software fault.
"},{"location":"ION-Guide/#asynchronous-message-service-ams","title":"Asynchronous Message Service (AMS)","text":"The ION implementation of the CCSDS AMS standard conforms fully to CCSDS 735.0-B-1. AMS is a data system communications architecture under which the modules of mission systems may be designed as if they were to operate in isolation, each one producing and consuming mission information without explicit awareness of which other modules are currently operating. Communication relationships among such modules are self-configuring; this tends to minimize complexity in the development and operations of modular data systems.
A system built on this model is a \"society\" of generally autonomous inter-operating modules that may fluctuate freely over time in response to changing mission objectives, modules' functional upgrades, and recovery from individual module failure. The purpose of AMS, then, is to reduce mission cost and risk by providing standard, reusable infrastructure for the exchange of information among data system modules in a manner that is simple to use, highly automated, flexible, robust, scalable, and efficient.
A detailed discussion of AMS is beyond the scope of this Design Guide. For more information, please see the AMS Programmer's Guide.
"},{"location":"ION-Guide/#datagram-retransmission-dgr","title":"Datagram Retransmission (DGR)","text":"The DGR package in ION is an alternative implementation of LTP that is designed to operate responsibly -- i.e., with built-in congestion control -- in the Internet or other IP-based networks. It is provided as a candidate \"primary transfer service\" in support of AMS operations in an Internet-like (non-delay-tolerant) environment. The DGR design combines LTP's concept of concurrent transmission transactions with congestion control and timeout interval computation algorithms adapted from TCP.
"},{"location":"ION-Guide/#ccsds-file-delivery-protocol-cfdp","title":"CCSDS File Delivery Protocol (CFDP)","text":"The ION implementation of CFDP conforms fully to Service Class 1 (Unreliable Transfer) of CCSDS 727.0-B-4, including support for the following standard capabilities:
All CFDP transaction state is safely retained in the ION heap for rapid recovery from a spacecraft or software fault.
"},{"location":"ION-Guide/#bundle-streaming-service-bss","title":"Bundle Streaming Service (BSS)","text":"The BSS service provided in ION enables a stream of video, audio, or other continuously generated application data units, transmitted over a delay-tolerant network, to be presented to a destination application in two useful modes concurrently:
The TC service provided in ION enables critical but non-confidential information (such as public keys, for asymmetric cryptography) to be provided in a delay-tolerant, trustworthy manner. An instance of TC comprises:
Any number of Clients, which:
Announce new content to the Authority via authenticated bundle multicast, and/or
A small number of network operation design elements -- fragmentation and reassembly, bandwidth management, and delivery assurance (retransmission) -- can potentially be addressed at multiple layers of the protocol stack, possibly in different ways for different reasons. In stack design it's important to allocate this functionality carefully so that the effects at lower layers complement, rather than subvert, the effects imposed at higher layers of the stack. This allocation of functionality is discussed below, together with a discussion of several related key concepts in the ION design.
"},{"location":"ION-Guide/#fragmentation-and-reassembly","title":"Fragmentation and Reassembly","text":"To minimize transmission overhead and accommodate asymmetric links (i.e., limited \"uplink\" data rate from a ground data system to a spacecraft) in an interplanetary network, we ideally want to send \"downlink\" data in the largest possible aggregations -- coarse-grained transmission.
But to minimize head-of-line blocking (i.e., delay in transmission of a newly presented high-priority item) and minimize data delivery latency by using parallel paths (i.e., to provide fine-grained partial data delivery, and to minimize the impact of unexpected link termination), we want to send \"downlink\" data in the smallest possible aggregations -- fine-grained transmission.
We reconcile these impulses by doing both, but at different layers of the ION protocol stack.
First, at the application service layer (AMS and CFDP) we present relatively small application data units (ADUs) -- on the order of 64 KB -- to BP for encapsulation in bundles. This establishes an upper bound on head-of-line blocking when bundles are de-queued for transmission, and it provides perforations in the data stream at which forwarding can readily be switched from one link (route) to another, enabling partial data delivery at relatively fine, application-appropriate granularity.
(Alternatively, large application data units may be presented to BP and the resulting large bundles may be proactively fragmented at the time they are presented to the convergence-layer manager. This capability is meant to accommodate environments in which the convergence-layer manager has better information than the application as to the optimal bundle size, such as when the residual capacity of a contact is known to be less than the size of the bundle.)
Then, at the BP/LTP convergence layer adapter lower in the stack, we aggregate these small bundles into blocks for presentation to LTP:
Any continuous sequence of bundles that are to be shipped to the same LTP engine and all require assured delivery may be aggregated into a single block, to reduce overhead and minimize report traffic.
However, this aggregation is constrained by an aggregation size limit rule: aggregation must stop and the block must be transmitted as soon as the sum of the sizes of all bundles aggregated into the block exceeds the block aggregation threshhold value declared for the applicable span (the relationship between the local node's LTP engine and the receiving LTP engine) during LTP protocol configuration via ltpadmin.
Given a preferred block acknowledgment period -- e.g., a preferred acknowledgement traffic rate of one report per second -- the nominal block aggregation threshold is notionally computed as the amount of data that can be sent over the link to the receiving LTP engine in a single block acknowledgment period at the planned outbound data rate to that engine.
Taken together, application-level fragmentation (or BP proactive fragmentation) and LTP aggregation place an upper limit on the amount of data that would need to be re-transmitted over a given link at next contact in the event of an unexpected link termination that caused delivery of an entire block to fail. For example, if the data rate is 1 Mbps and the nominal block size is 128 KB (equivalent to 1 second of transmission time), we would prefer to avoid the risk of having wasted five minutes of downlink in sending a 37.5 MB file that fails on transmission of the last kilobyte, forcing retransmission of the entire 37.5 MB. We therefore divide the file into, say, 1200 bundles of 32 KB each which are aggregated into blocks of 128 KB each: only a single block failed, so only that block (containing just 4 bundles) needs to be retransmitted. The cost of this retransmission is only 1 second of link time rather than 5 minutes. By controlling the cost of convergence-layer protocol failure in this way, we avoid the overhead and complexity of \"reactive fragmentation\" in the BP implementation.
Finally, within LTP itself we fragment the block as necessary to accommodate the Maximum Transfer Unit (MTU) size of the underlying link service, typically the transfer frame size of the applicable CCSDS link protocol.
"},{"location":"ION-Guide/#bandwidth-management","title":"Bandwidth Management","text":"The allocation of bandwidth (transmission opportunity) to application data is requested by the application task that's passing data to DTN, but it is necessarily accomplished only at the lowest layer of the stack at which bandwidth allocation decisions can be made -- and then always in the context of node policy decisions that have global effect.
The transmission queue interface to a given neighbor in the network is actually three queues of outbound bundles rather than one: one queue for each of the defined levels of priority (\"class of service\") supported by BP. When an application presents an ADU to BP for encapsulation in a bundle, it indicates its own assessment of the ADU's priority. Upon selection of a proximate forwarding destination node for that bundle, the bundle is appended to whichever of the queues corresponds to the ADU's priority.
Normally the convergence-layer manager (CLM) task servicing a given proximate node extracts bundles in strict priority order from the heads of the three queues. That is, the bundle at the head of the highest-priority non-empty queue is always extracted.
However, if the ION_BANDWIDTH_RESERVED compiler option is selected at the time ION is built, the convergence-layer manager task servicing a given proximate node extracts bundles in interleaved fashion from the heads of the node's three queues:
Following insertion of the extracted bundles into transmission buffers, CLO tasks other than ltpclo simply segment the buffered bundles as necessary and transmit them using the underlying convergence-layer protocols. In the case of ltpclo, the output task aggregates the buffered bundles into blocks as described earlier and a second daemon task named ltpmeter waits for aggregated blocks to be completed; ltpmeter, rather than the CLO task itself, segments each completed block as necessary and passes the segments to the link service protocol that underlies LTP. Either way, the transmission ordering requested by application tasks is preserved.
"},{"location":"ION-Guide/#contact-plans","title":"Contact Plans","text":"In the Internet, protocol operations can be largely driven by currently effective information that is discovered opportunistically and immediately, at the time it is needed, because the latency in communicating this information over the network is negligible: distances between communicating entities are small and connectivity is continuous. In a DTN-based network, however, ad-hoc information discovery would in many cases take so much time that it could not be completed before the information lost currency and effectiveness. Instead, protocol operations must be largely driven by information that is pre-placed at the network nodes and tagged with the dates and times at which it becomes effective. This information takes the form of contact plans that are managed by the R/F Contacts (rfx) services of ION's ici package.
Figure 6 RFX services in ION
The structure of ION's RFX (contact plan) database, the rfx system elements that populate and use that data, and affected portions of the BP and LTP protocol state databases are shown in Figure 6. (For additional details of BP and LTP database management, see the BP/LTP discussion later in this document.)
To clarify the notation of this diagram, which is also used in other database structure diagrams in this document:
A contact is here defined as an interval during which it is expected that data will be transmitted by DTN node A (the contact's transmitting node) and most or all of the transmitted data will be received by node B (the contact's receiving node). Implicitly, the transmitting mode will utilize some \"convergence-layer\" protocol underneath the Bundle Protocol to effect this direct transmission of data to the receiving node. Each contact is characterized by its start time, its end time, the identities of the transmitting and receiving nodes, and the rate at which data are expected to be transmitted by the transmitting node throughout the indicated time period.
(Note that a contact is specifically not an episode of activity on a link. Episodes of activity on different links -- e.g., different radio transponders operating on the same spacecraft -- may well overlap, but contacts by definition cannot; they are bounded time intervals and as such are innately \"tiled\". For example, suppose transmission on link X from node A to node B, at data rate RX, begins at time T1 and ends at time T2; also, transmission on link Y from node A to node B, at data rate RY begins at time T3 and ends at time T4. If T1 = T3 and T2 = T4, then there is a single contact from time T1 to time T2 at data rate RX + RY. If T1 \\< T3 and T2 = T4, then there are two contiguous contacts: one from T1 to T3 at data rate RX, then one from T3 to T2 at data rate RX + RY. If T1 \\< T3 and T3\\<T2 \\< T4, then there are three contiguous contacts: one from T1 to T3 at data rate RX, then one from T3 to T2 at data rate RX + RY, then one from T2 to T4 at data rate RY. And so on.)
A range interval is a period of time during which the displacement between two nodes A and B is expected to vary by less than 1 light second from a stated anticipated distance. (We expect this information to be readily computable from the known orbital elements of all nodes.) Each range interval is characterized by its start time, its end time, the identities of the two nodes to which it pertains, and the anticipated approximate distance between those nodes throughout the indicated time period, to the nearest light second.
The topology timeline at each node in the network is a time-ordered list of scheduled or anticipated changes in the topology of the network. Entries in this list are of two types:
\u2022 Contact entries characterize scheduled contacts.
\u2022 Range entries characterize anticipated range intervals.
Each node to which, according to the RFX database, the local node transmits data directly via some convergence-layer protocol at some time is termed a neighbor of the local node. Each neighbor is associated with one or more outduct for the applicable BP convergence-layer (CL) protocol adapter(s), so bundles that are to be transmitted directly to this neighbor can simply be queued for transmission by outduct (as discussed in the Bandwidth Management notes above).
At startup, and at any time while the system is running, ionadmin inserts and removes Contact and Range entries in the topology timeline of the RFX database. Inserting or removing a Contact or Range entry will cause routing tables to be recomputed for the destination nodes of all subsequently forwarded bundles, as described in the discussion of Contact Graph Routing below.
Once per second, the rfxclock task (which appears in multiple locations on the diagram to simplify the geometry) applies all topology timeline events (Contact and Range start, stop, purge) with effective time in the past. Applying a Contact event that cites a neighboring node revises the transmission or reception data rate between the local node and that Neighbor. Applying a Range event that cites a neighboring node revises the OWLT between the local node and that neighbor. Setting data rate or OWLT for a node with which the local node will at some time be in direct communication may entail creation of a Neighbor object.
"},{"location":"ION-Guide/#route-computation","title":"Route Computation","text":"ION's computation of a route for a given bundle with a given destination endpoint is accomplished by one of several methods, depending on the destination. In every case, the result of successful routing is the insertion of the bundle into an outbound transmission queue (selected according to the bundle's priority) for one or more neighboring nodes.
But before discussing these methods it will be helpful to establish some terminology:
Egress plans
ION can only forward bundles to a neighboring node by queuing them on some explicitly specified transmission queue. Specifications that associate neighboring nodes with outducts are termed egress plans. They are retained in ION's unicast forwarding database.
Static routes
ION can be configured to forward to some specified node all bundles that are destined for a given node to which no dynamic route can be discovered from an examination of the contact graph, as described later. Static routing is implemented by means of the \"exit\" mechanism described below.
Unicast
When the destination of a bundle is a single node that is registered within a known \"singleton endpoint\" (that is, an endpoint that is known to have exactly one member), then transmission of that bundle is termed unicast. For this purpose, the destination endpoint ID must be a URI formed in either the \"dtn\" scheme (e.g., dtn://bobsmac/mail) or the \"ipn\" scheme (e.g., ipn:913.11).
Exits
When unicast routes must be computed to nodes for which no contact plan information is known (e.g., the size of the network makes it impractical to distribute all Contact and Range information for all nodes to every node, or the destination nodes don't participate in Contact Graph Routing at all), the job of computing routes to all nodes may be partitioned among multiple exit nodes. Each exit is responsible for managing routing information (for example, a comprehensive contact graph) for some subset of the total network population -- a group comprising all nodes whose node numbers fall within the range of node numbers assigned to the exit. A bundle destined for a node for which no dynamic route can be computed from the local node's contact graph may be routed to the exit node for the group within whose range the destination's node number falls. Exits are defined in ION's unicast forwarding database. (Note that the exit implements static routes in ION in addition to improving scalability.)
Multicast
When the destination of a bundle is all nodes that are registered within a known \"multicast endpoint\" (that is, an endpoint that is not known to have exactly one member), then transmission of that bundle is termed multicast. For this purpose (in ION), the destination endpoint ID must be a URI formed in the \"imc\" scheme (e.g., imc:913.11).
Multicast Groups
A multicast group is the set of all nodes in the network that are members of a given multicast endpoint. Forwarding a bundle to all members of its destination multicast endpoint is the responsibility of all of the multicast-aware nodes of the network. These nodes are additionally configured to be nodes of a single multicast spanning tree overlaid onto the dtnet. A single multicast tree serves to forward bundles to all multicast groups: each node of the tree manages petitions indicating which of its \"relatives\" (parent and children) are currently interested in bundles destined for each multicast endpoint, either natively (due to membership in the indicated group) or on behalf of more distant relatives.
"},{"location":"ION-Guide/#unicast","title":"Unicast","text":"We begin unicast route computation by attempting to compute a dynamic route to the bundle's final destination node. The details of this algorithm are described in the section on Contact Graph Routing, below.
If no dynamic route can be computed, but the final destination node is a \"neighboring\" node that is directly reachable, then we assume that taking this direct route is the best strategy unless transmission to that neighbor is flagged as \"blocked\" for network operations purposes.
Otherwise we must look for a static route. If the bundle's destination node number is in one of the ranges of node numbers assigned to exit nodes, then we forward the bundle to the exit node for the smallest such range. (If the exit node is a neighbor and transmission to that neighbor is not blocked, we simply queue the bundle for transmission to that neighbor; otherwise we similarly look up the static route for the exit node until eventually we resolve to some egress plan.)
If we can determine neither a dynamic route nor a static route for this bundle, but the reason for this failure was transmission blockage that might be resolved in the future, then the bundle is placed in a \"limbo\" list for future re-forwarding when transmission to some node is \"unblocked.\"
Otherwise, the bundle cannot be forwarded. If custody transfer is requested for the bundle, we send a custody refusal to the bundle's current custodian; in any case, we discard the bundle.
"},{"location":"ION-Guide/#multicast","title":"Multicast","text":"Multicast route computation is much simpler.
A bundle whose destination endpoint cites a multicast group, whether locally sourced or received from another node:
Is delivered immediately, if the local node is a member of the indicated endpoint.
End-to-end delivery of data can fail in many ways, at different layers of the stack. When delivery fails, we can either accept the communication failure or retransmit the data structure that was transmitted at the stack layer at which the failure was detected. ION is designed to enable retransmission at multiple layers of the stack, depending on the preference of the end user application.
At the lowest stack layer that is visible to ION, the convergence-layer protocol, failure to deliver one or more segments due to segment loss or corruption will trigger segment retransmission if a \"reliable\" convergence-layer protocol is in use: LTP \"red-part\" transmission or TCP (including Bundle Relay Service, which is based on TCP)1.
Segment loss may be detected and signaled via NAK by the receiving entity, or it may only be detected at the sending entity by expiration of a timer prior to reception of an ACK. Timer interval computation is well understood in a TCP environment, but it can be a difficult problem in an environment of scheduled contacts as served by LTP. The round-trip time for an acknowledgment dialogue may be simply twice the one-way light time (OWLT) between sender and receiver at one moment, but it may be hours or days longer at the next moment due to cessation of scheduled contact until a future contact opportunity. To account for this timer interval variability in retransmission, the ltpclock task infers the initiation and cessation of LTP transmission, to and from the local node, from changes in the current xmit and recv data rates in the corresponding Neighbor objects. This controls the dequeuing of LTP segments for transmission by underlying link service adapter(s) and it also controls suspension and resumption of timers, removing the effects of contact interruption from the retransmission regime. For a further discussion of this mechanism, see the section below on LTP Timeout Intervals.
Note that the current OWLT in Neighbor objects is also used in the computation of the nominal expiration times of timers and that ltpclock is additionally the agent for LTP segment retransmission based on timer expiration.
It is, of course, possible for the nominally reliable convergence-layer protocol to fail altogether: a TCP connection might be abruptly terminated, or an LTP transmission might be canceled due to excessive retransmission activity (again possibly due to an unexpected loss of connectivity). In this event, BP itself detects the CL protocol failure and re-forwards all bundles whose acquisition by the receiving entity is presumed to have been aborted by the failure. This re-forwarding is initiated in different ways for different CL protocols, as implemented in the CL input and output adapter tasks. If immediate re-forwarding is impossible because transmission to all potentially viable neighbors is blocked, the affected bundles are placed in the limbo list for future re-forwarding when transmission to some node is unblocked.
In addition to the implicit forwarding failure detected when a CL protocol fails, the forwarding of a bundle may be explicitly refused by the receiving entity, provided the bundle is flagged for custody transfer service. A receiving node's refusal to take custody of a bundle may have any of a variety of causes: typically the receiving node either (a) has insufficient resources to store and forward the bundle, (b) has no route to the destination, or (c) will have no contact with the next hop on the route before the bundle's TTL has expired. In any case, a \"custody refusal signal\" (packaged in a bundle) is sent back to the sending node, which must re-forward the bundle in hopes of finding a more suitable route.
Alternatively, failure to receive a custody acceptance signal within some convergence-layer-specified or application-specified time interval may also be taken as an implicit indication of forwarding failure. Here again, when BP detects such a failure it attempts to re-forward the affected bundle, placing the bundle in the limbo list if re-forwarding is currently impossible.
In the worst case, the combined efforts of all the retransmission mechanisms in ION are not enough to ensure delivery of a given bundle, even when custody transfer is requested. In that event, the bundle's \"time to live\" will eventually expire while the bundle is still in custody at some node: the bpclock task will send a bundle status report to the bundle's report-to endpoint, noting the TTL expiration, and destroy the bundle. The report-to endpoint, upon receiving this report, may be able to initiate application-layer retransmission of the original application data unit in some way. This final retransmission mechanism is wholly application-specific, however.
"},{"location":"ION-Guide/#rate-control","title":"Rate Control","text":"In the Internet, the rate of transmission at a node can be dynamically negotiated in response to changes in level of activity on the link, to minimize congestion. On deep space links, signal propagation delays (distances) may be too great to enable effective dynamic negotiation of transmission rates. Fortunately, deep space links are operationally reserved for use by designated pairs of communicating entities over pre-planned periods of time at pre-planned rates. Provided there is no congestion inherent in the contact plan, congestion in the network can be avoided merely by adhering to the planned contact periods and data rates. Rate control in ION serves this purpose.
While the system is running, transmission and reception of bundles is constrained by the current capacity in the throttle of each convergence-layer manager. Completed bundle transmission activity reduces the current capacity of the applicable throttle by the capacity consumption computed for that bundle. This reduction may cause the throttle's current capacity to become negative. Once the current capacity of the applicable throttle goes negative, activity is blocked until non-negative capacity has been restored by bpclock.
Once per second, the bpclock task increases the current capacity of each throttle by one second's worth of traffic at the nominal data rate for transmission to that node, thus enabling some possibly blocked bundle transmission and reception to proceed.
bpclock revises all throttles' nominal data rates once per second in accord with the current data rates in the corresponding Neighbor objects, as adjusted by rfxclock per the contact plan.
Note that this means that, for any neighboring node for which there are planned contacts, ION's rate control system will enable data flow only while contacts are active.
"},{"location":"ION-Guide/#flow-control","title":"Flow Control","text":"A further constraint on rates of data transmission in an ION-based network is LTP flow control. LTP is designed to enable multiple block transmission sessions to be in various stages of completion concurrently, to maximize link utilization: there is no requirement to wait for one session to complete before starting the next one. However, if unchecked this design principle could in theory result in the allocation of all memory in the system to incomplete LTP transmission sessions. To prevent complete storage resource exhaustion, we set a firm upper limit on the total number of outbound blocks that can be concurrently in transit at any given time. These limits are established by ltpadmin at node initialization time.
The maximum number of transmission sessions that may be concurrently managed by LTP therefore constitutes a transmission \"window\" -- the basis for a delay-tolerant, non-conversational flow control service over interplanetary links. Once the maximum number of sessions are in flight, no new block transmission session can be initiated -- regardless of how much outduct transmission capacity is provided by rate control -- until some existing session completes or is canceled.
Note that this consideration emphasizes the importance of configuring the aggregation size limits and session count limits of spans during LTP initialization to be consistent with the maximum data rates scheduled for contacts over those spans.
"},{"location":"ION-Guide/#storage-management","title":"Storage Management","text":"Congestion in a dtnet is the imbalance between data enqueuing and dequeuing rates that results in exhaustion of queuing (storage) resources at a node, preventing continued operation of the protocols at that node.
In ION, the affected queuing resources are allocated from notionally non-volatile storage space in the SDR data store and/or file system. The design of ION is required to prevent resource exhaustion by simply refusing to enqueue additional data that would cause it.
However, a BP router's refusal to enqueue received data for forwarding could result in costly retransmission, data loss, and/or the \"upstream\" propagation of resource exhaustion to other nodes. Therefore the ION design additionally attempts to prevent potential resource exhaustion by forecasting levels of queuing resource occupancy and reporting on any congestion that is predicted. Network operators, upon reviewing these forecasts, may revise contact plans to avert the anticipated resource exhaustion.
The non-volatile storage used by ION serves several purposes: it contains queues of bundles awaiting forwarding, transmission, and delivery; it contains LTP transmission and reception sessions, including the blocks of data that are being transmitted and received; it contains queues of LTP segments awaiting radiation; it may contain CFDP transactions in various stages of completion; and it contains protocol operational state information, such as configuration parameters, static routes, the contact graph, etc.
Effective utilization of non-volatile storage is a complex problem. Static pre-allocation of storage resources is in general less efficient (and also more labor-intensive to configure) than storage resource pooling and automatic, adaptive allocation: trying to predict a reasonable maximum size for every data storage structure and then rigidly enforcing that limit typically results in underutilization of storage resources and underperformance of the system as a whole. However, static pre-allocation is mandatory for safety-critical resources, where certainty of resource availability is more important than efficient resource utilization.
The tension between the two approaches is analogous to the tension between circuit switching and packet switching in a network: circuit switching results in underutilization of link resources and underperformance of the network as a whole (some peaks of activity can never be accommodated, even while some resources lie idle much of the time), but dedicated circuits are still required for some kinds of safety-critical communication.
So the ION data management design combines these two approaches (see 1.5 above for additional discussion of this topic):
The maximum projected occupancy of the node is the result of computing a congestion forecast for the node, by adding to the current occupancy all anticipated net increases and decreases from now until some future time, termed the horizon for the forecast.
The forecast horizon is indefinite -- that is, \"forever\" -- unless explicitly declared by network management via the ionadmin utility program. The difference between the horizon and the current time is termed the interval of the forecast.
Net occupancy increases and decreases are of four types:
The type-1 anticipated net increase (total data origination) is computed by multiplying the node's projected rate of local data production, as declared via an ionadmin command, by the interval of the forecast. Similarly, the type-4 anticipated net decrease (total data delivery) is computed by multiplying the node's projected rate of local data consumption, as declared via an ionadmin command, by the interval of the forecast. Net changes of types 2 and 3 are computed by multiplying inbound and outbound data rates, respectively, by the durations of all periods of planned communication contact that begin and/or end within the interval of the forecast.
Congestion forecasting is performed by the ionwarn utility program. ionwarn may be run independently at any time; in addition, the ionadmin utility program automatically runs ionwarn immediately before exiting if it executed any change in the contact plan, the forecast horizon, or the node's projected rates of local data production or consumption. Moreover, the rfxclock daemon program also runs ionwarn automatically whenever any of the scheduled reconfiguration events it dispatches result in contact state changes that might alter the congestion forecast.
If the final result of the forecast computation -- the maximum projected occupancy of the node over the forecast interval -- is less than the total protocol traffic allocation, then no congestion is forecast. Otherwise, a congestion forecast status message is logged noting the time at which maximum projected occupancy is expected to equal the total protocol traffic allocation.
Congestion control in ION, then, has two components:
First, ION's congestion detection is anticipatory (via congestion forecasting) rather than reactive as in the Internet.
Anticipatory congestion detection is important because the second component -- congestion mitigation -- must also be anticipatory: it is the adjustment of communication contact plans by network management, via the propagation of revised schedules for future contacts.
(Congestion mitigation in an ION-based network is likely to remain mostly manual for many years to come, because communication contact planning involves much more than orbital dynamics: science operations plans, thermal and power constraints, etc. It will, however, rely on the automated rate control features of ION, discussed above, which ensure that actual network operations conform to established contact plans.)
Rate control in ION is augmented by admission control. ION tracks the sum of the sizes of all zero-copy objects currently residing in the heap and file system at any moment. Whenever any protocol implementation attempts to create or extend a ZCO in such a way that total heap or file occupancy would exceed an upper limit asserted for the node, that attempt is either blocked until ZCO space becomes available or else rejected altogether.
"},{"location":"ION-Guide/#optimizing-an-ion-based-network","title":"Optimizing an ION-based network","text":"ION is designed to deliver critical data to its final destination with as much certainty as possible (and optionally as soon as possible), but otherwise to try to maximize link utilization. The delivery of critical data is expedited by contact graph routing and bundle prioritization as described elsewhere. Optimizing link utilization, however, is a more complex problem.
If the volume of data traffic offered to the network for transmission is less than the capacity of the network, then all offered data should be successfully delivered3. But in that case the users of the network are paying the opportunity cost of whatever portion of the network capacity was not used.
Offering a data traffic volume that is exactly equal to the capacity of the network is in practice infeasible. TCP in the Internet can usually achieve this balance because it exercises end-to-end flow control: essentially, the original source of data is blocked from offering a message until notified by the final destination that transmission of this message can be accommodated given the current negotiated data rate over the end-to-end path (as determined by TCP's congestion control mechanisms). In a delay-tolerant network no such end-to-end negotiated data rate may exist, much less be knowable, so such precise control of data flow is impossible.4
The only alternative: the volume of traffic offered by the data source must be greater than the capacity of the network and the network must automatically discard excess traffic, shedding lower-priority data in preference to high-priority messages on the same path.
ION discards excess traffic proactively when possible and reactively when necessary.
Proactive data triage occurs when ION determines that it cannot compute a route that will deliver a given bundle to its final destination prior to expiration of the bundle's Time To Live (TTL). That is, a bundle may be discarded simply because its TTL is too short, but more commonly it will be discarded because the planned contacts to whichever neighboring node is first on the path to the destination are already fully subscribed: the queue of bundles awaiting transmission to that neighbor is already so long as to consume the entire capacity of all announced opportunities to transmit to it. Proactive data triage causes the bundle to be immediately destroyed as one for which there is \"No known route to destination from here.\"
The determination of the degree to which a contact is subscribed is based not only on the aggregate size of the queued bundles but also on the estimated aggregate size of the overhead imposed by all the convergence-layer (CL) protocol data units -- at all layers of the underlying stack -- that encapsulate those bundles: packet headers, frame headers, etc. This means that the accuracy of this overhead estimate will affect the aggressiveness of ION's proactive data triage:
Essentially, all reactive data triage -- the destruction of bundles due to TTL expiration prior to successful delivery to the final destination -- occurs when the network conveys bundles at lower net rates than were projected during route computation. These performance shortfalls can have a variety of causes:
Some level of data triage is essential to cost-effective network utilization, and proactive triage is preferable because its effects can be communicated immediately to users, improving user control over the use of the network. Optimizing an ION-based network therefore amounts to managing for a modicum of proactive data triage and as little reactive data triage as possible. It entails the following:
As an example, suppose the local node uses LTP over CCSDS Telemetry to send bundles. The immediate convergence-layer protocol is LTP, but the total overhead per CL \"frame\" (in this case, per LTP segment) will include not only the size of the LTP header (nominally 5 bytes) but also the size of the encapsulating space packet header (nominally 6 bytes) and the overhead imposed by the outer encapsulating TM frame.
Suppose each LTP segment is to be wrapped in a single space packet, which is in turn wrapped in a single TM frame, and Reed-Solomon encoding is applied. An efficient TM frame size is 1115 bytes, with an additional 160 bytes of trailing Reed-Solomon encoding and another 4 bytes of leading pseudo-noise code. The frame would contain a 6-byte TM frame header, a 6-byte space packet header, a 5-byte LTP segment header, and 1098 bytes of some LTP transmission block.
So the number of \"payload bytes per frame\" in this case would be 1098 and the number of \"overhead bytes per frame\" would be 4 + 6 + 6 + 5 + 160 = 181. Nominal total transmission overhead on the link would be 181 / 1279 = about 14%. 2. Synchronizing nodes' clocks as accurately as possible, so that timing margins configured to accommodate clock error can be kept as close to zero as possible. 3. Setting the LTP session limit and block size limit as generously as possible (whenever LTP is at the convergence layer), to assure that LTP flow control does not constrain data flow to rates below those supported by BP rate control. 4. Setting ranges (one-way light times) and queuing delays as accurately as possible, to prevent unnecessary retransmission. Err on the side of pessimism -- that is, overestimate a little. 5. Communicating changes in configuration -- especially contact plans -- to all nodes as far in advance of the time they take effect as possible. 6. Providing all nodes with as much storage capacity as possible for queues of bundles awaiting transmission.
"},{"location":"ION-Guide/#bpltp-detail-how-they-work","title":"BP/LTP Detail -- How They Work","text":"Although the operation of BP/LTP in ION is complex in some ways, virtually the entire system can be represented in a single diagram. The interactions among all of the concurrent tasks that make up the node -- plus a Remote AMS task or CFDP UT-layer task, acting as the application at the top of the stack -- are shown below. (The notation is as used earlier but with semaphores added. Semaphores are shown as small circles, with arrows pointing into them signifying that the semaphores are being given and arrows pointing out of them signifying that the semaphores are being taken.)
Figure 7 ION node functional overview
Further details of the BP/LTP data structures and flow of control and data appear on the following pages. (For specific details of the operation of the BP and LTP protocols as implemented by the ION tasks, such as the nature of report-initiated retransmission in LTP, please see the protocol specifications. The BP specification is documented in Internet RFC 5050, while the LTP specification is documented in Internet RFC 5326.)
"},{"location":"ION-Guide/#databases","title":"Databases","text":"Figure 8: Bundle protocol database
Figure 9: Licklider transmission protocol database
"},{"location":"ION-Guide/#control-and-data-flow","title":"Control and data flow","text":""},{"location":"ION-Guide/#bundle-protocol","title":"Bundle Protocol","text":"Figure 10 BP forwarder
Figure 11 BP convergence layer output
"},{"location":"ION-Guide/#ltp","title":"LTP","text":"Figure 12 LTP transmission metering
Figure 13 LTP link service output
Figure 14 LTP link service input
"},{"location":"ION-Guide/#contact-graph-routing-cgr","title":"Contact Graph Routing (CGR)","text":"CGR is a dynamic routing system that computes routes through a time-varying topology of scheduled communication contacts in a DTN network. It is designed to support operations in a space network based on DTN, but it also could be used in terrestrial applications where operation according to a predefined schedule is preferable to opportunistic communication, as in a low-power sensor network.
The basic strategy of CGR is to take advantage of the fact that, since communication operations are planned in detail, the communication routes between any pair of \"bundle agents\" in a population of nodes that have all been informed of one another's plans can be inferred from those plans rather than discovered via dialogue (which is impractical over long-one-way-light-time space links).
"},{"location":"ION-Guide/#contact-plan-messages","title":"Contact Plan Messages","text":"CGR relies on accurate contact plan information provided in the form of contact plan messages that currently are only read from ionrc files and processed by ionadmin, which retains them in a non-volatile contact plan in the RFX database, in ION's SDR data store.
Contact plan messages are of two types: contact messages and range messages.
Each contact message has the following content:
Each range message has the following content:
Note that range messages may be used to declare that the \"distance\" in light seconds between nodes A and B is different in the B\ud83e\udc6aA direction from the distance in the A\ud83e\udc6aB direction. While direct radio communication between A and B will not be subject to such asymmetry, it's possible for connectivity established using other convergence-layer technologies to take different physical paths in different directions, with different signal propagation delays.
"},{"location":"ION-Guide/#routing-tables","title":"Routing Tables","text":"Each node uses Range and Contact messages in the contact plan to build a \\\"routing table\\\" data structure.
The routing table constructed locally by each node in the network is a list of entry node lists, one route list for every other node D in the network that is cited in any Contact or Range in the contact plan. Entry node lists are computed as they are needed, and the maximum number of entry node lists resident at a given time is the number of nodes that are cited in any Contacts or Ranges in the contact plan. Each entry in the entry node list for node D is a list of the neighbors of local node X; included with each entry of the entry node list is a list one or more routes to D through the indicated neighbor, termed a route list.
Each route in the route list for node D identifies a path to destination node D, from the local node, that begins with transmission to one of the local node's neighbors in the network-- the initial receiving node for the route, termed the route's entry node.
For any given route, the contact from the local node to the entry node constitutes the initial transmission segment of the end-to-end path to the destination node. Additionally noted in each route object are all of the other contacts that constitute the remaining segments of the route's end-to-end path.
Each route object also notes the forwarding cost for a bundle that is forwarded along this route. In this version of ION, CGR is configured to deliver bundles as early as possible, so best-case final delivery time is used as the cost of a route. Other metrics might be substituted for final delivery time in other CGR implementations. NOTE, however, that if different metrics are used at different nodes along a bundle's end-to-end path it becomes impossible to prevent routing loops that can result in non-delivery of the data.
Finally, each route object also notes the route's termination time, the time after which the route will become moot due to the termination of the earliest-ending contact in the route.
"},{"location":"ION-Guide/#key-concepts","title":"Key Concepts","text":""},{"location":"ION-Guide/#expiration-time","title":"Expiration time","text":"Every bundle transmitted via DTN has a time-to-live (TTL), the length of time after which the bundle is subject to destruction if it has not yet been delivered to its destination. The expiration time of a bundle is computed as its creation time plus its TTL. When computing the next-hop destination for a bundle that the local bundle agent is required to forward, there is no point in selecting a route that can\\'t get the bundle to its final destination prior to the bundle's expiration time.
"},{"location":"ION-Guide/#owlt-margin","title":"OWLT margin","text":"One-way light time (OWLT) -- that is, distance -- is obviously a factor in delivering a bundle to a node prior to a given time. OWLT can actually change during the time a bundle is en route, but route computation becomes intractably complex if we can\\'t assume an OWLT \\\"safety margin\\\" -- a maximum delta by which OWLT between any pair of nodes can change during the time a bundle is in transit between them.
We assume that the maximum rate of change in distance between any two nodes in the network is about 150,000 miles per hour, which is about 40 miles per second. (This was the speed of the Helios spacecraft, the fastest man-made object launched to date.)
At this speed, the distance between any two nodes that are initially separated by a distance of N light seconds will increase by a maximum of 80 miles per second of transit (in the event that they are moving in opposite directions). This will result in data arrival no later than roughly (N + 2Q) seconds after transmission -- where the \"OWLT margin\" value Q is (40 * N) divided by 186,000 -- rather than just N seconds after transmission as would be the case if the two nodes were stationary relative to each other. When computing the expected time of arrival of a transmitted bundle we simply use N + 2Q, the most pessimistic case, as the anticipated total in-transit time.
"},{"location":"ION-Guide/#capacity","title":"Capacity","text":"The capacity of a contact is the product of its data transmission rate (in bytes per second) and its duration (stop time minus start time, in seconds).
"},{"location":"ION-Guide/#estimated-capacity-consumption","title":"Estimated capacity consumption","text":"The size of a bundle is the sum of its payload size and its header size5, but bundle size is not the only lien on the capacity of a contact. The total estimated volume consumption (or \"EVC\") for a bundle is the sum of the sizes of the bundle's payload and header and the estimated convergence-layer overhead. For a bundle whose header is of size M and whose payload is of size N, the estimated convergence-layer overhead is defined as 3% of (M+N), or 100 bytes, whichever is larger.
"},{"location":"ION-Guide/#residual-capacity","title":"Residual capacity","text":"The residual capacity of a given contact between the local node and one of its neighbors, as computed for a given bundle, is the sum of the capacities of that contact and all prior scheduled contacts between the local node and that neighbor, less the sum of the ECCs of all bundles with priority equal to or higher than the priority of the subject bundle that are currently queued on the outduct for transmission to that neighbor.
"},{"location":"ION-Guide/#excluded-neighbors","title":"Excluded neighbors","text":"A neighboring node C that refuses custody of a bundle destined for some remote node D is termed an excluded neighbor for (that is, with respect to computing routes to) D. So long as C remains an excluded neighbor for D, no bundles destined for D will be forwarded to C -- except that occasionally (once per lapse of the RTT between the local node and C) a custodial bundle destined for D will be forwarded to C as a \"probe bundle\". C ceases to be an excluded neighbor for D as soon as it accepts custody of a bundle destined for D.
"},{"location":"ION-Guide/#critical-bundles","title":"Critical bundles","text":"A Critical bundle is one that absolutely has got to reach its destination and, moreover, has got to reach that destination as soon as is physically possible6.
For an ordinary non-Critical bundle, the CGR dynamic route computation algorithm uses the routing table to select a single neighboring node to forward the bundle through. It is possible, though, that due to some unforeseen delay the selected neighbor may prove to be a sub-optimal forwarder: the bundle might arrive later than it would have if another neighbor had been selected, or it might not even arrive at all.
For Critical bundles, the CGR dynamic route computation algorithm causes the bundle to be inserted into the outbound transmission queues for transmission to all neighboring nodes that can plausibly forward the bundle to its final destination. The bundle is therefore guaranteed to travel over the most successful route, as well as over all other plausible routes. Note that this may result in multiple copies of a Critical bundle arriving at the final destination.
"},{"location":"ION-Guide/#dynamic-route-selection-algorithm","title":"Dynamic Route Selection Algorithm","text":"Given a bundle whose destination is node D, we proceed as follows.
First, if no contacts in the contact plan identify transmission to node D, then we cannot use CGR to find a route for this bundle; CGR route selection is abandoned.
Next, if the contact plan has been modified in any way since routes were computed for any nodes, we discard all routes for all nodes and authorize route recomputation. (The contact plan changes may have invalidated any or all of those earlier computations.)
We create an empty list of Proximate Nodes (network neighbors) to send the bundle to.
We create a list of Excluded Nodes, i.e., nodes through which we will not compute a route for this bundle. The list of Excluded Nodes is initially populated with:
If all routes computed for node D have been discarded due to contact plan modification, then we must compute a new list of all routes from the local node to D. To do so:
We perform several Dijkstra searches within this graph, one search for each of the local node's neighbors. On each search we find the lowest-cost route that begins at the root of the graph and ends at the terminal vertex. Each time a route is computed, we add it to the list of routes for that route's entry node and then remove from further consideration all contacts from the local node to the entry node of that route.
The lowest-cost route computed during a search is the one that is found to have the earliest best-case delivery time, where the best-case delivery time characterizing a route is given by the time at which a bundle would arrive at node D if transmitted at the earliest possible moment of the last contact in the route prior to the terminal vertex.
We next examine all of the routes that are currently computed for transmission of bundles to node D.
For each route that is not ignored, the route's entry node is added to the list of Proximate Nodes for this bundle. Associated with the entry node number in this list entry are the best-case final delivery time of the route, the total number of \"hops\" in the route's end-to-end path, and the forfeit time for transmission to this node. Forfeit time is the route's termination time, the time by which the bundle must have been transmitted to this node in order to have any chance of being forwarded on this route.
If, at the end of this procedure, the Proximate Nodes list is empty, then we have been unable to use CGR to find a route for this bundle; CGR route selection is abandoned.
Otherwise:
Otherwise, the bundle is enqueued for transmission on the outduct to the most preferred neighbor in the Proximate Nodes list:
If one of the nodes in this list is associated with a best-case delivery time that is earlier than that of all other nodes in the list, then it is the most preferred neighbor.
Conveyance of a bundle from source to destination through a DTN can fail in a number of ways, many of which are best addressed by means of the Delivery Assurance mechanisms described earlier. Failures in Contact Graph Routing, specifically, occur when the expectations on which routing decisions are based prove to be false. These failures of information fall into two general categories: contact failure and custody refusal.
"},{"location":"ION-Guide/#contact-failure","title":"Contact Failure","text":"A scheduled contact between some node and its neighbor on the end-to-end route may be initiated later than the originally scheduled start time, or be terminated earlier than the originally scheduled stop time, or be canceled altogether. Alternatively, the available capacity for a contact might be overestimated due to, for example, diminished link quality resulting in unexpectedly heavy retransmission at the convergence layer. In each of these cases, the anticipated transmission of a given bundle during the affected contact may not occur as planned: the bundle might expire before the contact's start time, or the contact's stop time might be reached before the bundle has been transmitted.
For a non-Critical bundle, we handle this sort of failure by means of a timeout: if the bundle is not transmitted prior to the forfeit time for the selected Proximate Node, then the bundle is removed from its outbound transmission queue and the Dynamic Route Computation Algorithm is re-applied to the bundle so that an alternate route can be computed.
"},{"location":"ION-Guide/#custody-refusal","title":"Custody refusal","text":"A node that receives a bundle may find it impossible to forward it, for any of several reasons: it may not have enough storage capacity to hold the bundle, it may be unable to compute a forward route (static, dynamic, or default) for the bundle, etc. Such bundles are simply discarded, but discarding any such bundle that is marked for custody transfer will cause a custody refusal signal to be returned to the bundle's current custodian.
When the affected bundle is non-Critical, the node that receives the custody refusal re-applies the Dynamic Route Computation Algorithm to the bundle so that an alternate route can be computed -- except that in this event the node from which the bundle was originally directly received is omitted from the initial list of Excluded Nodes. This enables a bundle that has reached a dead end in the routing tree to be sent back to a point at which an altogether different branch may be selected.
For a Critical bundle no mitigation of either sort of failure is required or indeed possible: the bundle has already been queued for transmission on all plausible routes, so no mechanism that entails re-application of CGR's Dynamic Route Computation Algorithm could improve its prospects for successful delivery to the final destination. However, in some environments it may be advisable to re-apply the Dynamic Route Computation Algorithm to all Critical bundles that are still in local custody whenever a new Contact is added to the contact graph: the new contact may open an additional forwarding opportunity for one or more of those bundles.
"},{"location":"ION-Guide/#remarks","title":"Remarks","text":"The CGR routing procedures respond dynamically to the changes in network topology that the nodes are able know about, i.e., those changes that are subject to mission operations control and are known in advance rather than discovered in real time. This dynamic responsiveness in route computation should be significantly more effective and less expensive than static routing, increasing total data return while at the same time reducing mission operations cost and risk.
Note that the non-Critical forwarding load across multiple parallel paths should be balanced automatically:
Although the route computation procedures are relatively complex they are not computationally difficult. The impact on computation resources at the vehicles should be modest.
"},{"location":"ION-Guide/#ltp-timeout-intervals","title":"LTP Timeout Intervals","text":"Suppose we've got Earth ground station ES that is currently in view of Mars but will be rotating out of view (\"Mars-set\") at some time T1 and rotating back into view (\"Mars-rise\") at time T3. Suppose we've also got Mars orbiter MS that is currently out of the shadow of Mars but will move behind Mars at time T2, emerging at time T4. Let's also suppose that ES and MS are 4 light-minutes apart (Mars is at its closest approach to Earth). Finally, for simplicity, let's suppose that both ES and MS want to be communicating at every possible moment (maximum link utilization) but never want to waste any electricity.
Neither ES nor MS wants to be wasting power on either transmitting or receiving at a time when either Earth or Mars will block the signal.
ES will therefore stop transmitting at either T1 or (T2 - 4 minutes), whichever is earlier; call this time Tet0. It will stop receiving -- that is, power off the receiver -- at either T1 or (T2 + 4 minutes), whichever is earlier; call this time Ter0. It will resume transmitting at either T3 or (T4 - 4 minutes), whichever is late, and it will resume reception at either T3 or (T4 + 4 minutes), whichever is later; call these times Tet1 and Ter1.
Similarly, MS will stop transmitting at either T2 or (T1 - 4 minutes), whichever is earlier; call this time Tmt0. It will stop receiving -- that is, power off the receiver -- at either T2 or (T1 + 4 minutes), whichever is earlier; call this time Tmr0. It will resume transmitting at either T4 or (T3 - 4 minutes), whichever is later, and it will resume reception at either T4 or (T3 + 4 minutes), whichever is later; call these times Tmt1 and Tmr1.
By making sure that we don't transmit when the signal would be blocked, we guarantee that anything that is transmitted will arrive at a time when it can be received. Any reception failure is due to data corruption en route.
So the moment of transmission of an acknowledgment to any message is always equal to the moment the original message was sent plus some imputed outbound queuing delay QO1 at the sending node, plus 4 minutes, plus some imputed inbound and outbound queuing delay QI1 + QO2 at the receiving node. The nominally expected moment of reception of this acknowledgment is that moment of transmission plus 4 minutes, plus some imputed inbound queuing delay QI2 at the original sending node. That is, the timeout interval is 8 minutes + QO1 + QI1 + QO2 + QO2 -- unless this moment of acknowledgement transmission is during an interval when the receiving node is not transmitting, for whatever reason. In this latter case, we want to suspend the acknowledgment timer during any interval in which we know the remote node will not be transmitting. More precisely, we want to add to the timeout interval the time difference between the moment of message arrival and the earliest moment at which the acknowledgment could be sent, i.e., the moment at which transmission is resumed7.
So the timeout interval Z computed at ES for a message sent to MS at time TX is given by:
Z = QO1 + 8 + QI1 + ((TA = TX + 4) > Tmt0 && TA < Tmt1) ?\nTmt1 - TA: 0) + QI2 + QO2\nThis can actually be computed in advance (at time TX) if T1, T2, T3, and T4 are known and are exposed to the protocol engine.
If they are not exposed, then Z must initially be estimated to be (2 * the one-way light time) + QI + QO. The timer for Z must be dynamically suspended at time Tmt0 in response to a state change as noted by ltpclock. Finally, the timer must be resumed at time Tmt1 (in response to another state change as noted by ltpclock), at which moment the correct value for Z can be computed.
"},{"location":"ION-Guide/#cfdp","title":"CFDP","text":"The ION implementation of CFDP is very simple, because only Class-1 (Unacknowledged) functionality is implemented: the store-and-forward routing performed by Bundle Protocol makes the CFDP Extended Procedures unnecessary and the inter-node reliability provided by the CL protocol underneath BP -- in particular, by LTP -- makes the CFDP Acknowledged Procedures unnecessary. All that CFDP is required to do is segment and reassemble files, interact with the underlying Unitdata Transfer layer -- BP/LTP -- to effect the transmission and reception of file data segments, and handle CFDP metadata including filestore requests. CFDP-ION does all this, including support for cancellation of a file transfer transaction by cancellation of the transmission of the bundles encapsulating the transaction's protocol data units.
Note that all CFDP data transmission is \"by reference\", via the ZCO system, rather than \"by value\": the retransmission buffer for a bundle containing CFDP file data is an extent of the original file itself, not a copy retained in the ION database, and data received in bundles containing CFDP PDU is written immediately to the appropriate location in the reconstituted file rather than stored in the ION database. This minimizes the space needed for the database. In general, file transmission via CFDP is the most memory-efficient way to use ION in flight operations.
Figure 15 A CFDP-ION entity
"},{"location":"ION-Guide/#list-data-structures-lyst-sdrlist-smlist","title":"List data structures (lyst, sdrlist, smlist)","text":"Figure 16 ION list data structures
"},{"location":"ION-Guide/#psm-partition-structure","title":"PSM Partition Structure","text":"Figure 17 psm partition structure
"},{"location":"ION-Guide/#psm-and-sdr-block-structures","title":"PSM and SDR Block Structures","text":"Figure 18 psm and sdr block structures
"},{"location":"ION-Guide/#sdr-heap-structure","title":"SDR Heap Structure","text":"Figure 19 sdr heap structure
"},{"location":"ION-Guide/#operation","title":"Operation","text":"The ION source distribution contains a README.TXT file with details on building ION from source. For installations starts with the open source distribution ION-DTN, using the standard sequence of
./configure
Note: the user needs to clear all errors reported by the configure script before proceeding. The distribution contains a default \"Makefile\" at the top level of the distribution for developer use. The configure script must complete successfully to produce an updated Makefile.
will build ION and install it under /usr/local.
Users building from a clone of the repository need to use the command
before starting the installation.
The \"Build\" instructions shown in the following sections for each package are the instructions for building each package individually, for ION development purposes. The default installation target for the individual package build commands is /opt.
One compile-time option is applicable to all ION packages: the platform selection parameters --DVXWORKS and --DRTEMS affect the manner in which most task instantiation functions are compiled. For VXWORKS and RTEMS, these functions are compiled as library functions that must be identified by name in the platform's symbol table, while for Unix-like platforms they are compiled as main()functions.
"},{"location":"ION-Guide/#interplanetary-communication-infrastructure-ici_1","title":"Interplanetary Communication Infrastructure (ICI)","text":""},{"location":"ION-Guide/#compile-time-options","title":"Compile-time options","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DFSWSOURCE or --DSM_SEMBASEKEY=0xff13), will alter the functionality of ION as noted below.
PRIVATE_SYMTAB
This option causes ION to be built for VxWorks 5.4 or RTEMS with reliance on a small private local symbol table that is accessed by means of a function named sm_FindFunction. Both the table and the function definition are, by default, provided by the symtab.c source file, which is automatically included within the platform_sm.c source when this option is set. The table provides the address of the top-level function to be executed when a task for the indicated symbol (name) is to be spawned, together with the priority at which that task is to execute and the amount of stack space to be allocated to that task.
PRIVATE_SYMTAB is defined by default for RTEMS but not for VxWorks 5.4.
Absent this option, ION on VxWorks 5.4 must successfully execute the VxWorks symFindByName function in order to spawn a new task. For this purpose the entire VxWorks symbol table for the compiled image must be included in the image, and task priority and stack space allocation must be explicitly specified when tasks are spawned.
FSWLOGGER
This option causes the standard ION logging function, which simply writes all ION status messages to a file named ion.log in the current working directory, to be replaced (by #include) with code in the source file fswlogger.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
FSWCLOCK
This option causes the invocation of the standard time function within getUTCTime (in ion.c) to be replaced (by #include) with code in the source file fswutc.c, which might for example invoke a mission-specific function to read a value from the spacecraft clock. A file of this name must be in the inclusion path for the compiler.
FSWWDNAME
This option causes the invocation of the standard getcwd function within cfdpInit (in libcfdpP.c) to be replaced (by #include) with code in the source file wdname.c, which must in some way cause the mission-specific value of the current working directory name to be copied into cfdpdbBuf.workingDirectoryName. A file of this name must be in the inclusion path for the compiler.
FSWSYMTAB
If the PRIVATE_SYMTAB option is also set, then the FSWSYMTAB option causes the code in source file mysymtab.c to be included in platform_sm.c in place of the default symbol table access implementation in symtab.c. A file named mysymtab.c must be in the inclusion path for the compiler.
FSWSOURCE
This option simply causes FSWLOGGER, FSWCLOCK, FSWWDNAME, and FSWSYMTAB all to be set.
GDSLOGGER
This option causes the standard ION logging function, which simply writes all ION status messages to a file named ion.log in the current working directory, to be replaced (by #include) with code in the source file gdslogger.c. A file of this name must be in the inclusion path for the compiler, as defined by --Ixxxx compiler option parameters.
GDSSOURCE
This option simply causes GDSLOGGER to be set.
ION_OPS_ALLOC=*xx*
This option specifies the percentage of the total non-volatile storage space allocated to ION that is reserved for protocol operational state information, i.e., is not available for the storage of bundles or LTP segments. The default value is 20.
ION_SDR_MARGIN=*xx*
This option specifies the percentage of the total non-volatile storage space allocated to ION that is reserved simply as margin, for contingency use. The default value is 20.
The sum of ION_OPS_ALLOC and ION_SDR_MARGIN defines the amount of non-volatile storage space that is sequestered at the time ION operations are initiated: for purposes of congestion forecasting and prevention of resource oversubscription, this sum is subtracted from the total size of the SDR \"heap\" to determine the maximum volume of space available for bundles and LTP segments. Data reception and origination activities fail whenever they would cause the total amount of data store space occupied by bundles and segments to exceed this limit.
USING_SDR_POINTERS
This is an optimization option for the SDR non-volatile data management system: when set, it enables the value of any variable in the SDR data store to be accessed directly by means of a pointer into the dynamic memory that is used as the data store storage medium, rather than by reading the variable into a location in local stack memory. Note that this option must not be enabled if the data store is configured for file storage only, i.e., if the SDR_IN_DRAM flag was set to zero at the time the data store was created by calling sdr_load_profile. See the ionconfig(5) man page in Appendix A for more information.
NO_SDR_TRACE
This option causes non-volatile storage utilization tracing functions to be omitted from ION when the SDR system is built. It disables a useful debugging option but reduces the size of the executable software.
NO_PSM_TRACE
This option causes memory utilization tracing functions to be omitted from ION when the PSM system is built. It disables a useful debugging option but reduces the size of the executable software.
IN_FLIGHT
This option controls the behavior of ION when an unrecoverable error is encountered.
If it is set, then the status message \"Unrecoverable SDR error\" is logged and the SDR non-volatile storage management system is globally disabled: the current database access transaction is ended and (provided transaction reversibility is enabled) rolled back, and all ION tasks terminate.
Otherwise, the ION task that encountered the error is simply aborted, causing a core dump to be produced to support debugging.
SM_SEMKEY=0x*XXXX*
This option overrides the default value (0xee01) of the identifying \"key\" used in creating and locating the global ION shared-memory system mutex.
SVR4_SHM
This option causes ION to be built using svr4 shared memory as the pervasive shared-memory management mechanism. svr4 shared memory is selected by default when ION is built for any platform other than MinGW, VxWorks 5.4, or RTEMS. (For these latter operating systems all memory is shared anyway, due to the absence of a protected-memory mode.)
POSIX1B_SEMAPHORES
This option causes ION to be built using POSIX semaphores as the pervasive semaphore mechanism. POSIX semaphores are selected by default when ION is built for RTEMS but are otherwise not used or supported; this option enables the default to be overridden.
SVR4_SEMAPHORES
This option causes ION to be built using svr4 semaphores as the pervasive semaphore mechanism. svr4 semaphores are selected by default when ION is built for any platform other than MinGW (for which Windows event objects are used), VxWorks 5.4 (for which VxWorks native semaphores are the default choice), or RTEMS (for which POSIX semaphores are the default choice).
SM_SEMBASEKEY=0x*XXXX*
This option overrides the default value (0xee02) of the identifying \"key\" used in creating and locating the global ION shared-memory semaphore database, in the event that svr4 semaphores are used.
SEMMNI=*xxx*
This option declares to ION the total number of svr4 semaphore sets provided by the operating system, in the event that svr4 semaphores are used. It overrides the default value, which is 10 for Cygwin and 128 otherwise. (Changing this value typically entails rebuilding the O/S kernel.)
SEMMSL=*xxx*
This option declares to ION the maximum number of semaphores in each svr4 semaphore set, in the event that svr4 semaphores are used. It overrides the default value, which is 6 for Cygwin and 250 otherwise. (Changing this value typically entails rebuilding the O/S kernel.)
SEMMNS=*xxx*
This option declares to ION the total number of svr4 semaphores that the operating system can support; the maximum possible value is SEMMNI x SEMMSL. It overrides the default value, which is 60 for Cygwin and 32000 otherwise. (Changing this value typically entails rebuilding the O/S kernel.)
ION_NO_DNS
This option causes the implementation of a number of Internet socket I/O operations to be omitted for ION. This prevents ION software from being able to operate over Internet connections, but it prevents link errors when ION is loaded on a spacecraft where the operating system does not include support for these functions.
ERRMSGS_BUFSIZE=*xxxx*
This option set the size of the buffer in which ION status messages are constructed prior to logging. The default value is 4 KB.
SPACE_ORDER=*x*
This option declares the word size of the computer on which the compiled ION software will be running: it is the base-2 log of the number of bytes in an address. The default value is 2, i.e., the size of an address is 2^2^ = 4 bytes. For a 64-bit machine, SPACE_ORDER must be declared to be 3, i.e., the size of an address is 2^3^ = 8 bytes.
NO_SDRMGT
This option enables the SDR system to be used as a data access transaction system only, without doing any dynamic management of non-volatile data. With the NO_SDRMGT option set, the SDR system library can (and in fact must) be built from the sdrxn.c source file alone.
DOS_PATH_DELIMITER
This option causes ION_PATH_DELIMITER to be set to '\\' (backslash), for use in construction path names. The default value of ION_PATH_DELIMITER is '/' (forward slash, as is used in Unix-like operating systems).
"},{"location":"ION-Guide/#build","title":"Build","text":"To build ICI for a given deployment platform:
Decide where you want ION's executables, libraries, header files, etc. to be installed. The ION makefiles all install their build products to subdirectories (named bin, lib, include, man, man/man1, man/man3, man/man5) of an ION root directory, which by default is the directory named /opt. If you wish to use the default build configuration, be sure that the default directories (/opt/bin, etc.) exist; if not, select another ION root directory name -- this document will refer to it as $OPT -- and create the subdirectories as needed. In any case, make sure that you have read, write, and execute permission for all of the ION installation directories and that:
The directory /$OPT/bin is in your execution path.
Edit the Makefile in ion/ici:
Make sure PLATFORMS is set to the appropriate platform name, e.g., x86-redhat, sparc-sol9, etc.
Set OPT to the directory where you want to install the ici packages you build, if other than \"/opt\" (for example: /usr/local).
Then:
cd ion/ici\nsudo make\nsudo make install\nThree types of files are used to provide the information needed to perform global configuration of the ION protocol stack: the ION system configuration (or ionconfig) file, the ION administration command (ionrc) file, and the ION security configuration (ionsecrc) file. For details, see the man pages for ionconfig(5), ionrc(5), and ionsecrc(5) in Appendix A.
Normally the instantiation of ION on a given computer establishes a single ION node on that computer, for which hard-coded values of wmKey and sdrName (see ionconfig(5)) are used in common by all executables to assure that all elements of the system operate within the same state space. For some purposes, however, it may be desirable to establish multiple ION nodes on a single workstation. (For example, constructing an entire self-contained DTN network on a single machine may simplify some kinds of regression testing.) ION supports this configuration option as follows:
sdrWmSize or default. If any later ION instance launched with sdrWmSize exceeding the first ION instance, it will result in crash upon launch. It is further recommended that all ION instances running simultaneously on a single host should set their sdrWmSize the same.The executable programs used in operation of the ici component of ION include:
Each time it is executed, ionadmin computes a new congestion forecast and, if a congestion collapse is predicted, invokes the node's congestion alarm script (if any). ionadmin also establishes the node number for the local node and starts/stops the rfxclock task, among other functions. For further details, see the man pages for ionadmin(1), ionsecadmin(1), rfxclock(1), sdrmend(1), sdrwatch(1), and psmwatch(1) in Appendix A.
"},{"location":"ION-Guide/#test","title":"Test","text":"Six test executables are provided to support testing and debugging of the ICI component of ION:
For details, see the man pages for file2sdr(1), sdr2file(1), psmshell(1), file2sm(1), sm2file(1), and smlistsh(1) in Appendix A.
"},{"location":"ION-Guide/#licklider-transmission-protocol-ltp_1","title":"Licklider Transmission Protocol (LTP)","text":""},{"location":"ION-Guide/#build_1","title":"Build","text":"To build LTP:
Edit the Makefile in ion/ltp:
As for ici, make sure PLATFORMS is set to the name of the platform on which you plan to run LTP.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/ltp\nmake\nsudo make install\nThe LTP administration command (ltprc) file provides the information needed to configure LTP on a given ION node. For details, see the man page for ltprc(5) in Appendix A.
"},{"location":"ION-Guide/#run_1","title":"Run","text":"The executable programs used in operation of the ltp component of ION include:
ltpadmin starts/stops the ltpclock and ltpmeter tasks and, as mandated by configuration, the udplsi and udplso tasks.
For details, see the man pages for ltpadmin(1), ltpclock(1), ltpmeter(1), udplsi(1), and udplso(1) in Appendix A.
"},{"location":"ION-Guide/#test_1","title":"Test","text":"Two test executables are provided to support testing and debugging of the LTP component of ION:
For details, see the man pages for ltpdriver(1) and ltpcounter(1) in Appendix A.
"},{"location":"ION-Guide/#bundle-streaming-service-protocol-bssp","title":"Bundle Streaming Service Protocol (BSSP)","text":""},{"location":"ION-Guide/#build_2","title":"Build","text":"To build BSSP:
Edit the Makefile in ion/bssp:
As for ici, make sure PLATFORMS is set to the name of the platform on which you plan to run BSSP.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/bssp\nmake\nsudo make install\nThe BSSP administration command (bssprc) file provides the information needed to configure BSSP on a given ION node. For details, see the man page for bssprc(5) in Appendix A.
The bssprc file has a command option specifying the max_block_size. This is to prevent retransmission inefficiency when the blocks size of a stream data is too large. The unit of retransmission for BSSP is the block, so if the block size is too large, it is very expensive to the network to provide retransmission. If one needs bulk data transfer, instead of streaming, one should use BP with reliability LTP instead of using BSSP. If you are using udpbso and udpbsi as the underlying convergence layer, then the max_block_size parameter for bssprc cannot be larger than 65507 bytes, because each UDP datagram can only be as large as 65507 bytes (payload) + 20 (IP Header) + 8 (UDP Header) = 65535 byte.
"},{"location":"ION-Guide/#run_2","title":"Run","text":"The executable programs used in operation of the bssp component of ION include:
bsspadmin starts/stops the bsspclock task and, as mandated by configuration, the udpbsi and udblso tasks.
For details, see the man pages for bsspadmin(1), bsspclock(1), bsspmeter(1), udpbsi(1), and udpbso(1) in Appendix A.
"},{"location":"ION-Guide/#bundle-protocol-bp_1","title":"Bundle Protocol (BP)","text":""},{"location":"ION-Guide/#compile-time-options_1","title":"Compile-time options","text":"Declaring values for the following variables, by setting parameters that are provided to the C compiler (for example, --DION_NOSTATS or --DBRSTERM=60), will alter the functionality of BP as noted below.
"},{"location":"ION-Guide/#targetffs","title":"TargetFFS","text":"Setting this option adapts BP for use with the TargetFFS flash file system on the VxWorks operating system. TargetFFS apparently locks one or more system semaphores so long as a file is kept open. When a BP task keeps a file open for a sustained interval, subsequent file system access may cause a high-priority non-BP task to attempt to lock the affected semaphore and therefore block; in this event, the priority of the BP task may automatically be elevated by the inversion safety mechanisms of VxWorks. This \"priority inheritance\" can result in preferential scheduling for the BP task -- which does not need it -- at the expense of normally higher-priority tasks, and can thereby introduce runtime anomalies. BP tasks should therefore close files immediately after each access when running on a VxWorks platform that uses the TargetFFS flash file system. The TargetFFS compile-time option ensures that they do so.
"},{"location":"ION-Guide/#brstermxx","title":"BRSTERM=xx","text":"This option sets the maximum number of seconds by which the current time at the BRS server may exceed the time tag in a BRS authentication message from a client; if this interval is exceeded, the authentication message is presumed to be a replay attack and is rejected. Small values of BRSTERM are safer than large ones, but they require that clocks be more closely synchronized. The default value is 5.
"},{"location":"ION-Guide/#ion_nostats","title":"ION_NOSTATS","text":"Setting this option prevents the logging of bundle processing statistics in status messages.
"},{"location":"ION-Guide/#keepalive_periodxx","title":"KEEPALIVE_PERIOD=xx","text":"This option sets the number of seconds between transmission of keep-alive messages over any TCP or BRS convergence-layer protocol connection. The default value is 15.
"},{"location":"ION-Guide/#ion_bandwidth_reserved","title":"ION_BANDWIDTH_RESERVED","text":"Setting this option overrides strict priority order in bundle transmission, which is the default. Instead, bandwidth is shared between the priority-1 and priority-0 queues on a 2:1 ratio whenever there is no priority-2 traffic.
"},{"location":"ION-Guide/#enable_bpacs","title":"ENABLE_BPACS","text":"This option causes Aggregate Custody Signaling source code to be included in the build. ACS is alternative custody transfer signaling mechanism that sharply reduces the volume of custody acknowledgment traffic.
"},{"location":"ION-Guide/#enable_imc","title":"ENABLE_IMC","text":"This option causes IPN Multicast source code to be included in the build. IMC is discussed in section 1.8.4 above.
"},{"location":"ION-Guide/#build_3","title":"Build","text":"To build BP:
Edit the Makefile in ion/bp:
As for ici, make sure PLATFORMS is set to the name of the platform on which you plan to run BP.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/bp\nmake\nsudo make install\nThe BP administration command (bprc) file provides the information needed to configure generic BP on a given ION node. The IPN scheme administration command (ipnrc) file provides information that configures static and default routes for endpoints whose IDs conform to the \"ipn\" scheme. The DTN scheme administration command (dtn2rc) file provides information that configures static and default routes for endpoints whose IDs conform to the \"dtn\" scheme, as supported by the DTN2 reference implementation. For details, see the man pages for bprc(5), ipnrc(5), and dtn2rc(5) in Appendix A.
"},{"location":"ION-Guide/#run_3","title":"Run","text":"The executable programs used in operation of the bp component of ION include:
bpadmin starts/stops the bpclock task and, as mandated by configuration, the ipnfw, dtn2fw, ipnadminep, dtn2adminep, bpclm, brsscla, brsccla, tcpcli, stcpcli, stcpclo, udpcli, udpclo, ltpcli, ltpclo, and dgrcla tasks.
For details, see the man pages for bpadmin(1),ipnadmin(1), dtn2admin(1), bpclock(1), bpclm(1), ipnfw(1), dtn2fw(1), ipnadminep(1), dtn2adminep(1), brsscla(1), brsccla(1),tcpcli(1), stcpcli(1), stcpclo(1), udpcli(1), udpclo(1), ltpcli(1), ltpclo(1), dgrcla(1), bpsendfile(1), bpstats(1), bptrace(1), lgsend(1), lgagent(1), and hmackeys(1) in Appendix A.
"},{"location":"ION-Guide/#test_2","title":"Test","text":"Five test executables are provided to support testing and debugging of the BP component of ION:
For details, see the man pages for bpdriver(1), bpcounter(1), bpecho(1), bpsource(1), and bpsink(1) in Appendix A.
"},{"location":"ION-Guide/#datagram-retransmission-dgr_1","title":"Datagram Retransmission (DGR)","text":""},{"location":"ION-Guide/#build_4","title":"Build","text":"To build DGR:
Edit the Makefile in ion/dgr:
As for ici, make sure PLATFORMS is set to the name of the platform on which you plan to run DGR.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/dgr\nmake\nsudo make install\nNo additional configuration files are required for the operation of the DGR component of ION.
"},{"location":"ION-Guide/#run_4","title":"Run","text":"No runtime executables are required for the operation of the DGR component of ION.
"},{"location":"ION-Guide/#test_3","title":"Test","text":"Two test executables are provided to support testing and debugging of the DGR component of ION:
For details, see the man pages for file2dgr(1) and dgr2file(1) in Appendix A.
"},{"location":"ION-Guide/#asynchronous-message-service-ams_1","title":"Asynchronous Message Service (AMS)","text":""},{"location":"ION-Guide/#compile-time-options_2","title":"Compile-time options","text":"Note that, by default, the syntax by which AMS MIB information is presented to AMS is as documented in the \"amsrc\" man page. Alternatively it is possible to use an XML-based syntax as documented in the \"amsxml\" man page. To use the XML-based syntax instead, be sure that the \"expat\" XML interpretation system is installed and pass the argument \"--with-expat\" to \"./configure\" when building ION.
Defining the following macros, by setting parameters that are provided to the C compiler (for example, DAMS_INDUSTRIAL), will alter the functionality of AMS as noted below.
AMS_INDUSTRIAL
Setting this option adapts AMS to an \"industrial\" rather than safety-critical model for memory management. By default, the memory acquired for message transmission and reception buffers in AMS is allocated from limited ION working memory, which is fixed at ION start-up time; this limits the rate at which AMS messages may be originated and acquired. When --DAMS_INDUSTRIAL is set at compile time, the memory acquired for message transmission and reception buffers in AMS is allocated from system memory, using the familiar malloc() and free() functions; this enables much higher message traffic rates on machines with abundant system memory.
"},{"location":"ION-Guide/#build_5","title":"Build","text":"To build AMS:
Edit the Makefile in ion/cfdp:
Just as for bp, make sure PLATFORMS is set to the name of the platform on which you plan to run AMS.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed (for example: /usr/local).
Then:
cd ion/ams\nmake\nsudo make install\nThere is no central configuration of AMS; each AMS entity (configuration server, registrar, or application module) is individually configured at the time its initial MIB is loaded at startup. Note that a single MIB may be shared between multiple AMS entities without issue.
For details of MIB file syntax, see the man pages for amsrc(5) and amsxml(5) in Appendix A.
"},{"location":"ION-Guide/#run_5","title":"Run","text":"The executable programs used in operation of the AMS component of ION include:
For details, see the man pages for amsd(1), ramsgate(1), amsstop(1), and amsmib(1) in Appendix A.
"},{"location":"ION-Guide/#test_4","title":"Test","text":"Seven test executables are provided to support testing and debugging of the AMS component of ION:
For details, see the man pages for amsbenchs(1), amsbenchr(1), amshello(1), amsshell(1), amslog(1), amslogprt(1), amspub(1), and amssub(1) in Appendix A.
For further operational details of the AMS system, please see sections 4 and 5 of the AMS Programmer's Guide.
"},{"location":"ION-Guide/#ccsds-file-delivery-protocol-cfdp_1","title":"CCSDS File Delivery Protocol (CFDP)","text":""},{"location":"ION-Guide/#compile-time-options_3","title":"Compile-time options","text":"Defining the following macro, by setting a parameter that is provided to the C compiler (i.e., --DTargetFFS), will alter the functionality of CFDP as noted below.
"},{"location":"ION-Guide/#targetffs_1","title":"TargetFFS","text":"Setting this option adapts CFDP for use with the TargetFFS flash file system on the VxWorks operating system. TargetFFS apparently locks one or more system semaphores so long as a file is kept open. When a CFDP task keeps a file open for a sustained interval, subsequent file system access may cause a high-priority non-CFDP task to attempt to lock the affected semaphore and therefore block; in this event, the priority of the CFDP task may automatically be elevated by the inversion safety mechanisms of VxWorks. This \"priority inheritance\" can result in preferential scheduling for the CFDP task -- which does not need it -- at the expense of normally higher-priority tasks, and can thereby introduce runtime anomalies. CFDP tasks should therefore close files immediately after each access when running on a VxWorks platform that uses the TargetFFS flash file system. The TargetFFS compile-time option ensures that they do so.
"},{"location":"ION-Guide/#build_6","title":"Build","text":"To build CFDP:
Edit the Makefile in ion/cfdp:
Just as for bp, make sure PLATFORMS is set to the name of the platform on which you plan to run CFDP.
Set OPT to the directory containing the bin, lib, include, etc. directories where the ici package is installed.
Then:
cd ion/cfdp\n\nmake\n\nmake install\nThe CFDP administration command (cfdprc) file provides the information needed to configure CFDP on a given ION node. For details, see the man page for cfdprc(5) in Appendix A.
"},{"location":"ION-Guide/#run_6","title":"Run","text":"The executable programs used in operation of the CFDP component of ION include:
cfdpadmin starts/stops the cfdpclock task and, as mandated by configuration, the bputa task.
For details, see the man pages for cfdpadmin(1), cfdpclock(1), and bputa(1) in Appendix A.
"},{"location":"ION-Guide/#test_5","title":"Test","text":"A single executable, cfdptest, is provided to support testing and debugging of the DGR component of ION. For details, see the man page for cfdptest(1) in Appendix A.
"},{"location":"ION-Guide/#bundle-streaming-service-bss_1","title":"Bundle Streaming Service (BSS)","text":""},{"location":"ION-Guide/#compile-time-options_4","title":"Compile-time options","text":"Defining the following macro, by setting a parameter that is provided to the C compiler (e.g., --DWINDOW=10000), will alter the functionality of BSS as noted below.
"},{"location":"ION-Guide/#windowxx","title":"WINDOW=xx","text":"Setting this option changes the maximum number of seconds by which the BSS database for a BSS application may be \"rewound\" for replay. The default value is 86400 seconds, which is 24 hours.
"},{"location":"ION-Guide/#build_7","title":"Build","text":"To build BSS:
cd ion/bss\n\nmake\n\nsudo make install\nNo additional configuration files are required for the operation of the BSS component of ION.
"},{"location":"ION-Guide/#run_7","title":"Run","text":"No runtime executables are required for the operation of the BSS component of ION.
"},{"location":"ION-Guide/#test_6","title":"Test","text":"Four test executables are provided to support testing and debugging of the BSS component of ION:
For details, see the man pages for bssdriver(1), bsscounter(1), bssStreamingApp(1), and bssrecv(1) in Appendix A.
In ION, reliable convergence-layer protocols (where available) are by default used for every bundle. The application can instead mandate selection of \"best-effort\" service at the convergence layer by setting the BP_BEST_EFFORT flag in the \"extended class of service flags\" parameter, but this feature is an ION extension that is not supported by other BP implementations at the time of this writing.\u00a0\u21a9
Note that, in all occupancy figures, ION data management accounts not only for the sizes of the payloads of all queued bundles but also for the sizes of their headers.\u00a0\u21a9
Barring data loss or corruption for which the various retransmission mechanisms in ION cannot compensate.\u00a0\u21a9
Note that ION may indeed block the offering of a message to the network, but this is local admission control -- assuring that the node's local buffer space for queuing outbound bundles is not oversubscribed -- rather than end-to-end flow control. It is always possible for there to be ample local buffer space yet insufficient network capacity to convey the offered data to their final destination, and vice versa.\u00a0\u21a9
The minimum size of an ION bundle header is 26 bytes. Adding extension blocks (such as those that effect the Bundle Security Protocol) will increase this figure.\u00a0\u21a9
In ION, all bundles are by default non-critical. The application can indicate that data should be sent in a Critical bundle by setting the BP_MINIMUM_LATENCY flag in the \"extended class of service\" parameter, but this feature is an ION extension that is not supported by other BP implementations at the time of this writing.\u00a0\u21a9
If we wanted to be extremely accurate we could also subtract from the timeout interval the imputed inbound queuing delay QI, since inbound queuing would presumably be completed during the interval in which transmission was suspended. But since we're guessing at the queuing delays anyway, this adjustment doesn't make a lot of sense.\u00a0\u21a9
Last Updated: 12/27/2023
Previous versions of ION required a good understanding of the different ION adminstrative programs, how to write RC files from them, and what the different configuration commands mean.
The ionlauncher was developed to ease the user into ION configuration by taking a few parameters that mission designer would likely know when planning a network. Using those parameters, captured in a simple JSON format, an entire ION network with defined configurations files can be created and started rather quickly.
This section will outline the necessary parameters needed to create a simple model for ionlauncher.
There are seven parameters that are needed to define a simple network model. They are as follows:
NAME: serves as the key for the other parameters and naming start scripts\nIP ADDRESS: Host IP address or domain name the node will be running on\nNODE: assigned node number, will be used for addressing with neighbor(s)\nSERVICES: Applications running on the node, currently supports CFDP, AMS, & AMP\nDEST: node's neighbor(s)\nPROTOCOL: convergance layer to reach a neighbor. Currently supported options include LTP, TCP, UDP, and STCP. \n (untested options: BSSP & DCCP)\nRATE: Data rate used to communicate with neighbor(s), in bytes/s\nThere are a few example models included with the ionlauncher prototype under example_models/. This section shows one of them and explains how it works.
{\n \"SC\": {\n \"IP\": \"192.168.1.115\",\n \"NODE\": 21,\n \"SERVICES\": [],\n \"DEST\": [\n \"Relay\"\n ],\n \"PROTOCOL\": [\n \"ltp\"\n ],\n \"RATE\": [\n 100000\n ]\n },\n \"Relay\": {\n \"IP\": \"192.168.1.114\",\n \"NODE\": 22,\n \"SERVICES\": [],\n \"DEST\": [\n \"SC\",\n \"GS\"\n ],\n \"PROTOCOL\": [\n \"ltp\",\n \"tcp\"\n ],\n \"RATE\": [\n 10000,\n 2500000\n ]\n },\n \"GS\": {\n \"IP\": \"192.168.1.113\",\n \"NODE\": 23,\n \"SERVICES\": [],\n \"DEST\": [\n \"Relay\"\n ],\n \"PROTOCOL\": [\n \"tcp\"\n ],\n \"RATE\": [\n 2500000\n ]\n }\n}\nThis is an example of a three node setup where Relay serves as a DTN relay between SC and GS. Order is important in the lists for DEST, PROTOCOL, and RATE. They assume each element in the lists correspond to each other. For example, Relay communicates with SC via LTP at 10,000 bytes/s and Relay communicates with GS via TCP at 2,500,000 bytes/s.
There are other two examples included with ionlaucher. The first is a simple two node setup over TCP. The second is a four node scenario where SC can only uplink to Relay1 and downlink from Relay2, while GS has continuous coverage of the two relays.
Ionlauncher is currently a prototype and may not be installed globally. Please make sure that both ionlauncher and net_model_gen in the demo folder has been copied to the execution path of ION, which is typically /usr/local/bin or something specified as part of the ./configure script during initial ION installation.
Ionlauncher's simple network model file current does not handle multi-network interface configuration - this will be updated for ION 4.1.4.
"},{"location":"ION-Launcher/#usage","title":"Usage","text":"This section will outline how to run ionlauncher and what the different parameters mean. It is assumed ionlauncher will be run on each host independently with the same simple model and the only parameter changing is the node name.
ionlauncher [-h] -n <node name> -m <simple model file> [-d <ionconfig cli directory>]
-h: display help\n-n: node name that will be used to start ION on the host\n-m: path to simple model file, ionlauncher assumes the file \n is in the same directory or a directory below\n-d: optional parameter that defines the path to the ION Config \n tool CLI scripts, default is /home/$USER/ionconfig-4.8.1/cli/bin\nOnce the ION configuration files have been generate. ION will be started using the configuration files for the node passed via -n. Stopping the node is done via ionstop and if that hangs or errors out, killm can be used to force stop ION processes. To restart ION, ionlauncher can be used again, but this will overwrite the configuration files and wipe out any customization that has been added to the initial set of configuration files generated from previous run. If you did not add any customization, it is perfectly find to launch ION again in the same way. If you did make changes, then it is recommended that you use the start script in the node's working directory, ./start_{node_name}.sh to start ION.
The ionlauncher and associated net_model_gen python scripts will be installed in the same install path for ION, therefore making them available for use from any working directory.
For example, say the 3 node simple file is called 3node.json and it is stored at directory $WKDIR. After cd into the working directory and executing the ionlauncher, a new directory $WKDIR/3node-ion will be created and it contains the following:
-ion.json. In this case, it will be called 3node-ion.json. This file can be opened and edited by the ION Config Tool's browser-based GUI-net_model.json. In this case, it will be called 3node-net_model.json. This file can be opened and edited by the ION Network Model's browser-based GUI.$WKDIR/3node/SC, $WKDIR/3node/Relay, and $WKDIR/3node/GSstart_<node name>.sh, that you can use to launch ION again.After the initial ionlauncher run, the ION configuration files are generated for you based on the simple network model description and a set of default settings. To activate additional features, optimize parameters settings, and refine protocol behaviors, you will need to edit the ION config files individually. For those changes to take effect, you need to stop ION and restart ION using the start script in each node's working folder.
NOTE: If you run ionlauncher again, the ION configuration files will regenerate and over-write your custom changes. So it is recommended that you make a copy or rename the configuration to avoid this situation.
"},{"location":"ION-Launcher/#dependency","title":"Dependency","text":"The ionlaunch script requires that the installation of the ION Config Tool, which is publically accessible (starting January 2024) from GitHub, and the companion tool called ION Network Model is also available for download, although it is not needed for using ionlauncher.
Download the latest release of the ION Config Tool and note the directory of the CLI (command line interface executables). For example, if it is /home/$USER/ionconfig-4.8.1/cli/bin, then you don't need to provide the -d option to ionlauncher. If it is somewhere else, then you should provide the -d option.
You also need to install node.js and make sure python version 3.6 or higher is available in your system.
To build and install the entire ION system on a Linux, MacOS, or Solaris platform, cd into ion-open-source and enter the following commands:
./configure
If configure is not present run: autoreconf -fi first
make
sudo make install
sudo ldconfig
For MacOS, the ldconfig command is not present and not necessary to run.
If you want to set overriding compile-time switches for a build, the place to do this is in the ./configure command. For details,
./configure -h
By default, Bundle Protocol V7 will be built and installed, but BPv6 source code is still available. The BPv6 implementation is essentially the same as that of ION 3.7.4, with only critical bugs being updated going forward. All users are encouraged to switch to BPV7.
To build BPv6, run
./configure --enable-bpv6
To clean up compilation artifacts such as object files and shared libraries stored within the ION open-source directory, cd to the ION open-source directory and run:
make clean
To remove executables and shared libraries installed in the system, run:
sudo make uninstall
To install ION for Windows, please download the Windows installer.
"},{"location":"ION-Quick-Start-Guide/#build-individual-packages","title":"Build Individual Packages","text":"It's also possible to build the individual packages of ION, using platform-specific Makefiles in the package subdirectories. Currently the only actively maintained platform-specific Makefile is for 64-bits Linux under the \"i86_48-fedora\" folder. If you choose this option, be aware of the dependencies among the packages:
make and make install) before any other package.For more detailed instruction on building ION, see section 2 of the \"ION Design and Operation Guide\" document that is distributed with this package.
Also, be aware that these Makefiles install everything into subdirectories of /usr/local. To override this behavior, change the value of OPT in the top-level Makefile of each package.
Additional details are provided in the README.txt files in the root directories of some of the subsystems.
Note that all Makefiles are for gmake; on a FreeBSD platform, be sure to install gmake before trying to build ION.
"},{"location":"ION-Quick-Start-Guide/#running-ion","title":"Running ION","text":""},{"location":"ION-Quick-Start-Guide/#check-installed-bp-and-ion-versions","title":"Check Installed BP and ION versions","text":"Before running ION, let's confirm which version of Bundle Protocol is installed by running:
bpversion
You will see a simple string on the terminal windows indicating either \"bpv6\" or \"bpv7\".
Also check the ION version installed by running:
ionadmin
At the \":\" prompt, please enter the single character command 'v' and you should see a response like this:
$ ionadmin\n: v\nION-OPEN-SOURCE-4.1.2\nThen type 'q' to quit ionadmin. While ionadmin quits, it may display certain error messages like this:
at line 427 of ici/library/platform_sm.c, Can't get shared memory segment: Invalid argument (0)\nat line 312 of ici/library/memmgr.c, Can't open memory region.\nat line 367 of ici/sdr/sdrxn.c, Can't open SDR working memory.\nat line 513 of ici/sdr/sdrxn.c, Can't open SDR working memory.\nat line 963 of ici/library/ion.c, Can't initialize the SDR system.\nStopping ionadmin.\nThis is normal due to the fact that ION has not launched yet.
"},{"location":"ION-Quick-Start-Guide/#try-the-bping-test","title":"Try the 'bping' test","text":"The tests directory contains regression tests used by system integrator to check ION before issuing each new release. To make sure ION is operating properly after installation, you can also manually run the bping test:
First enter the test directory: cd tests
Enter the command: ./runtests bping/
This command invokes one of the simplest test whereby two ION instances are created and a ping message is sent from one to the other and an echo is returned to the sender of the ping.
During test, ION will display the configuration files used, clean the system of existing ION instances, relaunch ION according to the test configuration files, execute bping actions, display texts that indicates what the actions are being executed in real-time, and then shutdown ION, and display the final test status message, which looks like this:
ION node ended. Log file: ion.log\nTEST PASSED!\n\npassed: 1\n bping\n\nfailed: 0\n\nskipped: 0\n\nexcluded by OS type: 0\n\nexcluded by BP version: 0\n\nobsolete tests: 0\nIn this case, the test script confirms that ION is able to execute a bping function properly.
"},{"location":"ION-Quick-Start-Guide/#try-to-setup-a-udp-session","title":"Try to Setup a UDP Session","text":"Under the demos folder of the ION code directory, there are benchmark tests for various ION configurations. These tests also provide a template of how to configure ION.
Take the example of the bench-udp demo:
Go into the demos/bench-udp/ folder, you will see two subfolders: 2.bench.udp and 3.bench.udp, these folders configures two ION nodes, one with node numbers 2 and 3.
Looking inside the 2.bench.udp folder, you will see specific files used to configure ION. These include:
bench.bprc \nbench.ionconfig \nbench.ionrc \nbench.ionsecrc \nbench.ipnrc \nionstart \nionstop\nbench.bprc is the configuration file for the bundle protocol. To study the command options contained in this file, run man bprc.bench.ionconfig is the configuration file for the storage configuration of ION. See man ionconfig for details.bench.ionrc is the configuration file for ION. See man ionrc for details.bench.ionsecrc is the configuration file for ION security administration. See man ionsecrc for details.bench.ipnrc is the configuration file for the IPN scheme. See man ipnrc for details.ionstart and ionstop are scripts to launch and shutdown ION.One must note that ION distribution comes with a separate, global ionstart and ionstop scripts installed in /usr/local/bin that can launch and stop ION. The advantage of using local script is that it allows you customize the way you launch and stop ION, for example add helpful text prompt, perform additional checks and clean up activities, etc.
To run this demo test, first go into the test directory bench-udp, then run the dotest script:
./dotest
You can also study the test script to understand better what is happening.
"},{"location":"ION-Quick-Start-Guide/#running-multiple-ion-instances-on-a-single-host","title":"Running multiple ION instances on a single host","text":"If you study the test script under the \"tests\" and the \"demos\" folders, you will realize that these tests often will launch 2 or 3 ION nodes on the same host to conduct the necessary tests. While this is necessary to simplify and better automate regression testing for ION developer and integration, it is not a typical, recommended configuration for new users.
In order to run multiple ION instances in one host, specific, different IPCS keys must be used for each instance, and several variables must be set properly in the shell environment. Please see the ION Deployment Guide (included with the ION distribution) for more information on how to do that.
We recommend that most users, unless due to specific contrain that they must run multiple ION instance on one host, to run each ION instance on a separate host or (VM).
"},{"location":"ION-Quick-Start-Guide/#setup-udp-configuration-on-two-hosts","title":"Setup UDP Configuration on Two Hosts","text":"Once you have studied these scripts, you can try to run it on two different machines running ION.
First, install ION in host A with an IP address of, for example, 192.168.0.2, and host B with an IP address of 192.168.0.3. Verify your installation based on earlier instructions.
Copy the 2.bench.udp folder into host A and the 3.bench.udp folder into host B.
Also copy the file global.ionrc from the bench.udp folder into the same folder where you placed 2.bench.udp and 3.bench.udp
Then you need to modify the IP addresses in the UDP demo configuration files to match the IP addresses of hosts A and B.
For example, the bprc files copied into host A is:
1\na scheme ipn 'ipnfw' 'ipnadminep'\na endpoint ipn:2.0 x\na endpoint ipn:2.1 x\na endpoint ipn:2.2 x\na endpoint ipn:2.64 x\na endpoint ipn:2.65 x\na protocol udp 1400 100\na induct udp 127.0.0.1:2113 udpcli\na outduct udp 127.0.0.1:3113 'udpclo 1'\nr 'ipnadmin bench.ipnrc'\ns\nTo make it work for host A, you need to replace the induct ip address 127.0.0.1:2113 to 192.168.0.2:2113 - this is where host A's ION will receive incoming UDP traffic.
Similarly for outduct, you want to change the ip address from 127.0.0.1:3113 to 192.168.0.3:3113 - this is where UDP traffic will go out to host B.
You can make similar modifications to the ipnrc file as well.
In the ionconfig file, you want to comment out or delete the wmKey and sdrName entries. Since we are running these two nodes on different hosts, we always let ION use the default values for these parameters.
If you don\u2019t do this you get an error on startup.
Repeat the same updates for host B by appropriately substituting old IP address to that of the new hosts.
"},{"location":"ION-Quick-Start-Guide/#launch-ion-on-two-separate-hosts","title":"Launch ION on two separate hosts","text":"After updating the configuration files on host A and B to reflect the new IP addresses and using default wmKey (by not specifying any), we are new ready to try launching ION.
Before you try to launch ION, it is recommended that you:
global.ionrc file, change the data rates for the a contact command down to something similar to your connection speed. Remember, the unit in the global.ionrc file is Bytes per second, not bits per second, which is typically what iperf test report uses.Once you are ready to launch ION on both host A and B, open a terminal and go to the directory where the configuration files are stored, and run the local ionstart script:
./ionstart
Note: do not run ionstart since that will trigger the global script in the execution PATH
You should see some standard output confirming that ION launch has completed. For example you might see something like this:
Starting ION...\nwmSize: 5000000\nwmAddress: 0\nsdrName: 'ion2'\nsdrWmSize: 0\nconfigFlags: 1\nheapWords: 100000000\nheapKey: -1\nlogSize: 0\nlogKey: -1\npathName: '/tmp'\nStopping ionadmin.\nStopping ionadmin.\nStopping ionsecadmin.\nStopping ltpadmin.\nStopping ipnadmin.\nStopping bpadmin.\nYou can also see additional status information in the ion.log file in the same directory.
Launch ION on both host A and B.
"},{"location":"ION-Quick-Start-Guide/#run-a-bpdriver-bpcounter-test","title":"Run a bpdriver-bpcounter test","text":"Now that we have launched ION on both host A and B, it's time to send some data.
We can repeat the bping test at this point. But since you have already seen that before, let's try something different.
Let's use the bpdriver-bpcounter test utilities. This pair of utility programs simply sends a number of data in bundles from one node to another and provides a measurement on the throughput.
On host B, run this command:
bpcounter ipn:3.2 3
This command tells ION node number 3 to be ready to receive three bundles on the end-point ID ipn:3.2 which was specified in the .bprc file.
After host B has launched bpcounter, then on host A, run this command:
bpdriver 3 ipn:2.2 ipn:3.2 -10000
This command tells ION running in host A to send 3 bundles from EID 2.2 to EID 3.2, which is waiting for data (per bpcounter command.) And each bundle should be 10,000 bytes in size.
Why use the \"-\" sign in front of the size parameter? It's not a typo. The \"-\" indicates that bpdriver should keep sending bundles without waiting for any response from the receiver. The feature where bpdriver waits for the receiver is available in BPv6 but no longer part of BPv7.
When the test completed, you should see output indicating that all the data were sent, how many bundles were transmitted/received, and at what rate.
Please note that on the sending side the transmission may appear to be almost instantaneous. That is because bpdriver, as an application, is pushing data into bundle protocol which has the ability to rate buffer the data. So as soon as the bpdriver application pushes all data into the local bundle protocol agent, it considers the transmission completed and it will report a very high throughput value, one that is far above the contact graph's data rate limit. This is not an error; it simple report the throughput as experienced by the sending application, knowing that the data has not yet delivered fully to the destination.
Throughput reported by bpcounter, on the other hand, is quite accurate if a large number of bundles are sent. To accurately measure the time it takes to send the bundles, bpdriver program will send a \"pilot\" bundle just before sending the test data to signals to the bpcounter program to run its throughput calculation timer. This allows the user to run bpcounter and not haveing to worry about immediately send all the bundles in order to produce an accurate throughput measurement.
If you want to emulate the action of a constant rate source, instead of having bpdriver pushing all data as fast as possible, then you can use the 'i' option to specify a data rate throttle in bits per second.
If you want to know more about how bpdriver and bpcounter work, look up their man pages for details on syntax and command line options. Other useful ION test utility commands include bpecho, bping, bpsource, bpsink, bpsendfile, bprecvfile, etc.
To confirm whether ION is running properly or has experienced an error, the first thing to do is to check the ion.log, which is a file created in the directory from which ION was launched. If an ion.log file exists when ION starts, it will simply append additional log entries into that file. Each entry has a timestamp to help you determine the time and the relative order in which events occurred.
When serious error occurs, ion.log will have detailed messages that can pinpoint the name and line number of the source code where the error was reported or triggered.
"},{"location":"ION-Quick-Start-Guide/#bpacq-and-ltpacq-files","title":"bpacq and ltpacq files","text":"Sometimes after operating ION for a while, you will notice a number of files with names such as \"bpacq\" or \"ltpacq\" followed by a number. These are temporary files created by ION to stage bundles or LTP blocks during reception and processing. Once a bundle or LTP block is completely constructed, delivered, or cancelled properly, these temporary files are automatically removed by ION. But if ION experiences an anomalous shutdown, then these files may remain and accumulate in the local directory.
It is generally safe to remove these files between ION runs. Their presence does not automatically imply issues with ION but can indicate that ION operations were interrupted for some reason. By noting their creation time stamp, it can provide clues on when these interruptions occurred. Right now there are no ION utilty program to parse them because these files are essentially bit buckets and do not contain internal markers or structure and allows user to parse them or extract information by processes outside the bundle agents that created them in the first place.
"},{"location":"ION-Quick-Start-Guide/#forced-shutdown-of-ion","title":"Forced Shutdown of ION","text":"Sometimes shutting down ION does not go smoothly and you can't seem to relaunch ION properly. In that case, you can use the global ionstop script (or the killm script) to kill all ION processes that did not terminate using local ionstop script. The global ionstop or killm scripts also clears out the IPC shared memory and semaphores allocations that were locked by ION processes and would not terminate otherwise.
To learn about the configuration files and the basic set of command syntax and functions: ION Config File Tutorial
"},{"location":"ION-Quick-Start-Guide/#ion-configuration-file-template","title":"ION Configuration File Template","text":"ION Config File Template
"},{"location":"ION-Quick-Start-Guide/#ion-nasa-course","title":"ION NASA Course","text":"To learn more about the design principle of ION and how to use it, a complete series of tutorials is available here: NASA ION Course
The ION Dev Kit mentioned in the NASA ION Course had been deprecated. However, some additional helpful files can be found here to complete the examples: Additional DevKit Files
"},{"location":"ION-Quick-Start-Guide/#accessing-ion-open-source-code-repository","title":"Accessing ION Open-Source Code Repository","text":""},{"location":"ION-Quick-Start-Guide/#releases","title":"Releases","text":"Use the Summary or the Files tab to download point releases
"},{"location":"ION-Quick-Start-Guide/#using-the-code-repository","title":"Using the code repository","text":"If you plan to contribute to the ION project, please keep these in mind:
The NASA team will review these contributions and determine to either
incorporate the code into the baseline, or
Generate a pull request (called Merge Request on Source Forge) with
Your feature or bugfix branch as the Source branch
The tests directory under ION's root folder contains the test suite. Each test lives in its own subdirectory of this directory. Each test is conducted by a script $TESTNAME/dotest. Another directory that contains ION tests is the demos directory, which includes examples of ION configurations using different convergence layers. For this document, we focus on the usage of the tests directory.
Exclude files are hidden files that allow for tests to be disabled based on certain conditions that may cause the test not to run correctly. If an exclude file exists, it should have a short message about why the test has been excluded.
Exclude files can exist in any of the following formats:
.exclude_OS-TYPE: Disables a test for an operating system that it does not run successfully on. Acceptable values to fill in for OS-TYPE are \"windows\", \"linux\", \"mac\", and \"solaris\".
.exclude_BP-VERSION: Disables a test for a version of the bundle protocol that it does not run correctly or does not make sense with. As of ION 4.0.0, the acceptable values to fill in for BP-VERSION are \"bpv6\" and \"bpv7\".
.exclude_all: Disables a test for all platforms.
.exclude_expert: Disables a test because of additional utilities that are required for the test. To work around this exclusion if you want to run an expert test, you can set ION_RUN_EXPERT=\"yes\" in your shell environment to enable all ION tests classified as expert.
.exclude_cbased: Disables a test that relies on compiling a C program to generate the dotest executable script. To exclude C-based tests, you need to define the environment variable ION_EXCLUDE_CBASED.
The tests are run by running make test-all in the top-level directory, or by running runtests in this directory.
An individual test can also be run: ./runtests <test_name>
A file defining a set of tests can be run with runtestset. The arguments to runtestset are files that contain globs of tests to run, for example: ./runtestset quicktests.
A test directory must contain an executable file named dotest. If a directory does not contain this, the test will be ignored. The dotest program should execute the test, possibly reporting runtime information on stdout and stderr, and indicate by its return value the result of the test as follows:
0: Success\n1: Failure\n2: Skip this test\nThe test program starts without the ION stack running. The test program is responsible for starting ION in the ways that is appropriate for the test.
The test program must stop the ION protocol stack before returning.
"},{"location":"ION-TestSet-Readme/#the-test-environment","title":"The test environment","text":"The dotest scripts are run in their test directory. The following environment variables are set as part of the test environment:
IONDIR is the root of the local ION source directory.
PATH begins with IONDIR (this is where the local executables are found.)
The runtests script maintains a file called tests/progress that gives the start time, finish time, and final result for each test.
If the environment variable RUNTESTS_OUTPUTDIR is set, as in, export RUNTESTS_OUTPUTDIR=\"/tmp\", then the output from each test will be stored in /tmp/results, which makes it much easier to find particular text or results when debugging.
The follow tutorials will help you get started with the ION BP Suite:
Note: These presentations/videos were released in 2020 and has not been updated since then. Some technical details and reference materials may be outdated. Please consult the latest man pages and released documentations.
"},{"location":"ION-Utilities/","title":"ION Utility Programs","text":"Here is a short list of utility programs that comes with ION that are frequently used by users launch, stop, and query ION/BP operation status:
ionexit - A program that shuts down ION with the option to preserve the SDR.Normally, when ION's various daemons were stopped down by calling ionstop, issuing the command '.' to the administration programs, the SDR will be modified/destroyed in the process. Calling ionexit with an argument 'keep' allows the SDR state just prior to the execution of ionexit to be preserved in the non-volatile storage such as a file if ION was configured to use a file for the SDR.
ION Version: 4.1.3
Bundle Protocol Version:7
Watch characters, when activated, provide immediate feedback on ION operations by printing various characters standard output (terminal). By examing the watch characters, and the order in which they appear, operators can quickly confirm proper operation or detect configuration or run-time errors.
This document will list all watch characters currently supported by ION.
"},{"location":"ION-Watch-Characters/#enhanced-watch-characters-ion-413-or-later","title":"Enhanced Watch Characters (ION 4.1.3 or later)","text":"Enhanced watch characters were added ION 4.1.3 to provide detailed state information at Bundle Protocol (BP) and LTP levels and can be activated at compile time by:
./configure --enable-ewchar\nor \n./configure CFLAGS=-DEWCHAR\nEnhanced watch characters prepends additional state information to the standard watch characters inside a pair of parenthesis. In this document, we use the following notion regarding enhanced watch characters information.
nnn = source node numbersss = service numberttt = bundle creation time in milliseconds Epoch(2000)ccc = bundle sequence numberxxx (LTP session number)Each field can be longer or shorter than 3 digits/characters.
"},{"location":"ION-Watch-Characters/#logging-and-processing-of-watch-characters","title":"Logging and Processing of Watch Characters","text":"Besides real-time monitoring of the watch characters on standard out, ION can redirect the watch characters to customized user applications for network monitoring purposes.Prior to and including ION 4.1.2, watch characters are single character. Starting from ION 4.1.3 release, a watch character is now generalized to a string of type char*.
To activate customized processing, there are two steps:
gdswatcher.c that defines a functions to process watch characters, and pass that function to ION to handle watch character:static void processWatchChar(char* token)\n{\n //your code goes here\n} \n\nstatic void ionRedirectWatchCharacters()\n{ \n setWatcher(processWatchChar);\n}\n./configure --enable-ewchar CFLAGS=\"-DGDSWATCHER -I/<path to the folder holding the gdswatcher.c file>\"\n./configure --enable-ewchar CFLAGS=\"-DGDSWATCHER -DGDSLOGGER -I/<path to the folder holding the gdswatcher.c file>\"\na - new bundle is queued for forwarding; (nnn,sss,tttt,cccc)a
b - bundle is queued for transmission; (nnn,sss,ccc)b
c - bundle is popped from its transmission queue; (nnn,sss,ccc)c
m - custody acceptance signal is received
w - custody of bundle is accepted
x - custody of bundle is refused
y - bundle is accepted upon arrival; (nnn,sss,tttt,ccc)y
z - bundle is queued for delivery to an application; (nnn,sss,tttt,ccc)z
~ - bundle is abandoned (discarded) on attempt to forward it; (nnn,sss,ccc)~
! - bundle is destroyed due to TTL expiration; (nnn,sss,ccc)!
& - custody refusal signal is received
# - bundle is queued for re-forwarding due to CL protocol failure; (nnn,sss,ccc)#
j - bundle is placed in \\\"limbo\\\" for possible future re-forwarding; (nnn,sss,ccc)j
k - bundle is removed from \\\"limbo\\\" and queued for re-forwarding; (nnn,sss,ccc)k
d - bundle appended to block for next session
e - segment of block is queued for transmission
f - block has been fully segmented for transmission; (xxxx)f
g - segment popped from transmission queue;
(cpxxx)g -- checkpoint, this could be a data segment or a standalone check point
(dsxxx)g -- non-check point data segment
(rcpxxx)g -- retransmitted checkpoint(prsxxx)g -- positive report (all segments received)(nrsxxx)g -- negative report (gaps)(rrsxxx)g -- retransmitted report (either positive or negative)(rasxxx)g -- a report ack segment(csxxx)g -- cancellation by block source(crxxx)g -- cancellation by block receiver(caxxx)g -- cancellation ack for either CS or CRh - positive ACK received for block, session ended; (xxx)h
s - segment received
t - block has been fully received
@ - negative ACK received for block, segments retransmitted; (xxx)@
= - unacknowledged checkpoint was retransmitted; (xxx)=
+ - unacknowledged report segment was retransmitted; (xxx)+
{ - export session canceled locally (by sender)
} - import session canceled by remote sender
[ - import session canceled locally (by receiver)
] - export session canceled by remote receiver
w - custody request is accepted (by receiving entity)
m - custody acceptance signal is received (by requester)
x - custody of bundle has been refused
& - custody refusal signal is received (by requester)
$ - bundle retransmitted due to expiration of custody request timer
D - bssp send completed
E - bssp block constructed for issuance
F - bssp block issued
G - bssp block popped from best-efforts transmission queue
H - positive ACK received for bssp block, session ended
S - bssp block received
T - bssp block popped from reliable transmission queue
- - unacknowledged best-efforts block requeued for reliable transmission
* - session canceled locally by sender
Here is a list of known issues that will updated on a regular basis to captures various lessons-learned relating to the configurations, testing, performance, and deployment of ION:
"},{"location":"Known-Issues/#convergence-layer-adaptor","title":"Convergence Layer Adaptor","text":""},{"location":"Known-Issues/#udp-cla","title":"UDP CLA","text":"root. This sometimes leads to build and test errors when one switches back to the host's development and testing environment. Therefore, we recommend that you execute the make clean and git stash command to remove all build and testing artifacts from ION 's source directory before exiting the container.In the Licklider Transmission Protocol (LTP) Specification issued by CCSDS 734.1-B-1, the elements of a LTP architecture is shown as follows:
The LTP Engine and MIB is implemented and configured by ION, and the Client Service Instance is either BPv6 or BPv7. The storage is provided by the host system through the ICI APIs.
The Underlying Communication Protocol element is responsible for data and control message exchanges between two peered LTP Engines. It is not responsible for flow control, error correction/detection, and in-ordered delivery.
For a spacecraft, the LTP Engine will execute the LTP protocol logic and handing the LTP segments to the underlying communication services provided in the form of a simple UDP socket or a radio frequency/optical telecommunication system. In ION, the standard underlying communications protocol is UDP since it is widely available in terrestrial computer systems. In actual deployment, the UDP protocol may need to be substituted by a different ground-based or flight communications system.
In the document we describe a few essential APIs for any externally implemented underlying communication protocols to interface with LTP engine and perform the most basic tasks of (a) submitting a received LTP segments to the LTP Engine for processing and (b) acquiring an LTP segment from the LTP Engine for transmission to its peer.
"},{"location":"LTP-UComm-API/#connecting-to-the-ltp-engine","title":"Connecting to the LTP Engine","text":"There are several steps for an external application to connecting to LTP:
.ltprc file processed ltpadmin. See the Configuration File Tutorial to understand how BP and LTP services are instantiated.ltprc for more details.ltpInit() API.ltpInit called returned successfully, it must obtain access to ION SDR and detemine the associated LTP span (based on a peer engine number) for which communication service will be provisioned. This is done by using the findSpan() API. A span defines the communication parameters between two LTP engine peers.ltpDequeueOUtboundSegment API to acquire each available segment from the LTP Engine for transmission to the peer entity.In the following section we will describe the private APIs used by the underlying communication protocols. There are other APIs for external processes to use LTP as a reliable point-to-point data transmission service, but they are not described in this document; they are available in the manual pages.
"},{"location":"LTP-UComm-API/#ltp-data-structure","title":"LTP Data Structure","text":"Here is a diagram of the major LTP data structures and their relationships.
+----------------------------------+----------------------------------+\n| | |\n| non->olatile (SDR heap) | volatile (working memory ION) |\n| | |\n| | |\n| LtpDB | LtpVdb |\n| + (list) | + (list) |\n| +---> spans +--+ | +-----+ spans+------+ |\n| | | | | | |\n| +---> seats +---------+ | +-----+ seats+---+ | |\n| | | | | | |\n| | | | | | |\n| LtpSpan <--------+ | | LtpVspan <----------+ |\n| + | | + | |\n| +---> importSessions+----+ | +-> importSessions+--+ |\n| | (list) | | | (list) | | |\n| +---> exportSessions+------+ | | | |\n| | | | | LtpVseat <-------+ | |\n| LtpSeat <---------------+ | | | | |\n| | | | | |\n| | | | | |\n| LtpImportSession <---------+ | | LtpVImportSession<-----+ |\n| | | |\n| | | |\n| LtpExportSession <-----------+ | |\n| | |\n+----------------------------------+----------------------------------+\nLtpDB: The LTP database is a global database that contains the LTP configuration information for the entire system. It is a persistent data stored in the SDR's heap - assuming the SDR is implemented in a non-volatile medium such as a disk or a battery backed RAM.
LtpSpan: A span is a communication channel between two LTP engine peers. A span is defined by a unique span number and a set of communication parameters stored in a non-volatile database. Each instance of LtpSpan is tracked as an element in the LTP database under the LtpDB.spans list.
LtpSeat: A seat is the reception process for LTP and its parameters are stored under LtpSeat, and its tracked as an element in the list LtpDB.seats.
LtpImportSession and LtpExportSession are tracked by lists in the LtpSpan structure.
LtpVdb: The LTP volatile database is a global database that contains the LTP configuration information for the entire system. It is a volatile data stored in the working memory and not expected to persist through power reset. It tracks, in two lists, each instance of LtpVspan and LtpVseat that are currently active.
LtpVspan: contains the state information of an active span in the working memory. It is tracked as an element in the list LtpVdb.spans.
LtpVseat: contains the state information of an active seat in the working memory. It is tracked as an element in the list LtpVdb.seats.
LtpVImportSession: contains the state information of an active import session in the working memory. It is tracked as an element in the list LtpVspan.importSessions.
#include \"ltpP.h\"\nFunction Prototype
extern int ltpInit(int estMaxExportSessions);\nParameters
estMaxExportSessions: name of the endpointReturn Value
Example Call
/* Note that ltpadmin must be run before the first\n * invocation of ltplso, to initialize the LTP database\n * (as necessary) and dynamic database.*/\n\nif (ltpInit(0) < 0)\n{\n putErrmsg(\"aoslso can't initialize LTP.\", NULL);\n\n /* user error handling routine here */\n}\nDescription
This call attaches to ION and either initializes a new LTP database or loads the LTP database of an existing service. If the value of estMaxExportSessions is positive and no existing LTP service are found, then LTP service will be initialized with the specified maximum number of export sessions indicated. If the value of estMaxExportSessions is zero or negative, then ltpInit will load the LTP database or otherwise quit if no existing LTP service is found. NOTE: for the underlying communication protocol implementation, setting ltpInit(0) is appropriate since the intention is to load an existing LTP service only.
Once a LTP service is either found or initialized, it loads the address to the LTP database object defined by LtpDB in ltpP.h.
Function Prototype
void findSpan(uvast engineId, LtpVspan **vspan, PsmAddress *vspanElt);\nParameters
engineId: The engine number of the peer LTP enginevspan: pointer to the pointer of the LTP span object in ION working memory that encapsulates the current state of the LTP spanvspanElt: pointer to the address stored in a list of span in the volatile database defined by LtpVdbReturn Value
Example Code
sdr = getIonsdr();\nCHKZERO(sdr_begin_xn(sdr)); /* Lock SDR. */\nfindSpan(remoteEngineId, &vspan, &vspanElt);\nif (vspanElt == 0)\n{\n sdr_exit_xn(sdr);\n putErrmsg(\"No such engine in database.\", itoa(remoteEngineId));\n /* user error handling routine here */\n}\n\nif (vspan->lsoPid != ERROR && vspan->lsoPid != sm_TaskIdSelf())\n{\n sdr_exit_xn(sdr);\n putErrmsg(\"LSO task is already started for this span.\",\n itoa(vspan->lsoPid));\n /* user error handling routine here */\n}\n\n/* unlock the SDR */\nsdr_exit_xn(sdr);\nDescription
This function searches the volatile database for the span that corresponds to the specified engine number. If the span is found, then the pointer to the span object is stored in the vspan parameter and the address of the span object in the list of spans in the volatile database is stored in the vspanElt parameter. If the span is not found, then vspanElt parameter is set to 0.
Note: In addition to check the value of vspanElt, one can also check for the process ID of the LSO task (the LTP output process, i.e., the underlying communication protocol) of the span has not already been serviced by another protocol implementation.
Function Prototype
extern int ltpDequeueOutboundSegment(LtpVspan *vspan, char **buf);\nParameters
vspan: address to the volatile LTP span objectbuf: the buffer in which outbound LTP segments are storedReturn Value
length of segment: success0: session associated to the dequeued segment has already closed; no need to transmit any data-1: any errorExample Code
segmentLength = ltpDequeueOutboundSegment(vspan, &segment);\nif (segmentLength < 0)\n{\n /* handle error */\n}\n\nif (segmentLength == 0)\n{\n /* session is closed, take appropriate action */\n\n}\n\n/* transmit the segment */\nDescription:
This function dequeues a LTP segment, based on the segSemaphore in vspan object, into a buffer space for the calling task to process for transmission. The returned value is the length of the LTP segment dequeue; 0 if the segment belongs to a session that already closed (therefore no action is required), and -1 if an error occurred.
If this call is implemented in a loop, then it is suggested that the loop monitors the segSemaphore in vspan to detect the termination of the semaphore using the sm_SemEnded(vspan->segSemaphore) call. If the semaphore has ended, it means the span associated with the underlying communication protocol instance has ended. This is the right time to end the task itself.
After each successful iteration in a loop, it is recommended that you call sm_TaskYield() to give other tasks a chance to run. A good example code to read is the udplso.c program.
Function Prototype
int ltpHandleInboundSegment(char *buf, int length)\nParameters
buf: pointer to buffer storing the received LTP segment, to be submitted to LTP engine for processinglength: the length of the received LTP segmentReturn Value
0: segment successfully handled-1: any errorExample Code
if (ltpHandleInboundSegment(buffer, segmentLength) < 0)\n{\n putErrmsg(\"Can't handle inbound segment.\", NULL);\n /* handle error here */\n}`\nDescription
This function submits received LTP segments to LTP engine for processing. The return value is 0 if the segment is successfully handled, and -1 if an error occurred. A successfully handled segment includes cases where the segments are ignored for several possible, non-critial, non-fatal discrepencies such as wrong LTP version number, closed session number, session under cancellation (therefore the segment was not processed) and other conditions are may occur under nominal condition.
To develop one's own underlying communication protocol implementation to support LTP, the udplsi.c and udplso.c programs are good templates to use.
NO WARRANTY:
DISCLAIMER
THE SOFTWARE AND/OR RELATED MATERIALS ARE PROVIDED \"AS-IS\" WITHOUT WARRANTY OF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OR PURPOSE (AS SET FORTH IN UCC 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE LICENSED PRODUCT, HOWEVER USED.
IN NO EVENT SHALL CALTECH/JPL BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING BUT NOT LIMITED TO INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, REGARDLESS OF WHETHER CALTECH/JPL SHALL BE ADVISED, HAVE REASON TO KNOW, OR IN FACT SHALL KNOW OF THE POSSIBILITY.
USER BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWARE AND/OR RELATED MATERIALS.
Copyright 2002-2013, by the California Institute of Technology. ALL RIGHTS RESERVED. U.S. Government Sponsorship acknowledged.
This software and/or related materials may be subject to U.S. export control laws. By accepting this software and related materials, the user agrees to comply with all applicable U.S. export laws and regulations. User has the responsibility to obtain export licenses or other export authority as may be required before exporting the software or related materials to foreign countries or providing access to foreign persons.
The QCBOR code included is distributed with the following condition
Copyright (c) 2016-2018, The Linux Foundation. Copyright (c) 2018-2019, Laurence Lundblade. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of The Linux Foundation nor the names of its contributors, nor the name \"Laurence Lundblade\" may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
"},{"location":"List-of-Papers/","title":"List of Papers","text":"From manual page for \"platform\"
"},{"location":"Platform-Macros-Error-Reporting/#platform-compatibility","title":"Platform Compatibility","text":"The platform library \"patches\" the APIs of supported OS's to guarantee that all of the following items may be utilized by application software:
The strchr(), strrchr(), strcasecmp(), and strncasecmp() functions.\n\nThe unlink(), getpid(), and gettimeofday() functions.\n\nThe select() function.\n\nThe FD_BITMAP macro (used by select()).\n\nThe MAXHOSTNAMELEN macro.\n\nThe NULL macro.\n\nThe timer_t type definition.\nThe generic macros and functions in this section may be used in place of comparable O/S-specific functions, to enhance the portability of code. (The implementations of these macros and functions are no-ops in environments in which they are inapplicable, so they're always safe to call.)
"},{"location":"Platform-Macros-Error-Reporting/#fdtable_size","title":"FDTABLE_SIZE","text":"The FDTABLE_SIZE macro returns the total number of file descriptors defined for the process (or VxWorks target).
"},{"location":"Platform-Macros-Error-Reporting/#ion_path_delimiter","title":"ION_PATH_DELIMITER","text":"The ION_PATH_DELIMITER macro returns the ASCII character -- either '/' or '\\' -- that is used as a directory name delimiter in path names for the file system used by the local platform.
"},{"location":"Platform-Macros-Error-Reporting/#ok","title":"oK","text":"oK(expression)\nCHKERR(condition)\nThe CHKERR macro is an \"assert\" mechanism. It causes the calling function to return -1 immediately if condition is false.
"},{"location":"Platform-Macros-Error-Reporting/#chkzero","title":"CHKZERO","text":"CHKZERO(condition)\nThe CHKZERO macro is an \"assert\" mechanism. It causes the calling function to return 0 immediately if condition is false.
"},{"location":"Platform-Macros-Error-Reporting/#chknull","title":"CHKNULL","text":"CHKNULL(condition)\nCHKVOID(condition)\nThe CHKVOID macro is an \"assert\" mechanism. It causes the calling function to return immediately if condition is false.
"},{"location":"Platform-Macros-Error-Reporting/#snooze","title":"snooze","text":"void snooze(unsigned int seconds)\nvoid microsnooze(unsigned int microseconds)\nSuspends execution of the invoking task or process for the indicated number of microseconds.
"},{"location":"Platform-Macros-Error-Reporting/#getcurrenttime","title":"getCurrentTime","text":"void getCurrentTime(struct timeval *time)\nReturns the current local time (ctime, i.e., Unix epoch time) in a timeval structure (see gettimeofday(3C)).
"},{"location":"Platform-Macros-Error-Reporting/#isprintf","title":"isprintf","text":"void isprintf(char *buffer, int bufSize, char *format, ...)\nisprintf() is a safe, portable implementation of snprintf(); see the snprintf(P) man page for details. isprintf() differs from snprintf() in that it always NULL-terminates the string in buffer, even if the length of the composed string would equal or exceed bufSize. Buffer overruns are reported by log message; unlike snprintf(), isprintf() returns void.
"},{"location":"Platform-Macros-Error-Reporting/#istrlen","title":"istrlen","text":"size_t istrlen(const char *sourceString, size_t maxlen)\nistrlen() is a safe implementation of strlen(); see the strlen(3) man page for details. istrlen() differs from strlen() in that it takes a second argument, the maximum valid length of sourceString. The function returns the number of non-NULL characters in sourceString preceding the first NULL character in sourceString, provided that a NULL character appears somewhere within the first maxlen characters of sourceString; otherwise it returns maxlen.
"},{"location":"Platform-Macros-Error-Reporting/#istrcpy","title":"istrcpy","text":"char *istrcpy(char *buffer, char *sourceString, int bufSize)\nistrcpy() is a safe implementation of strcpy(); see the strcpy(3) man page for details. istrcpy() differs from strcpy() in that it takes a third argument, the total size of the buffer into which sourceString is to be copied. istrcpy() always NULL-terminates the string in buffer, even if the length of sourceString string would equal or exceed bufSize (in which case sourceString is truncated to fit within the buffer).
"},{"location":"Platform-Macros-Error-Reporting/#istrcat","title":"istrcat","text":"char *istrcat(char *buffer, char *sourceString, int bufSize)\nistrcat() is a safe implementation of strcat(); see the strcat(3) man page for details. istrcat() differs from strcat() in that it takes a third argument, the total size of the buffer for the string that is being aggregated. istrcat() always NULL-terminates the string in buffer, even if the length of sourceString string would equal or exceed the sum of bufSize and the length of the string currently occupying the buffer (in which case sourceString is truncated to fit within the buffer).
"},{"location":"Platform-Macros-Error-Reporting/#igetcwd","title":"igetcwd","text":"char *igetcwd(char *buf, size_t size)\nigetcwd() is normally just a wrapper around getcwd(3). It differs from getcwd(3) only when FSWWDNAME is defined, in which case the implementation of igetcwd() must be supplied in an included file named \"wdname.c\"; this adaptation option accommodates flight software environments in which the current working directory name must be configured rather than discovered at run time.
"},{"location":"Platform-Macros-Error-Reporting/#isignal","title":"isignal","text":"void isignal(int signbr, void (*handler)(int))\nisignal() is a portable, simplified interface to signal handling that is functionally indistinguishable from signal(P). It assures that reception of the indicated signal will interrupt system calls in SVR4 fashion, even when running on a FreeBSD platform.
"},{"location":"Platform-Macros-Error-Reporting/#iblock","title":"iblock","text":"void iblock(int signbr)\niblock() simply prevents reception of the indicated signal by the calling thread. It provides a means of controlling which of the threads in a process will receive the signal cited in an invocation of isignal().
"},{"location":"Platform-Macros-Error-Reporting/#ifopen","title":"ifopen","text":"int ifopen(const char *fileName, int flags, int pmode)\nifopen() is a portable function for opening \"regular\" files. It operates in exactly the same way as open() except that it fails (returning -1) if fileName does not identify a regular file, i.e., it's a directory, a named pipe, etc.
NOTE that ION also provides iopen() which is nothing more than a portable wrapper for open(). iopen() can be used to open a directory, for example.
"},{"location":"Platform-Macros-Error-Reporting/#igets","title":"igets","text":"char *igets(int fd, char *buffer, int buflen, int *lineLen)\nigets() reads a line of text, delimited by a newline character, from fd into buffer and writes a NULL character at the end of the string. The newline character itself is omitted from the NULL-terminated text line in buffer; if the newline is immediately preceded by a carriage return character (i.e., the line is from a DOS text file), then the carriage return character is likewise omitted from the NULL-terminated text line in buffer. End of file is interpreted as an implicit newline, terminating the line. If the number of characters preceding the newline is greater than or equal to buflen, only the first (buflen - 1) characters of the line are written into buffer. On error the function sets lineLen to -1 and returns NULL. On reading end-of-file, the function sets lineLen to zero and returns NULL. Otherwise the function sets *lineLen to the length of the text line in buffer, as if from strlen(3), and returns buffer.
"},{"location":"Platform-Macros-Error-Reporting/#iputs","title":"iputs","text":"int iputs(int fd, char *string)\niputs() writes to fd the NULL-terminated character string at string. No terminating newline character is appended to string by iputs(). On error the function returns -1; otherwise the function returns the length of the character string written to fd, as if from strlen(3).
"},{"location":"Platform-Macros-Error-Reporting/#strtovast","title":"strtovast","text":"vast strtovast(char *string)\nConverts the leading characters of string, skipping leading white space and ending at the first subsequent character that can't be interpreted as contributing to a numeric value, to a vast integer and returns that integer.
"},{"location":"Platform-Macros-Error-Reporting/#strtouvast","title":"strtouvast","text":"uvast strtouvast(char *string)\nSame as strtovast() except the result is an unsigned vast integer value.
"},{"location":"Platform-Macros-Error-Reporting/#findtoken","title":"findToken","text":"void findToken(char **cursorPtr, char **token)\nLocates the next non-whitespace lexical token in a character array, starting at cursorPtr. The function NULL-terminates that token within the array and places a pointer to the token in token. Also accommodates tokens enclosed within matching single quotes, which may contain embedded spaces and escaped single-quote characters. If no token is found, *token contains NULL on return from this function.
"},{"location":"Platform-Macros-Error-Reporting/#acquiresystemmemory","title":"acquireSystemMemory","text":"void *acquireSystemMemory(size_t size)\nUses memalign() to allocate a block of system memory of length size, starting at an address that is guaranteed to be an integral multiple of the size of a pointer to void, and initializes the entire block to binary zeroes. Returns the starting address of the allocated block on success; returns NULL on any error.
"},{"location":"Platform-Macros-Error-Reporting/#createfile","title":"createFile","text":"int createFile(const char *name, int flags)\nCreates a file of the indicated name, using the indicated file creation flags. This function provides common file creation functionality across VxWorks and Unix platforms, invoking creat() under VxWorks and open() elsewhere. For return values, see creat(2) and open(2).
"},{"location":"Platform-Macros-Error-Reporting/#getinternetaddress","title":"getInternetAddress","text":"unsigned int getInternetAddress(char *hostName)\nReturns the IP address of the indicated host machine, or zero if the address cannot be determined.
"},{"location":"Platform-Macros-Error-Reporting/#getinternethostname","title":"getInternetHostName","text":"char *getInternetHostName(unsigned int hostNbr, char *buffer)\nWrites the host name of the indicated host machine into buffer and returns buffer, or returns NULL on any error. The size of buffer should be (MAXHOSTNAMELEN + 1).
"},{"location":"Platform-Macros-Error-Reporting/#getnameofhost","title":"getNameOfHost","text":"int getNameOfHost(char *buffer, int bufferLength)\nWrites the first (bufferLength - 1) characters of the host name of the local machine into buffer. Returns 0 on success, -1 on any error.
"},{"location":"Platform-Macros-Error-Reporting/#getaddressofhost","title":"getAddressOfHost","text":"unsigned int getAddressOfHost()\nReturns the IP address for the host name of the local machine, or 0 on any error.
"},{"location":"Platform-Macros-Error-Reporting/#parsesocketspec","title":"parseSocketSpec","text":"void parseSocketSpec(char *socketSpec, unsigned short *portNbr, unsigned int *hostNbr)\nParses socketSpec, extracting host number (IP address) and port number from the string. socketSpec is expected to be of the form \"{ @ | hostname }[:]\", where @ signifies \"the host name of the local machine\". If host number can be determined, writes it into hostNbr; otherwise writes 0 into hostNbr. If port number is supplied and is in the range 1024 to 65535, writes it into portNbr; otherwise writes 0 into portNbr."},{"location":"Platform-Macros-Error-Reporting/#printdottedstring","title":"printDottedString","text":"
void printDottedString(unsigned int hostNbr, char *buffer)\nComposes a dotted-string (xxx.xxx.xxx.xxx) representation of the IPv4 address in hostNbr and writes that string into buffer. The length of buffer must be at least 16.
"},{"location":"Platform-Macros-Error-Reporting/#getnameofuser","title":"getNameOfUser","text":"char *getNameOfUser(char *buffer)\nWrites the user name of the invoking task or process into buffer and returns buffer. The size of buffer must be at least L_cuserid, a constant defined in the stdio.h header file. Returns buffer.
"},{"location":"Platform-Macros-Error-Reporting/#reuseaddress","title":"reUseAddress","text":"int reUseAddress(int fd)\nMakes the address that is bound to the socket identified by fd reusable, so that the socket can be closed and immediately reopened and re-bound to the same port number. Returns 0 on success, -1 on any error.
"},{"location":"Platform-Macros-Error-Reporting/#makeiononblocking","title":"makeIoNonBlocking","text":"int makeIoNonBlocking(int fd)\nMakes I/O on the socket identified by fd non-blocking; returns -1 on failure. An attempt to read on a non-blocking socket when no data are pending, or to write on it when its output buffer is full, will not block; it will instead return -1 and cause errno to be set to EWOULDBLOCK.
"},{"location":"Platform-Macros-Error-Reporting/#watchsocket","title":"watchSocket","text":"int watchSocket(int fd)\nTurns on the \"linger\" and \"keepalive\" options for the socket identified by fd. See socket(2) for details. Returns 0 on success, -1 on any failure.
"},{"location":"Platform-Macros-Error-Reporting/#closeonexec","title":"closeOnExec","text":"void closeOnExec(int fd)\nEnsures that fd will NOT be open in any child process fork()ed from the invoking process. Has no effect on a VxWorks platform.
"},{"location":"Platform-Macros-Error-Reporting/#exception-reporting","title":"Exception Reporting","text":"The functions in this section offer platform-independent capabilities for reporting on processing exceptions.
The underlying mechanism for ICI's exception reporting is a pair of functions that record error messages in a privately managed pool of static memory. These functions -- postErrmsg() and postSysErrmsg() -- are designed to return very rapidly with no possibility of failing, themselves. Nonetheless they are not safe to call from an interrupt service routing (ISR). Although each merely copies its text to the next available location in the error message memory pool, that pool is protected by a mutex; multiple processes might be queued up to take that mutex, so the total time to execute the function is non-deterministic.
Built on top of postErrmsg() and postSysErrmsg() are the putErrmsg() and putSysErrmsg() functions, which may take longer to return. Each one simply calls the corresponding \"post\" function but then calls the writeErrmsgMemos() function, which calls writeMemo() to print (or otherwise deliver) each message currently posted to the pool and then destroys all of those posted messages, emptying the pool.
Recommended general policy on using the ICI exception reporting functions (which the functions in the ION distribution libraries are supposed to adhere to) is as follows:
In the implementation of any ION library function or any ION\ntask's top-level driver function, any condition that prevents\nthe function from continuing execution toward producing the\neffect it is designed to produce is considered an \"error\".\n\nDetection of an error should result in the printing of an\nerror message and, normally, the immediate return of whatever\nreturn value is used to indicate the failure of the function\nin which the error was detected. By convention this value\nis usually -1, but both zero and NULL are appropriate\nfailure indications under some circumstances such as object\ncreation.\n\nThe CHKERR, CHKZERO, CHKNULL, and CHKVOID macros are used to\nimplement this behavior in a standard and lexically terse\nmanner. Use of these macros offers an additional feature:\nfor debugging purposes, they can easily be configured to\ncall sm_Abort() to terminate immediately with a core dump\ninstead of returning a error indication. This option is\nenabled by setting the compiler parameter CORE_FILE_NEEDED\nto 1 at compilation time.\n\nIn the absence of either any error, the function returns a\nvalue that indicates nominal completion. By convention this\nvalue is usually zero, but under some circumstances other\nvalues (such as pointers or addresses) are appropriate\nindications of nominal completion. Any additional information\nproduced by the function, such as an indication of \"success\",\nis usually returned as the value of a reference argument.\n[Note, though, that database management functions and the\nSDR hash table management functions deviate from this rule:\nmost return 0 to indicate nominal completion but functional\nfailure (e.g., duplicate key or object not found) and return\n1 to indicate functional success.]\n\nSo when returning a value that indicates nominal completion\nof the function -- even if the result might be interpreted\nas a failure at a higher level (e.g., an object identified\nby a given string is not found, through no failure of the\nsearch function) -- do NOT invoke putErrmsg().\n\nUse putErrmsg() and putSysErrmsg() only when functions are\nunable to proceed to nominal completion. Use writeMemo()\nor writeMemoNote() if you just want to log a message.\n\nWhenever returning a value that indicates an error:\n\n If the failure is due to the failure of a system call\n or some other non-ION function, assume that errno\n has already been set by the function at the lowest\n layer of the call stack; use putSysErrmsg (or\n postSysErrmsg if in a hurry) to describe the nature\n of the activity that failed. The text of the error\n message should normally start with a capital letter\n and should NOT end with a period.\n\n Otherwise -- i.e., the failure is due to a condition\n that was detected within ION -- use putErrmsg (or\n postErrmg if pressed for time) to describe the nature\n of the failure condition. This will aid in tracing\n the failure through the function stack in which the\n failure was detected. The text of the error message\n should normally start with a capital letter and should\n end with a period.\n\nWhen a failure in a called function is reported to \"driver\"\ncode in an application program, before continuing or exiting\nuse writeErrmsgMemos() to empty the message pool and print a\nsimple stack trace identifying the failure.\nchar *system_error_msg( )\nReturns a brief text string describing the current system error, as identified by the current value of errno.
"},{"location":"Platform-Macros-Error-Reporting/#setlogger","title":"setLogger","text":"void setLogger(Logger usersLoggerName)\nSets the user function to be used for writing messages to a user-defined \"log\" medium. The logger function's calling sequence must match the following prototype:
void usersLoggerName(char *msg);\nThe default Logger function simply writes the message to standard output.
"},{"location":"Platform-Macros-Error-Reporting/#writememo","title":"writeMemo","text":"void writeMemo(char *msg)\nWrites one log message, using the currently defined message logging function. To construct a more complex string, it is customary and safer to use the isprintf function to build a message string first, and then pass that string as an argument to writeMemo.
"},{"location":"Platform-Macros-Error-Reporting/#writememonote","title":"writeMemoNote","text":"void writeMemoNote(char *msg, char *note)\nWrites a log message like writeMemo(), accompanied by the user-supplied context-specific text string in note. The text string can also be build separately using isprintf().
"},{"location":"Platform-Macros-Error-Reporting/#writeerrmemo","title":"writeErrMemo","text":"void writeErrMemo(char *msg)\nWrites a log message like writeMemo(), accompanied by text describing the current system error.
"},{"location":"Platform-Macros-Error-Reporting/#itoa","title":"itoa","text":"char *itoa(int value)\nReturns a string representation of the signed integer in value, nominally for immediate use as an argument to putErrmsg(). [Note that the string is constructed in a static buffer; this function is not thread-safe.]
"},{"location":"Platform-Macros-Error-Reporting/#utoa","title":"utoa","text":"char *utoa(unsigned int value)\nReturns a string representation of the unsigned integer in value, nominally for immediate use as an argument to putErrmsg(). [Note that the string is constructed in a static buffer; this function is not thread-safe.]
"},{"location":"Platform-Macros-Error-Reporting/#posterrmsg","title":"postErrmsg","text":"void postErrmsg(char *text, char *argument)\nConstructs an error message noting the name of the source file containing the line at which this function was called, the line number, the text of the message, and -- if not NULL -- a single textual argument that can be used to give more specific information about the nature of the reported failure (such as the value of one of the arguments to the failed function). The error message is appended to the list of messages in a privately managed pool of static memory, ERRMSGS_BUFSIZE bytes in length.
If text is NULL or is a string of zero length or begins with a newline character (i.e., *text == '\\0' or '\\n'), the function returns immediately and no error message is recorded.
The errmsgs pool is designed to be large enough to contain error messages from all levels of the calling stack at the time that an error is encountered. If the remaining unused space in the pool is less than the size of the new error message, however, the error message is silently omitted. In this case, provided at least two bytes of unused space remain in the pool, a message comprising a single newline character is appended to the list to indicate that a message was omitted due to excessive length.
"},{"location":"Platform-Macros-Error-Reporting/#postsyserrmsg","title":"postSysErrmsg","text":"void postSysErrmsg(char *text, char *arg)\nLike postErrmsg() except that the error message constructed by the function additionally contains text describing the current system error. text is truncated as necessary to assure that the sum of its length and that of the description of the current system error does not exceed 1021 bytes.
"},{"location":"Platform-Macros-Error-Reporting/#geterrmsg","title":"getErrmsg","text":"int getErrmsg(char *buffer)\nCopies the oldest error message in the message pool into buffer and removes that message from the pool, making room for new messages. Returns zero if the message pool cannot be locked for update or there are no more messages in the pool; otherwise returns the length of the message copied into buffer. Note that, for safety, the size of buffer should be ERRMSGS_BUFSIZE.
Note that a returned error message comprising only a single newline character always signifies an error message that was silently omitted because there wasn't enough space left on the message pool to contain it.
"},{"location":"Platform-Macros-Error-Reporting/#writeerrmsgmemos","title":"writeErrmsgMemos","text":"void writeErrmsgMemos( )\nCalls getErrmsg() repeatedly until the message pool is empty, using writeMemo() to log all the messages in the pool. Messages that were omitted due to excessive length are indicated by logged lines of the form \"[message omitted due to excessive length]\".
"},{"location":"Platform-Macros-Error-Reporting/#puterrmsg","title":"putErrmsg","text":"void putErrmsg(char *text, char *argument)\nThe putErrmsg() function merely calls postErrmsg() and then writeErrmsgMemos().
"},{"location":"Platform-Macros-Error-Reporting/#putsyserrmsg","title":"putSysErrmsg","text":"void putSysErrmsg(char *text, char *arg)\nThe putSysErrmsg() function merely calls postSysErrmsg() and then writeErrmsgMemos().
"},{"location":"Platform-Macros-Error-Reporting/#discarderrmsgs","title":"discardErrmsgs","text":"void discardErrmsgs( )\nCalls getErrmsg() repeatedly until the message pool is empty, discarding all of the messages.
"},{"location":"Platform-Macros-Error-Reporting/#printstacktrace","title":"printStackTrace","text":"void printStackTrace( )\nOn Linux machines only, uses writeMemo() to print a trace of the process's current execution stack, starting with the lowest level of the stack and proceeding to the main() function of the executable.
Note that (a) printStackTrace() is only implemented for Linux platforms at this time; (b) symbolic names of functions can only be printed if the -rdynamic flag was enabled when the executable was linked; (c) only the names of non-static functions will appear in the stack trace.
For more complete information about the state of the executable at the time the stack trace snapshot was taken, use the Linux addr2line tool. To do this, cd into a directory in which the executable file resides (such as /opt/bin) and submit an addr2line command as follows:
addr2line -e name_of_executable stack_frame_address where both name_of_executable and stack_frame_address are taken from one of the lines of the printed stack trace. addr2line will print the source file name and line number for that stack frame.
Scott Burleigh, Jay Gao, and Leigh Torgerson
Jet Propulsion Laboratory, California Institute of Technology
Version 4.1.3
"},{"location":"Using-LTP-Config-Tool/#introduction","title":"Introduction","text":"ION open source comes with an Excel spreadsheet to help users configure the LTP protocol to optimize performance based on each user's unique use case.
ION's implementation of LTP is challenging to configure: there are a lot of configuration parameters to set, because the design is intended to support a very wide variety of deployment scenarios that are optimized for a variety of different figures of merit (utility metrics).
LTP-ION is managed as a collection of \"spans\", that is, transmission/reception relationships between the local LTP engine (the engine -- or DTN \"node\" -- that you are configuring) and each other LTP engine with which the local engine can exchange LTP protocol segments. Spans are managed using functions defined in libltpP.c that are offered to the operator by the ltpadmin program.
ltpadmin can be used to add a span, update an existing span, delete a span, provide current information on a specified span, or list all spans. The span configuration parameters that must be set when you add or update a span are as follows:
remote LTP engine number identifying the span. For ION, this is by convention the same as the BP node number as established when the ION database was initialized.maximum number of export sessions that can be held open on this span at any one time. This implements LTP flow control across the span: since no new data can be transmitted until it is appended to a block -- the data to be conveyed in a single export session -- and no new session can be started until the total number of open sessions drops below the maximum, the closure of export sessions regulates the rate at which LTP can be used to transmit data.maximum number of import sessions that will be open on this span at any one time. This value is simply the remote engine's own value for the \"maximum number of export sessions\" parameter.Maximum LTP segment size. This value is typically the maximum permitted size of the payload of each link-layer protocol data unit -- nominally a frame.Aggregation size limit. This is the \"nominal\" size for blocks to be sent over this span: normally LTP will concatenate multiple service data units (such as BP bundles) into a single block until the aggregate size of those service data units exceeds the aggregation size limit, and only then will it divide the block into segments and use the underlying link service to transmit the segments. (Note that it is normal for the aggregation size limit to be exceeded. In this sense, the word \"limit\" is really a misnomer; \"threshold\" would be a better term.)Aggregation time limit. This parameter establishes an alternate means of terminating block aggregation and initiating segment transmission: in the event that service data units are not being presented to LTP rapidly enough to promptly fill blocks of nominal size, LTP will arbitrarily terminate aggregation when the length of time that the oldest service data units in the block have been waiting for transmission exceeds the aggregation time limit.The Link Service Output command. This parameter declares the command that will be used to start the link service output task for this span. The value of this parameter is a string, typically enclosed in single quote marks and typically beginning with the name of the executable object for the task. When the \"udplso\" link service output module is to be used for a given span, the module name is followed by the IPAddress:Port of the remote engine and (optionally) the UDP transmission rate limit in bits per second.In addition, at the time you initialize LTP (normally at the start of the ltpadmin configuration file) you must set one further configuration parameter:
Estimated total number of export sessions, for all spans: this value is used to size the hash table that LTP uses for storing and retrieving export session information.In many cases, the best values for these configuration parameters will not be obvious to the DTN network administrator. To simplify this task, an LTP Configuration Worksheet has been developed.
"},{"location":"Using-LTP-Config-Tool/#worksheet-overview","title":"Worksheet overview","text":"The LTP configuration worksheet is designed to aid in the configuration of a single span -- that is, the worksheet for the span between engines X and Y will provide configuration parameter values for use in commanding ltpadmin on both engine X and engine Y.
The cells of the worksheet are of two general types, Input Cells and Calculated Cells.
Input Cells are cells in which the network administrator must supply values based on project decisions. These cells are yellow-filled.Calculated Cells are cells that are computed by the worksheet based on LTP configuration principles. These cells are grey-filled. The cells are protected from modification (though you can unprotect them if you want by selecting \"Unprotect Sheet\" on the Excel \"Review\" tab).Some of these cells are used as span configuration parameters or are figures of merit for network administrators:
Note: Configuration parameters that are described in detail in this document are numbered. To ease cross referencing between this document and the worksheet, the parameter numbers are placed next to the title cells in the worksheet.*
"},{"location":"Using-LTP-Config-Tool/#input-parameters","title":"Input Parameters","text":"This section provides guidance on the values that must be supplied by the network administrator. Global parameters affect calculated values and configuration file parameters for all spans involving the local LTP engine.
"},{"location":"Using-LTP-Config-Tool/#global-parameters","title":"Global Parameters","text":"Maximum bit error rate is the maximum bit error rate that the LTP should provide for in computing the maximum number of transmission efforts to initiate in the course of transmitting 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, i.e., 10^-6^, one uncorrected (but detected) bit error per million bits transmitted.
The size - estimated size of an LTP report segment in bytes - may vary slightly depending on the sizes of the session numbers in use. 25 bytes is a reasonable estimate.
Values for the following parameters must be provided by the network administrator in order for the worksheet to guide the configuration. Values must be provided for both engine \"X\" and engine \"Y\".
OWLT between engines (sec) is the maximum one-way light time over this span, i.e., the distance between the engines. (Note that this value is assumed to be symmetrical.)engine number for each engine.IP address of each engine. (Assuming udplso will be used as the link service output daemon.)LTP reception port number for each engine. (Again assuming udplso will be used as the link service output daemon.)mean size of the LTP service data units (nominally bundles) sent from this engine over this span.Link service overhead. The expected number of bytes of link service protocol header information per LTP segment.Aggregation size limit - this is the service data unit aggregation size limit for LTP. Note that a suggested value for this parameter is automatically computed as described below, based on available return channel capacity.scheduled transmission rate (in bytes per second) at which this engine will transmit data over this span when the two engines are in contact.Maximum percentage of channel capacity that may be consumed by LTP report segments. A warning will be displayed if other configuration parameters cause this limit to be breached. There are no actual mechanism to enforce this limit in ION. This only set in order to check the estimated report traffic for the current configuration. It is provided as an aid to LTP link designer.estimate of the percentage of all data sent over this span that will be red data, i.e., will be subject to positive and negative LTP acknowledgment.Aggregation time limit. The minimum value is 1 second. Increasing this limit can marginally reduce the number of blocks transmitted, and hence protocol overhead, at times of low communication activity. However, it reduces the \"responsiveness\" of the protocol, increasing the maximum possible delay before transmission of any given service data unit. (This delay is referred to as \"data aggregation latency\".)
Low communication activity is defined as a rate of presentation of service data to LTP that is less than the aggregation size limit divided by the aggregation time limit.LTP segment size (bytes) is the maximum LTP segment size sent over this span by this engine. Typically, this is the maximum permitted size of the payloads of link-layer protocol data units (frames).The maximum number of export sessions. This implements a form of flow control by placing a limit on the number of concurrent LTP sessions used to transmit blocks. Smaller numbers will result in slower transmission, while higher numbers increase storage resource occupancy. Note that a suggested value for this parameter is automatically computed as described below, based on transmission rate and one-way light time.This section provides further information on the methods used to compute the Calculated Cells and also guidance for Input Cell values.
The following parameters are automatically computed based on the values of the basic input parameters.
Estimated \"red\" data transmission rate (bytes/sec) is simply the scheduled transmission rate multiplied by the estimated \"red\" data percentage.Maximum export data in transit (bytes) is the product of the estimated red data transmission rate and the round-trip light time (which is twice the one-way light time between the engines). This is the maximum amount of red data that cannot yet have been positively acknowledged by the remote engine and therefore must be retained in storage for possible retransmission.Values for the following parameters must be chosen by the network administrator on the basis of (a) known project requirements or preferences. (b) the first-order computed parameters, and (c) the computed values of figures of merit that result from tentative parameter value selections, as noted.
#6 Aggregation size limit (revisited). Reducing this parameter tends to increase the number of blocks transmitted, increasing total protocol overhead. The suggested value for this parameter is computed as follows:The threshold block size, expressed in bytes per block, is then given by dividing the local engine's transmission data rate (in bytes per second) by the maximum number of blocks to be transmitted per second.
Est. mean export block size is computed as follows:
a. If the mean service data unit size is so large that aggregation of multiple service data units into a block is never necessary, then that mean service data unit size will in effect determine the mean export block size (one service data unit per block).
b. Otherwise, the mean export block size will be determined by aggregation. If the red data transmission rate is so high that the aggregation time limit will normally never be reached, then the aggregation size limit constitutes the mean export block size. Otherwise, block size will be constrained by aggregation time limit expiration: the estimated mean export block size will be approximated by multiplying the red data transmission rate by the number of seconds in the aggregation time limit.
c. So estimated mean export block size is computed as larger of mean service data unit size and \"expected aggregate block size\", where expected aggregate block size is the lesser of block aggregation size limit and the product of red data transmission rate and aggregation time limit. 16. Estimated blocks transmitted per second are computed as Estimated red data xmit rate (bytes/sec) (parameter 13) divided by Est. mean export block size (parameter 15). 17. Est. Report bytes/sec sent by the remote engine in response to these transmitted blocks is computed as the product of Est. blocks transmitted per second (parameter 16) and Size (mean) of LTP acknowledgment (bytes) (a global parameter). When mean service data unit size is less than the aggregation size limit and the red data transmission rate is high enough to prevent the aggregation time limit from ever being reached, this value will be about the same as the maximum number of bytes of LTP report content that the remote engine may transmit per second as computed above.
Note: increasing the aggregation size limit reduces the block transmission rate at the local engine, reducing the rate of transmission of acknowledgment data at the remote engine; this can be a significant consideration on highly asymmetrical links. 18. Est. segments per block is computed as Est. mean export block size (parameter 15) divided by LTP segment size (bytes) (parameter 11). 19. Est. LTP delivery efficiency on the span is calculated by dividing Est. blocks delivered per second by Est blocks transmitted per second. Reducing the aggregation size limit indirectly improves delivery efficiency by reducing block size, thus reducing the percentage of transmitted blocks that will be affected by the loss of a given number of frames.
#12 Maximum number of export sessions (revisited). Increasing the maximum number of export sessions will tend to improve link bandwidth utilization but will increase the amount of storage space needed for span state retention. The suggested value for this parameter is computed as the maximum export data in transit (bytes) (Parameter 14) divided by Est. mean export block size (parameter 15) as determined above. Configuring the span for a maximum export session count that is less than this limit will make it impossible to fully utilize the link even if all blocks are of estimated mean size.Nominal export SDU's in transit is computed by dividing Nominal export data in transit (bytes) by the Size (mean) of service data units (bytes) (parameter 4).Expected link utilization is then computed by dividing Nominal export data in transit (bytes) by Maximum export data in transit (bytes) (parameter 14). Note that a low value of expected link utilization indicates that a high percentage of the span's transmission capacity is not being used. Utilization can be improved by increasing estimated mean export block size (e.g., by increasing aggregation size limit) or by increasing the maximum number of export sessions.Max data aggregation latency (sec) is simply the value supplied for Aggregation time limit (sec) (parameter 10) as this time limit is never exceeded.Finally, the remaining LTP initialization parameter can be computed when all span configuration decisions have been made.
Maximum number of import sessions is automatically taken from the remote engine's maximum number of export sessions.This research was carried out at the Jet Propulsion Laboratory, California Institute of Technology, under a contract with the National Aeronautics and Space Administration.
"},{"location":"Using-LTP-Config-Tool/#updated-features-may-2021","title":"Updated Features - May 2021","text":"This section describes the following features added to the configuration tool as of May 2021:
The recommended workflow for using the LTP configuration tool is to first establish the space link configuration using the link worksheet before attempting to generate a LTP configuration under the main worksheet. The link worksheet has the following input and computed cells:
Select CCSDS Frame Size (bits) \\[user input\\]-- this cell allows the user to select a standard CCSDS AOS/TM frame size from a drop down list that includes LDPC, Turbo, and Reed-Solomon codes.CCSDS Frame Size (bytes) \\[computed\\]-- converts frame size from bits to bytes.Desired Frame Error Rate \\[user input\\] -- this parameter sets the expected frame error rate of the LTP link in operation. This parameter could be derived from link budget analysis or a mission requirement document.Segment size (byte) \\[user input\\] -- this parameter sets the maximum segment payload size used by LTP. The size of the segment, in relation to the underlying CCSDS frame, will determine the segment error rate and the probability that LTP will need to request retransmission.Ethernet Frame Size (byte) \\[user input\\] -- this is the Ethernet frame size used in a laboratory environment to simulate space link frame losses.Segment Error Rate Computation \\[computed\\] -- this is the LTP segment error rate derived from the frame error rate and the segment and CCSDS frame size selections.*maxBER* Computation \\[computed\\] -- this is the computed maxBER parameter for LTP. The maxBER parameter is what LTP uses to estimate segment error rate, which in turn will affect how LTP handles handshaking failure and repeated retransmission requests. To properly operate LTP, the maxBER value provided must result in the same segment error rate as one expects to encounter in real space link.Ethernet Error Rate Computation \\[computed\\] -- this is the recommended setting for using laboratory Ethernet frame error software/hardware to simulate space link loss. This value is translated from the segment error rate to Ethernet frame error to make sure that laboratory testing provides a statistically equivalent impact on LTP.In the main worksheet described in Section 3, we made the following enhancements:
Aggregation size limit (bytes) -- a green icon is displayed when the input parameter is greater or equal to the suggested value; a red icon is displayed when this parameter is below the suggested value. The suggested value aggregation size limit upper bounds the LTP block rate such that the acknowledgement traffic (report segments) from the receiver to the sender can be supported.Aggregation time limit (sec) -- there are two factors affecting LTP block aggregation: time limit and size limit. The aggregation process stops as soon as one of the two limits is reached. A green icon is displayed if the time limit value in this cell is sufficiently large such that the aggregation process will be size limited, i.e., on average the LTP block aggregation process will reach the size limit before the time limit. This is the nominal and desired configuration unless there is a strict latency requirement that forces one to use a very low aggregation time limit. A red icon is displayed if the time limit will be driving, which means the LTP block size will generally be smaller than the aggregation size limit and the block rate will be higher than desired. If a latency requirement forces the use of a low aggregation time limit, one must check to make sure there is still sufficient bandwidth to support the acknowledgement (report segment) traffic.Est. report bytes/sec sent - this field estimates the bandwidth required to support LTP report segment traffic up to 95 percentile of all cases involving retransmission of missing segments. The segment error rate was derived from the link worksheet. The green icon indicates that estimated report bandwidth is feasible based on current configuration.A simple HeapWord size estimate calculation is added to the main worksheet, based on the following assumptions:
Longest Expected Period to Buffer Data Period (sec) -- this is the expected longest period of time one expects ION will buffer user data. The data accumulation rate is the same as the LTP red data data rate.(32/64) bit system -- this is platform dependent parameter. Heap space is specified in the number of words. For a 32-bit system, each word has 32 bits; for a 64-bit system, each word has 64 bits.Additional Margin -- adds more margin to the model per user's discretionRecommended heapWords value (with 40% for ZCO) -- this is the suggested heapWords value for ionconfig.Recommended heapWords value - iif source data completely in memory -- this is the suggested heapWords value for ionconfig assuming the source data is copied into heap space at the time of bundle creation without using file-resident reference.wmSize recommendation - this is the suggested wmSize parameter to use to support the staging of large quantities of bundles in the heap. This recommended value includes an additional 200% margin. The rationale for the calculation is derived from analysis summarized in the ION Deployment Guide and based on previous studies.In this section, we summarize the finding documented in a powerpoint presentation titled, \"ION DTN/LTP Configuration and ION Memory Usage Analysis\", dated January 2021, that is used as the basis for estimating the heap space required for BP/LTP operation in ION:
With 1 bundle in the system that is under active LTP session, the minimum heap space needed can be approximated as: heap space = S + base
S is the bundle size / segment size x segment header size x 10
If N \\<= M, heap space usage is approximately S x N + 1560 bytes x N + base
S x N is LTP related heap usage, 1560 x N is bundle level heap usage
If N > M, heap space usage is approximately S x M + 1560 bytes x N + base
For bundle in LTP transmission, we count both LTP and bundle level heap usage
Nik Ansell co-authored/contributed to the 2016 version of this document, which has been updated and revised in 2021.
\u00a9 2016 California Institute of Technology. Government sponsorship acknowledged.
"},{"location":"community/Contributing-Code-to-ION/","title":"Contributing Code to ION","text":""},{"location":"community/Contributing-Code-to-ION/#expectations","title":"Expectations","text":"If you plan to contribute to the ION project, please keep these in mind:
The NASA team will review these contributions and determine to either
Incorporate the code into the baseline, or
/contrib folder for continued experimental use,This project has been developed by Dr Lara Suzuki, a Visiting Researcher at NASA JPL.
"},{"location":"community/dtn-gcp-2nodes/ION-Two-Node-on-Cloud-Linux-VMs/#introduction","title":"Introduction","text":"In this project we demonstrate how to run DTN on two nodes on Cloud VM using NASA's implementation of the bundle protocol - ION.
Two-Node Topology
The ION (interplanetary overlay network) software is a suite of communication protocol implementations designed to support mission operation communications across an end-to-end interplanetary network, which might include on-board (flight) subnets, in-situ planetary or lunar networks, proximity links, deep space links, and terrestrial internets.
"},{"location":"community/dtn-gcp-2nodes/ION-Two-Node-on-Cloud-Linux-VMs/#dtn-on-cloud-linux-vms-101","title":"DTN on Cloud Linux VMs 101","text":"We strongly recommend that you firstly get familiar with the Loopback communication of ION running on a single node on Google Cloud Platform.
"},{"location":"community/dtn-gcp-2nodes/ION-Two-Node-on-Cloud-Linux-VMs/#getting-started-with-two-linux-cloud-vms","title":"Getting Started with Two Linux Cloud VMs","text":"On your preferred Cloud provider dashboard, create a Linux VM instance (e.g. for instance Debian). In this tutorial we have created one instance named Golstone in Zone: us-central1 and the another instance named Madrid in Zone: europe-west2-c. The diagram below illustrates the two node communication that we will be developing in this tutorial.
In this section we will walk you through the creation of the host1.rc file. Follow the same steps to create the same file for host2.rc.
ionadmin configuration","text":"The ionadmin configuration assigns an identity (node number) to the node, optionally configures the resources that will be made available to the node, and specifies contact bandwidths and one-way transmission times.
## begin ionadmin \n# Initialization command (command 1). \n# Set this node to be node 1 (as in ipn:1).\n# Use default sdr configuration (empty configuration file name '').\n1 1 ''\n\n# Start ion node\ns\n\n# Add a contact.\n# It will start at +1 seconds from now, ending +3600 seconds from now.\n# It will connect node 1 to itself.\n# It will transmit 100000 bytes/second.\na contact +1 +3600 1 1 100000\n\n# Add more contacts.\n# The network goes 1--2\n# Note that contacts are unidirectional, so order matters.\na contact +1 +3600 1 2 100000\na contact +1 +3600 2 1 100000\na contact +1 +3600 2 2 100000\n\n# Add a range. This is the physical distance between nodes.\n# It will start at +1 seconds from now, ending +3600 seconds from now.\n# It will connect node 1 to itself.\n# Data on the link is expected to take 1 second to reach the other\n# end (One Way Light Time).\na range +1 +3600 1 1 1\n\n# Add more ranges.\n# We will assume every range is one second.\n# Note that ranges cover both directions, so you \n#only need define one range for any combination of nodes.\na range +1 +3600 1 2 1\na range +1 +3600 2 2 1\n\n# Set this node to consume and produce a mean of 1000000 bytes/second.\nm production 1000000\nm consumption 1000000\n## end ionadmin \nltpadmin configuration","text":"The ltpadmin configuration specifies spans, transmission speeds, and resources for the Licklider Transfer Protocol convergence layer
# Initialization command (command 1).\n1 32\n\n# Add a span. (a connection)\na span 1 10 10 1400 10000 1 'udplso `external_IP_of_node_1`:1113'\n\n# Add another span. (to host2) \n# Identify the span as engine number 2.\n# Use the command 'udplso 10.1.1.2:1113' to implement the link itself. \na span 2 10 10 1400 10000 1 'udplso `external_IP_of_node_2`:1113'\n\n# Start command.\n# This command actually runs the link service output commands.\n# It also starts the link service INPUT task 'udplsi `internal_IP_of_node_1`:1113' \n# to listen locally on UDP port 1113 for incoming LTP traffic.\ns 'udplsi `internal_IP_of_node_1`:1113'\n## end ltpadmin \nbpadmin configuration","text":"The bpadmin configuration specifies all of the open endpoints for delivery on your local end and specifies which convergence layer protocol(s) you intend to use.
## begin bpadmin \n# Initialization command (command 1).\n1\n\n# Add an EID scheme.\n# The scheme's name is ipn.\n# This scheme's forwarding engine is handled by the program 'ipnfw.'\n# This scheme's administration program (acting as the custodian\n# daemon) is 'ipnadminep.'\na scheme ipn 'ipnfw' 'ipnadminep'\n\n# Add endpoints.\n# Establish endpoints ipn:1.0, ipn:1.1, and ipn:1.2 on the local node.\n# ipn:1.0 is expected for custodian traffic. The rest are usually\n# used for specific applications (such as bpsink).\n# The behavior for receiving a bundle when there is no application\n# currently accepting bundles, is to queue them 'q', as opposed to\n# immediately and silently discarding them (use 'x' instead of 'q' to\n# discard).\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n\n# Add a protocol. \n# Add the protocol named ltp.\n# Estimate transmission capacity assuming 1400 bytes of each frame (in\n# this case, udp on ethernet) for payload, and 100 bytes for overhead.\na protocol ltp 1400 100\n\n# Add an induct. (listen)\n# Add an induct to accept bundles using the ltp protocol.\n# The duct's name is 1 (this is for future changing/deletion of the\n# induct). \n# The induct itself is implemented by the 'ltpcli' command.\na induct ltp 1 ltpcli\n\n# Add an outduct (send to yourself).\n# Add an outduct to send bundles using the ltp protocol.\na outduct ltp 1 ltpclo\n\n# Add an outduct. (send to host2)\n# Add an outduct to send bundles using the ltp protocol.\na outduct ltp 2 ltpclo\n\n# Start bundle protocol engine, also running all of the induct, outduct,\n# and administration programs defined above\ns\n## end bpadmin \nipnadmin configuration","text":"The ipnadmin configuration maps endpoints at \"neighboring\" (topologically adjacent, directly reachable) nodes to convergence-layer addresses.
## begin ipnadmin \n# ipnrc configuration file for host1 in a 3node ltp/tcp test. \n# Essentially, this is the IPN scheme's routing table.\n\n# Add an egress plan.\n# Bundles to be transmitted to node number 1 (that is, yourself).\n# The plan is to queue for transmission on protocol 'ltp' using\n# the outduct identified as '1.'\na plan 1 ltp/1\n\n# Add other egress plans.\n# Bundles for elemetn 2 can be transmitted directly to host2 using\n# ltp outduct identified as '2.' \na plan 2 ltp/2\n## end ipnadmin\nionsecadmin configuration","text":"The ionsecadmin enables bundle security (also avoid error messages in ion.log).
## begin ionsecadmin\n# Enable bundle security and avoid error messages in ion.log\n1\n## end ionsecadmin\nOn the terminal of host 1 execute the command
$ ionstart -I host1.rc\nhost 2 execute the command $ ionstart -I host2.rc\nhost 1 to host 2, you must firstly start bpsink in host 2 by executing the command below $ bpsink ipn:2.1 &\nhost 1, enter the following command and hit enter $ echo \"hi\" | bpsource ipn:2.1\nhost 2 the following message $ ION event: Payload delivered.\n$ payload length is 2.\n$ 'hi'\nhost 2 sending a hello message to host 1. "},{"location":"community/dtn-gcp-2nodes/rc_files/host1-start-script-2node/","title":"ION Start Script Example","text":"Note: place this in a file named host1.rc
## begin ionadmin \n1 1 ''\ns \n\na contact +1 +3600 1 1 100000\na contact +1 +3600 1 2 100000\na contact +1 +3600 2 1 100000\na contact +1 +3600 2 2 100000\n\na range +1 +3600 1 1 1\na range +1 +3600 1 2 1\na range +1 +3600 2 2 1\n\nm production 1000000\nm consumption 1000000\n## end ionadmin \n\n## begin ltpadmin \n1 32\n\na span 1 10 10 1400 10000 1 'udplso `external_IP_of_node_1`:1113'\na span 2 10 10 1400 10000 1 'udplso `external_IP_of_node_2`:1113'\ns 'udplsi `internal_IP_of_node_1`:1113'\n## end ltpadmin \n\n## begin bpadmin \n1\na scheme ipn 'ipnfw' 'ipnadminep'\n\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n\na protocol ltp 1400 100\na induct ltp 1 ltpcli\na outduct ltp 1 ltpclo\na outduct ltp 2 ltpclo\n\ns\n## end bpadmin \n\n## begin ipnadmin \na plan 1 ltp/1\na plan 2 ltp/2\n## end ipnadmin\n\n## begin ionsecadmin\n1\n## end ionsecadmin\nNote: place this in a file named host2.rc
## begin ionadmin \n1 2 ''\ns\n\na contact +1 +3600 1 1 100000\na contact +1 +3600 1 2 100000\na contact +1 +3600 2 1 100000\na contact +1 +3600 2 2 100000 \n\na range +1 +3600 1 1 1\na range +1 +3600 1 2 1\na range +1 +3600 2 2 1\n\nm production 1000000\nm consumption 1000000\n## end ionadmin \n\n## begin ltpadmin \n1 32\n\na span 1 10 10 1400 10000 1 'udplso `external_IP_of_node_1`:1113'\na span 2 10 10 1400 10000 1 'udplso `external_IP_of_node_2`:1113'\ns 'udplsi `internal_IP_of_node_2`:1113'\n## end ltpadmin \n\n## begin bpadmin \n1\na scheme ipn 'ipnfw' 'ipnadminep'\n\na endpoint ipn:2.0 q\na endpoint ipn:2.1 q\na endpoint ipn:2.2 q\n\na protocol ltp 1400 100\na induct ltp 2 ltpcli\na outduct ltp 2 ltpclo\na outduct ltp 1 ltpclo\n\ns\n## end bpadmin \n\n## begin ipnadmin \na plan 1 ltp/1\na plan 2 ltp/2\n## end ipnadmin\n\n## begin ionsecadmin\n1\n## end ionsecadmin\nThis project has been developed by Dr Lara Suzuki, a visiting Researcher at NASA JPL.
In this tutorial we will demonstrate how to connect a Raspberry Pi and Sensor Hat onto Google Cloud using cloud Pub/Sub on host 1 and serving the messages over DTN to host 2. This tutorial follows the [Running DTN on Google Cloud using a Two-Node Ring] tutorial and uses the configurations of host 1 and host 2 as described in the tutorial.
In this tutorial we use Raspberry Pi 4 model B (2018) and Sense Hat Version 1.0.
The first step is to be sure your Pi can connect to the Internet. You can either plug in an ethernet cable, or if you\u2019re using WiFi, scan for networks your Pi can see. Plug your Pi in a monitor, and when it starts, at the top right corner you can find the wifi logo. Select the network you want to connect to. Once that is connected open your browser to check whether you can access the Internet.
"},{"location":"community/dtn-gcp-iot-main/ION-and-IOT-on-Linux-VMs-running-on-Cloud-Computing/#library-dependency-setup","title":"Library dependency setup","text":"The first thing to do is to make sure that the places where Raspberry Pi will be getting its libraries from is current. For this, on your Pi's terminal, run the following command:
$ sudo apt-get update\npyjwt). The meta-model for communication used on the cloud Pub/Sub is based on publish/subscribe messaging technology provided by the MQTT (MQ Telemetry Transport) protocol (library paho-mqtt). MQTT is a topic-based publish/subscribe communications protocol that is designed to be open, simple, lightweight, easy-to-implement, and efficient in terms of processor, memory, and network resources. On your Pi's terminal run the following commands
$ sudo apt-get install build-essential\n$ sudo apt-get install libssl-dev\n$ sudo apt-get install python-dev\n$ sudo apt-get install libffi-dev\n$ sudo pip install paho-mqtt\npyjwt library and its dependency, the cryptography library . $ sudo pip install pyjwt\n$ sudo pip install cryptography\n$ sudo apt get install sense-hat\nIn order to authenticate in Google Cloud IoT Core, we need a SSL certificate. We will create an RSA with X509 wrapper. For this, execute the following command on your Pi's terminal:
$ openssl req -x509 -newkey rsa:2048 -keyout sensing_private.pem -nodes -out demo.pub -subj \u201c/CN=unused\u201d\nOnce your Raspberry Pi is fully set up, follow the instructions of your Cloud provider to create a Registry of your new Pub/Sub service. For your Pub/Sub 'topic', create a topic named: sensing
To connect your device on your cloud provider, you will likely to need to use an authentication method. In our case we use authentication using a Public Key in the format RS256_X509.
To copy the content of your Pi's public key, on the Pi's terminal run:
$ cat demo.pub\nCopy everything, including the tages, between
-----BEGIN PUBLIC KEY-----\n-----END PUBLIC KEY-----\nPublic Key Value textbox."},{"location":"community/dtn-gcp-iot-main/ION-and-IOT-on-Linux-VMs-running-on-Cloud-Computing/#create-a-subscription-to-listen-to-the-pubsub-topic","title":"Create a Subscription to listen to the Pub/Sub Topic","text":"On your cloud provide Console, create a 'Subscription' to listen to the topic sensing we created in the previous steps. Now you should have all the pieces needed to send telemetry data from your Pi to a Pub/Sub service on a VM instance running on the cloud!
The code on this repository named sense.py is based on the implementation of GabeWeiss.
In the code, edit the following fields:
ssl_private_key_filepath = '/home/pi/sensing_private.pem'\nssl_algorithm = 'RS256'\nroot_cert_filepath = '/home/pi/roots.pem'\nproject_id = 'if you have to use a project ID identifier in your cloud service'\nregistry_id = 'name of your registry'\ndevice_id = 'name of your device'\n$ python3 sense.py\nLog into the VM host 1. In the VM go to the base directory of ION and create a folder named dtn
$ mkdir dtn\niot.py. In this file configure the following parameters: subscription_path = subscriber.subscription_path(\n 'ID_OF_YOUR_CLOUD_PROJECT', 'ID_OF_YOUR_SUBSCRIPTION')\nhost 2 as the receiver of the telemetry data: os.system(f'echo \"{value}\" | bpsource ipn:2.1')\nhost 1 and host 2, start ion: $ ionstart -I hostX.rc #where X is the number of the host\nhost 2, start bpsink $ bpsink ipn:2.1 &\nhost 1, start iot.py $ python3 iot.py\nhost 1 you should see the print out of the telemetry data received as below: On the terminal of host 2 you should see the payloads delivered. Please note that messages beyond 80 characters are not shown on bpsink:
Note: place this in a file named iot.py
```` import os import time from google.cloud import pubsub_v1 subscriber = pubsub_v1.SubscriberClient()
"},{"location":"community/dtn-gcp-iot-main/iot-python-script/#the-subscription_path-method-creates-a-fully-qualified-identifier","title":"Thesubscription_path method creates a fully qualified identifier","text":""},{"location":"community/dtn-gcp-iot-main/iot-python-script/#in-the-form-projectsproject_idsubscriptionssubscription_name","title":"in the form projects/{project_id}/subscriptions/{subscription_name}","text":"subscription_path = subscriber.subscription_path( 'ID_OF_YOUR_GOOGLE_CLOUD_PROJECT', 'ID_OF_YOUR_SUBSCRIPTION') def callback(message): value = message.data os.system(f'echo \"{value}\" | bpsource ipn:2.1') print('Received message: {}'.format(value)) message.ack() # Acknowledges the receipt of the message and remove it from the topic queue subscriber.subscribe(subscription_path, callback=callback)
"},{"location":"community/dtn-gcp-iot-main/iot-python-script/#the-subscriber-is-non-blocking-we-must-keep-the-main-thread-from","title":"The subscriber is non-blocking. We must keep the main thread from","text":""},{"location":"community/dtn-gcp-iot-main/iot-python-script/#exiting-to-allow-it-to-process-messages-asynchronously-in-the-background","title":"exiting to allow it to process messages asynchronously in the background.","text":"print('Listening for messages on {}'.format(subscription_path)) while True: time.sleep(60)
````
"},{"location":"community/dtn-gcp-iot-main/sense-python-script/","title":"ION Start Script Example","text":"Note: place this in a file named sense.py
```` from sense_hat import SenseHat import Adafruit_DHT import time import datetime import time import jwt import paho.mqtt.client as mqtt
"},{"location":"community/dtn-gcp-iot-main/sense-python-script/#define-some-project-based-variables-to-be-used-below-this-should-be-the-only","title":"Define some project-based variables to be used below. This should be the only","text":""},{"location":"community/dtn-gcp-iot-main/sense-python-script/#block-of-variables-that-you-need-to-edit-in-order-to-run-this-script","title":"block of variables that you need to edit in order to run this script","text":"ssl_private_key_filepath = '' # The .pem file of your Pi ssl_algorithm = 'RS256' root_cert_filepath = '' # The .pem file of Google project_id = '' # The project ID on Google Cloud gcp_location = '' # The zone where your project is deployed registry_id = '' # The ID of your registry on Google IoT Core device_id = '' # The ID of your Pi as set up on Google IoT Core
cur_time = datetime.datetime.utcnow()
DHT_SENSOR = Adafruit_DHT.DHT11 DHT_PIN = 4
def create_jwt(): token = { 'iat': cur_time, 'exp': cur_time + datetime.timedelta(minutes=60), 'aud': project_id }
with open(ssl_private_key_filepath, 'r') as f: private_key = f.read()
return jwt.encode(token, private_key, ssl_algorithm)
_CLIENT_ID = 'projects/{}/locations/{}/registries/{}/devices/{}'.format(project_id, gcp_location, registry_id, device_id) _MQTT_TOPIC = '/devices/{}/events'.format(device_id)
client = mqtt.Client(client_id=_CLIENT_ID) client.username_pw_set( username='unused', password=create_jwt())def error_str(rc): return '{}: {}'.format(rc, mqtt.error_string(rc))
def on_connect(unusued_client, unused_userdata, unused_flags, rc): print('on_connect', error_str(rc))
def on_publish(unused_client, unused_userdata, unused_mid): print('on_publish')
client.on_connect = on_connect client.on_publish = on_publish
client.tls_set(ca_certs=root_cert_filepath) client.connect('mqtt.googleapis.com', 8883) client.loop_start()
"},{"location":"community/dtn-gcp-iot-main/sense-python-script/#could-set-this-granularity-to-whatever-we-want-based-on-device-monitoring-needs-etc","title":"Could set this granularity to whatever we want based on device, monitoring needs, etc","text":"temperature = 0 humidity = 0 pressure = 0
sense = SenseHat()
while True: cur_temp = sense.get_temperature() cur_pressure = sense.get_pressure() cur_humidity = sense.get_humidity() if cur_temp == temperature and cur_humidity == humidity and cur_pressure == pressure: time.sleep(1) continue temperature = cur_temp pressure = cur_pressure humidity = cur_humidity
payload = '{{ \"ts\": {}, \"temperature\": {}, \"pressure\": {}, \"humidity\": {} }}'.format(cur_time, \"%.1f C\" % temperature,\"%.2f Millibars\" % press$
client.publish(_MQTT_TOPIC, payload, qos=1)
print(\"{}\\n\".format(payload))
sense.set_rotation(180) # Set LED matrix to scroll from right to left
sense.show_message(\"%.1f C\" % temperature, scroll_speed=0.10, text_colour=[0, 255, 0]) # Show the temperature on the LED Matrix
time.sleep(10)
````
"},{"location":"community/dtn-gcp-ltp-tcp-main/ION-LTP-TCP-on-Azure/","title":"Three-Node Network communication via DTN on Google Cloud Platform and Windows Azure","text":"This project has been developed by Dr Lara Suzuki, a Visiting Researcher at NASA JPL.
"},{"location":"community/dtn-gcp-ltp-tcp-main/ION-LTP-TCP-on-Azure/#introduction","title":"Introduction","text":"This is the third tutorial on a series of DTN on Google Cloud tutorials. In this tutorial we will introduce you to Windows Azure, and how to configure a 3-node network using ION. The figure below shows the network we will be building. Note that this example network uses two different convergence layers: TCP and LTP. This can illustrates the case of a terrestrial connection with two interplanetary internet nodes.
"},{"location":"community/dtn-gcp-ltp-tcp-main/ION-LTP-TCP-on-Azure/#getting-started-on-windows-azure","title":"Getting Started on Windows Azure","text":"Sign up for a free account on Windows Azure. Once your free account is set up, log into the Azure Portal. Under Azure Services, click Virtual Machines. In the Virtual Machines window, click Add and follow the steps below. 1. Click Add then Virtual Machine 2. Subscription free trial 3. In Resource Group select Create New and name it dtn 4. In Virtual Machine name give it a name. In our example it is named Canberra 5. In Region select the region closest to you or of your choice. In our example it is Australia Central 6. In Image select Debian 10 \"Buster\" Gen 1 7. Size leave it as Standard 8. Under Administrator Account select either the use of SSH public key or Password 9. For Select inbound ports leave SSH(22) 10. Click Review and Create, then click Create
To get ION working you must enable the inbound traffic to port 1113 and port 4556 - IANA assigned default DTN TCP port. To enable inbound traffic in those ports, at the top right of your window, hit Home, then Virtual Machines. Click on the Virtual Machine you have just created. On the new loaded page, under Settings click Networking as shown in the image below.
On the networking page, click Add inbound port rule. Select Source as Any, on Source port ranges add the port numbers you want to allow inbound traffic, select the Protocol, the Action (Allow), and add a high Priority (e.g. 380). Give it a name and hit Add. You now can execute ION and the induct and outducts will work.
In this section, we assume that host 3 has an IP address of 10.0.0.3. Please modify this for your uses. Please note that in this tutorial we are not covering routing, therefore, host2 cannot communicate with host3. The routing tutorial can be found here.
This network is created by running the following command on host 1
ionstart -I host1.rc\nhost 2: ionstart -I host2.rc\nhost 3 ionstart -I host3.rc\nFor the configuration files host 1 and host 2, follow the examples given in the tutorial Running DTN on Google Cloud using a Two-Node Ring
. Remember to add contact, range, span, outduct and a plan for host 3. Below is the configuration file host3.rc.
The ionadmin configuration uses tcp from host 2 to host 3
## begin ionadmin \n# ionrc configuration file for host3 in a 3node tcp/ltp test.\n# This uses tcp from 1 to 3.\n# \n# Initialization command (command 1). \n# Set this node to be node 3 (as in ipn:3).\n# Use default sdr configuration (empty configuration file name '').\n1 3 ''\n# start ion node\ns\n# Add a contact.\n# It will start at +1 seconds from now, ending +3600 seconds from now.\n# It will connect node 3 to itself\n# It will transmit 100000 bytes/second.\na contact +1 +3600 3 3 100000\n\n# Add more contacts.\n# They will connect 2 to 3, 3 to 2, and 3 to itself\n# Note that contacts are unidirectional, so order matters.\na contact +1 +3600 3 2 100000\na contact +1 +3600 2 3 100000\na contact +1 +3600 2 2 100000\n\n# Add a range. This is the physical distance between nodes.\na range +1 +3600 3 3 1\n\n# Add more ranges.\na range +1 +3600 2 2 1\na range +1 +3600 2 3 1\n\n# set this node to consume and produce a mean of 1000000 bytes/second.\nm production 1000000\nm consumption 1000000\n## end ionadmin \nThe bpadmin configuration uses adds the endpoints and the protocol tcp. In the protocol section, it estimates transmission capacity assuming 1400 bytes of each frame (in this case, tcp on ethernet) for payload, and 100 bytes for overhead. The induct and outduct will listen on port 4556, the IANA assigned default DTN TCP convergence layer port. The induct itself is implemented by the tcpcli command and the outduct is implemented by the tcpclo
## begin bpadmin \n# bprc configuration file for host3 in a 3node test.\n# Initialization command (command 1).\n1\n\n# Add an EID scheme.\na scheme ipn 'ipnfw' 'ipnadminep'\n\n# Add endpoints.\na endpoint ipn:3.0 q\na endpoint ipn:3.1 q\na endpoint ipn:3.2 q\n\n# Add a protocol. \n# Add the protocol named tcp.\na protocol tcp 1400 100\n\n# Add an induct. (listen)\na induct tcp 10.0.0.3:4556 tcpcli\n\n# Add an outduct (send to yourself).\na outduct tcp 10.0.0.3:4556 tcpclo\n\n# Add an outduct. (send to host2)\na outduct tcp external_ip_of_host_2:4556 tcpclo\n\n# Start bundle protocol engine, also running all of the induct, outduct,\n# and administration programs defined above.\ns\n## end bpadmin \nThe ipnadmin configuration adds the egress plans (to host 3 itself and to host 2) using tcp.
## begin ipnadmin \n# ipnrc configuration file for host1 in the 3node tcp network.\n# Add an egress plan (to yourself).\na plan 2 tcp/10.0.0.3:4556\n# Add an egress plan (to the host 2).\na plan 2 tcp/external_IP_of_node_2:4556\n## end ipnadmin\nThe ionsecadmin configuration enables bundle security
## begin ionsecadmin\n1\n## end ionsecadmin\nNote: place this in a file named host3.rc
## begin ionadmin \n# ionrc configuration file for host3 in a 3node tcp/ltp test.\n# This uses tcp from 1 to 3.\n# \n# Initialization command (command 1). \n# Set this node to be node 3 (as in ipn:3).\n# Use default sdr configuration (empty configuration file name '').\n1 3 ''\n# start ion node\ns\n# Add a contact.\n# It will start at +1 seconds from now, ending +3600 seconds from now.\n# It will connect node 3 to itself\n# It will transmit 100000 bytes/second.\na contact +1 +3600 3 3 100000\n\n# Add more contacts.\n# They will connect 2 to 3, 3 to 2, and 3 to itself\n# Note that contacts are unidirectional, so order matters.\na contact +1 +3600 3 2 100000\na contact +1 +3600 2 3 100000\na contact +1 +3600 2 2 100000\n\n# Add a range. This is the physical distance between nodes.\na range +1 +3600 3 3 1\n\n# Add more ranges.\na range +1 +3600 2 2 1\na range +1 +3600 2 3 1\n\n# set this node to consume and produce a mean of 1000000 bytes/second.\nm production 1000000\nm consumption 1000000\n## end ionadmin \n\n## begin bpadmin \n# bprc configuration file for host3 in a 3node test.\n# Initialization command (command 1).\n1\n\n# Add an EID scheme.\na scheme ipn 'ipnfw' 'ipnadminep'\n\n# Add endpoints.\na endpoint ipn:3.0 q\na endpoint ipn:3.1 q\na endpoint ipn:3.2 q\n\n# Add a protocol. \n# Add the protocol named tcp.\na protocol tcp 1400 100\n\n# Add an induct. (listen)\na induct tcp 10.0.0.3:4556 tcpcli\n\n# Add an outduct (send to yourself).\na outduct tcp 10.0.0.3:4556 tcpclo\n\n# Add an outduct. (send to host2)\na outduct tcp external_ip_of_host_2:4556 tcpclo\n\n# Start bundle protocol engine, also running all of the induct, outduct,\n# and administration programs defined above.\ns\n## end bpadmin \n\n## begin ipnadmin \n# ipnrc configuration file for host1 in the 3node tcp network.\n# Add an egress plan (to yourself).\na plan 2 tcp/10.0.0.3:4556\n# Add an egress plan (to the host 2).\na plan 2 tcp/external_IP_of_node_2:4556\n## end ipnadmin\n\n## begin ionsecadmin\n1\n## end ionsecadmin\nThis project has been developed by Dr Lara Suzuki, a visiting researcher at NASA JPL.
"},{"location":"community/dtn-gcp-main/ION-One-Node-on-Cloud-Linux-VM/#introduction","title":"Introduction","text":"In this project we demonstrate how to run DTN on a cloud VM using NASA's implementation of the bundle protocol - ION. DTN stands for delay-tolerant and disruption-tolerant networks.
\"It is an evolution of the architecture originally designed for the Interplanetary Internet, a communication system envisioned to provide Internet-like services across interplanetary distances in support of deep space exploration\" Cerf et al, 2007.
The ION (interplanetary overlay network) software is a suite of communication protocol implementations designed to support mission operation communications across an end-to-end interplanetary network, which might include on-board (flight) subnets, in-situ planetary or lunar networks, proximity links, deep space links, and terrestrial internets.
"},{"location":"community/dtn-gcp-main/ION-One-Node-on-Cloud-Linux-VM/#getting-started-with-cloud-linux-vms","title":"Getting Started with Cloud Linux VMs","text":"On your preferred Cloud provider dashboard, create a Linux VM (e.g. Debian).
When prompted, select the reagion closest to you. If you are prompted to select the machine type, select the configuration that will suit your needs. I have selected the a machine which has 2 virtual CPUs and 4 GB memory.
For boot disk, in this tutorial we are using Debian GNU/Linux 10 (buster). In firewall configurations, I have selected it Allow HTTP and HTTPS.
Once the VM is started you can SSH directly into the VM.
Mac and Linux support SSH connection natively. You just need to generate an SSH key pair (public key/private key) to connect securely to the virtual machine.
To generate the SSH key pair to connect securely to the virtual machine, follow these steps:
ssh-keygen -t rsa . ENTER to accept the default locationcat ~/.ssh/id_rsa.pub . Back in the Cloud VM tools, follow your provider's direction on how to SSH into the VM. If you are requested to provide your SSH Keys, locate the SSH key file in your computer and inform it here.
Now you can just open your terminal on your Mac or Linux machine and type ssh IP.IP.IP.IP and you will be on the VM (IP.IP.IP.IP is the external IP of the VM).
This example uses ION version 4.0.1, which can be downloaded here. ION 4.0.1 uses the version 7 of the Bundle Protocol.
On your VM execute the following commands
$ sudo apt update\n$ sudo apt install build-essential -y\n$ sudo apt-get install wget -y\n$ wget https://sourceforge.net/projects/ion-dtn/files/ion-open-source-4.0.1.tar.gz/download\n$ tar xzvf download\nFollow the standard autoconf method for compiling the project. In the base ION directory run:
$ ./configure\n$ make\n````\nFinally, install (requires root privileges):\nFor Linux based systems, you may need to run sudo ldconfig with no arguments after install.
The following tools are a few examples of programs availale to you after ION is built:
1. Daemon and Configuration: - ionadmin is the administration and configuration interface for the local ION node contacts and manages shared memory resources used by ION. - ltpadmin is the administration and configuration interface for LTP operations on the local ION node. - bsspadmin is the administrative interface for operations of the Bundle Streaming Service Protocol on the local ion node. - bpadmin is the administrative interface for bundle protocol operations on the local ion node. - ipnadmin is the administration and configuration interface for the IPN addressing system and routing on the ION node. (ipn:) - ionstart is a script which completely configures an ION node with the proper configuration file(s). - ionstop is a script which cleanly shut down all of the daemon processes. - killm is a script which releases all of the shared-memory resources that had been allocated to the state of the node. This actually destroys the node and enables a subsequent clean new start (the \u201cionstart\u201d script) to succeed. - ionscript is a script which aides in the creation and management of configuration files to be used with ionstart.
2. Simple Sending and Receiving: - bpsource and bpsink are for testing basic connectivity between endpoints. bpsink listens for and then displays messages sent by bpsource. - bpsendfile and bprecvfile are used to send files between ION nodes.
3. Testing and Benchmarking: - bpdriver benchmarks a connection by sending bundles in two modes: request-response and streaming. - bpecho issues responses to bpdriver in request-response mode. - bpcounter acts as receiver for streaming mode, outputting markers on receipt of data from bpdriver and computing throughput metrics.
4. Logging: - By default, the administrative programs will all trigger the creation of a log file called ion.log in the directory where the program is called. This means that write-access in your current working directory is required. The log file itself will contain the expected log information from administrative daemons, but it will also contain error reports from simple applications such as bpsink.
Below we present the configuration files that you should be aware and configure for ION to execute correctly.
ionadmin's configuration file, assigns an identity (node number) to the node, optionally configures the resources that will be made available to the node, and specifies contact bandwidths and one-way transmission times. Specifying the \"contact plan\" is important in deep-space scenarios where the bandwidth must be managed and where acknowledgments must be timed according to propagation delays. It is also vital to the function of contact-graph routing - How To
ltpadmin's configuration file, specifies spans, transmission speeds, and resources for the Licklider Transfer Protocol convergence layer - How To
bpadmin's configuration file, specifies all of the open endpoints for delivery on your local end and specifies which convergence layer protocol(s) you intend to use. With the exception of LTP, most convergence layer adapters are fully configured in this file - How To
ipnadmin's configuration file, maps endpoints at \"neighboring\" (topologically adjacent, directly reachable) nodes to convergence-layer addresses. This file populates the ION analogue to an ARP cache for the \"ipn\" naming scheme - How To
ionsecadmin's configuration file, enables bundle security to avoid error messages in ion.log - How To
Assuming no errors occur with the configuration files above, we are now ready to test loopback communications, and also learn how to properly stop ION nodes. The below items are covered in this How To page.
A script has been created which allows a more streamlined configuration and startup of an ION node. This script is called ionstart, and it has the following syntax. Don't run it yet; we still have to configure it!
ionstart -I <rc filename >\nfilename: This is the name for configuration file which the script will attempt to use for the various configuration commands. The script will perform a sanity check on the file, splitting it into command sections appropriate for each of the administration programs. Configuration information (such as routes, connections, etc) can be specified one of two ways for any of the individual administration programs:
(Recommended) Creating a configuration file and passing it to ionadmin, bpadmin, ipnadmin, ltpadmin, etc. either directly or via the ionstart helper script.
Assuming no errors occur with the configuration above, we are now ready to test loopback communications. In one terminal, we have to run the start script alongside the configuration files.
ionstart -i host1.ionrc -l host1.ltprc -b host1.bprc -p host1.ipnrc\nThis command will run the appropriate administration programs, in order, with the appropriate configuration files. Don't worry that the command is lengthy and unwieldly; we will show you how to make a more clean single configuration file later. The image below illustrates the start of the administration programs.
Once the daemon is started, run:
bpsink ipn:1.1 &\nThis will begin constantly listening on the Endpoint ID with the endpoint_number 1 on service_number 1, which is used for testing.
Now run the command:
bpsource ipn:1.1\nThis will begin sending messages you type to the Endpoint ID ipn:1.1, which is currently being listened to by bpsink. Type messages into bpsource, press enter, and see if they are reported by bpsink. In the example below I am using the Endpoint ID ipn:2.1.
"},{"location":"community/dtn-gcp-main/Running-ION/#stopping-the-daemon","title":"Stopping the Daemon","text":"As the daemon launches many ducts and helper applications, it can be complicated to turn it all off. The script similar to ionstart exists called ionstop, which tears down the ion node in one step. You can call it like so:
ionstop\nionstop script is shown below. # shell script to stop node\n#!/bin/bash\nbpadmin .\nsleep 1\nltpadmin .\nsleep 1\nionadmin .\nAfter stopping the daemon, you can start fresh with a brand-new node. To do that, you first need to run the killm script (to destroy all of the persistent state objects in shared memory); after that, you can run your ionstart script again, whether with changes or not. Do remember that the ion.log file is still present, and will just keep growing as you experiment with ION. You can of course periodically delete entries out of the ion.log file.
To create a single file host1.rc out of the various configuration files defined in the previous section, run this command:
ionscript -i host1.ionrc -p host1.ipnrc -l host1.ltprc -b host1.bprc -O host1.rc\nOnce you have a single configuration file, starting the ION node is a single command:
ionstart -I host1.rc\nAssuming no errors occur with the configuration files above, we are now ready to test a Loopback communication, and also learn how to properly stop the ION node. The single rc file for host 1 can be found here.
The execution of the host should be performed using the command
$ ionstart -I host1.rc\nThe image below illustrates the loopback communication using bpsink and bpsource.
To stop ION in the VM instance, use the command
$ ionstop. \nGiven to bpadmin either as a file or from the daemon command line, this file configures the endpoints through which this node's Bundle Protocol Agent (BPA) will communicate. We will assume the local BPA's node number is 1; as for LTP, in ION node numbers are used to identify bundle protocol agents.
"},{"location":"community/dtn-gcp-main/bp-config/#initialise-the-bundle-protocol","title":"Initialise the bundle protocol","text":"1\n````. \n\n`1` refers to this being the initialization or ''first'' command.\n\n## Add support for a new Endpoint Identifier (EID) scheme\n`a` means that this command will add something.\n\n`scheme` means that this command will add a scheme.\n\n`ipn` is the name of the scheme to be added.\n\n`'ipnfw'` is the name of the IPN scheme's forwarding engine daemon.\n\n`'ipnadminep'` is the name of the IPN scheme's custody transfer management daemon.\n\n## Establishes the BP node's membership in a BP endpoint\n`a` means that this command will add something.\n\n`endpoint` means that this command adds an endpoint.\n\n`ipn` is the scheme name of the endpoint.\n\n`1.0` is the scheme-specific part of the endpoint. For the IPN scheme the scheme-specific part always has the form nodenumber:servicenumber. Each node must be a member of the endpoint whose node number is the node's own node number and whose service number is 0, indicating administrative traffic.\n\n`q` means that the behavior of the engine, upon receipt of a new bundle for this endpoint, is to queue it until an application accepts the bundle. The alternative is to silently discard the bundle if no application is actively listening; this is specified by replacing q with x.\n\n\n## Specify two more endpoints that will be used for test traffic\n## Add support for a convergence-layer protocol\n`a` means that this command will add something.\n\n`protocol` means that this command will add a convergence-layer protocol.\n\n`ltp` is the name of the convergence-layer protocol.\n\n`1400` is the estimated size of each convergence-layer protocol data unit (in bytes); in this case, the value is based on the size of a UDP/IP packet on Ethernet.\n\n`100` is the estimated size of the protocol transmission overhead (in bytes) per convergence-layer procotol data unit sent.\n\n\n## Add an induct, through which incoming bundles can be received from other nodes\n`a` means that this command will add something.\n\n`induct` means that this command will add an induct.\n\n`ltp` is the convergence layer protocol of the induct.\n\n`1` is the identifier of the induct, in this case the ID of the local LTP engine.\n\n`ltpcli` is the name of the daemon used to implement the induct.\n\n\n\n## Add an outduct, through which outgoing bundles can be sent to other nodes\n`a` means that this command will add something.\n\n`outduct` means that this command will add an outduct.\n\n`ltp` is the convergence layer protocol of the outduct.\n\n`1` is the identifier of the outduct, the ID of the convergence-layer protocol induct of some remote node. \n\n`ltpclo` is the name of the daemon used to implement the outduct.\n\n\n## Start the bundle engine including all daemons for the inducts and outducts\n## Final configuration file - `host1.bprc`\n1 a scheme ipn 'ipnfw' 'ipnadminep' a endpoint ipn:1.0 q a endpoint ipn:1.1 q a endpoint ipn:1.2 q a protocol ltp 1400 100 a induct ltp 1 ltpcli a outduct ltp 1 ltpclo s
"},{"location":"community/dtn-gcp-main/bp-config/#end-bpadmin","title":"end bpadmin","text":"````
"},{"location":"community/dtn-gcp-main/host1-start-script/","title":"ION Start Script Example","text":"Note: place this in a file named host1.rc
## begin ionadmin\n1 1 ''\ns\n# Define contact plan\na contact +1 +3600 1 1 100000\n\n# Define 1sec OWLT between nodes\na range +1 +3600 1 1 1\nm production 1000000\nm consumption 1000000\n## end ionadmin\n\n## begin ltpadmin\n1 32\na span 1 32 32 1400 10000 1 'udplso 127.0.0.1:1113' 300\n# Start listening for incoming LTP traffic - assigned to the IP internal\ns 'udplsi 127.0.0.1:1113'\n## end ltpadmin\n\n## begin bpadmin\n1\n# Use the ipn eid naming scheme\na scheme ipn 'ipnfw' 'ipnadminep'\n# Create a endpoints\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n# Define ltp as the protocol used\na protocol ltp 1400 100\n# Listen \na induct ltp 1 ltpcli\n# Send to yourself\na outduct ltp 1 ltpclo\ns\n## end bpadmin\n\n## begin ipnadmin\n# Send to yourself\na plan 1 ltp/1\n## end ipnadmin\n\n## begin ionsecadmin\n# Enable bundle security to avoid error messages in ion.log\n1\n## end ionsecadmin\nGiven to ionadmin either as a file or from the daemon command line, this file configures contacts for the ION node. We will assume that the local node's identification number is 1.
This file specifies contact times and one-way light times between nodes. This is useful in deep-space scenarios: for instance, Mars may be 20 light-minutes away, or 8. Though only some transport protocols make use of this time (currently, only LTP), it must be specified for all links nonetheless. Times may be relative (prefixed with a + from current time) or absolute. Absolute times, are in the format yyyy/mm/dd-hh:mm:ss. By default, the contact-graph routing engine will make bundle routing decisions based on the contact information provided.
The configuration file lines are as follows:
"},{"location":"community/dtn-gcp-main/ion-config/#initialize-the-ion-node-to-be-node-number-1","title":"Initialize the ion node to be node number 1","text":"1 1 ''\n1 refers to this being the initialization or first command.
1 specifies the node number of this ion node. (IPN node 1).
'' specifies the name of a file of configuration commands for the node's use of shared memory and other resources (suitable defaults are applied if you leave this argument as an empty string).
s
This will start the ION node. It mostly functions to officially \"start\" the node in a specific instant; it causes all of ION's protocol-independent background daemons to start running.
"},{"location":"community/dtn-gcp-main/ion-config/#specify-a-transmission-opportunity","title":"Specify a transmission opportunity","text":"a contact +1 +3600 1 1 100000\nspecifies a transmission opportunity for a given time duration between two connected nodes (or, in this case, a loopback transmission opportunity).
a adds this entry in the configuration table.
contact specifies that this entry defines a transmission opportunity.
+1 is the start time for the contact (relative to when the s command is issued).
+3600 is the end time for the contact (relative to when the s command is issued).
1 is the source node number.
1 is the destination node number.
100000 is the maximum rate at which data is expected to be transmitted from the source node to the destination node during this time period (here, it is 100000 bytes / second).
a range +1 +3600 1 1 1\nspecifies a distance between nodes, expressed as a number of light seconds, where each element has the following meaning:
a adds this entry in the configuration table.
range declares that what follows is a distance between two nodes.
+1 is the earliest time at which this is expected to be the distance between these two nodes (relative to the time s was issued).
+3600 is the latest time at which this is still expected to be the distance between these two nodes (relative to the time s was issued).
1 is one of the two nodes in question.
1 is the other node.
1 is the distance between the nodes, measured in light seconds, also sometimes called the \"one-way light time\" (here, one light second is the expected distance).
m production 1000000\nm specifies that this is a management command.
production declares that this command declares the maximum rate of data production at this ION node.
1000000 specifies that at most 1000000 bytes/second will be produced by this node.
m consumption 1000000\nm specifies that this is a management command.
consumption declares that this command declares the maximum rate of data consumption at this ION node.
1000000 specifies that at most 1000000 bytes/second will be consumed by this node.
host1.ionrc","text":"## begin ionadmin\n1 1 ''\ns\na contact +1 +3600 1 1 100000\na range +1 +3600 1 1 1\nm production 1000000\nm consumption 1000000\n## end ionadmin\nThe ionsecadmin section is used to enable bundle security. Adding it will also avoid error messages in ion.log.
1 enables the bundle security
ionsec.rc","text":"## begin ionsecadmin\n1\n## end ionsecadmin\nAs noted earlier, this file is used to build ION's analogue to an ARP cache, a table of egress plans. It specifies which outducts to use in order to forward bundles to the local node's neighbors in the network. Since we only have one outduct, for forwarding bundles to one place (the local node), we only have one egress plan.
a plan 1 ltp/1\na means this command adds something. plan means this command adds an egress plan. 1 is the node number of the remote node. In this case, that is the local node's own node number; we're configuring for loopback. ltp/1 is the identifier of the outduct through which to transmit bundles in order to convey them to this ''remote'' node.
host1.ipnrc","text":"## begin ipnadmin\na plan 1 ltp/1\n## end ipnadmin\nGiven to ltpadmin as a file or from the command line, this file configures the LTP engine itself. We will assume the local IPN node number is 1; in ION, node numbers are used as the LTP engine numbers.
"},{"location":"community/dtn-gcp-main/ltp-config/#initialize-the-ltp-engine","title":"Initialize the LTP engine","text":"1 32 \n1 refers to this being the initialization or ''first'' command.
32 is an estimate of the maximum total number of LTP ''block'' transmission sessions - for all spans - that will be concurrently active in this LTP engine. It is used to size a hash table for session lookups.
a span 1 32 32 1400 10000 1 'udplso localhost:1113'\na indicates that this will add something to the engine.
span indicates that an LTP span will be added.
1 is the engine number for the span, the number of the remote engine to which LTP segments will be transmitted via this span. In this case, because the span is being configured for loopback, it is the number of the local engine, i.e., the local node number.
32 specifies the maximum number of LTP ''block'' transmission sessions that may be active on this span. The product of the mean block size and the maximum number of transmission sessions is effectively the LTP flow control ''window'' for this span: if it's less than the bandwidth delay product for traffic between the local LTP engine and this spa's remote LTP engine then you'll be under-utilizing that link. We often try to size each block to be about one second's worth of transmission, so to select a good value for this parameter you can simply divide the span's bandwidth delay product (data rate times distance in light seconds) by your best guess at the mean block size.
The second 32 specifies the maximum number of LTP ''block'' reception sessions that may be active on this span. When data rates in both directions are the same, this is usually the same value as the maximum number of transmission sessions.
1400 is the number of bytes in a single segment. In this case, LTP runs atop UDP/IP on ethernet, so we account for some packet overhead and use 1400.
1000 is the LTP aggregation size limit, in bytes. LTP will aggregate multiple bundles into blocks for transmission. This value indicates that the block currently being aggregated will be transmitted as soon as its aggregate size exceeds 10000 bytes.
1 is the LTP aggregation time limit, in seconds. This value indicates that the block currently being aggregated will be transmitted 1 second after aggregation began, even if its aggregate size is still less than the aggregation size limit.
'udplso localhost:1113' is the command used to implement the link itself. The link is implemented via UDP, sending segments to the localhost Internet interface on port 1113 (the IANA default port for LTP over UDP).
s 'udplsi localhost:1113'\ns starts the ltp engine.
'udplsi localhost:1113' is the link service input task. In this case, the input ''duct' is a UDP listener on the local host using port 1113.
host1.ltprc","text":"## begin ltpadmin\n1 32\na span 1 32 32 1400 10000 1 'udplso localhost:1113'\ns 'udplsi localhost:1113'\n## end ltpadmin\nThis project has been developed by Dr Lara Suzuki, a visiting Researcher at NASA JPL.
NOTE to reader: After ION 4.1, the imc multicasting implementation has changed its configuration and no longer requires the imcadmin program for configuration. Please see ION 4.1.2 man pages for more information. This tutorial is based on earlier version of ION's imc multicasting. The proper adaptation to latest ION version is left as an exercise for the reader.
Multicasting over the Interplanetary Internet uses version 7 of the Bundle Protocol. In a multicasting scenario, we send messages to a multicasting end point and the messages are propagated across the nodes of the network, removing the need to send data to individual nodes one at a time.
Use multicasting when the messages you are sending should be delivered to all the known nodes of the network.
"},{"location":"community/dtn-multicasting-main/Multicasting-over-ION/#executing-multicasting","title":"Executing Multicasting","text":"This tutorial presents the configurations of one host. To create additional hosts, you just need to copy the same configurations and alter the configuraation documents with the appropriate data as explained in our first tutorial.
To execute multicasting:
Execute the \"execute\" file to get ion started
$ ./execute\nWhen performing multicasting, the eid naming scheme is imc 'imcfw' 'imcadminep'
Once ION is started you can run the commands to open bpsink to listen to packages sent over DTN. Simply run on your terminal the command below. This command will leave bpsink running on the background. In our configuration file host.bprc.2 we define interplanetary multicasting EID as 19.0. Messages sent to this EID will be delivered to all the hosts running the same configuration.
$ bpsink imc:19.0 &\n$ bpsendfile ipn:1.1 imc:19.0 image.jpeg\n$ bprecvfile imc:19.0 1\nIn this section I will give a little overview of the basic concepts of the Interplanetary Overlay Network from Nasa.
Digital communication between interplanetary spacecraft and space flight control centres on Earth is subject to constraints that differ in some ways from those that characterize terrestrial communications.
"},{"location":"community/dtn-multicasting-main/Multicasting-over-ION/#basic-concepts-of-interplanetary-overlay-network","title":"Basic Concepts of Interplanetary Overlay Network","text":"Delay-Disruption Tolerant Networking (DTN) is NASA\u2019s solution for reliable, automated network communications in space missions. The DTN2 reference implementation of the Delay-Tolerant Networking (DTN) RFC 4838 and the current version of the Bundle Protocol (BP) is the foundation for a wide range of current DTN industrial and research applications.
The Jet Propulsion Laboratory (JPL) has developed an alternative implementation of BP, named \u201cInterplanetary Overlay Network\u201d (ION). ION addresses those constraints and enables delay-tolerant network communications in interplanetary mission operations.
"},{"location":"community/dtn-multicasting-main/Multicasting-over-ION/#space-communication-challenges","title":"Space communication challenges","text":"To give you a sense of signal propagation -> send a message and receive a response (RRT) back: 1. A typical round trip time between two points on the internet is 100ms to 300ms 2. Distance to ISS (throught TDRS - Tracking and Data Relay Satellite) approx 71322km -> round trip time is approx 1200 ms on Ku Link 3. Distance to the moon approx 384400 km - rrt 2560 ms -2,5 seconds 4. Minimun distance to mars: approx 54.6 million km - rrt of approx 6 min 5. Average distance to mars: approx 225 million km - rrt of approx 25 mins 6. Farthest distance to mars: approx 401 million km - rtt of approc 44.6 min
The internet architecture is based on the assumption that network nodes are continuously connected. The following assumptions are valid for the terrestrial Internet architecture: - Networks have short signal propagation delays - Data links are symmetric and bidirectional - Bit error rates are low
These assumptions are not valid in the space environment - a new sort of network is needed. In a space environment: - Connections can be routinely interrupted - Interplanetary distances impose delays - Link data rates are often asymmetric and some links are simplex - Bit error rates can be very high
To communicate across these vast distances, NASA manages three communication networks consisting of distributed ground stations and space relay satellites for data transmission and reception that support both NASA and non-NASA missions. These are: - the Deep Space Network (DSN) - the Near Earth Network (NEN) - the Space Network (SN).
Communication opportunities are scheduled, based on orbit dynamics and operation plans. Sometimes a spacecraft is on the far side of a planet and you cannot communicate with it. Transmission and reception episodes are individually configured, started and ended by command. Reliability over deeps space links is by management: on loss of data, command retransmission. More recently for Mars missions we have managed forwarding through relay points so that data from these surface vehicles is relayed thought Odyssey and other orbiting mars vehicles.
"},{"location":"community/dtn-multicasting-main/Host1/execute/","title":"Execute","text":"#!/usr/bin/bash\necho \"starting ION...\"\nionadmin host.ionrc\n./ionstart\n## begin bpadmin\n1\n# Use the ipn eid naming scheme\na scheme ipn 'ipnfw' 'ipnadminep'\n# Create a endpoints\na endpoint ipn:1.0 q\na endpoint ipn:1.1 q\na endpoint ipn:1.2 q\n# Define ltp as the protocol used\na scheme imc 'imcfw' 'imcadminep'\n#a endpoint imc:19.0 q\na protocol ltp 1400 100\n# Listen\na induct ltp 1 ltpcli\n# Send to yourself\na outduct ltp 1 ltpclo\n# Send to server2\na outduct ltp 2 ltpclo\na outduct ltp 3 ltpclo\nw 1\ns\n## end bpadmin\na endpoint imc:19.0 q\n## begin ionadmin\n1 1 ''\ns\n# Define contact plan\na contact +1 +3600 1 1 100000\na contact +1 +3600 1 2 100000\na contact +1 +3600 2 1 100000\na contact +1 +3600 2 2 100000\n\n# Define 1sec OWLT between nodes\na range +1 +3600 1 1 1\na range +1 +3600 1 2 1\na range +1 +3600 2 1 1\na range +1 +3600 2 2 1\nm production 1000000\nm consumption 1000000\n## end ionadmin\n1\n## begin ipnadmin\n# Send to yourself#\na plan 1 ltp/1\n# Send to server 2\na plan 2 ltp/2\n## end ipnadmin\n1 32\n#a span peer_engine_nbr\n# [queuing_latency]\n# Create a span to tx\na span 1 32 32 1400 10000 1 'udplso external_ip_host1:1113' 300\na span 2 32 32 1400 10000 1 'udplso external_ip_host2:1113' 300\n# Start listening for incoming LTP traffic - assigned to the IP internal\ns 'udplsi internal_ip:1113'\n## end ltpadmin\n#!/bin/bash\n# shell script to get node running\n\nionsecadmin host.ionsecrc\nsleep 1\nltpadmin host.ltprc\nsleep 1\nbpadmin host.bprc.1\nsleep 1\nipnadmin host.ipnrc\nsleep 2\nbpadmin host.bprc.2\necho \"Started Host 1.\"\n#!/bin/bash\n#\n# ionstop\n# David Young\n# Aug 20, 2008\n#\n# will quickly and completely stop an ion node.\n\nION_OPEN_SOURCE=1\n\necho \"IONSTOP will now stop ion and clean up the node for you...\"\nbpversion\nif [ $? -eq 6 ]; then\necho \"acsadmin .\"\nacsadmin .\nsleep 1\nfi\necho \"bpadmin .\"\nbpadmin .\nsleep 1\nif [ \"$ION_OPEN_SOURCE\" == \"1\" ]; then\necho \"cfdpadmin .\"\ncfdpadmin .\nsleep 1\nfi\necho \"ltpadmin .\"\nltpadmin .\nsleep 1\necho \"ionadmin .\"\nionadmin .\nsleep 1\necho \"killm\"\nkillm\necho \"ION node ended. Log file: ion.log\"\nThis project has been developed by Dr Lara Suzuki, a visiting researcher at NASA JPL.
In this tutorial I will demonstrate how to connect use GCP Video Intelligence over the Interplanetary Internet.
"},{"location":"community/dtn-video-intelligence-main/Video-Intelligence/#setting-up-the-interplanetary-internet","title":"Setting up the Interplanetary Internet","text":"Please follow tutorial Multicasting over the Interplanetary Internet to set up your nodes.
As noted in the multicasting tutorial, current ION imc multicasting operation has been updated and adaptation is required to make this tutorial work.
Once the hosts are configured you can run the command to get ionstart running:
$ ./execute\nCloud Video Intelligence API allows you to process frames of videos with a simple API call from anywhere. With GCP Video Intelligence you can:
Quickly understand video content by encapsulating powerful machine learning models in an easy to use REST API.
Accurately annotate videos stored in Google Cloud Storage with video and frame-level (1 fps) contextual information.
Make sense of large amount of video files in a very short amount of time.
Utilise the technology via an easy to use REST API to analyze videos stored anywhere, or integrate with your image storage on Google Cloud Storage.
In the Interplanetary host you choose to run the excecution of the Video Intelligence API, install the library:
$ pip install --upgrade google-cloud-videointelligence\nTo use the Video Intelligence API you must be Authenticated. To do that, please follow the instructions in this GCP Tutorial. After you've created your service account, Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS.
$ export GOOGLE_APPLICATION_CREDENTIALS=\"/home/user/Downloads/my-key.json\"\nOn the host that will run the Video Intelligence, execute:
python\npython3 video_processing.py\nimport argparse\nfrom google.cloud import videointelligence\n\nvideo_client = videointelligence.VideoIntelligenceServiceClient()\nfeatures = [videointelligence.Feature.LABEL_DETECTION]\noperation = video_client.annotate_video(\nrequest={\"features\": features, \"input_uri\":'gs://test_bucket_pi/video1_pi.mp4'})\nprint(\"Processing video for label annotations:\")\n\nresult = operation.result(timeout=90)\nprint(\"\\nFinished processing.\")\n\nsegment_labels = result.annotation_results[0].segment_label_annotations\nfor i, segment_label in enumerate(segment_labels):\n print(\"Video label description: {}\".format(segment_label.entity.description))\n for category_entity in segment_label.category_entities:\n print( \"\\tLabel category description: {}\".format(category_entity.description)\n )\n\n for i, segment in enumerate(segment_label.segments):\n start_time = (\n segment.segment.start_time_offset.seconds\n + segment.segment.start_time_offset.microseconds / 1e6\n )\n end_time = (\n segment.segment.end_time_offset.seconds\n + segment.segment.end_time_offset.microseconds / 1e6\n )\n positions = \"{}s to {}s\".format(start_time, end_time)\n confidence = segment.confidence\n print(\"\\tSegment {}: {}\".format(i, positions))\n print(\"\\tConfidence: {}\".format(confidence))\n print(\"\\n\")\nams - CCSDS Asynchronous Message Service(AMS) communications library
"},{"location":"man/ams/ams/#synopsis","title":"SYNOPSIS","text":"#include \"ams.h\"\n\ntypedef void (*AmsMsgHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int continuumNbr,\n int unitNbr,\n int moduleNbr,\n int subjectNbr,\n int contentLength,\n char *content,\n int context,\n AmsMsgType msgType,\n int priority,\n unsigned char flowLabel);\n\ntypedef void (*AmsRegistrationHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int roleNbr);\n\ntypedef void (*AmsUnregistrationHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr);\n\ntypedef void (*AmsInvitationHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int domainRoleNbr,\n int domainContinuumNbr,\n int domainUnitNbr,\n int subjectNbr,\n int priority,\n unsigned char flowLabel,\n AmsSequence sequence,\n AmsDiligence diligence);\n\ntypedef void (*AmsDisinvitationHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int domainRoleNbr,\n int domainContinuumNbr,\n int domainUnitNbr,\n int subjectNbr);\n\ntypedef void (*AmsSubscriptionHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int domainRoleNbr,\n int domainContinuumNbr,\n int domainUnitNbr,\n int subjectNbr,\n int priority,\n unsigned char flowLabel,\n AmsSequence sequence,\n AmsDiligence diligence);\n\ntypedef void (*AmsUnsubscriptionHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int unitNbr,\n int moduleNbr,\n int domainRoleNbr,\n int domainContinuumNbr,\n int domainUnitNbr,\n int subjectNbr);\n\ntypedef void (*AmsUserEventHandler)(AmsModule module,\n void *userData,\n AmsEvent *eventRef,\n int code,\n int dataLength,\n char *data);\n\ntypedef void (*AmsMgtErrHandler)(void *userData,\n AmsEvent *eventRef);\n\ntypedef struct\n{\n AmsMsgHandler msgHandler;\n void *msgHandlerUserData;\n AmsRegistrationHandler registrationHandler;\n void *registrationHandlerUserData;\n AmsUnregistrationHandler unregistrationHandler;\n void *unregistrationHandlerUserData;\n AmsInvitationHandler invitationHandler;\n void *invitationHandlerUserData;\n AmsDisinvitationHandler disinvitationHandler;\n void *disinvitationHandlerUserData;\n AmsSubscriptionHandler subscriptionHandler;\n void *subscriptionHandlerUserData;\n AmsUnsubscriptionHandler unsubscriptionHandler;\n void *unsubscriptionHandlerUserData;\n AmsUserEventHandler userEventHandler;\n void *userEventHandlerUserData;\n AmsMgtErrHandler errHandler;\n void *errHandlerUserData;\n} AmsEventMgt;\n\ntypedef enum\n{\n AmsArrivalOrder = 0,\n AmsTransmissionOrder\n} AmsSequence;\n\ntypedef enum\n{\n AmsBestEffort = 0,\n AmsAssured\n} AmsDiligence;\n\ntypedef enum\n{\n AmsRegistrationState,\n AmsInvitationState,\n AmsSubscriptionState\n} AmsStateType;\n\ntypedef enum\n{\n AmsStateBegins = 1,\n AmsStateEnds\n} AmsChangeType;\n\ntypedef enum\n{\n AmsMsgUnary = 0,\n AmsMsgQuery,\n AmsMsgReply,\n AmsMsgNone\n} AmsMsgType;\n\n[see description for available functions]\nThe ams library provides functions enabling application software to use AMS to send and receive brief messages, up to 65000 bytes in length. It conforms to AMS Blue Book, including support for Remote AMS (RAMS).
In the ION implementation of RAMS, the \"RAMS network protocol\" may be either the DTN Bundle Protocol (RFC 5050) or -- mainly for testing purposes -- the User Datagram Protocol (RFC 768). BP is the default. When BP is used as the RAMS network protocol, endpoints are by default assumed to conform to the \"ipn\" endpoint identifier scheme with node number set to the AMS continuum number and service number set to the AMS venture number.
Note that RAMS functionality is enabled by instantiating a ramsgate daemon, which is simply an AMS application program that acts as a gateway between the local AMS message space and the RAMS network.
AMS differs from other ION packages in that there is no utilization of non-volatile storage (aside from the BP functionality in RAMS, if applicable). Since there is no non-volatile AMS database, there is no AMS administration program and there are no library functions for attaching to or detaching from such a database. AMS is instantiated by commencing operation of the AMS real-time daemon amsd; once amsd is running, AMS application programs (\"modules\") can be started. All management of AMS operational state is performed automatically in real time.
However, amsd and the AMS application programs all require access to a common store of configuration data at startup in order to load their Management Information Bases. This configuration data must reside in a readable file, which may take either of two forms: a file of XML statements conforming to the scheme described in the amsxml(5) man page, or a file of simple but less powerful configuration statements as described in the amsrc(5) man page. The amsxml alternative requires that the expat XML parsing system be installed; the amsrc alternative was developed to simplify deployment of AMS in environments in which expat is not readily supported. Selection of the configuration file format is a compile-time decision, implemented by setting (or not setting) the -DNOEXPAT compiler option.
The path name of the applicable configuration file may be passed as a command-line parameter to amsd and as a registration function parameter by any AMS application program. Note, though, that ramsgate and the AMS test and utility programs included in ION always assume that the configuration file resides in the current working directory and that it is named \"mib.amsrc\" if AMS was built with -DNOEXPAT, \"amsmib.xml\" otherwise.
The transport services that are made available to AMS communicating entities are declared by the transportServiceLoaders array in the libams.c source file. This array is fixed at compile time. The order of preference of the transport services in the array is hard-coded, but the inclusion or omission of individual transport services is controlled by setting compiler options. The \"udp\" transport service -- nominally the most preferred because it imposes the least processing and transmission overhead -- is included by setting the -DUDPTS option. The \"dgr\" service is included by setting the -DDGRTS option. The \"vmq\" (VxWorks message queue) service, supported only on VxWorks, is included by setting the -DVMQTS option. The \"tcp\" transport service -- selected only when its quality of service is required -- is included by setting the -DTCPTS option.
The operating state of any single AMS application program is managed in an opaque AmsModule object. This object is returned when the application begins AMS operations (that is, registers) and must be provided as an argument to most AMS functions.
int ams_register(char *mibSource, char *tsorder, char *applicationName, char *authorityName, char *unitName, char *roleName, AmsModule *module)
Registers the application within a cell (identified by unitName) of a message space that is that portion of the venture identified by applicationName and authorityName that runs within the local AMS continuum. roleName identifies the role that this application will perform in this venture. The operating state of the registered application is returned in module.
The application module's identifying parameters are validated against the configuration information in the applicable Management Information Base, which is automatically loaded from the file whose pathname is provided in mibSource. If mibSource is the zero-length string (\"\") then the default configuration file name is used as noted above. If mibSource is NULL then a rudimentary hard-coded default MIB, useful for basic testing purposes, is loaded. This default MIB defines a single venture for application \"amsdemo\" and authority \"test\", using only the \"dgr\" transport service, with the configuration server residing on the local host machine; subject \"text\" and roles \"shell\", \"log\", \"pitch\", and \"catch\" are defined.
The tsorder argument is normally NULL. If non-NULL it must be a NULL-terminated string of ASCII numeric digits '0' through '9' identifying an alternative transport service preference order that overrides the standard transport service preference order defined by the hard-coded array of transportServiceLoaders in the libams.c source file. Each character of the tsorder string must represent the index position of one of the transport services within the array. For example, if services \"udp\", \"dgr\", \"vmq\", and \"tcp\" are all available in the array, a tsorder string of \"32\" would indicate that this application will only communicate using the tcp and vmq services; services 0 (udp) and 1 (dgr) will not be used, and tcp is preferred to vmq when both are candidate services for transmission of a given message.
Returns 0 on success. On any error, sets module to NULL and returns -1.
int ams_unregister(AmsModule module)
Reverses the operation of ams_unregister(), destroying module. Returns 0 on success, -1 on any error.
int ams_invite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)
Announces this module's agreement to receive messages on the subject identified by subjectNbr.
The invitation is extended only to modules registered in the role identified by roleNbr (where 0 indicates \"all roles\"), operating in the continuum identifed by continuumNbr (where 0 indicates \"all continua\"), and registered within the unit identified by unitNbr (where 0 indicates the venture's root unit) or any of that unit's subunits. These parameters define the \"domain\" of the invitation.
Such messages should be sent at the priority indicated by priority with flow label as indicated by flowLabel and with quality of service as indicated by sequence and diligence. priority must be an integer in the range 1-15, where priority 1 indicates the greatest urgency. Flow labels are passed through to transport services and are opaque to AMS itself; in the absence of defined flow labels, a value of 0 is typically used. These parameters define the \"class of service\" of the invitation.
Returns 0 on success, -1 on any error.
int ams_disinvite(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)
Rescinds the invitation characterized by the indicated subject and domain. Returns 0 on success, -1 on any error.
int ams_subscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, AmsSequence sequence, AmsDiligence diligence)
Announces this module's subscription to messages on the indicated subject, constrained by the indicated domain, and transmitted subject to the indicated class of service. Note that subscriptions differ from invitations in that reception of these messages is actively solicited, not just permitted.
Returns 0 on success, -1 on any error.
int ams_unsubscribe(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr)
Cancels the subscription characterized by the indicated subject and domain. Returns 0 on success, -1 on any error.
int ams_publish(AmsModule module, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)
Publishes contentLength bytes of data starting at content as the content of a message that is sent to all modules whose subscriptions to subjectNbr are characterized by a domain that includes this module. priority and flowLabel, if non-zero, override class of service as requested in the subscriptions. context is an opaque \"hint\" to the receiving modules; its use is application-specific.
Returns 0 on success, -1 on any error.
int ams_send(AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)
Sends contentLength bytes of data starting at content as the content of a message that is transmitted privately to the module in the continuum identified by continuumNbr (where 0 indicates \"the local continuum\") that is identified by unitNbr and moduleNbr -- provided that module is in the domain of one of that module's invitations on subjectNbr. priority and flowLabel, if non-zero, override class of service as requested in the invitation. context is an opaque \"hint\" to the receiving module; its use is application-specific.
Returns 0 on success, -1 on any error.
int ams_query(AmsModule module, int continuumNbr, int unitNbr, int moduleNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context, int term, AmsEvent *event)
Sends a message exactly is described above for ams_send(), but additionally suspends the delivery and processing of newly received messages until either (a) a \"reply\" message sent in response to this message is received or (b) the time interval indicated by term, in seconds, expires. The event (reply or timeout) that ends the suspension of processing is provided in event (as if from ams_get_event() when the function returns.
If term is AMS_BLOCKING then the timeout interval is indefinite; only reception of a reply message enables the function to return. If term is AMS_POLL then the function returns immediately, without waiting for a reply message.
Returns 0 on success, -1 on any error.
int ams_reply(AmsModule module, AmsEvent msg, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content)
Sends a message exactly is described above for ams_send(), except that the destination of the message is the sender of the message identified by msg and the \"context\" value included in the message is the context that was provided in msg. This message is identified as a \"reply\" message that will end the processing suspension resulting from transmission of msg if that message was issued by means of ams_query() rather than ams_send().
Returns 0 on success, -1 on any error.
int ams_announce(AmsModule module, int roleNbr, int continuumNbr, int unitNbr, int subjectNbr, int priority, unsigned char flowLabel, int contentLength, char *content, int context)
Sends a message exactly is described above for ams_send(), except that one copy of the message is sent to every module in the domain of this function (role, continuum, unit) whose invitation for messages on this subject is itself characterized by a domain that includes the the sending module, rather than to any specific module.
Returns 0 on success, -1 on any error.
int ams_get_event(AmsModule module, int term, AmsEvent *event)
Returns in event the next event in the queue of AMS events pending delivery to this module. If the event queue is empty at the time this function is called, processing is suspended until either an event is queued or the time interval indicated by term, in seconds, expires. See ams_query() above for the semantics of term. When the function returns on expiration of term, an event of type TIMEOUT_EVT is returned in event. Otherwise the event will be of type AMS_MSG_EVT (indicating arrival of a message), NOTICE_EVT (indicating a change in the configuration of the message space), or USER_DEFINED_EVT (indicating that application code posted an event).
The nature of the event returned by ams_get_event() can be determined by passing event to ams_get_event_type() as described below. Event type can then be used to determine whether the information content of the event must be obtained by calling ams_parse_msg(), ams_parse_notice(), or ams_parse_user_event().
In any case, the memory occupied by event must be released after the event object is no longer needed. The ams_recycle_event() function is invoked for this purpose.
Returns 0 on success, -1 on any error.
int ams_get_event_type(AmsEvent event)
Returns the event type of event, or -1 on any error.
int ams_parse_msg(AmsEvent event, int *continuumNbr, int *unitNbr, int *moduleNbr, int *subjectNbr, int *contentLength, char **content, int *context, AmsMsgType *msgType, int *priority, unsigned char *flowLabel);
Extracts all relevant information pertaining to the AMS message encapsulated in event, populating the indicated fields. Must only be called when the event type of event is known to be AMS_MSG_EVT.
Returns 0 on success, -1 on any error.
int ams_parse_notice(AmsEvent event, AmsStateType *state, AmsChangeType *change, int *unitNbr, int *moduleNbr, int *roleNbr, int *domainContinuumNbr, int *domainUnitNbr, int *subjectNbr, int *priority, unsigned char *flowLabel, AmsSequence *sequence, AmsDiligence *diligence)
Extracts all relevant information pertaining to the AMS configuration change notice encapsulated in event, populating the relevant fields. Must only be called when the event type of event is known to be NOTICE_EVT.
Note that different fields will be populated depending on the nature of the notice in event. state will be set to AmsRegistrationState, AmsInvitationState, or AmsSubscription state depending on whether the notice pertains to a change in module registration, a change in invitations, or a change in subscriptions. change will be set to AmsStateBegins or AmsStateEnds depending on whether the notice pertains to the initiation or termination of a registration, invitation, or subscription.
Returns 0 on success, -1 on any error.
int ams_post_user_event(AmsModule module, int userEventCode, int userEventDataLength, char *userEventData, int priority)
Posts a \"user event\" whose content is the userEventDataLength bytes of data starting at userEventData. userEventCode is an application-specific value that is opaque to AMS. priority determines the event's position in the queue of events pending delivery to this module; it may be any integer in the range 0-15, where 0 indicates the greatest urgency. (Note that user events can be delivered ahead of all message reception events if necessary.)
Returns 0 on success, -1 on any error.
int ams_parse_user_event(AmsEvent event, int *code, int *dataLength, char **data)
Extracts all relevant information pertaining to the user event encapsulated in event, populating the indicated fields. Must only be called when the event type of event is known to be USER_DEFINED_EVT.
Returns 0 on success, -1 on any error.
int ams_recycle_event(AmsEvent event)
Releases all memory occupied by event. Returns 0 on success, -1 on any error.
int ams_set_event_mgr(AmsModule module, AmsEventMgt *rules)
Starts a background thread that processes events queued for this module, handling each event in the manner indicated by rules. Returns 0 on success, -1 on any error.
void ams_remove_event_mgr(AmsModule module)
Terminates the background thread established to process events queued for this module. Returns 0 on success, -1 on any error.
int ams_get_module_nbr(AmsModule module)
Returns the module number assigned to this module upon registration, or -1 on any error.
int ams_get_unit_nbr(AmsModule module)
Returns the unit number assigned to the unit within which this module registered, or -1 on any error.
Lyst ams_list_msgspaces(AmsModule module)
Returns a dynamically allocated linked list of all message spaces identified in the MIB for this module, or -1 on any error. See lyst(3) for operations that can be performed on the returned linked list.
int ams_get_continuum_nbr()
Returns the continuum number assigned to the continuum within which this module operates, or -1 on any error.
int ams_rams_net_is_tree(AmsModule module)
Returns 1 if the RAMS net for the venture in which this module is registered is configured as a tree, 0 if that RAMS net is configured as a mesh, -1 on any error.
int ams_continuum_is_neighbor(int continuumNbr)
Returns 1 if continuumNbr identifies a continuum whose RAMS gateways are immediate neighbors (within the applicable RAMS networks) of the RAMS gateways in the local continuum. Returns 0 otherwise.
char *ams_get_role_name(AmsModule module, int unitNbr, int moduleNbr)
Returns the name of the role in which the module identified by unitNbr and moduleNbr registered, or NULL on any error.
int ams_subunit_of(AmsModule module, int argUnitNbr, int refUnitNbr)
Returns 1 if argUnitNbr identifies a unit that is wholly contained within the unit identified by refUnitNbr, in the venture within which this module is registered. Returns 0 otherwise.
int ams_lookup_unit_nbr(AmsModule module, char *unitName)
Returns the number assigned to the unit identified by unitName, in the venture within which this module is registered, or -1 on any error.
int ams_lookup_role_nbr(AmsModule module, char *roleName)
Returns the number assigned to the role identified by roleName, in the venture within which this module is registered, or -1 on any error.
int ams_lookup_subject_nbr(AmsModule module, char *subjectName)
Returns the number assigned to the subject identified by subjectName, in the venture within which this module is registered, or -1 on any error.
int ams_lookup_continuum_nbr(AmsModule module, char *continuumName)
Returns the number of the continuum identified by continuumName, or -1 on any error.
char *ams_lookup_unit_name(AmsModule module, int unitNbr)
Returns the name of the unit identified by unitNbr, in the venture within which this module is registered, or -1 on any error.
char *ams_lookup_role_name(AmsModule module, int roleNbr)
Returns the name of the role identified by roleNbr, in the venture within which this module is registered, or -1 on any error.
char *ams_lookup_subject_name(AmsModule module, int subjectNbr)
Returns the name of the subject identified by subjectNbr, in the venture within which this module is registered, or -1 on any error.
char *ams_lookup_continuum_name(AmsModule module, int continuumNbr)
Returns the name of the continuum identified by continuumNbr, or -1 on any error.
amsd(1), ramsgate(1), amsxml(5), amsrc(5)
"},{"location":"man/ams/amsbenchr/","title":"NAME","text":"amsbenchr - Asynchronous Message Service (AMS) benchmarking meter
"},{"location":"man/ams/amsbenchr/#synopsis","title":"SYNOPSIS","text":"amsbenchr
"},{"location":"man/ams/amsbenchr/#description","title":"DESCRIPTION","text":"amsbenchr is a test program that simply subscribes to subject \"bench\" and receives messages published by amsbenchs until all messages in the test - as indicated by the count of remaining messages, in in the first four bytes of each message - have been received. Then it stops receiving messages, calculates and prints performance statistics, and terminates.
amsbenchr will register as an application module in the root unit of the venture identified by application name \"amsdemo\" and authority name \"test\". A configuration server for the local continuum and a registrar for the root unit of that venture (which may both be instantiated in a single amsd daemon task) must be running in order for amsbenchr to commence operations.
"},{"location":"man/ams/amsbenchr/#exit-status","title":"EXIT STATUS","text":"-1
amsbenchr failed, for reasons noted in the ion.log file.
\"0\"
amsbenchr terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amsbenchr/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsbenchr/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
amsbenchr can't register.
amsbenchr failed to register, for reasons noted in the ion.log file.
amsbenchr: subject 'bench' is unknown.
amsbenchr can't subscribe to test messages; probably an error in the MIB initialization file.
amsbenchr can't subscribe.
amsbenchr failed to subscribe, for reasons noted in the ion.log file.
amsbenchr can't get event.
amsbenchr failed to receive a message, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsbenchr/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amsbenchs/","title":"NAME","text":"amsbenchs - Asynchronous Message Service (AMS) benchmarking driver
"},{"location":"man/ams/amsbenchs/#synopsis","title":"SYNOPSIS","text":"amsbenchs count size
"},{"location":"man/ams/amsbenchs/#description","title":"DESCRIPTION","text":"amsbenchs is a test program that simply publishes count messages of size bytes each on subject \"bench\", then waits while all published messages are transmitted, terminating when the user uses ^C to interrupt the program. The remaining number of messages to be published in the test is written into the first four octets of each message.
amsbenchs will register as an application module in the root unit of the venture identified by application name \"amsdemo\" and authority name \"test\". A configuration server for the local continuum and a registrar for the root unit of that venture (which may both be instantiated in a single amsd daemon task) must be running in order for amsbenchs to commence operations.
"},{"location":"man/ams/amsbenchs/#exit-status","title":"EXIT STATUS","text":"-1
amsbenchs failed, for reasons noted in the ion.log file.
\"0\"
amsbenchs terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amsbenchs/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsbenchs/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
No memory for amsbenchs.
Insufficient available memory for a message content buffer of the indicated size.
amsbenchs can't register.
amsbenchs failed to register, for reasons noted in the ion.log file.
amsbenchs can't set event manager.
amsbenchs failed to start its background event management thread, for reasons noted in the ion.log file.
amsbenchs: subject 'bench' is unknown.
amsbenchs can't publish test messages; probably an error in the MIB initialization file.
amsbenchs can't publish message.
amsbenchs failed to publish, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsbenchs/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amsd/","title":"NAME","text":"amsd - AMS configuration server and/or registrar daemon
"},{"location":"man/ams/amsd/#synopsis","title":"SYNOPSIS","text":"amsd { @ | MIB_source_name } { . | @ | config_server_endpoint_spec } [application_name authority_name registrar_unit_name]
"},{"location":"man/ams/amsd/#description","title":"DESCRIPTION","text":"amsd is a background \"daemon\" task that functions as an AMS \"configuration server\" in the local continuum, as an AMS \"registrar\" in a specified cell, or both.
If MIB_source_name is specified, it must name a MIB initialization file in the correct format for amsd, either amsrc(5) or amsxml(5), depending on whether or not -DNOEXPAT was set at compile time. Otherwise @ is required; in this case, the built-in default MIB is loaded.
If this amsd task is NOT to run as a configuration server then the second command-line argument must be a '.' character. Otherwise the second command-line argument must be either '@' or config_server_endpoint_spec. If '@' then the endpoint specification for this configuration server is automatically computed as the default endpoint specification for the primary transport service as noted in the MIB: \"hostname:2357\".
If an AMS module is NOT to be run in a background thread for this daemon (enabling shutdown by amsstop(1) and/or runtime MIB update by amsmib(1)), then either the last three command-line arguments must be omitted or else the \"amsd\" role must not be defined in the MIB loaded for this daemon. Otherwise the application_name and authority_name arguments are required and the \"amsd\" role must be defined in the MIB.
If this amsd task is NOT to run as a registrar then the last command-line argument must be omitted. Otherwise the last three command-line arguments are required and they must identify a unit in an AMS venture for the indicated application and authority that is known to operate in the local continuum, as noted in the MIB. Note that the unit name for the \"root unit\" of a venture is the zero-length string \"\".
"},{"location":"man/ams/amsd/#exit-status","title":"EXIT STATUS","text":"\"0\"
amsd terminated without error.
-1
amsd terminated due to an anomaly as noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and restart amsd.
If MIB source name is specified, then a file of this name must be present. Otherwise a MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amsd/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsd/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
amsd can't load MIB.
MIB initialization file was missing, unreadable, or invalid.
amsd can't start CS.
Configuration server initialization failed for reasons noted in ion.log file.
amsd can't start RS.
Registrar initialization failed for reasons noted in ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsd/#see-also","title":"SEE ALSO","text":"amsmib(1), amsstop(1), amsrc(5), amsxml(5)
"},{"location":"man/ams/amshello/","title":"NAME","text":"amshello - Asynchronous Message Service (AMS) demo program for UNIX
"},{"location":"man/ams/amshello/#synopsis","title":"SYNOPSIS","text":"amshello
"},{"location":"man/ams/amshello/#description","title":"DESCRIPTION","text":"amshello is a sample program designed to demonstrate that an entire (very simple) distributed AMS application can be written in just a few lines of C code. When started, amshello forks a second process and initiates transmission of a \"Hello\" text message from one process to the other, after which both processes unregister and terminate.
The amshello processes will register as application modules in the root unit of the venture identified by application name \"amsdemo\" and authority name \"test\". A configuration server for the local continuum and a registrar for the root unit of that venture (which may both be instantiated in a single amsd daemon task) must be running in order for the amshello processes to run.
"},{"location":"man/ams/amshello/#exit-status","title":"EXIT STATUS","text":"\"0\"
amshello terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amshello/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amshello/#diagnostics","title":"DIAGNOSTICS","text":"No diagnostics apply.
"},{"location":"man/ams/amshello/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amshello/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amslog/","title":"NAME","text":"amslog - Asynchronous Message Service (AMS) test message receiver
"},{"location":"man/ams/amslog/#synopsis","title":"SYNOPSIS","text":"amslog unit_name role_name application_name authority_name [{ s | i }]
"},{"location":"man/ams/amslog/#description","title":"DESCRIPTION","text":"amslog is a message reception program designed to test AMS functionality.
When amslog is started, it registers as an application module in the unit identified by unit_name of the venture identified by application_name and authority_name; the role in which it registers must be indicated in role_name. A configuration server for the local continuum and a registrar for the indicated unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for amslog to run.
amslog runs as two threads: a background thread that receives AMS messages and logs them to standard output, together with a foreground thread that acquires operating parameters in lines of console input to control the flow of messages to the background thread.
When the first character of a line of input from stdin to the amslog foreground thread is '.' (period), amslog immediately terminates. Otherwise, the first character of each line of input from stdin must be either '+' indicating assertion of interest in a message subject or '-' indicating cessation of interest in a subject. In each case, the name of the subject in question must begin in the second character of the input line. Note that \"everything\" is a valid subject name.
By default, amslog runs in \"subscribe\" mode: when interest in a message subject is asserted, amslog subscribes to that subject; when interest in a message subject is rescinded, amslog unsubscribes to that subject. This behavior can be overridden by providing a third command-line argument to amslog - a \"mode\" indicator. When mode is 'i', amslog runs in \"invite\" mode. In \"invite\" mode, when interest in a message subject is asserted, amslog invites messages on that subject; when interest in a message subject is rescinded, amslog cancels its invitation for messages on that subject.
The \"domain\" of a subscription or invitation can optionally be specified immediately after the subject name, on the same line of console input:
Domain continuum name may be specified, or the place-holder domain continuum name \"_\" may be specified to indicate \"all continua\".
If domain continuum name (\"_\" or otherwise) is specified, then domain unit name may be specified or the place-holder domain unit name \"_\" may be specified to indicate \"the root unit\" (i.e., the entire venture).
If domain unit name (\"_\" or otherwise) is specified, then domain role name may be specified.
When amslog runs in VxWorks or RTEMS, the subject and content of each message are simply written to standard output in a text line for display on the console. When amslog runs in a UNIX environment, the subject name length (a binary integer), subject name (ASCII text), content length (a binary integer), and content (ASCII text) are written to standard output for redirection either to a file or to a pipe to amslogprt.
Whenever a received message is flagged as a Query, amslog returns a reply message whose content is the string \"Got \" followed by the first 128 bytes of the content of the Query message, enclosed in single quote marks and followed by a period.
"},{"location":"man/ams/amslog/#exit-status","title":"EXIT STATUS","text":"-1
amslog terminated with an error as noted in the ion.log file.
\"0\"
amslog terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amslog/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amslog/#diagnostics","title":"DIAGNOSTICS","text":"amslog can't register.
amslog failed to register, for reasons noted in the ion.log file.
amslog can't set event manager.
amslog failed to start its background thread, for reasons noted in the ion.log file.
amslog can't read from stdin
amslog foreground thread failed to read console input, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amslog/#see-also","title":"SEE ALSO","text":"amsshell(1), amslogprt(1), amsrc(5)
"},{"location":"man/ams/amslogprt/","title":"NAME","text":"amslogprt - UNIX utility program for printing AMS log messages from amslog
"},{"location":"man/ams/amslogprt/#synopsis","title":"SYNOPSIS","text":"amslogprt
"},{"location":"man/ams/amslogprt/#description","title":"DESCRIPTION","text":"amslogprt simply reads AMS activity log messages from standard input (nominally written by amslog and prints them. When the content of a logged message is judged not to be an ASCII text string, the content is printed in hexadecimal.
amslogprt terminates at the end of input.
"},{"location":"man/ams/amslogprt/#exit-status","title":"EXIT STATUS","text":"\"0\"
amslogprt terminated normally.
No files are needed by amslogprt.
"},{"location":"man/ams/amslogprt/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amslogprt/#diagnostics","title":"DIAGNOSTICS","text":"None.
"},{"location":"man/ams/amslogprt/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amslogprt/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amsmib/","title":"NAME","text":"amsmib - Asynchronous Message Service (AMS) MIB update utility
"},{"location":"man/ams/amsmib/#synopsis","title":"SYNOPSIS","text":"amsmib application_name authority_name role_name continuum_name unit_name file_name
"},{"location":"man/ams/amsmib/#description","title":"DESCRIPTION","text":"amsmib is a utility program that announces relatively brief Management Information Base (MIB) updates to a select population of AMS modules. Because amsd processes may run AAMS modules in background threads, and because a single MIB is shared in common among all threads of any process, amsmib may update the MIBs used by registrars and/or configuration servers as well.
MIB updates can only be propagated to modules for which the subject \"amsmib\" was defined in the MIB initialization files cited at module registration time. All ION AMS modules implicitly invite messages on subject \"amsmib\" (from all modules registered in role \"amsmib\" in all continua of the same venture) at registration time if subject \"amsmib\" and role \"amsmib\" are defined in the MIB.
amsmib registers in the root cell of the message space identified by application_name and authority_name, within the local continuum. It registers in the role \"amsmib\"; if this role is not defined in the (initial) MIB loaded by amsmib at registration time, then registration fails and amsmib terminates.
amsmib then reads into a memory buffer up to 4095 bytes of MIB update text from the file identified by file_name. The MIB update text must conform to amsxml(5) or amsrc(5) syntax, depending on whether or not the intended recipient modules were compiled with the -DNOEXPAT option.
amsmib then \"announces\" (see ams_announce() in ams(3)) the contents of the memory buffer to all modules of this same venture (identified by application_name and authority_name) that registered in the indicated role, in the indicated unit of the indicated continuum. If continuum_name is \"\" then the message will be sent to modules in all continua. If role_name is \"\" then all modules will be eligible to receive the message, regardless of the role in which they registered. If unit_name is \"\" (the root unit) then all modules will be eligible to receive the message, regardless of the unit in which they registered.
Upon reception of the announced message, each destination module will apply all of the MIB updates in the content of the message, in exactly the same way that its original MIB was loaded from the MIB initialization file when the module started running.
If multiple modules are running in the same memory space (e.g., in different threads of the same process, or in different tasks on the same VxWorks target) then the updates will be applied multiple times, because all modules in the same memory space share a single MIB. MIB updates are idempotent, so this is harmless (though some diagnostics may be printed).
Moreover, an amsd daemon will have a relevant \"MIB update\" module running in a background thread if application_name and authority_name were cited on the command line that started the daemon (provided the role \"amsd\" was defined in the initial MIB loaded at the time amsd began running). The MIB exposed to the configuration server and/or registrar running in that daemon will likewise be updated upon reception of the announced message.
The name of the subject of the announced mib update message is \"amsmib\"; if this subject is not defined in the (initial) MIB loaded by amsmib then the message cannot be announced. Nor can any potential recipient module receive the message if subject \"amsmib\" is not defined in that module's MIB.
"},{"location":"man/ams/amsmib/#exit-status","title":"EXIT STATUS","text":"\"0\"
amsmib terminated normally.
\"1\"
An anomalous exit status, indicating that amsmib failed to register.
A MIB initialization file with the applicable default name (see amsrc(5) and amsxml(5)) must be present.
"},{"location":"man/ams/amsmib/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsmib/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
amsmib subject undefined.
The amsmib utility was unable to announce the MIB update message.
amsmib domain role unknown.
The amsmib utility was unable to announce the MIB update message.
amsmib domain continuum unknown.
The amsmib utility was unable to announce the MIB update message.
amsmib domain unit unknown.
The amsmib utility was unable to announce the MIB update message.
amsmib can't open MIB file.
The amsmib utility was unable to construct the MIB update message.
MIB file length > 4096.
The MIB update text file was too long to fit into the amsmib message buffer.
Can't seek to end of MIB file.
I/O error in processing the MIB update text file.
Can't read MIB file.
I/O error in processing the MIB update text file.
amsmib can't announce 'amsmib' message.
The amsmib utility was unable to announce the MIB update message, for reasons noted in the log file.
amsmib can't register.
The amsmib utility failed to register, for reasons noted in the log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsmib/#see-also","title":"SEE ALSO","text":"amsd(1), ams(3), amsrc(5), amsxml(5)
"},{"location":"man/ams/amspub/","title":"NAME","text":"amspub - Asynchronous Message Service (AMS) test driver for VxWorks
"},{"location":"man/ams/amspub/#synopsis","title":"SYNOPSIS","text":"amspub \"application_name\", \"authority_name\", \"subject_name\", \"message_text\"
"},{"location":"man/ams/amspub/#description","title":"DESCRIPTION","text":"amspub is a message publication program designed to test AMS functionality in a VxWorks environment. When an amspub task is started, it registers as an application module in the root unit of the venture identified by application_name and authority_name, looks up the subject number for subject_name, publishes a single message with content message_text on that subject, unregisters, and terminates.
A configuration server for the local continuum and a registrar for the root unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for amspub to run.
"},{"location":"man/ams/amspub/#exit-status","title":"EXIT STATUS","text":"-1
amspub terminated with an error as noted in the ion.log file.
\"0\"
amspub terminated normally.
The amspub source code is in the amspubsub.c source file.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amspub/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amspub/#diagnostics","title":"DIAGNOSTICS","text":"amspub can't register.
amspub failed to register, for reasons noted in the ion.log file.
amspub: subject is unknown
amspub can't publish test messages on the specified subject; possibly an error in the MIB initialization file.
amspub can't publish message.
amspub failed to publish, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amspub/#see-also","title":"SEE ALSO","text":"amssub(1), amsrc(5)
"},{"location":"man/ams/amsrc/","title":"NAME","text":"amsrc - CCSDS Asynchronous Message Service MIB initialization file
"},{"location":"man/ams/amsrc/#description","title":"DESCRIPTION","text":"The Management Information Base (MIB) for an AMS communicating entity (either amsd or an AMS application module) must contain enough information to enable the entity to initiate participation in AMS message exchange, such as the network location of the configuration server and the roles and message subjects defined for some venture.
AMS entities automatically load their MIBs from initialization files at startup. When AMS is built with the -DNOEXPAT compiler option set, the MIB initialization file must conform to the amsrc syntax described below; otherwise the expat XML parsing library must be linked into the AMS executable and the MIB initialization file must conform to the amsxml syntax described in amsxml(5).
The MIB initialization file lists elements of MIB update information, each of which may have one or more attributes. An element may also have sub-elements that are listed within the declaration of the parent element, and so on.
The declaration of an element may occupy a single line of text in the MIB initialization file or may extend across multiple lines. A single-line element declaration is indicated by a '*' in the first character of the line. The beginning of a multi-line element declaration is indicated by a '+' in the first character of the line, while the end of that declaration is indicated by a '-' in the first character of the line. In every case, the type of element must be indicated by an element-type name beginning in the second character of the line and terminated by whitespace. Every start-of-element line must be matched by a subsequent end-of-element line that precedes the start of any other element that is not a nested sub-element of this element.
Attributes are represented by whitespace-terminated <name>=<value> expressions immediately following the element-type name on a '*' or '+' line. An attribute value that contains whitespace must be enclosed within a pair of single-quote (') characters.
Two types of elements are recognized in the MIB initialization file: control elements and configuration elements. A control element establishes the update context within which the configuration elements nested within it are processed, while a configuration element declares values for one or more items of AMS configuration information in the MIB.
Note that an aggregate configuration element (i.e., one which may contain other interior configuration elements; venture, for example) may be presented outside of any control element, simply to establish the context in which subsequent control elements are to be interpreted.
"},{"location":"man/ams/amsrc/#control-elements","title":"CONTROL ELEMENTS","text":"ams_mib_init
Initializes an empty MIB. This element must be declared prior to the declaration of any other element.
Sub-elements: none
Attributes:
continuum_nbr
Identifies the local continuum.
ptsname
Identifies the primary transport service for the continuum. Valid values include \"dgr\" and \"udp\".
pubkey
This is the name of the public key used for validating the digital signatures of meta-AMS messages received from the configuration server for this continuum. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
privkey
This is the name of the private key used for constructing the digital signatures of meta-AMS messages sent by the configuration server for this continuum. This attribute should only be present in the MIB initialization file for amsd(). The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
ams_mib_add
This element contains a list of configuration items that are to be added to the MIB.
ams_mib_change
This element contains a list of configuration items that are to be revised in the MIB.
ams_mib_delete
This element contains a list of configuration items that are to be deleted from the MIB.
continuum
Identifies a known remote continuum.
Sub-elements: none
Attributes:
nbr
Identifies the remote continuum.
name
Identifies the remote continuum.
neighbor
1 if the continuum is a neighbor of the local continuum, zero otherwise.
desc
A textual description of this continuum.
csendpoint
Identifies one of the network locations at which the configuration server may be reachable. If the configuration server might be running at any one of several locations, the number of other locations that are preferred to this one is noted; in this case, csendpoints must be listed within the ams_mib_add element in descending order of preference, i.e., with the most preferred network location listed first.
Sub-elements: none
Attributes:
epspec
Identifies the endpoint at which the configuration server may be reachable. The endpoint specification must conform to the endpoint specification syntax defined for the continuum's primary transport service; see the AMS Blue Book for details.
after
If present, indicates the number of other configuration server network locations that are considered preferable to this one. This attribute is used to ensure that csendpoints are listed in descending order of preference.
amsendpoint
Normally the specifications of the transport service endpoints at which an AMS application module can receive messages are computed automatically using standard transport-service-specific rules. However, in some cases it might be necessary for a module to receive messages at one or more non-standard endpoints; in these cases, amsendpoint elements can be declared in order to override the standard endpoint specification rules.
Sub-elements: none
Attributes:
tsname
Identifies the transport service for which a non-standard endpoint specification is being supplied.
epspec
Identifies an endpoint at which the application module will be reachable, in the context of the named transport service. The endpoint specification must conform to the endpoint specification syntax defined for the named transport service; see the AMS Blue Book for details.
application
Identifies one of the applications supported within this continuum.
Sub-elements: none
Attributes:
name
Identifies the application.
pubkey
This is the name of the public key used for validating the digital signatures of meta-AMS messages received from the registrars for all cells of any message space in this continuum that is characterized by this application name. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
privkey
This is the name of the private key used for constructing the digital signatures of meta-AMS messages sent by the registrars for all cells of any message space in this continuum that is characterized by this application name. This attribute should only be present in the MIB initialization file for amsd(). The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
venture
Identifies one of the ventures operating within the local continuum.
Sub-elements: role, subject, unit, msgspace
Attributes:
nbr
Identifies the venture.
appname
Identifies the application addressed by this venture.
authname
Identifies the authority under which the venture operates, distinguishing this venture from all other ventures that address the same application.
gweid
Identifies the RAMS network endpoint ID of the RAMS gateway module for this venture's message space in the local continuum. Gateway endpoint ID is expressed as <protocol_name>@<eid_string> where protocol_name is either \"bp\" or \"udp\". If protocol name is \"bp\" then eid_string must be a valid Bundle Protocol endpoint ID; otherwise, eid_string must be of the form <hostname>:<port_number>. If the gweid attribute is omitted, the RAMS gateway module's RAMS network endpoint ID defaults to \"bp@ipn:<local_continuum_number>.<venture_number>\".
net_config
Has the value \"tree\" if the RAMS network supporting this venture is configured as a tree; otherwise \"mesh\", indicating that the RAMS network supporting this venture is configured as a mesh.
root_cell_resync_period
Indicates the number of seconds in the period on which resynchronization is performed for the root cell of this venture's message space in the local continuum. If this attribute is omitted, resynchronization in that cell is disabled.
role
Identifies one of the functional roles in the venture that is the element that's currently being configured.
Sub-elements: none
Attributes:
nbr
Identifies the role.
name
Identifies the role.
authname
Identifies the authority under which the venture operates, distinguishing this venture from all other ventures that address the same application.
pubkey
This is the name of the public key used for validating the digital signatures of meta-AMS messages received from all application modules that register in this functional role. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
privkey
This is the name of the private key used for constructing the digital signatures of meta-AMS messages sent by all application modules that register in this functional role. This attribute should only be present in the MIB initialization file for application modules that register in this role. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
subject
Identifies one of the subjects on which messages may be sent, within the venture that is the element that's currently being configured.
Sub-elements: sender, receiver
Attributes:
nbr
Identifies the subject.
name
Identifies the subject.
desc
A textual description of this message subject.
symkey
This is the name of the symmetric key used for both encrypting and decrypting the content of messages on this subject; if omitted, messages on this subject are not encrypted by AMS. If authorized senders and receivers are defined for this subject, then this attribute should only be present in the MIB initialization file for application modules that register in roles that appear in the subject's lists of authorized senders and/or receivers. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
marshal
This is the name associated with the content marshaling function defined for this message subject. If present, whenever a message on this subject is issued the associated function is automatically called to convert the supplied content data to a platform-independent representation for transmission; this conversion occurs before any applicable content encryption is performed. If omitted, content data are transmitted without conversion to a platform-independent representation. Marshaling functions are defined in the marshalRules table in the marshal.c source file.
unmarshal
This is the name associated with the content unmarshaling function defined for this message subject. If present, whenever a message on this subject is received the associated function is automatically called to convert the transmitted content to local platform-specific representation; this conversion occurs after any applicable content decryption is performed. If omitted, received content data are delivered without conversion to a local platform-specific representation. Unmarshaling functions are defined in the unmarshalRules table in the marshal.c source file.
sender
Identifies one of the roles in which application modules must register in order to be authorized senders of messages on the subject that is the element that's currently being configured.
Sub-elements: none
Attributes:
name
Identifies the sender. The value of this attribute must be the name of a role that has been defined for the venture that is currently being configured.
receiver
Identifies one of the roles in which application modules must register in order to be authorized receivers of messages on the subject that is the element that's currently being configured.
Sub-elements: none
Attributes:
name
Identifies the receiver. The value of this attribute must be the name of a role that has been defined for the venture that is currently being configured.
unit
Identifies one of the organizational units within the venture that is the element that's currently being configured.
Sub-elements: none
Attributes:
nbr
Identifies the unit.
name
Identifies the unit.
resync_period
Indicates the number of seconds in the period on which resynchronization is performed, for the cell of this venture's message space that is the portion of the indicated unit which resides in the local continuum. If this attribute is omitted, resynchronization in that cell is disabled.
msgspace
Identifies one of the message spaces in remote continua that are encompassed by the venture that is the element that's currently being configured.
Sub-elements: none
Attributes:
nbr
Identifies the remote continuum within which the message space operates.
gweid
Identifies the RAMS network endpoint ID of the RAMS gateway module for this message space. Gateway endpoint ID is expressed as <protocol_name>@<eid_string> where protocol_name is either \"bp\" or \"udp\". If protocol name is \"bp\" then eid_string must be a valid Bundle Protocol endpoint ID; otherwise, eid_string must be of the form <hostname>:<port_number>. If the gweid attribute is omitted, the RAMS network endpoint ID of the message space's RAMS gateway module defaults to \"bp@ipn:<remote_continuum_number>.<venture_number>\".
symkey
This is the name of the symmetric key used for both encrypting and decrypting all messages to and from modules in the remote message space that are forwarded between the local RAMS gateway server and modules in the local message space; if omitted, these messages are not encrypted. The value of this attribute (if present) must identify a key that has been loaded into the ION security database, nominally by ionsecadmin(1).
*ams_mib_init continuum_nbr=2 ptsname=dgr
+ams_mib_add
*continuum nbr=1 name=apl desc=APL
*csendpoint epspec=beaumont.stepsoncats.com:2357
*application name=amsdemo
+venture nbr=1 appname=amsdemo authname=test
*role nbr=2 name=shell
*role nbr=3 name=log
*role nbr=4 name=pitch
*role nbr=5 name=catch
*role nbr=6 name=benchs
*role nbr=7 name=benchr
*role nbr=96 name=amsd
*role nbr=97 name=amsmib
*role nbr=98 name=amsstop
*subject nbr=1 name=text desc='ASCII text'
*subject nbr=2 name=noise desc='more ASCII text'
*subject nbr=3 name=bench desc='numbered msgs'
*subject nbr=97 name=amsmib desc='MIB updates'
*subject nbr=98 name=amsstop desc='shutdown'
*unit nbr=1 name=orbiters
*unit nbr=2 name=orbiters.near
*unit nbr=3 name=orbiters.far
*msgspace nbr=2
-venture
-ams_mib_add
"},{"location":"man/ams/amsrc/#see-also","title":"SEE ALSO","text":"amsxml(5)
"},{"location":"man/ams/amsshell/","title":"NAME","text":"amsshell - Asynchronous Message Service (AMS) test message sender (UNIX)
"},{"location":"man/ams/amsshell/#synopsis","title":"SYNOPSIS","text":"amsshell unit_name role_name application_name authority_name [{ p | s | q | a }]
"},{"location":"man/ams/amsshell/#description","title":"DESCRIPTION","text":"amsshell is a message issuance program designed to test AMS functionality.
When amsshell is started, it registers as an application module in the unit identified by unit_name of the venture identified by application_name and authority_name; the role in which it registers must be indicated in role_name. A configuration server for the local continuum and a registrar for the indicated unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for amsshell to run.
amsshell runs as two threads: a background thread that receives watches for AMS configuration events (including shutdown), together with a foreground thread that acquires operating parameters and message content in lines of console input to control the issuance of messages.
The first character of each line of input from stdin to the amsshell indicates the significance of that line:
=
Sets the name of the subject on which all messages are to be issued, until superseded by another \"=\" line. The subject name must begin at the second character of this line. Optionally, subject name may be followed by a single ' ' (space) character and then the text of the first message to be issued on this subject, which is to be issued immediately.
r
Sets the number of the role constraining the domain of message issuance. The role number must begin at the second character of this line.
c
Sets the number of the continuum constraining the domain of message issuance. The continuum number must begin at the second character of this line.
u
Sets the number of the unit constraining the domain of message issuance. The unit number must begin at the second character of this line.
m
Sets the number of the module to which subsequent messages are to be issued. The module number must begin at the second character of this line.
.
Terminates amsshell.
When the first character of a line of input from stdin is none of the above, the entire line is taken to be the text of a message that is to be issued immediately, on the previously specified subject, to the previously specified module (if applicable), and subject to the previously specified domain (if applicable).
By default, amsshell runs in \"publish\" mode: when a message is to be issued, it is simply published. This behavior can be overridden by providing a fifth command-line argument to amsshell - a \"mode\" indicator. The supported modes are as follows:
p
This is \"publish\" mode. Every message is published.
s
This is \"send\" mode. Every message is sent privately to the application module identified by the specified module, unit, and continuum numbers.
q
This is \"query\" mode. Every message is sent privately to the application module identified by the specified module, unit, and continuum numbers, and amsshell then waits for a reply message before continuing.
a
This is \"announce\" mode. Every message is announced to all modules in the domain established by the previously specified role, unit, and continuum numbers.
-1
amsshell terminated with an error as noted in the ion.log file.
\"0\"
amsshell terminated normally.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amsshell/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsshell/#diagnostics","title":"DIAGNOSTICS","text":"amsshell can't register.
amsshell failed to register, for reasons noted in the ion.log file.
amsshell can't set event manager.
amsshell failed to start its background thread, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsshell/#see-also","title":"SEE ALSO","text":"amslog(1), amsrc(5)
"},{"location":"man/ams/amsstop/","title":"NAME","text":"amsstop - Asynchronous Message Service (AMS) message space shutdown utility
"},{"location":"man/ams/amsstop/#synopsis","title":"SYNOPSIS","text":"amsstop application_name authority_name
"},{"location":"man/ams/amsstop/#description","title":"DESCRIPTION","text":"amsstop is a utility program that terminates the operation of all registrars and all application modules running in the message space which is that portion of the indicated AMS venture that is operating in the local continuum. If one of the amsd tasks that are functioning as registrars for this venture is also functioning as the configuration server for the local continuum, then that configuration server is also terminated.
application_name and authority_name must identify an AMS venture that is known to operate in the local continuum, as noted in the MIB for the amsstop application module.
A message space can only be shut down by amsstop if the subject \"amsstop\" is defined in the MIBs of all modules in the message spaces.
"},{"location":"man/ams/amsstop/#exit-status","title":"EXIT STATUS","text":"\"0\"
amsstop terminated normally.
\"1\"
An anomalous exit status, indicating that amsstop was unable to register and therefore failed to shut down its message space, for reasons noted in the ion.log file.
A MIB initialization file with the applicable default name (see amsrc(5) and amsxml(5)) must be present.
"},{"location":"man/ams/amsstop/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amsstop/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
amsstop can't register.
This message indicates that amsstop was unable to register, possibly because the \"amsstop\" role is not defined in the MIB initialization file.
amsstop subject undefined.
This message indicates that amsstop was unable to stop the message space because the \"amsstop\" subject is not defined in the MIB initialization file.
amsstop can't publish 'amsstop' message.
This message indicates that amsstop was unable to publish a message on subject 'amsstop' for reasons noted in the ion.log log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amsstop/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/amssub/","title":"NAME","text":"amssub - Asynchronous Message Service (AMS) test message receiver for VxWorks
"},{"location":"man/ams/amssub/#synopsis","title":"SYNOPSIS","text":"amssub \"application_name\", \"authority_name\", \"subject_name\"
"},{"location":"man/ams/amssub/#description","title":"DESCRIPTION","text":"amssub is a message reception program designed to test AMS functionality in a VxWorks environment. When an amssub task is started, it registers as an application module in the root unit of the venture identified by application_name and authority_name, looks up the subject number for subject_name, subscribes to that subject, and begins receiving and printing messages on that subject until terminated by amsstop.
A configuration server for the local continuum and a registrar for the root unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for amssub to run.
"},{"location":"man/ams/amssub/#exit-status","title":"EXIT STATUS","text":"-1
amssub terminated with an error as noted in the ion.log file.
\"0\"
amssub terminated normally.
The amssub source code is in the amspubsub.c source file.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
"},{"location":"man/ams/amssub/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/amssub/#diagnostics","title":"DIAGNOSTICS","text":"amssub can't register.
amssub failed to register, for reasons noted in the ion.log file.
amssub: subject is unknown
amssub can't subscribe to messages on the specified subject; possibly an error in the MIB initialization file.
amssub can't subscribe.
amssub failed to subscribe, for reasons noted in the ion.log file.
amssub can't get event.
amssub failed to receive message, for reasons noted in the ion.log file.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/amssub/#see-also","title":"SEE ALSO","text":"amspub(1), amsrc(5)
"},{"location":"man/ams/amsxml/","title":"NAME","text":"amsxml - CCSDS Asynchronous Message Service MIB initialization XML file
"},{"location":"man/ams/amsxml/#description","title":"DESCRIPTION","text":"The Management Information Base (MIB) for an AMS communicating entity (either amsd or an AMS application module) must contain enough information to enable the entity to initiate participation in AMS message exchange, such as the network location of the configuration server and the roles and message subjects defined for some venture.
AMS entities automatically load their MIBs from initialization files at startup. When AMS is built with the -DNOEXPAT compiler option set, the MIB initialization file must conform to the amsrc syntax described in amsrc(5); otherwise the expat XML parsing library must be linked into the AMS executable and the MIB initialization file must conform to the amsxml syntax described below.
The XML statements in the MIB initialization file constitute elements of MIB update information, each of which may have one or more attributes. An element may also have sub-elements that are listed within the declaration of the parent element, and so on.
Two types of elements are recognized in the MIB initialization file: control elements and configuration elements. A control element establishes the update context within which the configuration elements nested within it are processed, while a configuration element declares values for one or more items of AMS configuration information in the MIB.
For a discussion of the recognized control elements and configuration elements of the MIB initialization file, see the amsrc(5) man page. NOTE, though, that all elements of an XML-based MIB initialization file must be sub-elements of a single sub-element of the XML extension type ams_load_mib in order for the file to be parsed successfully by expat.
"},{"location":"man/ams/amsxml/#example","title":"EXAMPLE","text":"<?xml version=\"1.0\" standalone=\"yes\"?>
<ams_mib_load>
<ams_mib_init continuum_nbr=\"2\" ptsname=\"dgr\"/>\n\n <ams_mib_add>\n\n <continuum nbr=\"1\" name=\"apl\" desc=\"APL\"/>\n\n <csendpoint epspec=\"beaumont.stepsoncats.com:2357\"/>\n\n <application name=\"amsdemo\" />\n\n <venture nbr=\"1\" appname=\"amsdemo\" authname=\"test\">\n\n <role nbr=\"2\" name=\"shell\"/>\n\n <role nbr=\"3\" name=\"log\"/>\n\n <role nbr=\"4\" name=\"pitch\"/>\n\n <role nbr=\"5\" name=\"catch\"/>\n\n <role nbr=\"6\" name=\"benchs\"/>\n\n <role nbr=\"7\" name=\"benchr\"/>\n\n <role nbr=\"96\" name=\"amsd\"/>\n\n <role nbr=\"97\" name=\"amsmib\"/>\n\n <role nbr=\"98\" name=\"amsstop\"/>\n\n <subject nbr=\"1\" name=\"text\" desc=\"ASCII text\"/>\n\n <subject nbr=\"2\" name=\"noise\" desc=\"more ASCII text\"/>\n\n <subject nbr=\"3\" name=\"bench\" desc=\"numbered msgs\"/>\n\n <subject nbr=\"97\" name=\"amsmib\" desc=\"MIB updates\"/>\n\n <subject nbr=\"98\" name=\"amsstop\" desc=\"shutdown\"/>\n\n <unit nbr=\"1\" name=\"orbiters\"/>\n\n <unit nbr=\"2\" name=\"orbiters.near\"/>\n\n <unit nbr=\"3\" name=\"orbiters.far\"/>\n\n <msgspace nbr=\"2\"/>\n\n </venture>\n\n </ams_mib_add>\n</ams_mib_load>
"},{"location":"man/ams/amsxml/#see-also","title":"SEE ALSO","text":"amsrc(5)
"},{"location":"man/ams/petition_log/","title":"NAME","text":"petition.log - Remote AMS petition log
"},{"location":"man/ams/petition_log/#description","title":"DESCRIPTION","text":"The Remote AMS daemon ramsgate records all \"petitions\" (requests for data on behalf of AMS modules in other continua) in a file named petition.log. At startup, the ramsgate daemon automatically reads and processes all petitions in the petition.log file just as if they were received in real time, to re-establish the petition state that was in effect at the time the ramsgate daemon shut down. Note that this means that you can cause petitions to be, in effect, \"pre-received\" by simply editing this file prior to startup. This can be an especially effective way to configure a RAMS network in which long signal propagation times would otherwise retard real-time petitioning and thus delay the onset of fully functional message exchange.
Entries in petition.log are simple ASCII text lines, with parameters separated by spaces. Each line of petition.log has the following parameters:
protocolId
This is a number that identifies the RAMS network protocol characterizing the network on which the petition was received: 1 == DTN Bundle Protocol, 2 = UDP.
gatewayID
This is a string that identifies the remote RAMS gateway node that issued this petition.
controlCode
This is a number that indicates whether the petition described by this line is one that is being asserted (2) or canceled (3).
subject
A number that identifies the subject of the traffic to which the petition pertains.
continuumNumber
Identifies the continuum for the domain of the petition.
unitNumber
Identifies the unit for the domain of the petition.
roleNumber
Identifies the role for the domain of the petition.
ramsgate(1), ams(3)
"},{"location":"man/ams/ramsgate/","title":"NAME","text":"ramsgate - Remote AMS gateway daemon
"},{"location":"man/ams/ramsgate/#synopsis","title":"SYNOPSIS","text":"ramsgate application_name authority_name [bundles_TTL]
"},{"location":"man/ams/ramsgate/#description","title":"DESCRIPTION","text":"ramsgate is a background \"daemon\" task that functions as a Remote AMS gateway. application_name and authority_name must identify an AMS venture that is known to operate in the local continuum, as noted in the MIB for the ramsgate application module.
ramsgate will register as an application module in the root unit of the indicated venture, so a configuration server for the local continuum and a registrar for the root unit of the indicated venture (which may both be instantiated in a single amsd daemon task) must be running in order for ramsgate to commence operations.
ramsgate with communicate with other RAMS gateway modules in other continua by means of the RAMS network protocol noted in the RAMS gateway endpoint ID for the local continuum, as identified (explicitly or implicitly) in the MIB.
If the RAMS network protocol is \"bp\" (i.e., the DTN Bundle Protocol), then an ION Bundle Protocol node must be operating on the local computer and that node must be registered in the BP endpoint identified by the RAMS gateway endpoint ID for the local continuum. Moreover, in this case the value of bundles_TTL - if specified - will be taken as the lifetime in seconds that is to be declared for all \"bundles\" issued by ramsgate; bundles_TTL defaults to 86400 seconds (one day) if omitted.
"},{"location":"man/ams/ramsgate/#exit-status","title":"EXIT STATUS","text":"\"0\"
ramsgate terminated normally.
\"1\"
ramsgate failed, for reasons noted in the ion.log file; the task terminated.
A MIB initialization file with the applicable default name (see amsrc(5)) must be present.
ramsgate records all \"petitions\" (requests for data on behalf of AMS modules in other continua) in a file named \"petition.log\". At startup, the ramsgate daemon automatically reads and processes all petitions in the petition.log file just as if they were received in real time. Note that this means that you can cause petitions to be, in effect, \"pre-received\" by simply editing this file prior to startup. This can be an especially effective way to configure a RAMS network in which long signal propagation times would otherwise retard real-time petitioning and thus delay the onset of fully functional message exchange.
"},{"location":"man/ams/ramsgate/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ams/ramsgate/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ramsgate can't run.
RAMS gateway functionality failed, for reasons noted in the ion.log file.
Note that the AMS design principle of receiving messages immediately and enqueuing them for eventual ingestion by the application module - rather than imposing application-layer flow control on AMS message traffic - enables high performance but makes ramsgate vulnerable to message spikes. Since production and transmission of bundles is typically slower than AMS message reception over TCP service, the ION working memory and/or heap space available for AMS event insertion and/or bundle production can be quickly exhausted if a high rate of application message production is sustained for a long enough time. Mechanisms for defending against this sort of failure are under study, but for now the best mitigations are simply to (a) build with compiler option -DAMS_INDUSTRIAL=1, (b) allocate as much space as possible to ION working memory and SDR heap (see ionconfig(5)) and (c) limit the rate of AMS message issuance.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ams/ramsgate/#see-also","title":"SEE ALSO","text":"amsrc(5), petition_log(5)
"},{"location":"man/bpv6/","title":"Index of Man Pages","text":"acsadmin - ION Aggregate Custody Signal (ACS) administration interface
"},{"location":"man/bpv6/acsadmin/#synopsis","title":"SYNOPSIS","text":"acsadmin [ commands_filename ]
"},{"location":"man/bpv6/acsadmin/#description","title":"DESCRIPTION","text":"acsadmin configures aggregate custody signal behavior for the local ION node.
It operates in response to ACS configuration commands found in the file commands_filename, if provided; if not, acsadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from acsadmin with the 'h' or '?' commands at the prompt. The commands are documented in acsrc(5).
"},{"location":"man/bpv6/acsadmin/#exit-status","title":"EXIT STATUS","text":"acsadmin
Enter interactive ACS configuration command entry mode.
acsadmin host1.acs
Execute all configuration commands in host1.acs, then terminate immediately.
See acsrc(5) for details of the ACS configuration commands.
"},{"location":"man/bpv6/acsadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/acsadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the acsrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to acsadmin. Otherwise acsadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
acsadmin can't attach to ION.
There is no SDR data store for acsadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause acsadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see acsrc(5) for details.
"},{"location":"man/bpv6/acsadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/acsadmin/#see-also","title":"SEE ALSO","text":"ionadmin(1), bpadmin(1), acsrc(5)
"},{"location":"man/bpv6/acslist/","title":"NAME","text":"acslist - Aggregate Custody Signals (ACS) utility for checking custody IDs.
"},{"location":"man/bpv6/acslist/#synopsis","title":"SYNOPSIS","text":"acslist [-s|--stdout]
"},{"location":"man/bpv6/acslist/#description","title":"DESCRIPTION","text":"acslist is a utility program that lists all mappings from bundle ID to custody ID currently in the local bundle agent's ACS ID database, in no specific order. A bundle ID (defined in RFC5050) is the tuple of (source EID, creation time, creation count, fragment offset, fragment length). A custody ID (defined in draft-jenkins-aggregate-custody-signals) is an integer that the local bundle agent will be able to map to a bundle ID for the purposes of aggregating and compressing custody signals.
The format for mappings is:
(ipn:13.1,333823688,95,0,0)->(26)
While listing, acslist also checks the custody ID database for self-consistency, and if it detects any errors it will print a line starting with \"Mismatch:\" and describing the error.
-s|--stdout tells acslist to print results to stdout, rather than to the ION log.
"},{"location":"man/bpv6/acslist/#exit-status","title":"EXIT STATUS","text":"\"0\"
acslist terminated after verifying the consistency of the custody ID database.
\"1\"
acslist was unable to attach to the ACS database, or it detected an inconsistency.
No configuration files are needed.
"},{"location":"man/bpv6/acslist/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/acslist/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued:
Can't attach to ACS.
acsadmin has not yet initialized ACS operations.
Mismatch: (description of the mismatch)
acslist detected an inconsistency in the database; this is a bug in ACS.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/acslist/#see-also","title":"SEE ALSO","text":"acsadmin(1), bplist(1)
"},{"location":"man/bpv6/acsrc/","title":"NAME","text":"acsrc - Aggregate Custody Signal management commands file
"},{"location":"man/bpv6/acsrc/#description","title":"DESCRIPTION","text":"Aggregate Custody Signal management commands are passed to acsadmin either in a file of text lines or interactively at acsadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the Aggregate Custody Signal management commands are described below.
"},{"location":"man/bpv6/acsrc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 acsadmin 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 <logLevel> [<heapWords>]
The initialize command. Until this command is executed, Aggregate Custody Signals are not in operation on the local ION node and most acsadmin commands will fail.
The logLevel argument specifies at which log level the ACS appending and transmitting implementation should record its activity to the ION log file. This argument is the bitwise \"OR\" of the following log levels:
0x01 ERROR
Errors in ACS programming are logged.
0x02 WARN
Warnings like \"out of memory\" that don't cause ACS to fail but may change behavior are logged.
0x04 INFO
Informative information like \"this custody signal is a duplicate\" is logged.
0x08 DEBUG
Verbose information like the state of the pending ACS tree is logged.
The optional heapWords argument informs ACS to allocate that many heap words in its own DRAM SDR for constructing pending ACS. If not supplied, the default value 10000 is used. Once all ACS SDR is allocated, any incoming custodial bundles that would trigger an ACS will trigger a normal, non-aggregate custody signal instead, until ACS SDR is freed. If your node intermittently emits non-aggregate custody signals when it should emit ACS, you should increase heapWords.
Since ACS uses SDR only for emitting Aggregate Custody Signals, ION can still receive ACS even if this command is not executed, or all ACS SDR memory is allocated.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
s <minimumCustodyId>
This command sets the minimum custody ID that the local bundle agent may use in custody transfer enhancement blocks that it emits. These custody IDs must be unique in the network (for the lifetime of the bundles to which they refer).
The minimumCustodyId provided is stored in SDR, and incremented every time a new custody ID is required. So, this command should be used only when the local bundle agent has discarded its SDR and restarted.
t <acsBundleLifetime>
This command sets the lifetime that will be asserted for every ACS bundle subsequently issued by the local bundle agent. The new acsBundleLifetime is stored in SDR.
a custodianEid acsSize [acsDelay]
The add custodian command. This command provides information about the ACS characteristics of a remote custodian. custodianEid is the custodian EID for which this command is providing information. acsSize is the preferred size of ACS bundles sent to custodianEid; ACS bundles this implementation sends to custodianEid will aggregate until ACS are at most acsSize bytes (if acsSize is smaller than 19 bytes, some ACS containing only one signal will exceed acsSize and be sent anyways; setting acsSize to 0 causes \"aggregates\" of only 1 signal to be sent).
acsDelay is the maximum amount of time to delay an ACS destined for this custodian before sending it, in seconds; if not specified, the default value 15 will be used.
a ipn:15.0 100 27
Informs ACS on the local node that the local node should send ACS bundles destined for the custodian ipn:15.0 whenever they are 100 bytes in size or have been delayed for 27 seconds, whichever comes first.
acsadmin(1)
"},{"location":"man/bpv6/bibeclo/","title":"NAME","text":"bibeclo - BP convergence layer output task using bundle-in-bundle encapsulation
"},{"location":"man/bpv6/bibeclo/#synopsis","title":"SYNOPSIS","text":"bibeclo peer_node_eid destination_node_eid
"},{"location":"man/bpv6/bibeclo/#description","title":"DESCRIPTION","text":"bibeclo is a background \"daemon\" task that extracts bundles from the queues of bundles ready for transmission to destination_node_eid via bundle-in-bundle encapsulation (BIBE), encapsulates them in BP administrative records of (non-standard) record type 7 (BP_ENCAPSULATED_BUNDLE), and sends those administrative records to the DTN node identified by peer_node_eid. The receiving node is expected to process these received administrative records by simply dispatching the encapsulated bundles as if they had been received from neighboring nodes in the normal course of operations.
bibeclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. bibeclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BIBE convergence layer protocol.
"},{"location":"man/bpv6/bibeclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
bibeclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bibeclo.
\"1\"
bibeclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart bibeclo.
No configuration files are needed.
"},{"location":"man/bpv6/bibeclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bibeclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bibeclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such bibe duct.
No BIBE outduct with duct name destination_node_eid has been added to the BP database. Use bpadmin to stop the BIBE convergence-layer protocol, add the outduct, and then restart the BIBE protocol.
No such bcla.
No BIBE convergence layer adapter named peer_node_eid has been added to the BIBE database. Use bibeadmin to add the BCLA.
CLO task is already started for this duct.
Redundant initiation of bibeclo.
Can't prepend header; CLO stopping.
This is a system error. Check ION log, correct problem, and restart BIBE.
Can't send encapsulated bundle; CLO stopping.
This is a system error. Check ION log, correct problem, and restart BIBE.
[!] Encapsulated bundle not sent.
Malformed bundle issuance request, which might be a software error. Contact technical support.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bibeclo/#see-also","title":"SEE ALSO","text":"bibeadmin(1), bp(3), biberc(5)
"},{"location":"man/bpv6/bp/","title":"NAME","text":"bp - Bundle Protocol communications library
"},{"location":"man/bpv6/bp/#synopsis","title":"SYNOPSIS","text":"#include \"bp.h\"\n\n[see description for available functions]\nThe bp library provides functions enabling application software to use Bundle Protocol to send and receive information over a delay-tolerant network. It conforms to the Bundle Protocol specification as documented in Internet RFC 5050.
int bp_attach( )
Attaches the application to BP functionality on the local computer. Returns 0 on success, -1 on any error.
Note that all ION libraries and applications draw memory dynamically, as needed, from a shared pool of ION working memory. The size of the pool is established when ION node functionality is initialized by ionadmin(1). This is a precondition for initializing BP functionality by running bpadmin(1), which in turn is required in order for bp_attach() to succeed.
Sdr bp_get_sdr( )
Returns handle for the SDR data store used for BP, to enable creation and interrogation of bundle payloads (application data units).
void bp_detach( )
Terminates all access to BP functionality on the local computer.
int bp_open(char *eid, BpSAP *ionsapPtr)
Opens the application's access to the BP endpoint identified by eid, so that the application can take delivery of bundles destined for the indicated endpoint. This SAP can also be used for sending bundles whose source is the indicated endpoint; all bundles sent via this SAP will be subject to immediate destruction upon transmission, i.e., no bundle addresses will be returned by bp_send() for use in tracking, suspending/resuming, or cancelling transmission of these bundles. On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
int bp_open_source(char *eid, BpSAP *ionsapPtr, detain)
Opens the application's access to the BP endpoint identified by eid, so that the application can send bundles whose source is the indicated endpoint. If and only if the value of detain is non-zero, citing this SAP in an invocation of bp_send() will cause the address of the newly issued bundle to be returned for use in tracking, suspending/resuming, or cancelling transmission of this bundle. USE THIS FEATURE WITH GREAT CARE: such a bundle will continue to occupy storage resources until it is explicitly released by an invocation of bp_release() or until its time to live expires, so bundle detention increases the risk of resource exhaustion. (If the value of detain is zero, all bundles sent via this SAP will be subject to immediate destruction upon transmission.) On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
int bp_send(BpSAP sap, char *destEid, char *reportToEid, int lifespan, int classOfService, BpCustodySwitch custodySwitch, unsigned char srrFlags, int ackRequested, BpAncillaryData *ancillaryData, Object adu, Object *newBundle)
Sends a bundle to the endpoint identified by destEid, from the source endpoint as provided to the bp_open() call that returned sap. When sap is NULL, the transmitted bundle is anonymous, i.e., the source of the bundle is not identified. This is legal, but anonymous bundles cannot be uniquely identified; custody transfer and status reporting therefore cannot be requested for an anonymous bundle.
reportToEid identifies the endpoint to which any status reports pertaining to this bundle will be sent; if NULL, defaults to the source endpoint.
lifespan is the maximum number of seconds that the bundle can remain in-transit (undelivered) in the network prior to automatic deletion.
classOfService is simply priority for now: BP_BULK_PRIORITY, BP_STD_PRIORITY, or BP_EXPEDITED_PRIORITY. If class-of-service flags are defined in a future version of Bundle Protocol, those flags would be OR'd with priority.
custodySwitch indicates whether or not custody transfer is requested for this bundle and, if so, whether or not the source node itself is required to be the initial custodian. The valid values are SourceCustodyRequired, SourceCustodyOptional, NoCustodyRequired. Note that custody transfer is possible only for bundles that are uniquely identified, so it cannot be requested for bundles for which BP_MINIMUM_LATENCY is requested, since BP_MINIMUM_LATENCY may result in the production of multiple identical copies of the same bundle. Similarly, custody transfer should never be requested for a \"loopback\" bundle, i.e., one whose destination node is the same as the source node: the received bundle will be identical to the source bundle, both residing in the same node, so no custody acceptance signal can be applied to the source bundle and the source bundle will remain in storage until its TTL expires.
srrFlags, if non-zero, is the logical OR of the status reporting behaviors requested for this bundle: BP_RECEIVED_RPT, BP_CUSTODY_RPT, BP_FORWARDED_RPT, BP_DELIVERED_RPT, BP_DELETED_RPT.
ackRequested is a Boolean parameter indicating whether or not the recipient application should be notified that the source application requests some sort of application-specific end-to-end acknowledgment upon receipt of the bundle.
ancillaryData, if not NULL, is used to populate the Extended Class Of Service block for this bundle. The block's ordinal value is used to provide fine-grained ordering within \"expedited\" traffic: ordinal values from 0 (the default) to 254 (used to designate the most urgent traffic) are valid, with 255 reserved for custody signals. The value of the block's flags is the logical OR of the applicable extended class-of-service flags:
BP\\_MINIMUM\\_LATENCY designates the bundle as \"critical\" for the\npurposes of Contact Graph Routing.\n\nBP\\_BEST\\_EFFORT signifies that non-reliable convergence-layer protocols, as\navailable, may be used to transmit the bundle. Notably, the bundle may be\nsent as \"green\" data rather than \"red\" data when issued via LTP.\n\nBP\\_DATA\\_LABEL\\_PRESENT signifies whether or not the value of _dataLabel_\nin _ancillaryData_ must be encoded into the ECOS block when the bundle is\ntransmitted.\nadu is the \"application data unit\" that will be conveyed as the payload of the new bundle. adu must be a \"zero-copy object\" (ZCO). To ensure orderly access to transmission buffer space for all applications, adu must be created by invoking ionCreateZco(), which may be configured either to block so long as insufficient ZCO storage space is available for creation of the requested ZCO or to fail immediately if insufficient ZCO storage space is available.
The function returns 1 on success, 0 on user error, -1 on any system error. If 0 is returned, then an invalid argument value was passed to bp_send(); a message to this effect will have been written to the log file. If 1 is returned, then either the destination of the bundle was \"dtn:none\" (the bit bucket) or the ADU has been accepted and queued for transmission in a bundle. In the latter case, if and only if sap was a reference to a BpSAP returned by an invocation of bp_open_source() that had a non-zero value in the detain parameter, then newBundle must be non-NULL and the address of the newly created bundle within the ION database is placed in newBundle. This address can be used to track, suspend/resume, or cancel transmission of the bundle.
int bp_track(Object bundle, Object trackingElt)
Adds trackingElt to the list of \"tracking\" references in bundle. trackingElt must be the address of an SDR list element -- whose data is the address of this same bundle -- within some list of bundles that is privately managed by the application. Upon destruction of the bundle this list element will automatically be deleted, thus removing the bundle from the application's privately managed list of bundles. This enables the application to keep track of bundles that it is operating on without risk of inadvertently de-referencing the address of a nonexistent bundle.
void bp_untrack(Object bundle, Object trackingElt)
Removes trackingElt from the list of \"tracking\" references in bundle, if it is in that list. Does not delete trackingElt itself.
int bp_memo(Object bundle, unsigned int interval)
Implements custodial retransmission. This function inserts a \"custody-acceptance due\" event into the timeline. The event causes the indicated bundle to be re-forwarded if it is still in the database (i.e., it has not yet been accepted by another custodian) as of the time computed by adding the indicated interval to the current time.
int bp_suspend(Object bundle)
Suspends transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or if the bundle is already suspended. Otherwise, reverses the enqueuing of the bundle to its selected transmission outduct and places it in the \"limbo\" queue until the suspension is lifted by calling bp_resume. Returns 0 on success, -1 on any error.
int bp_resume(Object bundle)
Terminates suspension of transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or is not suspended. Otherwise, removes the bundle from the \"limbo\" queue and queues it for route re-computation and re-queuing. Returns 0 on success, -1 on any error.
int bp_cancel(Object bundle)
Cancels transmission of bundle. If the indicated bundle is currently queued for forwarding, transmission, or retransmission, it is removed from the relevant queue and destroyed exactly as if its Time To Live had expired. Returns 0 on success, -1 on any error.
int bp_release(Object bundle)
Releases a detained bundle for destruction when all retention constraints have been removed. After a detained bundle has been released, the application can no longer track, suspend/resume, or cancel its transmission. Returns 0 on success, -1 on any error.
int bp_receive(BpSAP sap, BpDelivery *dlvBuffer, int timeoutSeconds)
Receives a bundle, or reports on some failure of bundle reception activity.
The \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one bundle destined for the endpoint for which this SAP is opened has not yet been delivered to the SAP, then the payload of the oldest such bundle will be returned in dlvBuffer->adu and dlvBuffer->result will be set to BpPayloadPresent. If there is no such bundle, bp_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is BP_POLL (i.e., zero) and no bundle is awaiting delivery, or if timeoutSeconds is greater than zero but no bundle arrives before timeoutSeconds have elapsed, then dlvBuffer->result will be set to BpReceptionTimedOut. If timeoutSeconds is BP_BLOCKING (i.e., -1) then bp_receive() blocks until either a bundle arrives or the function is interrupted by an invocation of bp_interrupt().
dlvBuffer->result will be set to BpReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer->result will be set to BpEndpointStopped in the event that the operation of the indicated endpoint has been terminated.
The application data unit delivered in the data delivery structure, if any, will be a \"zero-copy object\" reference. Use zco reception functions (see zco(3)) to read the content of the application data unit.
Be sure to call bp_release_delivery() after every successful invocation of bp_receive().
The function returns 0 on success, -1 on any error.
void bp_interrupt(BpSAP sap)
Interrupts a bp_receive() invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, sap may need to be obtained from a static variable.
void bp_release_delivery(BpDelivery *dlvBuffer, int releaseAdu)
Releases resources allocated to the indicated delivery. releaseAdu is a Boolean parameter: if non-zero, the ADU ZCO reference in dlvBuffer (if any) is destroyed, causing the ZCO itself to be destroyed if no other references to it remain.
void bp_close(BpSAP sap)
Terminates the application's access to the BP endpoint identified by the eid cited by the indicated service access point. The application relinquishes its ability to take delivery of bundles destined for the indicated endpoint and to send bundles whose source is the indicated endpoint.
bpadmin(1), lgsend(1), lgagent(1), bpextensions(3), bprc(5), lgfile(5)
"},{"location":"man/bpv6/bpadmin/","title":"NAME","text":"bpadmin - ION Bundle Protocol (BP) administration interface
"},{"location":"man/bpv6/bpadmin/#synopsis","title":"SYNOPSIS","text":"bpadmin [ commands_filename | . | ! ]
"},{"location":"man/bpv6/bpadmin/#description","title":"DESCRIPTION","text":"bpadmin configures, starts, manages, and stops bundle protocol operations for the local ION node.
It operates in response to BP configuration commands found in the file commands_filename, if provided; if not, bpadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to bpadmin -- that is, the ION node's bpclock task, forwarder tasks, and convergence layer adapter tasks are stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's bpclock task, forwarder tasks, and convergence layer adapter tasks are restarted.
The format of commands for commands_filename can be queried from bpadmin with the 'h' or '?' commands at the prompt. The commands are documented in bprc(5).
"},{"location":"man/bpv6/bpadmin/#exit-status","title":"EXIT STATUS","text":"bpadmin
Enter interactive BP configuration command entry mode.
bpadmin host1.bp
Execute all configuration commands in host1.bp, then terminate immediately.
bpadmin .
Stop all bundle protocol operations on the local node.
See bprc(5) for details of the BP configuration commands.
"},{"location":"man/bpv6/bpadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the bprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bpadmin. Otherwise bpadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ION can't set custodian EID information.
The custodial_endpoint_id specified in the BP initialization ('1') command is malformed. Remember that the format for this argument is ipn:element_number.0 and that the final 0 is required, as custodial/administration service is always service 0. Additional detail for this error is provided if one of the following other errors is present:
Malformed EID.\n\nMalformed custodian EID.\nbpadmin can't attach to ION.
There is no SDR data store for bpadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bpadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see bprc(5) for details.
"},{"location":"man/bpv6/bpadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpadmin/#see-also","title":"SEE ALSO","text":"ionadmin(1), bprc(5), ipnadmin(1), ipnrc(5), dtnadmin(1), dtnrc(5)
"},{"location":"man/bpv6/bpcancel/","title":"NAME","text":"bpcancel - Bundle Protocol (BP) bundle cancellation utility
"},{"location":"man/bpv6/bpcancel/#synopsis","title":"SYNOPSIS","text":"bpcancel source_EID creation_seconds [creation_count [fragment_offset [fragment_length]]]
"},{"location":"man/bpv6/bpcancel/#description","title":"DESCRIPTION","text":"bpcancel attempts to locate the bundle identified by the command-line parameter values and cancel transmission of this bundle. Bundles for which multiple copies have been queued for transmission can't be canceled, because one or more of those copies might already have been transmitted. Transmission of a bundle that has never been cloned and that is still in local bundle storage is cancelled by simulation of an immediate time-to-live expiration.
"},{"location":"man/bpv6/bpcancel/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcancel has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bpcancel/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpcancel/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
bpcancel failed finding bundle.
The attempt to locate the subject bundle failed due to some serious system error. It will probably be necessary to terminate and re-initialize the local ION node.
bpcancel failed destroying bundle.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpcancel failed.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpcancel/#see-also","title":"SEE ALSO","text":"bplist(1)
"},{"location":"man/bpv6/bpchat/","title":"NAME","text":"bpchat - Bundle Protocol chat test program
"},{"location":"man/bpv6/bpchat/#synopsis","title":"SYNOPSIS","text":"bpchat sourceEID destEID [ct]
"},{"location":"man/bpv6/bpchat/#description","title":"DESCRIPTION","text":"bpchat uses Bundle Protocol to send input text in bundles, and display the payload of received bundles as output. It is similar to the talk utility, but operates over the Bundle Protocol. It operates like a combination of the bpsource and bpsink utilities in one program (unlike bpsource, bpchat emits bundles with a sourceEID).
If the sourceEID and destEID are both bpchat applications, then two users can chat with each other over the Bundle Protocol: lines that one user types on the keyboard will be transported over the network in bundles and displayed on the screen of the other user (and the reverse).
bpchat terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv6/bpchat/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpchat has terminated normally. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpchat has terminated due to a BP transmit or reception failure. Details should be noted in the ion.log log file.
If the string \"ct\" is appended as the last argument, then bundles will be sent with custody transfer requested.
No configuration files are needed.
"},{"location":"man/bpv6/bpchat/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpchat/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpchat are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpchat bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpchat can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpchat/#see-also","title":"SEE ALSO","text":"bpecho(1), bpsource(1), bpsink(1), bp(3)
"},{"location":"man/bpv6/bpclm/","title":"NAME","text":"bpclm - DTN bundle protocol convergence layer management daemon
"},{"location":"man/bpv6/bpclm/#synopsis","title":"SYNOPSIS","text":"bpclm neighboring_node_ID
"},{"location":"man/bpv6/bpclm/#description","title":"DESCRIPTION","text":"bpclm is a background \"daemon\" task that manages the transmission of bundles to a single designated neighboring node (as constrained by an \"egress plan\" data structure for that node) by one or more convergence-layer (CL) adapter output daemons (via buffer structures called \"outducts\").
bpclm is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. bpclm can also be spawned and terminated in response to commands that START and STOP the corresponding node's egress plan.
"},{"location":"man/bpv6/bpclm/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpclm terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the egress plan for this node.
\"1\"
bpclm terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the egress plan for this node.
No configuration files are needed.
"},{"location":"man/bpv6/bpclm/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpclm/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpclm can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No egress plan for this node
No egress plan for the node identified by neighboring_node_ID has been added to the BP database. Use bpadmin to add and start the plan.
bpclm task is already started for this node
Redundant initiation of bpclm.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpclm/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv6/bpclock/","title":"NAME","text":"bpclock - Bundle Protocol (BP) daemon task for managing scheduled events
"},{"location":"man/bpv6/bpclock/#synopsis","title":"SYNOPSIS","text":"bpclock
"},{"location":"man/bpv6/bpclock/#description","title":"DESCRIPTION","text":"bpclock is a background \"daemon\" task that periodically performs scheduled Bundle Protocol activities. It is spawned automatically by bpadmin in response to the 's' command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command.
Once per second, bpclock takes the following action:
First it (a) destroys all bundles whose TTLs have expired, (b) enqueues for re-forwarding all bundles that were expected to have been transmitted (by convergence-layer output tasks) by now but are still stuck in their assigned transmission queues, and (c) enqueues for re-forwarding all bundles for which custody has not yet been taken that were expected to have been received and acknowledged by now (as noted by invocation of the bpMemo() function by some convergence-layer adapter that had CL-specific insight into the appropriate interval to wait for custody acceptance).
Then bpclock adjusts the transmission and reception \"throttles\" that control rates of LTP transmission to and reception from neighboring nodes, in response to data rate changes as noted in the RFX database by rfxclock.
bpclock then checks for bundle origination activity that has been blocked due to insufficient allocated space for BP traffic in the ION data store: if space for bundle origination is now available, bpclock gives the bundle production throttle semaphore to unblock that activity.
Finally, bpclock applies rate control to all convergence-layer protocol inducts and outducts:
For each induct, bpclock increases the current capacity of the duct by the applicable nominal data reception rate. If the revised current capacity is greater than zero, bpclock gives the throttle's semaphore to unblock data acquisition (which correspondingly reduces the current capacity of the duct) by the associated convergence layer input task.
For each outduct, bpclock increases the current capacity of the duct by the applicable nominal data transmission rate. If the revised current capacity is greater than zero, bpclock gives the throttle's semaphore to unblock data transmission (which correspondingly reduces the current capacity of the duct) by the associated convergence layer output task.
"},{"location":"man/bpv6/bpclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bpclock.
\"1\"
bpclock was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/bpclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpclock can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't dispatch events.
An unrecoverable database error was encountered. bpclock terminates.
Can't adjust throttles.
An unrecoverable database error was encountered. bpclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpclock/#see-also","title":"SEE ALSO","text":"bpadmin(1), rfxclock(1)
"},{"location":"man/bpv6/bpcounter/","title":"NAME","text":"bpcounter - Bundle Protocol reception test program
"},{"location":"man/bpv6/bpcounter/#synopsis","title":"SYNOPSIS","text":"bpcounter ownEndpointId [maxCount]
"},{"location":"man/bpv6/bpcounter/#description","title":"DESCRIPTION","text":"bpcounter uses Bundle Protocol to receive application data units from a remote bpdriver application task. When the total number of application data units it has received exceeds maxCount, it terminates and prints its reception count. If maxCount is omitted, the default limit is 2 billion application data units.
"},{"location":"man/bpv6/bpcounter/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcounter has terminated. Any problems encountered during operation will be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv6/bpcounter/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpcounter/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpcounter are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpcounter bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpcounter/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpdriver(1), bpecho(1), bp(3)
"},{"location":"man/bpv6/bpdriver/","title":"NAME","text":"bpdriver - Bundle Protocol transmission test program
"},{"location":"man/bpv6/bpdriver/#synopsis","title":"SYNOPSIS","text":"bpdriver nbrOfCycles ownEndpointId destinationEndpointId [length] [t_TTL_]
"},{"location":"man/bpv6/bpdriver/#description","title":"DESCRIPTION","text":"bpdriver uses Bundle Protocol to send nbrOfCycles application data units of length indicated by length, to a counterpart application task that has opened the BP endpoint identified by destinationEndpointId.
If omitted, length defaults to 60000.
TTL indicates the number of seconds the bundles may remain in the network, undelivered, before they are automatically destroyed. If omitted, TTL defaults to 300 seconds.
bpdriver normally runs in \"echo\" mode: after sending each bundle it waits for an acknowledgment bundle before sending the next one. For this purpose, the counterpart application task should be bpecho.
Alternatively bpdriver can run in \"streaming\" mode, i.e., without expecting or receiving acknowledgments. Streaming mode is enabled when length is specified as a negative number, in which case the additive inverse of length is used as the effective value of length. For this purpose, the counterpart application task should be bpcounter.
If the effective value of length is 1, the sizes of the transmitted service data units will be randomly selected multiples of 1024 in the range 1024 to 62464.
bpdriver normally runs with custody transfer disabled. To request custody transfer for all bundles sent by bpdriver, specify nbrOfCycles as a negative number; the additive inverse of nbrOfCycles will be used as its effective value in this case.
When all copies of the file have been sent, bpdriver prints a performance report.
"},{"location":"man/bpv6/bpdriver/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpdriver has terminated. Any problems encountered during operation will be noted in the ion.log log file.
The service data units transmitted by bpdriver are sequences of text obtained from a file in the current working directory named \"bpdriverAduFile\", which bpdriver creates automatically.
"},{"location":"man/bpv6/bpdriver/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpdriver/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpdriver are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
Can't create ADU file
Operating system error. Check errtext, correct problem, and rerun.
Error writing to ADU file
Operating system error. Check errtext, correct problem, and rerun.
bpdriver can't create file ref.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpdriver can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpdriver can't send message
Bundle Protocol service to the remote endpoint has been stopped.
bpdriver reception failed
bpdriver is in \"echo\" mode, and Bundle Protocol delivery service has been stopped.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpdriver/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpcounter(1), bpecho(1), bp(3)
"},{"location":"man/bpv6/bpecho/","title":"NAME","text":"bpecho - Bundle Protocol reception test program
"},{"location":"man/bpv6/bpecho/#synopsis","title":"SYNOPSIS","text":"bpecho ownEndpointId
"},{"location":"man/bpv6/bpecho/#description","title":"DESCRIPTION","text":"bpecho uses Bundle Protocol to receive application data units from a remote bpdriver application task. In response to each received application data unit it sends back an \"echo\" application data unit of length 2, the NULL-terminated string \"x\".
bpecho terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv6/bpecho/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpecho has terminated normally. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpecho has terminated due to a BP reception failure. Details should be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv6/bpecho/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpecho/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpecho are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpecho bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpecho can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpecho/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpdriver(1), bpcounter(1), bp(3)
"},{"location":"man/bpv6/bpextensions/","title":"NAME","text":"bpextensions - interface for adding extensions to Bundle Protocol
"},{"location":"man/bpv6/bpextensions/#synopsis","title":"SYNOPSIS","text":"#include \"bpextensions.c\"\nION's interface for extending the Bundle Protocol enables the definition of external functions that insert extension blocks into outbound bundles (either before or after the payload block), parse and record extension blocks in inbound bundles, and modify extension blocks at key points in bundle processing. All extension-block handling is statically linked into ION at build time, but the addition of an extension never requires that any standard ION source code be modified.
Standard structures for recording extension blocks -- both in transient storage [memory] during bundle acquisition (AcqExtBlock) and in persistent storage [the ION database] during subsequent bundle processing (ExtensionBlock) -- are defined in the bei.h header file. In each case, the extension block structure comprises a block type code, block processing flags, possibly a list of EID references, an array of bytes (the serialized form of the block, for transmission), the length of that array, optionally an extension-specific opaque object whose structure is designed to characterize the block in a manner that's convenient for the extension processing functions, and the size of that object.
The definition of each extension is asserted in an ExtensionDef structure, also as defined in the bei.h header file. Each ExtensionDef must supply:
The name of the extension. (Used in some diagnostic messages.)
The extension's block type code.
A pointer to an offer function.
A pointer to a function to be called when forwarding a bundle containing this sort of block.
A pointer to a function to be called when taking custody of a bundle containing this sort of block.
A pointer to a function to be called when enqueuing for transmission a bundle containing this sort of block.
A pointer to a function to be called when a convergence-layer adapter dequeues a bundle containing this sort of block, before serializing it.
A pointer to a function to be called immediately before a convergence-layer adapter transmits a bundle containing this sort of block, after the bundle has been serialized.
A pointer to a release function.
A pointer to a copy function.
A pointer to an acquire function.
A pointer to a decrypt function.
A pointer to a parse function.
A pointer to a check function.
A pointer to a record function.
A pointer to a clear function.
All extension definitions must be coded into an array of ExtensionDef structures named extensionDefs.
An array of ExtensionSpec structures named extensionSpecs is also required. Each ExtensionSpec provides the specification for producing an outbound extension block: block definition (identified by block type number), three discriminator tags whose semantics are block-type-specific, and a list index value indicating whether the extension block is to be inserted before or after the Payload block. The order of appearance of extension specifications in the extensionSpecs array determines the order in which extension blocks will be inserted into locally sourced bundles.
The standard extensionDefs array -- which is empty -- is in the noextensions.c prototype source file. The procedure for extending the Bundle Protocol in ION is as follows:
1. Specify -DBP_EXTENDED in the Makefile's compiler command line when building the libbpP.c library module.
2. Create a copy of the prototype extensions file, named \"bpextensions.c\", in a directory that is made visible to the Makefile's libbpP.c compilation command line (by a -I parameter).
3. In the \"external function declarations\" area of \"bpextensions.c\", add \"extern\" function declarations identifying the functions that will implement your extension (or extensions).
4. Add one or more ExtensionDef structure initialization lines to the extensionDefs array, referencing those declared functions.
5. Add one or more ExtensionSpec structure initialization lines to the extensionSpecs array, referencing those extension definitions.
6. Develop the implementations of the extension implementation functions in one or more new source code files.
7. Add the object file or files for the new extension implementation source file (or files) to the Makefile's command line for linking libbpP.so.
The function pointers supplied in each ExtensionDef must conform to the following specifications. NOTE that any function that modifies the bytes member of an ExtensionBlock or AckExtBlock must set the corresponding length to the new length of the bytes array, if changed.
int (*BpExtBlkOfferFn)(ExtensionBlock *blk, Bundle *bundle)
Populates all fields of the indicated ExtensionBlock structure for inclusion in the indicated outbound bundle. This function is automatically called when a new bundle is locally sourced or upon acquisition of a remotely sourced bundle that does not contain an extension block of this type. The values of the extension block are typically expected to be a function of the state of the bundle, but this is extension-specific. If it is not appropriate to offer an extension block of this type as part of this bundle, then the size, length, object, and bytes members of blk must all be set to zero. If it is appropriate to offer such a block but no internal object representing the state of the block is needed, the object and size members of blk must be set to zero. The type, blkProcFlags, and dataLength members of blk must be populated by the implementation of the \"offer\" function, but the length and bytes members are typically populated by calling the BP library function serializeExtBlk(), which must be passed the block to be serialized (with type, blkProcFlags and dataLength already set), a Lyst of EID references (two list elements -- offsets -- per EID reference, if applicable; otherwise NULL), and a pointer to the extension-specific block data. The block's bytes array and object (if present) must occupy space allocated from the ION database heap. Return zero on success, -1 on any system failure.
int (*BpExtBlkProcessFn)(ExtensionBlock *blk, Bundle *bundle, void *context)
Performs some extension-specific transformation of the data encapsulated in blk based on the state of bundle. The transformation to be performed will typically vary depending on whether the identified function is the one that is automatically invoked upon forwarding the bundle, upon taking custody of the bundle, upon enqueuing the bundle for transmission, upon removing the bundle from the transmission queue, or upon transmitting the serialized bundle. The context argument may supply useful supplemental information; in particular, the context provided to the ON_DEQUEUE function will comprise the name of the protocol for the duct from which the bundle has been dequeued, together with the EID of the neighboring node endpoint to which the bundle will be directly transmitted when serialized. The block-specific data in blk is located within bytes immediately after the header of the extension block; the length of the block's header is the difference between length and dataLength. Whenever the block's blkProcFlags, EID extensions, and/or block-specific data are altered, the serializeExtBlk() function should be called again to recalculate the size of the extension block and rebuild the bytes array. Return zero on success, -1 on any system failure.
void (*BpExtBlkReleaseFn)(ExtensionBlock *blk)
Releases all ION database space occupied by the object member of blk. This function is automatically called when a bundle is destroyed. Note that incorrect implementation of this function may result in a database space leak.
int (*BpExtBlkCopyFn)(ExtensionBlock *newblk, ExtensionBlock *oldblk)
Copies the object member of oldblk to ION database heap space and places the address of that new non-volatile object in the object member of newblk, also sets size in newblk. This function is automatically called when two copies of a bundle are needed, e.g., in the event that it must both be delivered to a local client and also fowarded to another node. Return zero on success, -1 on any system failure.
int (*BpAcqExtBlkAcquireFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Populates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is only to be provided for extension blocks that are never encrypted; a extension block that may be encrypted should have a BpAcqExtBlkParseFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkDecryptFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Decrypts some other extension block that has been acquired but not yet parsed, nominally using encapsulated ciphersuite information. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if no error in decryption was encountered, -1 on any system failure.
int (*BpAcqExtBlkParseFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Populates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is provided for extension blocks that may be encrypted; a extension block that can never be encrypted should have a BpAcqExtBlkAcquireFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkCheckFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Examines the bundle in work to determine whether or not it is authentic, in the context of the indicated extension block. Return 1 if the block is determined to be inauthentic (this will cause the bundle to be discarded), zero if no inauthenticity is detected, -1 on any system failure.
int (*BpExtBlkRecordFn)(ExtensionBlock *blk, AcqExtBlock *acqblk)
Copies the object member of acqblk to ION database heap space and places the address of that non-volatile object in the object member of blk; also sets size in blk. This function is automatically called when an acquired bundle is accepted for forwarding and/or delivery. Return zero on success, -1 on any system failure.
void (*BpAcqExtBlkClearFn)(AcqExtBlock *acqblk)
Uses MRELEASE to release all ION working memory occupied by the object member of acqblk. This function is automatically called when acquisition of a bundle is completed, whether or not the bundle is accepted. Note that incorrect implementation of this function may result in a working memory leak.
void discardExtensionBlock(AcqExtBlock *blk)
Deletes this block from the bundle acquisition work area prior to the recording of the bundle in the ION database.
void scratchExtensionBlock(ExtensionBlock *blk)
Deletes this block from the bundle after the bundle has been recorded in the ION database.
Object findExtensionBlock(Bundle *bundle, unsigned int type, unsigned int listIdx)
On success, returns the address of the ExtensionBlock in bundle for the indicated type and listIdx. If no such extension block exists, returns zero.
int serializeExtBlk(ExtensionBlock *blk, Lyst eidReferences, char *blockData)
Constructs an RFC5050-conformant serialized representation of this extension block in blk->bytes. Returns 0 on success, -1 on an unrecoverable system error.
void suppressExtensionBlock(ExtensionBlock *blk)
Causes blk to be omitted when the bundle to which it is attached is serialized for transmission. This suppression remains in effect until it is reversed by restoreExtensionBlock();
void restoreExtensionBlock(ExtensionBlock *blk)
Reverses the effect of suppressExtensionBlock(), enabling the block to be included when the bundle to which it is attached is serialized.
bp(3)
"},{"location":"man/bpv6/bping/","title":"NAME","text":"bping - Send and receive Bundle Protocol echo bundles.
"},{"location":"man/bpv6/bping/#synopsis","title":"SYNOPSIS","text":"bping [-c count] [-i interval] [-p priority] [-q wait] [-r flags] [-t ttl] srcEID destEID [reporttoEID]
"},{"location":"man/bpv6/bping/#description","title":"DESCRIPTION","text":"bping sends bundles from srcEID to destEID. If the destEID echoes the bundles back (for instance, it is a bpecho endpoint), bping will print the round-trip time. When complete, bping will print statistics before exiting. It is very similar to ping, except it works with the bundle protocol.
bping terminates when one of the following happens: it receives the SIGINT signal (Ctrl+C), it receives responses to all of the bundles it sent, or it has sent all count of its bundles and waited wait seconds.
When bping is executed in a VxWorks or RTEMS environment, its runtime arguments are presented positionally rather than by keyword, in this order: count, interval, priority, wait, flags, TTL, verbosity (a Boolean, defaulting to zero), source EID, destination EID, report-to EID.
Source EID and destination EID are always required.
"},{"location":"man/bpv6/bping/#exit-status","title":"EXIT STATUS","text":"These exit statuses are taken from ping.
\"0\"
bping has terminated normally, and received responses to all the packets it sent.
\"1\"
bping has terminated normally, but it did not receive responses to all the packets it sent.
\"2\"
bping has terminated due to an error. Details should be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv6/bping/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bping/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bping are written to the ION log file ion.log and printed to standard error. Diagnostic messages that don't cause bping to terminate indicate a failure parsing an echo response bundle. This means that destEID isn't an echo endpoint: it's responding with some other bundle message of an unexpected format.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bping bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bping can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bping/#see-also","title":"SEE ALSO","text":"bpecho(1), bptrace(1), bpadmin(1), bp(3), ping(8)
"},{"location":"man/bpv6/bplist/","title":"NAME","text":"bplist - Bundle Protocol (BP) utility for listing queued bundles
"},{"location":"man/bpv6/bplist/#synopsis","title":"SYNOPSIS","text":"bplist [{count | detail} [destination_EID[/priority]]]
"},{"location":"man/bpv6/bplist/#description","title":"DESCRIPTION","text":"bplist is a utility program that reports on bundles that currently reside in the local node, as identified by entries in the local bundle agent's \"timeline\" list.
Either a count of bundles or a detailed list of bundles (noting primary block information together with hex and ASCII dumps of the payload and all extension blocks, in expiration-time sequence) may be requested.
Either all bundles or just a subset of bundles - restricted to bundles for a single destination endpoint, or to bundles of a given level of priority that are all destined for some specified endpoint - may be included in the report.
By default, bplist prints a detailed list of all bundles residing in the local node.
"},{"location":"man/bpv6/bplist/#exit-status","title":"EXIT STATUS","text":"\"0\"
bplist terminated, for reasons noted in the ion.log file.
\"1\"
bplist was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/bplist/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bplist/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bplist/#see-also","title":"SEE ALSO","text":"bpclock(1)
"},{"location":"man/bpv6/bpnmtest/","title":"NAME","text":"bpnmtest - Bundle Protocol (BP) network management statistics test
"},{"location":"man/bpv6/bpnmtest/#synopsis","title":"SYNOPSIS","text":"bpnmtest
"},{"location":"man/bpv6/bpnmtest/#description","title":"DESCRIPTION","text":"bpnmtest simply prints to stdout messages containing the current values of all BP network management tallies, then terminates.
"},{"location":"man/bpv6/bpnmtest/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpnmtest has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bpnmtest/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpnmtest/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bprc/","title":"NAME","text":"bprc - Bundle Protocol management commands file
"},{"location":"man/bpv6/bprc/#description","title":"DESCRIPTION","text":"Bundle Protocol management commands are passed to bpadmin either in a file of text lines or interactively at bpadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the Bundle Protocol management commands are described below.
"},{"location":"man/bpv6/bprc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 bpadmin 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 and the crypto suite BP was compiled with. HINT: combine with e 1 command to log the version number at startup.
1
The initialize command. Until this command is executed, Bundle Protocol is not in operation on the local ION node and most bpadmin commands will fail.
r 'command_text'
The run command. This command will execute command_text as if it had been typed at a console prompt. It is used to, for example, run another administrative program.
s
The start command. This command starts all schemes and all protocols on the local node.
m heapmax max_database_heap_per_acquisition
The manage heap for bundle acquisition command. This command declares the maximum number of bytes of SDR heap space that will be occupied by any single bundle acquisition activity (nominally the acquisition of a single bundle, but this is at the discretion of the convergence-layer input task). All data acquired in excess of this limit will be written to a temporary file pending extraction and dispatching of the acquired bundle or bundles. 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.
m maxcount max_value_of_bundle_ID_sequence_nbr
The manage maximum bundle ID sequence number command. This command sets the maximum value that will be assigned as the sequence number in a bundle ID for any bundle sourced at a node that lacks a synchronized clock (such that the creation time in the ID of every locally sourced bundle is always zero). The default value is -1, i.e., unlimited.
x
The stop command. This command stops all schemes and all protocols on the local node.
w { 0 | 1 | activity_spec }
The BP watch command. This command enables and disables production of a continuous stream of user-selected Bundle Protocol activity indication characters. A watch parameter of \"1\" selects all BP activity indication characters; \"0\" de-selects all BP activity indication characters; any other activity_spec such as \"acz~\" selects all activity indication characters in the string, de-selecting all others. BP will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
a new bundle is queued for forwarding
b bundle is queued for transmission
c bundle is popped from its transmission queue
m custody acceptance signal is received
w custody of bundle is accepted
x custody of bundle is refused
y bundle is accepted upon arrival
z bundle is queued for delivery to an application
~ bundle is abandoned (discarded) on attempt to forward it
! bundle is destroyed due to TTL expiration
& custody refusal signal is received
# bundle is queued for re-forwarding due to CL protocol failure
j bundle is placed in \"limbo\" for possible future re-forwarding
k bundle is removed from \"limbo\" and queued for re-forwarding
$ bundle's custodial retransmission timeout interval expired
Note that a slightly amended interpretation should be applied to watch characters printed in the course of multicast transmission. The '~' character, meaning Abandoned (node did not forward this bundle), is printed by a node that is a leaf of the multicast tree, i.e., a node with no children; it cannot forward the bundle because it's got nobody to forward it to. The '!' character, meaning Destroyed (node destroyed a physical copy of a bundle), is printed by a node that has forwarded copies of the bundle to all of its children and no longer needs to retain the original - so it does an immediate permanent bundle destruction just as if the bundle's time to live had expired. Neither condition is anomalous.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a scheme scheme_name 'forwarder_command' 'admin_app_command'
The add scheme command. This command declares an endpoint naming \"scheme\" for use in endpoint IDs, which are structured as URIs: scheme_name:scheme-specific_part. forwarder_command will be executed when the scheme is started on this node, to initiate operation of a forwarding daemon for this scheme. admin_app_command will also be executed when the scheme is started on this node, to initiate operation of a daemon that opens a custodian endpoint identified within this scheme so that it can receive and process custody signals and bundle status reports.
c scheme scheme_name 'forwarder_command' 'admin_app_command'
The change scheme command. This command sets the indicated scheme's forwarder_command and admin_app_command to the strings provided as arguments.
d scheme scheme_name
The delete scheme command. This command deletes the scheme identified by scheme_name. The command will fail if any bundles identified in this scheme are pending forwarding, transmission, or delivery.
i scheme scheme_name
This command will print information (number and commands) about the endpoint naming scheme identified by scheme_name.
l scheme
This command lists all declared endpoint naming schemes.
s scheme scheme_name
The start scheme command. This command starts the forwarder and administrative endpoint tasks for the indicated scheme task on the local node.
x scheme scheme_name
The stop scheme command. This command stops the forwarder and administrative endpoint tasks for the indicated scheme task on the local node.
a endpoint endpoint_ID { q | x } ['recv_script']
The add endpoint command. This command establishes a DTN endpoint named endpoint_ID on the local node. The remaining parameters indicate what is to be done when bundles destined for this endpoint arrive at a time when no application has got the endpoint open for bundle reception. If 'x', then such bundles are to be discarded silently and immediately. If 'q', then such bundles are to be enqueued for later delivery and, if recv_script is provided, recv_script is to be executed.
c endpoint endpoint_ID { q | x } ['recv_script']
The change endpoint command. This command changes the action that is to be taken when bundles destined for this endpoint arrive at a time when no application has got the endpoint open for bundle reception, as described above.
d endpoint endpoint_ID
The delete endpoint command. This command deletes the endpoint identified by endpoint_ID. The command will fail if any bundles are currently pending delivery to this endpoint.
i endpoint endpoint_ID
This command will print information (disposition and script) about the endpoint identified by endpoint_ID.
l endpoint
This command lists all local endpoints, regardless of scheme name.
a protocol protocol_name payload_bytes_per_frame overhead_bytes_per_frame [protocol_class]
The add protocol command. This command establishes access to the named convergence layer protocol at the local node. The payload_bytes_per_frame and overhead_bytes_per_frame arguments are used in calculating the estimated transmission capacity consumption of each bundle, to aid in route computation and congestion forecasting.
The optional protocol_class argument indicates the reliability of the protocol. The value 1 indicates that the protocol natively supports bundle streaming; currently the only protocol in class 1 is BSSP. The value 2 indicates that the protocol performs no retransmission; an example is UDP. The value 8 (which is the default) indicates that the protocol detects data loss and automatically retransmits data accordingly; an example is TCP. Protocol class need not be specified when protocol_name is bssp, udp, tcp, stcp, brss, brsc, or ltp, as the protocol classes for these well-known protocols are hard-coded in ION.
d protocol protocol_name
The delete protocol command. This command deletes the convergence layer protocol identified by protocol_name. The command will fail if any ducts are still locally declared for this protocol.
i protocol protocol_name
This command will print information about the convergence layer protocol identified by protocol_name.
l protocol
This command lists all convergence layer protocols that can currently be utilized at the local node.
s protocol protocol_name
The start protocol command. This command starts all induct and outduct tasks for inducts and outducts that have been defined for the indicated CL protocol on the local node.
x protocol protocol_name
The stop protocol command. This command stops all induct and outduct tasks for inducts and outducts that have been defined for the indicated CL protocol on the local node.
a induct protocol_name duct_name 'CLI_command'
The add induct command. This command establishes a \"duct\" for reception of bundles via the indicated CL protocol. The duct's data acquisition structure is used and populated by the \"induct\" task whose operation is initiated by CLI_command at the time the duct is started.
c induct protocol_name duct_name 'CLI_command'
The change induct command. This command changes the command that is used to initiate operation of the induct task for the indicated duct.
d induct protocol_name duct_name
The delete induct command. This command deletes the induct identified by protocol_name and duct_name. The command will fail if any bundles are currently pending acquisition via this induct.
i induct protocol_name duct_name
This command will print information (the CLI command) about the induct identified by protocol_name and duct_name.
l induct [protocol_name]
If protocol_name is specified, this command lists all inducts established locally for the indicated CL protocol. Otherwise it lists all locally established inducts, regardless of protocol.
s induct protocol_name duct_name
The start induct command. This command starts the indicated induct task as defined for the indicated CL protocol on the local node.
x induct protocol_name duct_name
The stop induct command. This command stops the indicated induct task as defined for the indicated CL protocol on the local node.
a outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The add outduct command. This command establishes a \"duct\" for transmission of bundles via the indicated CL protocol. The duct's data transmission structure is serviced by the \"outduct\" task whose operation is initiated by CLO_command at the time the duct is started. A value of zero for max_payload_length indicates that bundles of any size can be accommodated; this is the default.
c outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The change outduct command. This command sets new values for the indicated duct's payload size limit and the command that is used to initiate operation of the outduct task for this duct.
d outduct protocol_name duct_name
The delete outduct command. This command deletes the outduct identified by protocol_name and duct_name. The command will fail if any bundles are currently pending transmission via this outduct.
i outduct protocol_name duct_name
This command will print information (the CLO command) about the outduct identified by protocol_name and duct_name.
l outduct [protocol_name]
If protocol_name is specified, this command lists all outducts established locally for the indicated CL protocol. Otherwise it lists all locally established outducts, regardless of protocol.
s outduct protocol_name duct_name
The start outduct command. This command starts the indicated outduct task as defined for the indicated CL protocol on the local node.
x outduct protocol_name duct_name
The stop outduct command. This command stops the indicated outduct task as defined for the indicated CL protocol on the local node.
a plan endpoint_name [transmission_rate]
The add plan command. This command establishes an egress plan governing transmission to the neighboring node[s] identified by endpoint_name. The plan is functionally enacted by a bpclm(1) daemon dedicated to managing bundles queued for transmission to the indicated neighboring node[s].
NOTE that these \"plan\" commands supersede and generalize the egress plan commands documented in the ipnrc(5) and dtn2rc(5) man pages, which are retained for backward compatibility. The syntax of the egress plan commands consumed by bpadmin is DIFFERENT from that of the commands consumed by ipnadmin and dtn2admin. The endpoint_name identifying an egress plan is normally the node ID for a single node but may instead be \"wild-carded\". That is, when the last character of an endpoint name ID is either '*' or '~' (these two wild-card characters are equivalent for this purpose), the plan applies to all nodes whose IDs are identical to the wild-carded node name up to the wild-card character. For example, a bundle whose destination EID name is \"dtn://foghorn\" would be routed by plans citing the following node IDs: \"dtn://foghorn\", \"dtn://fogh*\", \"dtn://fog~\", \"//*\". When multiple plans are all applicable to the same destination EID, the one citing the longest (i.e., most narrowly targeted) node ID will be applied.
An egress plan may direct that bundles queued for transmission to the node[s] matching endpoint_name be transmitted using one of the convergence-layer protocol \"outducts\" that have been attached to the plan, or instead that those bundles be routed to some other \"gateway\" endpoint (resulting in transmission according to some other egress plan). In the event that both a gateway endpoint and one or more outducts have been declared for a given plan, the gateway declaration prevails.
A transmission_rate may be asserted for an egress plan; this rate is used as the basis for transmission rate control in the absence of applicable contacts (in the node's contact plan, as per ionrc(5)). A transmission rate of zero (absent applicable contacts) disables rate control completely; this is the default.
c plan endpoint_name [transmission_rate]
The change plan command. This command sets a new value for the indicated plan's transmission rate.
d plan endpoint_name
The delete plan command. This command deletes the outduct identified by endpoint_name. The command will fail if any bundles are currently pending transmission per this plan.
i plan endpoint_name
This command will print information (the transmission rate) about the plan identified by endpoint_name.
l plan
This command lists all locally established egress plans.
s plan endpoint_name
The start plan command. This command starts the bpclm(1) task for the indicated egress plan.
x plan endpoint_name
The stop plan command. This command stops the bpclm(1) task for the indicated egress plan.
b plan endpoint_name
The block plan command. This command disables transmission of bundles queued for transmission to the indicated node and reforwards all non-critical bundles currently queued for transmission to this node. This may result in some or all of these bundles being enqueued for transmission (actually just retention) to the pseudo-node \"limbo\".
u plan endpoint_name
The unblock plan command. This command re-enables transmission of bundles to the indicated node and reforwards all bundles in \"limbo\" in the hope that the unblocking of this egress plan will enable some of them to be transmitted.
g plan endpoint_name gateway_endpoint_name
The declare gateway command. This command declares the name of the endpoint to which bundles queued for transmission to the node[s] identified by endpoint_name must be re-routed. Declaring gateway_endpoint_name to be the zero-length string \"''\" disables re-routing: bundles will instead be transmitted using the plan's attached convergence-layer protocol outduct[s].
a planduct endpoint_name protocol_name duct_name
The attach outduct command. This command declares that the indicated convergence-layer protocol outduct is now a viable device for transmitting bundles to the node[s] identified by endpoint_name.
d planduct protocol_name duct_name
The detach outduct command. This command declares that the indicated convergence-layer protocol outduct is no longer a viable device for transmitting bundles to the node[s] to which it is currently assigned.
a scheme ipn 'ipnfw' 'ipnadminep'
Declares the \"ipn\" scheme on the local node.
a protocol udp 1400 100 16384
Establishes access to the \"udp\" convergence layer protocol on the local node, estimating the number of payload bytes per ultimate (lowest-layer) frame to be 1400 with 100 bytes of total overhead (BP, UDP, IP, AOS) per lowest-layer frame, and setting the default nominal data rate to be 16384 bytes per second.
r 'ipnadmin flyby.ipnrc'
Runs the administrative program ipnadmin from within bpadmin.
bpadmin(1), ipnadmin(1), dtn2admin(1)
"},{"location":"man/bpv6/bprecvfile/","title":"NAME","text":"bprecvfile - Bundle Protocol (BP) file reception utility
"},{"location":"man/bpv6/bprecvfile/#synopsis","title":"SYNOPSIS","text":"bprecvfile own_endpoint_ID [max_files]
"},{"location":"man/bpv6/bprecvfile/#description","title":"DESCRIPTION","text":"bprecvfile is intended to serve as the counterpart to bpsendfile. It uses bp_receive() to receive bundles containing file content. The content of each bundle is simply written to a file named \"testfileN\" where N is the total number of bundles received since the program began running.
If a max_files value of N (where N > 0) is provided, the program will terminate automatically upon completing its Nth file reception. Otherwise it will run indefinitely; use ^C to terminate the program.
"},{"location":"man/bpv6/bprecvfile/#exit-status","title":"EXIT STATUS","text":"\"0\"
bprecvfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bprecvfile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bprecvfile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
bprecvfile bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't open test file
File system error. bprecvfile terminates.
bprecvfile: can't receive bundle content.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't write to test file
File system error. bprecvfile terminates.
bprecvfile cannot continue.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't handle bundle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bprecvfile/#see-also","title":"SEE ALSO","text":"bpsendfile(1), bp(3)
"},{"location":"man/bpv6/bpsecadmin/","title":"NAME","text":"bpsecadmin - BP security policy administration interface
"},{"location":"man/bpv6/bpsecadmin/#synopsis","title":"SYNOPSIS","text":"bpsecadmin [ commands_filename ]
"},{"location":"man/bpv6/bpsecadmin/#description","title":"DESCRIPTION","text":"bpsecadmin configures and manages BP security policy on the local computer.
It configures and manages BP security policy on the local computer in response to BP configuration commands found in commands_filename, if provided; if not, bpsecadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from bpsecadmin by entering the command 'h' or '?' at the prompt. The commands are documented in bpsecrc(5).
"},{"location":"man/bpv6/bpsecadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of BP security policy administration.
bpsecadmin
Enter interactive ION security policy administration command entry mode.
bpsecadmin host1.bpsecrc
Execute all configuration commands in host1.bpsecrc, then terminate immediately.
Status and diagnostic messages from bpsecadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which bpsecadmin was run. The log file is typically named ion.log.
See also bpsecrc(5).
"},{"location":"man/bpv6/bpsecadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpsecadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bpsecadmin. Otherwise bpsecadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bpsecadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see bpsecrc(5) for details.
"},{"location":"man/bpv6/bpsecadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpsecadmin/#see-also","title":"SEE ALSO","text":"bpsecrc(5)
"},{"location":"man/bpv6/bpsecrc/","title":"NAME","text":"bpsecrc - BP security policy management commands file
"},{"location":"man/bpv6/bpsecrc/#description","title":"DESCRIPTION","text":"BP security policy management commands are passed to bpsecadmin either in a file of text lines or interactively at bpsecadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the BP security policy management commands are described below.
A parameter identifed as an eid_expr is an \"endpoint ID expression.\" For all commands, whenever the last character of an endpoint ID expression is the wild-card character '*', an applicable endpoint ID \"matches\" this EID expression if all characters of the endpoint ID expression prior to the last one are equal to the corresponding characters of that endpoint ID. Otherwise an applicable endpoint ID \"matches\" the EID expression only when all characters of the EID and EID expression are identical.
ION supports the proposed \"streamlined\" Bundle Security Protocol (currently posted as CCSDS Red Book 734.5-R-1) in place of the standard Bundle Security Protocol (RFC 6257). Since SBSP is not yet a published standard, ION's Bundle Protocol security mechanisms will not necessarily interoperate with those of other BP implementations. This is unfortunate but (we hope) temporary, as SBSP represents a major improvement in bundle security. It is possible that the SBSP specification will change somewhat between now and the time SBSP is published as a CCSDS standard and eventually an RFC, and ION will be revised as necessary to conform to those changes, but in the meantime we believe that the advantages of SBSP make it more suitable than RFC 6257 as a foundation for the development and deployment of secure DTN applications.
"},{"location":"man/bpv6/bpsecrc/#commands","title":"COMMANDS","text":"?
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 bpsecadmin 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.
a bspbibrule source_eid_expr destination_eid_expr block_type_number { '' | ciphersuite_name key_name }
The add bspbibrule command. This command adds a rule specifying the manner in which Block Integrity Block (BIB) validation will be applied to blocks of type block_type_number for all bundles sourced at any node whose administrative endpoint ID matches source_eid_expr and destined for any node whose administrative endpoint ID ID matches destination_eid_expr.
If a zero-length string ('') is indicated instead of a ciphersuite_name then BIB validation is disabled for this source/destination EID expression pair: blocks of the type indicated by block_type_number in all bundles sourced at nodes with matching administrative endpoint IDs and destined for nodes with matching administrative endpoint IDs will be immediately deemed valid. Otherwise, a block of the indicated type that is attached to a bundle sourced at a node with matching administrative endpoint ID and destined for a node with matching administrative endpoint ID will only be deemed valid if the bundle contains a corresponding BIB computed via the ciphersuite named by ciphersuite_name using a key value that is identical to the current value of the key named key_name in the local security policy database.
c bspbibrule source_eid_expr destination_eid_expr block_type_number { '' | ciphersuite_name key_name }
The change bspbibrule command. This command changes the ciphersuite name and/or key name for the BIB rule pertaining to the source/destination EID expression pair identified by source_eid_expr and destination_eid_expr and the block identified by block_type_number. Note that the _eid_expr_s must exactly match those of the rule that is to be modified, including any terminating wild-card character.
d bspbibrule source_eid_expr destination_eid_expr block_type_number
The delete bspbibrule command. This command deletes the BIB rule pertaining to the source/destination EID expression pair identified by sender_eid_expr and receiver_eid_expr and the block identified by block_type_number. Note that the _eid_expr_s must exactly match those of the rule that is to be deleted, including any terminating wild-card character.
i bspbibrule source_eid_expr destination_eid_expr block_type_number
This command will print information (the ciphersuite and key names) about the BIB rule pertaining to source_eid_expr, destination_eid_expr, and block_type_number.
l bspbibrule
This command lists all BIB rules in the security policy database.
a bspbcbrule source_eid_expr destination_eid_expr block_type_number { '' | ciphersuite_name key_name }
The add bspbcbrule command. This command adds a rule specifying the manner in which Block Confidentiality Block (BCB) encryption will be applied to blocks of type block_type_number for all bundles sourced at any node whose administrative endpoint ID matches source_eid_expr and destined for any node whose administrative endpoint ID ID matches destination_eid_expr.
If a zero-length string ('') is indicated instead of a ciphersuite_name then BCB encryption is disabled for this source/destination EID expression pair: blocks of the type indicated by block_type_number in all bundles sourced at nodes with matching administrative endpoint IDs and destined for nodes with matching administrative endpoint IDs will be sent in plain text. Otherwise, a block of the indicated type that is attached to a bundle sourced at a node with matching administrative endpoint ID and destined for a node with matching administrative endpoint ID can only be deemed decrypted if the bundle contains a corresponding BCB computed via the ciphersuite named by ciphersuite_name using a key value that is identical to the current value of the key named key_name in the local security policy database.
c bspbcbrule source_eid_expr destination_eid_expr block_type_number { '' | ciphersuite_name key_name }
The change bspbcbrule command. This command changes the ciphersuite name and/or key name for the BCB rule pertaining to the source/destination EID expression pair identified by source_eid_expr and destination_eid_expr and the block identified by block_type_number. Note that the _eid_expr_s must exactly match those of the rule that is to be modified, including any terminating wild-card character.
d bspbcbrule source_eid_expr destination_eid_expr block_type_number
The delete bspbcbrule command. This command deletes the BCB rule pertaining to the source/destination EID expression pair identified by sender_eid_expr and receiver_eid_expr and the block identified by block_type_number. Note that the _eid_expr_s must exactly match those of the rule that is to be deleted, including any terminating wild-card character.
i bspbcbrule source_eid_expr destination_eid_expr block_type_number
This command will print information (the ciphersuite and key names) about the BCB rule pertaining to source_eid_expr, destination_eid_expr, and block_type_number.
l bspbcbrule
This command lists all BCB rules in the security policy database.
x [ { ~ | sender_eid_expr } [ { ~ | receiver_eid_expr} [ { ~ | bib | bcb } ] ] ]
This command will clear all rules for the indicated type of bundle security block between the indicated security source and security destination. If block type is omitted it defaults to ~ signifying \"all SBSP blocks\". If both block type and security destination are omitted, security destination defaults to ~ signifying \"all SBSP security destinations\". If all three command-line parameters are omitted, then security source defaults to ~ signifying \"all SBSP security sources\".
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
bpsecadmin(1)
"},{"location":"man/bpv6/bpsendfile/","title":"NAME","text":"bpsendfile - Bundle Protocol (BP) file transmission utility
"},{"location":"man/bpv6/bpsendfile/#synopsis","title":"SYNOPSIS","text":"bpsendfile own_endpoint_ID destination_endpoint_ID file_name [class_of_service [time_to_live (seconds) ]]
"},{"location":"man/bpv6/bpsendfile/#description","title":"DESCRIPTION","text":"bpsendfile uses bp_send() to issue a single bundle to a designated destination endpoint, containing the contents of the file identified by file_name, then terminates. The bundle is sent with no custody transfer requested. When class_of_service is omitted, the bundle is sent at standard priority; for details of the class_of_service parameter, see bptrace(1). time_to_live, if not specified, defaults to 300 seconds (5 minutes). NOTE that time_to_live is specified AFTER class_of_service, rather than before it as in bptrace(1).
"},{"location":"man/bpv6/bpsendfile/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsendfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bpsendfile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpsendfile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
Can't stat the file
Operating system error. Check errtext, correct problem, and rerun.
bpsendfile can't create file ref.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpsendfile can't create ZCO.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpsendfile can't send file in bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpsendfile/#see-also","title":"SEE ALSO","text":"bprecvfile(1), bp(3)
"},{"location":"man/bpv6/bpsink/","title":"NAME","text":"bpsink - Bundle Protocol reception test program
"},{"location":"man/bpv6/bpsink/#synopsis","title":"SYNOPSIS","text":"bpsink ownEndpointId
"},{"location":"man/bpv6/bpsink/#description","title":"DESCRIPTION","text":"bpsink uses Bundle Protocol to receive application data units from a remote bpsource application task. For each application data unit it receives, it prints the ADU's length and -- if length is less than 80 -- its text.
bpsink terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv6/bpsink/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsink has terminated. Any problems encountered during operation will be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv6/bpsink/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpsink/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpsink are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpsink bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't receive payload.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't handle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpsink/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpsource(1), bp(3)
"},{"location":"man/bpv6/bpsource/","title":"NAME","text":"bpsource - Bundle Protocol transmission test shell
"},{"location":"man/bpv6/bpsource/#synopsis","title":"SYNOPSIS","text":"bpsource destinationEndpointId [\"text\"] [-t_TTL_]
"},{"location":"man/bpv6/bpsource/#description","title":"DESCRIPTION","text":"When text is supplied, bpsource simply uses Bundle Protocol to send text to a counterpart bpsink application task that has opened the BP endpoint identified by destinationEndpointId, then terminates.
Otherwise, bpsource offers the user an interactive \"shell\" for testing Bundle Protocol data transmission. bpsource prints a prompt string (\": \") to stdout, accepts a string of text from stdin, uses Bundle Protocol to send the string to a counterpart bpsink application task that has opened the BP endpoint identified by destinationEndpointId, then prints another prompt string and so on. To terminate the program, enter a string consisting of a single exclamation point (!) character.
TTL indicates the number of seconds the bundles may remain in the network, undelivered, before they are automatically destroyed. If omitted, TTL defaults to 300 seconds.
The source endpoint ID for each bundle sent by bpsource is the null endpoint ID, i.e., the bundles are anonymous. All bundles are sent standard priority with no custody transfer and no status reports requested.
"},{"location":"man/bpv6/bpsource/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsource has terminated. Any problems encountered during operation will be noted in the ion.log log file.
The service data units transmitted by bpsource are sequences of text obtained from a file in the current working directory named \"bpsourceAduFile\", which bpsource creates automatically.
"},{"location":"man/bpv6/bpsource/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpsource/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpsource are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
bpsource fgets failed
Operating system error. Check errtext, correct problem, and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpsource can't send ADU
Bundle Protocol service to the remote endpoint has been stopped.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpsource/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpsink(1), bp(3)
"},{"location":"man/bpv6/bpstats/","title":"NAME","text":"bpstats - Bundle Protocol (BP) processing statistics query utility
"},{"location":"man/bpv6/bpstats/#synopsis","title":"SYNOPSIS","text":"bpstats
"},{"location":"man/bpv6/bpstats/#description","title":"DESCRIPTION","text":"bpstats simply logs messages containing the current values of all BP processing statistics accumulators, then terminates.
"},{"location":"man/bpv6/bpstats/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpstats has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bpstats/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpstats/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpstats can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpstats/#see-also","title":"SEE ALSO","text":"ion(3)
"},{"location":"man/bpv6/bpstats2/","title":"NAME","text":"bpstats2 - Bundle Protocol (BP) processing statistics query utility via bundles
"},{"location":"man/bpv6/bpstats2/#synopsis","title":"SYNOPSIS","text":"bpstats2 sourceEID [default destEID] [ct]
"},{"location":"man/bpv6/bpstats2/#description","title":"DESCRIPTION","text":"bpstats2 creates bundles containing the current values of all BP processing statistics accumulators. It creates these bundles when:
\"0\"
bpstats2 has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpstats2 failed to start up or receive bundles. Diagnose the issue reported in the ion.log file and try again.
If the string \"ct\" is appended as the last argument, then statistics bundles will be sent with custody transfer requested.
No configuration files are needed.
"},{"location":"man/bpv6/bpstats2/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bpstats2/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpstats2 can't bp_attach().
bpadmin has not yet initialized BP operations.
bpstats2 can't open own endpoint.
Another BP application has opened that endpoint; close it and try again.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpstats2 can't send stats bundle.
Bundle Protocol service to the remote endpoint has been stopped.
Can't send stats: bad dest EID (dest EID)
The destination EID printed is an invalid destination EID. The destination EID may be specified in default destEID or the source EID of the interrogation bundle. Ensure that default destEID is an EID that is valid for ION, and that the interrogator is a source EID that is also a valid destination EID. Note that \"dtn:none\" is not a valid destination EID, but is a valid source EID.
A very simple interrogator is bpchat which can repeatedly interrogate bpstats2 by just striking the enter key.
"},{"location":"man/bpv6/bpstats2/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bpstats2/#see-also","title":"SEE ALSO","text":"bpstats(1), bpchat(1)
"},{"location":"man/bpv6/bptrace/","title":"NAME","text":"bptrace - Bundle Protocol (BP) network trace utility
"},{"location":"man/bpv6/bptrace/#synopsis","title":"SYNOPSIS","text":"bptrace own_endpoint_ID destination_endpoint_ID report-to_endpoint_ID TTL class_of_service \"trace_text\" [status_report_flags]
"},{"location":"man/bpv6/bptrace/#description","title":"DESCRIPTION","text":"bptrace uses bp_send() to issue a single bundle to a designated destination endpoint, with status reporting options enabled as selected by the user, then terminates. The status reports returned as the bundle makes its way through the network provide a view of the operation of the network as currently configured.
TTL indicates the number of seconds the trace bundle may remain in the network, undelivered, before it is automatically destroyed.
class_of_service is custody-requested.priority[.ordinal[.unreliable.critical[.data-label]]], where custody-requested must be 0 or 1 (Boolean), priority must be 0 (bulk) or 1 (standard) or 2 (expedited), ordinal must be 0-254, unreliable must be 0 or 1 (Boolean), critical must also be 0 or 1 (Boolean), and data-label may be any unsigned integer. ordinal is ignored if priority is not 2. Setting class_of_service to \"0.2.254\" or \"1.2.254\" gives a bundle the highest possible priority. Setting unreliable to 1 causes BP to forego retransmission in the event of data loss, both at the BP layer and at the convergence layer. Setting critical to 1 causes contact graph routing to forward the bundle on all plausible routes rather than just the \"best\" route it computes; this may result in multiple copies of the bundle arriving at the destination endpoint, but when used in conjunction with priority 2.254 it ensures that the bundle will be delivered as soon as physically possible.
trace_text can be any string of ASCII text; alternatively, if we want to send a file, it can be \"@\" followed by the file name.
status_report_flags must be a sequence of status report flags, separated by commas, with no embedded whitespace. Each status report flag must be one of the following: rcv, ct, fwd, dlv, del.
"},{"location":"man/bpv6/bptrace/#exit-status","title":"EXIT STATUS","text":"\"0\"
bptrace has terminated.
No configuration files are needed.
"},{"location":"man/bpv6/bptrace/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bptrace/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bptrace can't attach to BP.
bpadmin has not yet initialized BP operations.
bptrace can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
No space for bptrace text.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't create ZCO.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't send message.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bptrace/#see-also","title":"SEE ALSO","text":"bp(3)
"},{"location":"man/bpv6/bptransit/","title":"NAME","text":"bptransit - Bundle Protocol (BP) daemon task for forwarding received bundles
"},{"location":"man/bpv6/bptransit/#synopsis","title":"SYNOPSIS","text":"bptransit
"},{"location":"man/bpv6/bptransit/#description","title":"DESCRIPTION","text":"bptransit is a background \"daemon\" task that is responsible for presenting to ION's forwarding daemons any bundles that were received from other nodes (i.e., bundles whose payloads reside in Inbound ZCO space) and are destined for yet other nodes. In doing so, it migrates these bundles from Inbound buffer space to Outbound buffer space on the same prioritized basis as the insertion of locally sourced outbound bundles.
Management of the bptransit daemon is automatic. It is spawned automatically by bpadmin in response to the 's' command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command.
Whenever a received bundle is determined to have a destination other than the local node, a pointer to that bundle is appended to one of two queues of \"in-transit\" bundles, one for bundles whose forwarding is provisional (depending on the availability of Outbound ZCO buffer space; bundles in this queue are potentially subject to congestion loss) and one for bundles whose forwarding is confirmed. Bundles received via convergence-layer adapters that can sustain flow control, such as STCP, are appended to the \"confirmed\" queue, while those from CLAs that cannot sustain flow control (such as LTP) are appended to the \"provisional\" queue.
bptransit comprises two threads, one for each in-transit queue. The confirmed in-transit thread dequeues bundles from the \"confirmed\" queue and moves them from Inbound to Outbound ZCO buffer space, blocking (if necessary) until space becomes available. The provisional in-transit queue dequeues bundles from the \"provisional\" queue and moves them from Inbound to Outbound ZCO buffer space if Outbound space is available, discarding (\"abandoning\") them if it is not.
"},{"location":"man/bpv6/bptransit/#exit-status","title":"EXIT STATUS","text":"\"0\"
bptransit terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bptransit.
\"1\"
bptransit was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/bptransit/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/bptransit/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bptransit can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/bptransit/#see-also","title":"SEE ALSO","text":"bpadmin(1)
"},{"location":"man/bpv6/brsccla/","title":"NAME","text":"brsccla - BRSC-based BP convergence layer adapter (input and output) task
"},{"location":"man/bpv6/brsccla/#synopsis","title":"SYNOPSIS","text":"brsccla server_hostname[:server_port_nbr]_own_node_nbr
"},{"location":"man/bpv6/brsccla/#description","title":"DESCRIPTION","text":"BRSC is the \"client\" side of the Bundle Relay Service (BRS) convergence layer protocol for BP. It is complemented by BRSS, the \"server\" side of the BRS convergence layer protocol for BP. BRS clients send bundles directly only to the server, regardless of their final destinations, and the server forwards them to other clients as necessary.
brsccla is a background \"daemon\" task comprising three threads: one that connects to the BRS server, spawns the other threads, and then handles BRSC protocol output by transmitting bundles over the connected socket to the BRS server; one that simply sends periodic \"keepalive\" messages over the connected socket to the server (to assure that local inactivity doesn't cause the connection to be lost); and one that handles BRSC protocol input from the connected server.
The output thread connects to the server's TCP socket at server_hostname and server_port_nbr, sends over the connected socket the client's own_node_nbr (in SDNV representation) followed by a 32-bit time tag and a 160-bit HMAC-SHA1 digest of that time tag, to authenticate itself; checks the authenticity of the 160-bit countersign returned by the server; spawns the keepalive and receiver threads; and then begins extracting bundles from the queues of bundles ready for transmission via BRSC and transmitting those bundles over the connected socket to the server. Each transmitted bundle is preceded by its length, a 32-bit unsigned integer in network byte order. The default value for server_port_nbr, if omitted, is 80.
The reception thread receives bundles over the connected socket and passes them to the bundle protocol agent on the local ION node. Each bundle received on the connection is preceded by its length, a 32-bit unsigned integer in network byte order.
The keepalive thread simply sends a \"bundle length\" value of zero (a 32-bit unsigned integer in network byte order) to the server once every 15 seconds.
brsccla is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. brsccla can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BRSC convergence layer protocol.
"},{"location":"man/bpv6/brsccla/#exit-status","title":"EXIT STATUS","text":"\"0\"
brsccla terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSC protocol.
\"1\"
brsccla terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSC protocol.
No configuration files are needed.
"},{"location":"man/bpv6/brsccla/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/brsccla/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
brsccla can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such brsc induct.
No BRSC induct with duct name matching server_hostname, own_node_nbr, and server_port_nbr has been added to the BP database. Use bpadmin to stop the BRSC convergence-layer protocol, add the induct, and then restart the BRSC protocol.
CLI task is already started for this duct.
Redundant initiation of brsccla.
No such brsc outduct.
No BRSC outduct with duct name matching server_hostname, own_node_nbr, and server_port_nbr has been added to the BP database. Use bpadmin to stop the BRSC convergence-layer protocol, add the outduct, and then restart the BRSC protocol.
Can't connect to server.
Operating system error. Check errtext, correct problem, and restart BRSC.
Can't register with server.
Configuration error. Authentication has failed, probably because (a) the client and server are using different HMAC/SHA1 keys or (b) the clocks of the client and server differ by more than 5 seconds. Update security policy database(s), as necessary, and assure that the clocks are synchronized.
brsccla can't create receiver thread
Operating system error. Check errtext, correct problem, and restart BRSC.
brsccla can't create keepalive thread
Operating system error. Check errtext, correct problem, and restart BRSC.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/brsccla/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), brsscla(1)
"},{"location":"man/bpv6/brsscla/","title":"NAME","text":"brsscla - BRSS-based BP convergence layer adapter (input and output) task
"},{"location":"man/bpv6/brsscla/#synopsis","title":"SYNOPSIS","text":"brsscla local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/brsscla/#description","title":"DESCRIPTION","text":"BRSS is the \"server\" side of the Bundle Relay Service (BRS) convergence layer protocol for BP. It is complemented by BRSC, the \"client\" side of the BRS convergence layer protocol for BP.
brsscla is a background \"daemon\" task that spawns 2*N threads: one that handles BRSS client connections and spawns sockets for continued data interchange with connected clients; one that handles BRSS protocol output by transmitting over those spawned sockets to the associated clients; and two thread for each spawned socket, an input thread to handle BRSS protocol input from the associated connected client and an output thread to forward BRSS protocol output to the associated connected client.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 80.
Each reception thread receives over the socket connection the node number of the connecting client (in SDNV representation), followed by a 32-bit time tag and a 160-bit HMAC-SHA1 digest of that time tag. The receiving thread checks the time tag, requiring that it differ from the current time by no more than BRSTERM (default value 5) seconds. It then recomputes the digest value using the HMAC-SHA1 key named \"node_number.brs\" as recorded in the ION security database (see ionsecrc(5)), requiring that the supplied and computed digests be identical. If all registration conditions are met, the receiving thread sends the client a countersign -- a similarly computed HMAC-SHA1 digest, for the time tag that is 1 second later than the provided time tag -- to assure the client of its own authenticity, then commences receiving bundles over the connected socket. Each bundle received on the connection is preceded by its length, a 32-bit unsigned integer in network byte order. The received bundles are passed to the bundle protocol agent on the local ION node.
Each output thread extracts bundles from the queues of bundles ready for transmission via BRSS to the corresponding connected client and transmits the bundles over the socket to that client. Each transmitted bundle is preceded by its length, a 32-bit unsigned integer in network byte order.
brsscla is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. brsscla can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BRSS convergence layer protocol.
"},{"location":"man/bpv6/brsscla/#exit-status","title":"EXIT STATUS","text":"\"0\"
brsscla terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSS protocol.
\"1\"
brsscla terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSS protocol.
No configuration files are needed.
"},{"location":"man/bpv6/brsscla/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/brsscla/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
brsscla can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such brss induct.
No BRSS induct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the BRSS convergence-layer protocol, add the induct, and then restart the BRSS protocol.
CLI task is already started for this duct.
Redundant initiation of brsscla.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart BRSS.
Can't open TCP socket
Operating system error -- unable to open TCP socket for accepting connections. Check errtext, correct problem, and restart BRSS.
Can't initialize socket (note: must be root for port 80)
Operating system error. Check errtext, correct problem, and restart BRSS.
brsscla can't create sender thread
Operating system error. Check errtext, correct problem, and restart BRSS.
brsscla can't create access thread
Operating system error. Check errtext, correct problem, and restart BRSS.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/brsscla/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), brsccla(1)
"},{"location":"man/bpv6/cgrfetch/","title":"NAME","text":"cgrfetch - Visualize CGR simulations
"},{"location":"man/bpv6/cgrfetch/#synopsis","title":"SYNOPSIS","text":"cgrfetch [OPTIONS] DEST-NODE
"},{"location":"man/bpv6/cgrfetch/#description","title":"DESCRIPTION","text":"cgrfetch uses CGR to simulate sending a bundle from the local node to DEST-NODE. It traces the execution of CGR to generate graphs of the routes that were considered and the routes that were ultimately chosen to forward along. No bundle is sent during the simulation.
A JSON representation of the simulation is output to OUTPUT-FILE. The representation includes parameters of the simulation and a structure for each considered route, which in turn includes calculated parameters for the route and an image of the contact graph.
The dot(1) tool from the Graphviz package is used to generate the contact graph images and is required for cgrfetch(1). The base64(1) tool from coreutils is used to embed the images in the JSON and is also required.
Note that a trace of the route computation logic performed by CGR is printed to stderr; there is currently no cgrfetch option for redirecting this output to a file.
"},{"location":"man/bpv6/cgrfetch/#options","title":"OPTIONS","text":"DEST-NODE
The final destination to route to. To be useful, it should be a node that exists in the contact plan.
-q
Disable trace message output.
-j
Disable JSON output.
-m
Use a minimum-latency extended COS for the bundle. This ends up sending the bundle to all proximate nodes.
-t DISPATCH-OFFSET
Request a dispatch time of DISPATCH-OFFSET seconds from the time the command is run (default: 0).
-e EXPIRATION-OFFSET
Set the bundle expiration time to EXPIRATION-OFFSET seconds from the time the command is run (default: 3600).
-s BUNDLE-SIZE
Set the bundle payload size to BUNDLE-SIZE bytes (default: 0).
-o OUTPUT-FILE
Send JSON to OUTPUT-FILE (default: stdout).
-d PROTO:NAME
Use PROTO as the outduct protocol and NAME as the outduct name (default: udp:*). Use list to list all available outducts.
cgrfetch 8
Simulate CGR with destination node 8 and dispatch time equal to the current time.
cgrfetch 8 -t 60
Do the same with a dispatch time 60 seconds in the future.
cgrfetch -d list
List all available outducts.
dot(1), base64(1)
"},{"location":"man/bpv6/dccpcli/","title":"NAME","text":"dccpcli - DCCP-based BP convergence layer input task
"},{"location":"man/bpv6/dccpcli/#synopsis","title":"SYNOPSIS","text":"dccpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/dccpcli/#description","title":"DESCRIPTION","text":"dccpcli is a background \"daemon\" task that receives DCCP datagrams via a DCCP socket bound to local_hostname and local_port_nbr, extracts bundles from those datagrams, and passes them to the bundle protocol agent on the local ION node.
If not specified, port number defaults to 4556.
Note that dccpcli has no fragmentation support at all. Therefore, the largest bundle that can be sent via this convergence layer is limited to just under the link's MTU (typically 1500 bytes).
The convergence layer input task is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"dccp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. dccpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DCCP convergence layer protocol.
"},{"location":"man/bpv6/dccpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dccpcli.
\"1\"
dccpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dccpcli.
No configuration files are needed.
"},{"location":"man/bpv6/dccpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dccpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such dccp duct.
No DCCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DCCP convergence-layer protocol, add the induct, and then restart the DCCP protocol.
CLI task is already started for this duct.
Redundant initiation of dccpcli.
dccpcli can't get IP address for host.
Operating system error. Check errtext, correct problem, and restart dccpcli.
CLI can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccpcli.
CLI can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccpcli.
dccpcli can't get acquisition work area.
ION system error. Check errtext, correct problem, and restart dccpcli.
dccpcli can't create new thread.
Operating system error. Check errtext, correct problem, and restart dccpcli.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dccpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), dccpclo(1)
"},{"location":"man/bpv6/dccpclo/","title":"NAME","text":"dccpclo - DCCP-based BP convergence layer output task
"},{"location":"man/bpv6/dccpclo/#synopsis","title":"SYNOPSIS","text":"dccpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/dccpclo/#description","title":"DESCRIPTION","text":"dccpclo is a background \"daemon\" task that connects to a remote node's DCCP socket at remote_hostname and remote_port_nbr. It then begins extracting bundles from the queues of bundles ready for transmission via DCCP to this remote bundle protocol agent and transmitting those bundles as DCCP datagrams to the remote host.
If not specified, remote_port_nbr defaults to 4556.
Note that dccpclo has no fragmentation support at all. Therefore, the largest bundle that can be sent via this convergence layer is limited to just under the link's MTU (typically 1500 bytes).
dccpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dccpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DCCP convergence layer protocol.
"},{"location":"man/bpv6/dccpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dccpclo.
\"1\"
dccpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dccpclo.
No configuration files are needed.
"},{"location":"man/bpv6/dccpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dccpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No memory for DCCP buffer in dccpclo.
ION system error. Check errtext, correct problem, and restart dccpclo.
No such dccp duct.
No DCCP outduct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DCCP convergence-layer protocol, add the outduct, and then restart dccpclo.
CLO task is already started for this duct.
Redundant initiation of dccpclo.
dccpclo can't get IP address for host.
Operating system error. Check errtext, correct problem, and restart dccpclo.
dccpclo can't create thread.
Operating system error. Check errtext, correct problem, and restart dccpclo.
CLO can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccpclo.
CLO can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccpclo.
CLO send() error on socket.
Operating system error. Check errtext, correct problem, and restart dccpclo.
Bundle is too big for DCCP CLO.
Configuration error: bundles that are too large for DCCP transmission (i.e., larger than the MTU of the link or 65535 bytes--whichever is smaller) are being enqueued for dccpclo. Change routing or use smaller bundles.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dccpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), dccpcli(1)
"},{"location":"man/bpv6/dgrcli/","title":"NAME","text":"dgrcli - DGR-based BP convergence layer reception task
"},{"location":"man/bpv6/dgrcli/#synopsis","title":"SYNOPSIS","text":"dgrcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/dgrcli/#description","title":"DESCRIPTION","text":"dgrcli is a background \"daemon\" task that handles DGR convergence layer protocol input.
The daemon receives DGR messages via a UDP socket bound to local_hostname and local_port_nbr, extracts bundles from those messages, and passes them to the bundle protocol agent on the local ION node. (local_port_nbr defaults to 1113 if not specified.)
dgrcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dgrcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DGR convergence layer protocol.
"},{"location":"man/bpv6/dgrcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgrcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dgrcli.
\"1\"
dgrcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dgrcli.
No configuration files are needed.
"},{"location":"man/bpv6/dgrcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dgrcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dgrcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such dgr induct.
No DGR induct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DGR convergence-layer protocol, add the induct, and then restart the DGR protocol.
CLI task is already started for this engine.
Redundant initiation of dgrcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart DGR.
dgrcli can't open DGR service access point.
DGR system error. Check prior messages in ion.log log file, correct problem, and then stop and restart the DGR protocol.
dgrcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart DGR.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dgrcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv6/dgrclo/","title":"NAME","text":"dgrclo - DGR-based BP convergence layer transmission task
"},{"location":"man/bpv6/dgrclo/#synopsis","title":"SYNOPSIS","text":"dgrclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/dgrclo/#description","title":"DESCRIPTION","text":"dgrclo is a background \"daemon\" task that spawns two threads, one that handles DGR convergence layer protocol input (positive and negative acknowledgments) and a second that handles DGR convergence layer protocol output.
The output thread extracts bundles from the queues of bundles ready for transmission via DGR to a remote bundle protocol agent, encapsulates them in DGR messages, and uses a randomly configured local UDP socket to send those messages to the remote UDP socket bound to remote_hostname and remote_port_nbr. (local_port_nbr defaults to 1113 if not specified.)
The input thread receives DGR messages via the same local UDP socket and uses them to manage DGR retransmission of transmitted datagrams.
dgrclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dgrclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DGR convergence layer protocol.
"},{"location":"man/bpv6/dgrclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgrclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dgrclo.
\"1\"
dgrclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dgrclo.
No configuration files are needed.
"},{"location":"man/bpv6/dgrclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dgrclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dgrclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
CLI task is already started for this engine.
Redundant initiation of dgrclo.
No such dgr outduct.
No DGR outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the DGR convergence-layer protocol, add the outduct, and then restart the DGR protocol.
dgrclo can't open DGR service access point.
DGR system error. Check prior messages in ion.log log file, correct problem, and then stop and restart the DGR protocol.
dgrclo can't create sender thread
Operating system error. Check errtext, correct problem, and restart DGR.
dgrclo can't create receiver thread
Operating system error. Check errtext, correct problem, and restart DGR.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dgrclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv6/dtn2admin/","title":"NAME","text":"dtn2admin - baseline \"dtn\" scheme administration interface
"},{"location":"man/bpv6/dtn2admin/#synopsis","title":"SYNOPSIS","text":"dtn2admin [ commands_filename ]
"},{"location":"man/bpv6/dtn2admin/#description","title":"DESCRIPTION","text":"dtn2admin configures the local ION node's routing of bundles to endpoints whose IDs conform to the dtn endpoint ID scheme. dtn is a non-CBHE-conformant scheme. The structure of dtn endpoint IDs remains somewhat in flux at the time of this writing, but endpoint IDs in the dtn scheme historically have been strings of the form \"dtn://node_name[/demux_token]\", where node_name normally identifies a computer somewhere on the network and demux_token normally identifies a specific application processing point. Although the dtn endpoint ID scheme imposes more transmission overhead than the ipn scheme, ION provides support for dtn endpoint IDs to enable interoperation with other implementations of Bundle Protocol.
dtn2admin operates in response to \"dtn\" scheme configuration commands found in the file commands_filename, if provided; if not, dtn2admin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from dtn2admin with the 'h' or '?' commands at the prompt. The commands are documented in dtn2rc(5).
"},{"location":"man/bpv6/dtn2admin/#exit-status","title":"EXIT STATUS","text":"dtn2admin
Enter interactive \"dtn\" scheme configuration command entry mode.
dtn2admin host1.dtn2rc
Execute all configuration commands in host1.dtn2rc, then terminate immediately.
See dtn2rc(5) for details of the DTN scheme configuration commands.
"},{"location":"man/bpv6/dtn2admin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dtn2admin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the dtn2rc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to dtn2admin. Otherwise dtn2admin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
dtn2admin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
dtn2admin can't initialize routing database.
There is no SDR data store for dtn2admin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause dtn2admin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see dtn2rc(5) for details.
"},{"location":"man/bpv6/dtn2admin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dtn2admin/#see-also","title":"SEE ALSO","text":"dtn2rc(5)
"},{"location":"man/bpv6/dtn2adminep/","title":"NAME","text":"dtn2adminep - administrative endpoint task for the \"dtn\" scheme
"},{"location":"man/bpv6/dtn2adminep/#synopsis","title":"SYNOPSIS","text":"dtn2adminep
"},{"location":"man/bpv6/dtn2adminep/#description","title":"DESCRIPTION","text":"dtn2adminep is a background \"daemon\" task that receives and processes administrative bundles (all custody signals and, nominally, all bundle status reports) that are sent to the \"dtn\"-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. dtn2adminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the \"dtn\" scheme.
dtn2adminep responds to custody signals as specified in the Bundle Protocol specification, RFC 5050. It responds to bundle status reports by logging ASCII text messages describing the reported activity.
"},{"location":"man/bpv6/dtn2adminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtn2adminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dtn2adminep.
\"1\"
dtn2adminep was unable to attach to Bundle Protocol operations or was unable to load the \"dtn\" scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/dtn2adminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dtn2adminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtn2adminep can't attach to BP.
bpadmin has not yet initialized BP operations.
dtn2adminep can't load routing database.
dtn2admin has not yet initialized the \"dtn\" scheme.
dtn2adminep can't get admin EID.
dtn2admin has not yet initialized the \"dtn\" scheme.
dtn2adminep crashed.
An unrecoverable database error was encountered. dtn2adminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dtn2adminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), dtn2admin(1).
"},{"location":"man/bpv6/dtn2fw/","title":"NAME","text":"dtn2fw - bundle route computation task for the \"dtn\" scheme
"},{"location":"man/bpv6/dtn2fw/#synopsis","title":"SYNOPSIS","text":"dtn2fw
"},{"location":"man/bpv6/dtn2fw/#description","title":"DESCRIPTION","text":"dtn2fw is a background \"daemon\" task that pops bundles from the queue of bundle destined for \"dtn\"-scheme endpoints, computes proximate destinations for those bundles, and appends those bundles to the appropriate queues of bundles pending transmission to those computed proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is affected by static routes as configured by dtn2admin(1).
dtn2fw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. dtn2fw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the \"dtn\" scheme.
"},{"location":"man/bpv6/dtn2fw/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtn2fw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dtn2fw.
\"1\"
dtn2fw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dtn2fw.
No configuration files are needed.
"},{"location":"man/bpv6/dtn2fw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/dtn2fw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtn2fw can't attach to BP.
bpadmin has not yet initialized BP operations.
dtn2fw can't load routing database.
dtn2admin has not yet initialized the \"dtn\" scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. dtn2fw terminates.
'dtn' scheme is unknown.
The \"dtn\" scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. dtn2fw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. dtn2fw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/dtn2fw/#see-also","title":"SEE ALSO","text":"bpadmin(1), dtn2admin(1), bprc(5), dtn2rc(5).
"},{"location":"man/bpv6/dtn2rc/","title":"NAME","text":"dtn2rc - \"dtn\" scheme configuration commands file
"},{"location":"man/bpv6/dtn2rc/#description","title":"DESCRIPTION","text":"\"dtn\" scheme configuration commands are passed to dtn2admin either in a file of text lines or interactively at dtn2admin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
\"dtn\" scheme configuration commands establish static routing rules for forwarding bundles to \"dtn\"-scheme destination endpoints, identified by node ID. (Each node ID is simply a BP endpoint ID.)
Static routes are expressed as plans in the \"dtn\"-scheme routing database. A plan that is established for a given node name associates a routing directive with the named node. Each directive is a string of one of two possible forms:
f endpoint_ID
...or...
x protocol_name/outduct_name
The former form signifies that the bundle is to be forwarded to the indicated endpoint, requiring that it be re-queued for processing by the forwarder for that endpoint (which might, but need not, be identified by another \"dtn\"-scheme endpoint ID). The latter form signifies that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
The node IDs cited in dtn2rc plans may be \"wild-carded\". That is, when the last character of a node ID is either '*' or '~' (these two wild-card characters are equivalent for this purpose), the plan applies to all nodes whose IDs are identical to the wild-carded node name up to the wild-card character. For example, a bundle whose destination EID name is \"dtn://foghorn\" would be routed by plans citing the following node IDs: \"dtn://foghorn\", \"dtn://fogh*\", \"dtn://fog~\", \"//*\". When multiple plans are all applicable to the same destination EID, the one citing the longest (i.e., most narrowly targeted) node ID will be applied.
The formats and effects of the DTN scheme configuration commands are described below.
"},{"location":"man/bpv6/dtn2rc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 dtn2admin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a plan node_ID directive [nominal_xmit_rate]
The add plan command. This command establishes a static route for the bundles destined for the node(s) identified by node_ID. The nominal_xmit_rate is the assumed rate of transmission to this node in the absence of contact plan information. A nominal_data_rate of zero (the default) in the absence of contact plan information completely disables rate control.
Note that the plan commands consumed by dtn2admin are a simplified shortcut for submitting plan commands as consumed by bpadmin (see bprc(5)). The syntax of these commands is DIFFERENT from that of the more general and more powerful bpadmin commands.
c plan node_ID [directive] [nominal_xmit_rate]
The change plan command. This command revises the directive and/or nominal_data_rate of the static route for the node(s) identified by node_ID.
d plan node_ID
The delete plan command. This command deletes the static route for the node(s) identified by node_ID.
i plan node_ID
This command will print information about the static route for the node(s) identified by node_ID.
l plan
This command lists all static routes established in the DTN database for the local node.
a plan dtn://bbn2 f ipn:8.41
Declares a static route from the local node to node \"//bbn2\". Any bundle destined for any endpoint whose node name is \"//bbn2\" will be forwarded to endpoint \"ipn:8.41\".
a plan dtn://mitre1* x ltp/6
Declares a static route from the local node to node \"//mitre1\". Any bundle destined for any endpoint whose node ID begins with \"mitre1\" will be queued for transmission on LTP outduct 6.
dtn2admin(1)
"},{"location":"man/bpv6/hmackeys/","title":"NAME","text":"hmackeys - utility program for generating good HMAC-SHA1 keys
"},{"location":"man/bpv6/hmackeys/#synopsis","title":"SYNOPSIS","text":"hmackeys [ keynames_filename ]
"},{"location":"man/bpv6/hmackeys/#description","title":"DESCRIPTION","text":"hmackeys writes files containing randomized 160-bit key values suitable for use by HMAC-SHA1 in support of Bundle Authentication Block processing, Bundle Relay Service connections, or other functions for which symmetric hash computation is applicable. One file is written for each key name presented to hmackeys; the content of each file is 20 consecutive randomly selected 8-bit integer values, and the name given to each file is simply \"keyname.hmk\".
hmackeys operates in response to the key names found in the file keynames_filename, one name per file text line, if provided; if not, hmackeys prints a simple prompt (:) so that the user may type key names directly into standard input.
When the program is run in interactive mode, either enter 'q' or press ^C to terminate.
"},{"location":"man/bpv6/hmackeys/#exit-status","title":"EXIT STATUS","text":"hmackeys
Enter interactive HMAC/SHA1 key generation mode.
hmackeys host1.keynames
Create a key file for each key name in host1.keynames, then terminate immediately.
No other files are used in the operation of hmackeys.
"},{"location":"man/bpv6/hmackeys/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/hmackeys/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the logfile ion.log:
Can't open keynames file...
The keynames_filename specified in the command line doesn't exist.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/hmackeys/#see-also","title":"SEE ALSO","text":"brsscla(1), ionsecadmin(1)
"},{"location":"man/bpv6/imcadmin/","title":"NAME","text":"imcadmin - Interplanetary Multicast (IMC) scheme administration interface
"},{"location":"man/bpv6/imcadmin/#synopsis","title":"SYNOPSIS","text":"imcadmin [ commands_filename ]
"},{"location":"man/bpv6/imcadmin/#description","title":"DESCRIPTION","text":"imcadmin configures the local ION node's routing of bundles to endpoints whose IDs conform to the imc endpoint ID scheme. imc is a CBHE-conformant scheme; that is, every endpoint ID in the imc scheme is a string of the form \"imc:group_number.service_number\" where group_number (an IMC multicast group number) serves as a CBHE \"node number\" and service_number identifies a specific application processing point.
imcadmin operates in response to IMC scheme configuration commands found in the file commands_filename, if provided; if not, imcadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from imcadmin with the 'h' or '?' commands at the prompt. The commands are documented in imcrc(5).
"},{"location":"man/bpv6/imcadmin/#exit-status","title":"EXIT STATUS","text":"imcadmin
Enter interactive IMC scheme configuration command entry mode.
imcadmin host1.imcrc
Execute all configuration commands in host1.imcrc, then terminate immediately.
See imcrc(5) for details of the IMC scheme configuration commands.
"},{"location":"man/bpv6/imcadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/imcadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the imcrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to imcadmin. Otherwise imcadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
imcadmin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
imcadmin can't initialize routing database.
There is no SDR data store for imcadmin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause imcadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see imcrc(5) for details.
"},{"location":"man/bpv6/imcadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/imcadmin/#see-also","title":"SEE ALSO","text":"imcrc(5)
"},{"location":"man/bpv6/imcfw/","title":"NAME","text":"imcfw - bundle route computation task for the IMC scheme
"},{"location":"man/bpv6/imcfw/#synopsis","title":"SYNOPSIS","text":"imcfw
"},{"location":"man/bpv6/imcfw/#description","title":"DESCRIPTION","text":"imcfw is a background \"daemon\" task that pops bundles from the queue of bundle destined for IMC-scheme (Interplanetary Multicast) endpoints, determines which \"relatives\" on the IMC multicast tree to forward the bundles to, and appends those bundles to the appropriate queues of bundles pending transmission to those proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is determined by multicast group membership as resulting from nodes' registration in multicast endpoints, governed by multicast tree structure as configured by imcadmin(1).
imcfw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. imcfw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IMC scheme.
"},{"location":"man/bpv6/imcfw/#exit-status","title":"EXIT STATUS","text":"\"0\"
imcfw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart imcfw.
\"1\"
imcfw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart imcfw.
No configuration files are needed.
"},{"location":"man/bpv6/imcfw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/imcfw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
imcfw can't attach to BP.
bpadmin has not yet initialized BP operations.
imcfw can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. imcfw terminates.
'imc' scheme is unknown.
The IMC scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. imcfw terminates.
Can't exclude sender from routes.
An unrecoverable database error was encountered. imcfw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. imcfw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/imcfw/#see-also","title":"SEE ALSO","text":"bpadmin(1), imcadmin(1), bprc(5), imcrc(5)
"},{"location":"man/bpv6/imcrc/","title":"NAME","text":"imcrc - IMC scheme configuration commands file
"},{"location":"man/bpv6/imcrc/#description","title":"DESCRIPTION","text":"IMC scheme configuration commands are passed to imcadmin either in a file of text lines or interactively at imcadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
IMC scheme configuration commands simply establish which nodes are the local node's parents and children within a single IMC multicast tree. This single spanning tree, an overlay on a single BP-based network, is used to convey all multicast group membership assertions and cancellations in the network, for all groups. Each node privately tracks which of its immediate \"relatives\" in the tree are members of which multicast groups and on this basis selectively forwards -- directly, to all (and only) interested relatives -- the bundles destined for the members of each group.
Note that all of a node's immediate relatives in the multicast tree must be among its immediate neighbors in the underlying network. This is because multicast bundles can only be correctly forwarded within the tree if each forwarding node knows the identity of the relative that passed the bundle to it, so that the bundle is not passed back to that relative creating a routing loop. The identity of that prior forwarding node can only be known if the forwarding node was a neighbor, because no prior forwarding node (aside from the source) other than the immediate proximate (neighboring) sender of a received bundle is ever known.
IMC group IDs are unsigned integers, just as IPN node IDs are unsigned integers. The members of a group are nodes identified by node number, and the multicast tree parent and children of a node are neighboring nodes identified by node number.
The formats and effects of the IMC scheme configuration commands are described below.
"},{"location":"man/bpv6/imcrc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 ipnadmin to be logged as well as sent to stdout. Setting echo to 0 disables this behavior.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a node_nbr { 1 | 0 }
The add kin command. This command adds the neighboring node identified by node_nbr as an immediate relative of the local node. The Boolean value that follows the node number indicates whether or not this node is the local node's parent within the tree.
c node_nbr { 1 | 0 }
The change kin command. This command changes the parentage status of the indicated relative according to Boolean value that follows the node number, as noted for the add kin command.
d node_nbr
The delete kin command. This command deletes the immediate multicast tree relative identified by node_nbr. That node still exists but it is no longer a parent or child of the local node.
i node_nbr
This command will print information (the parentage switch) for the multicast tree relative identified by node_nbr.
l
This command lists all of the local node's multicast tree relatives, indicating which one is its parent in the tree.
a 983 1
Declares that 983 is the local node's parent in the network's multicast tree.
imcadmin(1)
"},{"location":"man/bpv6/ipnadmin/","title":"NAME","text":"ipnadmin - Interplanetary Internet (IPN) scheme administration interface
"},{"location":"man/bpv6/ipnadmin/#synopsis","title":"SYNOPSIS","text":"ipnadmin [ commands_filename ]
"},{"location":"man/bpv6/ipnadmin/#description","title":"DESCRIPTION","text":"ipnadmin configures the local ION node's routing of bundles to endpoints whose IDs conform to the ipn endpoint ID scheme. ipn is a CBHE-conformant scheme; that is, every endpoint ID in the ipn scheme is a string of the form \"ipn:node_number.service_number\" where node_number is a CBHE \"node number\" and service_number identifies a specific application processing point.
ipnadmin operates in response to IPN scheme configuration commands found in the file commands_filename, if provided; if not, ipnadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from ipnadmin with the 'h' or '?' commands at the prompt. The commands are documented in ipnrc(5).
"},{"location":"man/bpv6/ipnadmin/#exit-status","title":"EXIT STATUS","text":"ipnadmin
Enter interactive IPN scheme configuration command entry mode.
ipnadmin host1.ipnrc
Execute all configuration commands in host1.ipnrc, then terminate immediately.
See ipnrc(5) for details of the IPN scheme configuration commands.
"},{"location":"man/bpv6/ipnadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ipnadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ipnrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ipnadmin. Otherwise ipnadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ipnadmin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
ipnadmin can't initialize routing database.
There is no SDR data store for ipnadmin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ipnadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see ipnrc(5) for details.
"},{"location":"man/bpv6/ipnadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ipnadmin/#see-also","title":"SEE ALSO","text":"ipnrc(5)
"},{"location":"man/bpv6/ipnadminep/","title":"NAME","text":"ipnadminep - administrative endpoint task for the IPN scheme
"},{"location":"man/bpv6/ipnadminep/#synopsis","title":"SYNOPSIS","text":"ipnadminep
"},{"location":"man/bpv6/ipnadminep/#description","title":"DESCRIPTION","text":"ipnadminep is a background \"daemon\" task that receives and processes administrative bundles (all custody signals and, nominally, all bundle status reports) that are sent to the IPN-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. ipnadminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IPN scheme.
ipnadminep responds to custody signals as specified in the Bundle Protocol specification, RFC 5050. It responds to bundle status reports by logging ASCII text messages describing the reported activity.
"},{"location":"man/bpv6/ipnadminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
ipnadminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ipnadminep.
\"1\"
ipnadminep was unable to attach to Bundle Protocol operations or was unable to load the IPN scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv6/ipnadminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ipnadminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ipnadminep can't attach to BP.
bpadmin has not yet initialized BP operations.
ipnadminep can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
ipnadminep crashed.
An unrecoverable database error was encountered. ipnadminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ipnadminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), ipnadmin(1), bprc(5).
"},{"location":"man/bpv6/ipnd/","title":"NAME","text":"ipnd - ION IPND module
"},{"location":"man/bpv6/ipnd/#description","title":"DESCRIPTION","text":"The ipnd daemon is the ION implementation of DTN IP Neighbor Discovery. This module allows the node to send and receive beacon messages using unicast, multicast or broadcast IP addresses. Beacons are used for the discovery of neighbors and may be used to advertise services that are present and available on nodes, such as routing algorithms or CLAs.
ION IPND module is configured using a *.rc configuration file. The name of the configuration file must be passed as the sole command-line argument to ipnd when the daemon is started. Commands are interpreted line by line, with exactly one command per line. The formats and effects of the ION ipnd management commands are described below.
"},{"location":"man/bpv6/ipnd/#usage","title":"USAGE","text":"ipnd config_file_name
"},{"location":"man/bpv6/ipnd/#commands","title":"COMMANDS","text":"1
The initialize command. This must be the first command.
#
Comment line. Lines beginning with # are not interpreted.
e { 1 | 0 }
Echo control. Setting echo to 1 causes all output printed by ipnd to be logged into ion.log. Setting echo to 0 disables this behavior. Default is 1.
m eid eid
Local eid. This command sets the advertised BP endpoint ID by which the node will identify itself in beacon messages.
m announce period { 1 | 0 }
Announce period control. Setting to 1 causes all beacons messages sent to contain beacon period. Setting to 0 disables this behavior. Default is 1.
m announce eid { 1 | 0 }
Announce eid control. Setting to 1 causes all beacons messages sent to contain source eid. Setting to 0 disables this behavior. This should be always set to 1. Default is 1.
m interval unicast interval
Unicast interval. This command sets the beacon messages period on unicast transmissions. Time interval is expressed in seconds. Default is 5.
m interval multicast interval
Multicast interval. This command sets the beacon messages period on multicast transmissions. Time interval is expressed in seconds. Default is 7.
m interval broadcast interval
Broadcastcast interval. This command sets the beacon messages period on broadcast transmissions. Time interval is expressed in seconds. Default is 11.
m multicast ttl ttl
Multicast ttl. This command sets the multicast outgoing beacon messages' time to live, in seconds. Default is 255.
m svcdef id name child_name:child_type ...
Service definition. This command specifies definitions of \"services\", which are dynamically defined beacon message data structures indicating the capabilities of the beacon message sender. id is a service-identifying number in the range 128-255. name is the name of the service type that is being defined. The definition of the structure of the service is a sequence of elements, each of which is a name:type pair. Each child_type must be the name of a standard or previously defined service type. Infinite recursion is supported.
a svcadv name child_name:child_value ...
Service advertising command. This command defines which services will be advertised and with which values. All types of formats for values are supported (e.g. 999, 0345 (octal), 0x999 (hex), -1e-9, 0.32, etc.). For a service that contains only a single element, it is not necessary to provide that element's name. E.g. it is enough to write Booleans:true instead of Booleans:BooleanValues:B:true, as BooleanValues is the only child of Booleans and B is the only child of BooleanValues.
a listen IP_address
Listen socket specification command. This command asserts, in the form IP_address, the IP address of the socket at which the IPND daemon is to listen for incoming beacons; a default port number is used. The address can be an unicast, a multicast or a broadcast address. If a multicast address is provided all the configured unicast addresses will listen for multicast packets in that group. If a broadcast address is provided all the unicast addresses will listen for broadcasted packets.
a destination destination_socket_spec
Destination socket specification command. This command asserts the specification for a socket to which the IPND daemon is to send beacons. It can be an unicast, a multicast or a broadcast address.
s
The start command. This command starts the IPND daemon for the local ION node.
m scvdef 128 FooRouter Seed:SeedVal BaseWeight:WeightVal RootHash:bytes
Defines a new service called FooRouter comprising 3 elements. SeedVal and WeightVal are user defined services that must be already defined.
m svcdef 129 SeedVal Value:fixed16
m svcdef 130 WeightVal Value:fixed16
m svcdef 128 FooRouter Seed:SeedVal BaseWeight:WeightVal RootHash:bytes
m svcdef 150 FixedValuesList F16:fixed16 F32:fixed32 F64:fixed64
m svcdef 131 VariableValuesList U64:uint64 S64:sint64
m svcdef 132 BooleanValues B:boolean
m svcdef 133 FloatValuesList F:float D:double
m svcdef 135 IntegersList FixedValues:FixedValuesList VariableValues:VariableValuesList
m svcdef 136 NumbersList Integers:IntegersList Floats:FloatValuesList
m svcdef 140 HugeService CLAv4:CLA-TCP-v4 Booleans:BooleanValues Numbers:NumbersList FR:FooRouter
a svcadv HugeService CLAv4:IP:10.1.0.10 CLAv4:Port:4444 Booleans:true FR:Seed:0x5432 FR:BaseWeight:13 FR:RootHash:BEEF Numbers:Integers:FixedValues:F16:0x16 Numbers:Integers:FixedValues:F32:0x32 Numbers:Integers:FixedValues:F64:0x1234567890ABCDEF Numbers:Floats:F:0.32 Numbers:Floats:D:-1e-6 Numbers:Integers:VariableValues:U64:18446744073704783380 Numbers:Integers:VariableValues:S64:-4611686018422619668
This shows how to define multiple nested services and how to advertise them.
"},{"location":"man/bpv6/ipnd/#see-also","title":"SEE ALSO","text":"ion(3)
"},{"location":"man/bpv6/ipnfw/","title":"NAME","text":"ipnfw - bundle route computation task for the IPN scheme
"},{"location":"man/bpv6/ipnfw/#synopsis","title":"SYNOPSIS","text":"ipnfw
"},{"location":"man/bpv6/ipnfw/#description","title":"DESCRIPTION","text":"ipnfw is a background \"daemon\" task that pops bundles from the queue of bundle destined for IPN-scheme endpoints, computes proximate destinations for those bundles, and appends those bundles to the appropriate queues of bundles pending transmission to those computed proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is affected by static and default routes as configured by ipnadmin(1) and by contact graphs as managed by ionadmin(1) and rfxclock(1).
ipnfw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. ipnfw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IPN scheme.
"},{"location":"man/bpv6/ipnfw/#exit-status","title":"EXIT STATUS","text":"\"0\"
ipnfw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ipnfw.
\"1\"
ipnfw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart ipnfw.
No configuration files are needed.
"},{"location":"man/bpv6/ipnfw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ipnfw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ipnfw can't attach to BP.
bpadmin has not yet initialized BP operations.
ipnfw can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. ipnfw terminates.
'ipn' scheme is unknown.
The IPN scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. ipnfw terminates.
Can't exclude sender from routes.
An unrecoverable database error was encountered. ipnfw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. ipnfw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ipnfw/#see-also","title":"SEE ALSO","text":"bpadmin(1), ipnadmin(1), bprc(5), ipnrc(5)
"},{"location":"man/bpv6/ipnrc/","title":"NAME","text":"ipnrc - IPN scheme configuration commands file
"},{"location":"man/bpv6/ipnrc/#description","title":"DESCRIPTION","text":"IPN scheme configuration commands are passed to ipnadmin either in a file of text lines or interactively at ipnadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
IPN scheme configuration commands (a) establish egress plans for direct transmission to neighboring nodes that are members of endpoints identified in the \"ipn\" URI scheme and (b) establish static default routing rules for forwarding bundles to specified destination nodes.
The egress plan established for a given node associates a duct expression with that node. Each duct expression is a string of the form \"protocol_name/outduct_name\" signifying that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
Note that egress plans must be established for all neighboring nodes, regardless of whether or not contact graph routing is used for computing dynamic routes to distant nodes. This is by definition: if there isn't an egress plan to a node, it can't be considered a neighbor.
Static default routes are declared as exits in the ipn-scheme routing database. An exit is a range of node numbers identifying a set of nodes for which defined default routing behavior is established. Whenever a bundle is to be forwarded to a node whose number is in the exit's node number range and it has not been possible to compute a dynamic route to that node from the contact schedules that have been provided to the local node and that node is not a neighbor to which the bundle can be directly transmitted, BP will forward the bundle to the gateway node associated with this exit. The gateway node for any exit is identified by an endpoint ID, which might or might not be an ipn-scheme EID; regardless, directing a bundle to the gateway for an exit causes the bundle to be re-forwarded to that intermediate destination endpoint. Multiple exits may encompass the same node number, in which case the gateway associated with the most restrictive exit (the one with the smallest range) is always selected.
Note that \"exits\" were termed \"groups\" in earlier versions of ION. The term \"exit\" has been adopted instead, to minimize any possible confusion with multicast groups. To protect backward compatibility, the keyword \"group\" continues to be accepted by ipnadmin as an alias for the new keyword \"exit\", but the older terminology is deprecated.
The formats and effects of the IPN scheme configuration commands are described below.
"},{"location":"man/bpv6/ipnrc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 ipnadmin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a plan node_nbr duct_expression [nominal_data_rate]
The add plan command. This command establishes an egress plan for the bundles that must be transmitted to the neighboring node identified by node_nbr. The nominal_data_rate is the assumed rate of transmission to this node in the absence of contact plan information. A nominal_data_rate of zero (the default) in the absence of contact plan information completely disables rate control.
Note that the plan commands consumed by ipnadmin are a simplified shortcut for submitting plan commands as consumed by bpadmin (see bprc(5)). The syntax of these commands is DIFFERENT from that of the more general and more powerful bpadmin commands.
c plan node_nbr nominal_data_rate
The change plan command. This command changes the nominal data rate for the indicated plan.
d plan node_nbr
The delete plan command. This command deletes the egress plan for the node identified by node_nbr.
i plan node_nbr
This command will print information about the egress plan for the node identified by node_nbr.
l plan
This command lists all egress plans established in the IPN database for the local node.
a exit first_node_nbr last_node_nbr gateway_endpoint_ID
The add exit command. This command establishes an \"exit\" for static default routing as described above.
c exit first_node_nbr last_node_nbr gateway_endpoint_ID
The change exit command. This command changes the gateway node number for the exit identified by first_node_nbr and last_node_nbr .
d exit first_node_nbr last_node_nbr
The delete exit command. This command deletes the exit identified by first_node_nbr and last_node_nbr.
i exit first_node_nbr last_node_nbr
This command will print information (the gateway endpoint ID) about the exit identified by first_node_nbr and last_node_nbr.
l exit
This command lists all exits defined in the IPN database for the local node.
a rtovrd data_label dest_node_nbr source_node_nbr neighbor
The add rtovrd command. This command cause bundles characterized by data_label, dest_node_nbr (\"all other destinations\" if this node number is zero) and source_node_nbr (\"all other sources\" if this node number is zero) to be forwarded to neighbor. If neighbor is zero, the override will be \"learned\" by ION: the neighbor selected for this bundle, by whatever means, becomes the override for all subsequent matching bundles.
c rtovrd data_label dest_node_nbr source_node_nbr neighbor
The change rtovrd command. This command changes the override neighbor for the override identified by data_label, dest_node_nbr, and source_node_nbr. To cause ION to forget the override, use -1 as neighbor.
a cosovrd data_label dest_node_nbr source_node_nbr priority ordinal
The add cosovrd command. This command cause bundles characterized by data_label, dest_node_nbr (\"all other destinations\" if this node number is zero) and source_node_nbr (\"all other sources\" if this node number is zero) to have their effective class of service (priority and ordinal) changed as noted.
c cosovrd data_label dest_node_nbr source_node_nbr priority ordinal
The change cosovrd command. This command changes the override priority and ordinal for the override identified by data_label, dest_node_nbr, and source_node_nbr. To cause ION to forget the override, use -1 as priority.
d ovrd data_label dest_node_nbr source_node_nbr
The delete override command. This command deletes all overrides identified by data_label, dest_node_nbr, and source_node_nbr.
i ovrd data_label dest_node_nbr source_node_nbr
This command will print information for all overrides identified by data_label, dest_node_nbr, and source_node_nbr.
l ovrd
This command lists all overrides defined in the IPN database for the local node.
a plan 18 ltp/18
Declares the egress plan to use for transmission from the local node to neighboring node 18. By default, any bundle for which the computed \"next hop\" node is node 18 will be queued for transmission on LTP outduct 18.
a exit 1 999 dtn://stargate
Declares a default route for bundles destined for all nodes whose numbers are in the range 1 through 999 inclusive: absent any other routing decision, such bundles are to be forwarded to \"dtn://stargate\".
ipnadmin(1)
"},{"location":"man/bpv6/lgagent/","title":"NAME","text":"lgagent - ION Load/Go remote agent program
"},{"location":"man/bpv6/lgagent/#synopsis","title":"SYNOPSIS","text":"lgagent own_endpoint_ID
"},{"location":"man/bpv6/lgagent/#description","title":"DESCRIPTION","text":"ION Load/Go is a system for management of an ION-based network, enabling the execution of ION administrative programs at remote nodes. The system comprises two programs, lgsend and lgagent.
The lgagent task on a given node opens the indicated ION endpoint for bundle reception, receives the extracted payloads of Load/Go bundles sent to it by lgsend as run on one or more remote nodes, and processes those payloads, which are the text of Load/Go source files.
Load/Go source file content is limited to newline-terminated lines of ASCII characters. More specifically, the text of any Load/Go source file is a sequence of line sets of two types: file capsules and directives. Any Load/Go source file may contain any number of file capsules and any number of directives, freely intermingled in any order, but the typical structure of a Load/Go source file is simply a single file capsule followed by a single directive.
When lgagent identifies a file capsule, it copies all of the capsule's text lines to a new file that it creates in the current working directory. When lgagent identifies a directive, it executes the directive by passing the text of the directive to the pseudoshell() function (see platform(3)). lgagent processes the line sets of a Load/Go source file in the order in which they appear in the file, so the text of a directive may reference a file that was created as the result of processing a prior file capsule in the same source file.
"},{"location":"man/bpv6/lgagent/#exit-status","title":"EXIT STATUS","text":"\"0\"
Load/Go remote agent processing has terminated.
lgfile contains the Load/Go file capsules and directives that are to be processed.
"},{"location":"man/bpv6/lgagent/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/lgagent/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
lgagent: can't attach to BP.
Bundle Protocol is not running on this computer. Run bpadmin(1) to start BP.
lgagent: can't open own endpoint.
own_endpoint_ID is not a declared endpoint on the local ION node. Run bpadmin(1) to add it.
lgagent: bundle reception failed.
ION system problem. Investigate and correct before restarting.
lgagent cannot continue.
lgagent processing problem. See earlier diagnostic messages for details. Investigate and correct before restarting.
lgagent: no space for bundle content.
ION system problem: have exhausted available SDR data store reserves.
lgagent: can't receive bundle content.
ION system problem: have exhausted available SDR data store reserves.
lgagent: can't handle bundle delivery.
ION system problem. Investigate and correct before restarting.
lgagent: pseudoshell failed.
Error in directive line, usually an attempt to execute a non-existent administration program (e.g., a misspelled program name). Terminates processing of source file content.
A variety of other diagnostics noting source file parsing problems may also be reported. These errors are non-fatal but they terminate the processing of the source file content from the most recently received bundle.
"},{"location":"man/bpv6/lgagent/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/lgagent/#see-also","title":"SEE ALSO","text":"lgsend(1), lgfile(5)
"},{"location":"man/bpv6/lgfile/","title":"NAME","text":"lgfile - ION Load/Go source file
"},{"location":"man/bpv6/lgfile/#description","title":"DESCRIPTION","text":"The ION Load/Go system enables the execution of ION administrative programs at remote nodes:
The lgsend program reads a Load/Go source file from a local file system, encapsulates the text of that source file in a bundle, and sends the bundle to a designated DTN endpoint on the remote node.
An lgagent task running on the remote node, which has opened that DTN endpoint for bundle reception, receives the extracted payload of the bundle -- the text of the Load/Go source file -- and processes it.
Load/Go source file content is limited to newline-terminated lines of ASCII characters. More specifically, the text of any Load/Go source file is a sequence of line sets of two types: file capsules and directives. Any Load/Go source file may contain any number of file capsules and any number of directives, freely intermingled in any order, but the typical structure of a Load/Go source file is simply a single file capsule followed by a single directive.
Each file capsule is structured as a single start-of-capsule line, followed by zero or more capsule text lines, followed by a single end-of-capsule line. Each start-of-capsule line is of this form:
[file_name
Each capsule text line can be any line of ASCII text that does not begin with an opening ([) or closing (]) bracket character.
A text line that begins with a closing bracket character (]) is interpreted as an end-of-capsule line.
A directive is any line of text that is not one of the lines of a file capsule and that is of this form:
!directive_text
When lgagent identifies a file capsule, it copies all of the capsule's text lines to a new file named file_name that it creates in the current working directory. When lgagent identifies a directive, it executes the directive by passing directive_text to the pseudoshell() function (see platform(3)). lgagent processes the line sets of a Load/Go source file in the order in which they appear in the file, so the directive_text of a directive may reference a file that was created as the result of processing a prior file capsule line set in the same source file.
Note that lgfile directives are passed to pseudoshell(), which on a VxWorks platform will always spawn a new task; the first argument in directive_text must be a symbol that VxWorks can resolve to a function, not a shell command. Also note that the arguments in directive_text will be actual task arguments, not shell command-line arguments, so they should never be enclosed in double-quote characters (\"). However, any argument that contains embedded whitespace must be enclosed in single-quote characters (') so that pseudoshell() can parse it correctly.
"},{"location":"man/bpv6/lgfile/#examples","title":"EXAMPLES","text":"Presenting the following lines of source file text to lgsend:
[cmd33.bprc
x protocol ltp
]
!bpadmin cmd33.bprc
should cause the receiving node to halt the operation of the LTP convergence-layer protocol.
"},{"location":"man/bpv6/lgfile/#see-also","title":"SEE ALSO","text":"lgsend(1), lgagent(1), platform(3)
"},{"location":"man/bpv6/lgsend/","title":"NAME","text":"lgsend - ION Load/Go command program
"},{"location":"man/bpv6/lgsend/#synopsis","title":"SYNOPSIS","text":"lgsend command_file_name own_endpoint_ID destination_endpoint_ID
"},{"location":"man/bpv6/lgsend/#description","title":"DESCRIPTION","text":"ION Load/Go is a system for management of an ION-based network, enabling the execution of ION administrative programs at remote nodes. The system comprises two programs, lgsend and lgagent.
The lgsend program reads a Load/Go source file from a local file system, encapsulates the text of that source file in a bundle, and sends the bundle to an lgagent task that is waiting for data at a designated DTN endpoint on the remote node.
To do so, it first reads all lines of the Load/Go source file identified by command_file_name into a temporary buffer in ION's SDR data store, concatenating the lines of the file and retaining all newline characters. Then it invokes the bp_send() function to create and send a bundle whose payload is this temporary buffer, whose destination is destination_endpoint_ID, and whose source endpoint ID is own_endpoint_ID. Then it terminates.
"},{"location":"man/bpv6/lgsend/#exit-status","title":"EXIT STATUS","text":"\"0\"
Load/Go file transmission succeeded.
\"1\"
Load/Go file transmission failed. Examine ion.log to determine the cause of the failure, then re-run.
lgfile contains the Load/Go file capsules and directive that are to be sent to the remote node.
"},{"location":"man/bpv6/lgsend/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/lgsend/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
lgsend: can't attach to BP.
Bundle Protocol is not running on this computer. Run bpadmin(1) to start BP.
lgsend: can't open own endpoint.
own_endpoint_ID is not a declared endpoint on the local ION node. Run bpadmin(1) to add it.
lgsend: can't open file of LG commands: error description
command_file_name doesn't identify a file that can be opened. Correct spelling of file name or file's access permissions.
lgsend: can't get size of LG command file: error description
Operating system problem. Investigate and correct before rerunning.
lgsend: LG cmd file size > 64000.
Load/Go command file is too large. Split it into multiple files if possible.
lgsend: no space for application data unit.
ION system problem: have exhausted available SDR data store reserves.
lgsend: fgets failed: error description
Operating system problem. Investigate and correct before rerunning.
lgsend: can't create application data unit.
ION system problem: have exhausted available SDR data store reserves.
lgsend: can't send bundle.
ION system problem. Investigate and correct before rerunning.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/lgsend/#see-also","title":"SEE ALSO","text":"lgagent(1), lgfile(5)
"},{"location":"man/bpv6/ltpcli/","title":"NAME","text":"ltpcli - LTP-based BP convergence layer input task
"},{"location":"man/bpv6/ltpcli/#synopsis","title":"SYNOPSIS","text":"ltpcli local_node_nbr
"},{"location":"man/bpv6/ltpcli/#description","title":"DESCRIPTION","text":"ltpcli is a background \"daemon\" task that receives LTP data transmission blocks, extracts bundles from the received blocks, and passes them to the bundle protocol agent on the local ION node.
ltpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"ltp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. ltpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the LTP convergence layer protocol.
"},{"location":"man/bpv6/ltpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ltpcli.
\"1\"
ltpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart ltpcli.
No configuration files are needed.
"},{"location":"man/bpv6/ltpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ltpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such ltp duct.
No LTP induct matching local_node_nbr has been added to the BP database. Use bpadmin to stop the LTP convergence-layer protocol, add the induct, and then restart the LTP protocol.
CLI task is already started for this duct.
Redundant initiation of ltpcli.
ltpcli can't initialize LTP.
ltpadmin has not yet initialized LTP operations.
ltpcli can't open client access.
Another task has already opened the client service for BP over LTP.
ltpcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart LTP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ltpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), ltpadmin(1), ltprc(5), ltpclo(1)
"},{"location":"man/bpv6/ltpclo/","title":"NAME","text":"ltpclo - LTP-based BP convergence layer adapter output task
"},{"location":"man/bpv6/ltpclo/#synopsis","title":"SYNOPSIS","text":"ltpclo remote_node_nbr
"},{"location":"man/bpv6/ltpclo/#description","title":"DESCRIPTION","text":"ltpclo is a background \"daemon\" task that extracts bundles from the queues of segments ready for transmission via LTP to the remote bundle protocol agent identified by remote_node_nbr and passes them to the local LTP engine for aggregation, segmentation, and transmission to the remote node.
ltpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. ltpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the LTP convergence layer protocol.
"},{"location":"man/bpv6/ltpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSC protocol.
\"1\"
ltpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSC protocol.
No configuration files are needed.
"},{"location":"man/bpv6/ltpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/ltpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such ltp duct.
No LTP outduct with duct name matching remote_node_nbr has been added to the BP database. Use bpadmin to stop the LTP convergence-layer protocol, add the outduct, and then restart the LTP protocol.
CLO task is already started for this duct.
Redundant initiation of ltpclo.
ltpclo can't initialize LTP.
ltpadmin has not yet initialized LTP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/ltpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), ltpadmin(1), ltprc(5), ltpcli(1)
"},{"location":"man/bpv6/stcpcli/","title":"NAME","text":"sstcpcli - DTN simple TCP convergence layer input task
"},{"location":"man/bpv6/stcpcli/#synopsis","title":"SYNOPSIS","text":"stcpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/stcpcli/#description","title":"DESCRIPTION","text":"stcpcli is a background \"daemon\" task comprising 1 + N threads: one that handles TCP connections from remote stcpclo tasks, spawning sockets for data reception from those tasks, plus one input thread for each spawned socket to handle data reception over that socket.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 4556.
Each reception thread receives bundles over the associated connected socket. Each bundle received on the connection is preceded by a 32-bit unsigned integer in network byte order indicating the length of the bundle. The received bundles are passed to the bundle protocol agent on the local ION node.
stcpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"stcp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. stcpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the STCP convergence layer protocol.
"},{"location":"man/bpv6/stcpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
stcpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart stcpcli.
\"1\"
stcpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart stcpcli.
No configuration files are needed.
"},{"location":"man/bpv6/stcpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/stcpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
stcpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such stcp duct.
No STCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the STCP convergence-layer protocol, add the induct, and then restart the STCP protocol.
CLI task is already started for this duct.
Redundant initiation of stcpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart STCP.
Can't open TCP socket
Operating system error. Check errtext, correct problem, and restart STCP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart STCP.
stcpcli can't create access thread
Operating system error. Check errtext, correct problem, and restart STCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/stcpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), stcpclo(1)
"},{"location":"man/bpv6/stcpclo/","title":"NAME","text":"stcpclo - DTN simple TCP convergence layer adapter output task
"},{"location":"man/bpv6/stcpclo/#synopsis","title":"SYNOPSIS","text":"stcpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/stcpclo/#description","title":"DESCRIPTION","text":"stcpclo is a background \"daemon\" task that connects to a remote node's TCP socket at remote_hostname and remote_port_nbr. It then begins extracting bundles from the queues of bundles ready for transmission via TCP to this remote bundle protocol agent and transmitting those bundles over the connected socket to that node. Each transmitted bundle is preceded by a 32-bit integer in network byte order indicating the length of the bundle.
If not specified, remote_port_nbr defaults to 4556.
stcpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. stcpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the STCP convergence layer protocol.
"},{"location":"man/bpv6/stcpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
stcpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the STCP protocol.
\"1\"
stcpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the STCP protocol.
No configuration files are needed.
"},{"location":"man/bpv6/stcpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/stcpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
stcpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such stcp duct.
No STCP outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the STCP convergence-layer protocol, add the outduct, and then restart the STCP protocol.
CLO task is already started for this duct.
Redundant initiation of stcpclo.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart STCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/stcpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), stcpcli(1)
"},{"location":"man/bpv6/tcpcli/","title":"NAME","text":"tcpcli - DTN TCPCL-compliant convergence layer input task
"},{"location":"man/bpv6/tcpcli/#synopsis","title":"SYNOPSIS","text":"tcpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/tcpcli/#description","title":"DESCRIPTION","text":"tcpcli is a background \"daemon\" task comprising 3 + 2*N threads: an executive thread; a clock thread that periodically attempts to connect to remote TCPCL entities as identified by the tcp outducts enumerated in the bprc(5) file (each of which must specify the hostname[:port_nbr] to connect to); a thread that handles TCP connections from remote TCPCL entities, spawning sockets for data reception from those tasks; plus one input thread and one output thread for each connection, to handle data reception and transmission over that socket.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 4556.
Each time a connection is established, the entities will first exchange contact headers, because connection parameters need to be negotiated. tcpcli records the acknowledgement flags, reactive fragmentation flag, and negative acknowledgements flag in the contact header it receives from its peer TCPCL entity.
Each reception thread receives bundles over the associated connected socket. Each bundle received on the connection is preceded by message type, fragmentation flags, and size represented as an SDNV. The received bundles are passed to the bundle protocol agent on the local ION node.
Similarly, each transmission thread obtains outbound bundles from the local ION node, encapsulates them as noted above, and transmits them over the associated connected socket.
tcpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"tcp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. tcpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the TCP convergence layer protocol.
"},{"location":"man/bpv6/tcpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart tcpcli.
\"1\"
tcpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart tcpcli.
No configuration files are needed.
"},{"location":"man/bpv6/tcpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/tcpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such tcp duct.
No TCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the TCP convergence-layer protocol, add the induct, and then restart the TCP protocol.
CLI task is already started for this duct.
Redundant initiation of tcpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart TCP.
Can't open TCP socket
Operating system error. Check errtext, correct problem, and restart TCP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart TCP.
tcpcli can't create access thread
Operating system error. Check errtext, correct problem, and restart TCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/tcpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv6/tcpclo/","title":"NAME","text":"tcpclo - DTN TCPCL-compliant convergence layer adapter output task
"},{"location":"man/bpv6/tcpclo/#synopsis","title":"SYNOPSIS","text":"tcpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/tcpclo/#description","title":"DESCRIPTION","text":"tcpclo is a background \"daemon\" task that connects to a remote node's TCP socket at remote_hostname and remote_port_nbr. It sends a contact header, and it records the acknowledgement flag, reactive fragmentation flag and negative acknowledgements flag in the contact header it receives from its peer tcpcli task. It then begins extracting bundles from the queues of bundles ready for transmission via TCP to this remote bundle protocol agent and transmitting those bundles over the connected socket to that node. Each transmitted bundle is preceded by message type, segmentation flags, and an SDNV indicating the size of the bundle (in bytes).
If not specified, remote_port_nbr defaults to 4556.
tcpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. tcpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the TCP convergence layer protocol.
"},{"location":"man/bpv6/tcpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the TCPCL protocol.
\"1\"
tcpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the TCPCL protocol.
No configuration files are needed.
"},{"location":"man/bpv6/tcpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/tcpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such tcp duct.
No TCP outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the TCP convergence-layer protocol, add the outduct, and then restart the TCP protocol.
CLO task is already started for this duct.
Redundant initiation of tcpclo.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart TCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/tcpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), tcpcli(1)
"},{"location":"man/bpv6/udpcli/","title":"NAME","text":"udpcli - UDP-based BP convergence layer input task
"},{"location":"man/bpv6/udpcli/#synopsis","title":"SYNOPSIS","text":"udpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv6/udpcli/#description","title":"DESCRIPTION","text":"udpcli is a background \"daemon\" task that receives UDP datagrams via a UDP socket bound to local_hostname and local_port_nbr, extracts bundles from those datagrams, and passes them to the bundle protocol agent on the local ION node.
If not specified, port number defaults to 4556.
The convergence layer input task is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"udp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. udpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the UDP convergence layer protocol.
"},{"location":"man/bpv6/udpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart udpcli.
\"1\"
udpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart udpcli.
No configuration files are needed.
"},{"location":"man/bpv6/udpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/udpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such udp duct.
No UDP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the UDP convergence-layer protocol, add the induct, and then restart the UDP protocol.
CLI task is already started for this duct.
Redundant initiation of udpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart UDP.
Can't open UDP socket
Operating system error. Check errtext, correct problem, and restart UDP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart UDP.
udpcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart UDP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/udpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), udpclo(1)
"},{"location":"man/bpv6/udpclo/","title":"NAME","text":"udpclo - UDP-based BP convergence layer output task
"},{"location":"man/bpv6/udpclo/#synopsis","title":"SYNOPSIS","text":"udpclo round_trip_time remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv6/udpclo/#description","title":"DESCRIPTION","text":"udpclo is a background \"daemon\" task that extracts bundles from the queues of bundles ready for transmission via UDP to a remote node's UDP socket at remote_hostname and remote_port_nbr, encapsulates those bundles in UDP datagrams, and sends those datagrams to that remote UDP socket.
Because UDP is not itself a \"reliable\" transmission protocol (i.e., it performs no retransmission of lost data), it may be used in conjunction with BP custodial retransmission. BP custodial retransmission is triggered only by expiration of a timer whose interval is nominally the round-trip time between the sending BP node and the next node in the bundle's end-to-end path that is expected to take custody of the bundle; notionally, if no custody signal citing the transmitted bundle has been received before the end of this interval it can be assumed that either the bundle or the custody signal was lost in transmission and therefore the bundle should be retransmitted. The value of the custodial retransmission timer interval (the expected round-trip time between the sending node and the anticipated next custodian) must be provided as a run-time argument to udpclo. If the value of this parameter is zero, custodial retransmission is disabled.
udpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. udpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the UDP convergence layer protocol.
"},{"location":"man/bpv6/udpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart udpclo.
\"1\"
udpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart udpclo.
No configuration files are needed.
"},{"location":"man/bpv6/udpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv6/udpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No memory for UDP buffer in udpclo.
ION system error. Check errtext, correct problem, and restart UDP.
No such udp duct.
No UDP outduct with duct name remote_hostname[:<remote_port_nbr>] has been added to the BP database. Use bpadmin to stop the UDP convergence-layer protocol, add the outduct, and then restart the UDP protocol.
CLO task is already started for this engine.
Redundant initiation of udpclo.
CLO can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udpclo.
CLO write() error on socket
Operating system error. Check errtext, correct problem, and restart udpclo.
Bundle is too big for UDP CLA.
Configuration error: bundles that are too large for UDP transmission (i.e., larger than 65535 bytes) are being enqueued for udpclo. Change routing.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv6/udpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), udpcli(1)
"},{"location":"man/bpv7/","title":"Index of Man Pages","text":"bibeadmin - bundle-in-bundle encapsulation database administration interface
"},{"location":"man/bpv7/bibeadmin/#synopsis","title":"SYNOPSIS","text":"bibeadmin [ commands_filename ]
"},{"location":"man/bpv7/bibeadmin/#description","title":"DESCRIPTION","text":"bibeadmin configures the local ION node's database of parameters governing the forwarding of BIBE PDUs to specified remote nodes.
bibeadmin operates in response to BIBE configuration commands found in the file commands_filename, if provided; if not, bibeadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from bibeadmin with the 'h' or '?' commands at the prompt. The commands are documented in biberc(5).
"},{"location":"man/bpv7/bibeadmin/#exit-status","title":"EXIT STATUS","text":"bibeadmin
Enter interactive BIBE configuration command entry mode.
bibeadmin host1.biberc
Execute all configuration commands in host1.biberc, then terminate immediately.
See biberc(5) for details of the BIBE configuration commands.
"},{"location":"man/bpv7/bibeadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bibeadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the biberc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bibeadmin. Otherwise bibeadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
bibeadmin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
bibeadmin can't initialize routing database.
There is no SDR data store for bibeadmin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bibeadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see biberc(5) for details.
"},{"location":"man/bpv7/bibeadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bibeadmin/#see-also","title":"SEE ALSO","text":"bibeclo(1), biberc(5)
"},{"location":"man/bpv7/bibeclo/","title":"NAME","text":"bibeclo - BP convergence layer output task using bundle-in-bundle encapsulation
"},{"location":"man/bpv7/bibeclo/#synopsis","title":"SYNOPSIS","text":"bibeclo peer_EID destination_EID
"},{"location":"man/bpv7/bibeclo/#description","title":"DESCRIPTION","text":"bibeclo is a background \"daemon\" task that extracts bundles from the queues of bundles destined for destination_EID that are ready for transmission via bundle-in-bundle encapsulation (BIBE) to peer_EID, encapsulates them in BP administrative records of (non-standard) record type 7 (BP_BIBE_PDU), and sends those administrative records in encapsulating bundles destined for peer_EID. The forwarding of encapsulated bundles for which custodial acknowledgment is requested causes bibeclo to post custodial re-forwarding timers to the node's timeline. Parameters governing the forwarding of BIBE PDUs to peer_EID are stipulated in the corresponding BIBE convergence-layer adapter (bcla) structure residing in the BIBE database, as managed by bibeadmin.
The receiving node is expected to process received BIBE PDUs by simply dispatching the encapsulated bundles - whose destination is the node identified by destination_EID - as if they had been received from neighboring nodes in the normal course of operations; BIBE PDUs for which custodial acknowledgment was requested cause the received bundles to be noted in custody signals that are being aggregated by the receiving node.
bibeclo additionally sends aggregated custody signals in BP administrative records of (non-standard) record type 8 (BP_BIBE_SIGNAL) as the deadlines for custody signal transmission arrive.
Note that the reception and processing of both encapsulated bundles and custody signals is performed by the scheme-specific administration endpoint daemon(s) at the receiving nodes. Reception of a custody signal terminates the custodial re-forwarding timers for all bundles acknowledged in that signal; the re-forwarding of bundles upon custodial re-forwarding timer expiration is initiated by the bpclock daemon.
bibeclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. bibeclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BIBE convergence layer protocol.
"},{"location":"man/bpv7/bibeclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
bibeclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bibeclo.
\"1\"
bibeclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart bibeclo.
No configuration files are needed.
"},{"location":"man/bpv7/bibeclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bibeclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bibeclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such bibe outduct.
No BIBE outduct with duct name destination_EID exists. Use bpadmin to stop the BIBE convergence-layer protocol, add the outduct, and then restart the BIBE protocol.
No such bcla.
No bcla structure for the node identified by peer_EID has been added to the BP database. Use bpadmin to stop the BIBE convergence-layer protocol, use bibeadmin to add the bcla, and then use bpadmin to restart the BIBE protocol.
CLO task is already started for this duct.
Redundant initiation of bibeclo.
Can't dequeue bundle.
BIBE outduct closed deleted or other system error. Check ION log; correct the problem and restart BIBE.
[i] bibeclo outduct closed.
Nominal shutdown message.
Can't prepend header; CLO stopping.
System error. Check ION log; correct the problem and restart BIBE.
Can't destroy old ZCO; CLO stopping.
System error. Check ION log; correct the problem and restart BIBE.
Can't get outbound space for BPDU.
System error. Check ION log; correct the problem and restart BIBE.
Can't send encapsulated bundle.
System error. Check ION log; correct the problem and restart BIBE.
Can't track bundle.
System error. Check ION log; correct the problem and restart BIBE.
[!] Encapsulated bundle not sent.
Malformed bundle issuance request, which might be a software error. Contact technical support.
Can't release ZCO; CLO stopping.
System error. Check ION log; correct the problem and restart BIBE.
[i] bibeclo duct has ended.
Nominal shutdown message.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bibeclo/#see-also","title":"SEE ALSO","text":"biberc(5), bibeadmin(1)
"},{"location":"man/bpv7/biberc/","title":"NAME","text":"biberc - BIBE configuration commands file
"},{"location":"man/bpv7/biberc/#description","title":"DESCRIPTION","text":"BIBE configuration commands are passed to bibeadmin either in a file of text lines or interactively at bibeadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
BIBE configuration commands establish the parameters governing transmission of BIBE PDUs to specified peer nodes: anticipated delivery latency in the forward direction, anticipated delivery latency in the return direction, TTL for BIBE PDUs, priority for BIBE PDUs, ordinal priority for BIBE PDUs in the event that priority is Expedited, and (optionally) data label for BIBE PDUs. As such, they configure BIBE convergence-layer adapter (bcla) structures.
The formats and effects of the BIBE configuration commands are described below.
NOTE: in order to cause bundles to be transmitted via BIBE:
Plan
Remember that BIBE is a convergence-layer protocol; as such, it operates between two nodes that are topologically adjacent in a BP network (but in this case the BP network within which the nodes are topologically adjacent is an overlay on top of the real BP network). Since the sending and receiving nodes are topologically adjacent they are neighbors: the sending node MUST have an egress plan for transmission to the receiving (that is, peer) node, and there MUST be a BIBE outduct attached to that plan.
Routing
In order to compel bundles bound for some destination node to be forwarded via the BIBE peer node rather than over some other route computed by CGR, you have to override CGR routing for that bundle. The way to do this is to (a) tag the bundle with data label X (in ancillary data) and (b) use ipnadmin to establish at the sending node a routing override that coerces all bundles with data label X to be sent directly to the peer node.
If the peer node happens to be a true BP neighbor as well - that is, there is also a non-BIBE outduct attached to the egress plan for transmission to that node - then you additionally need to tell the egress plan management daemon (bpclm) for that node which bundles need to be forwarded using the BIBE outduct rather than the non-BIBE outduct. The way to do this is to use ipnadmin to establish at the sending node a class-of-service override that locally and temporarily OR's the BP_BIBE_REQUESTED flag (32) to the quality-of-service flags of any bundle tagged with data label X.
Quality of Service
If you want custody transfer to be invoked for each BIBE transmission of a bundle from the sending node to the peer node, you must additionally use ipnadmin to establish at the sending node a class-of-service override that locally and temporarily OR's the BP_CT_REQUESTED flag (64) to the quality-of-service flags of any bundle tagged with data label X.
If you need to establish a class-of-service override to set the BP_BIBE_REQUESTED flag (as described above) as well, then use the OR of BP_BIBE_REQUESTED and BP_CT_REQUESTED - that is, 96 - as the quality-of-service flags argument for that override.
NOTE that an alternative method of setting both the BP_BIBE_REQUESTED and BP_CT_REQUESTED flags for a given bundle is simply to request custody transfer when the bundle is sourced; this will OR that bundle's own quality-of-service flags (in ancillary data) with 96. But be careful: in this case the bundle will be permanently tagged with these flag values, meaning that it will be forwarded via BIBE with custody transfer over every \"hop\" of the end-to-end path to its destination, and if BIBE is unavailable at any forwarding node on the path then the bundle can never reach the destination node.
?
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 bibeadmin to be logged as well as sent to stdout. Setting echo to 0 disables this behavior.
w { 0 | 1 | activity_spec }
The watch command. This command enables and disables production of a continuous stream of user-selected Bundle-in-Bundle Encapsulation custody transfer activity indication characters. A watch parameter of \"1\" selects all BIBE-CT activity indication characters; \"0\" de-selects all BIBE-CT activity indication characters; any other activity_spec such as \"mw\" selects all activity indicators in the string, de-selecting all others. BIBE will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
w custody of bundle is accepted
m custody acceptance is received for one bundle
x custody of bundle is refused
& custody refusal is received for one bundle
$ bundle retransmitted due to expired custodial retransmission interval
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a bcla peer_EID fwd_latency rtn_latency time_to_live priority ordinal [data label]
The add bcla command. This command adds the neighboring node identified by peer_EID as a BIBE destination of the local node.
c bcla peer_EID fwd_latency rtn_latency time_to_live priority ordinal [data label]
The change bcla command. This command changes the transmission parameters governing BIBE PDU transmission to the indicated peer node.
d bcla peer_EID
The delete bcla command. This command deletes the bcla identified by peer_EID.
i bcla peer_EID
This command will print information (the transmission parameters) for the BIBE peer node identified by peer_EID.
l
This command lists all of the local node's BIBE peers.
a bcla ipn:3.2 10 10 60 1 0 16
Declares that ipn:3.2 is a BIBE destination and that BIBE PDUs destined for this node are to be sent with TTL 60 seconds, priority 1 (standard), and data label 16; it is expected that BIBE PDUs sent to this node will arrive within 10 seconds and that BIBE PDUs sent from this node will arrive within 10 seconds.
bibeadmin(1), bibeclo(1)
"},{"location":"man/bpv7/bp/","title":"NAME","text":"bp - Bundle Protocol communications library
"},{"location":"man/bpv7/bp/#synopsis","title":"SYNOPSIS","text":"#include \"bp.h\"\n\n[see description for available functions]\nThe bp library provides functions enabling application software to use Bundle Protocol to send and receive information over a delay-tolerant network. It conforms to the Bundle Protocol specification as documented in Internet RFC 5050.
int bp_attach( )
Attaches the application to BP functionality on the local computer. Returns 0 on success, -1 on any error.
Note that all ION libraries and applications draw memory dynamically, as needed, from a shared pool of ION working memory. The size of the pool is established when ION node functionality is initialized by ionadmin(1). This is a precondition for initializing BP functionality by running bpadmin(1), which in turn is required in order for bp_attach() to succeed.
Sdr bp_get_sdr( )
Returns handle for the SDR data store used for BP, to enable creation and interrogation of bundle payloads (application data units).
void bp_detach( )
Terminates all access to BP functionality on the local computer.
int bp_open(char *eid, BpSAP *ionsapPtr)
Opens the application's access to the BP endpoint identified by eid, so that the application can take delivery of bundles destined for the indicated endpoint. This SAP can also be used for sending bundles whose source is the indicated endpoint; all bundles sent via this SAP will be subject to immediate destruction upon transmission, i.e., no bundle addresses will be returned by bp_send() for use in tracking, suspending/resuming, or cancelling transmission of these bundles. On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
int bp_open_source(char *eid, BpSAP *ionsapPtr, detain)
Opens the application's access to the BP endpoint identified by eid, so that the application can send bundles whose source is the indicated endpoint. If and only if the value of detain is non-zero, citing this SAP in an invocation of bp_send() will cause the address of the newly issued bundle to be returned for use in tracking, suspending/resuming, or cancelling transmission of this bundle. USE THIS FEATURE WITH GREAT CARE: such a bundle will continue to occupy storage resources until it is explicitly released by an invocation of bp_release() or until its time to live expires, so bundle detention increases the risk of resource exhaustion. (If the value of detain is zero, all bundles sent via this SAP will be subject to immediate destruction upon transmission.) On success, places a value in *ionsapPtr that can be supplied to future bp function invocations and returns 0. Returns -1 on any error.
int bp_send(BpSAP sap, char *destEid, char *reportToEid, int lifespan, int classOfService, BpCustodySwitch custodySwitch, unsigned char srrFlags, int ackRequested, BpAncillaryData *ancillaryData, Object adu, Object *newBundle)
Sends a bundle to the endpoint identified by destEid, from the source endpoint as provided to the bp_open() call that returned sap. When sap is NULL, the transmitted bundle is anonymous, i.e., the source of the bundle is not identified. This is legal, but anonymous bundles cannot be uniquely identified; status reporting therefore cannot be requested for an anonymous bundle.
reportToEid identifies the endpoint to which any status reports pertaining to this bundle will be sent; if NULL, defaults to the source endpoint.
lifespan is the maximum number of seconds that the bundle can remain in-transit (undelivered) in the network prior to automatic deletion.
classOfService is simply priority for now: BP_BULK_PRIORITY, BP_STD_PRIORITY, or BP_EXPEDITED_PRIORITY. If class-of-service flags are defined in a future version of Bundle Protocol, those flags would be OR'd with priority.
custodySwitch indicates whether or not custody transfer is requested for this bundle and, if so, whether or not the source node itself is required to be the initial custodian. The valid values are SourceCustodyRequired, SourceCustodyOptional, NoCustodyRequired. Note that custody transfer can take effect only for segments of the end-to-end path that are traversed using the Bundle-in-Bundle Encapsulation protocol at the \"convergence layer\"; however, requesting custody transfer is interpreted by ION as a request to use \"reliable\" convergence-layer protocols over all segments of the end-to-end path, whether implemented by custody transfer or not.
srrFlags, if non-zero, is the logical OR of the status reporting behaviors requested for this bundle: BP_RECEIVED_RPT, BP_FORWARDED_RPT, BP_DELIVERED_RPT, BP_DELETED_RPT.
ackRequested is a Boolean parameter indicating whether or not the recipient application should be notified that the source application requests some sort of application-specific end-to-end acknowledgment upon receipt of the bundle.
ancillaryData, if not NULL, is used to populate the Extended Class Of Service block for this bundle. The block's ordinal value is used to provide fine-grained ordering within \"expedited\" traffic: ordinal values from 0 (the default) to 254 (used to designate the most urgent traffic) are valid, with 255 reserved for custody signals. Note that the insertion of application-specific extension blocks into the bundle, in addition to the canonical extension blocks inserted automatically per the bpextensions.c file, may be requested by listing those blocks in the extensions variable of the ancillaryData block. The value of the block's flags is the logical OR of the applicable extended class-of-service flags:
BP\\_MINIMUM\\_LATENCY designates the bundle as \"critical\" for the\npurposes of Contact Graph Routing.\n\nBP\\_BEST\\_EFFORT signifies that non-reliable convergence-layer protocols, as\navailable, may be used to transmit the bundle. Notably, the bundle may be\nsent as \"green\" data rather than \"red\" data when issued via LTP.\n\nBP\\_DATA\\_LABEL\\_PRESENT signifies whether or not the value of _dataLabel_\nin _ancillaryData_ must be encoded into the ECOS block when the bundle is\ntransmitted.\nadu is the \"application data unit\" that will be conveyed as the payload of the new bundle. adu must be a \"zero-copy object\" (ZCO). To ensure orderly access to transmission buffer space for all applications, adu must be created by invoking ionCreateZco(), which may be configured either to block so long as insufficient ZCO storage space is available for creation of the requested ZCO or to fail immediately if insufficient ZCO storage space is available.
The function returns 1 on success, 0 on user error, -1 on any system error. If 0 is returned, then an invalid argument value was passed to bp_send(); a message to this effect will have been written to the log file. If 1 is returned, then either the destination of the bundle was \"dtn:none\" (the bit bucket) or the ADU has been accepted and queued for transmission in a bundle. In the latter case, if and only if sap was a reference to a BpSAP returned by an invocation of bp_open_source() that had a non-zero value in the detain parameter, then newBundle must be non-NULL and the address of the newly created bundle within the ION database is placed in newBundle. This address can be used to track, suspend/resume, or cancel transmission of the bundle.
int bp_track(Object bundle, Object trackingElt)
Adds trackingElt to the list of \"tracking\" references in bundle. trackingElt must be the address of an SDR list element -- whose data is the address of this same bundle -- within some list of bundles that is privately managed by the application. Upon destruction of the bundle this list element will automatically be deleted, thus removing the bundle from the application's privately managed list of bundles. This enables the application to keep track of bundles that it is operating on without risk of inadvertently de-referencing the address of a nonexistent bundle.
void bp_untrack(Object bundle, Object trackingElt)
Removes trackingElt from the list of \"tracking\" references in bundle, if it is in that list. Does not delete trackingElt itself.
int bp_suspend(Object bundle)
Suspends transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or if the bundle is already suspended. Otherwise, reverses the enqueuing of the bundle to its selected transmission outduct and places it in the \"limbo\" queue until the suspension is lifted by calling bp_resume. Returns 0 on success, -1 on any error.
int bp_resume(Object bundle)
Terminates suspension of transmission of bundle. Has no effect if bundle is \"critical\" (i.e., has got extended class of service BP_MINIMUM_LATENCY flag set) or is not suspended. Otherwise, removes the bundle from the \"limbo\" queue and queues it for route re-computation and re-queuing. Returns 0 on success, -1 on any error.
int bp_cancel(Object bundle)
Cancels transmission of bundle. If the indicated bundle is currently queued for forwarding, transmission, or retransmission, it is removed from the relevant queue and destroyed exactly as if its Time To Live had expired. Returns 0 on success, -1 on any error.
int bp_release(Object bundle)
Releases a detained bundle for destruction when all retention constraints have been removed. After a detained bundle has been released, the application can no longer track, suspend/resume, or cancel its transmission. Returns 0 on success, -1 on any error.
int bp_receive(BpSAP sap, BpDelivery *dlvBuffer, int timeoutSeconds)
Receives a bundle, or reports on some failure of bundle reception activity.
The \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one bundle destined for the endpoint for which this SAP is opened has not yet been delivered to the SAP, then the payload of the oldest such bundle will be returned in dlvBuffer->adu and dlvBuffer->result will be set to BpPayloadPresent. If there is no such bundle, bp_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is BP_POLL (i.e., zero) and no bundle is awaiting delivery, or if timeoutSeconds is greater than zero but no bundle arrives before timeoutSeconds have elapsed, then dlvBuffer->result will be set to BpReceptionTimedOut. If timeoutSeconds is BP_BLOCKING (i.e., -1) then bp_receive() blocks until either a bundle arrives or the function is interrupted by an invocation of bp_interrupt().
dlvBuffer->result will be set to BpReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer->result will be set to BpEndpointStopped in the event that the operation of the indicated endpoint has been terminated.
The application data unit delivered in the data delivery structure, if any, will be a \"zero-copy object\" reference. Use zco reception functions (see zco(3)) to read the content of the application data unit.
Be sure to call bp_release_delivery() after every successful invocation of bp_receive().
The function returns 0 on success, -1 on any error.
void bp_interrupt(BpSAP sap)
Interrupts a bp_receive() invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, sap may need to be obtained from a static variable.
void bp_release_delivery(BpDelivery *dlvBuffer, int releaseAdu)
Releases resources allocated to the indicated delivery. releaseAdu is a Boolean parameter: if non-zero, the ADU ZCO reference in dlvBuffer (if any) is destroyed, causing the ZCO itself to be destroyed if no other references to it remain.
void bp_close(BpSAP sap)
Terminates the application's access to the BP endpoint identified by the eid cited by the indicated service access point. The application relinquishes its ability to take delivery of bundles destined for the indicated endpoint and to send bundles whose source is the indicated endpoint.
bpadmin(1), lgsend(1), lgagent(1), bpextensions(3), bprc(5), lgfile(5)
"},{"location":"man/bpv7/bpadmin/","title":"NAME","text":"bpadmin - ION Bundle Protocol (BP) administration interface
"},{"location":"man/bpv7/bpadmin/#synopsis","title":"SYNOPSIS","text":"bpadmin [ commands_filename | . | ! ]
"},{"location":"man/bpv7/bpadmin/#description","title":"DESCRIPTION","text":"bpadmin configures, starts, manages, and stops bundle protocol operations for the local ION node.
It operates in response to BP configuration commands found in the file commands_filename, if provided; if not, bpadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to bpadmin -- that is, the ION node's bpclock task, forwarder tasks, and convergence layer adapter tasks are stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's bpclock task, forwarder tasks, and convergence layer adapter tasks are restarted.
The format of commands for commands_filename can be queried from bpadmin with the 'h' or '?' commands at the prompt. The commands are documented in bprc(5).
"},{"location":"man/bpv7/bpadmin/#exit-status","title":"EXIT STATUS","text":"bpadmin
Enter interactive BP configuration command entry mode.
bpadmin host1.bp
Execute all configuration commands in host1.bp, then terminate immediately.
bpadmin .
Stop all bundle protocol operations on the local node.
See bprc(5) for details of the BP configuration commands.
"},{"location":"man/bpv7/bpadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the bprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bpadmin. Otherwise bpadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ION can't set custodian EID information.
The custodial_endpoint_id specified in the BP initialization ('1') command is malformed. Remember that the format for this argument is ipn:element_number.0 and that the final 0 is required, as custodial/administration service is always service 0. Additional detail for this error is provided if one of the following other errors is present:
Malformed EID.\n\nMalformed custodian EID.\nbpadmin can't attach to ION.
There is no SDR data store for bpadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bpadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see bprc(5) for details.
"},{"location":"man/bpv7/bpadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpadmin/#see-also","title":"SEE ALSO","text":"ionadmin(1), bprc(5), ipnadmin(1), ipnrc(5), dtnadmin(1), dtnrc(5)
"},{"location":"man/bpv7/bpcancel/","title":"NAME","text":"bpcancel - Bundle Protocol (BP) bundle cancellation utility
"},{"location":"man/bpv7/bpcancel/#synopsis","title":"SYNOPSIS","text":"bpcancel source_EID creation_seconds [creation_count [fragment_offset [fragment_length]]]
"},{"location":"man/bpv7/bpcancel/#description","title":"DESCRIPTION","text":"bpcancel attempts to locate the bundle identified by the command-line parameter values and cancel transmission of this bundle. Bundles for which multiple copies have been queued for transmission can't be canceled, because one or more of those copies might already have been transmitted. Transmission of a bundle that has never been cloned and that is still in local bundle storage is cancelled by simulation of an immediate time-to-live expiration.
"},{"location":"man/bpv7/bpcancel/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcancel has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bpcancel/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpcancel/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
bpcancel failed finding bundle.
The attempt to locate the subject bundle failed due to some serious system error. It will probably be necessary to terminate and re-initialize the local ION node.
bpcancel failed destroying bundle.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpcancel failed.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpcancel/#see-also","title":"SEE ALSO","text":"bplist(1)
"},{"location":"man/bpv7/bpchat/","title":"NAME","text":"bpchat - Bundle Protocol chat test program
"},{"location":"man/bpv7/bpchat/#synopsis","title":"SYNOPSIS","text":"bpchat sourceEID destEID [ct]
"},{"location":"man/bpv7/bpchat/#description","title":"DESCRIPTION","text":"bpchat uses Bundle Protocol to send input text in bundles, and display the payload of received bundles as output. It is similar to the talk utility, but operates over the Bundle Protocol. It operates like a combination of the bpsource and bpsink utilities in one program (unlike bpsource, bpchat emits bundles with a sourceEID).
If the sourceEID and destEID are both bpchat applications, then two users can chat with each other over the Bundle Protocol: lines that one user types on the keyboard will be transported over the network in bundles and displayed on the screen of the other user (and the reverse).
bpchat terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv7/bpchat/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpchat has terminated normally. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpchat has terminated due to a BP transmit or reception failure. Details should be noted in the ion.log log file.
If the string \"ct\" is appended as the last argument, then bundles will be sent with custody transfer requested.
No configuration files are needed.
"},{"location":"man/bpv7/bpchat/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpchat/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpchat are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpchat bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpchat can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpchat/#see-also","title":"SEE ALSO","text":"bpecho(1), bpsource(1), bpsink(1), bp(3)
"},{"location":"man/bpv7/bpclm/","title":"NAME","text":"bpclm - DTN bundle protocol convergence layer management daemon
"},{"location":"man/bpv7/bpclm/#synopsis","title":"SYNOPSIS","text":"bpclm neighboring_node_ID
"},{"location":"man/bpv7/bpclm/#description","title":"DESCRIPTION","text":"bpclm is a background \"daemon\" task that manages the transmission of bundles to a single designated neighboring node (as constrained by an \"egress plan\" data structure for that node) by one or more convergence-layer (CL) adapter output daemons (via buffer structures called \"outducts\").
bpclm is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. bpclm can also be spawned and terminated in response to commands that START and STOP the corresponding node's egress plan.
"},{"location":"man/bpv7/bpclm/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpclm terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the egress plan for this node.
\"1\"
bpclm terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the egress plan for this node.
No configuration files are needed.
"},{"location":"man/bpv7/bpclm/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpclm/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpclm can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No egress plan for this node
No egress plan for the node identified by neighboring_node_ID has been added to the BP database. Use bpadmin to add and start the plan.
bpclm task is already started for this node
Redundant initiation of bpclm.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpclm/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/bpclock/","title":"NAME","text":"bpclock - Bundle Protocol (BP) daemon task for managing scheduled events
"},{"location":"man/bpv7/bpclock/#synopsis","title":"SYNOPSIS","text":"bpclock
"},{"location":"man/bpv7/bpclock/#description","title":"DESCRIPTION","text":"bpclock is a background \"daemon\" task that periodically performs scheduled Bundle Protocol activities. It is spawned automatically by bpadmin in response to the 's' command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command.
Once per second, bpclock takes the following action:
First it (a) destroys all bundles whose TTLs have expired, (b) enqueues for re-forwarding all bundles that were expected to have been transmitted (by convergence-layer output tasks) by now but are still stuck in their assigned transmission queues, and (c) enqueues for re-forwarding all bundles for which custody has not yet been taken that were expected to have been received and acknowledged by now (as noted by invocation of the bpMemo() function by some convergence-layer adapter that had CL-specific insight into the appropriate interval to wait for custody acceptance).
Then bpclock adjusts the transmission and reception \"throttles\" that control rates of LTP transmission to and reception from neighboring nodes, in response to data rate changes as noted in the RFX database by rfxclock.
bpclock then checks for bundle origination activity that has been blocked due to insufficient allocated space for BP traffic in the ION data store: if space for bundle origination is now available, bpclock gives the bundle production throttle semaphore to unblock that activity.
Finally, bpclock applies rate control to all convergence-layer protocol inducts and outducts:
For each induct, bpclock increases the current capacity of the duct by the applicable nominal data reception rate. If the revised current capacity is greater than zero, bpclock gives the throttle's semaphore to unblock data acquisition (which correspondingly reduces the current capacity of the duct) by the associated convergence layer input task.
For each outduct, bpclock increases the current capacity of the duct by the applicable nominal data transmission rate. If the revised current capacity is greater than zero, bpclock gives the throttle's semaphore to unblock data transmission (which correspondingly reduces the current capacity of the duct) by the associated convergence layer output task.
"},{"location":"man/bpv7/bpclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bpclock.
\"1\"
bpclock was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/bpclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpclock can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't dispatch events.
An unrecoverable database error was encountered. bpclock terminates.
Can't adjust throttles.
An unrecoverable database error was encountered. bpclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpclock/#see-also","title":"SEE ALSO","text":"bpadmin(1), rfxclock(1)
"},{"location":"man/bpv7/bpcounter/","title":"NAME","text":"bpcounter - Bundle Protocol reception test program
"},{"location":"man/bpv7/bpcounter/#synopsis","title":"SYNOPSIS","text":"bpcounter ownEndpointId [maxCount]
"},{"location":"man/bpv7/bpcounter/#description","title":"DESCRIPTION","text":"bpcounter uses Bundle Protocol to receive application data units from a remote bpdriver application task. When the total number of application data units it has received exceeds maxCount, it terminates and prints its reception count. If maxCount is omitted, the default limit is 2 billion application data units.
"},{"location":"man/bpv7/bpcounter/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcounter has terminated. Any problems encountered during operation will be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv7/bpcounter/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpcounter/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpcounter are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpcounter bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpcounter/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpdriver(1), bpecho(1), bp(3)
"},{"location":"man/bpv7/bpdriver/","title":"NAME","text":"bpdriver - Bundle Protocol transmission test program
"},{"location":"man/bpv7/bpdriver/#synopsis","title":"SYNOPSIS","text":"bpdriver nbrOfCycles ownEndpointId destinationEndpointId [length] [t_TTL_] [i_Injection Rate_]
"},{"location":"man/bpv7/bpdriver/#description","title":"DESCRIPTION","text":"bpdriver uses Bundle Protocol to send nbrOfCycles application data units of length indicated by length, to a counterpart application task that has opened the BP endpoint identified by destinationEndpointId.
If omitted, length defaults to 60000.
TTL indicates the number of seconds the bundles may remain in the network, undelivered, before they are automatically destroyed. If omitted, TTL defaults to 300 seconds.
bpdriver normally runs in \"echo\" mode: after sending each bundle it waits for an acknowledgment bundle before sending the next one. For this purpose, the counterpart application task should be bpecho.
Alternatively bpdriver can run in \"streaming\" mode, i.e., without expecting or receiving acknowledgments. Streaming mode is enabled when length is specified as a negative number, in which case the additive inverse of length is used as the effective value of length. For this purpose, the counterpart application task should be bpcounter.
If the effective value of length is 1, the sizes of the transmitted service data units will be randomly selected multiples of 1024 in the range 1024 to 62464.
Injection Rate specifies in bits-per-second the equivalent, average rate at which bpdriver will send bundles into the network. A negative or 0 rate value will turn off injection rate control. By default, bpdriver will inject bundle as fast as it can be handled by ION unless a positive value for injection rate is provided.
bpdriver normally runs with custody transfer disabled. To request custody transfer for all bundles sent by bpdriver, specify nbrOfCycles as a negative number; the additive inverse of nbrOfCycles will be used as its effective value in this case.
When all copies of the file have been sent, bpdriver prints a performance report.
"},{"location":"man/bpv7/bpdriver/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpdriver has terminated. Any problems encountered during operation will be noted in the ion.log log file.
The service data units transmitted by bpdriver are sequences of text obtained from a file in the current working directory named \"bpdriverAduFile\", which bpdriver creates automatically.
"},{"location":"man/bpv7/bpdriver/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpdriver/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpdriver are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
Can't create ADU file
Operating system error. Check errtext, correct problem, and rerun.
Error writing to ADU file
Operating system error. Check errtext, correct problem, and rerun.
bpdriver can't create file ref.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpdriver can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpdriver can't send message
Bundle Protocol service to the remote endpoint has been stopped.
bpdriver reception failed
bpdriver is in \"echo\" mode, and Bundle Protocol delivery service has been stopped.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpdriver/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpcounter(1), bpecho(1), bp(3)
"},{"location":"man/bpv7/bpecho/","title":"NAME","text":"bpecho - Bundle Protocol reception test program
"},{"location":"man/bpv7/bpecho/#synopsis","title":"SYNOPSIS","text":"bpecho ownEndpointId
"},{"location":"man/bpv7/bpecho/#description","title":"DESCRIPTION","text":"bpecho uses Bundle Protocol to receive application data units from a remote bpdriver application task. In response to each received application data unit it sends back an \"echo\" application data unit of length 2, the NULL-terminated string \"x\".
bpecho terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv7/bpecho/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpecho has terminated normally. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpecho has terminated due to a BP reception failure. Details should be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv7/bpecho/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpecho/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpecho are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpecho bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpecho can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpecho/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpdriver(1), bpcounter(1), bp(3)
"},{"location":"man/bpv7/bpextensions/","title":"NAME","text":"bpextensions - interface for adding extensions to Bundle Protocol
"},{"location":"man/bpv7/bpextensions/#synopsis","title":"SYNOPSIS","text":"#include \"bpextensions.c\"\nION's interface for extending the Bundle Protocol enables the definition of external functions that insert extension blocks into outbound bundles (either before or after the payload block), parse and record extension blocks in inbound bundles, and modify extension blocks at key points in bundle processing. All extension-block handling is statically linked into ION at build time, but the addition of an extension never requires that any standard ION source code be modified.
Standard structures for recording extension blocks -- both in transient storage [memory] during bundle acquisition (AcqExtBlock) and in persistent storage [the ION database] during subsequent bundle processing (ExtensionBlock) -- are defined in the bei.h header file. In each case, the extension block structure comprises a block type code, block processing flags, possibly a list of EID references, an array of bytes (the serialized form of the block, for transmission), the length of that array, optionally an extension-specific opaque object whose structure is designed to characterize the block in a manner that's convenient for the extension processing functions, and the size of that object.
The definition of each extension is asserted in an ExtensionDef structure, also as defined in the bei.h header file. Each ExtensionDef must supply:
The name of the extension. (Used in some diagnostic messages.)
The extension's block type code.
A pointer to an offer function.
A pointer to a function to be called when forwarding a bundle containing this sort of block.
A pointer to a function to be called when taking custody of a bundle containing this sort of block.
A pointer to a function to be called when enqueuing for transmission a bundle containing this sort of block.
A pointer to a function to be called when a convergence-layer adapter dequeues a bundle containing this sort of block, before serializing it.
A pointer to a function to be called immediately before a convergence-layer adapter transmits a bundle containing this sort of block, after the bundle has been serialized.
A pointer to a release function.
A pointer to a copy function.
A pointer to an acquire function.
A pointer to a review function.
A pointer to a decrypt function.
A pointer to a parse function.
A pointer to a check function.
A pointer to a record function.
A pointer to a clear function.
All extension definitions must be coded into an array of ExtensionDef structures named extensionDefs.
An array of ExtensionSpec structures named extensionSpecs is also required. Each ExtensionSpec provides the specification for producing an outbound extension block: block definition (identified by block type number), three discriminator tags whose semantics are block-type-specific, and CRC type indicating what type of CRC must be used to protect this extension block. The order of appearance of extension specifications in the extensionSpecs array determines the order in which extension blocks will be inserted into locally sourced bundles.
The standard extensionDefs array -- which is empty -- is in the noextensions.c prototype source file. The procedure for extending the Bundle Protocol in ION is as follows:
1. Specify -DBP_EXTENDED in the Makefile's compiler command line when building the libbpP.c library module.
2. Create a copy of the prototype extensions file, named \"bpextensions.c\", in a directory that is made visible to the Makefile's libbpP.c compilation command line (by a -I parameter).
3. In the \"external function declarations\" area of \"bpextensions.c\", add \"extern\" function declarations identifying the functions that will implement your extension (or extensions).
4. Add one or more ExtensionDef structure initialization lines to the extensionDefs array, referencing those declared functions.
5. Add one or more ExtensionSpec structure initialization lines to the extensionSpecs array, referencing those extension definitions.
6. Develop the implementations of the extension implementation functions in one or more new source code files.
7. Add the object file or files for the new extension implementation source file (or files) to the Makefile's command line for linking libbpP.so.
The function pointers supplied in each ExtensionDef must conform to the following specifications. NOTE that any function that modifies the bytes member of an ExtensionBlock or AckExtBlock must set the corresponding length to the new length of the bytes array, if changed.
int (*BpExtBlkOfferFn)(ExtensionBlock *blk, Bundle *bundle)
Populates all fields of the indicated ExtensionBlock structure for inclusion in the indicated outbound bundle. This function is automatically called when a new bundle is locally sourced or upon acquisition of a remotely sourced bundle that does not contain an extension block of this type. The values of the extension block are typically expected to be a function of the state of the bundle, but this is extension-specific. If it is not appropriate to offer an extension block of this type as part of this bundle, then the size, length, object, and bytes members of blk must all be set to zero. If it is appropriate to offer such a block but no internal object representing the state of the block is needed, the object and size members of blk must be set to zero. The type, blkProcFlags, and dataLength members of blk must be populated by the implementation of the \"offer\" function, but the length and bytes members are typically populated by calling the BP library function serializeExtBlk(), which must be passed the block to be serialized (with type, blkProcFlags and dataLength already set), a Lyst of EID references (two list elements -- offsets -- per EID reference, if applicable; otherwise NULL), and a pointer to the extension-specific block data. The block's bytes array and object (if present) must occupy space allocated from the ION database heap. Return zero on success, -1 on any system failure.
int (*BpExtBlkProcessFn)(ExtensionBlock *blk, Bundle *bundle, void *context)
Performs some extension-specific transformation of the data encapsulated in blk based on the state of bundle. The transformation to be performed will typically vary depending on whether the identified function is the one that is automatically invoked upon forwarding the bundle, upon taking custody of the bundle, upon enqueuing the bundle for transmission, upon removing the bundle from the transmission queue, or upon transmitting the serialized bundle. The context argument may supply useful supplemental information; in particular, the context provided to the ON_DEQUEUE function will comprise the name of the protocol for the duct from which the bundle has been dequeued, together with the EID of the neighboring node endpoint to which the bundle will be directly transmitted when serialized. The block-specific data in blk is located within bytes immediately after the header of the extension block; the length of the block's header is the difference between length and dataLength. Whenever the block's blkProcFlags, EID extensions, and/or block-specific data are altered, the serializeExtBlk() function should be called again to recalculate the size of the extension block and rebuild the bytes array. Return zero on success, -1 on any system failure.
void (*BpExtBlkReleaseFn)(ExtensionBlock *blk)
Releases all ION database space occupied by the object member of blk. This function is automatically called when a bundle is destroyed. Note that incorrect implementation of this function may result in a database space leak.
int (*BpExtBlkCopyFn)(ExtensionBlock *newblk, ExtensionBlock *oldblk)
Copies the object member of oldblk to ION database heap space and places the address of that new non-volatile object in the object member of newblk, also sets size in newblk. This function is automatically called when two copies of a bundle are needed, e.g., in the event that it must both be delivered to a local client and also fowarded to another node. Return zero on success, -1 on any system failure.
int (*BpAcqExtBlkAcquireFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Populates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is only to be provided for extension blocks that are never encrypted; a extension block that may be encrypted should have a BpAcqExtBlkParseFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkReviewFn)(AcqWorkArea *work)
Reviews the extension blocks that have been acquired for this bundle, checking to make sure that all blocks of this type that are required by policy are present. Returns 0 if any blocks are missing, 1 if all required blocks are present, -1 on any system failure.
int (*BpAcqExtBlkDecryptFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Decrypts some other extension block that has been acquired but not yet parsed, nominally using encapsulated ciphersuite information. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if no error in decryption was encountered, -1 on any system failure.
int (*BpAcqExtBlkParseFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Populates the indicated AcqExtBlock structure with size and object for retention as part of the indicated inbound bundle. (The type, blkProcFlags, EID references (if any), dataLength, length, and bytes values of the structure are pre-populated with data as extracted from the serialized bundle.) This function is provided for extension blocks that may be encrypted; a extension block that can never be encrypted should have a BpAcqExtBlkAcquireFn callback instead. The function is automatically called when an extension block of this type is encountered in the course of parsing and acquiring a bundle for local delivery and/or forwarding. If no internal object representing the state of the block is needed, the object member of acqblk must be set to NULL and the size member must be set to zero. If an object is needed for this block, it must occupy space that is allocated from ION working memory using MTAKE and its size must be indicated in blk. Return zero if the block is malformed (this will cause the bundle to be discarded), 1 if the block is successfully parsed, -1 on any system failure.
int (*BpAcqExtBlkCheckFn)(AcqExtBlock *acqblk, AcqWorkArea *work)
Examines the bundle in work to determine whether or not it is authentic, in the context of the indicated extension block. Return 1 if the block is determined to be inauthentic (this will cause the bundle to be discarded), zero if no inauthenticity is detected, -1 on any system failure.
int (*BpExtBlkRecordFn)(ExtensionBlock *blk, AcqExtBlock *acqblk)
Copies the object member of acqblk to ION database heap space and places the address of that non-volatile object in the object member of blk; also sets size in blk. This function is automatically called when an acquired bundle is accepted for forwarding and/or delivery. Return zero on success, -1 on any system failure.
void (*BpAcqExtBlkClearFn)(AcqExtBlock *acqblk)
Uses MRELEASE to release all ION working memory occupied by the object member of acqblk. This function is automatically called when acquisition of a bundle is completed, whether or not the bundle is accepted. Note that incorrect implementation of this function may result in a working memory leak.
void discardExtensionBlock(AcqExtBlock *blk)
Deletes this block from the bundle acquisition work area prior to the recording of the bundle in the ION database.
void scratchExtensionBlock(ExtensionBlock *blk)
Deletes this block from the bundle after the bundle has been recorded in the ION database.
Object findExtensionBlock(Bundle *bundle, unsigned int type, unsigned char tag1, unsigned char tag2, unsigned char tag3)
On success, returns the address of the ExtensionBlock in bundle for the indicated type and tag values. If no such extension block exists, returns zero.
int serializeExtBlk(ExtensionBlock *blk, char *blockData)
Constructs a BPv7-conformant serialized representation of this extension block in blk->bytes. Returns 0 on success, -1 on an unrecoverable system error.
void suppressExtensionBlock(ExtensionBlock *blk)
Causes blk to be omitted when the bundle to which it is attached is serialized for transmission. This suppression remains in effect until it is reversed by restoreExtensionBlock();
void restoreExtensionBlock(ExtensionBlock *blk)
Reverses the effect of suppressExtensionBlock(), enabling the block to be included when the bundle to which it is attached is serialized.
bp(3)
"},{"location":"man/bpv7/bping/","title":"NAME","text":"bping - Send and receive Bundle Protocol echo bundles.
"},{"location":"man/bpv7/bping/#synopsis","title":"SYNOPSIS","text":"bping [-c count] [-i interval] [-p priority] [-q wait] [-r flags] [-t ttl] srcEID destEID [reporttoEID]
"},{"location":"man/bpv7/bping/#description","title":"DESCRIPTION","text":"bping sends bundles from srcEID to destEID. If the destEID echoes the bundles back (for instance, it is a bpecho endpoint), bping will print the round-trip time. When complete, bping will print statistics before exiting. It is very similar to ping, except it works with the bundle protocol.
bping terminates when one of the following happens: it receives the SIGINT signal (Ctrl+C), it receives responses to all of the bundles it sent, or it has sent all count of its bundles and waited wait seconds.
When bping is executed in a VxWorks or RTEMS environment, its runtime arguments are presented positionally rather than by keyword, in this order: count, interval, priority, wait, flags, TTL, verbosity (a Boolean, defaulting to zero), source EID, destination EID, report-to EID.
Source EID and destination EID are always required.
"},{"location":"man/bpv7/bping/#exit-status","title":"EXIT STATUS","text":"These exit statuses are taken from ping.
\"0\"
bping has terminated normally, and received responses to all the packets it sent.
\"1\"
bping has terminated normally, but it did not receive responses to all the packets it sent.
\"2\"
bping has terminated due to an error. Details should be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv7/bping/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bping/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bping are written to the ION log file ion.log and printed to standard error. Diagnostic messages that don't cause bping to terminate indicate a failure parsing an echo response bundle. This means that destEID isn't an echo endpoint: it's responding with some other bundle message of an unexpected format.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bping bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bping can't send echo bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bping/#see-also","title":"SEE ALSO","text":"bpecho(1), bptrace(1), bpadmin(1), bp(3), ping(8)
"},{"location":"man/bpv7/bplist/","title":"NAME","text":"bplist - Bundle Protocol (BP) utility for listing queued bundles
"},{"location":"man/bpv7/bplist/#synopsis","title":"SYNOPSIS","text":"bplist [{count | detail} [destination_EID[/priority]]]
"},{"location":"man/bpv7/bplist/#description","title":"DESCRIPTION","text":"bplist is a utility program that reports on bundles that currently reside in the local node, as identified by entries in the local bundle agent's \"timeline\" list.
Either a count of bundles or a detailed list of bundles (noting primary block information together with hex and ASCII dumps of the payload and all extension blocks, in expiration-time sequence) may be requested.
Either all bundles or just a subset of bundles - restricted to bundles for a single destination endpoint, or to bundles of a given level of priority that are all destined for some specified endpoint - may be included in the report.
By default, bplist prints a detailed list of all bundles residing in the local node.
"},{"location":"man/bpv7/bplist/#exit-status","title":"EXIT STATUS","text":"\"0\"
bplist terminated, for reasons noted in the ion.log file.
\"1\"
bplist was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/bplist/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bplist/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bplist/#see-also","title":"SEE ALSO","text":"bpclock(1)
"},{"location":"man/bpv7/bpnmtest/","title":"NAME","text":"bpnmtest - Bundle Protocol (BP) network management statistics test
"},{"location":"man/bpv7/bpnmtest/#synopsis","title":"SYNOPSIS","text":"bpnmtest
"},{"location":"man/bpv7/bpnmtest/#description","title":"DESCRIPTION","text":"bpnmtest simply prints to stdout messages containing the current values of all BP network management tallies, then terminates.
"},{"location":"man/bpv7/bpnmtest/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpnmtest has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bpnmtest/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpnmtest/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bprc/","title":"NAME","text":"bprc - Bundle Protocol management commands file
"},{"location":"man/bpv7/bprc/#description","title":"DESCRIPTION","text":"Bundle Protocol management commands are passed to bpadmin either in a file of text lines or interactively at bpadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the Bundle Protocol management commands are described below.
"},{"location":"man/bpv7/bprc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 bpadmin 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 and the crypto suite BP was compiled with. HINT: combine with e 1 command to log the version number at startup.
1
The initialize command. Until this command is executed, Bundle Protocol is not in operation on the local ION node and most bpadmin commands will fail.
r 'command_text'
The run command. This command will execute command_text as if it had been typed at a console prompt. It is used to, for example, run another administrative program.
s
The start command. This command starts all schemes and all protocols on the local node.
m heapmax max_database_heap_per_acquisition
The manage heap for bundle acquisition command. This command declares the maximum number of bytes of SDR heap space that will be occupied by any single bundle acquisition activity (nominally the acquisition of a single bundle, but this is at the discretion of the convergence-layer input task). All data acquired in excess of this limit will be written to a temporary file pending extraction and dispatching of the acquired bundle or bundles. 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.
m maxcount max_value_of_bundle_ID_sequence_nbr
The manage maximum bundle ID sequence number command. This command sets the maximum value that will be assigned as the sequence number in a bundle ID for any bundle sourced at a node that lacks a synchronized clock (such that the creation time in the ID of every locally sourced bundle is always zero). The default value is -1, i.e., unlimited.
x
The stop command. This command stops all schemes and all protocols on the local node.
w { 0 | 1 | activity_spec }
The BP watch command. This command enables and disables production of a continuous stream of user-selected Bundle Protocol activity indication characters. A watch parameter of \"1\" selects all BP activity indication characters; \"0\" de-selects all BP activity indication characters; any other activity_spec such as \"acz~\" selects all activity indication characters in the string, de-selecting all others. BP will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
a new bundle is queued for forwarding
b bundle is queued for transmission
c bundle is popped from its transmission queue
y bundle is accepted upon arrival
z bundle is queued for delivery to an application
~ bundle is abandoned (discarded) on attempt to forward it
! bundle is destroyed due to TTL expiration
# bundle is queued for re-forwarding due to CL protocol failure
j bundle is placed in \"limbo\" for possible future re-forwarding
k bundle is removed from \"limbo\" and queued for re-forwarding
Note that a slightly amended interpretation should be applied to watch characters printed in the course of multicast transmission. The '~' character, meaning Abandoned (node did not forward this bundle), is printed by a node that is a leaf of the multicast tree, i.e., a node with no children; it cannot forward the bundle because it's got nobody to forward it to. The '!' character, meaning Destroyed (node destroyed a physical copy of a bundle), is printed by a node that has forwarded copies of the bundle to all of its children and no longer needs to retain the original - so it does an immediate permanent bundle destruction just as if the bundle's time to live had expired. Neither condition is anomalous.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a scheme scheme_name 'forwarder_command' 'admin_app_command'
The add scheme command. This command declares an endpoint naming \"scheme\" for use in endpoint IDs, which are structured as URIs: scheme_name:scheme-specific_part. forwarder_command will be executed when the scheme is started on this node, to initiate operation of a forwarding daemon for this scheme. admin_app_command will also be executed when the scheme is started on this node, to initiate operation of a daemon that opens a custodian endpoint identified within this scheme so that it can receive and process custody signals and bundle status reports.
c scheme scheme_name 'forwarder_command' 'admin_app_command'
The change scheme command. This command sets the indicated scheme's forwarder_command and admin_app_command to the strings provided as arguments.
d scheme scheme_name
The delete scheme command. This command deletes the scheme identified by scheme_name. The command will fail if any bundles identified in this scheme are pending forwarding, transmission, or delivery.
i scheme scheme_name
This command will print information (number and commands) about the endpoint naming scheme identified by scheme_name.
l scheme
This command lists all declared endpoint naming schemes.
s scheme scheme_name
The start scheme command. This command starts the forwarder and administrative endpoint tasks for the indicated scheme task on the local node.
x scheme scheme_name
The stop scheme command. This command stops the forwarder and administrative endpoint tasks for the indicated scheme task on the local node.
a endpoint endpoint_ID { q | x } ['recv_script']
The add endpoint command. This command establishes a DTN endpoint named endpoint_ID on the local node. The remaining parameters indicate what is to be done when bundles destined for this endpoint arrive at a time when no application has got the endpoint open for bundle reception. If 'x', then such bundles are to be discarded silently and immediately. If 'q', then such bundles are to be enqueued for later delivery and, if recv_script is provided, recv_script is to be executed.
c endpoint endpoint_ID { q | x } ['recv_script']
The change endpoint command. This command changes the action that is to be taken when bundles destined for this endpoint arrive at a time when no application has got the endpoint open for bundle reception, as described above.
d endpoint endpoint_ID
The delete endpoint command. This command deletes the endpoint identified by endpoint_ID. The command will fail if any bundles are currently pending delivery to this endpoint.
i endpoint endpoint_ID
This command will print information (disposition and script) about the endpoint identified by endpoint_ID.
l endpoint
This command lists all local endpoints, regardless of scheme name.
a protocol protocol_name [protocol_class]
The add protocol command. This command establishes access to the named convergence layer protocol at the local node.
The optional protocol_class argument indicates the reliability of the protocol. The value 1 indicates that the protocol natively supports bundle streaming; currently the only protocol in class 1 is BSSP. The value 2 indicates that the protocol performs no retransmission; an example is UDP. The value 8 (which is the default) indicates that the protocol detects data loss and automatically retransmits data accordingly; an example is TCP. Protocol class need not be specified when protocol_name is bssp, udp, tcp, stcp, brss, brsc, or ltp, as the protocol classes for these well-known protocols are hard-coded in ION.
In earlier versions of ION this command took two additional arguments, payload_bytes_per_frame and overhead_bytes_per_frame. These arguments are deprecated. BP configuration files that include a protocol commands in the old format will be processed correctly; the deprecated arguments will simply be ignored.
d protocol protocol_name
The delete protocol command. This command deletes the convergence layer protocol identified by protocol_name. The command will fail if any ducts are still locally declared for this protocol.
i protocol protocol_name
This command will print information about the convergence layer protocol identified by protocol_name.
l protocol
This command lists all convergence layer protocols that can currently be utilized at the local node.
s protocol protocol_name
The start protocol command. This command starts all induct and outduct tasks for inducts and outducts that have been defined for the indicated CL protocol on the local node.
x protocol protocol_name
The stop protocol command. This command stops all induct and outduct tasks for inducts and outducts that have been defined for the indicated CL protocol on the local node.
a induct protocol_name duct_name 'CLI_command'
The add induct command. This command establishes a \"duct\" for reception of bundles via the indicated CL protocol. The duct's data acquisition structure is used and populated by the \"induct\" task whose operation is initiated by CLI_command at the time the duct is started.
c induct protocol_name duct_name 'CLI_command'
The change induct command. This command changes the command that is used to initiate operation of the induct task for the indicated duct.
d induct protocol_name duct_name
The delete induct command. This command deletes the induct identified by protocol_name and duct_name. The command will fail if any bundles are currently pending acquisition via this induct.
i induct protocol_name duct_name
This command will print information (the CLI command) about the induct identified by protocol_name and duct_name.
l induct [protocol_name]
If protocol_name is specified, this command lists all inducts established locally for the indicated CL protocol. Otherwise it lists all locally established inducts, regardless of protocol.
s induct protocol_name duct_name
The start induct command. This command starts the indicated induct task as defined for the indicated CL protocol on the local node.
x induct protocol_name duct_name
The stop induct command. This command stops the indicated induct task as defined for the indicated CL protocol on the local node.
a outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The add outduct command. This command establishes a \"duct\" for transmission of bundles via the indicated CL protocol. The duct's data transmission structure is serviced by the \"outduct\" task whose operation is initiated by CLO_command at the time the duct is started. A value of zero for max_payload_length indicates that bundles of any size can be accommodated; this is the default.
c outduct protocol_name duct_name 'CLO_command' [max_payload_length]
The change outduct command. This command sets new values for the indicated duct's payload size limit and the command that is used to initiate operation of the outduct task for this duct.
d outduct protocol_name duct_name
The delete outduct command. This command deletes the outduct identified by protocol_name and duct_name. The command will fail if any bundles are currently pending transmission via this outduct.
i outduct protocol_name duct_name
This command will print information (the CLO command) about the outduct identified by protocol_name and duct_name.
l outduct [protocol_name]
If protocol_name is specified, this command lists all outducts established locally for the indicated CL protocol. Otherwise it lists all locally established outducts, regardless of protocol.
s outduct protocol_name duct_name
The start outduct command. This command starts the indicated outduct task as defined for the indicated CL protocol on the local node.
x outduct protocol_name duct_name
The stop outduct command. This command stops the indicated outduct task as defined for the indicated CL protocol on the local node.
a plan endpoint_name [transmission_rate]
The add plan command. This command establishes an egress plan governing transmission to the neighboring node[s] identified by endpoint_name. The plan is functionally enacted by a bpclm(1) daemon dedicated to managing bundles queued for transmission to the indicated neighboring node[s].
NOTE that these \"plan\" commands supersede and generalize the egress plan commands documented in the ipnrc(5) and dtn2rc(5) man pages, which are retained for backward compatibility. The syntax of the egress plan commands consumed by bpadmin is DIFFERENT from that of the commands consumed by ipnadmin and dtn2admin. The endpoint_name identifying an egress plan is normally the node ID for a single node but may instead be \"wild-carded\". That is, when the last character of an endpoint name ID is either '*' or '~' (these two wild-card characters are equivalent for this purpose), the plan applies to all nodes whose IDs are identical to the wild-carded node name up to the wild-card character. For example, a bundle whose destination EID name is \"dtn://foghorn\" would be routed by plans citing the following node IDs: \"dtn://foghorn\", \"dtn://fogh*\", \"dtn://fog~\", \"//*\". When multiple plans are all applicable to the same destination EID, the one citing the longest (i.e., most narrowly targeted) node ID will be applied.
An egress plan may direct that bundles queued for transmission to the node[s] matching endpoint_name be transmitted using one of the convergence-layer protocol \"outducts\" that have been attached to the plan, or instead that those bundles be routed to some other \"gateway\" endpoint (resulting in transmission according to some other egress plan). In the event that both a gateway endpoint and one or more outducts have been declared for a given plan, the gateway declaration prevails.
A transmission_rate may be asserted for an egress plan; this rate is used as the basis for transmission rate control in the absence of applicable contacts (in the node's contact plan, as per ionrc(5)). A transmission rate of zero (absent applicable contacts) disables rate control completely; this is the default.
c plan endpoint_name [transmission_rate]
The change plan command. This command sets a new value for the indicated plan's transmission rate.
d plan endpoint_name
The delete plan command. This command deletes the plan identified by endpoint_name. The command will fail if any bundles are currently pending transmission per this plan.
i plan endpoint_name
This command will print information (the transmission rate) about the plan identified by endpoint_name.
l plan
This command lists all locally established egress plans.
s plan endpoint_name
The start plan command. This command starts the bpclm(1) task for the indicated egress plan.
x plan endpoint_name
The stop plan command. This command stops the bpclm(1) task for the indicated egress plan.
b plan endpoint_name
The block plan command. This command disables transmission of bundles queued for transmission to the indicated node and reforwards all non-critical bundles currently queued for transmission to this node. This may result in some or all of these bundles being enqueued for transmission (actually just retention) to the pseudo-node \"limbo\".
u plan endpoint_name
The unblock plan command. This command re-enables transmission of bundles to the indicated node and reforwards all bundles in \"limbo\" in the hope that the unblocking of this egress plan will enable some of them to be transmitted.
g plan endpoint_name gateway_endpoint_name
The declare gateway command. This command declares the name of the endpoint to which bundles queued for transmission to the node[s] identified by endpoint_name must be re-routed. Declaring gateway_endpoint_name to be the zero-length string \"''\" disables re-routing: bundles will instead be transmitted using the plan's attached convergence-layer protocol outduct[s].
a planduct endpoint_name protocol_name duct_name
The attach outduct command. This command declares that the indicated convergence-layer protocol outduct is now a viable device for transmitting bundles to the node[s] identified by endpoint_name.
d planduct protocol_name duct_name
The detach outduct command. This command declares that the indicated convergence-layer protocol outduct is no longer a viable device for transmitting bundles to the node[s] to which it is currently assigned.
a scheme ipn 'ipnfw' 'ipnadminep'
Declares the \"ipn\" scheme on the local node.
a protocol udp 1400 100 16384
Establishes access to the \"udp\" convergence layer protocol on the local node, estimating the number of payload bytes per ultimate (lowest-layer) frame to be 1400 with 100 bytes of total overhead (BP, UDP, IP, AOS) per lowest-layer frame, and setting the default nominal data rate to be 16384 bytes per second.
r 'ipnadmin flyby.ipnrc'
Runs the administrative program ipnadmin from within bpadmin.
bpadmin(1), ipnadmin(1), dtn2admin(1)
"},{"location":"man/bpv7/bprecvfile/","title":"NAME","text":"bprecvfile - Bundle Protocol (BP) file reception utility
"},{"location":"man/bpv7/bprecvfile/#synopsis","title":"SYNOPSIS","text":"bprecvfile own_endpoint_ID [max_files]
"},{"location":"man/bpv7/bprecvfile/#description","title":"DESCRIPTION","text":"bprecvfile is intended to serve as the counterpart to bpsendfile. It uses bp_receive() to receive bundles containing file content. The content of each bundle is simply written to a file named \"testfileN\" where N is the total number of bundles received since the program began running.
If a max_files value of N (where N > 0) is provided, the program will terminate automatically upon completing its Nth file reception. Otherwise it will run indefinitely; use ^C to terminate the program.
"},{"location":"man/bpv7/bprecvfile/#exit-status","title":"EXIT STATUS","text":"\"0\"
bprecvfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bprecvfile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bprecvfile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
bprecvfile bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't open test file
File system error. bprecvfile terminates.
bprecvfile: can't receive bundle content.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't write to test file
File system error. bprecvfile terminates.
bprecvfile cannot continue.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't handle bundle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bprecvfile/#see-also","title":"SEE ALSO","text":"bpsendfile(1), bp(3)
"},{"location":"man/bpv7/bprecvfile2/","title":"NAME","text":"bprecvfile2 - Bundle Protocol (BP) file reception utility
"},{"location":"man/bpv7/bprecvfile2/#synopsis","title":"SYNOPSIS","text":"bprecvfile own_endpoint_ID [filename]
"},{"location":"man/bpv7/bprecvfile2/#description","title":"DESCRIPTION","text":"This is an updated version of the original bprecvfile utility
bprecvfile is intended to serve as the counterpart to bpsendfile. It uses bp_receive() to receive bundles containing file content. The content of each bundle is simply written to a file named \"filename\". If the filename is not provided on the command line bundles are written to stdout. Use of UNIX pipes is allowed. Note: If filename exists data will be appended to that file. If filename does not exist it will be created. Use ^C to terminate the program.
"},{"location":"man/bpv7/bprecvfile2/#exit-status","title":"EXIT STATUS","text":"\"0\"
bprecvfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bprecvfile2/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bprecvfile2/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
bprecvfile bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't open test file
File system error. bprecvfile terminates.
bprecvfile: can't receive bundle content.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't write to test file
File system error. bprecvfile terminates.
bprecvfile cannot continue.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bprecvfile: can't handle bundle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bprecvfile2/#see-also","title":"SEE ALSO","text":"bpsendfile(1), bp(3)
"},{"location":"man/bpv7/bpsecadmin/","title":"NAME","text":"bpsecadmin - BP security policy administration interface
"},{"location":"man/bpv7/bpsecadmin/#synopsis","title":"SYNOPSIS","text":"bpsecadmin [ commands_filename ]
"},{"location":"man/bpv7/bpsecadmin/#description","title":"DESCRIPTION","text":"bpsecadmin configures and manages BP security policy on the local computer.
It configures and manages BP security policy on the local computer in response to BP configuration commands found in commands_filename, if provided; if not, bpsecadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from bpsecadmin by entering the command 'h' or '?' at the prompt. The commands are documented in bpsecrc(5).
"},{"location":"man/bpv7/bpsecadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of BP security policy administration.
bpsecadmin
Enter interactive ION security policy administration command entry mode.
bpsecadmin host1.bpsecrc
Execute all configuration commands in host1.bpsecrc, then terminate immediately.
Status and diagnostic messages from bpsecadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which bpsecadmin was run. The log file is typically named ion.log.
See also bpsecrc(5).
"},{"location":"man/bpv7/bpsecadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpsecadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bpsecadmin. Otherwise bpsecadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bpsecadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see bpsecrc(5) for details.
"},{"location":"man/bpv7/bpsecadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpsecadmin/#see-also","title":"SEE ALSO","text":"bpsecrc(5)
"},{"location":"man/bpv7/bpsecrc/","title":"NAME","text":"bpsecrc - BP security policy management commands file
"},{"location":"man/bpv7/bpsecrc/#description","title":"DESCRIPTION","text":"BP security policy management commands are passed to bpsecadmin either in a file of text lines or interactively at bpsecadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. JSON commands may span multiple lines when provided as part of a config file. The formats and effects of the BP security policy management commands are described below.
A parameter identifed as an eid_expr is an \"endpoint ID expression.\" For all commands, whenever the last character of an endpoint ID expression is the wild-card character '*', an applicable endpoint ID \"matches\" this EID expression if all characters of the endpoint ID expression prior to the last one are equal to the corresponding characters of that endpoint ID. Otherwise an applicable endpoint ID \"matches\" the EID expression only when all characters of the EID and EID expression are identical.
At present, ION supports a subset of the proposed \"BPSec\" security protocol specification currently under consideration by the Internet Engineering Steering Group. Since BPSec is not yet a published standard, ION's Bundle Protocol security mechanisms will not necessarily interoperate with those of other BP implementations. This is unfortunate but (we hope) temporary, as BPSec represents a major improvement in bundle security. Future releases of ION will implement the entire BPSec specification.
"},{"location":"man/bpv7/bpsecrc/#commands","title":"COMMANDS","text":"?
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 bpsecadmin 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.
a { event_set : { name : event set name, desc : (opt) description } }
The add event_set command. This command will add a named security operation event set to the local security policy database.
i { event_set : { name : event set name } }
The info event_set command for event sets displays the information the system maintains for a named event set. The security operation events and configured, optional processing actions associated with that event set are shown.
d { event_set : { name : event set name } }
The delete event_set command deletes a named event set from the system. A named event set cannot be deleted if it is referenced by a security policy rule. All security policy rules associated with the named event set must be deleted before the event set itself may be deleted.
l {event_set}
The list event_set command lists the names of all event sets defined in the system.
a { event : { es_ref : event set name, event_id : security operation event ID, actions : [ {id: processing action, (opt.) action parm key, (opt.) parm value}, ... , {id: processing action, (opt.) action parm key, (opt.) parm value} ] } }
The add event command adds security operation event and associated optional processing action(s) to an event set. Multiple processing actions can be specified for a single security operation event.
d { event : { es_ref : event set name, event_id : security operation event ID } }
The delete event command is used to delete optional processing actions from a named event set. This command currently deletes all of the optional processing actions associated with the security operation event provided.
a { policyrule : { desc : (opt.) description, filter : { rule_id : Security policy rule id, role : Security policy role, src : Bundle source, dest : Bundle destination sec_src : Security source tgt : Security target block type, sc_id : Security context ID, }, spec : { svc : Security service, sc_id : Security context ID, sc_parms : [ {SC parm ID, SC parm value }, ... , {SC parm ID, SC parm value } ] }, es_ref : Event set name } }
The add policyrule command adds a policy rule to the system, describing a required security operation and the security policy role of the BPA applying the policy statement. The above command adds a policy rule referencing a named event set to the system.
d { policyrule : { rule_id : Security policy rule ID } }
The delete policyrule command deletes the policy rule identified by its rule ID.
i {policyrule : { rule_id : Security policy rule ID } }
The info policyrule command displays the information for the policy rule matching the provided ID.
f {policyrule : {type : all | best, src : Bundle source, dest : Bundle destination, sec_src : Security source, sc_id : Security context ID, role : Security policy role } }
The find policyrule command finds all policy rules matching the provided criteria when type all is selected, and finds the single policy rule that is determined to be the best match when type best is selected.
l {policyrule}
The list policyrule command lists all policy rules currently defined in the system.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
bpsecadmin(1)
"},{"location":"man/bpv7/bpsendfile/","title":"NAME","text":"bpsendfile - Bundle Protocol (BP) file transmission utility
"},{"location":"man/bpv7/bpsendfile/#synopsis","title":"SYNOPSIS","text":"bpsendfile own_endpoint_ID destination_endpoint_ID file_name [class_of_service [time_to_live (seconds) ]]
"},{"location":"man/bpv7/bpsendfile/#description","title":"DESCRIPTION","text":"bpsendfile uses bp_send() to issue a single bundle to a designated destination endpoint, containing the contents of the file identified by file_name, then terminates. The bundle is sent with no custody transfer requested. When class_of_service is omitted, the bundle is sent at standard priority; for details of the class_of_service parameter, see bptrace(1). time_to_live, if not specified, defaults to 300 seconds (5 minutes). NOTE that time_to_live is specified AFTER class_of_service, rather than before it as in bptrace(1).
"},{"location":"man/bpv7/bpsendfile/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsendfile has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bpsendfile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpsendfile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to BP.
bpadmin has not yet initialized BP operations.
Can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
Can't stat the file
Operating system error. Check errtext, correct problem, and rerun.
bpsendfile can't create file ref.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpsendfile can't create ZCO.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bpsendfile can't send file in bundle.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpsendfile/#see-also","title":"SEE ALSO","text":"bprecvfile(1), bp(3)
"},{"location":"man/bpv7/bpsink/","title":"NAME","text":"bpsink - Bundle Protocol reception test program
"},{"location":"man/bpv7/bpsink/#synopsis","title":"SYNOPSIS","text":"bpsink ownEndpointId
"},{"location":"man/bpv7/bpsink/#description","title":"DESCRIPTION","text":"bpsink uses Bundle Protocol to receive application data units from a remote bpsource application task. For each application data unit it receives, it prints the ADU's length and -- if length is less than 80 -- its text.
bpsink terminates upon receiving the SIGQUIT signal, i.e., ^C from the keyboard.
"},{"location":"man/bpv7/bpsink/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsink has terminated. Any problems encountered during operation will be noted in the ion.log log file.
No configuration files are needed.
"},{"location":"man/bpv7/bpsink/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpsink/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpsink are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
Can't open own endpoint.
Another application has already opened ownEndpointId. Terminate that application and rerun.
bpsink bundle reception failed.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't receive payload.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't handle delivery.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpsink/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpsource(1), bp(3)
"},{"location":"man/bpv7/bpsource/","title":"NAME","text":"bpsource - Bundle Protocol transmission test shell
"},{"location":"man/bpv7/bpsource/#synopsis","title":"SYNOPSIS","text":"bpsource destinationEndpointId [\"text\"] [-t_TTL_]
"},{"location":"man/bpv7/bpsource/#description","title":"DESCRIPTION","text":"When text is supplied, bpsource simply uses Bundle Protocol to send text to a counterpart bpsink application task that has opened the BP endpoint identified by destinationEndpointId, then terminates.
Otherwise, bpsource offers the user an interactive \"shell\" for testing Bundle Protocol data transmission. bpsource prints a prompt string (\": \") to stdout, accepts a string of text from stdin, uses Bundle Protocol to send the string to a counterpart bpsink application task that has opened the BP endpoint identified by destinationEndpointId, then prints another prompt string and so on. To terminate the program, enter a string consisting of a single exclamation point (!) character.
TTL indicates the number of seconds the bundles may remain in the network, undelivered, before they are automatically destroyed. If omitted, TTL defaults to 300 seconds.
The source endpoint ID for each bundle sent by bpsource is the null endpoint ID, i.e., the bundles are anonymous. All bundles are sent standard priority with no custody transfer and no status reports requested.
"},{"location":"man/bpv7/bpsource/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpsource has terminated. Any problems encountered during operation will be noted in the ion.log log file.
The service data units transmitted by bpsource are sequences of text obtained from a file in the current working directory named \"bpsourceAduFile\", which bpsource creates automatically.
"},{"location":"man/bpv7/bpsource/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpsource/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by bpsource are written to the ION log file ion.log.
Can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
bpsource fgets failed
Operating system error. Check errtext, correct problem, and rerun.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpsource can't send ADU
Bundle Protocol service to the remote endpoint has been stopped.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpsource/#see-also","title":"SEE ALSO","text":"bpadmin(1), bpsink(1), bp(3)
"},{"location":"man/bpv7/bpstats/","title":"NAME","text":"bpstats - Bundle Protocol (BP) processing statistics query utility
"},{"location":"man/bpv7/bpstats/#synopsis","title":"SYNOPSIS","text":"bpstats
"},{"location":"man/bpv7/bpstats/#description","title":"DESCRIPTION","text":"bpstats simply logs messages containing the current values of all BP processing statistics accumulators, then terminates.
"},{"location":"man/bpv7/bpstats/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpstats has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bpstats/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpstats/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpstats can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpstats/#see-also","title":"SEE ALSO","text":"ion(3)
"},{"location":"man/bpv7/bpstats2/","title":"NAME","text":"bpstats2 - Bundle Protocol (BP) processing statistics query utility via bundles
"},{"location":"man/bpv7/bpstats2/#synopsis","title":"SYNOPSIS","text":"bpstats2 sourceEID [default destEID] [ct]
"},{"location":"man/bpv7/bpstats2/#description","title":"DESCRIPTION","text":"bpstats2 creates bundles containing the current values of all BP processing statistics accumulators. It creates these bundles when:
\"0\"
bpstats2 has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
bpstats2 failed to start up or receive bundles. Diagnose the issue reported in the ion.log file and try again.
If the string \"ct\" is appended as the last argument, then statistics bundles will be sent with custody transfer requested.
No configuration files are needed.
"},{"location":"man/bpv7/bpstats2/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bpstats2/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bpstats2 can't bp_attach().
bpadmin has not yet initialized BP operations.
bpstats2 can't open own endpoint.
Another BP application has opened that endpoint; close it and try again.
No space for ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create ZCO extent.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
bpstats2 can't send stats bundle.
Bundle Protocol service to the remote endpoint has been stopped.
Can't send stats: bad dest EID (dest EID)
The destination EID printed is an invalid destination EID. The destination EID may be specified in default destEID or the source EID of the interrogation bundle. Ensure that default destEID is an EID that is valid for ION, and that the interrogator is a source EID that is also a valid destination EID. Note that \"dtn:none\" is not a valid destination EID, but is a valid source EID.
A very simple interrogator is bpchat which can repeatedly interrogate bpstats2 by just striking the enter key.
"},{"location":"man/bpv7/bpstats2/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bpstats2/#see-also","title":"SEE ALSO","text":"bpstats(1), bpchat(1)
"},{"location":"man/bpv7/bptrace/","title":"NAME","text":"bptrace - Bundle Protocol (BP) network trace utility
"},{"location":"man/bpv7/bptrace/#synopsis","title":"SYNOPSIS","text":"bptrace own_endpoint_ID destination_endpoint_ID report-to_endpoint_ID TTL class_of_service \"trace_text\" [status_report_flags]
"},{"location":"man/bpv7/bptrace/#description","title":"DESCRIPTION","text":"bptrace uses bp_send() to issue a single bundle to a designated destination endpoint, with status reporting options enabled as selected by the user, then terminates. The status reports returned as the bundle makes its way through the network provide a view of the operation of the network as currently configured.
TTL indicates the number of seconds the trace bundle may remain in the network, undelivered, before it is automatically destroyed.
class_of_service is custody-requested.priority[.ordinal[.unreliable.critical[.data-label]]], where custody-requested must be 0 or 1 (Boolean), priority must be 0 (bulk) or 1 (standard) or 2 (expedited), ordinal must be 0-254, unreliable must be 0 or 1 (Boolean), critical must also be 0 or 1 (Boolean), and data-label may be any unsigned integer. custody-requested is passed in with the bundle transmission request, but if set to 1 it serves only to request the use of reliable convergence-layer protocols; this will have the effect of enabling custody transfer whenever the applicable convergence-layer protocol is bundle-in-bundle encapsulation (BIBE). ordinal is ignored if priority is not 2. Setting class_of_service to \"0.2.254\" or \"1.2.254\" gives a bundle the highest possible priority. Setting unreliable to 1 causes BP to forego convergence-layer retransmission in the event of data loss. Setting critical to 1 causes contact graph routing to forward the bundle on all plausible routes rather than just the \"best\" route it computes; this may result in multiple copies of the bundle arriving at the destination endpoint, but when used in conjunction with priority 2.254 it ensures that the bundle will be delivered as soon as physically possible.
trace_text can be any string of ASCII text; alternatively, if we want to send a file, it can be \"@\" followed by the name of the file.
status_report_flags must be a sequence of status report flags, separated by commas, with no embedded whitespace. Each status report flag must be one of the following: rcv, fwd, dlv, del.
"},{"location":"man/bpv7/bptrace/#exit-status","title":"EXIT STATUS","text":"\"0\"
bptrace has terminated.
No configuration files are needed.
"},{"location":"man/bpv7/bptrace/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bptrace/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bptrace can't attach to BP.
bpadmin has not yet initialized BP operations.
bptrace can't open own endpoint.
Another BP application task currently has own_endpoint_ID open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
No space for bptrace text.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't create ZCO.
Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't send message.
BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bptrace/#see-also","title":"SEE ALSO","text":"bp(3)
"},{"location":"man/bpv7/bptransit/","title":"NAME","text":"bptransit - Bundle Protocol (BP) daemon task for forwarding received bundles
"},{"location":"man/bpv7/bptransit/#synopsis","title":"SYNOPSIS","text":"bptransit
"},{"location":"man/bpv7/bptransit/#description","title":"DESCRIPTION","text":"bptransit is a background \"daemon\" task that is responsible for presenting to ION's forwarding daemons any bundles that were received from other nodes (i.e., bundles whose payloads reside in Inbound ZCO space) and are destined for yet other nodes. In doing so, it migrates these bundles from Inbound buffer space to Outbound buffer space on the same prioritized basis as the insertion of locally sourced outbound bundles.
Management of the bptransit daemon is automatic. It is spawned automatically by bpadmin in response to the 's' command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command.
Whenever a received bundle is determined to have a destination other than the local node, a pointer to that bundle is appended to one of two queues of \"in-transit\" bundles, one for bundles whose forwarding is provisional (depending on the availability of Outbound ZCO buffer space; bundles in this queue are potentially subject to congestion loss) and one for bundles whose forwarding is confirmed. Bundles received via convergence-layer adapters that can sustain flow control, such as STCP, are appended to the \"confirmed\" queue, while those from CLAs that cannot sustain flow control (such as LTP) are appended to the \"provisional\" queue.
bptransit comprises two threads, one for each in-transit queue. The confirmed in-transit thread dequeues bundles from the \"confirmed\" queue and moves them from Inbound to Outbound ZCO buffer space, blocking (if necessary) until space becomes available. The provisional in-transit queue dequeues bundles from the \"provisional\" queue and moves them from Inbound to Outbound ZCO buffer space if Outbound space is available, discarding (\"abandoning\") them if it is not.
"},{"location":"man/bpv7/bptransit/#exit-status","title":"EXIT STATUS","text":"\"0\"
bptransit terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart bptransit.
\"1\"
bptransit was unable to attach to Bundle Protocol operations, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/bptransit/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/bptransit/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bptransit can't attach to BP.
bpadmin has not yet initialized BP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/bptransit/#see-also","title":"SEE ALSO","text":"bpadmin(1)
"},{"location":"man/bpv7/brsccla/","title":"NAME","text":"brsccla - BRSC-based BP convergence layer adapter (input and output) task
"},{"location":"man/bpv7/brsccla/#synopsis","title":"SYNOPSIS","text":"brsccla server_hostname[:server_port_nbr]_own_node_nbr
"},{"location":"man/bpv7/brsccla/#description","title":"DESCRIPTION","text":"BRSC is the \"client\" side of the Bundle Relay Service (BRS) convergence layer protocol for BP. It is complemented by BRSS, the \"server\" side of the BRS convergence layer protocol for BP. BRS clients send bundles directly only to the server, regardless of their final destinations, and the server forwards them to other clients as necessary.
brsccla is a background \"daemon\" task comprising three threads: one that connects to the BRS server, spawns the other threads, and then handles BRSC protocol output by transmitting bundles over the connected socket to the BRS server; one that simply sends periodic \"keepalive\" messages over the connected socket to the server (to assure that local inactivity doesn't cause the connection to be lost); and one that handles BRSC protocol input from the connected server.
The output thread connects to the server's TCP socket at server_hostname and server_port_nbr, sends over the connected socket the client's own_node_nbr (in SDNV representation) followed by a 32-bit time tag and a 160-bit HMAC-SHA1 digest of that time tag, to authenticate itself; checks the authenticity of the 160-bit countersign returned by the server; spawns the keepalive and receiver threads; and then begins extracting bundles from the queues of bundles ready for transmission via BRSC and transmitting those bundles over the connected socket to the server. Each transmitted bundle is preceded by its length, a 32-bit unsigned integer in network byte order. The default value for server_port_nbr, if omitted, is 80.
The reception thread receives bundles over the connected socket and passes them to the bundle protocol agent on the local ION node. Each bundle received on the connection is preceded by its length, a 32-bit unsigned integer in network byte order.
The keepalive thread simply sends a \"bundle length\" value of zero (a 32-bit unsigned integer in network byte order) to the server once every 15 seconds.
brsccla is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. brsccla can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BRSC convergence layer protocol.
"},{"location":"man/bpv7/brsccla/#exit-status","title":"EXIT STATUS","text":"\"0\"
brsccla terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSC protocol.
\"1\"
brsccla terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSC protocol.
No configuration files are needed.
"},{"location":"man/bpv7/brsccla/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/brsccla/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
brsccla can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such brsc induct.
No BRSC induct with duct name matching server_hostname, own_node_nbr, and server_port_nbr has been added to the BP database. Use bpadmin to stop the BRSC convergence-layer protocol, add the induct, and then restart the BRSC protocol.
CLI task is already started for this duct.
Redundant initiation of brsccla.
No such brsc outduct.
No BRSC outduct with duct name matching server_hostname, own_node_nbr, and server_port_nbr has been added to the BP database. Use bpadmin to stop the BRSC convergence-layer protocol, add the outduct, and then restart the BRSC protocol.
Can't connect to server.
Operating system error. Check errtext, correct problem, and restart BRSC.
Can't register with server.
Configuration error. Authentication has failed, probably because (a) the client and server are using different HMAC/SHA1 keys or (b) the clocks of the client and server differ by more than 5 seconds. Update security policy database(s), as necessary, and assure that the clocks are synchronized.
brsccla can't create receiver thread
Operating system error. Check errtext, correct problem, and restart BRSC.
brsccla can't create keepalive thread
Operating system error. Check errtext, correct problem, and restart BRSC.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/brsccla/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), brsscla(1)
"},{"location":"man/bpv7/brsscla/","title":"NAME","text":"brsscla - BRSS-based BP convergence layer adapter (input and output) task
"},{"location":"man/bpv7/brsscla/#synopsis","title":"SYNOPSIS","text":"brsscla local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/brsscla/#description","title":"DESCRIPTION","text":"BRSS is the \"server\" side of the Bundle Relay Service (BRS) convergence layer protocol for BP. It is complemented by BRSC, the \"client\" side of the BRS convergence layer protocol for BP.
brsscla is a background \"daemon\" task that spawns 2*N threads: one that handles BRSS client connections and spawns sockets for continued data interchange with connected clients; one that handles BRSS protocol output by transmitting over those spawned sockets to the associated clients; and two thread for each spawned socket, an input thread to handle BRSS protocol input from the associated connected client and an output thread to forward BRSS protocol output to the associated connected client.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 80.
Each reception thread receives over the socket connection the node number of the connecting client (in SDNV representation), followed by a 32-bit time tag and a 160-bit HMAC-SHA1 digest of that time tag. The receiving thread checks the time tag, requiring that it differ from the current time by no more than BRSTERM (default value 5) seconds. It then recomputes the digest value using the HMAC-SHA1 key named \"node_number.brs\" as recorded in the ION security database (see ionsecrc(5)), requiring that the supplied and computed digests be identical. If all registration conditions are met, the receiving thread sends the client a countersign -- a similarly computed HMAC-SHA1 digest, for the time tag that is 1 second later than the provided time tag -- to assure the client of its own authenticity, then commences receiving bundles over the connected socket. Each bundle received on the connection is preceded by its length, a 32-bit unsigned integer in network byte order. The received bundles are passed to the bundle protocol agent on the local ION node.
Each output thread extracts bundles from the queues of bundles ready for transmission via BRSS to the corresponding connected client and transmits the bundles over the socket to that client. Each transmitted bundle is preceded by its length, a 32-bit unsigned integer in network byte order.
brsscla is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. brsscla can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BRSS convergence layer protocol.
"},{"location":"man/bpv7/brsscla/#exit-status","title":"EXIT STATUS","text":"\"0\"
brsscla terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSS protocol.
\"1\"
brsscla terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSS protocol.
No configuration files are needed.
"},{"location":"man/bpv7/brsscla/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/brsscla/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
brsscla can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such brss induct.
No BRSS induct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the BRSS convergence-layer protocol, add the induct, and then restart the BRSS protocol.
CLI task is already started for this duct.
Redundant initiation of brsscla.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart BRSS.
Can't open TCP socket
Operating system error -- unable to open TCP socket for accepting connections. Check errtext, correct problem, and restart BRSS.
Can't initialize socket (note: must be root for port 80)
Operating system error. Check errtext, correct problem, and restart BRSS.
brsscla can't create sender thread
Operating system error. Check errtext, correct problem, and restart BRSS.
brsscla can't create access thread
Operating system error. Check errtext, correct problem, and restart BRSS.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/brsscla/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), brsccla(1)
"},{"location":"man/bpv7/cgrfetch/","title":"NAME","text":"cgrfetch - Visualize CGR simulations
"},{"location":"man/bpv7/cgrfetch/#synopsis","title":"SYNOPSIS","text":"cgrfetch [OPTIONS] DEST-NODE
"},{"location":"man/bpv7/cgrfetch/#description","title":"DESCRIPTION","text":"cgrfetch uses CGR to simulate sending a bundle from the local node to DEST-NODE. It traces the execution of CGR to generate graphs of the routes that were considered and the routes that were ultimately chosen to forward along. No bundle is sent during the simulation.
A JSON representation of the simulation is output to OUTPUT-FILE. The representation includes parameters of the simulation and a structure for each considered route, which in turn includes calculated parameters for the route and an image of the contact graph.
The dot(1) tool from the Graphviz package is used to generate the contact graph images and is required for cgrfetch(1). The base64(1) tool from coreutils is used to embed the images in the JSON and is also required.
Note that a trace of the route computation logic performed by CGR is printed to stderr; there is currently no cgrfetch option for redirecting this output to a file.
"},{"location":"man/bpv7/cgrfetch/#options","title":"OPTIONS","text":"DEST-NODE
The final destination to route to. To be useful, it should be a node that exists in the contact plan.
-q
Disable trace message output.
-j
Disable JSON output.
-m
Use a minimum-latency extended COS for the bundle. This ends up sending the bundle to all proximate nodes.
-t DISPATCH-OFFSET
Request a dispatch time of DISPATCH-OFFSET seconds from the time the command is run (default: 0).
-e EXPIRATION-OFFSET
Set the bundle expiration time to EXPIRATION-OFFSET seconds from the time the command is run (default: 3600).
-s BUNDLE-SIZE
Set the bundle payload size to BUNDLE-SIZE bytes (default: 0).
-o OUTPUT-FILE
Send JSON to OUTPUT-FILE (default: stdout).
-d PROTO:NAME
Use PROTO as the outduct protocol and NAME as the outduct name (default: udp:*). Use list to list all available outducts.
cgrfetch 8
Simulate CGR with destination node 8 and dispatch time equal to the current time.
cgrfetch 8 -t 60
Do the same with a dispatch time 60 seconds in the future.
cgrfetch -d list
List all available outducts.
dot(1), base64(1)
"},{"location":"man/bpv7/dccpcli/","title":"NAME","text":"dccpcli - DCCP-based BP convergence layer input task
"},{"location":"man/bpv7/dccpcli/#synopsis","title":"SYNOPSIS","text":"dccpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/dccpcli/#description","title":"DESCRIPTION","text":"dccpcli is a background \"daemon\" task that receives DCCP datagrams via a DCCP socket bound to local_hostname and local_port_nbr, extracts bundles from those datagrams, and passes them to the bundle protocol agent on the local ION node.
If not specified, port number defaults to 4556.
Note that dccpcli has no fragmentation support at all. Therefore, the largest bundle that can be sent via this convergence layer is limited to just under the link's MTU (typically 1500 bytes).
The convergence layer input task is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"dccp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. dccpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DCCP convergence layer protocol.
"},{"location":"man/bpv7/dccpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dccpcli.
\"1\"
dccpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dccpcli.
No configuration files are needed.
"},{"location":"man/bpv7/dccpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dccpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such dccp duct.
No DCCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DCCP convergence-layer protocol, add the induct, and then restart the DCCP protocol.
CLI task is already started for this duct.
Redundant initiation of dccpcli.
dccpcli can't get IP address for host.
Operating system error. Check errtext, correct problem, and restart dccpcli.
CLI can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccpcli.
CLI can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccpcli.
dccpcli can't get acquisition work area.
ION system error. Check errtext, correct problem, and restart dccpcli.
dccpcli can't create new thread.
Operating system error. Check errtext, correct problem, and restart dccpcli.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dccpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), dccpclo(1)
"},{"location":"man/bpv7/dccpclo/","title":"NAME","text":"dccpclo - DCCP-based BP convergence layer output task
"},{"location":"man/bpv7/dccpclo/#synopsis","title":"SYNOPSIS","text":"dccpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv7/dccpclo/#description","title":"DESCRIPTION","text":"dccpclo is a background \"daemon\" task that connects to a remote node's DCCP socket at remote_hostname and remote_port_nbr. It then begins extracting bundles from the queues of bundles ready for transmission via DCCP to this remote bundle protocol agent and transmitting those bundles as DCCP datagrams to the remote host.
If not specified, remote_port_nbr defaults to 4556.
Note that dccpclo has no fragmentation support at all. Therefore, the largest bundle that can be sent via this convergence layer is limited to just under the link's MTU (typically 1500 bytes).
dccpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dccpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DCCP convergence layer protocol.
"},{"location":"man/bpv7/dccpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dccpclo.
\"1\"
dccpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dccpclo.
No configuration files are needed.
"},{"location":"man/bpv7/dccpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dccpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No memory for DCCP buffer in dccpclo.
ION system error. Check errtext, correct problem, and restart dccpclo.
No such dccp duct.
No DCCP outduct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DCCP convergence-layer protocol, add the outduct, and then restart dccpclo.
CLO task is already started for this duct.
Redundant initiation of dccpclo.
dccpclo can't get IP address for host.
Operating system error. Check errtext, correct problem, and restart dccpclo.
dccpclo can't create thread.
Operating system error. Check errtext, correct problem, and restart dccpclo.
CLO can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccpclo.
CLO can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccpclo.
CLO send() error on socket.
Operating system error. Check errtext, correct problem, and restart dccpclo.
Bundle is too big for DCCP CLO.
Configuration error: bundles that are too large for DCCP transmission (i.e., larger than the MTU of the link or 65535 bytes--whichever is smaller) are being enqueued for dccpclo. Change routing or use smaller bundles.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dccpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), dccpcli(1)
"},{"location":"man/bpv7/dgrcli/","title":"NAME","text":"dgrcli - DGR-based BP convergence layer reception task
"},{"location":"man/bpv7/dgrcli/#synopsis","title":"SYNOPSIS","text":"dgrcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/dgrcli/#description","title":"DESCRIPTION","text":"dgrcli is a background \"daemon\" task that handles DGR convergence layer protocol input.
The daemon receives DGR messages via a UDP socket bound to local_hostname and local_port_nbr, extracts bundles from those messages, and passes them to the bundle protocol agent on the local ION node. (local_port_nbr defaults to 1113 if not specified.)
dgrcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dgrcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DGR convergence layer protocol.
"},{"location":"man/bpv7/dgrcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgrcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dgrcli.
\"1\"
dgrcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dgrcli.
No configuration files are needed.
"},{"location":"man/bpv7/dgrcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dgrcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dgrcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such dgr induct.
No DGR induct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the DGR convergence-layer protocol, add the induct, and then restart the DGR protocol.
CLI task is already started for this engine.
Redundant initiation of dgrcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart DGR.
dgrcli can't open DGR service access point.
DGR system error. Check prior messages in ion.log log file, correct problem, and then stop and restart the DGR protocol.
dgrcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart DGR.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dgrcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/dgrclo/","title":"NAME","text":"dgrclo - DGR-based BP convergence layer transmission task
"},{"location":"man/bpv7/dgrclo/#synopsis","title":"SYNOPSIS","text":"dgrclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv7/dgrclo/#description","title":"DESCRIPTION","text":"dgrclo is a background \"daemon\" task that spawns two threads, one that handles DGR convergence layer protocol input (positive and negative acknowledgments) and a second that handles DGR convergence layer protocol output.
The output thread extracts bundles from the queues of bundles ready for transmission via DGR to a remote bundle protocol agent, encapsulates them in DGR messages, and uses a randomly configured local UDP socket to send those messages to the remote UDP socket bound to remote_hostname and remote_port_nbr. (local_port_nbr defaults to 1113 if not specified.)
The input thread receives DGR messages via the same local UDP socket and uses them to manage DGR retransmission of transmitted datagrams.
dgrclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. dgrclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the DGR convergence layer protocol.
"},{"location":"man/bpv7/dgrclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgrclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dgrclo.
\"1\"
dgrclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dgrclo.
No configuration files are needed.
"},{"location":"man/bpv7/dgrclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dgrclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dgrclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
CLI task is already started for this engine.
Redundant initiation of dgrclo.
No such dgr outduct.
No DGR outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the DGR convergence-layer protocol, add the outduct, and then restart the DGR protocol.
dgrclo can't open DGR service access point.
DGR system error. Check prior messages in ion.log log file, correct problem, and then stop and restart the DGR protocol.
dgrclo can't create sender thread
Operating system error. Check errtext, correct problem, and restart DGR.
dgrclo can't create receiver thread
Operating system error. Check errtext, correct problem, and restart DGR.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dgrclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/dtn2admin/","title":"NAME","text":"dtn2admin - baseline \"dtn\" scheme administration interface
"},{"location":"man/bpv7/dtn2admin/#synopsis","title":"SYNOPSIS","text":"dtn2admin [ commands_filename ]
"},{"location":"man/bpv7/dtn2admin/#description","title":"DESCRIPTION","text":"dtn2admin configures the local ION node's routing of bundles to endpoints whose IDs conform to the dtn endpoint ID scheme. Endpoint IDs in the dtn scheme are strings of the form \"dtn://node_name/[[~]demux_token]\", where node_name identifies a BP node (often this is the DNS name of the computer on which the node resides) and demux_token normally identifies a specific application processing point. When and only when the terminating demux string (everything after the final '/') does NOT begin with '~', the endpoint ID identifies a singleton endpoint; when the terminating demux string is omitted, the endpoint ID constitutes a node ID. Although the dtn endpoint ID scheme imposes more transmission overhead than the ipn scheme, ION provides support for dtn endpoint IDs to enable interoperation with other implementations of Bundle Protocol.
dtn2admin operates in response to \"dtn\" scheme configuration commands found in the file commands_filename, if provided; if not, dtn2admin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from dtn2admin with the 'h' or '?' commands at the prompt. The commands are documented in dtn2rc(5).
"},{"location":"man/bpv7/dtn2admin/#exit-status","title":"EXIT STATUS","text":"dtn2admin
Enter interactive \"dtn\" scheme configuration command entry mode.
dtn2admin host1.dtn2rc
Execute all configuration commands in host1.dtn2rc, then terminate immediately.
See dtn2rc(5) for details of the DTN scheme configuration commands.
"},{"location":"man/bpv7/dtn2admin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dtn2admin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the dtn2rc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to dtn2admin. Otherwise dtn2admin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
dtn2admin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
dtn2admin can't initialize routing database.
There is no SDR data store for dtn2admin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause dtn2admin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see dtn2rc(5) for details.
"},{"location":"man/bpv7/dtn2admin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dtn2admin/#see-also","title":"SEE ALSO","text":"dtn2rc(5)
"},{"location":"man/bpv7/dtn2adminep/","title":"NAME","text":"dtn2adminep - administrative endpoint task for the \"dtn\" scheme
"},{"location":"man/bpv7/dtn2adminep/#synopsis","title":"SYNOPSIS","text":"dtn2adminep
"},{"location":"man/bpv7/dtn2adminep/#description","title":"DESCRIPTION","text":"dtn2adminep is a background \"daemon\" task that receives and processes administrative bundles (minimally, all bundle status reports) that are sent to the \"dtn\"-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. dtn2adminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the \"dtn\" scheme.
dtn2adminep responds to bundle status reports by logging ASCII text messages describing the reported activity.
"},{"location":"man/bpv7/dtn2adminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtn2adminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dtn2adminep.
\"1\"
dtn2adminep was unable to attach to Bundle Protocol operations or was unable to load the \"dtn\" scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/dtn2adminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dtn2adminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtn2adminep can't attach to BP.
bpadmin has not yet initialized BP operations.
dtn2adminep can't load routing database.
dtn2admin has not yet initialized the \"dtn\" scheme.
dtn2adminep can't get admin EID.
dtn2admin has not yet initialized the \"dtn\" scheme.
dtn2adminep crashed.
An unrecoverable database error was encountered. dtn2adminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dtn2adminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), dtn2admin(1).
"},{"location":"man/bpv7/dtn2fw/","title":"NAME","text":"dtn2fw - bundle route computation task for the \"dtn\" scheme
"},{"location":"man/bpv7/dtn2fw/#synopsis","title":"SYNOPSIS","text":"dtn2fw
"},{"location":"man/bpv7/dtn2fw/#description","title":"DESCRIPTION","text":"dtn2fw is a background \"daemon\" task that pops bundles from the queue of bundle destined for \"dtn\"-scheme endpoints, computes proximate destinations for those bundles, and appends those bundles to the appropriate queues of bundles pending transmission to those computed proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is affected by static routes as configured by dtn2admin(1).
dtn2fw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. dtn2fw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the \"dtn\" scheme.
"},{"location":"man/bpv7/dtn2fw/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtn2fw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart dtn2fw.
\"1\"
dtn2fw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart dtn2fw.
No configuration files are needed.
"},{"location":"man/bpv7/dtn2fw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/dtn2fw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtn2fw can't attach to BP.
bpadmin has not yet initialized BP operations.
dtn2fw can't load routing database.
dtn2admin has not yet initialized the \"dtn\" scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. dtn2fw terminates.
'dtn' scheme is unknown.
The \"dtn\" scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. dtn2fw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. dtn2fw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/dtn2fw/#see-also","title":"SEE ALSO","text":"bpadmin(1), dtn2admin(1), bprc(5), dtn2rc(5).
"},{"location":"man/bpv7/dtn2rc/","title":"NAME","text":"dtn2rc - \"dtn\" scheme configuration commands file
"},{"location":"man/bpv7/dtn2rc/#description","title":"DESCRIPTION","text":"\"dtn\" scheme configuration commands are passed to dtn2admin either in a file of text lines or interactively at dtn2admin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
\"dtn\" scheme configuration commands establish static routing rules for forwarding bundles to nodes identified by \"dtn\"-scheme destination endpoints.
Static routes are expressed as plans in the \"dtn\"-scheme routing database. A plan that is established for a given node name associates a routing directive with the named node. Each directive is a string of one of two possible forms:
f endpoint_ID
...or...
x protocol_name/outduct_name
The former form signifies that the bundle is to be forwarded to the indicated endpoint, requiring that it be re-queued for processing by the forwarder for that endpoint (which might, but need not, be identified by another \"dtn\"-scheme endpoint ID). The latter form signifies that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
The node names cited in dtn2rc plans may be \"wild-carded\". That is, when the last character of a plan's node name is either '*' or '~' (these two wild-card characters are equivalent for this purpose), the plan applies to all nodes whose names are identical to the wild-carded node name up to the wild-card character. For example, a bundle whose destination EID is \"dtn://foghorn/x\" would be routed by plans citing the following node names: \"foghorn\", \"fogh*\", \"fog~\", \"*\". When multiple plans are all applicable to the same destination EID, the one citing the longest (i.e., most narrowly targeted) node name will be applied.
The formats and effects of the DTN scheme configuration commands are described below.
"},{"location":"man/bpv7/dtn2rc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 dtn2admin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a plan node_name directive [nominal_xmit_rate]
The add plan command. This command establishes a static route for the bundles destined for the node(s) identified by node_nameID. The nominal_xmit_rate is the assumed rate of transmission to this node in the absence of contact plan information. A nominal_data_rate of zero (the default) in the absence of contact plan information completely disables rate control.
Note that the plan commands consumed by dtn2admin are a simplified shortcut for submitting plan commands as consumed by bpadmin (see bprc(5)). The syntax of these commands is DIFFERENT from that of the more general and more powerful bpadmin commands.
c plan node_nameID [f endpoint_ID] [nominal_xmit_rate]
The change plan command. This command revises the \"via node\" and/or nominal_data_rate of the static route for the node(s) identified by node_nameID. To detach an outduct from the plan, use the \"planduct\" deletion command processed by bpadmin.
d plan node_nameID
The delete plan command. This command deletes the static route for the node(s) identified by node_nameID.
i plan node_nameID
This command will print information about the static route for the node(s) identified by node_nameID.
l plan
This command lists all static routes established in the DTN database for the local node.
a plan bbn2 f ipn:8.41
Declares a static route from the local node to node \"bbn2\". Any bundle destined for any endpoint whose node name is \"bbn2\" will be forwarded to endpoint \"ipn:8.41\".
a plan mitre* x ltp/6
Declares a static route from the local node to any node whose node name begins with \"mitre\". Any bundle destined for any endpoint whose node name begins with \"mitre1\" will be queued for transmission on LTP outduct 6.
dtn2admin(1)
"},{"location":"man/bpv7/hmackeys/","title":"NAME","text":"hmackeys - utility program for generating good HMAC-SHA1 keys
"},{"location":"man/bpv7/hmackeys/#synopsis","title":"SYNOPSIS","text":"hmackeys [ keynames_filename ]
"},{"location":"man/bpv7/hmackeys/#description","title":"DESCRIPTION","text":"hmackeys writes files containing randomized 160-bit key values suitable for use by HMAC-SHA1 in support of Bundle Authentication Block processing, Bundle Relay Service connections, or other functions for which symmetric hash computation is applicable. One file is written for each key name presented to hmackeys; the content of each file is 20 consecutive randomly selected 8-bit integer values, and the name given to each file is simply \"keyname.hmk\".
hmackeys operates in response to the key names found in the file keynames_filename, one name per file text line, if provided; if not, hmackeys prints a simple prompt (:) so that the user may type key names directly into standard input.
When the program is run in interactive mode, either enter 'q' or press ^C to terminate.
"},{"location":"man/bpv7/hmackeys/#exit-status","title":"EXIT STATUS","text":"hmackeys
Enter interactive HMAC/SHA1 key generation mode.
hmackeys host1.keynames
Create a key file for each key name in host1.keynames, then terminate immediately.
No other files are used in the operation of hmackeys.
"},{"location":"man/bpv7/hmackeys/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/hmackeys/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the logfile ion.log:
Can't open keynames file...
The keynames_filename specified in the command line doesn't exist.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/hmackeys/#see-also","title":"SEE ALSO","text":"brsscla(1), ionsecadmin(1)
"},{"location":"man/bpv7/imcadminep/","title":"NAME","text":"imcadminep - administrative endpoint task for the IMC (multicast) scheme
"},{"location":"man/bpv7/imcadminep/#synopsis","title":"SYNOPSIS","text":"imcadminep
"},{"location":"man/bpv7/imcadminep/#description","title":"DESCRIPTION","text":"imcadminep is a background \"daemon\" task that receives and processes administrative bundles (multicast group petitions) that are sent to the IMC-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. imcadminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IMC scheme.
imcadminep responds to multicast group \"join\" and \"leave\" petitions by managing entries in the node's database of multicast groups and their members.
"},{"location":"man/bpv7/imcadminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
imcadminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart imcadminep.
\"1\"
imcadminep was unable to attach to Bundle Protocol operations or was unable to load the IMC scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/imcadminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/imcadminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
imcadminep can't attach to BP.
bpadmin has not yet initialized BP operations.
imcadminep can't load routing database.
imcadmin has not yet initialized the IMC scheme.
imcadminep crashed.
An unrecoverable database error was encountered. imcadminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/imcadminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/imcfw/","title":"NAME","text":"imcfw - bundle route computation task for the IMC scheme
"},{"location":"man/bpv7/imcfw/#synopsis","title":"SYNOPSIS","text":"imcfw
"},{"location":"man/bpv7/imcfw/#description","title":"DESCRIPTION","text":"imcfw is a background \"daemon\" task that pops bundles from the queue of bundle destined for IMC-scheme (Interplanetary Multicast) endpoints, determines which \"relatives\" on the IMC multicast tree to forward the bundles to, and appends those bundles to the appropriate queues of bundles pending transmission to those proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is determined by multicast group membership as resulting from nodes' registration in multicast endpoints (accomplished simply by adding the appropriate endpoint as discussed in bprc(5).
imcfw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. imcfw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IMC scheme.
"},{"location":"man/bpv7/imcfw/#exit-status","title":"EXIT STATUS","text":"\"0\"
imcfw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart imcfw.
\"1\"
imcfw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart imcfw.
No configuration files are needed.
"},{"location":"man/bpv7/imcfw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/imcfw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
imcfw can't attach to BP.
bpadmin has not yet initialized BP operations.
imcfw can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. imcfw terminates.
'imc' scheme is unknown.
The IMC scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. imcfw terminates.
Can't exclude sender from routes.
An unrecoverable database error was encountered. imcfw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. imcfw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/imcfw/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/ipnadmin/","title":"NAME","text":"ipnadmin - Interplanetary Internet (IPN) scheme administration interface
"},{"location":"man/bpv7/ipnadmin/#synopsis","title":"SYNOPSIS","text":"ipnadmin [ commands_filename ]
"},{"location":"man/bpv7/ipnadmin/#description","title":"DESCRIPTION","text":"ipnadmin configures the local ION node's routing of bundles to endpoints whose IDs conform to the ipn endpoint ID scheme. Every endpoint ID in the ipn scheme is a string of the form \"ipn:node_number.service_number\" where node_number is a CBHE \"node number\" and service_number identifies a specific application processing point. When service_number is zero, the endpoint ID constitutes a node ID. All endpoint IDs formed in the ipn scheme identify singleton endpoints.
ipnadmin operates in response to IPN scheme configuration commands found in the file commands_filename, if provided; if not, ipnadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from ipnadmin with the 'h' or '?' commands at the prompt. The commands are documented in ipnrc(5).
"},{"location":"man/bpv7/ipnadmin/#exit-status","title":"EXIT STATUS","text":"ipnadmin
Enter interactive IPN scheme configuration command entry mode.
ipnadmin host1.ipnrc
Execute all configuration commands in host1.ipnrc, then terminate immediately.
See ipnrc(5) for details of the IPN scheme configuration commands.
"},{"location":"man/bpv7/ipnadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ipnadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ipnrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ipnadmin. Otherwise ipnadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ipnadmin can't attach to BP.
Bundle Protocol has not been initialized on this computer. You need to run bpadmin(1) first.
ipnadmin can't initialize routing database.
There is no SDR data store for ipnadmin to use. Please run ionadmin(1) to start the local ION node.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ipnadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see ipnrc(5) for details.
"},{"location":"man/bpv7/ipnadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ipnadmin/#see-also","title":"SEE ALSO","text":"ipnrc(5)
"},{"location":"man/bpv7/ipnadminep/","title":"NAME","text":"ipnadminep - administrative endpoint task for the IPN scheme
"},{"location":"man/bpv7/ipnadminep/#synopsis","title":"SYNOPSIS","text":"ipnadminep
"},{"location":"man/bpv7/ipnadminep/#description","title":"DESCRIPTION","text":"ipnadminep is a background \"daemon\" task that receives and processes administrative bundles (nominally, all bundle status reports) that are sent to the IPN-scheme administrative endpoint on the local ION node, if and only if such an endpoint was established by bpadmin. It is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. ipnadminep can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IPN scheme.
ipnadminep responds to bundle status reports by logging ASCII text messages describing the reported activity.
"},{"location":"man/bpv7/ipnadminep/#exit-status","title":"EXIT STATUS","text":"\"0\"
ipnadminep terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ipnadminep.
\"1\"
ipnadminep was unable to attach to Bundle Protocol operations or was unable to load the IPN scheme database, probably because bpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bpv7/ipnadminep/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ipnadminep/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ipnadminep can't attach to BP.
bpadmin has not yet initialized BP operations.
ipnadminep can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
ipnadminep crashed.
An unrecoverable database error was encountered. ipnadminep terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ipnadminep/#see-also","title":"SEE ALSO","text":"bpadmin(1), ipnadmin(1), bprc(5)
"},{"location":"man/bpv7/ipnd/","title":"NAME","text":"ipnd - ION IPND module
"},{"location":"man/bpv7/ipnd/#description","title":"DESCRIPTION","text":"The ipnd daemon is the ION implementation of DTN IP Neighbor Discovery. This module allows the node to send and receive beacon messages using unicast, multicast or broadcast IP addresses. Beacons are used for the discovery of neighbors and may be used to advertise services that are present and available on nodes, such as routing algorithms or CLAs.
ION IPND module is configured using a *.rc configuration file. The name of the configuration file must be passed as the sole command-line argument to ipnd when the daemon is started. Commands are interpreted line by line, with exactly one command per line. The formats and effects of the ION ipnd management commands are described below.
"},{"location":"man/bpv7/ipnd/#usage","title":"USAGE","text":"ipnd config_file_name
"},{"location":"man/bpv7/ipnd/#commands","title":"COMMANDS","text":"1
The initialize command. This must be the first command.
#
Comment line. Lines beginning with # are not interpreted.
e { 1 | 0 }
Echo control. Setting echo to 1 causes all output printed by ipnd to be logged into ion.log. Setting echo to 0 disables this behavior. Default is 1.
m eid eid
Local eid. This command sets the advertised BP endpoint ID by which the node will identify itself in beacon messages.
m announce period { 1 | 0 }
Announce period control. Setting to 1 causes all beacons messages sent to contain beacon period. Setting to 0 disables this behavior. Default is 1.
m announce eid { 1 | 0 }
Announce eid control. Setting to 1 causes all beacons messages sent to contain source eid. Setting to 0 disables this behavior. This should be always set to 1. Default is 1.
m interval unicast interval
Unicast interval. This command sets the beacon messages period on unicast transmissions. Time interval is expressed in seconds. Default is 5.
m interval multicast interval
Multicast interval. This command sets the beacon messages period on multicast transmissions. Time interval is expressed in seconds. Default is 7.
m interval broadcast interval
Broadcastcast interval. This command sets the beacon messages period on broadcast transmissions. Time interval is expressed in seconds. Default is 11.
m multicast ttl ttl
Multicast ttl. This command sets the multicast outgoing beacon messages' time to live, in seconds. Default is 255.
m svcdef id name child_name:child_type ...
Service definition. This command specifies definitions of \"services\", which are dynamically defined beacon message data structures indicating the capabilities of the beacon message sender. id is a service-identifying number in the range 128-255. name is the name of the service type that is being defined. The definition of the structure of the service is a sequence of elements, each of which is a name:type pair. Each child_type must be the name of a standard or previously defined service type. Infinite recursion is supported.
a svcadv name child_name:child_value ...
Service advertising command. This command defines which services will be advertised and with which values. All types of formats for values are supported (e.g. 999, 0345 (octal), 0x999 (hex), -1e-9, 0.32, etc.). For a service that contains only a single element, it is not necessary to provide that element's name. E.g. it is enough to write Booleans:true instead of Booleans:BooleanValues:B:true, as BooleanValues is the only child of Booleans and B is the only child of BooleanValues.
a listen IP_address
Listen socket specification command. This command asserts, in the form IP_address, the IP address of the socket at which the IPND daemon is to listen for incoming beacons; a default port number is used. The address can be an unicast, a multicast or a broadcast address. If a multicast address is provided all the configured unicast addresses will listen for multicast packets in that group. If a broadcast address is provided all the unicast addresses will listen for broadcasted packets.
a destination destination_socket_spec
Destination socket specification command. This command asserts the specification for a socket to which the IPND daemon is to send beacons. It can be an unicast, a multicast or a broadcast address.
s
The start command. This command starts the IPND daemon for the local ION node.
m scvdef 128 FooRouter Seed:SeedVal BaseWeight:WeightVal RootHash:bytes
Defines a new service called FooRouter comprising 3 elements. SeedVal and WeightVal are user defined services that must be already defined.
m svcdef 129 SeedVal Value:fixed16
m svcdef 130 WeightVal Value:fixed16
m svcdef 128 FooRouter Seed:SeedVal BaseWeight:WeightVal RootHash:bytes
m svcdef 150 FixedValuesList F16:fixed16 F32:fixed32 F64:fixed64
m svcdef 131 VariableValuesList U64:uint64 S64:sint64
m svcdef 132 BooleanValues B:boolean
m svcdef 133 FloatValuesList F:float D:double
m svcdef 135 IntegersList FixedValues:FixedValuesList VariableValues:VariableValuesList
m svcdef 136 NumbersList Integers:IntegersList Floats:FloatValuesList
m svcdef 140 HugeService CLAv4:CLA-TCP-v4 Booleans:BooleanValues Numbers:NumbersList FR:FooRouter
a svcadv HugeService CLAv4:IP:10.1.0.10 CLAv4:Port:4444 Booleans:true FR:Seed:0x5432 FR:BaseWeight:13 FR:RootHash:BEEF Numbers:Integers:FixedValues:F16:0x16 Numbers:Integers:FixedValues:F32:0x32 Numbers:Integers:FixedValues:F64:0x1234567890ABCDEF Numbers:Floats:F:0.32 Numbers:Floats:D:-1e-6 Numbers:Integers:VariableValues:U64:18446744073704783380 Numbers:Integers:VariableValues:S64:-4611686018422619668
This shows how to define multiple nested services and how to advertise them.
"},{"location":"man/bpv7/ipnd/#see-also","title":"SEE ALSO","text":"ion(3)
"},{"location":"man/bpv7/ipnfw/","title":"NAME","text":"ipnfw - bundle route computation task for the IPN scheme
"},{"location":"man/bpv7/ipnfw/#synopsis","title":"SYNOPSIS","text":"ipnfw
"},{"location":"man/bpv7/ipnfw/#description","title":"DESCRIPTION","text":"ipnfw is a background \"daemon\" task that pops bundles from the queue of bundle destined for IPN-scheme endpoints, computes proximate destinations for those bundles, and appends those bundles to the appropriate queues of bundles pending transmission to those computed proximate destinations.
For each possible proximate destination (that is, neighboring node) there is a separate queue for each possible level of bundle priority: 0, 1, 2. Each outbound bundle is appended to the queue matching the bundle's designated priority.
Proximate destination computation is affected by static and default routes as configured by ipnadmin(1) and by contact graphs as managed by ionadmin(1) and rfxclock(1).
ipnfw is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of Bundle Protocol on the local ION node, and it is terminated by bpadmin in response to an 'x' (STOP) command. ipnfw can also be spawned and terminated in response to START and STOP commands that pertain specifically to the IPN scheme.
"},{"location":"man/bpv7/ipnfw/#exit-status","title":"EXIT STATUS","text":"\"0\"
ipnfw terminated, for reasons noted in the ion.log log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ipnfw.
\"1\"
ipnfw could not commence operations, for reasons noted in the ion.log log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart ipnfw.
No configuration files are needed.
"},{"location":"man/bpv7/ipnfw/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ipnfw/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ipnfw can't attach to BP.
bpadmin has not yet initialized BP operations.
ipnfw can't load routing database.
ipnadmin has not yet initialized the IPN scheme.
Can't create lists for route computation.
An unrecoverable database error was encountered. ipnfw terminates.
'ipn' scheme is unknown.
The IPN scheme was not added when bpadmin initialized BP operations. Use bpadmin to add and start the scheme.
Can't take forwarder semaphore.
ION system error. ipnfw terminates.
Can't exclude sender from routes.
An unrecoverable database error was encountered. ipnfw terminates.
Can't enqueue bundle.
An unrecoverable database error was encountered. ipnfw terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ipnfw/#see-also","title":"SEE ALSO","text":"bpadmin(1), ipnadmin(1), bprc(5), ipnrc(5)
"},{"location":"man/bpv7/ipnrc/","title":"NAME","text":"ipnrc - IPN scheme configuration commands file
"},{"location":"man/bpv7/ipnrc/#description","title":"DESCRIPTION","text":"IPN scheme configuration commands are passed to ipnadmin either in a file of text lines or interactively at ipnadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line.
IPN scheme configuration commands (a) establish egress plans for direct transmission to neighboring nodes that are members of endpoints identified in the \"ipn\" URI scheme and (b) establish static default routing rules for forwarding bundles to specified destination nodes.
The egress plan established for a given node associates a duct expression with that node. Each duct expression is a string of the form \"protocol_name/outduct_name\" signifying that the bundle is to be queued for transmission via the indicated convergence layer protocol outduct.
Note that egress plans must be established for all neighboring nodes, regardless of whether or not contact graph routing is used for computing dynamic routes to distant nodes. This is by definition: if there isn't an egress plan to a node, it can't be considered a neighbor.
Static default routes are declared as exits in the ipn-scheme routing database. An exit is a range of node numbers identifying a set of nodes for which defined default routing behavior is established. Whenever a bundle is to be forwarded to a node whose number is in the exit's node number range and it has not been possible to compute a dynamic route to that node from the contact schedules that have been provided to the local node and that node is not a neighbor to which the bundle can be directly transmitted, BP will forward the bundle to the gateway node associated with this exit. The gateway node for any exit is identified by an endpoint ID, which might or might not be an ipn-scheme EID; regardless, directing a bundle to the gateway for an exit causes the bundle to be re-forwarded to that intermediate destination endpoint. Multiple exits may encompass the same node number, in which case the gateway associated with the most restrictive exit (the one with the smallest range) is always selected.
Note that \"exits\" were termed \"groups\" in earlier versions of ION. The term \"exit\" has been adopted instead, to minimize any possible confusion with multicast groups. To protect backward compatibility, the keyword \"group\" continues to be accepted by ipnadmin as an alias for the new keyword \"exit\", but the older terminology is deprecated.
Routing and class-of-service overrides may also be managed:
A routing override declares a neighboring node to which all bundles must be forwarded that meet specified criteria. This override is strictly local, affecting only forwarding from the local node, and it is applied before any route computed by CGR or IRR is considered.
A class-of-service override declares the class of service (priority and ordinal and [optionally] quality-of-service flags) that will condition - in terms of order and outduct selection - the forwarding of all bundles that meet specified criteria. Again this override is strictly local, affecting only forwarding from the local node.
The formats and effects of the IPN scheme configuration commands are described below.
"},{"location":"man/bpv7/ipnrc/#general-commands","title":"GENERAL COMMANDS","text":"?
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 ipnadmin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a plan node_nbr duct_expression [nominal_data_rate]
The add plan command. This command establishes an egress plan for the bundles that must be transmitted to the neighboring node identified by node_nbr. The nominal_data_rate is the assumed rate of transmission to this node in the absence of contact plan information. A nominal_data_rate of zero (the default) in the absence of contact plan information completely disables rate control.
Note that the plan commands consumed by ipnadmin are a simplified shortcut for submitting plan commands as consumed by bpadmin (see bprc(5)). The syntax of these commands is DIFFERENT from that of the more general and more powerful bpadmin commands.
c plan node_nbr nominal_data_rate
The change plan command. This command changes the nominal data rate for the indicated plan.
d plan node_nbr
The delete plan command. This command deletes the egress plan for the node identified by node_nbr.
i plan node_nbr
This command will print information about the egress plan for the node identified by node_nbr.
l plan
This command lists all egress plans established in the IPN database for the local node.
a exit first_node_nbr last_node_nbr gateway_endpoint_ID
The add exit command. This command establishes an \"exit\" for static default routing as described above.
c exit first_node_nbr last_node_nbr gateway_endpoint_ID
The change exit command. This command changes the gateway node number for the exit identified by first_node_nbr and last_node_nbr .
d exit first_node_nbr last_node_nbr
The delete exit command. This command deletes the exit identified by first_node_nbr and last_node_nbr.
i exit first_node_nbr last_node_nbr
This command will print information (the gateway endpoint ID) about the exit identified by first_node_nbr and last_node_nbr.
l exit
This command lists all exits defined in the IPN database for the local node.
a rtovrd data_label dest_node_nbr source_node_nbr neighbor
The add rtovrd command. This command cause bundles characterized by data_label, dest_node_nbr (\"all other destinations\" if this node number is zero) and source_node_nbr (\"all other sources\" if this node number is zero) to be forwarded to neighbor. If neighbor is zero, the override will be \"learned\" by ION: the neighbor selected for this bundle, by whatever means, becomes the override for all subsequent matching bundles.
c rtovrd data_label dest_node_nbr source_node_nbr neighbor
The change rtovrd command. This command changes the override neighbor for the override identified by data_label, dest_node_nbr, and source_node_nbr. To cause ION to forget the override, use -1 as neighbor.
a cosovrd data_label dest_node_nbr source_node_nbr priority ordinal [qos_flags]
The add cosovrd command. This command cause bundles characterized by data_label, dest_node_nbr (\"all other destinations\" if this node number is zero) and source_node_nbr (\"all other sources\" if this node number is zero) to have their effective class of service (priority and ordinal and, optionally, additional quality-of-service flags) changed as noted.
c cosovrd data_label dest_node_nbr source_node_nbr priority ordinal [qos_flags]
The change cosovrd command. This command changes the effective class of service (priority and ordinal and, optionally, additional quality-of-service flags) for the override identified by data_label, dest_node_nbr, and source_node_nbr. To cause ION to forget the override, use -1 as priority.
d ovrd data_label dest_node_nbr source_node_nbr
The delete override command. This command deletes all overrides identified by data_label, dest_node_nbr, and source_node_nbr.
i ovrd data_label dest_node_nbr source_node_nbr
This command will print information for all overrides identified by data_label, dest_node_nbr, and source_node_nbr.
l ovrd
This command lists all overrides defined in the IPN database for the local node.
a plan 18 ltp/18
Declares the egress plan to use for transmission from the local node to neighboring node 18. By default, any bundle for which the computed \"next hop\" node is node 18 will be queued for transmission on LTP outduct 18.
a exit 1 999 dtn://stargate
Declares a default route for bundles destined for all nodes whose numbers are in the range 1 through 999 inclusive: absent any other routing decision, such bundles are to be forwarded to \"dtn://stargate\".
ipnadmin(1)
"},{"location":"man/bpv7/lgagent/","title":"NAME","text":"lgagent - ION Load/Go remote agent program
"},{"location":"man/bpv7/lgagent/#synopsis","title":"SYNOPSIS","text":"lgagent own_endpoint_ID
"},{"location":"man/bpv7/lgagent/#description","title":"DESCRIPTION","text":"ION Load/Go is a system for management of an ION-based network, enabling the execution of ION administrative programs at remote nodes. The system comprises two programs, lgsend and lgagent.
The lgagent task on a given node opens the indicated ION endpoint for bundle reception, receives the extracted payloads of Load/Go bundles sent to it by lgsend as run on one or more remote nodes, and processes those payloads, which are the text of Load/Go source files.
Load/Go source file content is limited to newline-terminated lines of ASCII characters. More specifically, the text of any Load/Go source file is a sequence of line sets of two types: file capsules and directives. Any Load/Go source file may contain any number of file capsules and any number of directives, freely intermingled in any order, but the typical structure of a Load/Go source file is simply a single file capsule followed by a single directive.
When lgagent identifies a file capsule, it copies all of the capsule's text lines to a new file that it creates in the current working directory. When lgagent identifies a directive, it executes the directive by passing the text of the directive to the pseudoshell() function (see platform(3)). lgagent processes the line sets of a Load/Go source file in the order in which they appear in the file, so the text of a directive may reference a file that was created as the result of processing a prior file capsule in the same source file.
"},{"location":"man/bpv7/lgagent/#exit-status","title":"EXIT STATUS","text":"\"0\"
Load/Go remote agent processing has terminated.
lgfile contains the Load/Go file capsules and directives that are to be processed.
"},{"location":"man/bpv7/lgagent/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/lgagent/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
lgagent: can't attach to BP.
Bundle Protocol is not running on this computer. Run bpadmin(1) to start BP.
lgagent: can't open own endpoint.
own_endpoint_ID is not a declared endpoint on the local ION node. Run bpadmin(1) to add it.
lgagent: bundle reception failed.
ION system problem. Investigate and correct before restarting.
lgagent cannot continue.
lgagent processing problem. See earlier diagnostic messages for details. Investigate and correct before restarting.
lgagent: no space for bundle content.
ION system problem: have exhausted available SDR data store reserves.
lgagent: can't receive bundle content.
ION system problem: have exhausted available SDR data store reserves.
lgagent: can't handle bundle delivery.
ION system problem. Investigate and correct before restarting.
lgagent: pseudoshell failed.
Error in directive line, usually an attempt to execute a non-existent administration program (e.g., a misspelled program name). Terminates processing of source file content.
A variety of other diagnostics noting source file parsing problems may also be reported. These errors are non-fatal but they terminate the processing of the source file content from the most recently received bundle.
"},{"location":"man/bpv7/lgagent/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/lgagent/#see-also","title":"SEE ALSO","text":"lgsend(1), lgfile(5)
"},{"location":"man/bpv7/lgfile/","title":"NAME","text":"lgfile - ION Load/Go source file
"},{"location":"man/bpv7/lgfile/#description","title":"DESCRIPTION","text":"The ION Load/Go system enables the execution of ION administrative programs at remote nodes:
The lgsend program reads a Load/Go source file from a local file system, encapsulates the text of that source file in a bundle, and sends the bundle to a designated DTN endpoint on the remote node.
An lgagent task running on the remote node, which has opened that DTN endpoint for bundle reception, receives the extracted payload of the bundle -- the text of the Load/Go source file -- and processes it.
Load/Go source file content is limited to newline-terminated lines of ASCII characters. More specifically, the text of any Load/Go source file is a sequence of line sets of two types: file capsules and directives. Any Load/Go source file may contain any number of file capsules and any number of directives, freely intermingled in any order, but the typical structure of a Load/Go source file is simply a single file capsule followed by a single directive.
Each file capsule is structured as a single start-of-capsule line, followed by zero or more capsule text lines, followed by a single end-of-capsule line. Each start-of-capsule line is of this form:
[file_name
Each capsule text line can be any line of ASCII text that does not begin with an opening ([) or closing (]) bracket character.
A text line that begins with a closing bracket character (]) is interpreted as an end-of-capsule line.
A directive is any line of text that is not one of the lines of a file capsule and that is of this form:
!directive_text
When lgagent identifies a file capsule, it copies all of the capsule's text lines to a new file named file_name that it creates in the current working directory. When lgagent identifies a directive, it executes the directive by passing directive_text to the pseudoshell() function (see platform(3)). lgagent processes the line sets of a Load/Go source file in the order in which they appear in the file, so the directive_text of a directive may reference a file that was created as the result of processing a prior file capsule line set in the same source file.
Note that lgfile directives are passed to pseudoshell(), which on a VxWorks platform will always spawn a new task; the first argument in directive_text must be a symbol that VxWorks can resolve to a function, not a shell command. Also note that the arguments in directive_text will be actual task arguments, not shell command-line arguments, so they should never be enclosed in double-quote characters (\"). However, any argument that contains embedded whitespace must be enclosed in single-quote characters (') so that pseudoshell() can parse it correctly.
"},{"location":"man/bpv7/lgfile/#examples","title":"EXAMPLES","text":"Presenting the following lines of source file text to lgsend:
[cmd33.bprc
x protocol ltp
]
!bpadmin cmd33.bprc
should cause the receiving node to halt the operation of the LTP convergence-layer protocol.
"},{"location":"man/bpv7/lgfile/#see-also","title":"SEE ALSO","text":"lgsend(1), lgagent(1), platform(3)
"},{"location":"man/bpv7/lgsend/","title":"NAME","text":"lgsend - ION Load/Go command program
"},{"location":"man/bpv7/lgsend/#synopsis","title":"SYNOPSIS","text":"lgsend command_file_name own_endpoint_ID destination_endpoint_ID
"},{"location":"man/bpv7/lgsend/#description","title":"DESCRIPTION","text":"ION Load/Go is a system for management of an ION-based network, enabling the execution of ION administrative programs at remote nodes. The system comprises two programs, lgsend and lgagent.
The lgsend program reads a Load/Go source file from a local file system, encapsulates the text of that source file in a bundle, and sends the bundle to an lgagent task that is waiting for data at a designated DTN endpoint on the remote node.
To do so, it first reads all lines of the Load/Go source file identified by command_file_name into a temporary buffer in ION's SDR data store, concatenating the lines of the file and retaining all newline characters. Then it invokes the bp_send() function to create and send a bundle whose payload is this temporary buffer, whose destination is destination_endpoint_ID, and whose source endpoint ID is own_endpoint_ID. Then it terminates.
"},{"location":"man/bpv7/lgsend/#exit-status","title":"EXIT STATUS","text":"\"0\"
Load/Go file transmission succeeded.
\"1\"
Load/Go file transmission failed. Examine ion.log to determine the cause of the failure, then re-run.
lgfile contains the Load/Go file capsules and directive that are to be sent to the remote node.
"},{"location":"man/bpv7/lgsend/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/lgsend/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
lgsend: can't attach to BP.
Bundle Protocol is not running on this computer. Run bpadmin(1) to start BP.
lgsend: can't open own endpoint.
own_endpoint_ID is not a declared endpoint on the local ION node. Run bpadmin(1) to add it.
lgsend: can't open file of LG commands: error description
command_file_name doesn't identify a file that can be opened. Correct spelling of file name or file's access permissions.
lgsend: can't get size of LG command file: error description
Operating system problem. Investigate and correct before rerunning.
lgsend: LG cmd file size > 64000.
Load/Go command file is too large. Split it into multiple files if possible.
lgsend: no space for application data unit.
ION system problem: have exhausted available SDR data store reserves.
lgsend: fgets failed: error description
Operating system problem. Investigate and correct before rerunning.
lgsend: can't create application data unit.
ION system problem: have exhausted available SDR data store reserves.
lgsend: can't send bundle.
ION system problem. Investigate and correct before rerunning.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/lgsend/#see-also","title":"SEE ALSO","text":"lgagent(1), lgfile(5)
"},{"location":"man/bpv7/ltpcli/","title":"NAME","text":"ltpcli - LTP-based BP convergence layer input task
"},{"location":"man/bpv7/ltpcli/#synopsis","title":"SYNOPSIS","text":"ltpcli local_node_nbr
"},{"location":"man/bpv7/ltpcli/#description","title":"DESCRIPTION","text":"ltpcli is a background \"daemon\" task that receives LTP data transmission blocks, extracts bundles from the received blocks, and passes them to the bundle protocol agent on the local ION node.
ltpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"ltp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. ltpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the LTP convergence layer protocol.
"},{"location":"man/bpv7/ltpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart ltpcli.
\"1\"
ltpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart ltpcli.
No configuration files are needed.
"},{"location":"man/bpv7/ltpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ltpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such ltp duct.
No LTP induct matching local_node_nbr has been added to the BP database. Use bpadmin to stop the LTP convergence-layer protocol, add the induct, and then restart the LTP protocol.
CLI task is already started for this duct.
Redundant initiation of ltpcli.
ltpcli can't initialize LTP.
ltpadmin has not yet initialized LTP operations.
ltpcli can't open client access.
Another task has already opened the client service for BP over LTP.
ltpcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart LTP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ltpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), ltpadmin(1), ltprc(5), ltpclo(1)
"},{"location":"man/bpv7/ltpclo/","title":"NAME","text":"ltpclo - LTP-based BP convergence layer adapter output task
"},{"location":"man/bpv7/ltpclo/#synopsis","title":"SYNOPSIS","text":"ltpclo remote_node_nbr
"},{"location":"man/bpv7/ltpclo/#description","title":"DESCRIPTION","text":"ltpclo is a background \"daemon\" task that extracts bundles from the queues of segments ready for transmission via LTP to the remote bundle protocol agent identified by remote_node_nbr and passes them to the local LTP engine for aggregation, segmentation, and transmission to the remote node.
ltpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. ltpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the LTP convergence layer protocol.
"},{"location":"man/bpv7/ltpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSC protocol.
\"1\"
ltpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSC protocol.
No configuration files are needed.
"},{"location":"man/bpv7/ltpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/ltpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such ltp duct.
No LTP outduct with duct name matching remote_node_nbr has been added to the BP database. Use bpadmin to stop the LTP convergence-layer protocol, add the outduct, and then restart the LTP protocol.
CLO task is already started for this duct.
Redundant initiation of ltpclo.
ltpclo can't initialize LTP.
ltpadmin has not yet initialized LTP operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/ltpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), ltpadmin(1), ltprc(5), ltpcli(1)
"},{"location":"man/bpv7/stcpcli/","title":"NAME","text":"sstcpcli - DTN simple TCP convergence layer input task
"},{"location":"man/bpv7/stcpcli/#synopsis","title":"SYNOPSIS","text":"stcpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/stcpcli/#description","title":"DESCRIPTION","text":"stcpcli is a background \"daemon\" task comprising 1 + N threads: one that handles TCP connections from remote stcpclo tasks, spawning sockets for data reception from those tasks, plus one input thread for each spawned socket to handle data reception over that socket.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 4556.
Each reception thread receives bundles over the associated connected socket. Each bundle received on the connection is preceded by a 32-bit unsigned integer in network byte order indicating the length of the bundle. The received bundles are passed to the bundle protocol agent on the local ION node.
stcpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"stcp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. stcpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the STCP convergence layer protocol.
"},{"location":"man/bpv7/stcpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
stcpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart stcpcli.
\"1\"
stcpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart stcpcli.
No configuration files are needed.
"},{"location":"man/bpv7/stcpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/stcpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
stcpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such stcp duct.
No STCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the STCP convergence-layer protocol, add the induct, and then restart the STCP protocol.
CLI task is already started for this duct.
Redundant initiation of stcpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart STCP.
Can't open TCP socket
Operating system error. Check errtext, correct problem, and restart STCP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart STCP.
stcpcli can't create access thread
Operating system error. Check errtext, correct problem, and restart STCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/stcpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), stcpclo(1)
"},{"location":"man/bpv7/stcpclo/","title":"NAME","text":"stcpclo - DTN simple TCP convergence layer adapter output task
"},{"location":"man/bpv7/stcpclo/#synopsis","title":"SYNOPSIS","text":"stcpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv7/stcpclo/#description","title":"DESCRIPTION","text":"stcpclo is a background \"daemon\" task that connects to a remote node's TCP socket at remote_hostname and remote_port_nbr. It then begins extracting bundles from the queues of bundles ready for transmission via TCP to this remote bundle protocol agent and transmitting those bundles over the connected socket to that node. Each transmitted bundle is preceded by a 32-bit integer in network byte order indicating the length of the bundle.
If not specified, remote_port_nbr defaults to 4556.
stcpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. stcpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the STCP convergence layer protocol.
"},{"location":"man/bpv7/stcpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
stcpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the STCP protocol.
\"1\"
stcpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the STCP protocol.
No configuration files are needed.
"},{"location":"man/bpv7/stcpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/stcpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
stcpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such stcp duct.
No STCP outduct with duct name matching remote_hostname and remote_port_nbr has been added to the BP database. Use bpadmin to stop the STCP convergence-layer protocol, add the outduct, and then restart the STCP protocol.
CLO task is already started for this duct.
Redundant initiation of stcpclo.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart STCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/stcpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), stcpcli(1)
"},{"location":"man/bpv7/tcpcli/","title":"NAME","text":"tcpcli - DTN TCPCL-compliant convergence layer input task
"},{"location":"man/bpv7/tcpcli/#synopsis","title":"SYNOPSIS","text":"tcpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/tcpcli/#description","title":"DESCRIPTION","text":"tcpcli is a background \"daemon\" task comprising 3 + 2*N threads: an executive thread; a clock thread that periodically attempts to connect to remote TCPCL entities as identified by the tcp outducts enumerated in the bprc(5) file (each of which must specify the hostname[:port_nbr] to connect to); a thread that handles TCP connections from remote TCPCL entities, spawning sockets for data reception from those tasks; plus one input thread and one output thread for each connection, to handle data reception and transmission over that socket.
The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr and spawns reception threads. The default value for local_port_nbr, if omitted, is 4556.
Each time a connection is established, the entities will first exchange contact headers, because connection parameters need to be negotiated. tcpcli records the acknowledgement flags, reactive fragmentation flag, and negative acknowledgements flag in the contact header it receives from its peer TCPCL entity.
Each reception thread receives bundles over the associated connected socket. Each bundle received on the connection is preceded by message type, fragmentation flags, and size represented as an SDNV. The received bundles are passed to the bundle protocol agent on the local ION node.
Similarly, each transmission thread obtains outbound bundles from the local ION node, encapsulates them as noted above, and transmits them over the associated connected socket.
tcpcli is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"tcp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. tcpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the TCP convergence layer protocol.
"},{"location":"man/bpv7/tcpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart tcpcli.
\"1\"
tcpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart tcpcli.
No configuration files are needed.
"},{"location":"man/bpv7/tcpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/tcpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such tcp duct.
No TCP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the TCP convergence-layer protocol, add the induct, and then restart the TCP protocol.
CLI task is already started for this duct.
Redundant initiation of tcpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart TCP.
Can't open TCP socket
Operating system error. Check errtext, correct problem, and restart TCP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart TCP.
tcpcli can't create access thread
Operating system error. Check errtext, correct problem, and restart TCP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/tcpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5)
"},{"location":"man/bpv7/tcpclo/","title":"NAME","text":"tcpclo - TCPCL-compliant convergence layer adapter output task [DEPRECATED]
"},{"location":"man/bpv7/tcpclo/#synopsis","title":"SYNOPSIS","text":"tcpclo
"},{"location":"man/bpv7/tcpclo/#description","title":"DESCRIPTION","text":"tcpclo is deprecated. The outducts for the \"tcp\" convergence-layer adapter are now drained by threads managed within tcpcli.
"},{"location":"man/bpv7/tcpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpclo terminated normally.
No configuration files are needed.
"},{"location":"man/bpv7/tcpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/tcpclo/#diagnostics","title":"DIAGNOSTICS","text":"No diagnostics apply.
"},{"location":"man/bpv7/tcpclo/#see-also","title":"SEE ALSO","text":"tcpcli(1)
"},{"location":"man/bpv7/udpcli/","title":"NAME","text":"udpcli - UDP-based BP convergence layer input task
"},{"location":"man/bpv7/udpcli/#synopsis","title":"SYNOPSIS","text":"udpcli local_hostname[:local_port_nbr]
"},{"location":"man/bpv7/udpcli/#description","title":"DESCRIPTION","text":"udpcli is a background \"daemon\" task that receives UDP datagrams via a UDP socket bound to local_hostname and local_port_nbr, extracts bundles from those datagrams, and passes them to the bundle protocol agent on the local ION node.
If not specified, port number defaults to 4556.
The convergence layer input task is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol; the text of the command that is used to spawn the task must be provided at the time the \"udp\" convergence layer protocol is added to the BP database. The convergence layer input task is terminated by bpadmin in response to an 'x' (STOP) command. udpcli can also be spawned and terminated in response to START and STOP commands that pertain specifically to the UDP convergence layer protocol.
"},{"location":"man/bpv7/udpcli/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpcli terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart udpcli.
\"1\"
udpcli terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart udpcli.
No configuration files are needed.
"},{"location":"man/bpv7/udpcli/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/udpcli/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpcli can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No such udp duct.
No UDP induct matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the UDP convergence-layer protocol, add the induct, and then restart the UDP protocol.
CLI task is already started for this duct.
Redundant initiation of udpcli.
Can't get IP address for host
Operating system error. Check errtext, correct problem, and restart UDP.
Can't open UDP socket
Operating system error. Check errtext, correct problem, and restart UDP.
Can't initialize socket
Operating system error. Check errtext, correct problem, and restart UDP.
udpcli can't create receiver thread
Operating system error. Check errtext, correct problem, and restart UDP.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/udpcli/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), udpclo(1)
"},{"location":"man/bpv7/udpclo/","title":"NAME","text":"udpclo - UDP-based BP convergence layer output task
"},{"location":"man/bpv7/udpclo/#synopsis","title":"SYNOPSIS","text":"udpclo remote_hostname[:remote_port_nbr]
"},{"location":"man/bpv7/udpclo/#description","title":"DESCRIPTION","text":"udpclo is a background \"daemon\" task that extracts bundles from the queues of bundles ready for transmission via UDP to a remote node's UDP socket at remote_hostname and remote_port_nbr, encapsulates those bundles in UDP datagrams, and sends those datagrams to that remote UDP socket.
udpclo is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and it is terminated by bpadmin in response to an 'x' (STOP) command. udpclo can also be spawned and terminated in response to START and STOP commands that pertain specifically to the UDP convergence layer protocol.
"},{"location":"man/bpv7/udpclo/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpclo terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart udpclo.
\"1\"
udpclo terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart udpclo.
No configuration files are needed.
"},{"location":"man/bpv7/udpclo/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bpv7/udpclo/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpclo can't attach to BP.
bpadmin has not yet initialized Bundle Protocol operations.
No memory for UDP buffer in udpclo.
ION system error. Check errtext, correct problem, and restart UDP.
No such udp duct.
No UDP outduct with duct name remote_hostname[:<remote_port_nbr>] has been added to the BP database. Use bpadmin to stop the UDP convergence-layer protocol, add the outduct, and then restart the UDP protocol.
CLO task is already started for this engine.
Redundant initiation of udpclo.
CLO can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udpclo.
CLO write() error on socket
Operating system error. Check errtext, correct problem, and restart udpclo.
Bundle is too big for UDP CLA.
Configuration error: bundles that are too large for UDP transmission (i.e., larger than 65535 bytes) are being enqueued for udpclo. Change routing.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bpv7/udpclo/#see-also","title":"SEE ALSO","text":"bpadmin(1), bprc(5), udpcli(1)
"},{"location":"man/bss/","title":"Index of Man Pages","text":"bss - Bundle Streaming Service library
"},{"location":"man/bss/bss/#synopsis","title":"SYNOPSIS","text":"#include \"bss.h\"\n\ntypedef int (*RTBHandler)(time_t time, unsigned long count, char *buffer, int bufLength);\n\n[see description for available functions]\nThe BSS library supports the streaming of data over delay-tolerant networking (DTN) bundles. The intent of the library is to enable applications that pass streaming data received in transmission time order (i.e., without time regressions) to an application-specific \"display\" function -- notionally for immediate real-time display -- but to store all received data (including out-of-order data) in a private database for playback under user control. The reception and real-time display of in-order data is performed by a background thread, leaving the application's main (foreground) thread free to respond to user commands controlling playback or other application-specific functions.
The application-specific \"display\" function invoked by the background thread must conform to the RTBHandler type definition. It must return 0 on success, -1 on any error that should terminate the background thread. Only on return from this function will the background thread proceed to acquire the next BSS payload.
All data acquired by the BSS background thread is written to a BSS database comprising three files: table, list, and data. The name of the database is the root name that is common to the three files, e.g., db3.tbl, db3.lst, db3.dat would be the three files making up the db3 BSS database. All three files of the selected BSS database must reside in the same directory of the file system.
Several replay navigation functions in the BSS library require that the application provide a navigation state structure of type bssNav as defined in the bss.h header file. The application is not reponsible for populating this structure; it's strictly for the private use of the BSS library.
int bssOpen(char *bssName, char *path, char *eid)
Opens access to a BSS database, to enable data playback. bssName identifies the specific BSS database that is to be opened. path identifies the directory in which the database resides. eid is ignored. On any failure, returns -1. On success, returns zero.
int bssStart(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)
Starts a BSS data acquisition background thread. bssName identifies the BSS database into which data will be acquired. path identifies the directory in which that database resides. eid is used to open the BP endpoint at which the delivered BSS bundle payload contents will be acquired. buffer identifies a data acquisition buffer, which must be provided by the application, and bufLen indicates the length of that buffer; received bundle payloads in excess of this length will be discarded.
handler identifies the display function to which each in-order bundle payload will be passed. The time and count parameters passed to this function identify the received bundle, indicating the bundle's creation timestamp time (in seconds) and counter value. The buffer and bufLength parameters indicate the location into which the bundle's payload was acquired and the length of the acquired payload. handler must return -1 on any unrecoverable system error, 0 otherwise. A return value of -1 from handler will terminate the BSS data acquisition background thread.
On any failure, returns -1. On success, returns zero.
int bssRun(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)
A convenience function that performs both bssOpen() and bssStart(). On any failure, returns -1. On success, returns zero.
void bssClose()
Terminates data playback access to the most recently opened BSS database.
void bssStop()
Terminates the most recently initiated BSS data acquisition background thread.
void bssExit()
A convenience function that performs both bssClose() and bssStop().
long bssRead(bssNav nav, char *data, int dataLen)
Copies the data at the current playback position in the database, as indicated by nav, into data; if the length of the data is in excess of dataLen then an error condition is asserted (i.e., -1 is returned). Note that bssRead() cannot be successfully called until nav has been populated, nominally by a preceding call to bssSeek(), bssNext(), or bssPrev(). Returns the length of data read, or -1 on any error.
long bssSeek(bssNav *nav, time_t time, time_t *curTime, unsigned long *count)
Sets the current playback position in the database, in nav, to the data received in the bundle with the earliest creation time that was greater than or equal to time. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location, or -1 on any error.
long bssSeek_read(bssNav *nav, time_t time, time_t *curTime, unsigned long *count, char *data, int dataLen)
A convenience function that performs bssSeek() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, or -1 on any error.
long bssNext(bssNav *nav, time_t *curTime, unsigned long *count)
Sets the playback position in the database, in nav, to the data received in the bundle with the earliest creation time and ID count greater than that of the bundle at the current playback position. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location (if any), -2 on reaching end of list, or -1 on any error.
long bssNext_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)
A convenience function that performs bssNext() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, -2 on reaching end of list, or -1 on any error.
long bssPrev(bssNav *nav, time_t *curTime, unsigned long *count)
Sets the playback position in the database, in nav, to the data received in the bundle with the latest creation time and ID count earlier than that of the bundle at the current playback position. Populates nav and also returns the creation time and bundle ID count of that bundle in curTime and count. Returns the length of data at this location (if any), -2 on reaching end of list, or -1 on any error.
long bssPrev_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)
A convenience function that performs bssPrev() followed by an immediate bssRead() to return the data at the new playback position. Returns the length of data read, -2 on reaching end of list, or -1 on any error.
bp(3)
"},{"location":"man/bss/bssStreamingApp/","title":"NAME","text":"bssStreamingApp - Bundle Streaming Service transmission test program
"},{"location":"man/bss/bssStreamingApp/#synopsis","title":"SYNOPSIS","text":"bssStreamingApp own_endpoint_ID destination_endpoint_ID [class_of_service]
"},{"location":"man/bss/bssStreamingApp/#description","title":"DESCRIPTION","text":"bssStreamingApp uses BSS to send streaming data over BP from own_endpoint_ID to bssrecv listening at destination_endpoint_ID. class_of_service is as specified for bptrace(1); if omitted, bundles are sent at BP's standard priority (1).
The bundles issued by bssStreamingApp all have 65000-byte payloads, where the ASCII representation of a positive integer (increasing monotonically from 0, by 1, throughout the operation of the program) appears at the start of each payload. All bundles are sent with custody transfer requested, with time-to-live set to 1 day. The application meters output by sleeping for 12800 microseconds after issuing each bundle.
Use CTRL-C to terminate the program.
"},{"location":"man/bss/bssStreamingApp/#files","title":"FILES","text":"No configuration files are needed.
"},{"location":"man/bss/bssStreamingApp/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bss/bssStreamingApp/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bss/bssStreamingApp/#see-also","title":"SEE ALSO","text":"bssrecv(1), bss(3)
"},{"location":"man/bss/bssrecv/","title":"NAME","text":"bssrecv - Bundle Streaming Service reception test program
"},{"location":"man/bss/bssrecv/#synopsis","title":"SYNOPSIS","text":"bssrecv
"},{"location":"man/bss/bssrecv/#description","title":"DESCRIPTION","text":"bssrecv uses BSS to acquire streaming data from bssStreamingApp.
bssrecv is a menu-driven interactive test program, run from the operating system shell prompt. The program enables the user to begin and end a session of BSS data acquisition from bssStreamingApp, displaying the data as it arrives in real time; to replay data acquired during the current session; and to replay data acquired during a prior session.
The user must provide values for three parameters in order to initiate the acquisition or replay of data from bssStreamingApp:
BSS database name
All data acquired by the BSS session thread will be written to a BSS \"database\" comprising three files: table, list, and data. The name of the database is the root name that is common to the three files, e.g., db3.tbl, db3.lst, db3.dat would be the three files making up the db3 BSS database.
path name
All three files of the selected BSS database must reside in the same directory of the file system; the path name of that directory is required.
endpoint ID
In order to acquire streaming data issued by bssStreamingApp, the bssrecv session thread must open the BP endpoint to which that data is directed. For this purpose, the ID of that endpoint is needed.
bssrecv offers the following menu options:
bssrecv prompts the user for the three parameter values noted above, then opens the indicated BSS database for replay of the data in that database.
bssrecv prompts the user for the three parameter values noted above, then starts a background session thread to acquire data into the indicated database. Each bundle that is acquired is passed to a display function that prints a single line consisting of N consecutive '*' characters, where N is computed as the data number at the start of the bundle's payload data, modulo 150. Note that the database is not open for replay at this time.
bssrecv prompts the user for the three parameter values noted above, then starts a background session thread to acquire data into the indicated database (displaying the data as described for option 2 above) and also opens the database for replay.
bssrecv closes the indicated BSS database, terminating replay access.
bssrecv terminates the current background session thread. Replay access to the BSS database, if currently open, is not terminated.
bssrecv terminates the current background session thread. Replay access to the BSS database, if currently open, is also terminated.
bssrecv prompts the user for the start and end times bounding the reception interval that is to be replayed, then displays all data within that interval in both forward and reverse time order. The display function performed for this purpose is the same one that is exercised during real-time acquisition of streaming data.
bssrecv terminates.
\"0\"
bssrecv has terminated.
No configuration files are needed.
"},{"location":"man/bss/bssrecv/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bss/bssrecv/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bss/bssrecv/#see-also","title":"SEE ALSO","text":"bssStreamingApp(1), bss(3)
"},{"location":"man/bssp/","title":"Index of Man Pages","text":"bssp - Bundle Streaming Service Protocol (BSSP) communications library
"},{"location":"man/bssp/bssp/#synopsis","title":"SYNOPSIS","text":"#include \"bssp.h\"\n\ntypedef enum\n{\n BsspNoNotice = 0,\n BsspXmitSuccess,\n BsspXmitFailure,\n BsspRecvSuccess\n} BsspNoticeType;\n\n[see description for available functions]\nThe bssp library provides functions enabling application software to use BSSP to send and receive streaming data in bundles.
BSSP is designed to forward streaming data in original transmission order wherever possible but to retransmit data as necessary to ensure that the entire stream is available for playback eventually. To this end, BSSP uses not one but two underlying \"link service\" channels: (a) an unreliable \"best efforts\" channel, for data items that are successfully received upon initial transmission over every extent of the end-to-end path, and (b) a \"reliable\" channel, for data items that were lost at some point, had to be retransmitted, and therefore are now out of order. The BSS library at the destination node supports immediate \"real-time\" display of all data received on the \"best efforts\" channel in transmission order, together with database retention of all data eventually received on the \"reliable\" channel.
The BSSP notion of engine ID corresponds closely to the Internet notion of a host, and in ION engine IDs are normally indistinguishable from node numbers including the node numbers in Bundle Protocol endpoint IDs conforming to the \"ipn\" scheme.
The BSSP notion of client ID corresponds closely to the Internet notion of \"protocol number\" as used in the Internet Protocol. It enables data from multiple applications -- clients -- to be multiplexed over a single reliable link. However, for ION operations we normally use BSSP exclusively for the transmission of Bundle Protocol data, identified by client ID = 1.
int bssp_attach()
Attaches the application to BSSP functionality on the lcoal computer. Returns 0 on success, -1 on any error.
void bssp_detach()
Terminates all access to BSSP functionality on the local computer.
int bssp_engine_is_started()
Returns 1 if the local BSSP engine has been started and not yet stopped, 0 otherwise.
int bssp_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData, int inOrder, BsspSessionId *sessionId)
Sends a client service data unit to the application that is waiting for data tagged with the indicated clientId as received at the remote BSSP engine identified by destinationEngineId.
clientServiceData must be a \"zero-copy object\" reference as returned by ionCreateZco(). Note that BSSP will privately make and destroy its own reference to the client service data object; the application is free to destroy its reference at any time.
inOrder is a Boolean value indicating whether or not the service data item that is being sent is \"in order\", i.e., was originally transmitted after all items that have previously been sent to this destination by this local BSSP engine: 0 if no (meaning that the item must be transmitted using the \"reliable\" channel), 1 if yes (meaning that the item must be transmitted using the \"best-efforts\" channel.
On success, the function populates *sessionId with the source engine ID and the \"session number\" assigned to transmission of this client service data unit and returns zero. The session number may be used to link future BSSP processing events to the affected client service data. bssp_send() returns -1 on any error.
int bssp_open(unsigned int clientId)
Establishes the application's exclusive access to received service data units tagged with the indicated BSSP client service data ID. At any time, only a single application task is permitted to receive service data units for any single client service data ID.
Returns 0 on success, -1 on any error (e.g., the indicated client service is already being held open by some other application task).
int bssp_get_notice(unsigned int clientId, BsspNoticeType *type, BsspSessionId *sessionId, unsigned char *reasonCode, unsigned int *dataLength, Object *data)
Receives notices of BSSP processing events pertaining to the flow of service data units tagged with the indicated client service ID. The nature of each event is indicated by *type. Additional parameters characterizing the event are returned in *sessionId, *reasonCode, *dataLength, and *data as relevant.
The value returned in *data is always a zero-copy object; use the zco_* functions defined in \"zco.h\" to retrieve the content of that object.
When the notice is an BsspRecvSuccess, the ZCO returned in *data contains the content of a single BSSP block.
The cancellation of an export session results in delivery of a BsspXmitFailure notice. In this case, the ZCO returned in *data is a service data unit ZCO that had previously been passed to bssp_send().
bssp_get_notice() always blocks indefinitely until an BSSP processing event is delivered.
Returns zero on success, -1 on any error.
void bssp_interrupt(unsigned int clientId)
Interrupts an bssp_get_notice() invocation. This function is designed to be called from a signal handler; for this purpose, clientId may need to be obtained from a static variable.
void bssp_release_data(Object data)
Releases the resources allocated to hold data, which must be a received client service data unit ZCO.
void bssp_close(unsigned int clientId)
Terminates the application's exclusive access to received service data units tagged with the indicated client service data ID.
bsspadmin(1), bssprc(5), zco(3)
"},{"location":"man/bssp/bsspadmin/","title":"NAME","text":"bsspadmin - Bundle Streaming Service Protocol (BSSP) administration interface
"},{"location":"man/bssp/bsspadmin/#synopsis","title":"SYNOPSIS","text":"bsspadmin [ commands_filename | . ]
"},{"location":"man/bssp/bsspadmin/#description","title":"DESCRIPTION","text":"bsspadmin configures, starts, manages, and stops BSSP operations for the local ION node.
It operates in response to BSSP configuration commands found in the file commands_filename, if provided; if not, bsspadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to bsspadmin -- that is, the ION node's bsspclock task and link service adapter tasks are stopped.
The format of commands for commands_filename can be queried from bsspadmin with the 'h' or '?' commands at the prompt. The commands are documented in bssprc(5).
"},{"location":"man/bssp/bsspadmin/#exit-status","title":"EXIT STATUS","text":"0
Successful completion of BSSP administration.
bsspadmin
Enter interactive BSSP configuration command entry mode.
bsspadmin host1.bssp
Execute all configuration commands in host1.bssp, then terminate immediately.
bsspadmin .
Stop all BSSP operations on the local node.
See bssprc(5) for details of the BSSP configuration commands.
"},{"location":"man/bssp/bsspadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/bsspadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the bssprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to bsspadmin. Otherwise bsspadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
bsspadmin can't attach to ION.
There is no SDR data store for bsspadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause bsspadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see bssprc(5) for details.
"},{"location":"man/bssp/bsspadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/bsspadmin/#see-also","title":"SEE ALSO","text":"bssprc(5)
"},{"location":"man/bssp/bsspclock/","title":"NAME","text":"bsspclock - BSSP daemon task for managing scheduled events
"},{"location":"man/bssp/bsspclock/#synopsis","title":"SYNOPSIS","text":"bsspclock
"},{"location":"man/bssp/bsspclock/#description","title":"DESCRIPTION","text":"bsspclock is a background \"daemon\" task that periodically performs scheduled BSSP activities. It is spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol, and it is terminated by bsspadmin in response to an 'x' (STOP) command.
Once per second, bsspclock takes the following action:
First it manages the current state of all links (\"spans\"). Specifically, it infers link state changes (\"link cues\") from data rate changes as noted in the RFX database by rfxclock:
If the rate of transmission to a neighbor was zero but is now non-zero, then transmission to that neighbor resumes. The applicable \"buffer empty\" semaphore is given (enabling start of a new transmission session) and the best-efforts and/or reliable \"PDUs ready\" semaphores are given if the corresponding outbound PDU queues are non-empty (enabling transmission of PDUs by the link service output task).
If the rate of transmission to a neighbor was non-zero but is now zero, then transmission to that neighbor is suspended -- i.e., the semaphores triggering transmission will no longer be given.
If the imputed rate of transmission from a neighbor was non-zero but is now zero, then all best-efforts transmission acknowledgment timers affecting transmission to that neighbor are suspended. This has the effect of extending the interval of each affected timer by the length of time that the timers remain suspended.
If the imputed rate of transmission from a neighbor was zero but is now non-zero, then all best-efforts transmission acknowledgment timers affecting transmission to that neighbor are resumed.
Then bsspclock enqueues for reliable transmission all blocks for which the best-efforts transmission acknowledgment timeout interval has now expired but no acknowledgment has yet been received.
"},{"location":"man/bssp/bsspclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
bsspclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart bsspclock.
\"1\"
bsspclock was unable to attach to BSSP protocol operations, probably because bsspadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/bssp/bsspclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/bsspclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
bsspclock can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
Can't dispatch events.
An unrecoverable database error was encountered. bsspclock terminates.
Can't manage links.
An unrecoverable database error was encountered. bsspclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/bsspclock/#see-also","title":"SEE ALSO","text":"bsspadmin(1), rfxclock(1)
"},{"location":"man/bssp/bssprc/","title":"NAME","text":"bssprc - Bundle Streaming Service Protocol management commands file
"},{"location":"man/bssp/bssprc/#description","title":"DESCRIPTION","text":"BSSP management commands are passed to bsspadmin either in a file of text lines or interactively at bsspadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the BSSP management commands are described below.
"},{"location":"man/bssp/bssprc/#commands","title":"COMMANDS","text":"?
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 bsspadmin 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_nbr_of_sessions
The initialize command. Until this command is executed, BSSP is not in operation on the local ION node and most bsspadmin commands will fail.
The command uses est_max_nbr_of_sessions to configure the hashtable it will use to manage access to transmission sessions that are currently in progress. For optimum performance, est_max_nbr_of_sessions should normally equal or exceed the summation of max_nbr_of_sessions over all spans as discussed below.
a span peer_engine_nbr max_nbr_of_sessions max_block_size 'BE-BSO_command' 'RL-BSO_command [queuing_latency]
The add span command. This command declares that a span of potential BSSP data interchange exists between the local BSSP engine and the indicated (neighboring) BSSP engine.
The max_block_size is expressed as a number of bytes of data. max_block_size is used to configure transmission buffer sizes; as such, it limits client data item size. When exceeded, it causes bssp_send() to fail, and bssp_clo() to shutdown. To restart bssp_clo() without rebooting ION immediately, say, due to on-going data transfer over other convergence layers, one can try to first stop bpadmin with 'x', then stop bsspadmin with 'x', then run ionrestart to repair any issue in the volatile database, then relaunch bssp daemon and then bp daemon using corresponding configuration files. This procedure could temporarily enable resumption of operation until it is safe to reboot ION.
max_nbr_of__sessions constitutes, in effect, the local BSSP engine's retransmission \"window\" for this span. The retransmission windows of the spans impose flow control on BSSP transmission, reducing the chance ofx allocation of all available space in the ION node's data store to BSSP transmission sessions.
BE-BSO_command is script text that will be executed when BSSP is started on this node, to initiate operation of the best-efforts transmission channel task for this span. Note that \" peer_engine_nbr\" will automatically be appended to BE-BSO_command by bsspadmin before the command is executed, so only the link-service-specific portion of the command should be provided in the LSO_command string itself.
RL-BSO_command is script text that will be executed when BSSP is started on this node, to initiate operation of the reliable transmission channel task for this span. Note that \" peer_engine_nbr\" will automatically be appended to RL-BSO_command by bsspadmin 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 block at this node and transmission of an acknowledging PDU, 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 'BE-BSI_command' 'RL-BSI_command'
The add seat command. This command declares that the local BSSP engine can receive BSSP PDUs via the link service input daemons that begin running when 'BE-BSI_command' and 'RL-BSI_command' are executed.
c span peer_engine_nbr max_nbr_of_sessions max_block_size 'BE-BSO_command' 'RL-BSO_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 blocks for this span are pending transmission.
d seat 'BE-BSI_command' 'RL-BSI_command'
The delete span command. This command deletes the seat identified by 'BE-BSI_command' and 'RL-BSI_command'.
i span peer_engine_nbr
This command will print information (all configuration parameters) about the span identified by peer_engine_nbr.
i seat 'BE-BSI_command' 'RL-BSI_command'
This command will print all information (i.e., process ID numbers) about the seat identified by 'BE-BSO_command' and 'RL-BSO_command'.
l span
This command lists all declared BSSP data interchange spans.
l seat
This command lists all declared BSSP data acquisition seats.
s ['BE-BSI_command' 'RL-BSI_command']
The start command. This command starts reliable and best-efforts link service output tasks for all BSSP spans (to remote engines) from the local BSSP engine, and it starts the reliable and best-efforts link service input tasks for the local engine. 'BE-BSI_command' and 'RL-BSI_command' are deprecated but are supported for backward compatibility; if provided, the effect is the same as entering the command \"a seat 'BE-BSI_command' 'RL-BSI_command'\" prior to starting all daemon tasks.
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 BSSP computes the nominal round-trip time for an exchange of data with any remote engine. The default value is 1.
x
The stop command. This command stops all link service input and output tasks for the local BSSP engine.
w { 0 | 1 | <activity_spec> }
The BSSP watch command. This command enables and disables production of a continuous stream of user-selected BSSP activity indication characters. A watch parameter of \"1\" selects all BSSP activity indication characters; \"0\" de-selects all BSSP activity indication characters; any other activity_spec such as \"DF-\" selects the activity indication characters in the string, de-selecting all others. BSSP will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
D bssp send completed
E bssp block constructed for issuance
F bssp block issued
G bssp block popped from best-efforts transmission queue
H positive ACK received for bssp block, session ended
S bssp block received
T bssp block popped from reliable transmission queue
- unacknowledged best-efforts block requeued for reliable transmission
* session canceled locally by sender
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a span 19 20 4096 'udpbso node19.ohio.edu:5001' 'tcpbso node19.ohio.edu:5001'
Declares a data interchange span between the local BSSP engine and the remote engine (ION node) numbered 19. There can be at most 20 concurrent sessions of BSSP transmission activity to this node. Maximum block size for this span is set to 4096 bytes, and the best-efforts and reliable link service output tasks that are initiated when BSSP is started on the local ION node will execute the udpbso and tcpbso programs as indicated.
m ownqtime 2
Sets local queuing delay allowance to 2 seconds.
bsspadmin(1), udpbsi(1), udpbso(1), tcpbsi(1), tcpbso(1)
"},{"location":"man/bssp/tcpbsi/","title":"NAME","text":"tcpbsi - TCP-based reliable link service input task for BSSP
"},{"location":"man/bssp/tcpbsi/#synopsis","title":"SYNOPSIS","text":"tcpbsi {local_hostname | @}[:local_port_nbr]
"},{"location":"man/bssp/tcpbsi/#description","title":"DESCRIPTION","text":"tcpbsi is a background \"daemon\" task that receives TCP stream data via a TCP socket bound to local_hostname and local_port_nbr, extracts BSSP blocks from that stream, and passes them to the local BSSP engine. Host name \"@\" signifies that the host name returned by hostname(1) is to be used as the socket's host name. If not specified, port number defaults to 4556.
The link service input task is spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The link service input task is terminated by bsspadmin in response to an 'x' (STOP) command.
"},{"location":"man/bssp/tcpbsi/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpbsi terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart tcpbsi.
\"1\"
tcpbsi terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bsspadmin to restart tcpbsi.
No configuration files are needed.
"},{"location":"man/bssp/tcpbsi/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/tcpbsi/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpbsi can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
RL-BSI task is already started.
Redundant initiation of tcpbsi.
RL-BSI can't open TCP socket
Operating system error. Check errtext, correct problem, and restart tcpbsi.
RL-BSI can't initialize socket
Operating system error. Check errtext, correct problem, and restart tcpbsi.
tcpbsi can't create receiver thread
Operating system error. Check errtext, correct problem, and restart tcpbsi.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/tcpbsi/#see-also","title":"SEE ALSO","text":"bsspadmin(1), tcpbso(1), udpbsi(1)
"},{"location":"man/bssp/tcpbso/","title":"NAME","text":"tcpbso - TCP-based reliable link service output task for BSSP
"},{"location":"man/bssp/tcpbso/#synopsis","title":"SYNOPSIS","text":"tcpbso {remote_engine_hostname | @}[:remote_port_nbr] remote_engine_nbr
"},{"location":"man/bssp/tcpbso/#description","title":"DESCRIPTION","text":"tcpbso is a background \"daemon\" task that extracts BSSP blocks from the queue of blocks bound for the indicated remote BSSP engine and uses a TCP socket to send them to the indicated TCP port on the indicated host. If not specified, port number defaults to 4556.
Each \"span\" of BSSP data interchange between the local BSSP engine and a neighboring BSSP engine requires its own best-effort and reliable link service output tasks. All link service output tasks are spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol, and they are all terminated by bsspadmin in response to an 'x' (STOP) command.
"},{"location":"man/bssp/tcpbso/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcpbso terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart tcpbso.
\"1\"
tcpbso terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bsspadmin to restart tcpbso.
No configuration files are needed.
"},{"location":"man/bssp/tcpbso/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/tcpbso/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcpbso can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the BSSP database by bsspadmin.
RL-BSO task is already started for this engine.
Redundant initiation of tcpbso.
RL-BSO can't open TCP socket
Operating system error. Check errtext, correct problem, and restart tcpbso.
RL-BSO can't bind TCP socket
Operating system error. Check errtext, correct problem, and restart tcpbso.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/tcpbso/#see-abso","title":"SEE ABSO","text":"bsspadmin(1), tcpbsi(1), udpbso(1)
"},{"location":"man/bssp/udpbsi/","title":"NAME","text":"udpbsi - UDP-based best-effort link service input task for BSSP
"},{"location":"man/bssp/udpbsi/#synopsis","title":"SYNOPSIS","text":"udpbsi {local_hostname | @}[:local_port_nbr]
"},{"location":"man/bssp/udpbsi/#description","title":"DESCRIPTION","text":"udpbsi is a background \"daemon\" task that receives UDP datagrams via a UDP socket bound to local_hostname and local_port_nbr, extracts BSSP PDUs from those datagrams, and passes them to the local BSSP engine. Host name \"@\" signifies that the host name returned by hostname(1) is to be used as the socket's host name. If not specified, port number defaults to 6001.
The link service input task is spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The link service input task is terminated by bsspadmin in response to an 'x' (STOP) command.
"},{"location":"man/bssp/udpbsi/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpbsi terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart udpbsi.
\"1\"
udpbsi terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bsspadmin to restart udpbsi.
No configuration files are needed.
"},{"location":"man/bssp/udpbsi/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/udpbsi/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpbsi can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
BE-BSI task is already started.
Redundant initiation of udpbsi.
BE-BSI can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udpbsi.
BE-BSI can't initialize socket
Operating system error. Check errtext, correct problem, and restart udpbsi.
udpbsi can't create receiver thread
Operating system error. Check errtext, correct problem, and restart udpbsi.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/udpbsi/#see-also","title":"SEE ALSO","text":"bsspadmin(1), tcpbsi(1), udpbso(1)
"},{"location":"man/bssp/udpbso/","title":"NAME","text":"udpbso - UDP-based best-effort link service output task for BSSP
"},{"location":"man/bssp/udpbso/#synopsis","title":"SYNOPSIS","text":"udpbso {remote_engine_hostname | @}[:remote_port_nbr] txbps remote_engine_nbr
"},{"location":"man/bssp/udpbso/#description","title":"DESCRIPTION","text":"udpbso is a background \"daemon\" task that extracts BSSP PDUs from the queue of PDUs bound for the indicated remote BSSP engine, encapsulates them in UDP datagrams, and sends those datagrams to the indicated UDP port on the indicated host. If not specified, port number defaults to 6001.
The parameter txbps is optional and kept only for backward compatibility with older configuration files. If it is included, it's value is ignored. For context, txbps (transmission rate in bits per second) was used for congestion control but udpbso now derive its data rate from contact graph.
When invoking udpbso through bsspadmin using the start or add seat command, the remote_engine_nbr and txbps should be omitted. BSSP admin daemon will automatically provide the remote_engine_nbr.
Each \"span\" of BSSP data interchange between the local BSSP engine and a neighboring BSSP engine requires its own best-effort and reliable link service output tasks. All link service output tasks are spawned automatically by bsspadmin in response to the 's' command that starts operation of the BSSP protocol, and they are all terminated by bsspadmin in response to an 'x' (STOP) command.
"},{"location":"man/bssp/udpbso/#exit-status","title":"EXIT STATUS","text":"\"0\"
udpbso terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bsspadmin to restart udpbso.
\"1\"
udpbso terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bsspadmin to restart udpbso.
No configuration files are needed.
"},{"location":"man/bssp/udpbso/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/bssp/udpbso/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udpbso can't initialize BSSP.
bsspadmin has not yet initialized BSSP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the BSSP database by bsspadmin.
BE-BSO task is already started for this engine.
Redundant initiation of udpbso.
BE-BSO can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udpbso.
BE-BSO can't bind UDP socket
Operating system error. Check errtext, correct problem, and restart udpbso.
Segment is too big for UDP BSO.
Configuration error: PDUs that are too large for UDP transmission (i.e., larger than 65535 bytes) are being enqueued for udpbso. Use bsspadmin to change maximum block size for this span.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/bssp/udpbso/#see-abso","title":"SEE ABSO","text":"bsspadmin(1), tcpbso(1), udpbsi(1)
"},{"location":"man/cfdp/","title":"Index of Man Pages","text":"bpcp - A remote copy utility for delay tolerant networks utilizing NASA JPL's Interplanetary Overlay Network (ION)
"},{"location":"man/cfdp/bpcp/#synopsis","title":"SYNOPSIS","text":"bpcp [-dqr | -v] [-L bundle_lifetime] [-C custody_on/off] [-S class_of_service] [host1:]file1 ... [host2:]file2
"},{"location":"man/cfdp/bpcp/#description","title":"DESCRIPTION","text":"bpcp copies files between hosts utilizing NASA JPL's Interplanetary Overlay Network (ION) to provide a delay tolerant network. File copies from local to remote, remote to local, or remote to remote are permitted. bpcp depends on ION to do any authentication or encryption of file transfers. All covergence layers over which bpcp runs MUST be reliable.
The options are permitted as follows:
** -L** bundle_lifetime
Bundle lifetime in seconds. Default is 86400 seconds (1 day).
** -C** BP_custody
Acceptable values are ON/OFF,YES/NO,1/0. Default is OFF.
** -S** class_of_service
Bundle Protocol Class of Service for this transfer. Available options are:
Default is Standard Priority.
bpcp utilizes CFDP to preform the actual file transfers. This has several important implications. First, ION's CFDP implementation requires that reliable convergence layers be used to transfer the data. Second, file permissions are not transferred. Files will be made executable on copy. Third, symbolic links are ignored for local to remote transfers and their target is copied for remote transfers. Fourth, all hosts must be specified using ION's IPN naming scheme.
In order to preform remote to local transfers or remote to remote transfers, bpcpd must be running on the remote hosts. However, bpcp should NOT be run simultaneously with bpcpd or cfdptest.
"},{"location":"man/cfdp/bpcp/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcp terminated normally.
\"1\"
bpcp terminated abnormally. Check console and the ion.log file for error messages.
No configuration files are needed.
"},{"location":"man/cfdp/bpcp/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/bpcp/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/bpcp/#see-also","title":"SEE ALSO","text":"bpcpd(1), ion(3), cfdptest(1)
"},{"location":"man/cfdp/bpcpd/","title":"NAME","text":"bpcpd - ION Delay Tolerant Networking remote file copy daemon
"},{"location":"man/cfdp/bpcpd/#synopsis","title":"SYNOPSIS","text":"bpcpd [-d | -v]
"},{"location":"man/cfdp/bpcpd/#description","title":"DESCRIPTION","text":"bpcpd is the daemon for bpcp. Together these programs copy files between hosts utilizing NASA JPL's Interplanetary Overlay Network (ION) to provide a delay tolerant network.
The options are permitted as follows:
** -d** Debug output. Repeat for increased verbosity.
** -v** Display version information.
bpcpd must be running in order to copy files from this host to another host (i.e. remote to local). Copies in the other direction (local to remote) do not require bpcpd. Further, bpcpd should NOT be run simultaneously with bpcp or cfdptest.
"},{"location":"man/cfdp/bpcpd/#exit-status","title":"EXIT STATUS","text":"\"0\"
bpcpd terminated normally.
\"1\"
bpcpd terminated abnormally. Check console and the ion.log file for error messages.
No configuration files are needed.
"},{"location":"man/cfdp/bpcpd/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/bpcpd/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/bpcpd/#see-also","title":"SEE ALSO","text":"bpcp(1), ion(3), cfdptest(1)
"},{"location":"man/cfdp/bputa/","title":"NAME","text":"bputa - BP-based CFDP UT-layer adapter
"},{"location":"man/cfdp/bputa/#synopsis","title":"SYNOPSIS","text":"bputa
"},{"location":"man/cfdp/bputa/#description","title":"DESCRIPTION","text":"bputa is a background \"daemon\" task that sends and receives CFDP PDUs encapsulated in DTN bundles.
The task is spawned automatically by cfdpadmin in response to the 's' command that starts operation of the CFDP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The UT-layer daemon is terminated by cfdpadmin in response to an 'x' (STOP) command.
"},{"location":"man/cfdp/bputa/#exit-status","title":"EXIT STATUS","text":"\"0\"
bputa terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use cfdpadmin to restart bputa.
\"1\"
bputa terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use cfdpadmin to restart bputa.
No configuration files are needed.
"},{"location":"man/cfdp/bputa/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/bputa/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
CFDP can't attach to BP.
bpadmin has not yet initialized BP protocol operations.
CFDP can't open own endpoint.
Most likely another bputa task is already running. Use cfdpadmin to stop CFDP and restart.
CFDP can't get Bundle Protocol SAP.
Most likely a BP configuration problem. Use bpadmin to stop BP and restart.
bputa can't attach to CFDP.
cfdpadmin has not yet initialized CFDP protocol operations.
bputa can't dequeue outbound CFDP PDU; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
bputa can't send PDU in bundle; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
bputa can't track PDU; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
bputa bundle reception failed.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
bputa can't receive bundle ADU.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
bputa can't handle bundle delivery.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
bputa can't handle inbound PDU.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/bputa/#see-also","title":"SEE ALSO","text":"cfdpadmin(1), bpadmin(1)
"},{"location":"man/cfdp/cfdp/","title":"NAME","text":"cfdp - CCSDS File Delivery Protocol (CFDP) communications library
"},{"location":"man/cfdp/cfdp/#synopsis","title":"SYNOPSIS","text":"#include \"cfdp.h\"\n\ntypedef enum\n{\n CksumTypeUnknown = -1,\n ModularChecksum = 0,\n CRC32CChecksum = 2,\n NullChecksum = 15\n} CfdpCksumType;\n\ntypedef int (*CfdpReaderFn)(int fd, unsigned int *checksum, CfdpCksumType ckType);\n\ntypedef int (*CfdpMetadataFn)(uvast fileOffset, unsigned int recordOffset, unsigned int length, int sourceFileFD, char *buffer);\n\ntypedef enum\n{\n CfdpCreateFile = 0,\n CfdpDeleteFile,\n CfdpRenameFile,\n CfdpAppendFile,\n CfdpReplaceFile,\n CfdpCreateDirectory,\n CfdpRemoveDirectory,\n CfdpDenyFile,\n CfdpDenyDirectory\n} CfdpAction;\n\ntypedef enum\n{\n CfdpNoEvent = 0,\n CfdpTransactionInd,\n CfdpEofSentInd,\n CfdpTransactionFinishedInd,\n CfdpMetadataRecvInd,\n CfdpFileSegmentRecvInd,\n CfdpEofRecvInd,\n CfdpSuspendedInd,\n CfdpResumedInd,\n CfdpReportInd,\n CfdpFaultInd,\n CfdpAbandonedInd\n} CfdpEventType;\n\ntypedef struct\n{\n char *sourceFileName;\n char *destFileName;\n MetadataList messagesToUser;\n MetadataList filestoreRequests;\n CfdpHandler *faultHandlers;\n int unacknowledged;\n unsigned int flowLabelLength;\n unsigned char *flowLabel;\n int recordBoundsRespected;\n int closureRequested;\n} CfdpProxyTask;\n\ntypedef struct\n{\n char *directoryName;\n char *destFileName;\n} CfdpDirListTask;\n\n[see description for available functions]\nThe cfdp library provides functions enabling application software to use CFDP to send and receive files. It conforms to the Class 1 (Unacknowledged) service class defined in the CFDP Blue Book and includes implementations of several standard CFDP user operations.
In the ION implementation of CFDP, the CFDP notion of entity ID is taken to be identical to the BP (CBHE) notion of DTN node number.
CFDP entity and transaction numbers may be up to 64 bits in length. For portability to 32-bit machines, these numbers are stored in the CFDP state machine as structures of type CfdpNumber.
To simplify the interface between CFDP the user application without risking storage leaks, the CFDP-ION API uses MetadataList objects. A MetadataList is a specially formatted SDR list of user messages, filestore requests, or filestore responses. During the time that a MetadataList is pending processing via the CFDP API, but is not yet (or is no longer) reachable from any FDU object, a pointer to the list is appended to one of the lists of MetadataList objects in the CFDP non-volatile database. This assures that any unplanned termination of the CFDP daemons won't leave any SDR lists unreachable -- and therefore un-recyclable -- due to the absence of references to those lists. Restarting CFDP automatically purges any unused MetadataLists from the CFDP database. The \"user data\" variable of the MetadataList itself is used to implement this feature: while the list is reachable only from the database root, its user data variable points to the database root list from which it is referenced; while the list is attached to a File Delivery Unit, its user data is null.
By default, CFDP transmits the data in a source file in segments of fixed size. The user application can override this behavior at the time transmission of a file is requested, by supplying a file reader callback function that reads the file -- one byte at a time -- until it detects the end of a \"record\" that has application significance. Each time CFDP calls the reader function, the function must return the length of one such record (which must be no greater than 65535).
When CFDP is used to transmit a file, a 32-bit checksum must be provided in the \"EOF\" PDU to enable the receiver of the file to assure that it was not corrupted in transit. When an application-specific file reader function is supplied, that function is responsible for updating the computed checksum as it reads each byte of the file; a CFDP library function is provided for this purpose. Two types of file checksums are supported: a simple modular checksum or a 32-bit CRC. The checksum type must be passed through to the CFDP checksum computation function, so it must be provided by (and thus to) the file reader function.
Per-segment metadata may be provided by the user application. To enable this, upon formation of each file data segment, CFDP will invoke the user-provided per-segment metadata composition callback function (if any), a function conforming to the CfdpMetadataFn type definition. The callback will be passed the offset of the segment within the file, the segment's offset within the current record (as applicable), the length of the segment, an open file descriptor for the source file (in case the data must be read in order to construct the metadata), and a 63-byte buffer in which to place the new metadata. The callback function must return the length of metadata to attach to the file data segment PDU (may be zero) or -1 in the event of a general system failure.
The return value for each CFDP \"request\" function (put, cancel, suspend, resume, report) is a reference number that enables \"events\" obtained by calling cfdp_get_event() to be matched to the requests that caused them. Events with reference number set to zero are events that were caused by autonomous CFDP activity, e.g., the reception of a file data segment.
int cfdp_attach()
Attaches the application to CFDP functionality on the local computer. Returns 0 on success, -1 on any error.
int cfdp_entity_is_started()
Returns 1 if the local CFDP entity has been started and not yet stopped, 0 otherwise.
void cfdp_detach()
Terminates all access to CFDP functionality on the local computer.
void cfdp_compress_number(CfdpNumber *toNbr, uvast from)
Converts an unsigned vast number into a CfdpNumber structure, e.g., for use when invoking the cfdp_put() function.
void cfdp_decompress_number(uvast toNbr, CfdpNumber *from)
Converts a numeric value in a CfdpNumber structure to an unsigned vast integer.
void cfdp_update_checksum(unsigned char octet, uvast *offset, unsigned int *checksum, CfdpCksumType ckType)
For use by an application-specific file reader callback function, which must pass to cfdp_update_checksum() the value of each byte (octet) it reads. offset must be octet's displacement in bytes from the start of the file. The checksum pointer is provided to the reader function by CFDP.
MetadataList cfdp_create_usrmsg_list()
Creates a non-volatile linked list, suitable for containing messages-to-user that are to be presented to cfdp_put().
int cfdp_add_usrmsg(MetadataList list, unsigned char *text, int length)
Appends the indicated message-to-user to list.
int cfdp_get_usrmsg(MetadataList list, unsigned char *textBuf, int *length)
Removes from list the first of the remaining messages-to-user contained in the list and delivers its text and length. When the last message in the list is delivered, destroys the list.
void cfdp_destroy_usrmsg_list(MetadataList *list)
Removes and destroys all messages-to-user in list and destroys the list.
MetadataList cfdp_create_fsreq_list()
Creates a non-volatile linked list, suitable for containing filestore requests that are to be presented to cfdp_put().
int cfdp_add_fsreq(MetadataList list, CfdpAction action, char *firstFileName, char *seconfdFIleName)
Appends the indicated filestore request to list.
int cfdp_get_fsreq(MetadataList list, CfdpAction *action, char *firstFileNameBuf, char *secondFileNameBuf)
Removes from list the first of the remaining filestore requests contained in the list and delivers its action code and file names. When the last request in the list is delivered, destroys the list.
void cfdp_destroy_fsreq_list(MetadataList *list)
Removes and destroys all filestore requests in list and destroys the list.
int cfdp_get_fsresp(MetadataList list, CfdpAction *action, int *status, char *firstFileNameBuf, char *secondFileNameBuf, char *messageBuf)
Removes from list the first of the remaining filestore responses contained in the list and delivers its action code, status, file names, and message. When the last response in the list is delivered, destroys the list.
void cfdp_destroy_fsresp_list(MetadataList *list)
Removes and destroys all filestore responses in list and destroys the list.
int cfdp_read_space_packets(int fd, unsigned int *checksum)
This is a standard \"reader\" function that segments the source file on CCSDS space packet boundaries. Multiple small packets may be aggregated into a single file data segment.
int cfdp_read_text_lines(int fd, unsigned int *checksum)
This is a standard \"reader\" function that segments a source file of text lines on line boundaries.
int cfdp_put(CfdpNumber *destinationEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpMetadataFn metadataFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *transactionId)
Sends the file identified by sourceFileName to the CFDP entity identified by destinationEntityNbr. destinationFileName is used to indicate the name by which the file will be catalogued upon arrival at its final destination; if NULL, the destination file name defaults to sourceFileName. If sourceFileName is NULL, it is assumed that the application is requesting transmission of metadata only (as discussed below) and destinationFileName is ignored. Note that both sourceFileName and destinationFileName are interpreted as path names, i.e., directory paths may be indicated in either or both. The syntax of path names is opaque to CFDP; the syntax of sourceFileName must conform to the path naming syntax of the source entity's file system and the syntax of destinationFileName must conform to the path naming syntax of the destination entity's file system.
The byte array identified by utParms, if non-NULL, is interpreted as transmission control information that is to be passed on to the UT layer. The nominal UT layer for ION's CFDP being Bundle Protocol, the utParms array is normally a pointer to a structure of type BpUtParms; see the bp man page for a discussion of the parameters in that structure.
closureLatency is the length of time following transmission of the EOF PDU within which a responding Transaction Finish PDU is expected. If no Finish PDU is requested, this parameter value should be zero.
messagesToUser and filestoreRequests, where non-zero, must be the addresses of non-volatile linked lists (that is, linked lists in ION's SDR database) of CfdpMsgToUser and CfdpFilestoreRequest objects identifying metadata that are intended to accompany the transmitted file. Note that this metadata may accompany a file of zero length (as when sourceFileName is NULL as noted above) -- a transmission of metadata only.
On success, the function populates *transactionID with the source entity ID and the transaction number assigned to this transmission and returns the request number identifying this \"put\" request. The transaction ID may be used to suspend, resume, cancel, or request a report on the progress of this transmission. cfdp_put() returns -1 on any error.
int cfdp_cancel(CfdpTransactionId *transactionId)
Cancels transmission or reception of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, cancellation of a file transmission may have little effect. Returns request number on success, -1 on any error.
int cfdp_suspend(CfdpTransactionId *transactionId)
Suspends transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, suspension of a file transmission may have little effect. Returns request number on success, -1 on any error.
int cfdp_resume(CfdpTransactionId *transactionId)
Resumes transmission of the indicated transaction. Note that, since the ION implementation of CFDP is Unacknowledged, resumption of a file transmission may have little effect. Returns request number on success, -1 on any error.
int cfdp_report(CfdpTransactionId *transactionId)
Requests issuance of a report on the transmission or reception progress of the indicated transaction. The report takes the form of a character string that is returned in a CfdpEvent structure; use cfdp_get_event() to receive the event (which may be matched to the request by request number). Returns request number on success, 0 if transaction is unknown, -1 on any error.
int cfdp_get_event(CfdpEventType *type, time_t *time, int *reqNbr, CfdpTransactionId *transactionId, char *sourceFileNameBuf, char *destFileNameBuf, uvast *fileSize, MetadataList *messagesToUser, uvast *offset, unsigned int *length, CfdpCondition *condition, uvast *progress, CfdpFileStatus *fileStatus, CfdpDeliveryCode *deliveryCode, CfdpTransactionId *originatingTransactionId, char *statusReportBuf, MetadataList *filestoreResponses);
Populates return value fields with data from the oldest CFDP event not yet delivered to the application.
cfdp_get_event() always blocks indefinitely until an CFDP processing event is delivered or the function is interrupted by an invocation of cfdp_interrupt().
On application error, returns zero but sets errno to EINVAL. Returns -1 on system failure, zero otherwise.
void cfdp_interrupt()
Interrupts an cfdp_get_event() invocation. This function is designed to be called from a signal handler.
int cfdp_rput(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpNumber *beneficiaryEntityNbr, CfdpProxyTask *proxyTask, CfdpTransactionId *transactionId)
Sends to the indicated respondent entity a \"proxy\" request to perform a file transmission. The transmission is to be subject to the configuration values in proxyTask and the destination of the file is to be the entity identified by beneficiaryEntityNbr.
int cfdp_rput_cancel(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *rputTransactionId, CfdpTransactionId *transactionId)
Sends to the indicated respondent entity a request to cancel a prior \"proxy\" file transmission request as identified by rputTransactionId, which is the value of transactionId that was returned by that earlier proxy transmission request.
int cfdp_get(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpProxyTask *proxyTask, CfdpTransactionId *transactionId)
Same as cfdp_rput except that beneficiaryEntityNbr is omitted; the local entity is the implicit beneficiary of the request.
int cfdp_rls(CfdpNumber *respondentEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, unsigned int closureLatency, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpDirListTask *dirListTask, CfdpTransactionId *transactionId)
Sends to the indicated respondent entity a request to prepare a directory listing, save that listing in a file, and send it to the local entity. The request is subject to the configuration values in dirListTask.
int cfdp_preview(CfdpTransactionId *transactionId, uvast offset, unsigned int length, char *buffer);
This function is provided to enable the application to get an advance look at the content of a file that CFDP has not yet fully received. Reads length bytes starting at offset bytes from the start of the file that is the destination file of the transaction identified by transactionID, into buffer. On user error (transaction is nonexistent or is outbound, or offset is beyond the end of file) returns 0. On system failure, returns -1. Otherwise returns number of bytes read.
int cfdp_map(CfdpTransactionId *transactionId, unsigned int *extentCount, CfdpExtent *extentsArray);
This function is provided to enable the application to report on the portions of a partially-received file that have been received and written. Lists the received continuous data extents in the destination file of the transaction identified by transactionID. The extents (offset and length) are returned in the elements of extentsArray; the number of extents returned in the array is the total number of continuous extents received so far, or extentCount, whichever is less. The total number of extents received so far is returned as the new value of extentCount. On system failure, returns -1. Otherwise returns 0.
cfdpadmin(1), cfdprc(5)
"},{"location":"man/cfdp/cfdpadmin/","title":"NAME","text":"cfdpadmin - ION's CCSDS File Delivery Protocol (CFDP) administration interface
"},{"location":"man/cfdp/cfdpadmin/#synopsis","title":"SYNOPSIS","text":"cfdpadmin [ commands_filename | . | ! ]
"},{"location":"man/cfdp/cfdpadmin/#description","title":"DESCRIPTION","text":"cfdpadmin configures, starts, manages, and stops CFDP operations for the local ION node.
It operates in response to CFDP configuration commands found in the file commands_filename, if provided; if not, cfdpadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to cfdpadmin -- that is, the ION node's cfdpclock task and UT layer service task (nominally bputa) are stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's cfdpclock task and UT layer service task (nominally bputa) are restarted.
The format of commands for commands_filename can be queried from cfdpadmin with the 'h' or '?' commands at the prompt. The commands are documented in cfdprc(5).
"},{"location":"man/cfdp/cfdpadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of CFDP administration.
cfdpadmin
Enter interactive CFDP configuration command entry mode.
cfdpadmin host1.cfdprc
Execute all configuration commands in host1.cfdprc, then terminate immediately.
cfdpadmin .
Stop all CFDP operations on the local node.
See cfdprc(5) for details of the CFDP configuration commands.
"},{"location":"man/cfdp/cfdpadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/cfdpadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the cfdprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to cfdpadmin. Otherwise cfdpadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
cfdpadmin can't attach to ION.
There is no SDR data store for cfdpadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause cfdpadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see cfdprc(5) for details.
"},{"location":"man/cfdp/cfdpadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/cfdpadmin/#see-also","title":"SEE ALSO","text":"cfdprc(5)
"},{"location":"man/cfdp/cfdpclock/","title":"NAME","text":"cfdpclock - CFDP daemon task for managing scheduled events
"},{"location":"man/cfdp/cfdpclock/#synopsis","title":"SYNOPSIS","text":"cfdpclock
"},{"location":"man/cfdp/cfdpclock/#description","title":"DESCRIPTION","text":"cfdpclock is a background \"daemon\" task that periodically performs scheduled CFDP activities. It is spawned automatically by cfdpadmin in response to the 's' command that starts operation of the CFDP protocol, and it is terminated by cfdpadmin in response to an 'x' (STOP) command.
Once per second, cfdpclock takes the following action:
First it scans all inbound file delivery units (FDUs). For each one whose check timeout deadline has passed, it increments the check timeout count and resets the check timeout deadline. For each one whose check timeout count exceeds the limit configured for this node, it invokes the Check Limit Reached fault handling procedure.
Then it scans all outbound FDUs. For each one that has been Canceled, it cancels all extant PDU bundles and sets transmission progress to the size of the file, simulating the completion of transmission. It destroys each outbound FDU whose transmission is completed.
"},{"location":"man/cfdp/cfdpclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
cfdpclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use cfdpadmin to restart cfdpclock.
\"1\"
cfdpclock was unable to attach to CFDP protocol operations, probably because cfdpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/cfdp/cfdpclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/cfdpclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
cfdpclock can't initialize CFDP.
cfdpadmin has not yet initialized CFDP protocol operations.
Can't dispatch events.
An unrecoverable database error was encountered. cfdpclock terminates.
Can't manage links.
An unrecoverable database error was encountered. cfdpclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/cfdpclock/#see-also","title":"SEE ALSO","text":"cfdpadmin(1)
"},{"location":"man/cfdp/cfdprc/","title":"NAME","text":"cfdprc - CCSDS File Delivery Protocol management commands file
"},{"location":"man/cfdp/cfdprc/#description","title":"DESCRIPTION","text":"CFDP management commands are passed to cfdpadmin either in a file of text lines or interactively at cfdpadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the CFDP management commands are described below.
"},{"location":"man/cfdp/cfdprc/#commands","title":"COMMANDS","text":"?
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 cfdpadmin 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
The initialize command. Until this command is executed, CFDP is not in operation on the local ION node and most cfdpadmin commands will fail.
a entity> <entity nbr> <rtt> <incstype> <outcstype>
The add entity command. This command will add a new remote CFDP entity to the CFDP management information base. Valid UT protocol names are bp and tcp. Endpoint name is EID for bp, socket spec (IP address:port number) for tcp. RTT is round-trip time, used to set acknowledgement timers. incstype is the type of checksum to use when validating data received from this entity; valid values are 0 (modular checksum), 2 (CRC32C), and 15 (the null checksum). outcstype is the type of checksum to use when computing the checksum for transmitting data to this entity.
c entity> <entity nbr> <rtt> <incstype> <outcstype>
The change entity command. This command will change information associated with an existing entity in the CFDP management information base.
d entity> <entity nbr>
The delete entity command. This command will delete an existing entity from the CFDP management information base.
i [<entity nbr>]
The info command. When entity nbr is provided, this command will print information about the indicated entity. Otherwise this command will print information about the current state of the local CFDP entity, including the current settings of all parameters that can be managed as described below.
s 'UTS command'
The start command. This command starts the UT-layer service task for the local CFDP entity.
m discard { 0 | 1 }
The manage discard command. This command enables or disables the discarding of partially received files upon cancellation of a file reception. The default value is 1;
m requirecrc { 0 | 1 }
The manage CRC data integrity command. This command enables or disables the attachment of CRCs to all PDUs issued by the local CFDP entity. The default value is 0;
m fillchar file_fill_character
The manage fill character command. This command establishes the fill character to use for the portions of an incoming file that have not yet been received. The fill character is normally expressed in hex, e.g., the default value is 0xaa.
m ckperiod check_cycle_period
The manage check interval command. This command establishes the number of seconds following reception of the EOF PDU -- or following expiration of a prior check cycle -- after which the local CFDP will check for completion of a file that is being received. Default value is 86400 (i.e., one day).
m maxtimeouts check_cycle_limit
The manage check limit command. This command establishes the number of check cycle expirations after which the local CFDP entity will invoke the check cycle expiration fault handler upon expiration of a check cycle. Default value is 7.
m maxevents event_queue_limit
The manage event queue limit command. This command establishes the maximum number of unread service indications (CFDP \"events\") that may be queued up for delivery at any time. When the events queue length exceeds this figure, events are simply deleted (in decreasing age order, oldest first) until the the limit is no longer exceeded. Default value is 20.
m maxtrnbr max_transaction_number
The manage transaction numbers command. This command establishes the largest possible transaction number used by the local CFDP entity for file transmission transactions. After this number has been used, the transaction number assigned to the next transaction will be 1. The default value is 999999999.
m segsize max_bytes_per_file_data_segment
The manage segment size command. This command establishes the number of bytes of file data in each file data PDU transmitted by the local CFDP entity in the absence of an application-supplied reader function. The default value is 65000.
m inactivity inactivity_period
The manage inactivity period command. This command establishes the number of seconds that a CFDP file transfer is allowed to go idle before being canceled for inactivity. The default is one day.
x
The stop command. This command stops the UT-layer service task for the local CFDP engine.
w { 0 | 1 | <activity_spec> }
The CFDP watch command. This command enables and disables production of a continuous stream of user-selected CFDP activity indication characters. A watch parameter of \"1\" selects all CFDP activity indication characters; \"0\" de-selects all CFDP activity indication characters; any other activity_spec such as \"p\" selects all activity indication characters in the string, de-selecting all others. CFDP will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
p CFDP PDU transmitted
q CFDP PDU received
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
m requirecrc 1
Initiates attachment of CRCs to all subsequently issued CFDP PDUs.
cfdpadmin(1), bputa(1)
"},{"location":"man/cfdp/cfdptest/","title":"NAME","text":"cfdptest - CFDP test shell for ION
"},{"location":"man/cfdp/cfdptest/#synopsis","title":"SYNOPSIS","text":"cfdptest [ commands_filename ]
"},{"location":"man/cfdp/cfdptest/#description","title":"DESCRIPTION","text":"cfdptest provides a mechanism for testing CFDP file transmission. It can be used in either scripted or interactive mode. All bundles containing CFDP PDUs are sent with custody transfer requested and with all bundle status reporting disabled.
When scripted with commands_filename, cfdptest operates in response to CFDP management commands contained in the provided commands file. Each line of text in the file is interpreted as a single command comprising several tokens: a one-character command code and, in most cases, one or more command arguments of one or more characters. The commands configure and initiate CFDP file transmission operations.
If no file is specified, cfdptest instead offers the user an interactive \"shell\" for command entry. cfdptest prints a prompt string (\": \") to stdout, accepts strings of text from stdin, and interprets each string as a command.
The supported cfdptest commands (whether interactive or scripted) are as follows:
?
The help command. This will display a listing of the commands and their formats. It is the same as the h command.
h
An alternate form of the help command.
z [<number of seconds to pause>]
The pause command. When cfdptest is running in interactive mode, this command causes the console input processing thread to pause the indicated number of seconds (defaulting to 1) before processing the next command. This is provided for use in test scripting.
d <destination CFDP entity ID number>
The destination command. This command establishes the CFDP entity to which the next file transmission operation will be directed. CFDP entity numbers in ION are, by convention, the same as BP node numbers.
f <source file path name>
The from command. This command identifies the file that will be transmitted when the next file transmission operation is commanded.
t <destination file path name>
The to command. This command provides the name for the file that will be created at the receiving entity when the next file transmission operation is commanded.
l <lifetime in seconds>
The time-to-live command. This command establishes the time-to-live for all subsequently issued bundles containing CFDP PDUs. If not specified, the default value 86400 (1 day) is used.
p <priority>
The priority command. This command establishes the priority (class of service) for all subsequently issued bundles containing CFDP PDUs. Valid values are 0, 1, and 2. If not specified, priority is 1.
o <ordinal>
The ordinal command. This command establishes the \"ordinal\" (sub-priority within priority 2) for all subsequently issued bundles containing CFDP PDUs. Valid values are 0-254. If not specified, ordinal is 0.
m <mode>
The mode command. This command establishes the transmission mode (\"best-effort\" or assured) for all subsequently issued bundles containing CFDP PDUs. Valid values are 0 (assured, reliable, with reliability provided by a reliable DTN convergence layer protocol), 1 (best-effort, unreliable), and 2 (assured, reliable, but with reliability provided by BP custody transfer). If not specified, transmission mode is 0.
a <latency in seconds>
The closure latency command. This command establishes the transaction closure latency for all subsequent file transmission operations. When it is set to zero, the file transmission is \"open loop\" and the CFDP transaction at the sending entity finishes when the EOF is sent. Otherwise, the receiving CFDP entity is being asked to send a \"Finished\" PDU back to the sending CFDP entity when the transaction finishes at the receiving entity. Normally the transaction finishes at the sending entity only when that Finished PDU is received. However, when closure latency seconds elapse following transmission of the EOF PDU prior to receipt of the Finished PDU, the transaction finishes immediately with a Check Timer fault.
n { 0 | 1 }
The segment metadata command. This command controls the insertion of sample segment metadata -- a string representation of the current time -- in every file data segment PDU. A value of 1 enables segment metadata insertion, while a value of 0 disables it.
g <srrflags>
The srrflags command. This command establishes the BP status reporting that will be requested for all subsequently issued bundles containing CFDP PDUs. srrflags must be a status reporting flags string as defined for bptrace(1): a sequence of status report flags, separated by commas, with no embedded whitespace. Each status report flag must be one of the following: rcv, ct, fwd, dlv, del.
c <criticality>
The criticality command. This command establishes the criticality for all subsequently issued bundles containing CFDP PDUs. Valid values are 0 (not critical) and 1 (critical). If not specified, criticality is 0.
r <action code nbr> <first path name> <second path name>
The filestore request command. This command adds a filestore request to the metadata that will be issued when the next file transmission operation is commanded. Action code numbers are:
u '<message text>'
The user message command. This command adds a user message to the metadata that will be issued when the next file transmission operation is commanded.
&
The send command. This command initiates file transmission as configured by the most recent preceding d, f, t, and a commands.
|
The get command. This command causes a request for file transmission to the local node, subject to the parameters provided by the most recent preceding f, t, and a commands, to be sent to the entity identified by the most recent preceding d command.
NOTE that 'get' in CFDP is implemented very differently from 'send'. The 'send' operation is a native element of the CFDP protocol. The 'get' operation is implemented by sending to the responding entity a standardized sequence of message-to-user messages in a Metadata PDU - the user application at the responding entity receives those messages and initiates a 'send' to accomplish transmission of the file. This means that 'send' can succeed even if no user application is running at the remote node, but 'get' cannot.
^
The cancel command. This command cancels the most recently initiated file transmission.
%
The suspend command. This command suspends the most recently initiated file transmission.
$
The resume command. This command resumes the most recently initiated file transmission.
#
The report command. This command reports on the most recently initiated file transmission.
q
The quit command. Terminates the cfdptest program.
cfdptest in interactive mode also spawns a CFDP event handling thread. The event thread receives CFDP service indications and simply prints lines of text to stdout to announce them.
NOTE that when cfdptest runs in scripted mode it does not spawn an event handling thread, which makes it possible for the CFDP events queue to grow indefinitely unless some other task consumes and reports on the events. One simple solution is to run an interactive cfdptest task in background, simply to keep the event queue cleared, while scripted non-interactive cfdptest tasks are run in the foreground.
"},{"location":"man/cfdp/cfdptest/#exit-status","title":"EXIT STATUS","text":"\"0\"
cfdptest has terminated. Any problems encountered during operation will be noted in the ion.log log file.
See above for details on valid commands_filename commands.
"},{"location":"man/cfdp/cfdptest/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/cfdptest/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by cfdptest are written to the ION log file ion.log.
Can't open command file...
The file identified by commands_filename doesn't exist.
cfdptest can't initialize CFDP.
cfdpadmin has not yet initialized CFDP operations.
Can't put FDU.
The attempt to initiate file transmission failed. See the ION log for additional diagnostic messages from the CFDP library.
Failed getting CFDP event.
The attempt to retrieve a CFDP service indication failed. See the ION log for additional diagnostic messages from the CFDP library.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/cfdptest/#see-also","title":"SEE ALSO","text":"cfdpadmin(1), cfdp(3)
"},{"location":"man/cfdp/tcputa/","title":"NAME","text":"tcputa - TCP/IP-based CFDP UT-layer adapter
"},{"location":"man/cfdp/tcputa/#synopsis","title":"SYNOPSIS","text":"tcputa
"},{"location":"man/cfdp/tcputa/#description","title":"DESCRIPTION","text":"tcputa is a background \"daemon\" task that sends and receives CFDP PDUs via a TCP/IP socket.
The task is spawned automatically by cfdpadmin in response to the 's' command that starts operation of the CFDP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The UT-layer daemon is terminated by cfdpadmin in response to an 'x' (STOP) command.
"},{"location":"man/cfdp/tcputa/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcputa terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use cfdpadmin to restart tcputa.
\"1\"
tcputa terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use cfdpadmin to restart tcputa.
No configuration files are needed.
"},{"location":"man/cfdp/tcputa/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/cfdp/tcputa/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcputa can't attach to CFDP.
cfdpadmin has not yet initialized CFDP protocol operations.
tcputa can't dequeue outbound CFDP PDU; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
tcputa can't track PDU; terminating.
Possible system error. Check ion.log for additional diagnostic messages.
tcputa can't handle inbound PDU.
Possible system error; reception thread terminates. Check ion.log for additional diagnostic messages.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/cfdp/tcputa/#see-also","title":"SEE ALSO","text":"cfdpadmin(1), bpadmin(1)
"},{"location":"man/dgr/","title":"Index of Man Pages","text":"dgr - Datagram Retransmission system library
"},{"location":"man/dgr/dgr/#synopsis","title":"SYNOPSIS","text":"#include \"dgr.h\"\n\n[see description for available functions]\nThe DGR library is an alternative implementation of a subset of LTP, intended for use over UDP/IP in the Internet; unlike ION's canonical LTP implementation it includes a congestion control mechanism that interprets LTP block transmission failure as an indication of network congestion (not data corruption) and reduces data transmission rate in response.
As such, DGR differs from many reliable-UDP systems in two main ways:
It uses adaptive timeout interval computation techniques\n borrowed from TCP to try to avoid introducing congestion\n into the network.\n\n It borrows the concurrent-session model of transmission\n from LTP (and ultimately from CFDP), rather than waiting\n for one datagram to be acknowledged before sending the next,\n to improve bandwidth utilization.\nAt this time DGR is interoperable with other implementations of LTP only when each block it receives is transmitted in a single LTP data segment encapsulated in a single UDP datagram. More complex LTP behavior may be implemented in the future.
int dgr_open(uvast ownEngineId, unsigned int clientSvcId, unsigned short ownPortNbr, unsigned int ownIpAddress, char *memmgrName, Dgr *dgr, DgrRC *rc)
Establishes the application's access to DGR communication service.
ownEngineId is the sending LTP engine ID that will characterize segments issued by this DGR service access point. In order to prevent erroneous system behavior, never assign the same LTP engine ID to any two interoperating DGR SAPs.
clientSvcId identifies the LTP client service to which all LTP segments issued by this DGR service access point will be directed.
ownPortNbr is the port number to use for DGR service. If zero, a system-assigned UDP port number is used.
ownIpAddress is the Internet address of the network interface to use for DGR service. If zero, this argument defaults to the address of the interface identified by the local machine's host name.
memmgrName is the name of the memory manager (see memmgr(3)) to use for dynamic memory management in DGR. If NULL, defaults to the standard system malloc() and free() functions.
dgr is the location in which to store the service access pointer that must be supplied on subsequent DGR function invocations.
rc is the location in which to store the DGR return code resulting from the attempt to open this service access point (always DgrOpened).
On any failure, returns -1. On success, returns zero.
void dgr_getsockname(Dgr dgr, unsigned short *portNbr, unsigned int *ipAddress)
States the port number and IP address of the UDP socket used for this DGR service access point.
void dgr_close(Dgr dgr)
Reverses dgr_open(), releasing resources where possible.
int dgr_send(Dgr dgr, unsigned short toPortNbr, unsigned int toIpAddress, int notificationFlags, char *content, int length, DgrRC *rc)
Sends the indicated content, of length as indicated, to the remote DGR service access point identified by toPortNbr and toIpAddress. The message will be retransmitted as necessary until either it is acknowledged or DGR determines that it cannot be delivered.
notificationFlags, if non-zero, is the logical OR of the notification behaviors requested for this datagram. Available behaviors are DGR_NOTE_FAILED (a notice of datagram delivery failure will issued if delivery of the datagram fails) and DGR_NOTE_ACKED (a notice of datagram delivery success will be issued if delivery of the datagram succeeds). Notices are issued via dgr_receive() that is, the thread that calls dgr_receive() on this DGR service access point will receive these notices interspersed with inbound datagram contents.
length of content must be greater than zero and may be as great as 65535, but lengths greater than 8192 may not be supported by the local underlying UDP implementation; to minimize the chance of data loss when transmitting over the internet, length should not exceed 512.
rc is the location in which to store the DGR return code resulting from the attempt to send the content.
On any failure, returns -1 and sets *rc to DgrFailed. On success, returns zero.
int dgr_receive(Dgr dgr, unsigned short *fromPortNbr, unsigned int *fromIpAddress, char *content, int *length, int *errnbr, int timeoutSeconds, DgrRC *rc)
Delivers the oldest undelivered DGR event queued for delivery.
DGR events are of two type: (a) messages received from a remote DGR service access point and (b) notices of previously sent messages that DGR has determined either have been or cannot be delivered, as requested in the notificationFlags parameters provided to the dgr_send() calls that sent those messages.
In the former case, dgr_receive() will place the content of the inbound message in content, its length in length, and the IP address and port number of the sender in fromIpAddress and fromPortNbr, and it will set *rc to DgrDatagramReceived and return zero.
In the latter case, dgr_receive() will place the content of the affected outbound message in content and its length in length and return zero. If the event being reported is a delivery success, then DgrDatagramAcknowledged will be placed in *rc. Otherwise, DgrDatagramNotAcknowledged will be placed in *rc and the relevant errno (if any) will be placed in *errnbr.
The content buffer should be at least 65535 bytes in length to enable delivery of the content of the received or delivered/undeliverable message.
timeoutSeconds controls blocking behavior. If timeoutSeconds is DGR_BLOCKING (i.e., -1), dgr_receive() will not return until (a) there is either an inbound message to deliver or an outbound message delivery result to report, or (b) the function is interrupted by means of dgr_interrupt(). If timeoutSeconds is DGR_POLL (i.e., zero), dgr_receive() returns immediately; if there is currently no inbound message to deliver and no outbound message delivery result to report, the function sets *rc to DgrTimedOut and returns zero. For any other positive value of timeoutSeconds, dgr_receive() returns after the indicated number of seconds have lapsed (in which case the returned value of *rc is DgrTimedOut), or when there is a message to deliver or a delivery result to report, or when the function is interrupted by means of dgr_interrupt(), whichever occurs first. When the function returns due to interruption by dgr_interrupt(), the value placed in *rc is DgrInterrupted instead of DgrDatagramReceived.
rc is the location in which to store the DGR return code resulting from the attempt to receive content.
On any I/O error or other unrecoverable system error, returns -1. Otherwise always returns zero, placing DgrFailed in *rc and writing a failure message in the event of an operating error.
void dgr_interrupt(Dgr dgr)
Interrupts a dgr_receive() invocation that is currently blocked. Designed to be called from a signal handler; for this purpose, dgr may need to be obtained from a static variable.
ltp(3), file2dgr(1), dgr2file(1)
"},{"location":"man/dgr/dgr2file/","title":"NAME","text":"dgr2file - DGR reception test program
"},{"location":"man/dgr/dgr2file/#synopsis","title":"SYNOPSIS","text":"dgr2file
"},{"location":"man/dgr/dgr2file/#description","title":"DESCRIPTION","text":"dgr2file uses DGR to receive multiple copies of the text of a file transmitted by file2dgr, writing each copy of the file to the current working directory. The name of each file written by dgr2file is file_copy_cycleNbr, where cycleNbr is initially zero and is increased by 1 every time dgr2file closes the file it is currently writing and opens a new one.
Upon receiving a DGR datagram from file2dgr, dgr2file extracts the content of the datagram (either a line of text from the file that is being transmitted by file2dgr or else an EOF string indicating the end of that file). It appends each extracted line of text to the local copy of that file that dgr2file is currently writing. When the extracted datagram content is an EOF string (the ASCII text \"*** End of the file ***\"), dgr2file closes the file it is writing, increments cycleNbr, opens a new copy of the file for writing, and prints the message \"working on cycle cycleNbr.\"
dgr2file always receives datagrams at port 2101.
"},{"location":"man/dgr/dgr2file/#exit-status","title":"EXIT STATUS","text":"\"0\"
dgr2file has terminated.
No configuration files are needed.
"},{"location":"man/dgr/dgr2file/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dgr/dgr2file/#diagnostics","title":"DIAGNOSTICS","text":"can't open dgr service
Operating system error. Check errtext, correct problem, and rerun.
can't open output file
Operating system error. Check errtext, correct problem, and rerun.
dgr_receive failed
Operating system error. Check errtext, correct problem, and rerun.
can't write to output file
Operating system error. Check errtext, correct problem, and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dgr/dgr2file/#see-also","title":"SEE ALSO","text":"file2dgr(1), dgr(3)
"},{"location":"man/dgr/file2dgr/","title":"NAME","text":"file2dgr - DGR transmission test program
"},{"location":"man/dgr/file2dgr/#synopsis","title":"SYNOPSIS","text":"file2dgr remoteHostName fileName [nbrOfCycles]
"},{"location":"man/dgr/file2dgr/#description","title":"DESCRIPTION","text":"file2dgr uses DGR to send nbrOfCycles copies of the text of the file named fileName to the dgr2file process running on the computer identified by remoteHostName. If not specified (or if less than 1), nbrOfCycles defaults to 1. After sending all lines of the file, file2dgr sends a datagram containing an EOF string (the ASCII text \"*** End of the file ***\") before reopening the file and starting transmission of the next copy.
When all copies of the file have been sent, file2dgr prints a performance report:
Bytes sent = I<byteCount>, usec elapsed = I<elapsedTime>.\n\n Sending I<dataRate> bits per second.\n\"0\"
file2dgr has terminated.
No configuration files are needed.
"},{"location":"man/dgr/file2dgr/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dgr/file2dgr/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by file2dgr are written to the ION log file ion.log.
Can't open dgr service.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't open input file
Operating system error. Check errtext, correct problem, and rerun.
Can't acquire DGR working memory.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't reopen input file
Operating system error. Check errtext, correct problem, and rerun.
Can't read from input file
Operating system error. Check errtext, correct problem, and rerun.
dgr_send failed.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dgr/file2dgr/#see-also","title":"SEE ALSO","text":"file2dgr(1), dgr(3)
"},{"location":"man/dtpc/","title":"Index of Man Pages","text":"dtpc - Delay-Tolerant Payload Conditioning (DTPC) communications library
"},{"location":"man/dtpc/dtpc/#synopsis","title":"SYNOPSIS","text":"#include \"dtpc.h\"\n\n[see description for available functions]\nThe dtpc library provides functions enabling application software to use Delay-Tolerant Payload Conditioning (DTPC) when exchanging information over a delay-tolerant network. DTPC is an application service protocol, running in a layer immediately above Bundle Protocol, that offers delay-tolerant support for several end-to-end services to applications that may require them. These services include delivery of application data items in transmission (rather than reception) order; detection of reception gaps in the sequence of transmitted application data items, with end-to-end negative acknowledgment of the missing data; end-to-end positive acknowledgment of successfully received data; end-to-end retransmission of missing data, driven either by negative acknowledgment or timer expiration; suppression of duplicate application data items; aggregation of small application data items into large bundle payloads, to reduce bundle protocol overhead; and application-controlled elision of redundant data items in aggregated payloads, to improve link utiliization.
int dptc_attach( )
Attaches the application to DTPC functionality on the local computer. Returns 0 on success, -1 on any error.
void dptc_detach( )
Terminates all access to DTPC functionality on the local computer.
int dtpc_entity_is_started( )
Returns 1 if the local DTPC entity has been started and not yet stopped, 0 otherwise.
int dtpc_open(unsigned int topicID, DtpcElisionFn elisionFn, DtpcSAP *dtpcsapPtr)
Establishes the application as the sole authorized client for posting and receiving application data items on topic topicID within the local BP node. On success, the service access point for posting and receiving such data items is placed in *dtpcsapPtr, the elision callback function elisionFn (if not NULL) is associated with this topic, and 0 is returned. Returns -1 on any error.
int dtpc_send(unsigned int profileID, DtpcSAP sap, char *destEid, unsigned int maxRtx, unsigned int aggrSizeLimit, unsigned int aggrTimeLimit, int lifespan, BpAncillaryData *ancillaryData, unsigned char srrFlags, BpCustodySwitch custodySwitch, char *reportToEid, int classOfService, Object item, unsigned int length)
Inserts an application data item into an outbound DTPC application data unit destined for destEid.
Transmission of that outbound ADU will be subject to the profile identified by profileID, as asserted by dtpcadmin(1), if profileID is non-zero. In that case, maxRtx, aggrSizeLimit, aggrTimeLimit, lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService are ignored.
If profileID is zero then the profile asserted by dtpcadmin(1) that matches maxRtx, aggrSizeLimit, aggrTimeLimit, lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService will govern transmission of the ADU, unless no such profile has been asserted, in which case dtpc_send() returns 0 indicating user error.
maxRtx is the maximum number of times any single DTPC ADU transmitted subject to the indicated profile may be retransmitted by the DTPC entity. If maxRtx is zero, then the DTPC transport service features (in-order delivery, end-to-end acknowledgment, etc.) are disabled for this profile.
aggrSizeLimit is the size threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrSizeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
aggrTimeLimit is the time threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrTimeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
lifespan, ancillaryData, srrFlags, custodySwitch, reportToEid, and classOfService are as defined for bp_send (see bp(3)).
item must be an object allocated within ION's SDR \"heap\", and length must be the length of that object. The item will be inserted into the outbound ADU's list of data items posted for the topic associated with sap, and the elision callback function declared for sap (if any, and if the applicable profile does not disable transmission optimization features) will be invoked immediately after insertion of the application data item but before DTPC makes any decision on whether or not to initiate transmission of the outbound ADU.
The function returns 1 on success, 0 on any user application error, -1 on any system error.
int dtpc_receive(DtpcSAP sap, DtpcDelivery *dlvBuffer, int timeoutSeconds)
Receives a single DTPC application data item, or reports on some failure of DTPC reception activity.
The \"result\" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one application data item on the topic associated with sap has not yet been delivered to the SAP, then the payload of the oldest such item will be returned in dlvBuffer->item and dlvBuffer->result will be set to PayloadPresent. If there is no such item, dtpc_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is DTPC_POLL (i.e., zero) and no application data item is awaiting delivery, or if timeoutSeconds is greater than zero but no item arrives before timeoutSeconds have elapsed, then dlvBuffer->result will be set to ReceptionTimedOut. If timeoutSeconds is DTPC_BLOCKING (i.e., -1) then bp_receive() blocks until either an item arrives or the function is interrupted by an invocation of dtpc_interrupt().
dlvBuffer->result will be set to ReceptionInterrupted in the event that the calling process received and handled some signal other than SIGALRM while waiting for a bundle.
dlvBuffer->result will be set to DtpcServiceStopped in the event that DTPC service has been terminated on the local node.
The application data item delivered in the DTPC delivery structure, if any, will be an object allocated within ION's SDR \"heap\"; the length of that object will likewise be provided in the DtpcDelivery structure.
Be sure to call dtpc_release_delivery() after every successful invocation of dtpc_receive().
The function returns 0 on success, -1 on any error.
void dtpc_interrupt(DtpcSAP sap)
Interrupts a dtpc_receive() invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, sap may need to be obtained from a static variable.
void dtpc_release_delivery(DtpcDelivery *dlvBuffer)
Releases resources allocated to the indicated DTPC delivery.
void dtpc_close(DtpcSAP sap)
Removes the application as the sole authorized client for posting and receiving application data items on the topic indicated in sap within the local BP node. The application relinquishes its ability to send and receive application data items on the indicated topic.
dtpcadmin(1), dtpcrc(5), bp(3)
"},{"location":"man/dtpc/dtpcadmin/","title":"NAME","text":"dtpcadmin - Delay-Tolerant Payload Conditioning (DTPC) administration interface
"},{"location":"man/dtpc/dtpcadmin/#synopsis","title":"SYNOPSIS","text":"dtpcadmin [ commands_filename | . ]
"},{"location":"man/dtpc/dtpcadmin/#description","title":"DESCRIPTION","text":"dtpcadmin configures, starts, manages, and stops DTPC operations for the local ION node.
It operates in response to DTPC configuration commands found in the file commands_filename, if provided; if not, dtpcadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to dtpcadmin -- that is, the ION node's dtpcclock task and dtpcd task are stopped.
The format of commands for commands_filename can be queried from dtpcadmin with the 'h' or '?' commands at the prompt. The commands are documented in dtpcrc(5).
"},{"location":"man/dtpc/dtpcadmin/#exit-status","title":"EXIT STATUS","text":"0
Successful completion of DTPC administration.
dtpcadmin
Enter interactive DTPC configuration command entry mode.
dtpcadmin host1.dtpc
Execute all configuration commands in host1.dtpc, then terminate immediately.
dtpcadmin .
Stop all DTPC operations on the local node.
See dtpcrc(5) for details of the DTPC configuration commands.
"},{"location":"man/dtpc/dtpcadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the dtpcrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to dtpcadmin. Otherwise dtpcadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
dtpcadmin can't attach to ION.
There is no SDR data store for dtpcadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause dtpcadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see dtpcrc(5) for details.
"},{"location":"man/dtpc/dtpcadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcadmin/#see-also","title":"SEE ALSO","text":"dtpcrc(5)
"},{"location":"man/dtpc/dtpcclock/","title":"NAME","text":"dtpcclock - DTPC daemon task for managing scheduled events
"},{"location":"man/dtpc/dtpcclock/#synopsis","title":"SYNOPSIS","text":"dtpcclock
"},{"location":"man/dtpc/dtpcclock/#description","title":"DESCRIPTION","text":"dtpcclock is a background \"daemon\" task that periodically performs scheduled DTPC activities. It is spawned automatically by dtpcadmin in response to the 's' command that starts operation of the DTPC protocol, and it is terminated by dtpcadmin in response to an 'x' (STOP) command.
Once per second, dtpcclock takes the following action:
First it executes all DTPC events scheduled to occur at any time up to the current moment:
DTPC ADUs for which an expected positive acknowledgment has not yet arrived are retransmitted.
Received DTPC ADUs whose time to live has elapsed are deleted.
Then dtpcclock increases the ages of all DTPC ADUs pending transmission and initiates transmission of each such ADU whose age now equals or exceeds its aggregation time limit.
"},{"location":"man/dtpc/dtpcclock/#exit-status","title":"EXIT STATUS","text":"0
dtpcclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use dtpcadmin to restart dtpcclock.
1
dtpcclock was unable to attach to DTPC protocol operations, probably because dtpcadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/dtpc/dtpcclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dtpcclock can't initialize DTPC.
dtpcadmin has not yet initialized DTPC protocol operations.
Can't send finished adu.
An unrecoverable database error was encountered. dtpcclock terminates.
Can't stop aggregation for adu.
An unrecoverable database error was encountered. dtpcclock terminates.
Could not scan outbound Adus
An unrecoverable database error was encountered. dtpcclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcclock/#see-also","title":"SEE ALSO","text":"dtpcadmin(1)
"},{"location":"man/dtpc/dtpcd/","title":"NAME","text":"dtpcd - DTPC daemon task for receiving and processing DTPC ADUs in bundles
"},{"location":"man/dtpc/dtpcd/#synopsis","title":"SYNOPSIS","text":"dtpcd
"},{"location":"man/dtpc/dtpcd/#description","title":"DESCRIPTION","text":"dtpcd is a background \"daemon\" task that manages the reception and processing of DTPC protocol data units. It receives the payloads of bundles destined for the \"ipn\"-scheme endpoint whose node number is the number of the local node and whose service number is the DTPC_RECV_SVC_NBR (129 as of the time of this writeng).
DTPC protocol data units are of two types: application data units (ADUs, i.e., aggregations of application data items) and acknowledgments. Each acknowledgment is interpreted as authorization to release the buffer space occupied by the node's local copy of the acknowledged ADU. Each ADU is parsed into its constituent application data items, which are then delivered to the applications awaiting them, and when required a DTPC end-to-end acknowledgment PDU is returned to the DTPC PDU sender.
"},{"location":"man/dtpc/dtpcd/#exit-status","title":"EXIT STATUS","text":"0
dtpcd terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use dtpcadmin to restart dtpcd.
1
dtpcd terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use dtpcadmin to restart dtpcd.
No configuration files are needed.
"},{"location":"man/dtpc/dtpcd/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcd/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
DTPC can't open own 'send' endpoint.
Bundle protocol agent has not been started. See ion(3).
dtpcd can't attach to DTPC.
dtpcadmin has not yet initialized DTPC protocol operations.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcd/#see-also","title":"SEE ALSO","text":"dtpcadmin(1), ion(3)
"},{"location":"man/dtpc/dtpcrc/","title":"NAME","text":"dtpcrc - Delay-Tolerant Payload Conditioning management commands file
"},{"location":"man/dtpc/dtpcrc/#description","title":"DESCRIPTION","text":"DTPC management commands are passed to dtpcadmin either in a file of text lines or interactively at dtpcadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the DTPC management commands are described below.
"},{"location":"man/dtpc/dtpcrc/#commands","title":"COMMANDS","text":"?
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 dtpcadmin 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
The initialize command. Until this command is executed, DTPC is not in operation on the local ION node and most dtpcadmin commands will fail.
a profile profileID maxRtx aggrSizeLimit aggrTimeLimit TTL class_of_service report_to_endpointID [statusReportFlags]
The add profile command. This command notes the definition of a single DPTC transmission profile. A transmission profile asserts the BP and DTPC configuration parameter values that will be applied to all application data items (encapsulated in DTPC application data units and transmitted in bundles) that are issued subject to this profile. Transmission profiles are globally defined; all transmission profiles must be provided, with identical parameter values, to all inter-communicating DTPC protocol entities.
profileID must be the positive integer that uniquely defines the profile.
maxRtx is the maximum number of times any single DTPC ADU transmitted subject to the indicated profile may be retransmitted by the DTPC entity. If maxRtx is zero, then the DTPC transport service features (in-order delivery, end-to-end acknowledgment, etc.) are disabled for this profile.
aggrSizeLimit is the size threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrSizeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
aggrTimeLimit is the time threshold for concluding aggregation of an outbound ADU and requesting transmission of that ADU. If aggrTimeLimit is zero, then the DTPC transmission optimization features (aggregation and elision) are disabled for this profile.
class_of_service is the class-of-service string as defined for bptrace(1).
report_to_endpointID identifies the BP endpoint to which all status reports generated from bundles transmitted subject to this profile will be sent.
statusReportFlags, if present, must be a sequence of status report flags, separated by commas, with no embedded whitespace. Each status report flag must be one of the following: rcv, ct, fwd, dlv, del.
d profile profileId
The delete profile command. This command erases the definition of the DTPC transmission profile identified by profileId.
i profile profileId
This command will print information (all configuration parameters) about the profile identified by profileId.
l profile
This command lists all known DTPC transmission profiles.
s
The start command. This command starts the DTPC clock and daemon tasks for the local BP node.
x
The stop command. This command stops all DTPC tasks and notifies all DTPC applications that DTPC service has been stopped.
w { 0 | 1 | <activity_spec> }
The DTPC watch command. This command enables and disables production of a continuous stream of user-selected DTPC activity indication characters. A watch parameter of \"1\" selects all DTPC activity indication characters; \"0\" de-selects all DTPC activity indication characters; any other activity_spec such as \"o<r>\" selects all activity indication characters in the string, de-selecting all others. DTPC will print each selected activity indication character to stdout every time a processing event of the associated type occurs:
o new aggregator created for profile and destination endpoint
\\< new ADU aggregation initiated
r application data item added to aggregation
\\> aggregation complete, outbound ADU created
- outbound ADU sent via BP
l ADU end-to-end acknowledgment sent
m ADU deleted due to TTL expiration
n ADU queued for retransmission
i inbound ADU collector created
u inbound ADU received
v ADU sequence gap detected
? inbound ADU discarded
* ADU sequence gap deleted due to impending ADU TTL expiration
$ inbound ADU collector reset
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a profile 5 6 1000000 5 3600 0.1 dtn:none
Notes the definition of DTPC transmission profile 5: transport services are enabled, with an end-to-end retransmission limit of 5; transmission optimization service is enabled, initiating bundle transmission whenever the aggregation of data items queued for transmission subject to this profile exceeds one million bytes or is more than five seconds old; the transmitted bundles will have one-hour lifetime, will not be subject to custody transfer, will be sent at \"standard\" priority, and will not be tracked by any bundle status report production.
dtpcadmin(1), bptrace(1)
"},{"location":"man/dtpc/dtpcreceive/","title":"NAME","text":"dtpcreceive - Delay-Tolerant Payload Conditioning reception test program
"},{"location":"man/dtpc/dtpcreceive/#synopsis","title":"SYNOPSIS","text":"dtpcreceive topic_ID
"},{"location":"man/dtpc/dtpcreceive/#description","title":"DESCRIPTION","text":"dtpcreceive uses DTPC to acquire application data items on topic topic_ID sent by dtpcsend. Upon termination it prints the total number of application data items received and the mean rate of application data transmission.
Use CTRL-C to terminate the program.
"},{"location":"man/dtpc/dtpcreceive/#exit-status","title":"EXIT STATUS","text":"0
dtpcreceive has terminated.
No configuration files are needed.
"},{"location":"man/dtpc/dtpcreceive/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcreceive/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcreceive/#see-also","title":"SEE ALSO","text":"dtpcsend(1), dtpc(3)
"},{"location":"man/dtpc/dtpcsend/","title":"NAME","text":"dtpcsend - Delay-Tolerant Payload Conditioning transmission test program
"},{"location":"man/dtpc/dtpcsend/#synopsis","title":"SYNOPSIS","text":"dtpcsend nbr_of_cycles rate payload_size topic_ID profile_ID destination_endpoint
"},{"location":"man/dtpc/dtpcsend/#description","title":"DESCRIPTION","text":"dtpcsend uses DTPC to send nbr_of_cycles application data items of payload_size bytes each on topic topic_ID to destination_endpoint using transmission profile profile_ID at rate bits per second.
rate must be between 1000 and 200 million bits per second.
payload_size must be between 2 and 1 million bytes. To use application data item sizes chosen at random from the range 1 to 65536, specify payload_size = 1.
NOTE that dtpcsend invokes an elision function that removes from the outbound DTPC aggregate ADU all records that are of the same size as the first record in that aggregation. This means that specifying any payload size other than 1 that is less than the configured DTPC aggregation size limit will cause DTPC to issue ADUs only when the aggregation time limit is exceeded, and each such ADU will always contain only a single record.
Use CTRL-C to terminate the program.
"},{"location":"man/dtpc/dtpcsend/#files","title":"FILES","text":"No configuration files are needed.
"},{"location":"man/dtpc/dtpcsend/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/dtpc/dtpcsend/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/dtpc/dtpcsend/#see-also","title":"SEE ALSO","text":"dtpcreceive(1), dtpc(3)
"},{"location":"man/ici/","title":"Index of Man Pages","text":"file2sdr - SDR data ingestion test program
"},{"location":"man/ici/file2sdr/#synopsis","title":"SYNOPSIS","text":"file2sdr configFlags fileName
"},{"location":"man/ici/file2sdr/#description","title":"DESCRIPTION","text":"file2sdr stress-tests SDR data ingestion by repeatedly writing all text lines of the file named fileName to one of a series of non-volatile linked lists created in a test SDR data store named \"testsdr_configFlags_\". By incorporating the data store configuration into the name (e.g., \"testsdr14\") we make it relatively easy to perform comparative testing on SDR data stores that are identical aside from their configuration settings.
The operation of file2sdr is cyclical: a new linked list is created each time the program finishes copying the file's text lines and starts over again. If you use ^C to terminate file2sdr and then restart it, the program resumes operation at the point where it left off.
After writing each line to the current linked list, file2sdr gives a semaphore to indicate that the list is now non-empty. This is mainly for the benefit of the complementary test program sdr2file(1).
At the end of each cycle file2sdr appends a final EOF line to the current linked list, containing the text \"*** End of the file ***\", and prints a brief performance report:
Processing I<lineCount> lines per second.\n\"0\"
file2sdr has terminated.
No configuration files are needed.
"},{"location":"man/ici/file2sdr/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/file2sdr/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by file2sdr are written to the ION log file ion.log.
Can't use sdr.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create semaphore.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
SDR transaction failed.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't open input file
Operating system error. Check errtext, correct problem, and rerun.
Can't reopen input file
Operating system error. Check errtext, correct problem, and rerun.
Can't read from input file
Operating system error. Check errtext, correct problem, and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/file2sdr/#see-also","title":"SEE ALSO","text":"sdr2file(1), sdr(3)
"},{"location":"man/ici/file2sm/","title":"NAME","text":"file2sm - shared-memory linked list data ingestion test program
"},{"location":"man/ici/file2sm/#synopsis","title":"SYNOPSIS","text":"file2sm fileName
"},{"location":"man/ici/file2sm/#description","title":"DESCRIPTION","text":"file2sm stress-tests shared-memory linked list data ingestion by repeatedly writing all text lines of the file named fileName to a shared-memory linked list that is the root object of a PSM partition named \"file2sm\".
After writing each line to the linked list, file2sm gives a semaphore to indicate that the list is now non-empty. This is mainly for the benefit of the complementary test program sm2file(1).
The operation of file2sm is cyclical. After copying all text lines of the source file to the linked list, file2sm appends an EOF line to the linked list, containing the text \"*** End of the file ***\", and prints a brief performance report:
Processing I<lineCount> lines per second.\nThen it reopens the source file and starts appending the file's text lines to the linked list again.
"},{"location":"man/ici/file2sm/#exit-status","title":"EXIT STATUS","text":"\"0\"
file2sm has terminated.
No configuration files are needed.
"},{"location":"man/ici/file2sm/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/file2sm/#diagnostics","title":"DIAGNOSTICS","text":"Can't attach to shared memory
Operating system error. Check errtext, correct problem, and rerun.
Can't manage shared memory.
PSM error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create shared memory list.
smlist error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't create semaphore.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Can't open input file
Operating system error. Check errtext, correct problem, and rerun.
Can't reopen input file
Operating system error. Check errtext, correct problem, and rerun.
Can't read from input file
Operating system error. Check errtext, correct problem, and rerun.
Ran out of memory.
Nominal behavior. sm2file is not extracting data from the linked list quickly enough to prevent it from growing to consume all memory allocated to the test partition.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/file2sm/#see-also","title":"SEE ALSO","text":"sm2file(1), smlist(3), psm(3)
"},{"location":"man/ici/ion/","title":"NAME","text":"ion - Interplanetary Overlay Network common definitions and functions
"},{"location":"man/ici/ion/#synopsis","title":"SYNOPSIS","text":"#include \"ion.h\"\n\n[see description for available functions]\nThe Interplanetary Overlay Network (ION) software distribution is an implementation of Delay-Tolerant Networking (DTN) architecture as described in Internet RFC 4838. It is designed to enable inexpensive insertion of DTN functionality into embedded systems such as robotic spacecraft. The intent of ION deployment in space flight mission systems is to reduce cost and risk in mission communications by simplifying the construction and operation of automated digital data communication networks spanning space links, planetary surface links, and terrestrial links.
The ION distribution comprises the following software packages:
ici (Interplanetary Communication Infrastructure), a set of general-purpose libraries providing common functionality to the other packages.
ltp (Licklider Transmission Protocol), a core DTN protocol that provides transmission reliability based on delay-tolerant acknowledgments, timeouts, and retransmissions.
dgr (Datagram Retransmission), a library that enables data to be transmitted via UDP with reliability comparable to that provided by TCP. DGR is an alternative implementation of LTP, designed for use within an internet.
bssp (Bundle Streaming Service Protocol), a protocol that supports delay-tolerant data streaming. BSSP delivers data in transmission order with minimum latency but possibly with omissions, for immediate display, and at the same time it delivers the same data reliably in background so that the streamed data can be \"rewound\" for possibly improved presentation.
bp (Bundle Protocol), a core DTN protocol that provides delay-tolerant forwarding of data through a network in which continuous end-to-end connectivity is never assured, including support for delay-tolerant dynamic routing. The Bundle Protocol (BP) specification is defined in Internet RFC 5050.
ams (Asynchronous Message Service), cfdp (CCSDS File Delivery Protocol), dtpc (Delay-Tolerant Payload Conditioning), and bss (Bundle Streaming Service), application-layer services that are not part of the DTN architecture but utilize underlying DTN protocols.
Taken together, the packages included in the ION software distribution constitute a communication capability characterized by the following operational features:
Reliable conveyance of data over a DTN, i.e., a network in which it might never be possible for any node to have reliable information about the detailed current state of any other node.
Built on this capability, reliable distribution of short messages to multiple recipients (subscribers) residing in such a network.
Management of traffic through such a network.
Facilities for monitoring the performance of the network.
Robustness against node failure.
Portability across heterogeneous computing platforms.
High speed with low overhead.
Easy integration with heterogeneous underlying communication infrastructure, ranging from Internet to dedicated spacecraft communication links.
While most of the ici package consists of libraries providing functionality that may be of general utility in any complex embedded software system, the functions and macros described below are specifically designed to support operations of ION's delay-tolerant networking protocol stack.
TIMESTAMPBUFSZ
This macro returns the recommended size of a buffer that is intended to contain a timestamp in ION-standard format:
yyyy/mm/dd-hh:mm:ss\nint ionAttach()
Attaches the invoking task to ION infrastructure as previously established by running the ionadmin utility program. Returns zero on success, -1 on any error.
void ionDetach()
Detaches the invoking task from ION infrastructure. In particular, releases handle allocated for access to ION's non-volatile database. NOTE, though, that ionDetach() has no effect when the invoking task is running in a non-memory-protected environment, such as VxWorks, where all ION resource access variables are shared by all tasks: no single task could detach without crashing all other ION tasks.
void ionProd(uvast fromNode, uvast toNode, unsigned int xmitRate, unsigned int owlt)
This function is designed to be called from an operating environment command or a fault protection routine, to enable operation of a node to resume when all of its scheduled contacts are in the past (making it impossible to use a DTN communication contact to assert additional future communication contacts). The function asserts a single new unidirectional contact conforming to the arguments provided, including the applicable one-way light time, with start time equal to the current time (at the moment of execution of the function) and end time equal to the start time plus 2 hours. The result of executing the function is written to the ION log using standard ION status message logging functions.
NOTE that the ionProd() function must be invoked twice in order to establish bidirectional communication.
void ionTerminate()
Shuts down the entire ION node, terminating all daemons. The state of the node is retained in the node's SDR heap.
int ionStartAttendant(ReqAttendant *attendant)
Initializes the semaphore in attendant so that it can be used for blocking ZCO space requisitions by ionRequestZcoSpace(). Returns 0 on success, -1 on any error.
void ionPauseAttendant(ReqAttendant *attendant)
\"Ends\" the semaphore in attendant so that the task that is blocked on taking it is interrupted and may respond to an error or shutdown condition.
void ionResumeAttendant(ReqAttendant *attendant)
Reinitializes the semaphore in attendant so that it can again be used for blocking ZCO space requisitions.
void ionStopAttendant(ReqAttendant *attendant)
Destroys the semaphore in attendant, preventing a potential resource leak.
int ionRequestZcoSpace(ZcoAcct acct, vast fileSpaceNeeded, vast bulkSpaceNeeded, vast heapSpaceNeeded, unsigned char coarsePriority, unsigned char finePriority, ReqAttendant *attendant, ReqTicket *ticket)
Lodges a request for ZCO space in the pool identified by acct. If the requested space can be provided immediately, it is reserved for use by the calling task. Otherwise, if attendant is non-NULL then the request is queued for service when space becomes available. In any case, *ticket is set to the address of a \"ticket\" referencing this request. The status of the request can be interrogated by calling ionSpaceAwarded(). If this function returns 1 (True) then ZCO space may be consumed immediately and the ticket must then be destroyed by a call to ionShred(). Otherwise, if an attendant was provided, then the calling task should pend on the semaphore in attendant and upon successfully taking the semaphore it must consume the requested ZCO space and then ionShred() the ticket. Otherwise the request for ZCO space has been definitively denied and, as always, the ticket must by destroyed by an invocation of ionShred(). Returns 0 on success, -1 on any failure.
int ionSpaceAwarded(ReqTicket *ticket)
Returns 1 if ticket is for a ZCO space request that has been serviced (ZCO space has been reserved per this request), 0 otherwise.
void ionShred(ReqTicket *ticket)
Dismisses the reservation of ZCO space (if any) requested by the call to ionRequestZcoSpace() that returned ticket. Calling ionShred() indicates either that the requested space was reserved (i.e., the request was \"serviced\") and has been claimed (consumed by the appending of a ZCO extent) or that the request has been canceled. Note that failure to promptly (within 3 seconds of reception) ionShred() the ticket for a service request will be interpreted as refusal of the reserved ZCO space, resulting in that space being made available for use by other tasks.
Object ionCreateZco(ZcoMedium source, Object location, vast offset, vast length, unsigned char coarsePriority, unsigned char finePriority, ZcoAcct acct, ReqAttendant *attendant)
This function provides a \"blocking\" implementation of admission control in ION. Like zco_create(), it constructs a zero-copy object (see zco(3)) that contains a single extent of source data residing at location in source, of which the first offset bytes are omitted and the next length bytes are included. But unlike zco_create(), ionCreateZco() can be configured to block (rather than return an immediate error indication) so long as the total amount of space in source that is available for new ZCO formation is less than length. ionCreateZco() operates by calling ionRequestZcoSpace(), then pending on the semaphore in attendant as necessary before creating the ZCO. ionCreateZco() returns when either (a) space has become available and the ZCO has been created, in which case the location of the ZCO is returned, or (b) the function has failed (in which case ((Object) -1) is returned), or (c) either attendant was null and sufficient space for the first extent of the ZCO was not immediately available or else the function was interrupted by ionPauseAttendant() before space for the ZCO became available (in which case 0 is returned).
vast ionAppendZcoExtent(Object zco, ZcoMedium source, Object location, vast offset, vast length, unsigned char coarsePriority, unsigned char finePriority, ReqAttendant *attendant)
Similar to ionCreateZco() except that instead of creating a new ZCO it appends an additional extent to an existing ZCO. Returns -1 on failure, 0 on interruption by ionPauseAttendant() or if attendant was NULL and sufficient space for the extent was not immediately available, length on success.
char *getIonVersionNbr()
Returns the name of the ION version installed on the local machine.
Sdr getIonsdr()
Returns a pointer to the SDR management object, previously acquired by calling ionAttach(), or zero on any error.
PsmPartition getIonwm()
Returns a pointer to the ION working memory partition, previously acquired by calling ionAttach(), or zero on any error.
int getIonMemoryMgr()
Returns the memory manager ID for operations on ION's working memory partition, previously acquired by calling ionAttach(), or -1 on any error.
int ionLocked();
Returns 1 if the calling task is the owner of the current SDR transaction. Assuring that ION is locked while related critical operations are performed is essential to the avoidance of race conditions.
uvast getOwnNodeNbr()
Returns the Bundle Protocol node number identifying this node, as declared when ION was initialized by ionadmin.
time_t getCtime()
Returns the current calendar (i.e., Unix epoch) time, as computed from local clock time and the computer's current offset from UTC (due to clock drift, not due to time zone difference; the utcdelta) as managed from ionadmin.
int ionClockIsSynchronized()
Returns 1 if the computer on which the local ION node is running has a synchronized clock , i.e., a clock that reports the current calendar (i.e., Unix epoch) time as a value that differs from the correct calendar time by an interval approximately equal to the currently asserted offset from UTC due to clock drift; returns zero otherwise.
If the machine's clock is synchronized then its reported values (as returned by getCtime()) can safely be used as the creation times of new bundles and the expiration time of such a bundle can accurately be computed as the sum of the bundle's creation time and time to live. If not, then the creation timestamp time of new bundles sourced at the local ION node must be zero and the creation timestamp sequence numbers must increase monotonically forever, never rolling over to zero.
void writeTimestampLocal(time_t timestamp, char *timestampBuffer)
Expresses the time value in timestamp as a local timestamp string in ION-standard format, as noted above, in timestampBuffer.
void writeTimestampUTC(time_t timestamp, char *timestampBuffer)
Expresses the time value in timestamp as a UTC timestamp string in ION-standard format, as noted above, in timestampBuffer.
time_t readTimestampLocal(char *timestampBuffer, time_t referenceTime)
Parses the local timestamp string in timestampBuffer and returns the corresponding calendar (i.e., Unix epoch) time value (as would be returned by time(2)), or zero if the timestamp string cannot be parsed successfully. The timestamp string is normally expected to be an absolute expression of local time in ION-standard format as noted above. However, a relative time expression variant is also supported: if the first character of timestampBuffer is '+' then the remainder of the string is interpreted as a count of seconds; the sum of this value and the time value in referenceTime is returned.
time_t readTimestampUTC(char *timestampBuffer, time_t referenceTime)
Same as readTimestampLocal() except that if timestampBuffer is not a relative time expression then it is interpreted as an absolute expression of UTC time in ION-standard format as noted above.
ION uses writeMemo(), putErrmsg(), and putSysErrmsg() to log several different types of standardized status messages.
Informational messages
These messages are generated to inform the user of the occurrence of events that are nominal but significant, such as the controlled termination of a daemon or the production of a congestion forecast. Each informational message has the following format:
{_yyyy/mm/dd hh:mm:ss_} \\[i\\] _text_\nWarning messages
These messages are generated to inform the user of the occurrence of events that are off-nominal but are likely caused by configuration or operational errors rather than software failure. Each warning message has the following format:
{_yyyy/mm/dd hh:mm:ss_} \\[?\\] _text_\nDiagnostic messages
These messages are produced by calling putErrmsg() or putSysErrmsg(). They are generated to inform the user of the occurrence of events that are off-nominal and might be due to errors in software. The location within the ION software at which the off-nominal condition was detected is indicated in the message:
{_yyyy/mm/dd hh:mm:ss_} at line _nnn_ of _sourcefilename_, _text_ (_argument_)\nNote that the argument portion of the message (including its enclosing parentheses) will be provided only when an argument value seems potentially helpful in fault analysis.
Bundle Status Report (BSR) messages
A BSR message informs the user of the arrival of a BSR, a Bundle Protocol report on the status of some bundle. BSRs are issued in the course of processing bundles for which one or more status report request flags are set, and they are also issued when bundles for which custody transfer is requested are destroyed prior to delivery to their destination endpoints. A BSR message is generated by ipnadminep upon reception of a BSR. The time and place (node) at which the BSR was issued are indicated in the message:
{_yyyy/mm/dd hh:mm:ss_} \\[s\\] (_sourceEID_)/_creationTimeSeconds_:_counter_/_fragmentOffset_ status _flagsByte_ at _time_ on _endpointID_, '_reasonString_'.\nCommunication statistics messages
A network performance report is a set of eight communication statistics messages, one for each of eight different types of network activity. A report is issued every time contact transmission or reception starts or stops, except when there is no activity of any kind on the local node since the prior report. When a report is issued, statistic messages are generated to summarize all network activity detected since the prior report, after which all network activity counters and accumulators are reset to zero.
NOTE also that the bpstats utility program can be invoked to issue an interim network performance report at any time. Issuance of interim status reports does not cause network activity counters and accumulators to be reset to zero.
Statistics messages have the following format:
{_yyyy/mm/dd hh:mm:ss_} \\[x\\] _xxx_ from _tttttttt_ to _TTTTTTTT_: (0) _aaaa_ _bbbbbbbbbb_ (1) _cccc_ _dddddddddd_ (2) _eeee_ _ffffffffff_ (+) _gggg_ _hhhhhhhhhh_\nxxx indicates the type of network activity that the message is reporting on. Statistics for eight different types of network activity are reported:
src
This message reports on the bundles sourced at the local node during the indicated interval.
fwd
This message is about routing; it reports on the number of bundles queued for forwarding to neighboring nodes as selected by the routing procedure. When a bundle must be re-forwarded due to convergence-layer transmission failure it is counted a second time here.
xmt
This message reports on the bundles passed to the convergence layer protocol(s) for transmission from this node. Again, a re-forwarded bundle that is then re-transmitted at the convergence layer is counted a second time here.
rcv
This message reports on the bundles from other nodes that were received at the local node.
dlv
This message reports on the bundles delivered to applications via endpoints on the local node.
ctr
This message reports on the custody refusal signals received at the local node.
rfw
This message reports on bundles for which convergence-layer transmission failed at this node, causing the bundles to be re-forwarded.
exp
This message reports on the bundles destroyed at this node due to TTL expiration.
tttttttt and TTTTTTTT indicate the start and end times of the interval for which statistics are being reported, expressed in yyyy/mm/dd-hh:mm:ss format. TTTTTTTT is the current time and tttttttt is the time of the prior report.
Each of the four value pairs following the colon (:) reports on the number of bundles counted for the indicated type of network activity, for the indicated traffic flow, followed by the sum of the sizes of the payloads of all those bundles. The four traffic flows for which statistics are reported are \"(0)\" the priority-0 or \"bulk\" traffic, \"(1)\" the priority-1 \"standard\" traffic, \"(2)\" the priority-2 \"expedited\" traffic, and \"(+)\" the total for all classes of service.
Free-form messages
Other status messages are free-form, except that date and time are always noted just as for the documented status message types.
ionadmin(1), rfxclock(1), bpstats(1), llcv(3), lyst(3), memmgr(3), platform(3), psm(3), sdr(3), zco(3), ltp(3), bp(3), cfdp(3), ams(3), bss(3)
"},{"location":"man/ici/ionadmin/","title":"NAME","text":"ionadmin - ION node administration interface
"},{"location":"man/ici/ionadmin/#synopsis","title":"SYNOPSIS","text":"ionadmin [ commands_filename | . | ! ]
"},{"location":"man/ici/ionadmin/#description","title":"DESCRIPTION","text":"ionadmin configures, starts, manages, and stops the ION node on the local computer.
It configures the node and sets (and reports on) global operational settings for the DTN protocol stack on the local computer in response to ION configuration commands found in commands_filename, if provided; if not, ionadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to ionadmin -- that is, the ION node's rfxclock task is stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's rfxclock task is restarted.
The format of commands for commands_filename can be queried from ionadmin by entering the command 'h' or '?' at the prompt. The commands are documented in ionrc(5).
Note that ionadmin always computes a congestion forecast immediately before exiting. The result of this forecast -- maximum projected occupancy of the DTN protocol traffic allocation in ION's SDR database -- is retained for application flow control purposes: if maximum projected occupancy is the entire protocol traffic allocation, then a message to this effect is logged and no new bundle origination by any application will be accepted until a subsequent forecast that predicts no congestion is computed. (Congestion forecasts are constrained by horizon times, which can be established by commands issued to ionadmin. One way to re-enable data origination temporarily while long-term traffic imbalances are being addressed is to declare a congestion forecast horizon in the near future, before congestion would occur if no adjustments were made.)
"},{"location":"man/ici/ionadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of ION node administration.
ionadmin
Enter interactive ION configuration command entry mode.
ionadmin host1.ion
Execute all configuration commands in host1.ion, then terminate immediately.
Status and diagnostic messages from ionadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which ionadmin was run. The log file is typically named ion.log.
See also ionconfig(5) and ionrc(5).
"},{"location":"man/ici/ionadmin/#environment","title":"ENVIRONMENT","text":"Environment variables ION_NODE_LIST_DIR and ION_NODE_WDNAME can be used to enable the operation of multiple ION nodes on a single workstation computer. See section 2.1.3 of the ION Design and Operations Guide for details.
"},{"location":"man/ici/ionadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ionadmin. Otherwise ionadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
ionadmin SDR definition failed.
A node initialization command was executed, but an SDR database already exists for the indicated node. It is likely that an ION node is already running on this computer or that destruction of a previously started the previous ION node was incomplete. For most ION installations, incomplete node destruction can be repaired by (a) killing all ION processes that are still running and then (b) using ipcrm to remove all SVr4 IPC objects owned by ION.
ionadmin can't get SDR parms.
A node initialization command was executed, but the ion_config_filename passed to that command contains improperly formatted commands. Please see ionconfig(5) for further details.
Various errors that don't cause ionadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see ionrc(5) for details.
"},{"location":"man/ici/ionadmin/#bugs","title":"BUGS","text":"If the ion_config_filename parameter passed to a node initialization command refers to a nonexistent filename, then ionadmin uses default values are used rather than reporting an error in the command line argument.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionadmin/#see-also","title":"SEE ALSO","text":"ionrc(5), ionconfig(5)
"},{"location":"man/ici/ioncbor/","title":"NAME","text":"cbor - ION library for encoding and decoding CBOR data representations
"},{"location":"man/ici/ioncbor/#synopsis","title":"SYNOPSIS","text":"#include \"cbor.h\"\nION's \"cbor\" library implements a subset of the Concise Binary Object Representation (CBOR) standard, RFC 7049; only those data types used in ION code are implemented. Unlike other CBOR implementations, ION CBOR is specifically intended for compatibility with zero-copy objects, i.e., the data being decoded need not all be in a memory buffer.
For all functions, *cursor is a pointer to the location in the CBOR coding buffer at which bytes are to be encoded or decoded. This pointer is automatically advanced as the encoding or decoding operation is performed.
Most of the ION CBOR decoding functions entail the decoding of unsigned integers. The invoking code may require that an integer representation have a specific size by indicating the integer size \"class\" that is required. Class -1 indicates that an integer of any size is acceptable; the other classes (0, 1, 2, 4, 8) indicate the number of bytes of integer data that MUST follow the integers initial byte.
int cbor_encode_integer(uvast value, unsigned char **cursor)
Represent this value in an integer of the smallest possible integer class. Cursor is automatically advanced. Returns number of bytes written.
int cbor_encode_fixed_int(uvast value, int class, unsigned char **cursor)
Represent this value in an integer of the indicated class. Cursor is automatically advanced. Returns number of bytes written, 0 on encoding error.
int cbor_encode_byte_string(unsigned char *value, uvast size, unsigned char **cursor)
size is the number of bytes to write. If value is NULL, only the size of the byte string is written; otherwise the byte string itself is written as well. Cursor is advanced by the number of bytes written in either case. Returns number of bytes written.
int cbor_encode_text_string(char *value, uvast size, unsigned char **cursor)
size is the number of bytes to write. If value is NULL, only the size of the text string is written; otherwise the text string itself is written as well. Cursor is advanced by the number of bytes written in either case. Returns number of bytes written.
int cbor_encode_array_open(uvast size, unsigned char **cursor)
If size is ((uvast) -1), the array is of indefinite size; otherwise size indicates the number of items in the array. Cursor is automatically advanced. Returns number of bytes written.
int cbor_encode_break(unsigned char **cursor)
Break code is written at the indicated location. Cursor is automatically advanced. Returns number of bytes written (always 1).
int cbor_decode_initial_byte(unsigned char **cursor, unsigned int *bytesBuffered, int *majorType, int *additionalInfo)
This function just extracts major type and additional info from the byte identified by cursor. Cursor is automatically advanced. Returns number of bytes decoded (always 1) or 0 on decoding error (e.g., no byte to decode).
int cbor_decode_integer( uvast *value, int class, unsigned char **cursor, unsigned int *bytesBuffered)
If class is CborAny, any class of data item is accepted; otherwise only an integer data item of the indicated class is accepted. Cursor is automatically advanced. Returns number of bytes read, 0 on decoding error (e.g., integer is of the wrong class).
int cbor_decode_byte_string(unsigned char *value, uvast *size, unsigned char **cursor, unsigned int *bytesBuffered)
Initial value of size is the maximum allowable size of the decoded byte string; the actual number of bytes in the byte string (which, NOTE, is less than the number of bytes read) is returned in size. If value is non-NULL, the decoded byte string is copied into value and cursor is automatically advanced to the end of the byte string; otherwise, cursor is advanced only to the beginning of the byte string. Returns number of bytes read, 0 on decoding error (e.g., byte string exceeds maximum size).
int cbor_decode_text_string(char *value, uvast *size, unsigned char **cursor, unsigned int *bytesBuffered)
Initial value of size is the maximum allowable size of the decoded text string; the actual number of bytes in the text string (which, NOTE, is less than the number of bytes read) is returned in size. If value is non-NULL, the decoded text string is copied into value and cursor is automatically advanced to the end of the text string; otherwise, cursor is advanced only to the beginning of the text string. Returns number of bytes read, 0 on decoding error (e.g., text string exceeds maximum size).
int cbor_decode_array_open(uvast *size, unsigned char **cursor, unsigned int *bytesBuffered)
If size is zero, any array is accepted and the actual size of the decoded array is returned in size; ((uvast) -1) is returned in size if the array is of indefinite size. If size is ((uvast) -1), only an array of indefinite length is accepted. Otherwise, size indicates the required number of items in the array. Cursor is automatically advanced. Returns number of bytes read, 0 on decoding error (such as wrong number of items).
int cbor_decode_break(unsigned char **cursor, unsigned int *bytesBuffered)
Break code is read from the indicated location. Cursor is automatically advanced. Returns number of bytes read, 0 on decoding error (e.g., no break character at this location).
ionconfig - ION node configuration parameters file
"},{"location":"man/ici/ionconfig/#description","title":"DESCRIPTION","text":"ION node configuration parameters are passed to ionadmin in a file of parameter name/value pairs:
parameter_name parameter_value
Any line of the file that begins with a '#' character is considered a comment and is ignored.
ionadmin supplies default values for any parameters for which no value is provided in the node configuration parameters file.
The applicable parameters are as follows:
sdrName
This is the character string by which this ION node's SDR database will be identified. (Note that the SDR database infrastructure enables multiple databases to be constructed on a single host computer.) The default value is \"ion\".
sdrWmSize
This is the size of the block of dynamic memory that will be reserved as private working memory for the SDR system itself. A block of system memory of this size will be allocated (e.g., by malloc()) at the time the SDR system is initialized on the host computer. The default value is 1000000 (1 million bytes).
configFlags
This is the bitwise \"OR\" (i.e., the sum) of the flag values that characterize the SDR database to use for this ION node. The default value is 13 (that is, SDR_IN_DRAM | SDR_REVERSIBLE | SDR_BOUNDED). The SDR configuration flags are documented in detail in sdr(3). To recap:
SDR_IN_DRAM (1)
The SDR is implemented in a region of shared memory. [Possibly with write-through to a file, for fault tolerance.]
SDR_IN_FILE (2)
The SDR is implemented as a file. [Possibly cached in a region of shared memory, for faster data retrieval.]
SDR_REVERSIBLE (4)
Transactions in the SDR are written ahead to a log, making them reversible.
SDR_BOUNDED (8)
SDR heap updates are not allowed to cross object boundaries.
heapKey
This is the shared-memory key by which the pre-allocated block of shared dynamic memory to be used as heap space for this SDR can be located, if applicable. The default value is -1, i.e., not specified and not applicable.
pathName
This is the fully qualified path name of the directory in which are located (a) the file to be used as heap space for this SDR (which will be created, if it doesn't already exist), in the event that the SDR is to be implemented in a file, and (b) the file to be used to log the database updates of each SDR transaction, in the event that transactions in this SDR are to be reversible. The default value is /tmp.
heapWords
This is the number of words (of 32 bits each on a 32-bit machine, 64 bits each on a 64-bit machine) of nominally non-volatile storage to use for ION's SDR database. If the SDR is to be implemented in shared memory and no heapKey is specified, a block of shared memory of this size will be allocated (e.g., by malloc()) at the time the node is created. If the SDR is to be implemented in a file and no file named ion.sdr exists in the directory identified by pathName, then a file of this name and size will be created in this directory and initialized to all binary zeroes. The default value is 250000 words (1 million bytes on a 32-bit computer).
logSize
This is the number of bytes of shared memory to use for ION's SDR transaction log. If zero (the default), the transaction log is written to a file rather than to memory. If the log is to be implemented in shared memory and no logKey is specified, a block of shared memory of this size will be allocated (e.g., by malloc()) at the time the node is created.
logKey
This is the shared-memory key by which the pre-allocated block of shared dynamic memory to be used for the transaction log for this SDR can be located, if applicable. The default value is -1, i.e., not specified and not applicable.
wmKey
This is the shared-memory key by which this ION node's working memory will be identified. The default value is 65281.
wmAddress
This is the address of the block of dynamic memory -- volatile storage, which is not expected to persist across a system reboot -- to use for this ION node's working memory. If zero, the working memory block will be allocated from system memory (e.g., by malloc()) at the time the local ION node is created. The default value is zero.
wmSize
This is the size of the block of dynamic memory that will be used for this ION node's working memory. If wmAddress is zero, a block of system memory of this size will be allocated (e.g., by malloc()) at the time the node is created. The default value is 5000000 (5 million bytes).
configFlags 1
heapWords 2500000
heapKey -1
pathName /usr/ion
wmSize 5000000
wmAddress 0
"},{"location":"man/ici/ionconfig/#see-also","title":"SEE ALSO","text":"ionadmin(1)
"},{"location":"man/ici/ioncrc/","title":"NAME","text":"crc - ION library for computing several types of checksums.
"},{"location":"man/ici/ioncrc/#synopsis","title":"SYNOPSIS","text":"#include \"crc.h\"\nION's \"crc\" library implements functions for computing four types of checksums: X.25 (16-bit), bzip2 (32-bit), CRC32 (32-bit), and CRC32C (32-bit).
All checksum computation functions were provided by Antara Teknik, LLC.
uint16_t ion_CRC16_1021_X25(const char *data, uint32_t dLen, uint16_t crc)
Computes the CRC16 value for poly 0x1021. data points to the data block over which the checksum value is to be computed, len must be the length of that data block, and crc is the current value of the checksum that is being incrementally computed over a multi-block extent of data (zero for the first block of this extent, or if this block is the entire extent).
uint32_t ion_CRC32_04C11DB7_bzip2(const char *data, uint32_t dLen, uint32_t crc)
Computes the bzip2 CRC32 checksum value for poly 0x04c11db7. data points to the data block over which the checksum value is to be computed, len must be the length of that data block, and crc is the current value of the checksum that is being incrementally computed over a multi-block extent of data (zero for the first block of this extent, or if this block is the entire extent).
uint32_t ion_CRC32_04C11DB7(const char *data, uint32_t dLen, uint32_t crc)
Computes the ISO-HDLC CRC32 value for poly 0x04c11db7. data points to the data block over which the checksum value is to be computed, len must be the length of that data block, and crc is the current value of the checksum that is being incrementally computed over a multi-block extent of data (zero for the first block of this extent, or if this block is the entire extent).
uint32_t ion_CRC32_1EDC6F41_C(const char *data, uint32_t dLen, uint32_t crc)
Computes the CRC32C value for poly 0x1edc6f41. data points to the data block over which the checksum value is to be computed, len must be the length of that data block, and crc is the current value of the checksum that is being incrementally computed over a multi-block extent of data (zero for the first block of this extent, or if this block is the entire extent).
ionlog - utility for redirecting stdin to the ION log file
"},{"location":"man/ici/ionlog/#synopsis","title":"SYNOPSIS","text":"ionlog
"},{"location":"man/ici/ionlog/#description","title":"DESCRIPTION","text":"The ionlog program simply reads lines of text from stdin and uses writeMemo to copy them into the ion.log file. It terminates when it reaches EOF in stdin.
"},{"location":"man/ici/ionlog/#exit-status","title":"EXIT STATUS","text":"\"0\"
ionlog has terminated successfully.
No configuration files are needed.
"},{"location":"man/ici/ionlog/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/ionlog/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ionlog unable to attach to ION.
Probable operations error: ION appears not to be initialized, in which case there is no point in running ionlog.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionlog/#see-also","title":"SEE ALSO","text":"amslogprt(1)
"},{"location":"man/ici/ionrc/","title":"NAME","text":"ionrc - ION node management commands file
"},{"location":"man/ici/ionrc/#description","title":"DESCRIPTION","text":"ION node management commands are passed to ionadmin either in a file of text lines or interactively at ionadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the ION node management commands are described below.
"},{"location":"man/ici/ionrc/#time-representation","title":"TIME REPRESENTATION","text":"For many ION node management commands, time values must be passed as arguments. Every time value may be represented in either of two formats. Absolute time is expressed as:
yyyy/mm/dd-hh:mm:ss
Relative time (a number of seconds following the current reference time, which defaults to the current time at the moment ionadmin began execution but which can be overridden by the at command described below) is expressed as:
+ss
"},{"location":"man/ici/ionrc/#commands","title":"COMMANDS","text":"?
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 ionadmin 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 node_number [ { ion_config_filename | '.' | '' } ]
The initialize command. Until this command is executed, the local ION node does not exist and most ionadmin commands will fail.
The command configures the local node to be identified by node_number, a CBHE node number which uniquely identifies the node in the delay-tolerant network. It also configures ION's data space (SDR) and shared working-memory region. For this purpose it uses a set of default settings if no argument follows node_number or if the argument following node_number is ''; otherwise it uses the configuration settings found in a configuration file. If configuration file name '.' is provided, then the configuration file's name is implicitly \"hostname.ionconfig\"; otherwise, ion_config_filename is taken to be the explicit configuration file name. Please see ionconfig(5) for details of the configuration settings.
For example:
1 19 ''\nwould initialize ION on the local computer, assigning the local ION node the node number 19 and using default values to configure the data space and shared working-memory region.
@ time
The at command. This is used to set the reference time that will be used for interpreting relative time values from now until the next revision of reference time. Note that the new reference time can be a relative time, i.e., an offset beyond the current reference time.
^ region_number
The region command. This is used to select the region to which all ensuing \"contact\" operations (until this execution of ionadmin terminates, or until the next region command is processed) pertain. A region is an arbitarily managed set of nodes that customarily are able to use contact graph routing to compute forwarding routes among themselves, and which consequently share a common contact plan. As such, there is a one-to-one correspondence between regions and contact plans, so in effect the region command is used to switch between contact plans. Regions are notionally quite small sets (on the order of 16-32 nodes) because contact graph routing is computationally intensive.
Information regarding up to two (2) regions may be managed at any single node.
By default, region number 1 (the \"universal\" region) is selected.
! [0 | 1]
\"Announce\" control. Setting the announce flag to 1 causes contact plan updates (contact add/change/delete, range add/delete) to be multicast to all other nodes in the region in addition to being processed at the local node. Setting the announce flag to 0 disables this behavior.
a contact start_time stop_time source_node dest_node xmit_data_rate [confidence]
The add contact command. This command schedules a period of data transmission from source_node to dest_node. The period of transmission will begin at start_time and end at stop_time, and the rate of data transmission will be xmit_data_rate bytes/second. Our confidence in the contact defaults to 1.0, indicating that the contact is scheduled - not that non-occurrence of the contact is impossible, just that occurrence of the contact is planned and scheduled rather than merely imputed from past node behavior. In the latter case, confidence indicates our estimation of the likelihood of this potential contact.
The period of time between the start and stop times of a contact is termed the contact's \"interval\". The intervals of scheduled contacts are not allowed to overlap.
Commands pertaining to three different types of contact can be intermixed within an .ionrc file that defines a contact plan.
1 Registration
When start_time is \"-1\", the contact signifies the \"registration\" of a node in the region corresponding to the contact plan of which this contact is a part. In this case, source_node and dest_node must be identical and non-zero. A registration contact simply affirms the source node's permanent membership in this region, persisting even during periods when the node is able neither to send nor to receive data. When inserted into the contact plan, the contact's start and stop times are both automatically set to the maximum POSIX time, its data rate is set to zero, and its confidence value is set to 1.0.
2 Hypothetical
When stop_time is \"0\", the contact is \"hypothetical\". A hypothetical contact is an anticipated opportunity for the local node to transmit data to, or receive data from, some potentially neighboring node in the same region. The nature of that contact is completely unknown; if and when the contact occurs, the hypothetical contact will be transformed into a \"discovered\" contact for the duration of the opportunity, after which it will revert to being hypothetical. source_node and dest_node must NOT be identical, and one or the other must identify the local node. When inserted into the contact plan, the contact's start time is automatically set to zero, its stop time is set to the maximum POSIX time, its data rate is set to zero, and its confidence value is set to 0.0.
3 Scheduled
Otherwise, the contact is \"scheduled\". A scheduled contact is a managed opportunity to transmit data between nodes, as inferred (for example) from a spacecraft or ground station operating plan. start_time must be less than stop_time and data_rate and confidence must both be greater than zero.
c contact start_time source_node dest_node xmit_data_rate [confidence]
The change contact command. This command changes the data transmission rate and possibly our level of confidence in the scheduled period of data transmission from source_node to dest_node starting at start_time. Registration and hypothetical contacts cannot be changed.
d contact start_time source_node dest_node
The delete contact command. This command deletes the contact from source_node to dest_node starting at start_time. To delete all scheduled contacts between some pair of nodes, use '*' as start_time. To delete a registration contact, use \"-1\" as start_time. To delete a hypothetical contact, use \"0\" as start_time.
i contact start_time source_node dest_node
This command will print information (stop time, data rate, confidence) about the scheduled period of transmission from source_node to dest_node that starts at start_time.
l contact
This command lists all contacts in the contact plan for the selected region.
b contact
The brief contacts command. This command writes a file of commands that will recreate the current list of contacts, for the selected region, in the node's ION database. The name of the file will be \"contacts.region_number.ionrc\".
a range start_time stop_time one_node the_other_node distance
The add range command. This command predicts a period of time during which the distance from one_node to the_other_node will be constant to within one light second. The period will begin at start_time and end at stop_time, and the distance between the nodes during that time will be distance light seconds.
NOTE that the ranges declared by these commands are directional. ION does not automatically assume that the distance from node A to node B is the same as the distance from node B to node A. While this symmetry is certainly true of geographic distance, the range that concerns ION is the latency in propagating a signal from one node to the other; this latency may be different in different directions because (for example) the signal from B to A might need to be forwarded along a different convergence-layer network path from the one used for the signal from A to B.
For this reason, the range identification syntax for this command is asymmetrical: ION interprets an add range command in which the node number of the first cited node is numerically less than that of the second cited node as implicitly declaring the same distance in the reverse direction (the normal case) UNLESS a second range command is present that cites the same two nodes in the opposite order, which overrides the implicit declaration. A range command in which the node number of the first cited node is numerically greater than that of the second cited node implies ABSOLUTELY NOTHING about the distance in the reverse direction.
d range start_time one_node the_other_node
The delete range command. This command deletes the predicted period of constant distance between one_node and the_other_node starting at start_time. To delete all ranges between some pair of nodes, use '*' as start_time.
NOTE that the range identification syntax for this command is asymmetrical, much as described for the add range command described above. ION interprets a delete range command in which the node number of the first cited node is numerically less than that of the second cited node as implicitly requesting deletion of the range in the opposite direction as well. A delete range command in which the node number of the first cited node is numerically greater than that of the second cited node deletes only the range in that direction; the asserted range in the opposite direction is unaffected.
i range start_time one_node the_other_node
This command will print information (the stop time and range) about the predicted period of constant distance between one_node and the_other_node that starts at start_time.
l range
This command lists all predicted periods of constant distance.
b range
The brief ranges command. This command writes a file of commands that will recreate the current list of ranges in the node's ION database. The file's name will be \"ranges.ionrc\".
m utcdelta local_time_sec_after_UTC
This management command sets ION's understanding of the current difference between correct UTC time and the localtime equivalent of the current calendar (i.e., Unix epoch) time as reported by the clock for the local ION node's computer. This delta is automatically applied to locally obtained time values whenever ION needs to know the current time. For machines that are synchronized by NTP, the value of this delta should be 0, the default.
Note that the purpose of the UTC delta is not to correct for time zone differences (which operating systems often do natively) but rather to compensate for error (drift) in clocks, particularly spacecraft clocks. The hardware clock on a spacecraft might gain or lose a few seconds every month, to the point at which its understanding of the current time - as reported out by the operating system and converted to UTC - might differ significantly from the actual value of UTC as reported by authoritative clocks on Earth. To compensate for this difference without correcting the clock itself (which can be difficult and dangerous), ION simply adds the UTC delta to the calendar time reported by the operating system.
Note that this means that setting the UTC delta is not a one-time node configuration activity but rather an ongoing node administration chore, because a drifting clock typically keeps on drifting.
m clockerr known_maximum_clock_error
This management command sets ION's understanding of the accuracy of the scheduled start and stop times of planned contacts, in seconds. The default value is 1. When revising local data transmission and reception rates, ionadmin will adjust contact start and stop times by this interval to be sure not to send bundles that arrive before the neighbor expects data arrival or to discard bundles that arrive slightly before they were expected.
m clocksync [ { 1 | 0 } ]
This management command reports whether or not the computer on which the local ION node is running has a synchronized clock, as discussed in the description of the ionClockIsSynchronized() function (ion(3)).
If a Boolean argument is provided when the command is executed, the characterization of the machine's clock is revised to conform with the asserted value. The default value is 1.
m production planned_data_production_rate
This management command sets ION's expectation of the mean rate of continuous data origination by local BP applications throughout the period of time over which congestion forecasts are computed, in bytes per second. For nodes that function only as routers this variable will normally be zero. A value of -1, which is the default, indicates that the rate of local data production is unknown; in that case local data production is not considered in the computation of congestion forecasts.
m consumption planned_data_consumption_rate
This management command sets ION's expectation of the mean rate of continuous data delivery to local BP applications throughout the period of time over which congestion forecasts are computed, in bytes per second. For nodes that function only as routers this variable will normally be zero. A value of -1, which is the default, indicates that the rate of local data consumption is unknown; in that case local data consumption is not considered in the computation of congestion forecasts.
m inbound heap_occupancy_limit [file_system_occupancy_limit]
This management command sets the maximum number of megabytes of storage space in ION's SDR non-volatile heap, and/or in the local file system, that can be used for the storage of inbound zero-copy objects. A value of -1 for either limit signifies \"leave unchanged\". The default heap limit is 30% of the SDR data space's total heap size. The default file system limit is 1 Terabyte.
m outbound heap_occupancy_limit [file_system_occupancy_limit]
This management command sets the maximum number of megabytes of storage space in ION's SDR non-volatile heap, and/or in the local file system, that can be used for the storage of outbound zero-copy objects. A value of -1 for either limit signifies \"leave unchanged\". The default heap limit is 30% of the SDR data space's total heap size. The default file system limit is 1 Terabyte.
m search max_free_blocks_to_search_through
This management command sets the limit on the number of free blocks the heap space allocation function will search through in the nominal free space bucket, looking for a sufficiently large free block, before giving up and switching to the next higher non-empty free space bucket. The default value is 0, which yields the highest memory management speed but may leave heap space under-utilized: data objects may be stored in unnecessarily large heap space blocks. Increasing the value of the heap space search limit will manage space more efficiently - with less waste - but more slowly.
m horizon { 0 | end_time_for_congestion_forecasts }
This management command sets the end time for computed congestion forecasts. Setting congestion forecast horizon to zero sets the congestion forecast end time to infinite time in the future: if there is any predicted net growth in bundle storage space occupancy at all, following the end of the last scheduled contact, then eventual congestion will be predicted. The default value is zero, i.e., no end time.
m alarm 'congestion_alarm_command'
This management command establishes a command which will automatically be executed whenever ionadmin predicts that the node will become congested at some future time. By default, there is no alarm command.
m usage
This management command simply prints ION's current data space occupancy (the number of megabytes of space in the SDR non-volatile heap and file system that are occupied by inbound and outbound zero-copy objects), the total zero-copy-object space occupancy ceiling, and the maximum level of occupancy predicted by the most recent ionadmin congestion forecast computation.
r 'command_text'
The run command. This command will execute command_text as if it had been typed at a console prompt. It is used to, for example, run another administrative program.
s
The start command. This command starts the rfxclock task on the local ION node.
x
The stop command. This command stops the rfxclock task on the local ION node.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
@ 2008/10/05-11:30:00
Sets the reference time to 1130 (UTC) on 5 October 2008.
a range +1 2009/01/01-00:00:00 1 2 12
Predicts that the distance between nodes 1 and 2 (endpoint IDs ipn:1.0 and ipn:2.0) will remain constant at 12 light seconds over the interval that begins 1 second after the reference time and ends at the end of calendar year 2009.
a contact +60 +7260 1 2 10000
Schedules a period of transmission at 10,000 bytes/second from node 1 to node 2, starting 60 seconds after the reference time and ending exactly two hours (7200 seconds) after it starts.
ionadmin(1), rfxclock(1), ion(3)
"},{"location":"man/ici/ionsecadmin/","title":"NAME","text":"ionsecadmin - ION global security database management interface
"},{"location":"man/ici/ionsecadmin/#synopsis","title":"SYNOPSIS","text":"ionsecadmin [ commands_filename ]
"},{"location":"man/ici/ionsecadmin/#description","title":"DESCRIPTION","text":"ionsecadmin configures and manages the ION security database on the local computer.
It configures and manages the ION security database on the local computer in response to ION configuration commands found in commands_filename, if provided; if not, ionsecadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from ionsecadmin by entering the command 'h' or '?' at the prompt. The commands are documented in ionsecrc(5).
"},{"location":"man/ici/ionsecadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of ION security database administration.
ionsecadmin
Enter interactive ION security policy administration command entry mode.
ionsecadmin host1.ionsecrc
Execute all configuration commands in host1.ionsecrc, then terminate immediately.
Status and diagnostic messages from ionsecadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which ionsecadmin was run. The log file is typically named ion.log.
See also ionsecrc(5).
"},{"location":"man/ici/ionsecadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/ionsecadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ionsecadmin. Otherwise ionsecadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ionsecadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see ionsecrc(5) for details.
"},{"location":"man/ici/ionsecadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionsecadmin/#see-also","title":"SEE ALSO","text":"ionsecrc(5)
"},{"location":"man/ici/ionsecrc/","title":"NAME","text":"ionsecrc - ION security database management commands file
"},{"location":"man/ici/ionsecrc/#description","title":"DESCRIPTION","text":"ION security database management commands are passed to ionsecadmin either in a file of text lines or interactively at ionsecadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the ION security database management commands are described below.
"},{"location":"man/ici/ionsecrc/#commands","title":"COMMANDS","text":"?
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 ionsecadmin 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
The initialize command. Until this command is executed, the local ION node has no security database and most ionsecadmin commands will fail.
a key key_name file_name
The add key command. This command adds a named key value to the security database. The content of file_name is taken as the value of the key. Named keys can be referenced by other elements of the security database.
c key key_name file_name
The change key command. This command changes the value of the named key, obtaining the new key value from the content of file_name.
d key key_name
The delete key command. This command deletes the key identified by name.
i key key_name
This command will print information about the named key, i.e., the length of its current value.
l key
This command lists all keys in the security database.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
a key BABKEY ./babkey.txt
Adds a new key named \"BABKEY\" whose value is the content of the file \"./babkey.txt\".
ionsecadmin(1)
"},{"location":"man/ici/ionunlock/","title":"NAME","text":"ionunlock - utility for unlocking a locked ION node
"},{"location":"man/ici/ionunlock/#synopsis","title":"SYNOPSIS","text":"ionunlock [sdr_name]
"},{"location":"man/ici/ionunlock/#description","title":"DESCRIPTION","text":"The ionunlock program is designed to be run when some ION thread has terminated while it is the owner of the node's system mutex, i.e., while in the midst of an SDR transaction. IT MUST NEVER BE RUN AT ANY OTHER TIME as it will totally corrupt a node that is not locked up. The program simply declares itself to be the owner of the incomplete transaction and cancels it, enabling the rest of the system to resume operations.
If omitted, sdr_name defaults to \"ion\".
"},{"location":"man/ici/ionunlock/#exit-status","title":"EXIT STATUS","text":"\"0\"
ionunlock has terminated successfully.
\"1\"
ionunlock has terminated unsuccessfully. See diagnostic messages in the ion.log log file for details.
No configuration files are needed.
"},{"location":"man/ici/ionunlock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/ionunlock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't initialize the SDR system.
Probable operations error: ION appears not to be initialized, in which case there is no point in running ionunlock.
Can't start using SDR.
ION system error. See earlier diagnostic messages posted to ion.log for details. In this event it is unlikely that ionunlock can be run successfully, and it is also unlikely that it would have any effect if it did run successfully.
ionunlock unnecessary; exiting.
Either the indicated SDR is not initialized or it is not currently stuck in a transaction.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionunlock/#see-also","title":"SEE ALSO","text":"ionxnowner(1), sdrmend(1), sdr(3)
"},{"location":"man/ici/ionxnowner/","title":"NAME","text":"ionxnowner - report on which threads are initiating SDR transactions
"},{"location":"man/ici/ionxnowner/#synopsis","title":"SYNOPSIS","text":"ionxnowner [interval [count [echo]]]
"},{"location":"man/ici/ionxnowner/#description","title":"DESCRIPTION","text":"For count interations (defaulting to 1), ionxnowner prints the process ID and thread ID of the thread that currently \"owns\" the local node's SDR data store (i.e., started the current transaction), then sleeps interval seconds (minimum 1). If the optional echo parameter is set to 1, then the transaction owner message is logged as well as printed to the console.
"},{"location":"man/ici/ionxnowner/#exit-status","title":"EXIT STATUS","text":"\"0\"
ionxnowner has terminated.
No configuration files are needed.
"},{"location":"man/ici/ionxnowner/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/ionxnowner/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to ION.
ION system error. See earlier diagnostic messages posted to ion.log for details.
Can't access SDR.
ION system error. See earlier diagnostic messages posted to ion.log for details.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/ionxnowner/#see-also","title":"SEE ALSO","text":"ionunlock(1), sdr(3), psmwatch(1)
"},{"location":"man/ici/llcv/","title":"NAME","text":"llcv - library for manipulating linked-list condition variable objects
"},{"location":"man/ici/llcv/#synopsis","title":"SYNOPSIS","text":"#include \"llcv.h\"\n\ntypedef struct llcv_str\n{\n Lyst list;\n pthread_mutex_t mutex;\n pthread_cond_t cv;\n} *Llcv;\n\ntypedef int (*LlcvPredicate)(Llcv);\n\n[see description for available functions]\nA \"linked-list condition variable\" object (LLCV) is an inter-thread communication mechanism that pairs a process-private linked list in memory with a condition variable as provided by the pthreads library. LLCVs echo in thread programming the standard ION inter-process or inter-task communication model that pairs shared-memory semaphores with linked lists in shared memory or shared non-volatile storage. As in the semaphore/list model, variable-length messages may be transmitted; the resources allocated to the communication mechanism grow and shrink to accommodate changes in data rate; the rate at which messages are issued is completely decoupled from the rate at which messages are received and processed. That is, there is no flow control, no blocking, and therefore no possibility of deadlock or \"deadly embrace\". Traffic spikes are handled without impact on processing rate, provided sufficient memory is provided to accommodate the peak backlog.
An LLCV comprises a Lyst, a mutex, and a condition variable. The Lyst may be in either private or shared memory, but the Lyst itself is not shared with other processes. The reader thread waits on the condition variable until signaled by a writer that some condition is now true. The standard Lyst API functions are used to populate and drain the linked list. In order to protect linked list integrity, each thread must call llcv_lock() before operating on the Lyst and llcv_unlock() afterwards. The other llcv functions merely effect flow signaling in a way that makes it unnecessary for the reader to poll or busy-wait on the Lyst.
Llcv llcv_open(Lyst list, Llcv llcv)
Opens an LLCV, initializing as necessary. The list argument must point to an existing Lyst, which may reside in either private or shared dynamic memory. llcv must point to an existing llcv_str management object, which may reside in either static or dynamic (private or shared) memory -- but NOT in stack space. Returns llcv on success, NULL on any error.
void llcv_lock(Llcv llcv)
Locks the LLCV's Lyst so that it may be updated or examined safely by the calling thread. Fails silently on any error.
void llcv_unlock(Llcv llcv)
Unlocks the LLCV's Lyst so that another thread may lock and update or examine it. Fails silently on any error.
int llcv_wait(Llcv llcv, LlcvPredicate cond, int microseconds)
Returns when the Lyst encapsulated within the LLCV meets the indicated condition. If microseconds is non-negative, will return -1 and set errno to ETIMEDOUT when the indicated number of microseconds has passed, if and only if the indicated condition has not been met by that time. Negative values of the microseconds argument other than LLCV_BLOCKING (defined as -1) are illegal. Returns -1 on any error.
void llcv_signal(Llcv llcv, LlcvPredicate cond)
Locks the indicated LLCV's Lyst; tests (evaluates) the indicated condition with regard to that LLCV; if the condition is true, signals to the waiting reader on this LLCV (if any) that the Lyst encapsulated in the indicated LLCV now meets the indicated condition; and unlocks the Lyst.
void llcv_signal_while_locked(Llcv llcv, LlcvPredicate cond)
Same as llcv_signal() except does not lock the Llcv's mutex before signalling or unlock afterwards. For use when the Llcv is already locked; prevents deadlock.
void llcv_close(Llcv llcv)
Destroys the indicated LLCV's mutex and condition variable. Fails silently (and has no effect) if a reader is currently waiting on the Llcv.
int llcv_lyst_is_empty(Llcv Llcv)
A built-in \"convenience\" predicate, for use when calling llcv_wait(), llcv_signal(), or llcv_signal_while_locked(). Returns true if the length of the indicated LLCV's encapsulated Lyst is zero, false otherwise.
int llcv_lyst_not_empty(Llcv Llcv)
A built-in \"convenience\" predicate, for use when calling llcv_wait(), llcv_signal(), or llcv_signal_while_locked(). Returns true if the length of the LLCV's encapsulated Lyst is non-zero, false otherwise.
lyst(3)
"},{"location":"man/ici/lyst/","title":"NAME","text":"lyst - library for manipulating generalized doubly linked lists
"},{"location":"man/ici/lyst/#synopsis","title":"SYNOPSIS","text":"#include \"lyst.h\"\n\ntypedef int (*LystCompareFn)(void *s1, void *s2);\ntypedef void (*LystCallback)(LystElt elt, void *userdata);\n\n[see description for available functions]\nThe \"lyst\" library uses two types of objects, Lyst objects and LystElt objects. A Lyst knows how many elements it contains, its first and last elements, the memory manager used to create/destroy the Lyst and its elements, and how the elements are sorted. A LystElt knows its content (normally a pointer to an item in memory), what Lyst it belongs to, and the LystElts before and after it in that Lyst.
Lyst lyst_create(void)
Create and return a new Lyst object without any elements in it. All operations performed on this Lyst will use the allocation/deallocation functions of the default memory manager \"std\" (see memmgr(3)). Returns NULL on any failure.
Lyst lyst_create_using(unsigned memmgrId)
Create and return a new Lyst object without any elements in it. All operations performed on this Lyst will use the allocation/deallocation functions of the specified memory manager (see memmgr(3)). Returns NULL on any failure.
void lyst_clear(Lyst list)
Clear a Lyst, i.e. free all elements of list, calling the Lyst's deletion function if defined, but without destroying the Lyst itself.
void lyst_destroy(Lyst list)
Destroy a Lyst. Will free all elements of list, calling the Lyst's deletion function if defined.
void lyst_compare_set(Lyst list, LystCompareFn compareFn)
LystCompareFn lyst_compare_get(Lyst list)
Set/get comparison function for specified Lyst. Comparison functions are called with two Lyst element data pointers, and must return a negative integer if first is less than second, 0 if both are equal, and a positive integer if first is greater than second (i.e., same return values as strcmp(3)). The comparison function is used by the lyst_insert(), lyst_search(), lyst_sort(), and lyst_sorted() functions.
void lyst_direction_set(Lyst list, LystSortDirection direction)
Set sort direction (either LIST_SORT_ASCENDING or LIST_SORT_DESCENDING) for specified Lyst. If no comparison function is set, then this controls whether new elements are added to the end or beginning (respectively) of the Lyst when lyst_insert() is called.
void lyst_delete_set(Lyst list, LystCallback deleteFn, void *userdata)
Set user deletion function for specified Lyst. This function is automatically called whenever an element of the Lyst is deleted, to perform any user-required processing. When automatically called, the deletion function is passed two arguments: the element being deleted and the userdata pointer specified in the lyst_delete_set() call.
void lyst_insert_set(Lyst list, LystCallback insertFn, void *userdata)
Set user insertion function for specified Lyst. This function is automatically called whenever a Lyst element is inserted into the Lyst, to perform any user-required processing. When automatically called, the insertion function is passed two arguments: the element being inserted and the userdata pointer specified in the lyst_insert_set() call.
unsigned long lyst_length(Lyst list)
Return the number of elements in the Lyst.
LystElt lyst_insert(Lyst list, void *data)
Create a new element whose content is the pointer value data and insert it into the Lyst. Uses the Lyst's comparison function to select insertion point, if defined; otherwise adds the new element at the beginning or end of the Lyst, depending on the Lyst sort direction setting. Returns a pointer to the newly created element, or NULL on any failure.
LystElt lyst_insert_first(Lyst list, void *data)
LystElt lyst_insert_last(Lyst list, void *data)
Create a new element and insert it at the beginning/end of the Lyst. If these functions are used when inserting elements into a Lyst with a defined comparison function, then the Lyst may get out of order and future calls to lyst_insert() can put new elements in unpredictable locations. Returns a pointer to the newly created element, or NULL on any failure.
LystElt lyst_insert_before(LystElt element, void *data)
LystElt lyst_insert_after(LystElt element, void *data)
Create a new element and insert it before/after the specified element. If these functions are used when inserting elements into a Lyst with a defined comparison function, then the Lyst may get out of order and future calls to lyst_insert() can put new elements in unpredictable locations. Returns a pointer to the newly created element, or NULL on any failure.
void lyst_delete(LystElt element)
Delete the specified element from its Lyst and deallocate its memory. Calls the user delete function if defined.
LystElt lyst_first(Lyst list)
LystElt lyst_last(Lyst list)
Return a pointer to the first/last element of a Lyst.
LystElt lyst_next(LystElt element)
LystElt lyst_prev(LystElt element)
Return a pointer to the element following/preceding the specified element.
LystElt lyst_search(LystElt element, void *searchValue)
Find the first matching element in a Lyst starting with the specified element. Returns NULL if no matches are found. Uses the Lyst's comparison function if defined, otherwise searches from the given element to the end of the Lyst.
Lyst lyst_lyst(LystElt element)
Return the Lyst to which the specified element belongs.
void* lyst_data(LystElt element)
void* lyst_data_set(LystElt element, void *data)
Get/set the pointer value content of the specified Lyst element. The set routine returns the element's previous content, and the delete function is not called. If the lyst_data_set() function is used on an element of a Lyst with a defined comparison function, then the Lyst may get out of order and future calls to lyst_insert() can put new elements in unpredictable locations.
void lyst_sort(Lyst list)
Sort the Lyst based on the current comparison function and sort direction. A stable insertion sort is used that is very fast when the elements are already in order.
int lyst_sorted(Lyst list)
Determine whether or not the Lyst is sorted based on the current comparison function and sort direction.
void lyst_apply(Lyst list, LystCallback applyFn, void *userdata)
Apply the function applyFn automatically to each element in the Lyst. When automatically called, applyFn is passed two arguments: a pointer to an element, and the userdata argument specified in the call to lyst_apply(). applyFn should not delete or reorder the elements in the Lyst.
memmgr(3), psm(3)
"},{"location":"man/ici/memmgr/","title":"NAME","text":"memmgr - memory manager abstraction functions
"},{"location":"man/ici/memmgr/#synopsis","title":"SYNOPSIS","text":"#include \"memmgr.h\"\n\ntypedef void *(* MemAllocator)\n (char *fileName, int lineNbr, size_t size);\ntypedef void (* MemDeallocator)\n (char *fileName, int lineNbr, void * blk);\ntypedef void *(* MemAtoPConverter) (unsigned int address);\ntypedef unsigned int (* MemPtoAConverter) (void * pointer);\n\nunsigned int memmgr_add (char *name,\n MemAllocator take, \n MemDeallocator release, \n MemAtoPConverter AtoP, \n MemPtoAConverter PtoA);\nint memmgr_find (char *name);\nchar *memmgr_name (int mgrId);\nMemAllocator memmgr_take (int mgrId);\nMemDeallocator memmgr_release (int mgrId);\nMemAtoPConverter memmgr_AtoP (int mgrId);\nMemPtoAConverter memmgr_PtoA (int mgrId;\n\nint memmgr_open (int memKey,\n unsigned long memSize,\n char **memPtr,\n int *smId,\n char *partitionName,\n PsmPartition *partition,\n int *memMgr,\n MemAllocator afn,\n MemDeallocator ffn,\n MemAtoPConverter apfn,\n MemPtoAConverter pafn);\nvoid memmgr_destroy (int smId,\n PsmPartition *partition);\n\"memmgr\" is an abstraction layer for administration of memory management. It enables multiple memory managers to coexist in a single application. Each memory manager specification is required to include pointers to a memory allocation function, a memory deallocation function, and functions for translating between local memory pointers and \"addresses\", which are abstract memory locations that have private meaning to the manager. The allocation function is expected to return a block of memory of size \"size\" (in bytes), initialized to all binary zeroes. The fileName and lineNbr arguments to the allocation and deallocation functions are expected to be the values of __FILE__ and __LINE__ at the point at which the functions are called; this supports any memory usage tracing via sptrace(3) that may be implemented by the underlying memory management system.
Memory managers are identified by number and by name. The identifying number for a memory manager is an index into a private, fixed-length array of up to 8 memory manager configuration structures; that is, memory manager number must be in the range 0-7. However, memory manager numbers are assigned dynamically and not always predictably. To enable multiple applications to use the same memory manager for a given segment of shared memory, a memory manager may be located by a predefined name of up to 15 characters that is known to all the applications.
The memory manager with manager number 0 is always available; its name is \"std\". Its memory allocation function is calloc(), its deallocation function is free(), and its pointer/address translation functions are merely casts.
unsigned int memmgr_add(char *name, MemAllocator take, MemDeallocator release, MemAtoPConverter AtoP, MemPtoAConverter PtoA)
Add a memory manager to the memory manager array, if not already defined; attempting to add a previously added memory manager is not considered an error. name is the name of the memory manager. take is a pointer to the manager's memory allocation function; release is a pointer to the manager's memory deallocation function. AtoP is a pointer to the manager's function for converting an address to a local memory pointer; PtoA is a pointer to the manager's pointer-to-address converter function. Returns the memory manager ID number assigned to the named manager, or -1 on any error.
NOTE: memmgr_add() is NOT thread-safe. In a multithreaded execution image (e.g., VxWorks), all memory managers should be loaded before any subordinate threads or tasks are spawned.
int memmgr_find(char *name)
Return the memmgr ID of the named manager, or -1 if not found.
char *memmgr_name(int mgrId)
Return the name of the manager given by mgrId.
MemAllocator memmgr_take(int mgrId)
Return the allocator function pointer for the manager given by mgrId.
memDeallocator memmgr_release(int mgrId)
Return the deallocator function pointer for the manager given by mgrId.
MemAtoPConverter memmgr_AtoP(int mgrId)
Return the address-to-pointer converter function pointer for the manager given by mgrId.
MemPtoAConverter memmgr_PtoA(int mgrId)
Return the pointer-to-address converter function pointer for the manager given by mgrId.
int memmgr_open(int memKey, unsigned long memSize, char **memPtr, int *smId, char *partitionName, PsmPartition *partition, int *memMgr, MemAllocator afn, MemDeallocator ffn, MemAtoPConverter apfn, MemPtoAConverter pafn);
memmgr_open() opens one avenue of access to a PSM managed region of shared memory, initializing as necessary.
In order for multiple tasks to share access to this memory region, all must cite the same memkey and partitionName when they call memmgr_open(). If shared access is not necessary, then memKey can be SM_NO_KEY and partitionName can be any valid partition name.
If it is known that a prior invocation of memmgr_open() has already initialized the region, then memSize can be zero and memPtr must be NULL. Otherwise memSize is required and the required value of memPtr depends on whether or not the memory that is to be shared and managed has already been allocated (e.g., it's a fixed region of bus memory). If so, then the memory pointer variable that memPtr points to must contain the address of that memory region. Otherwise, *memPtr must contain NULL.
memmgr_open() will allocate system memory as necessary and will in any case return the address of the shared memory region in *memPtr.
If the shared memory is newly allocated or otherwise not yet under PSM management, then memmgr_open() will invoke psm_manage() to manage the shared memory region. It will also add a catalogue for the managed shared memory region as necessary.
If memMgr is non-NULL, then memmgr_open() will additionally call memmgr_add() to establish a new memory manager for this managed shared memory region, as necessary. The index of the applicable memory manager will be returned in memMgr. If that memory manager is newly created, then the supplied afn, ffn, apfn, and pafn functions (which can be written with reference to the memory manager index value returned in memMgr) have been established as the memory management functions for local private access to this managed shared memory region.
Returns 0 on success, -1 on any error.
void memmgr_destroy(int smId, PsmPartition *partition);
memmgr_destroy() terminates all access to a PSM managed region of shared memory, invoking psm_erase() to destroy the partition and sm_ShmDestroy() to destroy the shared memory object.
/* this example uses the calloc/free memory manager, which is\n * called \"std\", and is always defined in memmgr. */\n\n #include \"memmgr.h\"\n\n main() \n {\n int mgrId;\n MemAllocator myalloc;\n MemDeallocator myfree;\n char *newBlock;\n\n mgrId = memmgr_find(\"std\");\n myalloc = memmgr_take(mgrId);\n myfree = memmgr_release(mgrId);\n ...\n\n newBlock = myalloc(5000);\n ...\n myfree(newBlock);\n }\npsm(3)
"},{"location":"man/ici/owltsim/","title":"NAME","text":"owltsim - one-way light time transmission delay simulator
"},{"location":"man/ici/owltsim/#synopsis","title":"SYNOPSIS","text":"owltsim config_filename [-v]
"},{"location":"man/ici/owltsim/#description","title":"DESCRIPTION","text":"owltsim delays delivery of data between pairs of ION nodes by specified lengths of time, simulating the signal propagation delay imposed by distance between the nodes.
Its operation is configured by delay simulation configuration lines in the file identified by config_filename. A pair of threads is created for each line in the file: one that receives UDP datagrams on a specified port and queues them in a linked list, and a second that later removes queued datagrams from the linked list and sends them on to a specified UDP port on a specified network host.
Each configuration line must be of the following form:
to from my_port# dest_host dest_port# owlt modulus
to identifies the receiving node.
This parameter is purely informational, intended to make owltsim's printed messages more helpful to the user.
from identifies the sending node.
A value of '*' may be used to indicate \"all nodes\". Again, this parameter is purely informational, intended to make owltsim's printed messages more helpful to the user.
my_port# identifies owltsim's receiving port for this traffic.
modulus controls the artificial random data loss imposed on this traffic by owltsim.
A value of '0' specifies \"no imposed data loss\". Any modulus value N > 0 causes owltsim to randomly drop (i.e., not transmit upon expiration of the delay interval) one out of every N packets. Any modulus value N < 0 causes owltsim to deterministically drop every (0 - N)th packet.
The optional -v (\"verbose\") parameter causes owltsim to print a message whenever it receives, sends, or drops (due to artificial random data loss) a datagram.
Note that error conditions may cause one delay simulation (a pair of threads) to terminate without terminating any others.
owltsim is designed to run indefinitely. To terminate the program, just use control-C to kill it.
"},{"location":"man/ici/owltsim/#exit-status","title":"EXIT STATUS","text":"Here is a sample owltsim configuration file:
This file indicates that owltsim will receive on port 5502 the ION traffic from node 2 that is destined for node 7, which will receive it at port 5001 on the computer named ptl07.jpl.nasa.gov; 75 seconds of delay (simulating a distance of 75 light seconds) will be imposed on this transmission activity, and owltsim will not simulate any random data loss.
In the reverse direction, owltsim will receive on port 5507 the ION traffic from node 7 that is destined for node 2, which will receive it at port 5001 on the computer named ptl02.jpl.nasa.gov; 75 seconds of delay will again be imposed on this transmission activity, and owltsim will randomly discard (i.e., not transmit upon expiration of the transmission delay interval) one datagram out of every 16 received at this port.
"},{"location":"man/ici/owltsim/#files","title":"FILES","text":"Not applicable.
"},{"location":"man/ici/owltsim/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/owltsim/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be printed to stdout:
owltsim can't open configuration file
The program terminates.
owltsim failed on fscanf
Failure on reading the configuration file. The program terminates.
owltsim stopped malformed config file line line_number.
Failure on parsing the configuration file. The program terminates.
owltsim can't spawn receiver thread
The program terminates.
owltsim out of memory.
The program terminates.
owltsim can't open reception socket
The program terminates.
owltsim can't initialize reception socket
The program terminates.
owltsim can't open transmission socket
The program terminates.
owltsim can't initialize transmission socket
The program terminates.
owltsim can't spawn timer thread
The program terminates.
owltsim can't acquire datagram
Datagram transmission failed. This causes the threads for the affected delay simulation to terminate, without terminating any other threads.
owltsim failed on send
Datagram transmission failed. This causes the threads for the affected delay simulation to terminate, without terminating any other threads.
at time owltsim LOST a dg of length length from sending node destined for receiving node due to ECONNREFUSED.
This is an informational message. Due to an apparent bug in Internet protocol implementation, transmission of a datagram on a connected UDP socket occasionally fails. owltsim does not attempt to retransmit the affected datagram.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/owltsim/#see-also","title":"SEE ALSO","text":"udplsi(1), udplso(1)
"},{"location":"man/ici/owlttb/","title":"NAME","text":"owlttb - one-way light time transmission delay simulator
"},{"location":"man/ici/owlttb/#synopsis","title":"SYNOPSIS","text":"owlttb own_uplink_port# own_downlink_port# dest_uplink_IP_address dest_uplink_port# dest_downlink_IP_address dest_downlink_port# owlt_sec. [-v]
"},{"location":"man/ici/owlttb/#description","title":"DESCRIPTION","text":"owlttb delays delivery of data between an NTTI and a NetAcquire box (or two, one for uplink and one for downlink) by a specified length of time, simulating the signal propagation delay imposed by distance between the nodes.
Its operation is configured by the command-line parameters, except that the delay interval itself may be changed while the program is running. owlttb offers a command prompt (:), and when a new value of one-way light time is entered at this prompt the new delay interval takes effect immediately.
The optional -v (\"verbose\") parameter causes owlttb to print a message whenever it receives, sends, or discards (due to absence of a connected downlink client) a segment of TCP traffic.
owlttb is designed to run indefinitely. To terminate the program, just use control-C to kill it or enter \"q\" at the prompt.
"},{"location":"man/ici/owlttb/#exit-status","title":"EXIT STATUS","text":"Here is a sample owlttb command:
This command indicates that owlttb will accept an uplink traffic connection on port 2901, forwarding the received uplink traffic to port 10001 on the NetAcquire box at 137.7.8.19, and it will accept a downlink traffic connection on port 2902, delivering over that connection all downlink traffic that it receives from connecting to port 10002 on the NetAcquire box at 137.7.8.19. 75 seconds of delay (simulating a distance of 75 light seconds) will be imposed on this transmission activity.
"},{"location":"man/ici/owlttb/#files","title":"FILES","text":"Not applicable.
"},{"location":"man/ici/owlttb/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/owlttb/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be printed to stdout:
owlttb can't spawn uplink thread
The program terminates.
owlttb can't spawn uplink sender thread
The program terminates.
owlttb can't spawn downlink thread
The program terminates.
owlttb can't spawn downlink receiver thread
The program terminates.
owlttb can't spawn downlink sender thread
The program terminates.
owlttb fgets failed
The program terminates.
owlttb out of memory.
The program terminates.
owlttb lost uplink client.
This is an informational message. The NTTI may reconnect at any time.
owlttb lost downlink client
This is an informational message. The NTTI may reconnect at any time.
owlttb can't open TCP socket to NetAcquire
The program terminates.
owlttb can't connect TCP socket to NetAcquire
The program terminates.
owlttb write() error on socket
The program terminates if it was writing to NetAcquire; otherwise it simply recognizes that the client NTTI has disconnected.
owlttb read() error on socket
The program terminates.
owlttb can't open uplink dialup socket
The program terminates.
owlttb can't initialize uplink dialup socket
The program terminates.
owlttb can't open downlink dialup socket
The program terminates.
owlttb can't initialize downlink dialup socket
The program terminates.
owlttb accept() failed
The program terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/platform/","title":"NAME","text":"platform - C software portability definitions and functions
"},{"location":"man/ici/platform/#synopsis","title":"SYNOPSIS","text":"#include \"platform.h\"\n\n[see description for available functions]\nplatform is a library of functions that simplify the porting of software written in C. It provides an API that enables application code to access the resources of an abstract POSIX-compliant \"least common denominator\" operating system -- typically a large subset of the resources of the actual underlying operating system.
Most of the functionality provided by the platform library is aimed at making communication code portable: common functions for shared memory, semaphores, and IP sockets are provided. The implementation of the abstract O/S API varies according to the actual operating system on which the application runs, but the API's behavior is always the same; applications that invoke the platform library functions rather than native O/S system calls may forego some O/S-specific capability, but they gain portability at little if any cost in performance.
Differences in word size among platforms are implemented by values of the SPACE_ORDER macro. \"Space order\" is the base 2 log of the number of octets in a word: for 32-bit machines the space order is 2 (2^2 = 4 octets per word), for 64-bit machines it is 3 (2^3 = 8 octets per word).
A consistent platform-independent representation of large integers is useful for some applications. For this purpose, platform defines new types vast and uvast (unsigned vast) which are consistently defined to be 64-bit integers regardless of the platform's native word size.
The platform.h header file #includes many of the most frequently needed header files: sys/types.h, errno.h, string.h, stdio.h, sys/socket.h, signal.h, dirent.h, netinet/in.h, unistd.h, stdlib.h, sys/time.h, sys/resource.h, malloc.h, sys/param.h, netdb.h, sys/uni.h, and fcntl.h. Beyond this, platform attempts to enhance compatibility by providing standard macros, type definitions, external references, or function implementations that are missing from a few supported O/S's but supported by all others. Finally, entirely new, generic functions are provided to establish a common body of functionality that subsumes significantly different O/S-specific capabilities.
"},{"location":"man/ici/platform/#platform-compatibility-patches","title":"PLATFORM COMPATIBILITY PATCHES","text":"The platform library \"patches\" the APIs of supported O/S's to guarantee that all of the following items may be utilized by application software:
The strchr(), strrchr(), strcasecmp(), and strncasecmp() functions.\n\nThe unlink(), getpid(), and gettimeofday() functions.\n\nThe select() function.\n\nThe FD_BITMAP macro (used by select()).\n\nThe MAXHOSTNAMELEN macro.\n\nThe NULL macro.\n\nThe timer_t type definition.\nThe generic macros and functions in this section may be used in place of comparable O/S-specific functions, to enhance the portability of code. (The implementations of these macros and functions are no-ops in environments in which they are inapplicable, so they're always safe to call.)
FDTABLE_SIZE
The FDTABLE_SIZE macro returns the total number of file descriptors defined for the process (or VxWorks target).
ION_PATH_DELIMITER
The ION_PATH_DELIMITER macro returns the ASCII character -- either '/' or '\\' -- that is used as a directory name delimiter in path names for the file system used by the local platform.
oK(expression)
The oK macro simply casts the value of expression to void, a way of handling function return codes that are not meaningful in this context.
CHKERR(condition)
The CHKERR macro is an \"assert\" mechanism. It causes the calling function to return -1 immediately if condition is false.
CHKZERO(condition)
The CHKZERO macro is an \"assert\" mechanism. It causes the calling function to return 0 immediately if condition is false.
CHKNULL(condition)
The CHKNULL macro is an \"assert\" mechanism. It causes the calling function to return NULL immediately if condition is false.
CHKVOID(condition)
The CHKVOID macro is an \"assert\" mechanism. It causes the calling function to return immediately if condition is false.
void snooze(unsigned int seconds)
Suspends execution of the invoking task or process for the indicated number of seconds.
void microsnooze(unsigned int microseconds)
Suspends execution of the invoking task or process for the indicated number of microseconds.
void getCurrentTime(struct timeval *time)
Returns the current local time (ctime, i.e., Unix epoch time) in a timeval structure (see gettimeofday(3C)).
void isprintf(char *buffer, int bufSize, char *format, ...)
isprintf() is a safe, portable implementation of snprintf(); see the snprintf(P) man page for details. isprintf() differs from snprintf() in that it always NULL-terminates the string in buffer, even if the length of the composed string would equal or exceed bufSize. Buffer overruns are reported by log message; unlike snprintf(), isprintf() returns void.
size_t istrlen(const char *sourceString, size_t maxlen)
istrlen() is a safe implementation of strlen(); see the strlen(3) man page for details. istrlen() differs from strlen() in that it takes a second argument, the maximum valid length of sourceString. The function returns the number of non-NULL characters in sourceString preceding the first NULL character in sourceString, provided that a NULL character appears somewhere within the first maxlen characters of sourceString; otherwise it returns maxlen.
char *istrcpy(char *buffer, char *sourceString, int bufSize)
istrcpy() is a safe implementation of strcpy(); see the strcpy(3) man page for details. istrcpy() differs from strcpy() in that it takes a third argument, the total size of the buffer into which sourceString is to be copied. istrcpy() always NULL-terminates the string in buffer, even if the length of sourceString string would equal or exceed bufSize (in which case sourceString is truncated to fit within the buffer).
char *istrcat(char *buffer, char *sourceString, int bufSize)
istrcat() is a safe implementation of strcat(); see the strcat(3) man page for details. istrcat() differs from strcat() in that it takes a third argument, the total size of the buffer for the string that is being aggregated. istrcat() always NULL-terminates the string in buffer, even if the length of sourceString string would equal or exceed the sum of bufSize and the length of the string currently occupying the buffer (in which case sourceString is truncated to fit within the buffer).
char *igetcwd(char *buf, size_t size)
igetcwd() is normally just a wrapper around getcwd(3). It differs from getcwd(3) only when FSWWDNAME is defined, in which case the implementation of igetcwd() must be supplied in an included file named \"wdname.c\"; this adaptation option accommodates flight software environments in which the current working directory name must be configured rather than discovered at run time.
void isignal(int signbr, void (*handler)(int))
isignal() is a portable, simplified interface to signal handling that is functionally indistinguishable from signal(P). It assures that reception of the indicated signal will interrupt system calls in SVR4 fashion, even when running on a FreeBSD platform.
void iblock(int signbr)
iblock() simply prevents reception of the indicated signal by the calling thread. It provides a means of controlling which of the threads in a process will receive the signal cited in an invocation of isignal().
int ifopen(const char *fileName, int flags, int pmode)
ifopen() is a portable function for opening \"regular\" files. It operates in exactly the same way as open() except that it fails (returning -1) if fileName does not identify a regular file, i.e., it's a directory, a named pipe, etc.
NOTE that ION also provides iopen() which is nothing more than a portable wrapper for open(). iopen() can be used to open a directory, for example.
char *igets(int fd, char *buffer, int buflen, int *lineLen)
igets() reads a line of text, delimited by a newline character, from fd into buffer and writes a NULL character at the end of the string. The newline character itself is omitted from the NULL-terminated text line in buffer; if the newline is immediately preceded by a carriage return character (i.e., the line is from a DOS text file), then the carriage return character is likewise omitted from the NULL-terminated text line in buffer. End of file is interpreted as an implicit newline, terminating the line. If the number of characters preceding the newline is greater than or equal to buflen, only the first (buflen - 1) characters of the line are written into buffer. On error the function sets *lineLen to -1 and returns NULL. On reading end-of-file, the function sets *lineLen to zero and returns NULL. Otherwise the function sets *lineLen to the length of the text line in buffer, as if from strlen(3), and returns buffer.
int iputs(int fd, char *string)
iputs() writes to fd the NULL-terminated character string at string. No terminating newline character is appended to string by iputs(). On error the function returns -1; otherwise the function returns the length of the character string written to fd, as if from strlen(3).
vast strtovast(char *string)
Converts the leading characters of string, skipping leading white space and ending at the first subsequent character that can't be interpreted as contributing to a numeric value, to a vast integer and returns that integer.
uvast strtouvast(char *string)
Same as strtovast() except the result is an unsigned vast integer value.
void findToken(char **cursorPtr, char **token)
Locates the next non-whitespace lexical token in a character array, starting at *cursorPtr. The function NULL-terminates that token within the array and places a pointer to the token in *token. Also accommodates tokens enclosed within matching single quotes, which may contain embedded spaces and escaped single-quote characters. If no token is found, *token contains NULL on return from this function.
void *acquireSystemMemory(size_t size)
Uses memalign() to allocate a block of system memory of length size, starting at an address that is guaranteed to be an integral multiple of the size of a pointer to void, and initializes the entire block to binary zeroes. Returns the starting address of the allocated block on success; returns NULL on any error.
int createFile(const char *name, int flags)
Creates a file of the indicated name, using the indicated file creation flags. This function provides common file creation functionality across VxWorks and Unix platforms, invoking creat() under VxWorks and open() elsewhere. For return values, see creat(2) and open(2).
unsigned int getInternetAddress(char *hostName)
Returns the IP address of the indicated host machine, or zero if the address cannot be determined.
char *getInternetHostName(unsigned int hostNbr, char *buffer)
Writes the host name of the indicated host machine into buffer and returns buffer, or returns NULL on any error. The size of buffer should be (MAXHOSTNAMELEN + 1).
int getNameOfHost(char *buffer, int bufferLength)
Writes the first (bufferLength - 1) characters of the host name of the local machine into buffer. Returns 0 on success, -1 on any error.
unsigned int getAddressOfHost()
Returns the IP address for the host name of the local machine, or 0 on any error.
void parseSocketSpec(char *socketSpec, unsigned short *portNbr, unsigned int *hostNbr)
Parses socketSpec, extracting host number (IP address) and port number from the string. socketSpec is expected to be of the form \"{ @ | hostname }[:<portnbr>]\", where @ signifies \"the host name of the local machine\". If host number can be determined, writes it into *hostNbr; otherwise writes 0 into *hostNbr. If port number is supplied and is in the range 1024 to 65535, writes it into *portNbr; otherwise writes 0 into *portNbr.
void printDottedString(unsigned int hostNbr, char *buffer)
Composes a dotted-string (xxx.xxx.xxx.xxx) representation of the IPv4 address in hostNbr and writes that string into buffer. The length of buffer must be at least 16.
char *getNameOfUser(char *buffer)
Writes the user name of the invoking task or process into buffer and returns buffer. The size of buffer must be at least L_cuserid, a constant defined in the stdio.h header file. Returns buffer.
int reUseAddress(int fd)
Makes the address that is bound to the socket identified by fd reusable, so that the socket can be closed and immediately reopened and re-bound to the same port number. Returns 0 on success, -1 on any error.
int makeIoNonBlocking(int fd)
Makes I/O on the socket identified by fd non-blocking; returns -1 on failure. An attempt to read on a non-blocking socket when no data are pending, or to write on it when its output buffer is full, will not block; it will instead return -1 and cause errno to be set to EWOULDBLOCK.
int watchSocket(int fd)
Turns on the \"linger\" and \"keepalive\" options for the socket identified by fd. See socket(2) for details. Returns 0 on success, -1 on any failure.
void closeOnExec(int fd)
Ensures that fd will NOT be open in any child process fork()ed from the invoking process. Has no effect on a VxWorks platform.
The functions in this section offer platform-independent capabilities for reporting on processing exceptions.
The underlying mechanism for ICI's exception reporting is a pair of functions that record error messages in a privately managed pool of static memory. These functions -- postErrmsg() and postSysErrmsg() -- are designed to return very rapidly with no possibility of failing, themselves. Nonetheless they are not safe to call from an interrupt service routing (ISR). Although each merely copies its text to the next available location in the error message memory pool, that pool is protected by a mutex; multiple processes might be queued up to take that mutex, so the total time to execute the function is non-deterministic.
Built on top of postErrmsg() and postSysErrmsg() are the putErrmsg() and putSysErrmsg() functions, which may take longer to return. Each one simply calls the corresponding \"post\" function but then calls the writeErrmsgMemos() function, which calls writeMemo() to print (or otherwise deliver) each message currently posted to the pool and then destroys all of those posted messages, emptying the pool.
Recommended general policy on using the ICI exception reporting functions (which the functions in the ION distribution libraries are supposed to adhere to) is as follows:
In the implementation of any ION library function or any ION\n task's top-level driver function, any condition that prevents\n the function from continuing execution toward producing the\n effect it is designed to produce is considered an \"error\".\n\n Detection of an error should result in the printing of an\n error message and, normally, the immediate return of whatever\n return value is used to indicate the failure of the function\n in which the error was detected. By convention this value\n is usually -1, but both zero and NULL are appropriate\n failure indications under some circumstances such as object\n creation.\n\n The CHKERR, CHKZERO, CHKNULL, and CHKVOID macros are used to\n implement this behavior in a standard and lexically terse\n manner. Use of these macros offers an additional feature:\n for debugging purposes, they can easily be configured to\n call sm_Abort() to terminate immediately with a core dump\n instead of returning a error indication. This option is\n enabled by setting the compiler parameter CORE_FILE_NEEDED\n to 1 at compilation time.\n\n In the absence of either any error, the function returns a\n value that indicates nominal completion. By convention this\n value is usually zero, but under some circumstances other\n values (such as pointers or addresses) are appropriate\n indications of nominal completion. Any additional information\n produced by the function, such as an indication of \"success\",\n is usually returned as the value of a reference argument.\n [Note, though, that database management functions and the\n SDR hash table management functions deviate from this rule:\n most return 0 to indicate nominal completion but functional\n failure (e.g., duplicate key or object not found) and return\n 1 to indicate functional success.]\n\n So when returning a value that indicates nominal completion\n of the function -- even if the result might be interpreted\n as a failure at a higher level (e.g., an object identified\n by a given string is not found, through no failure of the\n search function) -- do NOT invoke putErrmsg().\n\n Use putErrmsg() and putSysErrmsg() only when functions are\n unable to proceed to nominal completion. Use writeMemo()\n or writeMemoNote() if you just want to log a message.\n\n Whenever returning a value that indicates an error:\n\n If the failure is due to the failure of a system call\n or some other non-ION function, assume that errno\n has already been set by the function at the lowest\n layer of the call stack; use putSysErrmsg (or\n postSysErrmsg if in a hurry) to describe the nature\n of the activity that failed. The text of the error\n message should normally start with a capital letter\n and should NOT end with a period.\n\n Otherwise -- i.e., the failure is due to a condition\n that was detected within ION -- use putErrmsg (or\n postErrmg if pressed for time) to describe the nature\n of the failure condition. This will aid in tracing\n the failure through the function stack in which the\n failure was detected. The text of the error message\n should normally start with a capital letter and should\n end with a period.\n\n When a failure in a called function is reported to \"driver\"\n code in an application program, before continuing or exiting\n use writeErrmsgMemos() to empty the message pool and print a\n simple stack trace identifying the failure.\nchar *system_error_msg( )
Returns a brief text string describing the current system error, as identified by the current value of errno.
void setLogger(Logger usersLoggerName)
Sets the user function to be used for writing messages to a user-defined \"log\" medium. The logger function's calling sequence must match the following prototype:
void usersLoggerName(char *msg);\nThe default Logger function simply writes the message to standard output.
void writeMemo(char *msg)
Writes one log message, using the currently defined message logging function.
void writeMemoNote(char *msg, char *note)
Writes a log message like writeMemo(), accompanied by the user-supplied context-specific text in note.
void writeErrMemo(char *msg)
Writes a log message like writeMemo(), accompanied by text describing the current system error.
char *itoa(int value)
Returns a string representation of the signed integer in value, nominally for immediate use as an argument to putErrmsg(). [Note that the string is constructed in a static buffer; this function is not thread-safe.]
char *utoa(unsigned int value)
Returns a string representation of the unsigned integer in value, nominally for immediate use as an argument to putErrmsg(). [Note that the string is constructed in a static buffer; this function is not thread-safe.]
void postErrmsg(char *text, char *argument)
Constructs an error message noting the name of the source file containing the line at which this function was called, the line number, the text of the message, and -- if not NULL -- a single textual argument that can be used to give more specific information about the nature of the reported failure (such as the value of one of the arguments to the failed function). The error message is appended to the list of messages in a privately managed pool of static memory, ERRMSGS_BUFSIZE bytes in length.
If text is NULL or is a string of zero length or begins with a newline character (i.e., *text == '\\0' or '\\n'), the function returns immediately and no error message is recorded.
The errmsgs pool is designed to be large enough to contain error messages from all levels of the calling stack at the time that an error is encountered. If the remaining unused space in the pool is less than the size of the new error message, however, the error message is silently omitted. In this case, provided at least two bytes of unused space remain in the pool, a message comprising a single newline character is appended to the list to indicate that a message was omitted due to excessive length.
void postSysErrmsg(char *text, char *arg)
Like postErrmsg() except that the error message constructed by the function additionally contains text describing the current system error. text is truncated as necessary to assure that the sum of its length and that of the description of the current system error does not exceed 1021 bytes.
int getErrmsg(char *buffer)
Copies the oldest error message in the message pool into buffer and removes that message from the pool, making room for new messages. Returns zero if the message pool cannot be locked for update or there are no more messages in the pool; otherwise returns the length of the message copied into buffer. Note that, for safety, the size of buffer should be ERRMSGS_BUFSIZE.
Note that a returned error message comprising only a single newline character always signifies an error message that was silently omitted because there wasn't enough space left on the message pool to contain it.
void writeErrmsgMemos( )
Calls getErrmsg() repeatedly until the message pool is empty, using writeMemo() to log all the messages in the pool. Messages that were omitted due to excessive length are indicated by logged lines of the form \"[message omitted due to excessive length]\".
void putErrmsg(char *text, char *argument)
The putErrmsg() function merely calls postErrmsg() and then writeErrmsgMemos().
void putSysErrmsg(char *text, char *arg)
The putSysErrmsg() function merely calls postSysErrmsg() and then writeErrmsgMemos().
void discardErrmsgs( )
Calls getErrmsg() repeatedly until the message pool is empty, discarding all of the messages.
void printStackTrace( )
On Linux machines only, uses writeMemo() to print a trace of the process's current execution stack, starting with the lowest level of the stack and proceeding to the main() function of the executable.
Note that (a) printStackTrace() is only implemented for Linux platforms at this time; (b) symbolic names of functions can only be printed if the -rdynamic flag was enabled when the executable was linked; (c) only the names of non-static functions will appear in the stack trace.
For more complete information about the state of the executable at the time the stack trace snapshot was taken, use the Linux addr2line tool. To do this, cd into a directory in which the executable file resides (such as /opt/bin) and submit an addr2line command as follows:
addr2line -e _name\\_of\\_executable_ _stack\\_frame\\_address_\nwhere both name_of_executable and stack_frame_address are taken from one of the lines of the printed stack trace. addr2line will print the source file name and line number for that stack frame.
The functions in this section offer platform-independent capabilities for recording \"watch\" characters indicating the occurrence of protocol events. See bprc(5), ltprc(5), cfdprc(5), etc. for details of the watch character production options provided by the protocol packages.
void setWatcher(Watcher usersWatcherName)
Sets the user function to be used for recording watch characters to a user-defined \"watch\" medium. The watcher function's calling sequence must match the following prototype:
void usersWatcherName(char token);\nThe default Watcher function simply writes the token to standard output.
void iwatch(char token)
Records one \"watch\" character, using the currently defined watch character recording function.
The functions in this section encode and decode SDNVs, portable variable-length numeric variables that expand to whatever size is necessary to contain the values they contain. SDNVs are used extensively in the BP and LTP libraries.
void encodeSdnv(Sdnv *sdnvBuffer, uvast value)
Determines the number of octets of SDNV text needed to contain the value, places that number in the length field of the SDNV buffer, and encodes the value in SDNV format into the first length octets of the text field of the SDNV buffer.
int decodeSdnv(uvast *value, unsigned char *sdnvText)
Determines the length of the SDNV located at sdnvText and returns this number after extracting the SDNV's value from those octets and storing it in value. Returns 0 if the encoded number value will not fit into an unsigned vast integer.
The functions in this section perform simple arithmetic operations on unsigned Scalar objects -- structures encapsulating large positive integers in a machine-independent way. Each Scalar comprises two integers, a count of units [ranging from 0 to (2^30 - 1), i.e., up to 1 gig] and a count of gigs [ranging from 0 to (2^31 -1)]. A Scalar can represent a numeric value up to 2 billion billions, i.e., 2 million trillions.
void loadScalar(Scalar *scalar, signed int value)
Sets the value of scalar to the absolute value of value.
void increaseScalar(Scalar *scalar, signed int value)
Adds to scalar the absolute value of value.
void reduceScalar(Scalar *scalar, signed int value)
Adds to scalar the absolute value of value.
void multiplyScalar(Scalar *scalar, signed int value)
Multiplies scalar by the absolute value of value.
void divideScalar(Scalar *scalar, signed int value)
Divides scalar by the absolute value of value.
void copyScalar(Scalar *to, Scalar *from)
Copies the value of from into to.
void addToScalar(Scalar *scalar, Scalar *increment)
Adds increment (a Scalar rather than a C integer) to scalar.
void subtractFromScalar(Scalar *scalar, Scalar *decrement)
Subtracts decrement (a Scalar rather than a C integer) from scalar.
int scalarIsValid(Scalar *scalar)
Returns 1 if the arithmetic performed on scalar has not resulted in overflow or underflow.
int scalarToSdnv(Sdnv *sdnv, Scalar *scalar)
If scalar points to a valid Scalar, stores the value of scalar in sdnv; otherwise sets the length of sdnv to zero.
int sdnvToScalar(Scalar *scalar, unsigned char *sdnvText)
If sdnvText points to a sequence of bytes that, when interpreted as the text of an Sdnv, has a value that can be represented in a 61-bit unsigned binary integer, then this function stores that value in scalar and returns the detected Sdnv length. Otherwise returns zero.
Note that Scalars and Sdnvs are both representations of potentially large unsigned integer values. Any Scalar can alternatively be represented as an Sdnv. However, it is possible for a valid Sdnv to be too large to represent in a Scalar.
The functions in this section provide platform-independent management of mutexes for synchronizing operations of threads or tasks in a common private address space.
int initResourceLock(ResourceLock *lock)
Establishes an inter-thread lock for use in locking some resource. Returns 0 if successful, -1 if not.
void killResourceLock(ResourceLock *lock)
Deletes the resource lock referred to by lock.
void lockResource(ResourceLock *lock)
Checks the state of lock. If the lock is already owned by a different thread, the call blocks until the other thread relinquishes the lock. If the lock is unowned, it is given to the current thread and the lock count is set to 1. If the lock is already owned by this thread, the lock count is incremented by 1.
void unlockResource(ResourceLock *lock)
If called by the current owner of lock, decrements lock's lock count by 1; if zero, relinquishes the lock so it may be taken by other threads. Care must be taken to make sure that one, and only one, unlockResource() call is issued for each lockResource() call issued on a given resource lock.
The functions in this section provide platform-independent management of IPC mechanisms for synchronizing operations of threads, tasks, or processes that may occupy different address spaces but share access to a common system (nominally, processor) memory.
NOTE that this is distinct from the VxWorks \"VxMP\" capability enabling tasks to share access to bus memory or dual-ported board memory from multiple processors. The \"platform\" system will support IPC devices that utilize this capability at some time in the future, but that support is not yet implemented.
int sm_ipc_init( )
Acquires and initializes shared-memory IPC management resources. Must be called before any other shared-memory IPC function is called. Returns 0 on success, -1 on any failure.
void sm_ipc_stop( )
Releases shared-memory IPC management resources, disabling the shared-memory IPC functions until sm_ipc_init() is called again.
int sm_GetUniqueKey( )
Some of the \"sm_\" (shared memory) functions described below associate new communication objects with key values that uniquely identify them, so that different processes can access them independently. Key values are typically defined as constants in application code. However, when a new communication object is required for which no specific need was anticipated in the application, the sm_GetUniqueKey() function can be invoked to obtain a new, arbitrary key value that is known not to be already in use.
sm_SemId sm_SemCreate(int key, int semType)
Creates a shared-memory semaphore that can be used to synchronize activity among tasks or processes residing in a common system memory but possibly multiple address spaces; returns a reference handle for that semaphore, or SM_SEM_NONE on any failure. If key refers to an existing semaphore, returns the handle of that semaphore. If key is the constant value SM_NO_KEY, automatically obtains an unused key. On VxWorks platforms, semType determines the order in which the semaphore is given to multiple tasks that attempt to take it while it is already taken: if set to SM_SEM_PRIORITY then the semaphore is given to tasks in task priority sequence (i.e., the highest-priority task waiting for it receives it when it is released), while otherwise (SM_SEM_FIFO) the semaphore is given to tasks in the order in which they attempted to take it. On all other platforms, only SM_SEM_FIFO behavior is supported and semType is ignored.
int sm_SemTake(sm_SemId semId)
Blocks until the indicated semaphore is no longer taken by any other task or process, then takes it. Return 0 on success, -1 on any error.
void sm_SemGive(sm_SemId semId)
Gives the indicated semaphore, so that another task or process can take it.
void sm_SemEnd(sm_SemId semId)
This function is used to pass a termination signal to whatever task is currently blocked on taking the indicated semaphore, if any. It sets to 1 the \"ended\" flag associated with this semaphore, so that a test for sm_SemEnded() will return 1, and it gives the semaphore so that the blocked task will have an opportunity to test that flag.
int sm_SemEnded(sm_SemId semId)
This function returns 1 if the \"ended\" flag associated with the indicated semaphore has been set to 1; returns zero otherwise. When the function returns 1 it also gives the semaphore so that any other tasks that might be pended on the same semaphore are also given an opportunity to test it and discover that it has been ended.
void sm_SemUnend(sm_SemId semId)
This function is used to reset an ended semaphore, so that a restarted subsystem can reuse that semaphore rather than delete it and allocate a new one.
int sm_SemUnwedge(sm_SemId semId, int timeoutSeconds)
Used to release semaphores that have been taken but never released, possibly because the tasks or processes that took them crashed before releasing them. Attempts to take the semaphore; if this attempt does not succeed within timeoutSeconds seconds (providing time for normal processing to be completed, in the event that the semaphore is legitimately and temporarily locked by some task), the semaphore is assumed to be wedged. In any case, the semaphore is then released. Returns 0 on success, -1 on any error.
void sm_SemDelete(sm_SemId semId)
Destroys the indicated semaphore.
sm_SemId sm_GetTaskSemaphore(int taskId)
Returns the ID of the semaphore that is dedicated to the private use of the indicated task, or SM_SEM_NONE on any error.
This function implements the concept that for each task there can always be one dedicated semaphore, which the task can always use for its own purposes, whose key value may be known a priori because the key of the semaphore is based on the task's ID. The design of the function rests on the assumption that each task's ID, whether a VxWorks task ID or a Unix process ID, maps to a number that is out of the range of all possible key values that are arbitrarily produced by sm_GetUniqueKey(). For VxWorks, we assume this to be true because task ID is a pointer to task state in memory which we assume not to exceed 2GB; the unique key counter starts at 2GB. For Unix, we assume this to be true because process ID is an index into a process table whose size is less than 64K; unique keys are formed by shifting process ID left 16 bits and adding the value of an incremented counter which is always greater than zero.
int sm_ShmAttach(int key, int size, char **shmPtr, int *id)
Attaches to a segment of memory to which tasks or processes residing in a common system memory, but possibly multiple address spaces, all have access.
This function registers the invoking task or process as a user of the shared memory segment identified by key. If key is the constant value SM_NO_KEY, automatically sets key to some unused key value. If a shared memory segment identified by key already exists, then size may be zero and the value of *shmPtr is ignored. Otherwise the size of the shared memory segment must be provided in size and a new shared memory segment is created in a manner that is dependent on *shmPtr: if *shmPtr is NULL then size bytes of shared memory are dynamically acquired, allocated, and assigned to the newly created shared memory segment; otherwise the memory located at shmPtr is assumed to have been pre-allocated and is merely assigned to the newly created shared memory segment.
On success, stores the unique shared memory ID of the segment in *id for possible future destruction, stores a pointer to the segment's assigned memory in *shmPtr, and returns 1 (if the segment is newly created) or 0 (otherwise). Returns -1 on any error.
void sm_ShmDetach(char *shmPtr)
Unregisters the invoking task or process as a user of the shared memory starting at shmPtr.
void sm_ShmDestroy(int id)
Destroys the shared memory segment identified by id, releasing any memory that was allocated when the segment was created.
int sm_TaskIdSelf( )
Returns the unique identifying number of the invoking task or process.
int sm_TaskExists(int taskId)
Returns non-zero if a task or process identified by taskId is currently running on the local processor, zero otherwise.
void *sm_TaskVar(void **arg)
Posts or retrieves the value of the \"task variable\" belonging to the invoking task. Each task has access to a single task variable, initialized to NULL, that resides in the task's private state; this can be convenient for passing task-specific information to a signal handler, for example. If arg is non-NULL, then *arg is posted as the new value of the task's private task variable. In any case, the value of that task variable is returned.
void sm_TaskSuspend( )
Indefinitely suspends execution of the invoking task or process. Helpful if you want to freeze an application at the point at which an error is detected, then use a debugger to examine its state.
void sm_TaskDelay(int seconds)
Same as snooze(3).
void sm_TaskYield( )
Relinquishes CPU temporarily for use by other tasks.
int sm_TaskSpawn(char *name, char *arg1, char *arg2, char *arg3, char *arg4, char *arg5, char *arg6, char *arg7, char *arg8, char *arg9, char *arg10, int priority, int stackSize)
Spawns/forks a new task/process, passing it up to ten command-line arguments. name is the name of the function (VxWorks) or executable image (UNIX) to be executed in the new task/process.
For UNIX, name must be the name of some executable program in the $PATH of the invoking process.
For VxWorks, name must be the name of some function named in an application-defined private symbol table (if PRIVATE_SYMTAB is defined) or the system symbol table (otherwise). If PRIVATE_SYMTAB is defined, the application must provide a suitable adaptation of the symtab.c source file, which implements the private symbol table.
\"priority\" and \"stackSize\" are ignored under UNIX. Under VxWorks, if zero they default to the values in the application-defined private symbol table if provided, or otherwise to ICI_PRIORITY (nominally 100) and 32768 respectively.
Returns the task/process ID of the new task/process on success, or -1 on any error.
void sm_TaskKill(int taskId, int sigNbr)
Sends the indicated signal to the indicated task or process.
void sm_TaskDelete(int taskId)
Terminates the indicated task or process.
void sm_Abort()
Terminates the calling task or process. If not called while ION is in flight configuration, a stack trace is printed or a core file is written.
int pseudoshell(char *script)
Parses script into a command name and up to 10 arguments, then passes the command name and arguments to sm_TaskSpawn() for execution. The sm_TaskSpawn() function is invoked with priority and stack size both set to zero, causing default values (possibly from an application-defined private symbol table) to be used. Tokens in script are normally whitespace-delimited, but a token that is enclosed in single-quote characters (') may contain embedded whitespace and may contain escaped single-quote characters (\"\\'\"). On any parsing failure returns -1; otherwise returns the value returned by sm_TaskSpawn().
Compiling an application that uses \"platform\":
Just be sure to \"#include \"platform.h\"\" at the top of each source file that includes any platform function calls.
Linking/loading an application that uses \"platform\":
a. In a Solaris environment, link with these libraries:\n\n -lplatform -socket -nsl -posix4 -c\n\nb. In a Linux environment, simply link with platform:\n\n -lplatform\n\nc. In a VxWorks environment, use\n\n ld 1, 0, \"libplatform.o\"\n\n to load platform on the target before loading applications.\ngettimeofday(3C)
"},{"location":"man/ici/psm/","title":"NAME","text":"psm - Personal Space Management
"},{"location":"man/ici/psm/#synopsis","title":"SYNOPSIS","text":"#include \"psm.h\"\n\ntypedef enum { Okay, Redundant, Refused } PsmMgtOutcome;\ntypedef unsigned long PsmAddress;\ntypedef struct psm_str\n{\n char *space;\n int freeNeeded;\n struct psm_str *trace;\n int traceArea[3];\n} PsmView, *PsmPartition;\n\n[see description for available functions]\nPSM is a library of functions that support personal space management, that is, user management of an application-configured memory partition. PSM is designed to be faster and more efficient than malloc/free (for details, see the DETAILED DESCRIPTION below), but more importantly it provides a memory management abstraction that insulates applications from differences in the management of private versus shared memory.
PSM is often used to manage shared memory partitions. On most operating systems, separate tasks that connect to a common shared memory partition are given the same base address with which to access the partition. On some systems (such as Solaris) this is not necessarily the case; an absolute address within such a shared partition will be mapped to different pointer values in different tasks. If a pointer value is stored within shared memory and used without conversion by multiple tasks, segment violations will occur.
PSM gets around this problem by providing functions for translating between local pointer values and relative addresses within the shared memory partition. For complete portability, applications which store addresses in shared memory should store these addresses as PSM relative addresses and convert them to local pointer values before using them. The PsmAddress data type is provided for this purpose, along with the conversion functions psa() and psp().
int psm_manage(char *start, unsigned int length, char *name, PsmPartition *partitionPointer, PsmMgtOutcome *outcome)
Puts the length bytes of memory at start under PSM management, associating this memory partition with the identifying string name (which is required and which can have a maximum string length of 31). PSM can manage any contiguous range of addresses to which the application has access, typically a block of heap memory returned by a malloc call.
Every other PSM API function must be passed a pointer to a local \"partition\" state structure characterizing the PSM-managed memory to which the function is to be applied. The partition state structure itself may be pre-allocated in static or local (or shared) memory by the application, in which case a pointer to that structure must be passed to psm_manage() as the value of *partitionPointer; if *partitionPointer is null, psm_manage() will use malloc() to allocate this structure dynamically from local memory and will store a pointer to the structure in *partitionPointer.
psm_manage() formats the managed memory as necessary and returns -1 on any error, 0 otherwise. The outcome to the attempt to manage memory is placed in outcome. An outcome of Redundant means that the memory at start is already under PSM management with the same name and size. An outcome of Refused means that PSM was unable to put the memory at start under PSM management as directed; a diagnostic message was posted to the message pool (see discussion of putErrmsg() in platform(3)).
char *psm_name(PsmPartition partition)
Returns the name associated with the partition at the time it was put under management.
char *psm_space(PsmPartition partition)
Returns the address of the space managed by PSM for partition. This function is provided to enable the application to do an operating-system release (such as free()) of this memory when the managed partition is no longer needed. NOTE that calling psm_erase() or psm_unmanage() [or any other PSM function, for that matter] after releasing that space is virtually guaranteed to result in a segmentation fault or other seriously bad behavior.
void *psp(PsmPartition partition, PsmAddress address)
address is an offset within the space managed for the partition. Returns the conversion of that offset into a locally usable pointer.
PsmAddress psa(PsmPartition partition, void *pointer)
Returns the conversion of pointer into an offset within the space managed for the partition.
PsmAddress psm_malloc(PsmPartition partition, unsigned int length)
Allocates a block of memory from the \"large pool\" of the indicated partition. (See the DETAILED DESCRIPTION below.) length is the size of the block to allocate; the maximum size is 1/2 of the total address space (i.e., 2G for a 32-bit machine). Returns NULL if no free block could be found. The block returned is aligned on a doubleword boundary.
void psm_panic(PsmPartition partition)
Forces the \"large pool\" memory allocation algorithm to hunt laboriously for free blocks in buckets that may not contain any. This setting remains in force for the indicated partition until a subsequent psm_relax() call reverses it.
void psm_relax(PsmPartition partition)
Reverses psm_panic(). Lets the \"large pool\" memory allocation algorithm return NULL when no free block can be found easily.
PsmAddress psm_zalloc(PsmPartition partition, unsigned int length)
Allocates a block of memory from the \"small pool\" of the indicated partition, if possible; if the requested block size -- length -- is too large for small pool allocation (which is limited to 64 words, i.e., 256 bytes for a 32-bit machine), or if no small pool space is available and the size of the small pool cannot be increased, then allocates from the large pool instead. Small pool allocation is performed by an especially speedy algorithm, and minimum space is consumed in memory management overhead for small-pool blocks. Returns NULL if no free block could be found. The block returned is aligned on a word boundary.
void psm_free(PsmPartition partition, PsmAddress block)
Frees for subsequent re-allocation the indicated block of memory from the indicated partition. block may have been allocated by either psm_malloc() or psm_zalloc().
int psm_set_root(PsmPartition partition, PsmAddress root)
Sets the \"root\" word of the indicated partition (a word at a fixed, private location in the PSM bookkeeping data area) to the indicated value. This function is typically useful in a shared-memory environment, such as a VxWorks address space, in which a task wants to retrieve from the indicated partition some data that was inserted into the partition by some other task; the partition root word enables multiple tasks to navigate the same data in the same PSM partition in shared memory. The argument is normally a pointer to something like a linked list of the linked lists that populate the partition; in particular, it is likely to be an object catalog (see psm_add_catlg()). Returns 0 on success, -1 on any failure (e.g., the partition already has a root object, in which case psm_erase_root() must be called before psm_set_root()).
PsmAddress psm_get_root(PsmPartition partition)
Retrieves the current value of the root word of the indicated partition.
void psm_erase_root(PsmPartition partition)
Erases the current value of the root word of the indicated partition.
PsmAddress psm_add_catlg(PsmPartition partition)
Allocates space for an object catalog in the indicated partition and establishes the new catalog as the partition's root object. Returns 0 on success, -1 on any error (e.g., the partition already has some other root object).
int psm_catlg(PsmPartition partition, char *objName, PsmAddress objLocation)
Inserts an entry for the indicated object into the catalog that is the root object for this partition. The length of objName cannot exceed 32 bytes, and objName must be unique in the catalog. Returns 0 on success, -1 on any error.
int psm_uncatlg(PsmPartition partition, char *objName)
Removes the entry for the named object from the catalog that is the root object for this partition, if that object is found in the catalog. Returns 0 on success, -1 on any error.
int psm_locate(PsmPartition partition, char *objName, PsmAddress *objLocation, PsmAddress *entryElt)
Places in *objLocation the address associated with objName in the catalog that is the root object for this partition and places in *entryElt the address of the list element that points to this catalog entry. If name is not found in catalog, set *entryElt to zero. Returns 0 on success, -1 on any error.
void psm_usage(PsmPartition partition, PsmUsageSummary *summary)
Loads the indicated PsmUsageSummary structure with a snapshot of the indicated partition's usage status. PsmUsageSummary is defined by:
typedef struct {\n char partitionName[32];\n unsigned int partitionSize;\n unsigned int smallPoolSize;\n unsigned int smallPoolFreeBlockCount[SMALL_SIZES];\n unsigned int smallPoolFree;\n unsigned int smallPoolAllocated;\n unsigned int largePoolSize;\n unsigned int largePoolFreeBlockCount[LARGE_ORDERS];\n unsigned int largePoolFree;\n unsigned int largePoolAllocated;\n unsigned int unusedSize;\n} PsmUsageSummary;\nvoid psm_report(PsmUsageSummary *summary)
Sends to stdout the content of summary, a snapshot of a partition's usage status.
void psm_unmanage(PsmPartition partition)
Terminates local PSM management of the memory in partition and destroys the partition state structure *partition, but doesn't erase anything in the managed memory; PSM management can be re-established by a subsequent call to psm_manage().
void psm_erase(PsmPartition partition)
Unmanages the indicated partition and additionally discards all information in the managed memory, preventing re-management of the partition.
If PSM_TRACE is defined at the time the PSM source code is compiled, the system includes built-in support for simple tracing of memory usage: memory allocations are logged, and memory deallocations are matched to logged allocations, \"closing\" them. This enables memory leaks and some other kinds of memory access problems to be readily investigated.
int psm_start_trace(PsmPartition partition, int traceLogSize, char *traceLogAddress)
Begins an episode of PSM memory usage tracing. traceLogSize is the number of bytes of shared memory to use for trace activity logging; the frequency with which \"closed\" trace log events must be deleted will vary inversely with the amount of memory allocated for the trace log. traceLogAddress is normally NULL, causing the trace system to allocate traceLogSize bytes of shared memory dynamically for trace logging; if non-NULL, it must point to traceLogSize bytes of shared memory that have been pre-allocated by the application for this purpose. Returns 0 on success, -1 on any failure.
void psm_print_trace(PsmPartition partition, int verbose)
Prints a cumulative trace report and current usage report for partition. If verbose is zero, only exceptions (notably, trace log events that remain open -- potential memory leaks) are printed; otherwise all activity in the trace log is printed.
void psm_clear_trace(PsmPartition partition)
Deletes all closed trace log events from the log, freeing up memory for additional tracing.
void psm_stop_trace(PsmPartition partition)
Ends the current episode of PSM memory usage tracing. If the shared memory used for the trace log was allocated by psm_start_trace(), releases that shared memory.
For an example of the use of psm, see the file psmshell.c in the PSM source directory.
"},{"location":"man/ici/psm/#users-guide","title":"USER'S GUIDE","text":"Compiling a PSM application
Just be sure to \"#include \"psm.h\"\" at the top of each source file that includes any PSM function calls.
Linking/loading a PSM application
a. In a UNIX environment, link with libpsm.a.
b. In a VxWorks environment, use
ld 1, 0, \"libpsm.o\"\nto load PSM on the target before loading any PSM applications.
Typical usage:
a. Call psm_manage() to initiate management of the partition.
b. Call psm_malloc() (and/or psm_zalloc()) to allocate space in the partition; call psm_free() to release space for later re-allocation.
c. When psm_malloc() returns NULL and you're willing to wait a while for a more exhaustive free block search, call psm_panic() before retrying psm_malloc(). When you're no longer so desperate for space, call psm_relax().
d. To store a vital pointer in the single predefined location in the partition that PSM reserves for this purpose, call psm_set_root(); to retrieve that pointer, call psm_get_root().
e. To get a snapshot of the current configuration of the partition, call psm_usage(). To print this snapshot to stdout, call psm_report().
f. When you're done with the partition but want to leave it in its current state for future re-management (e.g., if the partition is in shared memory), call psm_unmanage(). If you're done with the partition forever, call psm_erase().
PSM supports user management of an application-configured memory partition. The partition is functionally divided into two pools of variable size: a \"small pool\" of low-overhead blocks aligned on 4-byte boundaries that can each contain up to 256 bytes of user data, and a \"large pool\" of high-overhead blocks aligned on 8-byte boundaries that can each contain up to 2GB of user data.
Space in the small pool is allocated in any one of 64 different block sizes; each possible block size is (4i + n) where i is a \"block list index\" from 1 through 64 and n is the length of the PSM overhead information per block [4 bytes on a 32-bit machine]. Given a user request for a block of size q where q is in the range 1 through 256 inclusive, we return the first block on the j'th small-pool free list where j = (q - 1) / 4. If there is no such block, we increase the size of the small pool [incrementing its upper limit by (4 * (j + 1)) + n], initialize the increase as a free block from list j, and return that block. No attempt is made to consolidate physically adjacent blocks when they are freed or to bisect large blocks to satisfy requests for small ones; if there is no free block of the requested size and the size of the small pool cannot be increased without encroaching on the large pool (or if the requested size exceeds 256), we attempt to allocate a large-pool block as described below. The differences between small-pool and large-pool blocks are transparent to the user, and small-pool and large-pool blocks can be freely intermixed in an application.
Small-pool blocks are allocated and freed very rapidly, and space overhead consumption is small, but capacity per block is limited and space assigned to small-pool blocks of a given size is never again available for any other purpose. The small pool is designed to satisfy requests for allocation of a stable overall population of small, volatile objects such as List and ListElt structures (see lyst(3)).
Space in the large pool is allocated from any one of 29 buckets, one for each power of 2 in the range 8 through 2G. The size of each block can be expressed as (n + 8i + m) where i is any integer in the range 1 through 256M, n is the size of the block's leading overhead area [8 bytes on a 32-bit machine], and m is the size of the block's trailing overhead area [also 8 bytes on a 32-bit machine]. Given a user request for a block of size q where q is in the range 1 through 2G inclusive, we first compute r as the smallest multiple of 8 that is greater than or equal to q. We then allocate the first block in bucket t such that 2 ** (t + 3) is the smallest power of 2 that is greater than r [or, if r is a power of 2, the first block in bucket t such that 2 ** (t + 3) = r]. That is, we try to allocate blocks of size 8 from bucket 0 [2**3 = 8], blocks of size 16 from bucket 1 [2**4 = 16], blocks of size 24 from bucket 2 [2**5 = 32, 32 > 24], blocks of size 32 from bucket 2 [2**5 = 32], and so on. t is the first bucket whose free blocks are ALL guaranteed to be at least as large as r; bucket t - 1 may also contain some blocks that are as large as r (e.g., bucket 1 will contain blocks of size 24 as well as blocks of size 16), but we would have to do a possibly time consuming sequential search through the free blocks in that bucket to find a match, because free blocks within a bucket are stored in no particular order.
If bucket t is empty, we allocate the first block from the first non-empty bucket corresponding to a greater power of two; if all eligible bucket are empty, we increase the size of the large pool [decrementing its lower limit by (r + 16)], initialize the increase as a free block and \"free\" it, and try again. If the size of the large pool cannot be increased without encroaching on the small pool, then if we are desperate we search sequentially through all blocks in bucket t - 1 (some of which may be of size r or greater) and allocate the first block that is big enough, if any. Otherwise, no block is returned.
Having selected a free block to allocate, we remove the allocated block from the free list, split off as a new free block all bytes in excess of (r + 16) bytes [unless that excess is too small to form a legal-size block], and return the remainder to the user. When a block is freed, it is automatically consolidated with the physically preceding block (if that block is free) and the physically subsequent block (if that block is free).
Large-pool blocks are allocated and freed quite rapidly; capacity is effectively unlimited; space overhead consumption is very high for extremely small objects but becomes an insignificant fraction of block size as block size increases. The large pool is designed to serve as a general-purpose heap with minimal fragmentation whose overhead is best justified when used to store relatively large, long-lived objects such as image packets.
The general goal of this memory allocation scheme is to satisfy memory management requests rapidly and yet minimize the chance of refusing a memory allocation request when adequate unused space exists but is inaccessible (because it is fragmentary or is buried as unused space in a block that is larger than necessary). The size of a small-pool block delivered to satisfy a request for q bytes will never exceed q + 3 (alignment), plus 4 bytes of overhead. The size of a large-pool block delivered to satisfy a request for q bytes will never exceed q + 7 (alignment) + 20 (the maximum excess that can't be split off as a separate free block), plus 16 bytes of overhead.
Neither the small pool nor the large pool ever decrease in size, but large-pool space previously allocated and freed is available for small-pool allocation requests if no small-pool space is available. Small-pool space previously allocated and freed cannot easily be reassigned to the large pool, though, because blocks in the large pool must be physically contiguous to support defragmentation. No such reassignment algorithm has yet been developed.
"},{"location":"man/ici/psm/#see-also","title":"SEE ALSO","text":"lyst(3)
"},{"location":"man/ici/psmshell/","title":"NAME","text":"psmshell - PSM memory management test shell
"},{"location":"man/ici/psmshell/#synopsis","title":"SYNOPSIS","text":"psmshell partition_size
"},{"location":"man/ici/psmshell/#description","title":"DESCRIPTION","text":"psmshell allocates a region of partition_size bytes of system memory, places it under PSM management, and offers the user an interactive \"shell\" for testing various PSM management functions.
psmshell prints a prompt string (\": \") to stdout, accepts a command from stdin, executes the command (possibly printing a diagnostic message), then prints another prompt string and so on.
The locations of objects allocated from the PSM-managed region of memory are referred to as \"cells\" in psmshell operations. That is, when an object is to be allocated, a cell number in the range 0-99 must be specified as the notional \"handle\" for that object, for use in future commands.
The following commands are supported:
h
The help command. Causes psmshell to print a summary of available commands. Same effect as the ? command.
?
Another help command. Causes psmshell to print a summary of available commands. Same effect as the h command.
m cell_nbr size
The malloc command. Allocates a large-pool object of the indicated size and associates that object with cell_nbr.
z cell_nbr size
The zalloc command. Allocates a small-pool object of the indicated size and associates that object with cell_nbr.
p cell_nbr
The print command. Prints the address (i.e., the offset within the managed block of memory) of the object associated with cell_nbr.
f cell_nbr
The free command. Frees the object associated with cell_nbr, returning the space formerly occupied by that object to the appropriate free block list.
u
The usage command. Prints a partition usage report, as per psm_report(3).
q
The quit command. Frees the allocated system memory in the managed block and terminates psmshell.
\"0\"
psmshell has terminated.
No configuration files are needed.
"},{"location":"man/ici/psmshell/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/psmshell/#diagnostics","title":"DIAGNOSTICS","text":"IPC initialization failed.
ION system error. Investigate, correct problem, and try again.
psmshell: can't allocate space; quitting.
Insufficient available system memory for selected partition size.
psmshell: can't allocate test variables; quitting.
Insufficient available system memory for selected partition size.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/psmshell/#see-also","title":"SEE ALSO","text":"psm(3)
"},{"location":"man/ici/psmwatch/","title":"NAME","text":"psmwatch - PSM memory partition activity monitor
"},{"location":"man/ici/psmwatch/#synopsis","title":"SYNOPSIS","text":"psmwatch shared_memory_key memory_size partition_name interval count [ verbose ]
"},{"location":"man/ici/psmwatch/#description","title":"DESCRIPTION","text":"For count interations, psmwatch sleeps interval seconds and then invokes the psm_print_trace() function (see psm(3)) to report on PSM dynamic memory management activity in the PSM-managed shared memory partition identified by shared_memory_key during that interval. If the optional verbose parameter is specified, the printed PSM activity trace will be verbose as described in psm(3).
To prevent confusion, the specified memory_size and partition_name are compared to those declared when this shared memory partition was initially managed; if they don't match, psmwatch immediately terminates.
If interval is zero, psmwatch merely prints a current usage summary for the indicated shared-memory partition and terminates.
psmwatch is helpful for detecting and diagnosing memory leaks. For debugging the ION protocol stack:
shared_memory_key
Normally \"65281\", but might be overridden by the value of wmKey in the .ionconfig file used to configure the node under study.
memory_size
As given by the value of wmKey in the .ionconfig file used to configure the node under study. If this value is not stated in the .ionconfig file, the default value is \"5000000\".
partition_name
Always \"ionwm\".
\"0\"
psmwatch has terminated.
No configuration files are needed.
"},{"location":"man/ici/psmwatch/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/psmwatch/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to psm.
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 start trace.
Insufficient ION working memory to contain trace information. Reinitialize ION with more memory.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/psmwatch/#see-also","title":"SEE ALSO","text":"psm(3), sdrwatch(1)
"},{"location":"man/ici/rfxclock/","title":"NAME","text":"rfxclock - ION daemon task for managing scheduled events
"},{"location":"man/ici/rfxclock/#synopsis","title":"SYNOPSIS","text":"rfxclock
"},{"location":"man/ici/rfxclock/#description","title":"DESCRIPTION","text":"rfxclock is a background \"daemon\" task that periodically applies scheduled changes in node connectivity and range to the ION node's database. It is spawned automatically by ionadmin in response to the 's' command that starts operation of the ION node infrastructure, and it is terminated by ionadmin in response to an 'x' (STOP) command.
Once per second, rfxclock takes the following action:
For each neighboring node that has been refusing custody of bundles sent to it to be forwarded to some destination node, to which no such bundle has been sent for at least N seconds (where N is twice the one-way light time from the local node to this neighbor), rfxclock turns on a probeIsDue flag authorizing transmission of the next such bundle in hopes of learning that this neighbor is now able to accept custody.
Then rfxclock purges the database of all range and contact information that is no longer applicable, based on the stop times of the records.
Finally, rfxclock applies to the database all range and contact information that is currently applicable, i.e., those records whose start times are before the current time and whose stop times are in the future.
"},{"location":"man/ici/rfxclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
rfxclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ionadmin to restart rfxclock.
\"1\"
rfxclock was unable to attach to the local ION node, probably because ionadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/ici/rfxclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/rfxclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
rfxclock can't attach to ION.
ionadmin has not yet initialized the ION database.
Can't apply ranges.
An unrecoverable database error was encountered. rfxclock terminates.
Can't apply contacts.
An unrecoverable database error was encountered. rfxclock terminates.
Can't purge ranges.
An unrecoverable database error was encountered. rfxclock terminates.
Can't purge contacts.
An unrecoverable database error was encountered. rfxclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/rfxclock/#see-also","title":"SEE ALSO","text":"ionadmin(1)
"},{"location":"man/ici/sdr/","title":"NAME","text":"sdr - Simple Data Recorder library
"},{"location":"man/ici/sdr/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\n[see below for available functions]\nSDR is a library of functions that support the use of an abstract data recording device called an \"SDR\" (\"simple data recorder\") for persistent storage of data. The SDR abstraction insulates software not only from the specific characteristics of any single data storage device but also from some kinds of persistent data storage and retrieval chores. The underlying principle is that an SDR provides standardized support for user data organization at object granularity, with direct access to persistent user data objects, rather than supporting user data organization only at \"file\" granularity and requiring the user to implement access to the data objects accreted within those files.
The SDR library is designed to provide some of the same kinds of directory services as a file system together with support for complex data structures that provide more operational flexibility than files. (As an example of this flexibility, consider how much easier and faster it is to delete a given element from the middle of a linked list than it is to delete a range of bytes from the middle of a text file.) The intent is to enable the software developer to take maximum advantage of the high speed and direct byte addressability of a non-volatile flat address space in the management of persistent data. The SDR equivalent of a \"record\" of data is simply a block of nominally persistent memory allocated from this address space. The SDR equivalent of a \"file\" is a collection object. Like files, collections can have names, can be located by name within persistent storage, and can impose structure on the data items they encompass. But, as discussed later, SDR collection objects can impose structures other than the strict FIFO accretion of records or bytes that characterizes a file.
The notional data recorder managed by the SDR library takes the form of a single array of randomly accessible, contiguous, nominally persistent memory locations called a heap. Physically, the heap may be implemented as a region of shared memory, as a single file of predefined size, or both -- that is, the heap may be a region of shared memory that is automatically mirrored in a file.
SDR services that manage SDR data are provided in several layers, each of which relies on the services implemented at lower levels:
At the highest level, a cataloguing service enables retrieval of persistent objects by name.
Services that manage three types of persistent data collections are provided for use both by applications and by the cataloguing service: linked lists, self-delimiting tables (which function as arrays that remember their own dimensions), and self-delimiting strings (short character arrays that remember their lengths, for speedier retrieval).
Basic SDR heap space management services, analogous to malloc() and free(), enable the creation and destruction of objects of arbitrary type.
Farther down the service stack are memcpy-like low-level functions for reading from and writing to the heap.
Protection of SDR data integrity across a series of reads and writes is provided by a transaction mechanism.
SDR persistent data are referenced in application code by Object values and Address values, both of which are simply displacements (offsets) within SDR address space. The difference between the two is that an Object is always the address of a block of heap space returned by some call to sdr_malloc(), while an Address can refer to any byte in the address space. That is, an Address is the SDR functional equivalent of a C pointer in DRAM, and some Addresses point to Objects.
Before using SDR services, the services must be loaded to the target machine and initialized by invoking the sdr_initialize() function and the management profiles of one or more SDR's must be loaded by invoking the sdr_load_profile() function. These steps are normally performed only once, at application load time.
An application gains access to an SDR by passing the name of the SDR to the sdr_start_using() function, which returns an Sdr pointer. Most other SDR library functions take an Sdr pointer as first argument.
All writing to an SDR heap must occur during a transaction that was initiated by the task issuing the write. Transactions are single-threaded; if task B wants to start a transaction while a transaction begun by task A is still in progress, it must wait until A's transaction is either ended or cancelled. A transaction is begun by calling sdr_begin_xn(). The current transaction is normally ended by calling the sdr_end_xn() function, which returns an error return code value in the event that any serious SDR-related processing error was encountered in the course of the transaction. Transactions may safely be nested, provided that every level of transaction activity that is begun is properly ended.
The current transaction may instead be cancelled by calling sdr_cancel_xn(), which is normally used to indicate that some sort of serious SDR-related processing error has been encountered. Canceling a transaction reverses all SDR update activity performed up to that point within the scope of the transaction -- and, if the canceled transaction is an inner, nested transaction, all SDR update activity performed within the scope of every outer transaction encompassing that transaction and every other transaction nested within any of those outer transactions -- provided the SDR was configured for transaction reversibility. When an SDR is configured for reversibility, all heap write operations performed during a transaction are recorded in a log file that is retained until the end of the transaction. Each log file entry notes the location at which the write operation was performed, the length of data written, and the content of the overwritten heap bytes prior to the write operation. Canceling the transaction causes the log entries to be read and processed in reverse order, restoring all overwritten data. Ending the transaction, on the other hand, simply causes the log to be discarded.
If a log file exists at the time that the profile for an SDR is loaded (typically during application initialization), the transaction that was being logged is automatically canceled and reversed. This ensures that, for example, a power failure that occurs in the middle of a transaction will never wreck the SDR's data integrity: either all updates issued during a given transaction are reflected in the current dataspace content or none are.
As a further measure to protect SDR data integrity, an SDR may additionally be configured for object bounding. When an SDR is configured to be \"bounded\", every heap write operation is restricted to the extent of a single object allocated from heap space; that is, it's impossible to overwrite part of one object by writing beyond the end of another. To enable the library to enforce this mechanism, application code is prohibited from writing anywhere but within the extent of an object that either (a) was allocated from managed heap space during the same transaction (directly or indirectly via some collection management function) or (b) was staged -- identified as an update target -- during the same transaction (again, either directly or via some collection management function).
Note that both transaction reversibility and object bounding consume processing cycles and inhibit performance to some degree. Determining the right balance between operational safety and processing speed is left to the user.
Note also that, since SDR transactions are single-threaded, they can additionally be used as a general mechanism for simply implementing \"critical sections\" in software that is already using SDR for other purposes: the beginning of a transaction marks the start of code that can't be executed concurrently by multiple tasks. To support this use of the SDR transaction mechanism, the additional transaction termination function sdr_exit_xn() is provided. sdr_exit_xn() simply ends a transaction without either signaling an error or checking for errors. Like sdr_cancel_xn(), sdr_exit_xn() has no return value; unlike sdr_cancel_xn(), it assures that ending an inner, nested transaction does not cause the outer transaction to be aborted and backed out. But this capability must be used carefully: the protection of SDR data integrity requires that transactions which are ended by sdr_exit_xn() must not encompass any SDR update activity whatsoever.
The heap space management functions of the SDR library are adapted directly from the Personal Space Management (psm) function library. The manual page for psm(3) explains the algorithms used and the rationale behind them. The principal difference between PSM memory management and SDR heap management is that, for performance reasons, SDR reserves the \"small pool\" for its own use only; all user data space is allocated from the \"large pool\", via the sdr_malloc() function.
"},{"location":"man/ici/sdr/#return-values-and-error-handling","title":"RETURN VALUES AND ERROR HANDLING","text":"Whenever an SDR function call fails, a diagnostic message explaining the failure of the function is recorded in the error message pool managed by the \"platform\" system (see the discussion of putErrmsg() in platform(3)).
The failure of any function invoked in the course of an SDR transaction causes all subsequent SDR activity in that transaction to fail immediately. This can streamline SDR application code somewhat: it may not be necessary to check the return value of every SDR function call executed during a transaction. If the sdr_end_xn() call returns zero, all updates performed during the transaction must have succeeded.
"},{"location":"man/ici/sdr/#system-administration-functions","title":"SYSTEM ADMINISTRATION FUNCTIONS","text":"int sdr_initialize(int wmSize, char *wmPtr, int wmKey, char *wmName)
Initializes the SDR system. sdr_initialize() must be called once every time the computer on which the system runs is rebooted, before any call to any other SDR library function.
This function attaches to a pool of shared memory, managed by PSM (see psm(3), that enables SDR library operations. If the SDR system is to access a common pool of shared memory with one or more other systems, the key of that shared memory segment must be provided in wmKey and the PSM partition name associated with that memory segment must be provided in wmName; otherwise wmKey must be zero and wmName must be NULL, causing sdr_initialize() to assign default values. If a shared memory segment identified by the effective value of wmKey already exists, then wmSize may be zero and the value of wmPtr is ignored. Otherwise the size of the shared memory pool must be provided in wmSize and a new shared memory segment is created in a manner that is dependent on wmPtr: if wmPtr is NULL then wmSize bytes of shared memory are dynamically acquired, allocated, and assigned to the newly created shared memory segment; otherwise the memory located at wmPtr is assumed to have been pre-allocated and is merely assigned to the newly created shared memory segment.
sdr_initialize() also creates a semaphore to serialize access to the SDR system's private array of SDR profiles.
Returns 0 on success, -1 on any failure.
void sdr_wm_usage(PsmUsageSummary *summary)
Loads summary with a snapshot of the usage of the SDR system's private working memory. To print the snapshot, use psm_report(). (See psm(3).)
void sdr_shutdown( )
Ends all access to all SDRs (see sdr_stop_using()), detaches from the SDR system's working memory (releasing the memory if it was dynamically allocated by sdr_initialize()), and destroys the SDR system's private semaphore. After sdr_shutdown(), sdr_initialize() must be called again before any call to any other SDR library function.
int sdr_load_profile(char *name, int configFlags, long heapWords, int heapKey, int logSize, int logKey, char *pathName, char *restartCmd, unsigned int restartLatency)
Loads the profile for an SDR into the system's private list of SDR profiles. Although SDRs themselves are persistent, SDR profiles are not: in order for an application to access an SDR, sdr_load_profile() must have been called to load the profile of the SDR since the last invocation of sdr_initialize().
name is the name of the SDR, required for any subsequent sdr_start_using() call.
configFlags specifies the configuration of the SDR, the bitwise \"or\" of some combination of the following:
SDR_IN_DRAM
SDR dataspace is implemented as a region of shared memory.
SDR_IN_FILE
SDR dataspace is implemented as a file.
SDR_REVERSIBLE
SDR transactions are logged and are reversed if canceled.
SDR_BOUNDED
Heap updates are not allowed to cross object boundaries.
heapWords specifies the size of the heap in words; word size depends on machine architecture, i.e., a word is 4 bytes on a 32-bit machine, 8 bytes on a 64-bit machine. Note that each SDR prepends to the heap a \"map\" of predefined, fixed size. The total amount of space occupied by an SDR dataspace in memory and/or in a file is the sum of the size of the map plus the product of word size and heapWords.
heapKey is ignored if configFlags does not include SDR_IN_DRAM. It should normally be SM_NO_KEY, causing the shared memory region for the SDR dataspace to be allocated dynamically and shared using a dynamically selected shared memory key. If specified, heapKey must be a shared memory key identifying a pre-allocated region of shared memory whose length is equal to the total SDR dataspace size, shared via the indicated key.
logSize specifies the maximum size of the transaction log (in bytes) if and only if the log is to be written to memory rather than to a file; otherwise it must be zero. logKey is ignored if logSize is zero. It should normally be SM_NO_KEY, causing the shared memory region for the transaction log to be allocated dynamically and shared using a dynamically selected shared memory key. If specified, logKey must be a shared memory key identifying a pre-allocated region of shared memory whose length is equal to logSize, shared via the indicated key.
pathName is ignored if configFlags includes neither SDR_REVERSIBLE nor SDR_IN_FILE. It is the fully qualified name of the directory into which the SDR's log file and/or dataspace file will be written. The name of the log file (if any) will be \"<sdrname>.sdrlog\". The name of the dataspace file (if any) will be \"<sdrname>.sdr\"; this file will be automatically created and filled with zeros if it does not exist at the time the SDR's profile is loaded.
If a cleanup task must be run whenever a transaction is reversed, the command to execute this task must be provided in restartCmd and the number of seconds to wait for this task to finish before resuming operations must be provided in restartLatency. If restartCmd is NULL or restartLatency is zero then no cleanup task will be run upon transaction reversal.
Returns 0 on success, -1 on any error.
int sdr_reload_profile(char *name, int configFlags, long heapWords, int heapKey, int logSize, int logKey, char *pathName, char *restartCmd, unsigned int restartLatency)
For use when the state of an SDR is thought to be inconsistent, perhaps due to crash of a program that had a transaction open. Unloads the profile for the SDR, forcing the reversal of any transaction that is currently in progress when the SDR's profile is re-loaded. Then calls sdr_load_profile() to re-load the profile for the SDR. Same return values as sdr_load_profile.
Sdr sdr_start_using(char *name)
Locates SDR profile by name and returns a handle that can be used for all functions that operate on that SDR. On any failure, returns NULL.
char *sdr_name(Sdr sdr)
Returns the name of the sdr.
long sdr_heap_size(Sdr sdr)
Returns the total size of the SDR heap, in bytes.
void sdr_stop_using(Sdr sdr)
Terminates access to the SDR via this handle. Other users of the SDR are not affected. Frees the Sdr object.
void sdr_abort(Sdr sdr)
Terminates the task. In flight configuration, also terminates all use of the SDR system by all tasks.
void sdr_destroy(Sdr sdr)
Ends all access to this SDR, unloads the SDR's profile, and erases the SDR from memory and file system.
int sdr_begin_xn(Sdr sdr)
Initiates a transaction. Returns 1 on success, 0 on any failure. Note that transactions are single-threaded; any task that calls sdr_begin_xn() is suspended until all previously requested transactions have been ended or canceled.
int sdr_in_xn(Sdr sdr)
Returns 1 if called in the course of a transaction, 0 otherwise.
void sdr_exit_xn(Sdr sdr)
Simply abandons the current transaction, ceasing the calling task's lock on ION. Must not be used if any dataspace modifications were performed during the transaction; sdr_end_xn() must be called instead, to commit those modifications.
void sdr_cancel_xn(Sdr sdr)
Cancels the current transaction. If reversibility is enabled for the SDR, canceling a transaction reverses all heap modifications performed during that transaction.
int sdr_end_xn(Sdr sdr)
Ends the current transaction. Returns 0 if the transaction completed without any error; returns -1 if any operation performed in the course of the transaction failed, in which case the transaction was automatically canceled.
void sdr_read(Sdr sdr, char *into, Address from, int length)
Copies length characters at from (a location in the indicated SDR) to the memory location given by into. The data are copied from the shared memory region in which the SDR resides, if any; otherwise they are read from the file in which the SDR resides.
void sdr_peek(sdr, variable, from)
sdr_peek() is a macro that uses sdr_read() to load variable from the indicated address in the SDR dataspace; the size of variable is used as the number of bytes to copy.
void sdr_write(Sdr sdr, Address into, char *from, int length)
Copies length characters at from (a location in memory) to the SDR heap location given by into. Can only be performed during a transaction, and if the SDR is configured for object bounding then heap locations into through (into + (length - 1)) must be within the extent of some object that was either allocated or staged within the same transaction. The data are copied both to the shared memory region in which the SDR resides, if any, and also to the file in which the SDR resides, if any.
void sdr_poke(sdr, into, variable)
sdr_poke() is a macro that uses sdr_write() to store variable at the indicated address in the SDR dataspace; the size of variable is used as the number of bytes to copy.
char *sdr_pointer(Sdr sdr, Address address)
Returns a pointer to the indicated location in the heap - a \"heap pointer\" - or NULL if the indicated address is invalid. NOTE that this function cannot be used if the SDR does not reside in a shared memory region.
Providing an alternative to using sdr_read() to retrieve objects into local memory, sdr_pointer() can help make SDR-based applications run very quickly, but it must be used WITH GREAT CAUTION! Never use a direct pointer into the heap when not within a transaction, because you will have no assurance at any time that the object pointed to by that pointer has not changed (or is even still there). And NEVER de-reference a heap pointer in order to write directly into the heap: this makes transaction reversal impossible. Whenever writing to the SDR, always use sdr_write().
Address sdr_address(Sdr sdr, char *pointer)
Returns the address within the SDR heap of the indicated location, which must be (or be derived from) a heap pointer as returned by sdr_pointer(). Returns zero if the indicated location is not greater than the start of the heap mirror. NOTE that this function cannot be used if the SDR does not reside in a shared memory region.
void sdr_get(sdr, variable, heap_pointer)
sdr_get() is a macro that uses sdr_read() to load variable from the SDR address given by heap_pointer; heap_pointer must be (or be derived from) a heap pointer as returned by sdr_pointer(). The size of variable is used as the number of bytes to copy.
void sdr_set(sdr, heap_pointer, variable)
sdr_set() is a macro that uses sdr_write() to store variable at the SDR address given by heap_pointer; heap_pointer must be (or be derived from) a heap pointer as returned by sdr_pointer(). The size of variable is used as the number of bytes to copy.
Object sdr_malloc(Sdr sdr, unsigned long size)
Allocates a block of space from the of the indicated SDR's heap. size is the size of the block to allocate; the maximum size is 1/2 of the maximum address space size (i.e., 2G for a 32-bit machine). Returns block address if successful, zero if block could not be allocated.
Object sdr_insert(Sdr sdr, char *from, unsigned long size)
Uses sdr_malloc() to obtain a block of space of size size and, if this allocation is successful, uses sdr_write() to copy size bytes of data from memory at from into the newly allocated block. Returns block address if successful, zero if block could not be allocated.
Object sdr_stow(sdr, variable)
sdr_stow() is a macro that uses sdr_insert() to insert a copy of variable into the dataspace. The size of variable is used as the number of bytes to copy.
int sdr_object_length(Sdr sdr, Object object)
Returns the number of bytes of heap space allocated to the application data at object.
void sdr_free(Sdr sdr, Object object)
Frees for subsequent re-allocation the heap space occupied by object.
void sdr_stage(Sdr sdr, char *into, Object from, int length)
Like sdr_read(), this function will copy length characters at from (a location in the heap of the indicated SDR) to the memory location given by into. Unlike sdr_get(), sdr_stage() requires that from be the address of some allocated object, not just any location within the heap. sdr_stage(), when called from within a transaction, notifies the SDR library that the indicated object may be updated later in the transaction; this enables the library to retrieve the object's size for later reference in validating attempts to write into some location within the object. If length is zero, the object's size is privately retrieved by SDR but none of the object's content is copied into memory.
long sdr_unused(Sdr sdr)
Returns number of bytes of heap space not yet allocated to either the large or small objects pool.
void sdr_usage(Sdr sdr, SdrUsageSummary *summary)
Loads the indicated SdrUsageSummary structure with a snapshot of the SDR's usage status. SdrUsageSummary is defined by:
typedef struct\n{\n char sdrName[MAX_SDR_NAME + 1];\n unsigned int dsSize;\n unsigned int smallPoolSize;\n unsigned int smallPoolFreeBlockCount[SMALL_SIZES];\n unsigned int smallPoolFree;\n unsigned int smallPoolAllocated;\n unsigned int largePoolSize;\n unsigned int largePoolFreeBlockCount[LARGE_ORDERS];\n unsigned int largePoolFree;\n unsigned int largePoolAllocated;\n unsigned int unusedSize;\n} SdrUsageSummary;\nvoid sdr_report(SdrUsageSummary *summary)
Sends to stdout a printed summary of the SDR's usage status.
int sdr_heap_depleted(Sdr sdr)
A Boolean function: returns 1 if the total available space in the SDR's heap (small pool free, large pool free, and unused) is less than 1/16 of the total size of the heap. Otherwise returns zero.
If SDR_TRACE is defined at the time the SDR source code is compiled, the system includes built-in support for simple tracing of SDR heap space usage: heap space allocations are logged, and heap space deallocations are matched to logged allocations, \"closing\" them. This enables heap space leaks and some other kinds of SDR heap access problems to be readily investigated.
int sdr_start_trace(Sdr sdr, int traceLogSize, char *traceLogAddress)
Begins an episode of SDR heap space usage tracing. traceLogSize is the number of bytes of shared memory to use for trace activity logging; the frequency with which \"closed\" trace log events must be deleted will vary inversely with the amount of memory allocated for the trace log. traceLogAddress is normally NULL, causing the trace system to allocate traceLogSize bytes of shared memory dynamically for trace logging; if non-NULL, it must point to traceLogSize bytes of shared memory that have been pre-allocated by the application for this purpose. Returns 0 on success, -1 on any failure.
void sdr_print_trace(Sdr sdr, int verbose)
Prints a cumulative trace report and current usage report for sdr. If verbose is zero, only exceptions (notably, trace log events that remain open -- potential SDR heap space leaks) are printed; otherwise all activity in the trace log is printed.
void sdr_clear_trace(Sdr sdr)
Deletes all closed trace log events from the log, freeing up memory for additional tracing.
void sdr_stop_trace(Sdr sdr)
Ends the current episode of SDR heap space usage tracing. If the shared memory used for the trace log was allocated by sdr_start_trace(), releases that shared memory.
The SDR catalogue functions are used to maintain the catalogue of the names, types, and addresses of objects within an SDR. The catalogue service includes functions for creating, deleting and finding catalogue entries and a function for navigating through catalogue entries sequentially.
void sdr_catlg(Sdr sdr, char *name, int type, Object object)
Associates object with name in the indicated SDR's catalogue and notes the type that was declared for this object. type is optional and has no significance other than that conferred on it by the application.
The SDR catalogue is flat, not hierarchical like a directory tree, and all names must be unique. The length of name is limited to 15 characters.
Object sdr_find(Sdr sdr, char *name, int *type)
Locates the Object associated with name in the indicated SDR's catalogue and returns its address; also reports the catalogued type of the object in *type if type is non-NULL. Returns zero if no object is currently catalogued under this name.
void sdr_uncatlg(Sdr sdr, char *name)
Dissociates from name whatever object in the indicated SDR's catalogue is currently catalogued under that name.
Object sdr_read_catlg(Sdr sdr, char *name, int *type, Object *object, Object previous_entry)
Used to navigate through catalogue entries sequentially. If previous_entry is zero, reads the first entry in the indicated SDR's catalogue; otherwise, reads the next catalogue entry following the one located at previous_entry. In either case, returns zero if no such catalogue entry exists; otherwise, copies that entry's name, type, and catalogued object address into name, *type, and *object, and then returns the address of the catalogue entry (which may be used as previous_entry in a subsequent call to sdr_read_catlg()).
Compiling an SDR application
Just be sure to \"#include \"sdr.h\"\" at the top of each source file that includes any SDR function calls.
For UNIX applications, link with \"-lsdr\".
Loading an SDR application (VxWorks)
ld < \"libsdr.o\"\nAfter the library has been loaded, you can begin loading SDR applications.
sdrlist(3), sdrstring(3), sdrtable(3)
"},{"location":"man/ici/sdr2file/","title":"NAME","text":"sdr2file - SDR data extraction test program
"},{"location":"man/ici/sdr2file/#synopsis","title":"SYNOPSIS","text":"sdr2file configFlags
"},{"location":"man/ici/sdr2file/#description","title":"DESCRIPTION","text":"sdr2file stress-tests SDR data extraction by retrieving and deleting all text file lines inserted into a test SDR data store named \"testsdr_configFlags_\" by the complementary test program file2sdr(1).
The operation of sdr2file echoes the cyclical operation of file2sdr: each linked list created by file2sdr is used to create in the current working directory a copy of file2sdr's original source text file. The name of each file written by sdr2file is file_copy_cycleNbr, where cycleNbr identifies the linked list from which the file's text lines were obtained.
sdr2file may catch up with the data ingestion activity of file2sdr, in which case it blocks (taking the file2sdr test semaphore) until the linked list it is currently draining is no longer empty.
"},{"location":"man/ici/sdr2file/#exit-status","title":"EXIT STATUS","text":"\"0\"
sdr2file has terminated.
No configuration files are needed.
"},{"location":"man/ici/sdr2file/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/sdr2file/#diagnostics","title":"DIAGNOSTICS","text":"Can't use sdr.
ION system error. Check for diagnostics in the ION log file ion.log.
Can't create semaphore.
ION system error. Check for diagnostics in the ION log file ion.log.
SDR transaction failed.
ION system error. Check for diagnostics in the ION log file ion.log.
Can't open output file
Operating system error. Check errtext, correct problem, and rerun.
can't write to output file
Operating system error. Check errtext, correct problem, and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/sdr2file/#see-also","title":"SEE ALSO","text":"file2sdr(1), sdr(3)
"},{"location":"man/ici/sdrhash/","title":"NAME","text":"sdrhash - Simple Data Recorder hash table management functions
"},{"location":"man/ici/sdrhash/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\nObject sdr_hash_create (Sdr sdr, int keyLength,\n int estNbrOfEntries,\n int meanSearchLength);\nint sdr_hash_insert (Sdr sdr, Object hash, char *key,\n Address value, Object *entry);\nint sdr_hash_delete_entry (Sdr sdr, Object entry);\nint sdr_hash_entry_value (Sdr sdr, Object hash, Object entry);\nint sdr_hash_retrieve (Sdr sdr, Object hash, char *key,\n Address *value, Object *entry);\nint sdr_hash_count (Sdr sdr, Object hash);\nint sdr_hash_revise (Sdr sdr, Object hash, char *key,\n Address value);\nint sdr_hash_remove (Sdr sdr, Object hash, char *key,\n Address *value);\nint sdr_hash_destroy (Sdr sdr, Object hash);\nThe SDR hash functions manage hash table objects in an SDR.
Hash tables associate values with keys. A value is always in the form of an SDR Address, nominally the address of some stored object identified by the associated key, but the actual significance of a value may be anything that fits into a long. A key is always an array of from 1 to 255 bytes, which may have any semantics at all.
Keys must be unique; no two distinct entries in an SDR hash table may have the same key. Any attempt to insert a duplicate entry in an SDR hash table will be rejected.
All keys must be of the same length, and that length must be declared at the time the hash table is created. Invoking a hash table function with a key that is shorter than the declared length will have unpredictable results.
An SDR hash table is an array of linked lists. The location of a given value in the hash table is automatically determined by computing a \"hash\" of the key, dividing the hash by the number of linked lists in the array, using the remainder as an index to the corresponding linked list, and then sequentially searching through the list entries until the entry with the matching key is found.
The number of linked lists in the array is automatically computed at the time the hash table is created, based on the estimated maximum number of entries you expect to store in the table and the mean linked list length (i.e., mean search time) you prefer. Increasing the maximum number of entries in the table and decreasing the mean linked list length both tend to increase the amount of SDR heap space occupied by the hash table.
Object sdr_hash_create(Sdr sdr, int keyLength, int estNbrOfEntries, int meanSearchLength)
Creates an SDR hash table. Returns the SDR address of the new hash table on success, zero on any error.
int sdr_hash_insert(Sdr sdr, Object hash, char *key, Address value, Object *entry)
Inserts an entry into the hash table identified by hash. On success, places the address of the new hash table entry in entry and returns zero. Returns -1 on any error.
int sdr_hash_delete_entry(Sdr sdr, Object entry)
Deletes the hash table entry identified by entry. Returns zero on success, -1 on any error.
Address sdr_hash_entry_value(Sdr sdr, Object hash, Object entry)
Returns the value of the hash table entry identified by entry.
int sdr_hash_retrieve(Sdr sdr, Object hash, char *key, Address *value, Object *entry)
Searches for the value associated with key in this hash table, storing it in value if found. If the entry matching key was found, places the address of the hash table entry in entry and returns 1. Returns zero if no such entry exists, -1 on any other failure.
int sdr_hash_count(Sdr sdr, Object hash)
Returns the number of entries in the hash table identified by hash.
int sdr_hash_revise(Sdr sdr, Object hash, char *key, Address value)
Searches for the hash table entry matching key in this hash table, replacing the associated value with value if found. Returns 1 if the entry matching key was found, zero if no such entry exists, -1 on any other failure.
int sdr_hash_remove(Sdr sdr, Object hash, char *key, Address *value)
Searches for the hash table entry matching key in this hash table; if the entry is found, stores its value in value, deletes the entry, and returns 1. Returns zero if no such entry exists, -1 on any other failure.
void sdr_hash_destroy(Sdr sdr, Object hash);
Destroys hash, destroying all entries in all linked lists of the array and destroying the hash table array structure itself. DO NOT use sdr_free() to destroy a hash table, as this would leave the hash table's content allocated yet unreferenced.
sdr(3), sdrlist(3), sdrtable(3)
"},{"location":"man/ici/sdrlist/","title":"NAME","text":"sdrlist - Simple Data Recorder list management functions
"},{"location":"man/ici/sdrlist/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\ntypedef int (*SdrListCompareFn)(Sdr sdr, Address eltData, void *argData);\ntypedef void (*SdrListDeleteFn)(Sdr sdr, Object elt, void *argument);\n\n[see description for available functions]\nThe SDR list management functions manage doubly-linked lists in managed SDR heap space. The functions manage two kinds of objects: lists and list elements. A list knows how many elements it contains and what its start and end elements are. An element knows what list it belongs to and the elements before and after it in the list. An element also knows its content, which is normally the SDR Address of some object in the SDR heap. A list may be sorted, which speeds the process of searching for a particular element.
Object sdr_list_create(Sdr sdr)
Creates a new list object in the SDR; the new list object initially contains no list elements. Returns the address of the new list, or zero on any error.
void sdr_list_destroy(Sdr sdr, Object list, SdrListDeleteFn fn, void *arg)
Destroys a list, freeing all elements of list. If fn is non-NULL, that function is called once for each freed element; when called, fn is passed the Address that is the element's data and the argument pointer passed to sdr_list_destroy().
Do not use sdr_free to destroy an SDR list, as this would leave the elements of the list allocated yet unreferenced.
int sdr_list_length(Sdr sdr, Object list)
Returns the number of elements in the list, or -1 on any error.
void sdr_list_user_data_set(Sdr sdr, Object list, Address userData)
Sets the \"user data\" word of list to userData. Note that userData is nominally an Address but can in fact be any value that occupies a single word. It is typically used to point to an SDR object that somehow characterizes the list as a whole, such as a name.
Address sdr_list_user_data(Sdr sdr, Object list)
Returns the value of the \"user data\" word of list, or zero on any error.
Object sdr_list_insert(Sdr sdr, Object list, Address data, SdrListCompareFn fn, void *dataBuffer)
Creates a new list element whose data value is data and inserts that element into the list. If fn is NULL, the new list element is simply appended to the list; otherwise, the new list element is inserted after the last element in the list whose data value is \"less than or equal to\" the data value of the new element (in dataBuffer) according to the collating sequence established by fn. Returns the address of the newly created element, or zero on any error.
Object sdr_list_insert_first(Sdr sdr, Object list, Address data)
Object sdr_list_insert_last(Sdr sdr, Object list, Address data)
Creates a new element and inserts it at the front/end of the list. This function should not be used to insert a new element into any ordered list; use sdr_list_insert() instead. Returns the address of the newly created list element on success, or zero on any error.
Object sdr_list_insert_before(Sdr sdr, Object elt, Address data)
Object sdr_list_insert_after(Sdr sdr, Object elt, Address data)
Creates a new element and inserts it before/after the specified list element. This function should not be used to insert a new element into any ordered list; use sdr_list_insert() instead. Returns the address of the newly created list element, or zero on any error.
void sdr_list_delete(Sdr sdr, Object elt, SdrListDeleteFn fn, void *arg)
Delete elt from the list it is in. If fn is non-NULL, that function will be called upon deletion of elt; when called, that function is passed the Address that is the list element's data value and the arg pointer passed to sdr_list_delete().
Object sdr_list_first(Sdr sdr, Object list)
Object sdr_list_last(Sdr sdr, Object list)
Returns the address of the first/last element of list, or zero on any error.
Object sdr_list_next(Sdr sdr, Object elt)
Object sdr_list_prev(Sdr sdr, Object elt)
Returns the address of the element following/preceding elt in that element's list, or zero on any error.
Object sdr_list_search(Sdr sdr, Object elt, int reverse, SdrListCompareFn fn, void *dataBuffer);
Search a list for an element whose data matches the data in dataBuffer, starting at the indicated initial list element. If the compare function is non-NULL, the list is assumed to be sorted in the order implied by that function and the function is automatically called once for each element of the list until it returns a value that is greater than or equal to zero (where zero indicates an exact match and a value greater than zero indicates that the list contains no matching element); each time compare is called it is passed the Address that is the element's data value and the dataBuffer value passed to sm_list_search(). If reverse is non-zero, then the list is searched in reverse order (starting at the indicated initial list element) and the search ends when compare returns a value that is less than or equal to zero. If compare is NULL, then the entire list is searched (in either forward or reverse order, as directed) until an element is located whose data value is equal to ((Address) dataBuffer). Returns the address of the matching element if one is found, 0 otherwise.
Object sdr_list_list(Sdr sdr, Object elt)
Returns the address of the list to which elt belongs, or 0 on any error.
Address sdr_list_data(Sdr sdr, Object elt)
Returns the Address that is the data value of elt, or 0 on any error.
Address sdr_list_data_set(Sdr sdr, Object elt, Address data)
Sets the data value for elt to data, replacing the original value. Returns the original data value for elt, or 0 on any error. The original data value for elt may or may not have been the address of an object in heap data space; even if it was, that object was NOT deleted.
Warning: changing the data value of an element of an ordered list may ruin the ordering of the list.
When inserting elements or searching a list, the user may optionally provide a compare function of the form:
int user_comp_name(Sdr sdr, Address eltData, void *dataBuffer);\nWhen provided, this function is automatically called by the sdrlist function being invoked; when the function is called it is passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, dataBuffer, which is nominally the address in local memory of some other item in the same format. The user-supplied function normally compares some key values of the two data items and returns 0 if they are equal, an integer less than 0 if eltData's key value is less than that of dataBuffer, and an integer greater than 0 if eltData's key value is greater than that of dataBuffer. These return values will produce a list in ascending order. If the user desires the list to be in descending order, the function must reverse the signs of these return values.
When deleting an element or destroying a list, the user may optionally provide a delete function of the form:
void user_delete_name(Sdr sdr, Address eltData, void *argData)\nWhen provided, this function is automatically called by the sdrlist function being invoked; when the function is called it is passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, argData, which if non-NULL is normally the address in local memory of a data item providing context for the list element deletion. The user-supplied function performs any application-specific cleanup associated with deleting the element, such as freeing the element's content data item and/or other SDR heap space associated with the element.
"},{"location":"man/ici/sdrlist/#see-also","title":"SEE ALSO","text":"lyst(3), sdr(3), sdrstring(3), sdrtable(3), smlist(3)
"},{"location":"man/ici/sdrmend/","title":"NAME","text":"sdrmend - SDR corruption repair utility
"},{"location":"man/ici/sdrmend/#synopsis","title":"SYNOPSIS","text":"sdrmend sdr_name config_flags heap_words heap_key path_name [restartCmd restartLatency]
"},{"location":"man/ici/sdrmend/#description","title":"DESCRIPTION","text":"The sdrmend program simply invokes the sdr_reload_profile() function (see sdr(3)) to effect necessary repairs in a potentially corrupt SDR, e.g., due to the demise of a program that had an SDR transaction in progress at the moment it crashed.
Note that sdrmend need not be run to repair ION's data store in the event of a hardware reboot: restarting ION will automatically reload the data store's profile. sdrmend is needed only when it is desired to repair the data store without requiring all ION software to terminate and restart.
"},{"location":"man/ici/sdrmend/#exit-status","title":"EXIT STATUS","text":"\"0\"
sdrmend has terminated successfully.
\"1\"
sdrmend has terminated unsuccessfully. See diagnostic messages in the ion.log log file for details.
No configuration files are needed.
"},{"location":"man/ici/sdrmend/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/sdrmend/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't initialize the SDR system.
Probable operations error: ION appears not to be initialized, in which case there is no point in running sdrmend.
Can't reload profile for SDR.
ION system error. See earlier diagnostic messages posted to ion.log for details. In this event it is unlikely that sdrmend can be run successfully, and it is also unlikely that it would have any effect if it did run successfully.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/sdrmend/#see-also","title":"SEE ALSO","text":"ionunlock(1), sdr(3), ionadmin(1)
"},{"location":"man/ici/sdrstring/","title":"NAME","text":"sdrstring - Simple Data Recorder string functions
"},{"location":"man/ici/sdrstring/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\nObject sdr_string_create (Sdr sdr, char *from);\nObject sdr_string_dup (Sdr sdr, Object from);\nint sdr_string_length (Sdr sdr, Object string);\nint sdr_string_read (Sdr sdr, char *into, Object string);\nSDR strings are used to record strings of up to 255 ASCII characters in the heap space of an SDR. Unlike standard C strings, which are terminated by a zero byte, SDR strings record the length of the string as part of the string object.
To store strings longer than 255 characters, use sdr_malloc() and sdr_write() instead of these functions.
Object sdr_string_create(Sdr sdr, char *from)
Creates a \"self-delimited string\" in the heap of the indicated SDR, allocating the required space and copying the indicated content. from must be a standard C string for which strlen() must not exceed 255; if it does, or if insufficient SDR space is available, 0 is returned. Otherwise the address of the newly created SDR string object is returned. To destroy, just use sdr_free().
Object sdr_string_dup(Sdr sdr, Object from)
Creates a duplicate of the SDR string whose address is from, allocating the required space and copying the original string's content. If insufficient SDR space is available, 0 is returned. Otherwise the address of the newly created copy of the original SDR string object is returned. To destroy, use sdr_free().
int sdr_string_length(Sdr sdr, Object string)
Returns the length of the indicated self-delimited string (as would be returned by strlen()), or -1 on any error.
int sdr_string_read(Sdr sdr, char *into, Object string)
Retrieves the content of the indicated self-delimited string into memory as a standard C string (NULL terminated). Length of into should normally be SDRSTRING_BUFSZ (i.e., 256) to allow for the largest possible SDR string (255 characters) plus the terminating NULL. Returns length of string (as would be returned by strlen()), or -1 on any error.
sdr(3), sdrlist(3), sdrtable(3), string(3)
"},{"location":"man/ici/sdrtable/","title":"NAME","text":"sdrtable - Simple Data Recorder table management functions
"},{"location":"man/ici/sdrtable/#synopsis","title":"SYNOPSIS","text":"#include \"sdr.h\"\n\nObject sdr_table_create (Sdr sdr, int rowSize, int rowCount);\nint sdr_table_user_data_set (Sdr sdr, Object table, Address userData);\nAddress sdr_table_user_data (Sdr sdr, Object table);\nint sdr_table_dimensions (Sdr sdr, Object table, int *rowSize, \n int *rowCount);\nint sdr_table_stage (Sdr sdr, Object table);\nAddress sdr_table_row (Sdr sdr, Object table, \n unsigned int rowNbr);\nint sdr_table_destroy (Sdr sdr, Object table);\nThe SDR table functions manage table objects in the SDR. An SDR table comprises N rows of M bytes each, plus optionally one word of user data (which is nominally the address of some other object in the SDR's heap space). When a table is created, the number of rows in the table and the length of each row are specified; they remain fixed for the life of the table. The table functions merely maintain information about the table structure and its location in the SDR and calculate row addresses; other SDR functions such as sdr_read() and sdr_write() are used to read and write the contents of the table's rows. In particular, the format of the rows of a table is left entirely up to the user.
Object sdr_table_create(Sdr sdr, int rowSize, int rowCount)
Creates a \"self-delimited table\", comprising rowCount rows of rowSize bytes each, in the heap space of the indicated SDR. Note that the content of the table, a two-dimensional array, is a single SDR heap space object of size (rowCount x rowSize). Returns the address of the new table on success, zero on any error.
void sdr_table_user_data_set(Sdr sdr, Object table, Address userData)
Sets the \"user data\" word of table to userData. Note that userData is nominally an Address but can in fact be any value that occupies a single word. It is typically used to point to an SDR object that somehow characterizes the table as a whole, such as an SDR string containing a name.
Address sdr_table_user_data(Sdr sdr, Object table)
Returns the value of the \"user data\" word of table, or zero on any error.
void sdr_table_dimensions(Sdr sdr, Object table, int *rowSize, int *rowCount)
Reports on the row size and row count of the indicated table, as specified when the table was created.
void sdr_table_stage(Sdr sdr, Object table)
Stages table so that the array it encapsulates may be updated; see the discussion of sdr_stage() in sdr(3). The effect of this function is the same as:
sdr_stage(sdr, NULL, (Object) sdr_table_row(sdr, table, 0), 0)\nAddress sdr_table_row(Sdr sdr, Object table, unsigned int rowNbr)
Returns the address of the rowNbr_th row of _table, for use in reading or writing the content of this row; returns -1 on any error.
void sdr_table_destroy(Sdr sdr, Object table)
Destroys table, releasing all bytes of all rows and destroying the table structure itself. DO NOT use sdr_free() to destroy a table, as this would leave the table's content allocated yet unreferenced.
sdr(3), sdrlist(3), sdrstring(3)
"},{"location":"man/ici/sdrwatch/","title":"NAME","text":"sdrwatch - SDR non-volatile data store activity monitor
"},{"location":"man/ici/sdrwatch/#synopsis","title":"SYNOPSIS","text":"sdrwatch sdr_name [ -t | -s | -r | -z ] [interval [count [ verbose ]]]
"},{"location":"man/ici/sdrwatch/#description","title":"DESCRIPTION","text":"For count interations (defaulting to 1), sdrwatch sleeps interval seconds and then performs the SDR operation indicated by the specified mode: 's' to print statistics, 'r' to reset statistics, 'z' to print ZCO space utilization, 't' (the default) to call the sdr_print_trace() function (see sdr(3)) to report on SDR data storage management activity in the SDR data store identified by sdr_name during that interval. If the optional verbose parameter is specified, the printed SDR activity trace will be verbose as described in sdr(3).
If interval is zero, sdrwatch just performs the indicated operation once (for 't', it merely prints a current usage summary for the indicated data store) and terminates.
sdrwatch is helpful for detecting and diagnosing storage space leaks. For debugging the ION protocol stack, sdr_name is normally \"ion\" but might be overridden by the value of sdrName in the .ionconfig file used to configure the node under study.
"},{"location":"man/ici/sdrwatch/#exit-status","title":"EXIT STATUS","text":"\"0\"
sdrwatch has terminated.
No configuration files are needed.
"},{"location":"man/ici/sdrwatch/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/sdrwatch/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
Can't attach to sdr.
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 start trace.
Insufficient ION working memory to contain trace information. Reinitialize ION with more memory.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/sdrwatch/#see-also","title":"SEE ALSO","text":"sdr(3), psmwatch(1)
"},{"location":"man/ici/sm2file/","title":"NAME","text":"sm2file - shared-memory linked list data extraction test program
"},{"location":"man/ici/sm2file/#synopsis","title":"SYNOPSIS","text":"sm2file
"},{"location":"man/ici/sm2file/#description","title":"DESCRIPTION","text":"sm2file stress-tests shared-memory linked list data extraction by retrieving and deleting all text file lines inserted into a shared-memory linked list that is the root object of a PSM partition named \"file2sm\".
The operation of sm2file echoes the cyclical operation of file2sm: the EOF lines inserted into the linked list by file2sm punctuate the writing of files that are copies of file2sm's original source text file. The name of each file written by sm2file is file_copy_cycleNbr, where cycleNbr is, in effect, the count of EOF lines encountered in the linked list up to the point at which the writing of this file began.
sm2file may catch up with the data ingestion activity of file2sm, in which case it blocks (taking the file2sm test semaphore) until the linked list is no longer empty.
"},{"location":"man/ici/sm2file/#exit-status","title":"EXIT STATUS","text":"\"0\"
sm2file has terminated.
No configuration files are needed.
"},{"location":"man/ici/sm2file/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/sm2file/#diagnostics","title":"DIAGNOSTICS","text":"can't attach to shared memory
Operating system error. Check errtext, correct problem, and rerun.
Can't manage shared memory.
PSM error. Check for earlier diagnostics describing the cause of the error; correct problem and rerun.
Can't create shared memory list.
PSM error. Check for earlier diagnostics describing the cause of the error; correct problem and rerun.
Can't create semaphore.
ION system error. Check for earlier diagnostics describing the cause of the error; correct problem and rerun.
Can't open output file
Operating system error. Check errtext, correct problem, and rerun.
can't write to output file
Operating system error. Check errtext, correct problem, and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/sm2file/#see-also","title":"SEE ALSO","text":"file2sm(1), smlist(3), psm(3)
"},{"location":"man/ici/smlist/","title":"NAME","text":"smlist - shared memory list management library
"},{"location":"man/ici/smlist/#synopsis","title":"SYNOPSIS","text":"#include \"smlist.h\"\n\ntypedef int (*SmListCompareFn)\n (PsmPartition partition, PsmAddress eltData, void *argData);\ntypedef void (*SmListDeleteFn)\n (PsmPartition partition, PsmAddress elt, void *argument);\n\n[see description for available functions]\nThe smlist library provides functions to create, manipulate and destroy doubly-linked lists in shared memory. As with lyst(3), smlist uses two types of objects, list objects and element objects. However, as these objects are stored in shared memory which is managed by psm(3), pointers to these objects are carried as PsmAddress values. A list knows how many elements it contains and what its first and last elements are. An element knows what list it belongs to and the elements before and after it in its list. An element also knows its content, which is normally the PsmAddress of some object in shared memory.
PsmAddress sm_list_create(PsmPartition partition)
Create a new list object without any elements in it, within the memory segment identified by partition. Returns the PsmAddress of the list, or 0 on any error.
void sm_list_unwedge(PsmPartition partition, PsmAddress list, int interval)
Unwedge, as necessary, the mutex semaphore protecting shared access to the indicated list. For details, see the explanation of the sm_SemUnwedge() function in platform(3).
int sm_list_clear(PsmPartition partition, PsmAddress list, SmListDeleteFn delete, void *argument);
Empty a list. Frees each element of the list. If the delete function is non-NULL, that function is called once for each freed element; when called, that function is passed the PsmAddress of the list element and the argument pointer passed to sm_list_clear(). Returns 0 on success, -1 on any error.
int sm_list_destroy(PsmPartition partition, PsmAddress list, SmListDeleteFn delete, void *argument);
Destroy a list. Same as sm_list_clear(), but additionally frees the list structure itself. Returns 0 on success, -1 on any error.
int sm_list_user_data_set(PsmPartition partition, PsmAddress list, PsmAddress userData);
Set the value of a user data variable associated with the list as a whole. This value may be used for any purpose; it is typically used to store the PsmAddress of a shared memory block containing data (e.g., state data) which the user wishes to associate with the list. Returns 0 on success, -1 on any error.
PsmAddress sm_list_user_data(PsmPartition partition, PsmAddress list);
Return the value of the user data variable associated with the list as a whole, or 0 on any error.
int sm_list_length(PsmPartition partition, PsmAddress list);
Return the number of elements in the list.
PsmAddress sm_list_insert(PsmPartition partition, PsmAddress list, PsmAddress data, SmListCompareFn compare, void *dataBuffer);
Create a new list element whose data value is data and insert it into the given list. If the compare function is NULL, the new list element is simply appended to the list; otherwise, the new list element is inserted after the last element in the list whose data value is \"less than or equal to\" the data value of the new element (in dataBuffer) according to the collating sequence established by compare. Returns the PsmAddress of the new element, or 0 on any error.
PsmAddress sm_list_insert_first(PsmPartition partition, PsmAddress list, PsmAddress data);
PsmAddress sm_list_insert_last(PsmPartition partition, PsmAddress list, PsmAddress data);
Create a new list element and insert it at the start/end of a list. Returns the PsmAddress of the new element on success, or 0 on any error. Disregards any established sort order in the list.
PsmAddress sm_list_insert_before(PsmPartition partition, PsmAddress elt, PsmAddress data);
PsmAddress sm_list_insert_after(PsmPartition partition, PsmAddress elt, PsmAddress data);
Create a new list element and insert it before/after a given element. Returns the PsmAddress of the new element on success, or 0 on any error. Disregards any established sort order in the list.
int sm_list_delete(PsmPartition partition, PsmAddress elt, SmListDeleteFn delete, void *argument);
Delete an element from a list. If the delete function is non-NULL, that function is called upon deletion of elt; when called, that function is passed the PsmAddress of the list element and the argument pointer passed to sm_list_delete(). Returns 0 on success, -1 on any error.
PsmAddress sm_list_first(PsmPartition partition, PsmAddress list);
PsmAddress sm_list_last(PsmPartition partition, PsmAddress list);
Return the PsmAddress of the first/last element in list, or 0 on any error.
PsmAddress sm_list_next(PsmPartition partition, PsmAddress elt);
PsmAddress sm_list_prev(PsmPartition partition, PsmAddress elt);
Return the PsmAddress of the element following/preceding elt in that element's list, or 0 on any error.
PsmAddress sm_list_search(PsmPartition partition, PsmAddress elt, SmListCompareFn compare, void *dataBuffer);
Search a list for an element whose data matches the data in dataBuffer. If the compare function is non-NULL, the list is assumed to be sorted in the order implied by that function and the function is automatically called once for each element of the list until it returns a value that is greater than or equal to zero (where zero indicates an exact match and a value greater than zero indicates that the list contains no matching element); each time compare is called it is passed the PsmAddress that is the element's data value and the dataBuffer value passed to sm_list_search(). If compare is NULL, then the entire list is searched until an element is located whose data value is equal to ((PsmAddress) dataBuffer). Returns the PsmAddress of the matching element if one is found, 0 otherwise.
PsmAddress sm_list_list(PsmPartition partition, PsmAddress elt);
Return the PsmAddress of the list to which elt belongs, or 0 on any error.
PsmAddress sm_list_data(PsmPartition partition, PsmAddress elt);
Return the PsmAddress that is the data value for elt, or 0 on any error.
PsmAddress sm_list_data_set(PsmPartition partition, PsmAddress elt, PsmAddress data);
Set the data value for elt to data, replacing the original value. Returns the original data value for elt, or 0 on any error. The original data value for elt may or may not have been the address of an object in memory; even if it was, that object was NOT deleted.
Warning: changing the data value of an element of an ordered list may ruin the ordering of the list.
A user normally creates an element and adds it to a list by doing the following:
1
obtaining a shared memory block to contain the element's data;
2
converting the shared memory block's PsmAddress to a character pointer;
3
using that pointer to write the data into the shared memory block;
4
calling one of the sm_list_insert functions to create the element structure (which will include the shared memory block's PsmAddress) and insert it into the list.
When inserting elements or searching a list, the user may optionally provide a compare function of the form:
int user_comp_name(PsmPartition partition, PsmAddress eltData, \n void *dataBuffer);\nWhen provided, this function is automatically called by the smlist function being invoked; when the function is called it is passed the content of a list element (eltData, nominally the PsmAddress of an item in shared memory) and an argument, dataBuffer, which is nominally the address in local memory of some other item in the same format. The user-supplied function normally compares some key values of the two data items and returns 0 if they are equal, an integer less than 0 if eltData's key value is less than that of dataBuffer, and an integer greater than 0 if eltData's key value is greater than that of dataBuffer. These return values will produce a list in ascending order. If the user desires the list to be in descending order, the function must reverse the signs of these return values.
When deleting an element or destroying a list, the user may optionally provide a delete function of the form:
void user_delete_name(PsmPartition partition, PsmAddress elt, void *argData)\nWhen provided, this function is automatically called by the smlist function being invoked; when the function is called it is passed the address of a list element (elt and an argument, argData, which if non-NULL is normally the address in local memory of a data item providing context for the list element deletion. The user-supplied function performs any application-specific cleanup associated with deleting the element, such as freeing the element's content data item and/or other memory associated with the element.
"},{"location":"man/ici/smlist/#example","title":"EXAMPLE","text":"For an example of the use of smlist, see the file smlistsh.c in the utils directory of ICI.
"},{"location":"man/ici/smlist/#see-also","title":"SEE ALSO","text":"lyst(3), platform(3), psm(3)
"},{"location":"man/ici/smlistsh/","title":"NAME","text":"smlistsh - shared-memory linked list test shell
"},{"location":"man/ici/smlistsh/#synopsis","title":"SYNOPSIS","text":"smlistsh partition_size
"},{"location":"man/ici/smlistsh/#description","title":"DESCRIPTION","text":"smlistsh attaches to a region of system memory (allocating it if necessary, and placing it under PSM management as necessary) and offers the user an interactive \"shell\" for testing various shared-memory linked list management functions.
smlistsh prints a prompt string (\": \") to stdout, accepts a command from stdin, executes the command (possibly printing a diagnostic message), then prints another prompt string and so on.
The following commands are supported:
h
The help command. Causes smlistsh to print a summary of available commands. Same effect as the ? command.
?
Another help command. Causes smlistsh to print a summary of available commands. Same effect as the h command.
k
The key command. Computes and prints an unused shared-memory key, for possible use in attaching to a shared-memory region.
+ key_value size
The attach command. Attaches smlistsh to a region of shared memory. key_value identifies an existing shared-memory region, in the event that you want to attach to an existing shared-memory region (possibly created by another smlistsh process running on the same computer). To create and attach to a new shared-memory region that other processes can attach to, use a key_value as returned by the key command and supply the size of the new region. If you want to create and attach to a new shared-memory region that is for strictly private use, use -1 as key and supply the size of the new region.
-
The detach command. Detaches smlistsh from the region of shared memory it is currently using, but does not free any memory.
n
The new command. Creates a new shared-memory list to operate on, within the currently attached shared-memory region. Prints the address of the list.
s list_address
The share command. Selects an existing shared-memory list to operate on, within the currently attached shared-memory region.
a element_value
The append command. Appends a new list element, containing element_value, to the list on which smlistsh is currently operating.
p element_value
The prepend command. Prepends a new list element, containing element_value, to the list on which smlistsh is currently operating.
w
The walk command. Prints the addresses and contents of all elements of the list on which smlistsh is currently operating.
f element_value
The find command. Finds the list element that contains element_value, within the list on which smlistsh is currently operating, and prints the address of that list element.
d element_address
The delete command. Deletes the list element located at element_address.
r
The report command. Prints a partition usage report, as per psm_report(3).
q
The quit command. Detaches smlistsh from the region of shared memory it is currently using (without freeing any memory) and terminates smlistsh.
\"0\"
smlistsh has terminated.
No configuration files are needed.
"},{"location":"man/ici/smlistsh/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/smlistsh/#diagnostics","title":"DIAGNOSTICS","text":"No diagnostics apply.
"},{"location":"man/ici/smlistsh/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/smlistsh/#see-also","title":"SEE ALSO","text":"smlist(3)
"},{"location":"man/ici/smrbt/","title":"NAME","text":"smrbt - shared-memory red-black tree management library
"},{"location":"man/ici/smrbt/#synopsis","title":"SYNOPSIS","text":"#include \"smrbt.h\"\n\ntypedef int (*SmRbtCompareFn)\n (PsmPartition partition, PsmAddress nodeData, void *dataBuffer);\ntypedef void (*SmRbtDeleteFn)\n (PsmPartition partition, PsmAddress nodeData, void *argument);\n\n[see description for available functions]\nThe smrbt library provides functions to create, manipulate and destroy \"red-black\" balanced binary trees in shared memory. smrbt uses two types of objects, rbt objects and node objects; as these objects are stored in shared memory which is managed by psm(3), pointers to these objects are carried as PsmAddress values. An rbt knows how many nodes it contains and what its root node is. An node knows what rbt it belongs to and which nodes are its parent and (up to 2) children. A node also knows its content, which is normally the PsmAddress of some object in shared memory.
PsmAddress sm_rbt_create(PsmPartition partition)
Create a new rbt object without any nodes in it, within the memory segment identified by partition. Returns the PsmAddress of the rbt, or 0 on any error.
void sm_rbt_unwedge(PsmPartition partition, PsmAddress rbt, int interval)
Unwedge, as necessary, the mutex semaphore protecting shared access to the indicated rbt. For details, see the explanation of the sm_SemUnwedge() function in platform(3).
int sm_rbt_clear(PsmPartition partition, PsmAddress rbt, SmRbtDeleteFn delete, void *argument);
Frees every node of the rbt, leaving the rbt empty. If the delete function is non-NULL, that function is called once for each freed node; when called, that function is passed the PsmAddress that is the node's data and the argument pointer passed to sm_rbt_clear(). Returns 0 on success, -1 on any error.
void sm_rbt_destroy(PsmPartition partition, PsmAddress rbt, SmRbtDeleteFn delete, void *argument);
Destroy an rbt. Frees all nodes of the rbt as in sm_rbt_clear(), then frees the rbt structure itself.
int sm_rbt_user_data_set(PsmPartition partition, PsmAddress rbt, PsmAddress userData);
Set the value of a user data variable associated with the rbt as a whole. This value may be used for any purpose; it is typically used to store the PsmAddress of a shared memory block containing data (e.g., state data) which the user wishes to associate with the rbt. Returns 0 on success, -1 on any error.
PsmAddress sm_rbt_user_data(PsmPartition partition, PsmAddress rbt);
Return the value of the user data variable associated with the rbt as a whole, or 0 on any error.
int sm_rbt_length(PsmPartition partition, PsmAddress rbt);
Return the number of nodes in the rbt.
PsmAddress sm_rbt_insert(PsmPartition partition, PsmAddress rbt, PsmAddress data, SmRbtCompareFn compare, void *dataBuffer);
Create a new rbt node whose data value is data and insert it into rbt. The nodes of an rbt are ordered by their notional \"key\" values; for this purpose, no two nodes may have the same key value. The key value of a node is assumed to be some function of the content of dataBuffer, which is assumed to be a representation in memory of the data value indicated by data, and that function must be implicit in the compare function, which must not be NULL. The new rbt node is inserted into the rbt in a tree location that preserves order in the tree, according to the collating sequence established by compare, and also ensures that no path (from root to leaf) in the tree is more than twice as long as any other path. This makes searching the tree for a given data value quite rapid even if the number of nodes in the tree is very large. Returns the PsmAddress of the new node, or 0 on any error.
void sm_rbt_delete(PsmPartition partition, PsmAddress rbt, SmRbtCompareFn compare, void *dataBuffer, SmRbtDeleteFn delete, void *argument);
Delete a node from rbt. compare must be the same function that was used to insert the node: the tree must be dynamically re-balanced upon node deletion, and the compare function and the data value of the node that is to be deleted (as represented in memory in dataBuffer) are required for this purpose. (Since the function descends the tree in search of the matching node anyway, in order to preserve balance, the address of the node itself is not needed.)
If the delete function is non-NULL, that function is called upon deletion of the indicated node. When called, that function is passed the PsmAddress that is the node's data value and the argument pointer passed to sm_rbt_delete().
NOTE that this function does something highly devious to avoid extra tree-balancing complexity when node is deleted. For details, see the code, but the main point is that deleting a node WILL MOVE NODES WITHIN THE TREE. After the deletion, the next node may not be the one that would have been reported if you passed the to-be-deleted node to sm_rbt_next() before calling sm_rbt_delete(). This is important: do not apply updates (no insertions, and especially no deletions) while you are traversing a red-black tree sequentially. If you do, the result will not be what you expect.
PsmAddress sm_rbt_first(PsmPartition partition, PsmAddress rbt);
PsmAddress sm_rbt_last(PsmPartition partition, PsmAddress rbt);
Return the PsmAddress of the first/last node in rbt, or 0 on any error.
PsmAddress sm_rbt_next(PsmPartition partition, PsmAddress node);
PsmAddress sm_rbt_prev(PsmPartition partition, PsmAddress node);
Return the PsmAddress of the node following/preceding node in that node's rbt, or 0 on any error.
NOTE that the red-black tree node insertion and deletion functions WILL MOVE NODES WITHIN THE TREE. This is important: do not apply updates (no insertions, and especially no deletions) while you are traversing a red-black tree sequentially, using sm_rbt_next() or sm_rbt_prev(). If you do, the result will not be what you expect.
PsmAddress sm_rbt_search(PsmPartition partition, PsmAddress rbt, SmRbtCompareFn compare, void *dataBuffer, PsmAddress *successor);
Search rbt for a node whose data matches the data in dataBuffer. compare must be the same function that was used to insert all nodes into the tree. The tree is searched until a node is found whose data value is \"equal\" (according to compare) to the data value represented in memory in dataBuffer, or until it is known that there is no such node in the tree. If the matching node is found, the PsmAddress of that node is returned and *successor is set to zero. Otherwise, zero is returned and *successor is set to the PsmAddress of the first node in the tree whose key value is greater than the key value of dataBuffer, according to compare, or to zero if there is no such successor node.
PsmAddress sm_rbt_rbt(PsmPartition partition, PsmAddress node);
Return the PsmAddress of the rbt to which node belongs, or 0 on any error.
PsmAddress sm_rbt_data(PsmPartition partition, PsmAddress node);
Return the PsmAddress that is the data value for node, or 0 on any error.
A user normally creates an node and adds it to a rbt by doing the following:
1
obtaining a shared memory block to contain the node's data;
2
converting the shared memory block's PsmAddress to a character pointer;
3
using that pointer to write the data into the shared memory block;
4
calling the sm_rbt_insert function to create the node structure (which will include the shared memory block's PsmAddress) and insert it into the rbt.
When inserting or deleting nodes or searching a rbt, the user must provide a compare function of the form:
int user_comp_name(PsmPartition partition, PsmAddress node, \n void *dataBuffer);\nThis function is automatically called by the smrbt function being invoked; when the function is called it is passed the data content of an rbt node (node, nominally the PsmAddress of an item in shared memory) and an argument, dataBuffer, which is nominally the address in local memory of some other data item in the same format. The user-supplied function normally compares some key values of the two data items and returns 0 if they are equal, an integer less than 0 if node's key value is less than that of dataBuffer, and an integer greater than 0 if node's key value is greater than that of dataBuffer. These return values will produce an rbt in ascending order.
When deleting an node or destroying a rbt, the user may optionally provide a delete function of the form:
void user_delete_name(PsmPartition partition, PsmAddress node, \n void *argData)\nWhen provided, this function is automatically called by the smrbt function being invoked; when the function is called it is passed the content of a rbt node (node, nominally the PsmAddress of an item in shared memory) and an argument, argData, which if non-NULL is normally the address in local memory of a data item providing context for the rbt node deletion. The user-supplied function performs any application-specific cleanup associated with deleting the node, such as freeing the node's content data item and/or other memory associated with the node.
"},{"location":"man/ici/smrbt/#example","title":"EXAMPLE","text":"For an example of the use of smrbt, see the file smrbtsh.c in the utils directory of ICI.
"},{"location":"man/ici/smrbt/#see-also","title":"SEE ALSO","text":"smrbtsh(1), platform(3), psm(3)
"},{"location":"man/ici/smrbtsh/","title":"NAME","text":"smrbtsh - shared-memory red-black tree test shell
"},{"location":"man/ici/smrbtsh/#synopsis","title":"SYNOPSIS","text":"smrbtsh [command_file_name]
"},{"location":"man/ici/smrbtsh/#description","title":"DESCRIPTION","text":"smrbtsh allocates a region of shared system memory, attaches to that region, places it under PSM management, creates a temporary \"test\" red-black tree in that memory region, and executes a series of shared-memory red-black tree commands that exercise various tree access and management functions.
If command_file_name is provided, then the commands in the indicated file are executed and the program then terminates. Upon termination, the shared memory region allocated to smrbtsh is detached and destroyed.
Otherwise, smrbtsh offers the user an interactive \"shell\" for testing the smrbt functions in a conversational manner: smrbtsh prints a prompt string (\": \") to stdout, accepts a command from stdin, executes the command (possibly printing a diagnostic message), then prints another prompt string and so on. Upon execution of the 'q' command, the program terminates.
The following commands are supported:
h
The help command. Causes smrbtsh to print a summary of available commands. Same effect as the ? command.
?
Another help command. Causes smrbtsh to print a summary of available commands. Same effect as the h command.
s [seed_value]
The seed command. Seeds random data value generator, which is used to generate node values when the r command is used. If seed_value is omitted, uses current time (as returned by time(1)) as seed value.
r [count]
The random command. Inserts count new nodes into the red-black tree, using randomly selected unsigned long integers as the data values of the nodes; count defaults to 1 if omitted.
i data_value
The insert command. Inserts a single new node into the red-black tree, using data_value as the data value of the node.
f data_value
The find command. Finds the rbt node whose value is data_value, within the red-black tree, and prints the address of that node. If the node is not found, prints address zero and prints the address of the successor node in the tree.
d data_value
The delete command. Deletes the rbt node whose data value is data_value.
p
The print command. Prints the red-black tree, using indentation to indicate descent along paths of the tree.
Note: this function is supported only if the smrbt library was built with compilation flag -DSMRBT_DEBUG=1.
k
The check command. Examines the red-black tree, noting the first violation of red-black structure rules, if any.
Note: this function is supported only if the smrbt library was built with compilation flag -DSMRBT_DEBUG=1.
l
The list command. Lists all nodes in the red-black tree in traversal order, noting any nodes whose data values are not in ascending numerical order.
q
The quit command. Detaches smrbtsh from the region of shared memory it is currently using, destroys that shared memory region, and terminates smrbtsh.
\"0\"
smrbtsh has terminated.
No configuration files are needed.
"},{"location":"man/ici/smrbtsh/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ici/smrbtsh/#diagnostics","title":"DIAGNOSTICS","text":"No diagnostics apply.
"},{"location":"man/ici/smrbtsh/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ici/smrbtsh/#see-also","title":"SEE ALSO","text":"smrbt(3)
"},{"location":"man/ici/zco/","title":"NAME","text":"zco - library for manipulating zero-copy objects
"},{"location":"man/ici/zco/#synopsis","title":"SYNOPSIS","text":"#include \"zco.h\"\n\ntypedef enum\n{\n ZcoInbound = 0,\n ZcoOutbound = 1,\n ZcoUnknown = 2\n} ZcoAcct;\n\ntypedef enum\n{\n ZcoFileSource = 1,\n ZcoBulkSource = 2,\n ZcoObjSource = 3,\n ZcoSdrSource = 4,\n ZcoZcoSource = 5\n} ZcoMedium;\n\ntypedef void (*ZcoCallback)(ZcoAcct);\n\n[see description for available functions]\n\"Zero-copy objects\" (ZCOs) are abstract data access representations designed to minimize I/O in the encapsulation of application source data within one or more layers of communication protocol structure. ZCOs are constructed within the heap space of an SDR to which implementations of all layers of the stack must have access. Each ZCO contains information enabling access to the source data objects, together with (a) a linked list of zero or more \"extents\" that reference portions of these source data objects and (b) linked lists of protocol header and trailer capsules that have been explicitly attached to the ZCO since its creation. The concatenation of the headers (in ascending stack sequence), source data object extents, and trailers (in descending stack sequence) is what is to be transmitted or has been received.
Each source data object may be either a file (identified by pathname stored in a \"file reference\" object in SDR heap) or an item in mass storage (identified by item number, with implementation-specific semantics, stored in a \"bulk reference\" object in SDR heap) or an object in SDR heap space (identified by heap address stored in an \"object reference\" object in SDR heap) or an array of bytes in SDR heap space (identified by heap address). Each protocol header or trailer capsule indicates the length and the address (within SDR heap space) of a single protocol header or trailer at some layer of the stack. Note that the source data object for each ZCO extent is specified indirectly, by reference to a content lien reference structure that refers to a heap space object, mass storage item, or file; the reference structures contain the actual locations of the source data together with reference counts, enabling any number of \"clones\" of a given ZCO extent to be constructed without consuming additional resources. These reference counts ensure that the reference structures and the source data items they refer to are deleted automatically when (and only when) all ZCO extents that reference them have been deleted.
Note that the safety of shared access to a ZCO is protected by the fact that the ZCO resides in SDR heap space and therefore cannot be modified other than in the course of an SDR transaction, which serializes access. Moreover, extraction of data from a ZCO may entail the reading of file-based source data extents, which may cause file progress to be updated in one or more file reference objects in the SDR heap. For this reason, all ZCO \"transmit\" and \"receive\" functions must be performed within SDR transactions.
Note also that ZCO can more broadly be used as a general-purpose reference counting system for non-volatile data objects, where a need for such a system is identified.
The total volume of file system space, mass storage space, and SDR heap space that may be occupied by inbound and (separately) outbound ZCO extents are system configuration parameters that may be set by ZCO library functions. Those limits are enforced when extents are appended to ZCOs: total inbound and outbound ZCO file space, mass storage, and SDR heap occupancy are updated continuously as ZCOs are created and destroyed, and the formation of a new extent is prohibited when the length of the extent exceeds the difference between the applicable limit and the corresponding current occupancy total. Doing separate accounting for inbound and outbound ZCOs enables inbound ZCOs to be formed (for data reception purposes) even when the total current volume of outbound ZCOs has reached its limit, and vice versa.
void zco_register_callback(ZcoCallback notify)
This function registers the \"callback\" function that the ZCO system will invoke every time a ZCO is destroyed, making ZCO file, bulk, and/or heap space available for the formation of new ZCO extents. This mechanism can be used, for example, to notify tasks that are waiting for ZCO space to be made available so that they can resume some communication protocol procedure.
void zco_unregister_callback( )
This function simply unregisters the currently registered callback function for ZCO destruction.
Object zco_create_file_ref(Sdr sdr, char *pathName, char *cleanupScript, ZcoAcct acct)
Creates and returns a new file reference object, which can be used as the source data extent location for creating a ZCO whose source data object is the file identified by pathName. cleanupScript, if not NULL, is invoked at the moment the last ZCO that cites this file reference is destroyed [normally upon delivery either down to the \"ZCO transition layer\" of the protocol stack or up to a ZCO-capable application]. A zero-length string is interpreted as implicit direction to delete the referenced file when the file reference object is destroyed. Maximum length of cleanupScript is 255. acct must be ZcoInbound or ZcoOutbound, depending on whether the first ZCO that will reference this object will be inbound or outbound. Returns SDR location of file reference object on success, 0 on any error.
Object zco_revise_file_ref(Sdr sdr, Object fileRef, char *pathName, char *cleanupScript)
Changes the pathName and cleanupScript of the indicated file reference. The new values of these fields are validated as for zco_create_file_ref(). Returns 0 on success, -1 on any error.
char *zco_file_ref_path(Sdr sdr, Object fileRef, char *buffer, int buflen)
Retrieves the pathName associated with fileRef and stores it in buffer, truncating it to fit (as indicated by buflen) and NULL-terminating it. On success, returns buffer; returns NULL on any error.
int zco_file_ref_xmit_eof(Sdr sdr, Object fileRef)
Returns 1 if the last octet of the referenced file (as determined at the time the file reference object was created) has been read by ZCO via a reader with file offset tracking turned on. Otherwise returns zero.
void zco_destroy_file_ref(Sdr sdr, Object fileRef)
If the file reference object residing at location fileRef within the indicated Sdr is no longer in use (no longer referenced by any ZCO), destroys this file reference object immediately. Otherwise, flags this file reference object for destruction as soon as the last reference to it is removed.
Object zco_create_bulk_ref(Sdr sdr, unsigned long item, vast length, ZcoAcct acct)
Creates and returns a new bulk reference object, which can be used as the source data extent location for creating a ZCO whose source data object is the mass storage item of length length identified by item (the semantics of which are implementation-dependent). Note that the referenced item is automatically destroyed at the time that the last ZCO that cites this bulk reference is destroyed (normally upon delivery either down to the \"ZCO transition layer\" of the protocol stack or up to a ZCO-capable application). acct must be ZcoInbound or ZcoOutbound, depending on whether the first ZCO that will reference this object will be inbound or outbound. Returns SDR location of bulk reference object on success, 0 on any error.
void zco_destroy_bulk_ref(Sdr sdr, Object bulkRef)
If the bulk reference object residing at location bulkRef within the indicated Sdr is no longer in use (no longer referenced by any ZCO), destroys this bulk reference object immediately. Otherwise, flags this bulk reference object for destruction as soon as the last reference to it is removed.
Object zco_create_obj_ref(Sdr sdr, Object object, vast length, ZcoAcct acct)
Creates and returns a new object reference object, which can be used as the source data extent location for creating a ZCO whose source data object is the SDR heap object of length length identified by object. Note that the referenced object is automatically freed at the time that the last ZCO that cites this object reference is destroyed (normally upon delivery either down to the \"ZCO transition layer\" of the protocol stack or up to a ZCO-capable application). acct must be ZcoInbound or ZcoOutbound, depending on whether the first ZCO that will reference this object will be inbound or outbound. Returns SDR location of object reference object on success, 0 on any error.
void zco_destroy_obj_ref(Sdr sdr, Object objRef)
If the object reference object residing at location objRef within the indicated Sdr is no longer in use (no longer referenced by any ZCO), destroys this object reference object immediately. Otherwise, flags this object reference object for destruction as soon as the last reference to it is removed.
void zco_status(Sdr sdr)
Uses the ION logging function to write a report of the current contents of the ZCO space accounting database.
vast zco_get_file_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of file system space bytes occupied by ZCOs (inbound or outbound) created in this Sdr.
void zco_set_max_file_occupancy(Sdr sdr, vast occupancy, ZcoAcct acct)
Declares the total number of file system space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
vast zco_get_max_file_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of file system space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
int zco_enough_file_space(Sdr sdr, vast length, ZcoAcct acct)
Returns 1 if the total remaining file system space available for ZCOs (inbound or outbound) in this Sdr is greater than length. Returns 0 otherwise.
vast zco_get_bulk_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of mass storage space bytes occupied by ZCOs (inbound or outbound) created in this Sdr.
void zco_set_max_bulk_occupancy(Sdr sdr, vast occupancy, ZcoAcct acct)
Declares the total number of mass storage space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
vast zco_get_max_bulk_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of mass storage space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
int zco_enough_bulk_space(Sdr sdr, vast length, ZcoAcct acct)
Returns 1 if the total remaining mass storage space available for ZCOs (inbound or outbound) in this Sdr is greater than length. Returns 0 otherwise.
vast zco_get_heap_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of SDR heap space bytes occupied by ZCOs (inbound or outbound) created in this Sdr.
void zco_set_max_heap_occupancy(Sdr sdr, vast occupancy, ZcoAcct acct)
Declares the total number of SDR heap space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
vast zco_get_max_heap_occupancy(Sdr sdr, ZcoAcct acct)
Returns the total number of SDR heap space bytes that may be occupied by ZCOs (inbound or outbound) created in this Sdr.
int zco_enough_heap_space(Sdr sdr, vast length, ZcoAcct acct)
Returns 1 if the total remaining SDR heap space available for ZCOs (inbound or outbound) in this Sdr is greater than length. Returns 0 otherwise.
int zco_extent_too_large(Sdr sdr, ZcoMedium source, vast length, ZcoAcct acct)
Returns 1 if the total remaining space available for ZCOs (inbound or outbound) is NOT enough to contain a new extent of the indicated length in the indicated source medium. Returns 0 otherwise.
int zco_get_aggregate_length(Sdr sdr, Object location, vast offset, vast length, vast *fileSpaceOccupied, vast *bulkSpaceOccupied, vast *heapSpaceOccupied)
Populates *fileSpaceOccupied, *bulkSpaceOccupied, and *heapSpaceOccupied with the total number of ZCO space bytes occupied by the extents of the zco at location, from offset to offset + length. If offset isn't the start of an extent or offset + length isn't the end of an extent, returns -1 in all three fields.
Object zco_create(Sdr sdr, ZcoMedium firstExtentSourceMedium, Object firstExtentLocation, vast firstExtentOffset, vast firstExtentLength, ZcoAcct acct)
Creates a new inbound or outbound ZCO. firstExtentLocation and firstExtentLength must either both be zero (indicating that zco_append_extent() will be used to insert the first source data extent later) or else both be non-zero. If firstExtentLocation is non-zero, then (a) firstExtentLocation must be the SDR location of a file reference object, bulk reference object, object reference object, SDR heap object, or ZCO, depending on the value of firstExtentSourceMedium, and (b) firstExtentOffset indicates how many leading bytes of the source data object should be skipped over when adding the initial source data extent to the new ZCO. A negative value for firstExtentLength indicates that the extent is already known not to be too large for the available ZCO space, and the actual length of the extent is the additive inverse of this value. On success, returns the SDR location of the new ZCO. Returns 0 if there is insufficient ZCO space for creation of the new ZCO; returns ((Object) -1) on any error.
int zco_append_extent(Sdr sdr, Object zco, ZcoMedium sourceMedium, Object location, vast offset, vast length)
Appends the indicated source data extent to the indicated ZCO, as described for zco_create(). Both the location and length of the source data must be non-zero. A negative value for length indicates that the extent is already known not to be too large for the available ZCO space, and the actual length of the extent is the additive inverse of this value. For constraints on the value of location, see zco_create(). Returns length on success, 0 if there is insufficient ZCO space for creation of the new source data extent, -1 on any error.
int zco_prepend_header(Sdr sdr, Object zco, char *header, vast length)
void zco_discard_last_trailer(Sdr sdr, Object zco)
These functions attach and remove the ZCO's headers and trailers. header and trailer are assumed to be arrays of octets, not necessarily text. Attaching a header or trailer causes it to be written to the SDR. The prepend and append functions return 0 on success, -1 on any error.
Object zco_header_text(Sdr sdr, Object zco, int skip, vast *length)
Skips over the first skip headers of zco and returns the address of the text of the next header, placing the length of the header's text in *length. Returns 0 on any error.
Object zco_trailer_text(Sdr sdr, Object zco, int skip, vast *length)
Skips over the first skip trailers of zco and returns the address of the text of the next trailer, placing the length of the trailer's text in *length. Returns 0 on any error.
void zco_destroy(Sdr sdr, Object zco)
Destroys the indicated Zco. This reduces the reference counts for all files and SDR objects referenced in the ZCO's extents, resulting in the freeing of SDR objects and (optionally) the deletion of files as those reference count drop to zero.
void zco_bond(Sdr sdr, Object zco)
Converts all headers and trailers of the indicated Zco to source data extents. Use this function to ensure that known header and trailer data are included when the ZCO is cloned.
int zco_revise(Sdr sdr, Object zco, vast offset, char *buffer, vast length)
Writes the contents of buffer, for length length, into zco at offset offset. Returns 0 on success, -1 on any error.
Object zco_clone(Sdr sdr, Object zco, vast offset, vast length)
Creates a new ZCO whose source data is a copy of a subset of the source data of the referenced ZCO. This procedure is required whenever it is necessary to process the ZCO's source data in multiple different ways, for different purposes, and therefore the ZCO must be in multiple states at the same time. Portions of the source data extents of the original ZCO are copied as necessary, but no header or trailer capsules are copied. Returns SDR location of the new ZCO on success, (Object) -1 on any error.
vast zco_clone_source_data(Sdr sdr, Object toZco, Object fromZco, vast offset, vast length)
Appends to toZco a copy of a subset of the source data of fromZCO. Portions of the source data extents of fromZCO are copied as necessary. Returns total data length cloned, or -1 on any error.
vast zco_length(Sdr sdr, Object zco)
Returns length of entire ZCO, including all headers and trailers and all source data extents. This is the size of the object that would be formed by concatenating the text of all headers, trailers, and source data extents into a single serialized object.
vast zco_source_data_length(Sdr sdr, Object zco)
Returns length of entire ZCO minus the lengths of all attached header and trailer capsules. This is the size of the object that would be formed by concatenating the text of all source data extents (including those that are presumed to contain header or trailer text attached elsewhere) into a single serialized object.
ZcoAcct zco_acct(Sdr sdr, Object zco)
Returns an indicator as to whether zco is inbound or outbound.
void zco_start_transmitting(Object zco, ZcoReader *reader)
Used by underlying protocol layer to start extraction of an outbound ZCO's bytes (both from header and trailer capsules and from source data extents) for \"transmission\" -- i.e., the copying of bytes into a memory buffer for delivery to some non-ZCO-aware protocol implementation. Initializes reading at the first byte of the total concatenated ZCO object. Populates reader, which is used to keep track of \"transmission\" progress via this ZCO reference.
Note that this function can be called multiple times to restart reading at the start of the ZCO. Note also that multiple ZcoReader objects may be used concurrently, by the same task or different tasks, to advance through the ZCO independently.
void zco_track_file_offset(ZcoReader *reader)
Turns on file offset tracking for this reader.
vast zco_transmit(Sdr sdr, ZcoReader *reader, vast length, char *buffer)
Copies length as-yet-uncopied bytes of the total concatenated ZCO (referenced by reader) into buffer. If buffer is NULL, skips over length bytes without copying. Returns the number of bytes copied (or skipped) on success, 0 on any file access error, -1 on any other error.
void zco_start_receiving(Object zco, ZcoReader *reader)
Used by overlying protocol layer to start extraction of an inbound ZCO's bytes for \"reception\" -- i.e., the copying of bytes into a memory buffer for delivery to a protocol header parser, to a protocol trailer parser, or to the ultimate recipient (application). Initializes reading of headers, source data, and trailers at the first byte of the concatenated ZCO objects. Populates reader, which is used to keep track of \"reception\" progress via this ZCO reference and is required.
vast zco_receive_headers(Sdr sdr, ZcoReader *reader, vast length, char *buffer)
Copies length as-yet-uncopied bytes of presumptive protocol header text from ZCO source data extents into buffer. If buffer is NULL, skips over length bytes without copying. Returns number of bytes copied (or skipped) on success, 0 on any file access error, -1 on any other error.
void zco_delimit_source(Sdr sdr, Object zco, vast offset, vast length)
Sets the computed offset and length of actual source data in the ZCO, thereby implicitly establishing the total length of the ZCO's concatenated protocol headers as offset and the location of the ZCO's innermost protocol trailer as the sum of offset and length. Offset and length are typically determined from the information carried in received presumptive protocol header text.
vast zco_receive_source(Sdr sdr, ZcoReader *reader, vast length, char *buffer)
Copies length as-yet-uncopied bytes of source data from ZCO extents into buffer. If buffer is NULL, skips over length bytes without copying. Returns number of bytes copied (or skipped) on success, 0 on any file access error, -1 on any other error.
vast zco_receive_trailers(Sdr sdr, ZcoReader *reader, vast length, char *buffer)
Copies length as-yet-uncopied bytes of trailer data from ZCO extents into buffer. If buffer is NULL, skips over length bytes without copying. Returns number of bytes copied (or skipped) on success, 0 on any file access error, -1 on any other error.
void zco_strip(Sdr sdr, Object zco)
Deletes all source data extents that contain only header or trailer data and adjusts the offsets and/or lengths of all remaining extents to exclude any known header or trailer data. This function is useful when handling a ZCO that was received from an underlying protocol layer rather than from an overlying application or protocol layer; use it before starting the transmission of the ZCO to another node or before enqueuing it for reception by an overlying application or protocol layer.
sdr(3)
"},{"location":"man/ltp/","title":"Index of Man Pages","text":"dccplsi - DCCP-based LTP link service input task
"},{"location":"man/ltp/dccplsi/#synopsis","title":"SYNOPSIS","text":"dccplsi {local_hostname | @}[:local_port_nbr]
"},{"location":"man/ltp/dccplsi/#description","title":"DESCRIPTION","text":"dccplsi is a background \"daemon\" task that receives DCCP datagrams via a DCCP socket bound to local_hostname and local_port_nbr, extracts LTP segments from those datagrams, and passes them to the local LTP engine. Host name \"@\" signifies that the host name returned by hostname(1) is to be used as the socket's host name. If not specified, port number defaults to 1113.
The link service input task is spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The link service input task is terminated by ltpadmin in response to an 'x' (STOP) command.
"},{"location":"man/ltp/dccplsi/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccplsi terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart dccplsi.
\"1\"
dccplsi terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart dccplsi.
No configuration files are needed.
"},{"location":"man/ltp/dccplsi/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/dccplsi/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccplsi can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
LSI task is already started.
Redundant initiation of dccplsi.
LSI can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccplsi.
LSI can't initialize socket.
Operating system error. Check errtext, correct problem, and restart dccplsi.
LSI can't create listener thread.
Operating system error. Check errtext, correct problem, and restart dccplsi.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/dccplsi/#see-also","title":"SEE ALSO","text":"ltpadmin(1), dccplso(1), owltsim(1)
"},{"location":"man/ltp/dccplso/","title":"NAME","text":"dccplso - DCCP-based LTP link service output task
"},{"location":"man/ltp/dccplso/#synopsis","title":"SYNOPSIS","text":"dccplso {remote_engine_hostname | @}[:remote_port_nbr] remote_engine_nbr
"},{"location":"man/ltp/dccplso/#description","title":"DESCRIPTION","text":"dccplso is a background \"daemon\" task that extracts LTP segments from the queue of segments bound for the indicated remote LTP engine, encapsulates them in DCCP datagrams, and sends those datagrams to the indicated DCCP port on the indicated host. If not specified, port number defaults to 1113.
Each \"span\" of LTP data interchange between the local LTP engine and a neighboring LTP engine requires its own link service output task, such as dccplso. All link service output tasks are spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol, and they are all terminated by ltpadmin in response to an 'x' (STOP) command.
"},{"location":"man/ltp/dccplso/#exit-status","title":"EXIT STATUS","text":"\"0\"
dccplso terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart dccplso.
\"1\"
dccplso terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart dccplso.
No configuration files are needed.
"},{"location":"man/ltp/dccplso/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/dccplso/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
dccplso can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the LTP database by ltpadmin.
LSO task is already started for this engine.
Redundant initiation of dccplso.
LSO can't create idle thread.
Operating system error. Check errtext, correct problem, and restart dccplso.
LSO can't open DCCP socket. This probably means DCCP is not supported on your system.
Operating system error. This probably means that you are not using an operating system that supports DCCP. Make sure that you are using a current Linux kernel and that the DCCP modules are being compiled. Check errtext, correct problem, and restart dccplso.
LSO can't connect DCCP socket.
Remote host's dccplsi isn't listening or has terminated. Restart dccplsi on the remote host and then restart dccplso.
Segment is too big for DCCP LSO.
Configuration error: segments that are too large for DCCP transmission (i.e., larger than 65535 bytes) are being enqueued for dccplso. Use ltpadmin to change maximum segment size for this span.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/dccplso/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpmeter(1), dccplsi(1), owltsim(1)
"},{"location":"man/ltp/ltp/","title":"NAME","text":"ltp - Licklider Transmission Protocol (LTP) communications library
"},{"location":"man/ltp/ltp/#synopsis","title":"SYNOPSIS","text":"#include \"ltp.h\"\n\ntypedef enum\n{\n LtpNoNotice = 0,\n LtpExportSessionStart,\n LtpXmitComplete,\n LtpExportSessionCanceled,\n LtpExportSessionComplete,\n LtpRecvGreenSegment,\n LtpRecvRedPart,\n LtpImportSessionCanceled\n} LtpNoticeType;\n\n[see description for available functions]\nThe ltp library provides functions enabling application software to use LTP to send and receive information reliably over a long-latency link. It conforms to the LTP specification as documented by the Delay-Tolerant Networking Research Group of the Internet Research Task Force.
The LTP notion of engine ID corresponds closely to the Internet notion of a host, and in ION engine IDs are normally indistinguishable from node numbers including the node numbers in Bundle Protocol endpoint IDs conforming to the \"ipn\" scheme.
The LTP notion of client ID corresponds closely to the Internet notion of \"protocol number\" as used in the Internet Protocol. It enables data from multiple applications -- clients -- to be multiplexed over a single reliable link. However, for ION operations we normally use LTP exclusively for the transmission of Bundle Protocol data, identified by client ID = 1.
int ltp_attach()
Attaches the application to LTP functionality on the lcoal computer. Returns 0 on success, -1 on any error.
void ltp_detach()
Terminates all access to LTP functionality on the local computer.
int ltp_engine_is_started()
Returns 1 if the local LTP engine has been started and not yet stopped, 0 otherwise.
int ltp_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData, unsigned int redLength, LtpSessionId *sessionId)
Sends a client service data unit to the application that is waiting for data tagged with the indicated clientId as received at the remote LTP engine identified by destinationEngineId.
clientServiceData must be a \"zero-copy object\" reference as returned by ionCreateZco(). Note that LTP will privately make and destroy its own reference to the client service data object; the application is free to destroy its reference at any time.
redLength indicates the number of leading bytes of data in clientServiceData that are to be sent reliably, i.e., with selective retransmission in response to explicit or implicit negative acknowledgment as necessary. All remaining bytes of data in clientServiceData will be sent as \"green\" data, i.e., unreliably. If redLength is zero, the entire client service data unit will be sent unreliably. If the entire client service data unit is to be sent reliably, redLength may be simply be set to LTP_ALL_RED (i.e., -1).
On success, the function populates *sessionId with the source engine ID and the \"session number\" assigned to transmission of this client service data unit and returns zero. The session number may be used to link future LTP processing events, such as transmission cancellation, to the affected client service data. ltp_send() returns -1 on any error.
int ltp_open(unsigned int clientId)
Establishes the application's exclusive access to received service data units tagged with the indicated client service data ID. At any time, only a single application task is permitted to receive service data units for any single client service data ID.
Returns 0 on success, -1 on any error (e.g., the indicated client service is already being held open by some other application task).
int ltp_get_notice(unsigned int clientId, LtpNoticeType *type, LtpSessionId *sessionId, unsigned char *reasonCode, unsigned char *endOfBlock, unsigned int *dataOffset, unsigned int *dataLength, Object *data)
Receives notices of LTP processing events pertaining to the flow of service data units tagged with the indicated client service ID. The nature of each event is indicated by *type. Additional parameters characterizing the event are returned in *sessionId, *reasonCode, *endOfBlock, *dataOffset, *dataLength, and *data as relevant.
The value returned in *data is always a zero-copy object; use the zco_* functions defined in \"zco.h\" to retrieve the content of that object.
When the notice is an LtpRecvGreenSegment, the ZCO returned in *data contains the content of a single LTP green segment. Reassembly of the green part of some block from these segments is the responsibility of the application.
When the notice is an LtpRecvRedPart, the ZCO returned in *data contains the red part of a possibly aggregated block. The ZCO's content may therefore comprise multiple service data objects. Extraction of individual service data objects from the aggregated block is the responsibility of the application. A simple way to do this is to prepend the length of the service data object to the object itself (using zco_prepend_header) before calling ltp_send, so that the receiving application can alternate extraction of object lengths and objects from the delivered block's red part.
The cancellation of an export session may result in delivery of multiple LtpExportSessionCanceled notices, one for each service data unit in the export session's (potentially) aggregated block. The ZCO returned in *data for each such notice is a service data unit ZCO that had previously been passed to ltp_send().
ltp_get_notice() always blocks indefinitely until an LTP processing event is delivered.
Returns zero on success, -1 on any error.
void ltp_interrupt(unsigned int clientId)
Interrupts an ltp_get_notice() invocation. This function is designed to be called from a signal handler; for this purpose, clientId may need to be obtained from a static variable.
void ltp_release_data(Object data)
Releases the resources allocated to hold data, which must be a received client service data ZCO.
void ltp_close(unsigned int clientId)
Terminates the application's exclusive access to received service data units tagged with the indicated client service data ID.
ltpadmin(1), ltprc(5), zco(3)
"},{"location":"man/ltp/ltpadmin/","title":"NAME","text":"ltpadmin - ION Licklider Transmission Protocol (LTP) administration interface
"},{"location":"man/ltp/ltpadmin/#synopsis","title":"SYNOPSIS","text":"ltpadmin [ commands_filename | . | ! ]
"},{"location":"man/ltp/ltpadmin/#description","title":"DESCRIPTION","text":"ltpadmin configures, starts, manages, and stops LTP operations for the local ION node.
It operates in response to LTP configuration commands found in the file commands_filename, if provided; if not, ltpadmin prints a simple prompt (:) so that the user may type commands directly into standard input. If commands_filename is a period (.), the effect is the same as if a command file containing the single command 'x' were passed to ltpadmin -- that is, the ION node's ltpclock task, ltpmeter tasks, and link service adapter tasks are stopped. If commands_filename is an exclamation point (!), that effect is reversed: the ION node's ltpclock task, ltpmeter tasks, and link service adapter tasks are restarted.
The format of commands for commands_filename can be queried from ltpadmin with the 'h' or '?' commands at the prompt. The commands are documented in ltprc(5).
"},{"location":"man/ltp/ltpadmin/#exit-status","title":"EXIT STATUS","text":"ltpadmin
Enter interactive LTP configuration command entry mode.
ltpadmin host1.ltp
Execute all configuration commands in host1.ltp, then terminate immediately.
ltpadmin .
Stop all LTP operations on the local node.
See ltprc(5) for details of the LTP configuration commands.
"},{"location":"man/ltp/ltpadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ltprc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ltpadmin. Otherwise ltpadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the logfile ion.log:
ltpadmin can't attach to ION.
There is no SDR data store for ltpadmin to use. You should run ionadmin(1) first, to set up an SDR data store for ION.
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ltpadmin to fail but are noted in the ion.log log file may be caused by improperly formatted commands given at the prompt or in the commands_filename file. Please see ltprc(5) for details.
"},{"location":"man/ltp/ltpadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpadmin/#see-also","title":"SEE ALSO","text":"ltpmeter(1), ltprc(5)
"},{"location":"man/ltp/ltpclock/","title":"NAME","text":"ltpclock - LTP daemon task for managing scheduled events
"},{"location":"man/ltp/ltpclock/#synopsis","title":"SYNOPSIS","text":"ltpclock
"},{"location":"man/ltp/ltpclock/#description","title":"DESCRIPTION","text":"ltpclock is a background \"daemon\" task that periodically performs scheduled LTP activities. It is spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol, and it is terminated by ltpadmin in response to an 'x' (STOP) command.
Once per second, ltpclock takes the following action:
First it manages the current state of all links (\"spans\"). In particular, it checks the age of the currently buffered session block for each span and, if that age exceeds the span's configured aggregation time limit, gives the \"buffer full\" semaphore for that span to initiate block segmentation and transmission by ltpmeter.
In so doing, it also infers link state changes (\"link cues\") from data rate changes as noted in the RFX database by rfxclock:
If the rate of transmission to a neighbor was zero but is now non-zero, then transmission to that neighbor is unblocked. The applicable \"buffer empty\" semaphore is given if no outbound block is being constructed (enabling start of a new transmission session) and the \"segments ready\" semaphore is given if the outbound segment queue is non-empty (enabling transmission of segments by the link service output task).
If the rate of transmission to a neighbor was non-zero but is now zero, then transmission to that neighbor is blocked -- i.e., the semaphores triggering transmission will no longer be given.
If the imputed rate of transmission from a neighbor was non-zero but is now zero, then all timers affecting segment retransmission to that neighbor are suspended. This has the effect of extending the interval of each affected timer by the length of time that the timers remain suspended.
If the imputed rate of transmission from a neighbor was zero but is now non-zero, then all timers affecting segment retransmission to that neighbor are resumed.
Then ltpclock retransmits all unacknowledged checkpoint segments, report segments, and cancellation segments whose computed timeout intervals have expired.
"},{"location":"man/ltp/ltpclock/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpclock terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart ltpclock.
\"1\"
ltpclock was unable to attach to LTP protocol operations, probably because ltpadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/ltp/ltpclock/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpclock/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpclock can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
Can't dispatch events.
An unrecoverable database error was encountered. ltpclock terminates.
Can't manage links.
An unrecoverable database error was encountered. ltpclock terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpclock/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpmeter(1), rfxclock(1)
"},{"location":"man/ltp/ltpcounter/","title":"NAME","text":"ltpcounter - LTP reception test program
"},{"location":"man/ltp/ltpcounter/#synopsis","title":"SYNOPSIS","text":"ltpcounter client_ID [max_nbr_of_bytes]
"},{"location":"man/ltp/ltpcounter/#description","title":"DESCRIPTION","text":"ltpcounter uses LTP to receive service data units flagged with client service number client_ID from a remote ltpdriver client service process. When the total number of bytes of client service data it has received exceeds max_nbr_of_bytes, it terminates and prints reception and cancellation statistics. If max_nbr_of_bytes is omitted, the default limit is 2 billion bytes.
While receiving data, ltpcounter prints a 'v' character every 5 seconds to indicate that it is still alive.
"},{"location":"man/ltp/ltpcounter/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpcounter has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
ltpcounter was unable to start, because it could not attach to the LTP protocol on the local node or could not open access to client service clientId.
In the former case, run ltpadmin to start LTP and try again.
In the latter case, some other client service task has already opened access to client service clientId. If no such task is currently running (e.g., it crashed while holding the client service open), use ltpadmin to stop and restart the LTP protocol.
No configuration files are needed.
"},{"location":"man/ltp/ltpcounter/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpcounter/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by ltpcounter are written to the ION log file ion.log.
ltpcounter can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
ltpcounter can't open client access.
Another task has opened access to service client clientId and has not yet relinquished it.
Can't get LTP notice.
LTP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpcounter/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpdriver(1), ltp(3)
"},{"location":"man/ltp/ltpdriver/","title":"NAME","text":"ltpdriver - LTP transmission test program
"},{"location":"man/ltp/ltpdriver/#synopsis","title":"SYNOPSIS","text":"ltpdriver remoteEngineNbr clientId nbrOfCycles greenLength [ totalLength]
"},{"location":"man/ltp/ltpdriver/#description","title":"DESCRIPTION","text":"ltpdriver uses LTP to send nbrOfCycles service data units of length indicated by totalLength, of which the trailing greenLength bytes are sent unreliably, to the ltpcounter client service process for client service number clientId attached to the remote LTP engine identified by remoteEngineNbr. If omitted, length defaults to 60000. If length is 1, the sizes of the transmitted service data units will be randomly selected multiples of 1024 in the range 1024 to 62464.
Whenever the size of the transmitted service data unit is less than or equal to greenLength, the entire SDU is sent unreliably.
When all copies of the file have been sent, ltpdriver prints a performance report.
"},{"location":"man/ltp/ltpdriver/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpdriver has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
ltpdriver was unable to start, because it could not attach to the LTP protocol on the local node. Run ltpadmin to start LTP, then try again.
The service data units transmitted by ltpdriver are sequences of text obtained from a file in the current working directory named \"ltpdriverAduFile\", which ltpdriver creates automatically.
"},{"location":"man/ltp/ltpdriver/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpdriver/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by ltpdriver are written to the ION log file ion.log.
ltpdriver can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
Can't create ADU file
Operating system error. Check errtext, correct problem, and rerun.
Error writing to ADU file
Operating system error. Check errtext, correct problem, and rerun.
ltpdriver can't create file ref.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
ltpdriver can't create ZCO.
ION system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
ltpdriver can't send message.
LTP span to the remote engine has been stopped.
ltp_send failed.
LTP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpdriver/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpcounter(1), ltp(3)
"},{"location":"man/ltp/ltpmeter/","title":"NAME","text":"ltpmeter - LTP daemon task for aggregating and segmenting transmission blocks
"},{"location":"man/ltp/ltpmeter/#synopsis","title":"SYNOPSIS","text":"ltpmeter remote_engine_nbr
"},{"location":"man/ltp/ltpmeter/#description","title":"DESCRIPTION","text":"ltpmeter is a background \"daemon\" task that manages the presentation of LTP segments to link service output tasks. Each \"span\" of LTP data interchange between the local LTP engine and a neighboring LTP engine requires its own ltpmeter task. All ltpmeter tasks are spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol, and they are all terminated by ltpadmin in response to an 'x' (STOP) command.
ltpmeter waits until its span's current transmission block (the data to be transmitted during the transmission session that is currently being constructed) is ready for transmission, then divides the data in the span's block buffer into segments and enqueues the segments for transmission by the span's link service output task (giving the segments semaphore to unblock the link service output task as necessary), then reinitializes the span's block buffer and starts another session (giving the \"buffer empty\" semaphore to unblock the client service task -- nominally ltpclo, the LTP convergence layer output task for Bundle Protocol -- as necessary).
ltpmeter determines that the current transmission block is ready for transmission by waiting until either (a) the aggregate size of all service data units in the block's buffer exceeds the aggregation size limit for this span or (b) the length of time that the first service data unit in the block's buffer has been awaiting transmission exceeds the aggregation time limit for this span. The \"buffer full\" semaphore is given when ION (either the ltp_send() function or the ltpclock daemon) determines that one of these conditions is true; ltpmeter simply waits for this semaphore to be given.
The initiation of a new session may also be blocked: the total number of transmission sessions that the local LTP engine may have open at a single time is limited (this is LTP flow control), and while the engine is at this limit no new sessions can be started. Availability of a session from the session pool is signaled by the \"session\" semaphore, which is given whenever a session is completed or canceled.
"},{"location":"man/ltp/ltpmeter/#exit-status","title":"EXIT STATUS","text":"\"0\"
ltpmeter terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart ltpmeter.
\"1\"
ltpmeter terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart ltpmeter.
No configuration files are needed.
"},{"location":"man/ltp/ltpmeter/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpmeter/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
ltpmeter can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the LTP database by ltpadmin.
ltpmeter task is already started for this engine.
Redundant initiation of ltpmeter.
ltpmeter can't start new session.
An unrecoverable database error was encountered. ltpmeter terminates.
Can't take bufClosedSemaphore.
An unrecoverable database error was encountered. ltpmeter terminates.
Can't create extents list.
An unrecoverable database error was encountered. ltpmeter terminates.
Can't post ExportSessionStart notice.
An unrecoverable database error was encountered. ltpmeter terminates.
Can't finish session.
An unrecoverable database error was encountered. ltpmeter terminates.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpmeter/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpclock(1)
"},{"location":"man/ltp/ltprc/","title":"NAME","text":"ltprc - Licklider Transmission Protocol management commands file
"},{"location":"man/ltp/ltprc/#description","title":"DESCRIPTION","text":"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.
"},{"location":"man/ltp/ltprc/#commands","title":"COMMANDS","text":"?
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.
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.
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).
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.
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.
ltpadmin(1), udplsi(1), udplso(1)
"},{"location":"man/ltp/ltpsecadmin/","title":"NAME","text":"ltpsecadmin - LTP security policy administration interface
"},{"location":"man/ltp/ltpsecadmin/#synopsis","title":"SYNOPSIS","text":"ltpsecadmin [ commands_filename ]
"},{"location":"man/ltp/ltpsecadmin/#description","title":"DESCRIPTION","text":"ltpsecadmin configures and manages LTP security policy on the local computer.
It configures and manages LTP security policy on the local computer in response to LTP configuration commands found in commands_filename, if provided; if not, ltpsecadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from ltpsecadmin by entering the command 'h' or '?' at the prompt. The commands are documented in ltpsecrc(5).
"},{"location":"man/ltp/ltpsecadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of LTP security policy administration.
ltpsecadmin
Enter interactive LTP security policy administration command entry mode.
ltpsecadmin host1.ltpsecrc
Execute all configuration commands in host1.ltpsecrc, then terminate immediately.
Status and diagnostic messages from ltpsecadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which ltpsecadmin was run. The log file is typically named ion.log.
See also ltpsecrc(5).
"},{"location":"man/ltp/ltpsecadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/ltpsecadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the ionrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to ltpsecadmin. Otherwise ltpsecadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause ltpsecadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see ltpsecrc(5) for details.
"},{"location":"man/ltp/ltpsecadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/ltpsecadmin/#see-also","title":"SEE ALSO","text":"ltpsecrc(5)
"},{"location":"man/ltp/ltpsecrc/","title":"NAME","text":"ltpsecrc - LTP security policy management commands file
"},{"location":"man/ltp/ltpsecrc/#description","title":"DESCRIPTION","text":"LTP security policy management commands are passed to ltpsecadmin either in a file of text lines or interactively at ltpsecadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the LTP security policy management commands are described below.
"},{"location":"man/ltp/ltpsecrc/#commands","title":"COMMANDS","text":"?
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 ltpsecadmin 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.
a ltprecvauthrule ltp_engine_id ciphersuite_nbr [key_name]
The add ltprecvauthrule command. This command adds a rule specifying the manner in which LTP segment authentication will be applied to LTP segments received from the indicated LTP engine.
A segment from the indicated LTP engine will only be deemed authentic if it contains an authentication extension computed via the ciphersuite identified by ciphersuite_nbr using the applicable key value. If ciphersuite_nbr is 255 then the applicable key value is a hard-coded constant and key_name must be omitted; otherwise key_name is required and the applicable key value is the current value of the key named key_name in the local security policy database.
Valid values of ciphersuite_nbr are:
0: HMAC-SHA1-80\n1: RSA-SHA256\n255: NULL\nc ltprecvauthrule ltp_engine_id ciphersuite_nbr [key_name]
The change ltprecvauthrule command. This command changes the parameters of the LTP segment authentication rule for the indicated LTP engine.
d ltprecvauthrule ltp_engine_id
The delete ltprecvauthrule command. This command deletes the LTP segment authentication rule for the indicated LTP engine.
i ltprecvauthrule ltp_engine_id
This command will print information (the LTP engine id, ciphersuite number, and key name) about the LTP segment authentication rule for the indicated LTP engine.
l ltprecvauthrule
This command lists all LTP segment authentication rules in the security policy database.
a ltpxmitauthrule ltp_engine_id ciphersuite_nbr [key_name]
The add ltpxmitauthrule command. This command adds a rule specifying the manner in which LTP segments transmitted to the indicated LTP engine must be signed.
Signing a segment destined for the indicated LTP engine entails computing an authentication extension via the ciphersuite identified by ciphersuite_nbr using the applicable key value. If ciphersuite_nbr is 255 then the applicable key value is a hard-coded constant and key_name must be omitted; otherwise key_name is required and the applicable key value is the current value of the key named key_name in the local security policy database.
Valid values of ciphersuite_nbr are:
0: HMAC\\_SHA1-80\n1: RSA\\_SHA256\n255: NULL\nc ltpxmitauthrule ltp_engine_id ciphersuite_nbr [key_name]
The change ltpxmitauthrule command. This command changes the parameters of the LTP segment signing rule for the indicated LTP engine.
d ltpxmitauthrule ltp_engine_id
The delete ltpxmitauthrule command. This command deletes the LTP segment signing rule for the indicated LTP engine.
i ltpxmitauthrule ltp_engine_id
This command will print information (the LTP engine id, ciphersuite number, and key name) about the LTP segment signing rule for the indicated LTP engine.
l ltpxmitauthrule
This command lists all LTP segment signing rules in the security policy database.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
ltpsecadmin(1)
"},{"location":"man/ltp/sda/","title":"NAME","text":"sda - LTP Service Data Aggregation (SDA) library
"},{"location":"man/ltp/sda/#synopsis","title":"SYNOPSIS","text":"#include \"sda.h\"\n\ntypedef vast (*SdaDelimiterFn)(unsigned int clientId, unsigned char *buffer, vast bufferLength);\n\ntypedef int (*SdaHandlerFn)(uvast sourceEngineId, unsigned int clientId, Object clientServiceData);\n\n[see description for available functions]\nThe sda library provides functions enabling application software to use LTP more efficiently, by aggregating multiple small client service data units into larger LTP client service data items. This reduces overhead somewhat, but more importantly it reduces the volume of positive and negative LTP acknowledgment traffic by sending more data in fewer LTP blocks -- because LTP acknowledgments are issued on a per-block basis.
The library relies on the application to detect the boundaries between aggregated service data units in each received LTP client service data item; the application must provide an SdaDelimiterFn function for this purpose. An SDA delimiter function inspects the client service data bytes in buffer - some portion of an LTP service data block, of length bufferLength - to determine the length of the client service data unit at the start of the buffer; data unit client service ID is provided to aid in this determination. The function returns that length if the determination was successful, zero if there is no valid client service data item at the start of the buffer, -1 on any system failure.
The sda library similarly relies on the application to process the service data units identified in this manner; the application must provide an SdaHandlerFn function for this purpose. An SDA handler function is provided with the ID of the LTP engine that sent the service data unit, the client ID characterizing the service data unit, and the service data unit itself; the service data unit is presented as a Zero-Copy Object (ZCO). The handler function must return -1 on any system error, zero otherwise.
int sda_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData);
Sends a client service data unit to an application, identified by clientId, at the LTP engine identified by destinationEngineId. clientServiceData must be a \"zero-copy object\" reference as returned by ionCreateZco(). Note that SDA will privately make and destroy its own reference to the client service data; the application is free to destroy its reference at any time. Note that the client service data unit will always be sent reliably (i.e., \"red\").
Also note that sda_run() must be executing in order for sda_send to be performed.
Returns 0 on success, -1 on any system failure.
int sda_run(SdaDelimiterFn delimiter, SdaHandlerFn handler);
sda_run() executes an infinite loop that receives LTP client service data items, calls delimiter to determine the length of each client service data unit in each item, and passes those client service data units to the handler function. To terminate the loop, call sda_interrupt(). Note that sda_send() can only be executed while the sda_run() loop is still executing.
Returns 0 on success, -1 on any system failure.
void sda_interrupt();
Interrupts sda_run().
sdatest(1), zco(3)
"},{"location":"man/ltp/sdatest/","title":"NAME","text":"sdatest - LTP service data aggreggation test program
"},{"location":"man/ltp/sdatest/#synopsis","title":"SYNOPSIS","text":"sdatest [remoteEngineNbr]
"},{"location":"man/ltp/sdatest/#description","title":"DESCRIPTION","text":"sdatest tests LTP service data aggregation (SDA).
Each instance of the program can run either as a sender and receiver or as a receiver only. For sending, sdatest starts a background thread that offers a command-line prompt and accepts strings of text for transmission. It uses SDA to aggregate the strings into LTP service data items for LTP client ID 2, which is SDA. The strings (SDA data units) are delimited by terminating NULLs, and they are all identified by SDA client ID number 135.
For reception, sdatest listens for LTP traffic for client 2. When it receives an LTP Service data item (in an LTP block), it parses out all of the SDA data units aggregated in that data item and prints them to stdout.
Use ^C to terminate sdatest.
"},{"location":"man/ltp/sdatest/#exit-status","title":"EXIT STATUS","text":"\"0\"
sdatest has terminated. Any problems encountered during operation will be noted in the ion.log log file.
\"1\"
sdatest was unable to start. See the ion.log file for details.
No files are used by sdatest.
"},{"location":"man/ltp/sdatest/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/sdatest/#diagnostics","title":"DIAGNOSTICS","text":"Diagnostic messages produced by sdatest are written to the ION log file ion.log.
"},{"location":"man/ltp/sdatest/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/sdatest/#see-also","title":"SEE ALSO","text":"sda(3)
"},{"location":"man/ltp/udplsi/","title":"NAME","text":"udplsi - UDP-based LTP link service input task
"},{"location":"man/ltp/udplsi/#synopsis","title":"SYNOPSIS","text":"udplsi {local_hostname | @}[:local_port_nbr]
"},{"location":"man/ltp/udplsi/#description","title":"DESCRIPTION","text":"udplsi is a background \"daemon\" task that receives UDP datagrams via a UDP socket bound to local_hostname and local_port_nbr, extracts LTP segments from those datagrams, and passes them to the local LTP engine. Host name \"@\" signifies that the host name returned by hostname(1) is to be used as the socket's host name. If not specified, port number defaults to 1113.
The link service input task is spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol; the text of the command that is used to spawn the task must be provided as a parameter to the 's' command. The link service input task is terminated by ltpadmin in response to an 'x' (STOP) command.
"},{"location":"man/ltp/udplsi/#exit-status","title":"EXIT STATUS","text":"\"0\"
udplsi terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart udplsi.
\"1\"
udplsi terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart udplsi.
No configuration files are needed.
"},{"location":"man/ltp/udplsi/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/udplsi/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udplsi can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
LSI task is already started.
Redundant initiation of udplsi.
LSI can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udplsi.
LSI can't initialize socket
Operating system error. Check errtext, correct problem, and restart udplsi.
LSI can't create receiver thread
Operating system error. Check errtext, correct problem, and restart udplsi.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/udplsi/#see-also","title":"SEE ALSO","text":"ltpadmin(1), udplso(1), owltsim(1)
"},{"location":"man/ltp/udplso/","title":"NAME","text":"udplso - UDP-based LTP link service output task
"},{"location":"man/ltp/udplso/#synopsis","title":"SYNOPSIS","text":"udplso {remote_engine_hostname | @}[:remote_port_nbr] remote_engine_nbr
"},{"location":"man/ltp/udplso/#description","title":"DESCRIPTION","text":"udplso is a background \"daemon\" task that extracts LTP segments from the queue of segments bound for the indicated remote LTP engine, encapsulates them in UDP datagrams, and sends those datagrams to the indicated UDP port on the indicated host. If not specified, port number defaults to 1113.
Each \"span\" of LTP data interchange between the local LTP engine and a neighboring LTP engine requires its own link service output task, such as udplso. All link service output tasks are spawned automatically by ltpadmin in response to the 's' command that starts operation of the LTP protocol, and they are all terminated by ltpadmin in response to an 'x' (STOP) command.
"},{"location":"man/ltp/udplso/#exit-status","title":"EXIT STATUS","text":"\"0\"
udplso terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use ltpadmin to restart udplso.
\"1\"
udplso terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use ltpadmin to restart udplso.
No configuration files are needed.
"},{"location":"man/ltp/udplso/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/ltp/udplso/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
udplso can't initialize LTP.
ltpadmin has not yet initialized LTP protocol operations.
No such engine in database.
remote_engine_nbr is invalid, or the applicable span has not yet been added to the LTP database by ltpadmin.
LSO task is already started for this engine.
Redundant initiation of udplso.
LSO can't open UDP socket
Operating system error. Check errtext, correct problem, and restart udplso.
LSO can't connect UDP socket
Operating system error. Check errtext, correct problem, and restart udplso.
Segment is too big for UDP LSO.
Configuration error: segments that are too large for UDP transmission (i.e., larger than 65535 bytes) are being enqueued for udplso. Use ltpadmin to change maximum segment size for this span.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/ltp/udplso/#see-also","title":"SEE ALSO","text":"ltpadmin(1), ltpmeter(1), udplsi(1), owltsim(1)
"},{"location":"man/nm/","title":"Index of Man Pages","text":"nm_agent - Network Management Agent implementing the Asynchronous Management Protocol (AMP)
"},{"location":"man/nm/nm_agent/#synopsis","title":"SYNOPSIS","text":"nm_agent <agent eid> manager eid
"},{"location":"man/nm/nm_agent/#description","title":"DESCRIPTION","text":"Starts the network management agent listening on agent eid and communicating with a remote manager at manager eid
"},{"location":"man/nm/nm_agent/#see-also","title":"SEE ALSO","text":"Asynchronous Management Protocol
nm_mgr(1)
"},{"location":"man/nm/nm_mgr/","title":"NAME","text":"nm_mgr - Network Management server implementing the Asynchronous Management Protocol (AMP)
"},{"location":"man/nm/nm_mgr/#synopsis","title":"SYNOPSIS","text":"nm_mgr [options] manager eid
The following options may be specified to customize behavior. Use \"nm_mgr --help\" for full usage information:
-A
Startup directly in the alternative Automator UI mode. This mode is designed to provide a consistent line-based interface suitable for automated scripting. Type ? when active for usage details.
-l
If specified, enable file-based logging of Manager Activity on startup. This can be toggled at any time from the main menu of the UI.
If logging is not enabled, the following arguments have no affect until enabled in UI.
-d
Log each agent to a different directory.
-L #
Specify maximum number of entries (reports+tables) per file before rotating.
-D DIR
NM logs will be placed in this directory.
-r
Log all received reports to file in text format (as shown in UI).
-t
Log all received tables to file in text format (as shown in UI).
-T
Log all transmitted message as ASCII-encoded CBOR HEX strings.
-R
Log all received messages as ASCII-encoded CBOR HEX strings.
Starts the nm_mgr application listening on mgr eid for messages from nm_agent clients. Specify \"--help\" for full usage information.
An agent will automatically attempt to register with it's configured manager on startup. Agents may also be added manually through the managers UI.
The manager provides a text based UI as its primary interface. The UI provides capabilities to list, register, or delete agents. It can view received reports and tables, and be used to send commands (ARIs) to registered agents.
An experimental REST API is available if built with the configuration option \"--enable-rest\". The default configuration will be accessible at http://localhost:8089/nm/api.
"},{"location":"man/nm/nm_mgr/#see-also","title":"SEE ALSO","text":"Asynchronous Management Protocol
nm_agent(1)
"},{"location":"man/restart/","title":"Index of Man Pages","text":"ionrestart - ION node restart utility
"},{"location":"man/restart/ionrestart/#synopsis","title":"SYNOPSIS","text":"ionrestart
"},{"location":"man/restart/ionrestart/#description","title":"DESCRIPTION","text":"ionrestart is a utility task that is executed automatically when an ION transaction fails, provided transaction reversibility is enabled (see ionconfig(5)). It should never need to be executed from the command line.
When an ION transaction is reversed, all changes made to the SDR non-volatile heap in the course of the transaction are backed out but changes made to ION's working memory are not. (Forward logging of these changes to enable automatic reversal on these relatively rare occasions is judged to impose too much continuous processing overhead to be cost-justified.) Because the state of working memory is thereupon in conflict with information in the heap, ionrestart is automatically invoked to reload all of working memory; because this would obviously threaten the stability of all running ION tasks, ionrestart gracefully terminates the tasks of the node (not only ION daemons but also applications), then reloads working memory from the recovered heap, and finally restarts the ION daemons. Applications that receive termination indications from ionrestart may choose to sleep for a few seconds and then automatically re-initialize their own operations.
ionrestart will attempt to restart all core ION protocols including LTP, BP, and CFDP, but any protocols which were not operating at the time of the transaction reversal are not restarted. Also, protocols that ionrestart has not yet been adapted to cleanly terminate and restart (including, at the time of this writing, BSSP and DPTC) are not restarted.
"},{"location":"man/restart/ionrestart/#exit-status","title":"EXIT STATUS","text":"\"0\"
ionrestart terminated normally.
\"1\"
ionrestart failed, for reasons noted in the ion.log file; the task terminated.
No configuration files are used beyond those required for normal ION node initialization.
"},{"location":"man/restart/ionrestart/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/restart/ionrestart/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/restart/ionrestart/#see-also","title":"SEE ALSO","text":"ionadmin(1), ltpadmin(1), bpadmin(1), cfdpadmin(1)
"},{"location":"man/tc/","title":"Index of Man Pages","text":"dtka - Delay-Tolerant Key Administration (DTKA) daemon
"},{"location":"man/tc/dtka/#synopsis","title":"SYNOPSIS","text":"dtka
dtka is a delay-tolerant public key infrastructure (PKI) system, built on the Trusted Collective (TC) application framework. Each DTKA daemon generates public/private key pairs and uses the TC framework to distribute public keys securely and to receive the public keys generated and distributed by other DTKA daemons. For an overview of TC, see the tc(3) manual page.
"},{"location":"man/tc/dtka/#description","title":"DESCRIPTION","text":"The DTKA system provides a trustworthy mechanism for delay-tolerant distribution of public keys, enabling ION's BP and LTP implementations to utilize asymmetric cryptography to ensure the integrity and/or confidentiality of data exchange as necessary. (Discussion of asymmetric cryptography is beyond the scope of this manual page.)
A central principle of DTKA is that keys have effective times which condition their applicability. For example, the public key that must be used to encrypt a bundle payload destined for a given node is the public key (asserted by that node) whose associated effective time is greatest among all of that node's public keys whose associated effective times are less than or equal to the creation time of the bundle. Effective times enable keys to be distributed far in advance of the times at which they will be used, which is what makes DTKA delay-tolerant: when the time arrives at which a node needs a given key, the key is already in place.
The dtka daemon is responsible for periodically generating, on behalf of a given DTN node, public/private key pairs that will be effective at times in the future.
The first public key generated by a given DTN node's dtka daemon is distributed by means of an application-specific DTKA initialization procedure. The procedure may be an out-of-band mechanism by which the initializing node's public key is generated and submitted to the DTKA authority while the user node is under the physical control of the DTKA authority's administrator. Alternatively, the initializing node's public key may be submitted to the DTKA authority by some other DTN node whose dtka daemon is known to the DTKA authority and is trusted, in which case that node utilizes the TC framework on behalf of the initializing node.
Each subsequently generated public key is signed in the node's applicable private key and is submitted directly to the DTKA authority by means of the TC framework.
Public key revocations, generated by the DTKA authority's administrator, are submitted in the same way as assertions of new public keys.
NOTE that dtka utilizes functions provided by cryptography software that is not distributed with ION. To indicate that this supporting software has been installed, set the compiler flag -DCRYPTO_SOFTWARE_INSTALLED when compiling this program. Absent that flag setting at compile time, the dtka daemon's generateKeyPair() function does nothing.
"},{"location":"man/tc/dtka/#exit-status","title":"EXIT STATUS","text":"\"0\"
dtka terminated, for reasons noted in the ion.log file.
\"1\"
dtka was unable to attach to TC client functionality, possibly because tcc is not running.
The dtkaadmin utility is used to configure the operation of the dtka daemon; see the dtkarc(5) man page for details.
"},{"location":"man/tc/dtka/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/dtka/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/dtka/#see-also","title":"SEE ALSO","text":"dtkaadmin(1), dtkarc(5), tc(3), tcc(1), tccadmin(1), tccrc(5)
"},{"location":"man/tc/dtkaadmin/","title":"NAME","text":"dtkaadmin - DTKA user function administration interface
"},{"location":"man/tc/dtkaadmin/#synopsis","title":"SYNOPSIS","text":"dtkaadmin [ commands_filename ]
"},{"location":"man/tc/dtkaadmin/#description","title":"DESCRIPTION","text":"dtkaadmin configures and manages the DTKA administration database for the local ION node, enabling the node to utilize the services of the Trusted Collective for Delay-Tolerant Key Administration.
It configures and manages that database in response to DTKA configuration commands found in commands_filename, if provided; if not, dtkaadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from dtkaadmin by entering the command 'h' or '?' at the prompt. The commands are documented in dtkarc(5).
"},{"location":"man/tc/dtkaadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of DTKA configuration.
dtkaadmin
Enter interactive DTKA configuration command entry mode.
dtkaadmin host1.karc
Execute all configuration commands in host1.karc, then terminate immediately.
Status and diagnostic messages from dtkaadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which dtkaadmin was run. The log file is typically named ion.log.
See also dtkarc(5).
"},{"location":"man/tc/dtkaadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/dtkaadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the dtkarc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to dtkaadmin. Otherwise dtkaadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause dtkaadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see dtkarc(5) for details.
"},{"location":"man/tc/dtkaadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/dtkaadmin/#see-also","title":"SEE ALSO","text":"dtka(1), dtkarc(5)
"},{"location":"man/tc/dtkarc/","title":"NAME","text":"dtkarc - DTKA user configuration commands file
"},{"location":"man/tc/dtkarc/#description","title":"DESCRIPTION","text":"DTKA user configuration commands are passed to dtkaadmin either in a file of text lines or interactively at dtkaadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the DTKA user function administration commands are described below.
"},{"location":"man/tc/dtkarc/#commands","title":"COMMANDS","text":"?
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 dtkaadmin to be logged as well as sent to stdout. Setting echo to 0 disables this behavior.
1
The initialize command. Until this command is executed, the DTKA user function is not in operation on the local ION node and most dtkaadmin commands will fail.
i
The info This command will print information about the current state of the local node's DTKA user function, including the current settings of all parameters that can be managed as described below.
m keygentime time
The manage key generation time command. This command sets the time at which the node will next generate a public/private key pair and multicast the public key. The command is not needed in normal operations, because future key generation times are computed automatically as key pairs are generated. time must be in yyyy/mm/dd-hh:mm:ss format.
m interval key_pair_generation_interval
The manage key pair generation interval command. This interval, expressed as a number of seconds, controls the period on which the DTKA user function will generate new public/private key pairs. The default value is 604800 (one week).
m leadtime key_pair_effectivenes_lead_time
The manage key pair effectivenes lead time command. This interval, expressed as a number of seconds, controls the length of time after the time of key pair generation at which the key pair will become effective. The default value is 345600 (four days).
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
m interval 3600
Asserts that the DTKA function will generate a new key pair every 3600 seconds (one hour).
dtkaadmin(1)
"},{"location":"man/tc/tc/","title":"NAME","text":"tc - the Trusted Collective system for Delay-Tolerant Networking
"},{"location":"man/tc/tc/#synopsis","title":"SYNOPSIS","text":"#include \"tcc.h\"\n\n[see description for available functions]\nThe TC system provides a trustworthy framework for delay-tolerant distribution of information that is of critical importance - that is, information that must be made available as needed and must not be corrupt - but is not confidential. As such it accomplishes some of the same objectives as are accomplished by \"servers\" in the Internet.
A central principle of TC is that items of critical information may have effective times which condition their applicability. For example, a change in rules restricting air travel will typically be scheduled to take effect on some stated date in the near future. Effective times enable critical information to be distributed far in advance of the time at which it will be needed, which is what makes TC delay-tolerant: when the time arrives at which a node needs a given item of critical information, the information is already in place. No query/response exchange is necessary.
The TC framework for a given TC application comprises (a) a collective authority, which should include several geographically distributed \"authority\" nodes, and (b) \"client\" nodes which utilize the services of the collective authority, possibly including the key authority nodes themselves. The framework is designed to convey to every participating client node the critical information submitted to the collective authority by all other participating client nodes, in a trustworthy manner, prior to the times at which those items of information become effective. It operates as follows.
The user function of a given TC application generates records containing critical information and issues those records as the application data units forming the payloads of BP bundles. The destination of each such bundle is the multicast group designated for receivers of the records of that application. The members of that multicast group are the authority nodes of the application's collective authority.
The records are delivered to the tcarecv daemons of the authority nodes. Each such daemon validates the received records and inserts all valid records in its authority node's private database of pending records.
Periodically, the tcacompile daemons of all authority nodes in the application's collective authority simultaneously compile bulletins of all records recently received from user nodes. (A TC bulletin is simply an array of contiguous TC records.) These daemons then all issue their bulletins as the application data units forming the payloads of BP bundles. The destination of each such bundle is the multicast group designated for receivers of the bulletins of that application. The members of that multicast group are, again, the authority nodes of the application's collective authority. In addition, each tcacompile daemon spawns one tcapublish process that is assigned the task of processing the bulletins compiled by all authority nodes during this iteration of the compilation cycle.
The bulletins are delivered to the tcapublish processes of all authority nodes in the application's collective authority. The tcapublish processes then compute a common consensus bulletin, which includes all recently asserted records that all of the authority nodes have received and found valid.
Each tcapublish process then computes a hash for the consensus bulletin and erasure-codes the bulletin, producing a list of code blocks; the hashes and lists of blocks will be identical for all key authority nodes. It then issues a small subset of those code blocks as the application data units forming the payloads of BP bundles. The destination of each such bundle is the multicast group designated for receivers of the code blocks of the application. The members of that multicast group are the tcc (that is, TC client) daemons serving the application's user nodes. The subsets of the block list issued by all tcapublish daemons are different, but each code block is tagged with the common bulletin hash.
The code blocks are delivered to the tcc daemons of all of the application's user nodes, each of which uses the received code blocks to reassemble the consensus bulletin. Code blocks with differing bulletin hashes are not used to reassemble the same bulletin, and the erasure coding of the bulletin prevents failure to receive all code blocks from preventing reassembly of the complete bulletin. When a consensus bulletin has been successfully reassembled, the records in the bulletin are delivered to the user function.
The tcaboot and tcaadmin utilities are used to configure the collective authority of a given TC application; the tccadmin utility is used to configure TC client functionality for a given TC application on a given user node.
The TC library functions provided to TC application user software are described below.
int tc_serialize(char *buffer, unsigned int buflen, uvast nodeNbr, time_t effectiveTime, time_t assertionTime, unsigned short datLength, unsigned char *datValue)
Forms in buffer a serialized TC record, ready for transmission as a BP application data unit, that contains the indicated node number, effective time, assertion time, application data length, and application data. Returns the length of the record, or -1 on any missing arguments.
int tcc_getBulletin(int blocksGroupNbr, char **bulletinContent, int *length)
Places in *bulletinContent a pointer to an ION private working memory buffer containing the content of the oldest previously unhandled received TC bulletin for the application identified by blocksGroupNbr. Returns 0 on success, -1 on any system failure. A returned buffer length of 0 indicates that the function was interrupted and must be repeated.
Note that the calling function MUST MRELEASE the bulletin content buffer when processing is complete. Failure to do so will introduce a memory leak.
int tc_deserialize(char **buffer, int *buflen, unsigned short maxDatLength, uvast *nodeNbr, time_t *effectiveTime, time_t *assertionTime, unsigned short *datLength, unsigned char *datValue)
Parses out of the bulletin in buffer the data elements of a single serialized TC record: node number, effective time, assertion time, application data length, and application data. Returns -1 on any missing arguments, 0 on any record malformation, record length otherwise.
tcaboot(1), tcaadmin(1), tcarecv(1), tcacompile(1), tcapublish(1), tccadmin(1), tcc(1)
"},{"location":"man/tc/tcaadmin/","title":"NAME","text":"tcaadmin - Trusted Collective (TC) authority administration interface
"},{"location":"man/tc/tcaadmin/#synopsis","title":"SYNOPSIS","text":"tcaadmin blocks_group_number [ commands_filename ]
"},{"location":"man/tc/tcaadmin/#description","title":"DESCRIPTION","text":"tcaadmin configures and manages the Trusted Collective authority databases for TC applications on the local ION node, enabling the node to function as a member of one or more collective authorities.
The first command-line argument to tcaadmin is blocksGroupNumber, which identifies the specific TC application to which all commands submitted to this instance of tcaadmin will apply. A TC application is uniquely identified by the group number of the Bundle Protocol multicast group comprising all nodes hosting TC clients that subscribe to TC \"blocks\" published for that application.
tcaadmin configures and manages a TC authority database in response to authority configuration commands found in commands_filename, if provided; if not, tcaadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from tcaadmin by entering the command 'h' or '?' at the prompt. The commands are documented in tcarc(5).
"},{"location":"man/tc/tcaadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of TC authority administration.
tcaadmin 203
Enter interactive TC authority administration command entry mode for application 203.
tcaadmin 203 host1.tcarc
Apply the application-203 configuration commands in host1.tcarc, then terminate immediately.
Status and diagnostic messages from tcaadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which tcaadmin was run. The log file is typically named ion.log.
See also tcarc(5).
"},{"location":"man/tc/tcaadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcaadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the tcarc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to tcaadmin. Otherwise tcaadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause tcaadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see tcarc(5) for details.
"},{"location":"man/tc/tcaadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcaadmin/#see-also","title":"SEE ALSO","text":"tcacompile(1), tcapublish(1), tcarecv(1), tcarc(5)
"},{"location":"man/tc/tcaboot/","title":"NAME","text":"tcaboot - Trusted Collective (TC) authority initialization utility
"},{"location":"man/tc/tcaboot/#synopsis","title":"SYNOPSIS","text":"tcaboot multicast_group_number_for_TC_bulletins multicast_group_number_for_TC_records number_of_authorities_in_collective K R [ delay ]
"},{"location":"man/tc/tcaboot/#description","title":"DESCRIPTION","text":"tcaboot writes a TC authority administration command file that initializes a TC authority database. The file, named \"boot.tcarc\", is written to the current working directory. It simply contains two authority configuration commands that initialize the TC authority database for the TC application and then set the initial bulletin compilation time for this authority to the current ctime plus delay seconds. If omitted, delay defaults to 5. The other command-line arguments for tcaboot are discussed in the descriptions of application initialization commands for tcaadmin; see the tcarc(5) manual page for details.
"},{"location":"man/tc/tcaboot/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful generation of TC authority initialization file.
tcaboot 210 209 6 50 .2
Writes a boot.tcarc file that initializes the local node's TC authority database as indicated and sets the next bulletin compilation time to the current time plus 5 seconds.
tcaboot 210 209 6 50 .2 90
Writes a boot.tcarc file that initializes the local node's TC authority database as indicated and sets the next bulletin compilation time to the current time plus 90 seconds.
No files apply.
"},{"location":"man/tc/tcaboot/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcaboot/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the log file:
Can't open cmd file
tcaboot is unable to create a file named boot.tcarc for the indicated reason, a system error.
Can't write to cmd file
tcaboot is unable to write to boot.tcarc for the indicated reason, a system error.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcaboot/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tcarc(5)
"},{"location":"man/tc/tcacompile/","title":"NAME","text":"tcacompile - Trusted Collective daemon task for compiling critical information bulletins
"},{"location":"man/tc/tcacompile/#synopsis","title":"SYNOPSIS","text":"tcacompile blocks_group_number
"},{"location":"man/tc/tcacompile/#description","title":"DESCRIPTION","text":"tcacompile is a background \"daemon\" task that periodically generates new proposed bulletins of recent critical information records and multicasts those bulletins to all nodes in the collective authority for the TC application identified by blocks_group_number. It is spawned automatically by tcaadmin in response to the 's' command that starts operation of the TC authority function for this application on the local node, and it is terminated by tcaadmin in response to an 'x' (STOP) command.
"},{"location":"man/tc/tcacompile/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcacompile terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use tcaadmin to restart tcacompile.
\"1\"
tcacompile was unable to attach to TC authority operations, probably because tcaadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/tc/tcacompile/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcacompile/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcacompile can't attach to tca system.
tcaadmin has not yet initialized the authority database for this TC application.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcacompile/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tc(3), tcarc(5)
"},{"location":"man/tc/tcapublish/","title":"NAME","text":"tcapublish - Trusted Collective authority task that publishes consensus critical information bulletins
"},{"location":"man/tc/tcapublish/#synopsis","title":"SYNOPSIS","text":"tcapublish blocks_group_number
"},{"location":"man/tc/tcapublish/#description","title":"DESCRIPTION","text":"tcapublish is a background task that completes the processing of a single iteration of the bulletin publication cycle for the collective authority function of the TC application identified by blocks_group_number on the local node. To do so, it receives proposed bulletins multicast by tcacompile daemons, resolves differences among the received bulletins to arrive at a consensus bulletin, computes a hash for the consensus bulletin, erasure-codes the consensus bulletin, and multicasts that subset of the resulting code blocks that is allocated to the local node according to the local node's assigned position in the authority array of the application's collective authority. It is spawned automatically by the local node's tcacompile daemon for the indicated application, at the time that daemon publishes its own proposed bulletin for this iteration of the bulletin compilation cycle; it terminates immediately after it has finished publishing code blocks.
"},{"location":"man/tc/tcapublish/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcapublish terminated, for reasons noted in the ion.log file.
\"1\"
tcapublish was unable to attach to TC authority operations, probably because tcaadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/tc/tcapublish/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcapublish/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcapublish can't attach to DTKA.
tcaadmin has not yet initialized the authority database for this TC application.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcapublish/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tc(3), tcauthrc(5)
"},{"location":"man/tc/tcarc/","title":"NAME","text":"tcarc - Trusted Collective authority configuration commands file
"},{"location":"man/tc/tcarc/#description","title":"DESCRIPTION","text":"TC authority configuration commands are passed to tcaadmin either in a file of text lines or interactively at tcaadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the TC authority configuration commands are described below.
"},{"location":"man/tc/tcarc/#commands","title":"COMMANDS","text":"?
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 tcaadmin 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.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
1 multicast_group_number_for_TC_bulletins multicast_group_number_for_TC_records number_of_authorities_in_collective K R
The initialize command. Until this command is executed, the authority function for the selected TC application is not in operation on the local ION node and most tcaadmin commands will fail.
K is the mandated diffusion for the selected TC application, i.e., the number of blocks into which each bulletin of published TC information is divided for transmission.
R is the mandated redundancy for the selected TC application, i.e., the percentage of blocks issued per bulletin that will be parity blocks rather than extents of the bulletin itself.
i
The info This command will print information about the current state of the authority function for the selected TC application on the local node, including the current settings of all parameters that can be managed as described below.
s
The start command. This command starts the tcarecv and tcacompile daemons of the authority function for the selected TC application on the local node.
m compiletime time
The manage compile time command. This command sets the time at which the authority function for the selected TC application on this node will next compile a bulletin. The command is not needed in normal operations, because future compile times are computed automatically as bulletins are compiled. time must be in yyyy/mm/dd-hh:mm:ss format.
m interval bulletin_compilation_interval
The manage bulletin compilation interval command. This interval, expressed as a number of seconds, controls the period on which the authority function for the selected TC appliction on this node will compile new key information bulletins. The default value is 3600 (one hour).
m grace bulletin_consensus_grace_time
The manage bulletin consensus grace time command. This interval, expressed as a number of seconds, controls the length of time the authority function for the selected TC application on this node will wait after publishing a bulletin before computing a consensus bulletin; this parameter is intended to relax the degree to which the system clocks of all members of the collective authority for this TC application must be in agreement. The default value is 60 (1 minute).
+ authority_array_index node_number
This command asserts that the trusted Nth member of the collective authority for the selected TC application, where N is the authority_array_index value, is the node identified by node_number.
- authority_array_index
This command asserts that the Nth member of the collective authority for the selected TC application, where N is the authority_array_index value, is no longer trusted; bulletins received from this collective authority member must be discarded.
a node_number
This command adds the node identified by node_number to the list of nodes hosting authorized_clients for the selected TC application. Once this list has been populated, TC records for this application that are received from clients residing on nodes that are not in the list are automatically discarded by the authority function residing on the local node.
d node_number
This command deletes the node identified by node_number from the list of nodes hosting authorized_clients for the selected TC application.
l
This command lists all nodes currently hosting authorized_clients for the selected TC application.
x
The stop command. This command stops the tcarecv and tcacompile daemons of the authority function for the selected TC application on the local node.
Asserts that node 6913 is now member 3 of the collective authority for the selected application.
tcaadmin(1), dtka(3)
"},{"location":"man/tc/tcarecv/","title":"NAME","text":"tcarecv - Trusted Collective daemon task for receiving newly generated records of critical information
"},{"location":"man/tc/tcarecv/#synopsis","title":"SYNOPSIS","text":"tcarecv blocks_group_number
"},{"location":"man/tc/tcarecv/#description","title":"DESCRIPTION","text":"tcarecv is a background \"daemon\" task that receives new critical information records multicast by user nodes of the TC application identified by blocks_group_number. It records those assertions in a database for future processing by tcacompile. It is spawned automatically by tcaadmin in response to the 's' command that starts operation of the TC authority function for this application on the local node, and it is terminated by tcaadmin in response to an 'x' (STOP) command.
"},{"location":"man/tc/tcarecv/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcarecv terminated, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use tcaadmin to restart tcarecv.
\"1\"
tcarecv was unable to attach to DTKA operations, probably because tcaadmin has not yet been run.
No configuration files are needed.
"},{"location":"man/tc/tcarecv/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcarecv/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcarecv can't attach to DTKA.
tcaadmin has not yet initialized the authority database for this TC application.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcarecv/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tc(3), tcarc(5)
"},{"location":"man/tc/tcc/","title":"NAME","text":"tcc - Trusted Collective client daemon task for handling bulletins from a collective authority
"},{"location":"man/tc/tcc/#synopsis","title":"SYNOPSIS","text":"tcc blocks_group_number
"},{"location":"man/tc/tcc/#description","title":"DESCRIPTION","text":"tcc is a background \"daemon\" task that receives code blocks multicast by the authority nodes of the collective authority for the TC application identified by blocks_group_number. It reassembles bulletins from compatible code blocks and delivers those bulletins to the application's user function on the local node.
"},{"location":"man/tc/tcc/#exit-status","title":"EXIT STATUS","text":"\"0\"
tcc terminated, for reasons noted in the ion.log file.
\"1\"
tcc was unable to attach to TC client operations, possibly because the TC client database for this application has not yet been initialized by tcaadmin.
No configuration files are needed.
"},{"location":"man/tc/tcc/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tcc/#diagnostics","title":"DIAGNOSTICS","text":"The following diagnostics may be issued to the ion.log log file:
tcc can't attach to tcc system.
tcaadmin has not yet initialized the TC client database for this application.
Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tcc/#see-also","title":"SEE ALSO","text":"tcaadmin(1), tcarc(5)
"},{"location":"man/tc/tccadmin/","title":"NAME","text":"tccadmin - DTKA node administration interface
"},{"location":"man/tc/tccadmin/#synopsis","title":"SYNOPSIS","text":"tccadmin blocks_group_number [ commands_filename ]
"},{"location":"man/tc/tccadmin/#description","title":"DESCRIPTION","text":"tccadmin configures and manages the Trusted Collecive client databases for TC applications on the local ION node, enabling the node to utilize the services of one or more collective authorities.
The first command-line argument to tccadmin is blocksGroupNumber, which identifies the specific TC application to which all commands submitted to this instance of tccadmin will apply. A TC application is uniquely identified by the group number of the Bundle Protocol multicast group comprising all nodes hosting TC clients that subscribe to TC \"blocks\" published for that application.
tccadmin configures and manages a TC client database in response to client configuration commands found in commands_filename, if provided; if not, tccadmin prints a simple prompt (:) so that the user may type commands directly into standard input.
The format of commands for commands_filename can be queried from tccadmin by entering the command 'h' or '?' at the prompt. The commands are documented in tccrc(5).
"},{"location":"man/tc/tccadmin/#exit-status","title":"EXIT STATUS","text":"\"0\"
Successful completion of TC client administration.
tccadmin
Enter interactive TC client administration command entry mode.
tccadmin host1.karc
Execute all configuration commands in host1.karc, then terminate immediately.
Status and diagnostic messages from tccadmin and from other software that utilizes the ION node are nominally written to a log file in the current working directory within which tccadmin was run. The log file is typically named ion.log.
See also tccrc(5).
"},{"location":"man/tc/tccadmin/#environment","title":"ENVIRONMENT","text":"No environment variables apply.
"},{"location":"man/tc/tccadmin/#diagnostics","title":"DIAGNOSTICS","text":"Note: all ION administration utilities expect source file input to be lines of ASCII text that are NL-delimited. If you edit the tccrc file on a Windows machine, be sure to use dos2unix to convert it to Unix text format before presenting it to tccadmin. Otherwise tccadmin will detect syntax errors and will not function satisfactorily.
The following diagnostics may be issued to the log file:
Can't open command file...
The commands_filename specified in the command line doesn't exist.
Various errors that don't cause tccadmin to fail but are noted in the log file may be caused by improperly formatted commands given at the prompt or in the commands_filename. Please see tccrc(5) for details.
"},{"location":"man/tc/tccadmin/#bugs","title":"BUGS","text":"Report bugs to ion-dtn-support@lists.sourceforge.net
"},{"location":"man/tc/tccadmin/#see-also","title":"SEE ALSO","text":"tcc(1), tccrc(5)
"},{"location":"man/tc/tccrc/","title":"NAME","text":"tccrc - Trusted Collective client configuration commands file
"},{"location":"man/tc/tccrc/#description","title":"DESCRIPTION","text":"TC client configuration commands are passed to tccadmin either in a file of text lines or interactively at tccadmin's command prompt (:). Commands are interpreted line-by line, with exactly one command per line. The formats and effects of the TC client configuration commands are described below.
"},{"location":"man/tc/tccrc/#commands","title":"COMMANDS","text":"?
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 tccadmin 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 withe 1 command to log the version number at startup.
h
The help command. This will display a listing of the commands and their formats. It is the same as the h command.
1 number_of_authorities_in_collective [ K [ R ]]
The initialize command. Until this command is executed, the client daemon for the selected TC application is not in operation on the local ION node and most tccadmin commands will fail.
K is the mandated diffusion for the selected TC application, i.e., the number of blocks into which each bulletin of published TC information is divided for transmission.
R is the mandated redundancy for the selected TC application, i.e., the percentage of blocks issued per bulletin that will be parity blocks rather than extents of the bulletin itself.
i
The info This command will print information about the current state of the client daemon for the selected TC application on the local node, i.e., the identities of the TC authority nodes that the client daemon recognizes.
s
The start command. This command starts the client daemon (tcc) for the selected TC application.
m authority authority_array_index node_number
This command asserts that the Nth member of the collective authority for the selected TC application, where N is the authority_array_index value, is the node identified by node_number.
x
The stop command. This command stops the client daemon (tcc) for the selected TC application.
h
The help command. This will display a listing of the commands and their formats. It is the same as the ? command.
m authority 3 6913
Asserts that node 6913 is member 3 of the collective authority for the selected application.
tccadmin(1)
"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml index 676b24038..b1cb772ec 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -2,1502 +2,1502 @@