NAME

bp_admin - ION Bundle Protocol programmatic administration library

SYNOPSIS

#include "bp_admin.h"

int bp_init(void);
int bp_start(void);
void bp_stop(void);
int ipn_init(void);
int add_scheme(char *name, char *fwdCmd, char *admAppCmd);
int remove_scheme(char *name);
int bp_start_scheme(char *name);
void bp_stop_scheme(char *name);
int add_endpoint(char *eid, BpRecvRule recvRule, char *script);
int remove_endpoint(char *eid);
void bp_list_schemes(void);
void bp_list_endpoints(void);
void bp_list_protocols(void);
void report_all_state_stats(void);

int bp_remove_all_endpoints(char *scheme); int bp_remove_all_inducts(char *protocol); int bp_remove_all_outducts(char *protocol); int ipn_remove_all_plans(void);

DESCRIPTION

The bp_admin library provides a set of functions for programmatically configuring and managing an ION (Interplanetary Overlay Network) node's Bundle Protocol (BP) agent. This API serves as an alternative to using the interactive bpadmin(1) command-line utility, allowing applications to automate the setup, control, and monitoring of the BP service.

All functions in this library require that the application first attach to the BP agent by calling bp_attach(3).

NAMING CONVENTION

All public API functions follow snake_case naming (e.g., bp_init(), add_scheme()). This distinguishes them from the private implementation functions which use camelCase (e.g., bpInit(), addScheme()). Applications should only use the public snake_case functions.

FUNCTIONS

System Lifecycle

These functions manage the complete lifecycle of the BP agent and are intended for applications that perform all configuration programmatically.

int bp_init(void)

Initializes the BP database and prepares the node for BP operations. This is one of the first functions that should be called when setting up a node from scratch.

Returns 0 on success, -1 on error.
int bp_start(void)

Starts all BP agent processes, including the bundle expiration clock (bpclock), the main forwarding daemon (bptransit), and all scheme-specific forwarders (e.g., ipnfw) and administrative daemons (e.g., ipnadminep) that have been configured.

Returns 0 on success, -1 on error.
void bp_stop(void)

Stops all running BP agent processes. This function should be called to gracefully shut down the BP service.
int ipn_init(void)

Initializes the database used for IPN (Interplanetary Networking) routing. This is an optional step required only if you intend to configure and use IPN routing plans.

Returns 0 on success, -1 on error.

Scheme Configuration

These functions manage the structural configuration of URI schemes.

int add_scheme(char *name, char *fwdCmd, char *admAppCmd)

Adds a new URI scheme to the BP configuration.
- name is the name of the scheme (e.g., "ipn").
- fwdCmd is the command to start the scheme's forwarder daemon (e.g., "ipnfw").
- admAppCmd is the command to start the scheme's administrative application (e.g., "ipnadminep").
Returns 1 on success, 0 if the scheme already exists, -1 on error.
int remove_scheme(char *name)

Removes an existing scheme. The scheme must not have any registered endpoints or queued bundles. This function will first stop the scheme's daemons before attempting removal.

Returns 1 on success, 0 if the scheme is not found, -1 on error.

Endpoint Configuration

int add_endpoint(char *eid, BpRecvRule recvRule, char *script)

Adds a new endpoint to the BP configuration, registering it under the appropriate scheme.
- eid is the full endpoint ID string (e.g., "ipn:1.2").
- recvRule specifies the behavior when a bundle arrives for an endpoint that is not currently open. It can be EnqueueBundle (the default) or DiscardBundle.
- script is an optional command to be executed when a bundle arrives for an endpoint that is not open. May be NULL.
Returns 1 on success, 0 if the endpoint already exists, -1 on error.
int remove_endpoint(char *eid)

Removes an existing endpoint. The endpoint must not be currently open by any application and must not have any bundles in its delivery queue.

Returns 1 on success, 0 if the endpoint is not found, -1 on error.

Scheme Lifecycle Control

These functions manage the operational state of individual schemes.

int bp_start_scheme(char *name)

Starts the forwarder and administrative daemons for a single, already-configured scheme. This is a safe operation to perform while the main BP agent is running.

Returns 1 on success, 0 if the scheme is not found, -1 on error.
void bp_stop_scheme(char *name)

Stops the daemons for a single scheme. Bundles destined for this scheme will accumulate in its forward queue until it is restarted. This is a safe operation to perform while the main BP agent is running.

Monitoring

void bp_list_schemes(void)

Prints a list of all configured schemes and their current status to standard output. Displays scheme names, code numbers, admin endpoints, and process IDs for forwarder and admin daemons.
void bp_list_endpoints(void)

Prints a list of all registered endpoints and their status to standard output. Shows endpoint IDs, receive rules, application PIDs, and associated scripts.
void bp_list_protocols(void)

Prints a list of all configured convergence-layer protocols to standard output. Displays protocol names and their classes (Scheduled, Unscheduled, or OnDemand).
void report_all_state_stats(void)

Prints a summary of bundle processing statistics to standard output. Includes counts for sourced, received, forwarded, delivered, expired, and other bundle state transitions.

Bulk Removal Functions

These functions remove all items of a specific type. Useful for runtime reconfiguration or selective cleanup without full shutdown.

int bp_remove_all_endpoints(char *scheme)

Remove all endpoints registered under a scheme.

scheme is the scheme name ("ipn" or "dtn").

Endpoints with pending bundles or open applications will be skipped. For complete shutdown, use bp_stop() + ionTerminate(1) instead.

Returns the number of endpoints successfully removed (>= 0), or -1 on fatal error.

Note: This includes the administrative endpoint (e.g., ipn:N.0) that is automatically created when add_scheme() is called.

Example:
```
bp_stop();
int removed = bp_remove_all_endpoints("ipn");
printf("Removed %d endpoints\n", removed);
```
int bp_remove_all_inducts(char *protocol)

Remove all inducts for a protocol.

protocol is the protocol name (e.g., "ltp", "tcp", "udp").

For complete shutdown, use bp_stop() + ionTerminate(1) instead.

Returns the number of inducts successfully removed (>= 0), or -1 on fatal error.

Example:
```
int removed = bp_remove_all_inducts("ltp");
printf("Removed %d LTP inducts\n", removed);
```
int bp_remove_all_outducts(char *protocol)

Remove all outducts for a protocol.

protocol is the protocol name (e.g., "ltp", "tcp", "udp").

Outducts attached to plans will be skipped (remove plans first using ipn_remove_all_plans()). For complete shutdown, use bp_stop() + ionTerminate(1) instead.

Returns the number of outducts successfully removed (>= 0), or -1 on fatal error.

Example:
```
/* Remove plans first, then outducts */
ipn_remove_all_plans();
int removed = bp_remove_all_outducts("ltp");
printf("Removed %d LTP outducts\n", removed);
```
int ipn_remove_all_plans(void)

Remove all IPN egress plans.

Plans with pending bundles in queues will be skipped. For complete shutdown, use bp_stop() + ionTerminate(1) instead.

Returns the number of plans successfully removed (>= 0), or -1 on fatal error.

Example:
```
bp_stop();
int removed = ipn_remove_all_plans();
printf("Removed %d IPN plans\n", removed);
```

OPERATIONAL NOTES

When managing BP schemes, it is critical to distinguish between operations that modify the system's configuration and those that change a scheme's operational state.

Configuration Changes (add/remove)

Functions like add_scheme() and remove_scheme() perform structural configuration changes. They create or permanently destroy a scheme's underlying data structures, such as its forward queue.

WARNING: These operations are not safe to perform while the main BP agent (e.g., bptransit) is running. Doing so can create a race condition where the agent might try to access a data structure that is being deleted, leading to a crash or memory corruption. Scheme configuration changes should ONLY be made when the main BP agent is stopped (i.e., between a call to bp_stop() and bp_start()).

State Changes (start/stop)

Functions like bp_start_scheme() and bp_stop_scheme() are operational state changes designed to be used while the BP agent is running.

bp_stop_scheme() safely terminates a scheme's forwarder process but leaves its data structures intact. The main bptransit daemon can still route bundles to the scheme's forward queue, where they will wait until the scheme is restarted.

bp_start_scheme() starts a scheme's forwarder, allowing it to begin processing its queue. It is the intended method for dynamically activating a scheme without stopping the entire BP node.

RETURN VALUES

Functions that return an integer typically follow this convention:

1 indicates successful completion
0 indicates the operation could not be performed (e.g., item already exists or not found)
-1 indicates a system error occurred

System lifecycle functions (bp_init(), bp_start(), ipn_init()) return 0 on success and -1 on error.

EXAMPLE

#include "bp_admin.h"

/* Initialize and start BP */
if (bp_init() < 0) {
    fprintf(stderr, "Failed to initialize BP\n");
    return -1;
}

/* Add IPN scheme */
if (add_scheme("ipn", "ipnfw", "ipnadminep") < 0) {
    fprintf(stderr, "Failed to add IPN scheme\n");
    return -1;
}

/* Add an endpoint */
if (add_endpoint("ipn:1.1", EnqueueBundle, NULL) < 0) {
    fprintf(stderr, "Failed to add endpoint\n");
    return -1;
}

/* Start the BP agent */
if (bp_start() < 0) {
    fprintf(stderr, "Failed to start BP agent\n");
    return -1;
}

/* Display current configuration */
bp_list_schemes();
bp_list_endpoints();
report_all_state_stats();

COPYRIGHT

AUTHOR

iondev33, JPL