dtnd Configuration

Note that lots of the info that should be on this page has not been written up yet. Please see the to do list for information on how you can help.

At startup, dtnd creates an initializes a TCL interpreter. It then loads and evaluates the contents of the configuration file. For more info on the TCL language, see the TCL homepage.

The name of the configuration file is usually set with the -c argument. If the -c argument is missing, dtnd will try to load /etc/dtn.conf. If that file is not readable, it will try to read daemon/dtn.conf. If that file is not readable, it will log a warning and continue without a configuration file. You may still configure dtnd by hand at the dtn% prompt.

Each of the commands that dtnd handles is described below. These are extensions to the normal TCL command set. You may always use TCL commands and other expressions in your dtn.conf configuration file. For an example of this, search for [info hostname] in the sample daemon/dtn.conf file.

api

Syntax: api set variable value
Example: api set local_addr 10.0.0.1

Use the api command to configure the interface between dtnd and the DTN applications (like dtnping, dtncp, etc). See also environment variables which are used to control the behavior of the API clients.

Variable Possible settings Default Comments
local_addr An IP address or a hostname. 127.0.0.1 The IP address the API Server will listen to for requests from API clients.
local_port An IP port number 5010 The IP port on which the API Server listens for requests from API clients.

bundle

You can use the bundle command to see the status of bundles currently being held by your dtnd.

Syntax: bundle command [id]
Example: storage set type berkeleydb

Use the bundle command to get high level information on the bundle and bundle daemon statistcs,

Command Comments
stats list bundle statistics.
daemon_stats list bundle daemon statistics.
reset_stats reset bundle statistics.
list list all bundle.
ids list all bundle IDs.

While testing a DTN, you can also inject bundles.

Syntax: bundle inject src dest payload opt1=val1, opt2=val2 optN=valN...
Example: bundle inject dtn://source.dtn dtn://dest.dtn payload

Getting bundle and bundle daemon statistics

The bundle stats command shows the following counts:

Pending is the current count of bundles in dtnd's store, which may be non-zero when the server starts if bundles are still in the store from the last time the server was running. All the other counters are zeroed when the server boots. Pending is practically limited by the storage system and the memory use of dtnd. The other counters are unsigned 32-bit integers, and will roll over accordingly.

bundle reset_stats may be used to reset currently maintained statistics.

The bundle daemon_stats command shows the following counts:

Getting a list of pending bundles

The bundle list command shows a list of all pending bundles in the system. It looks like this:

dtn% bundle list
Currently Pending Bundles (2):
        0  : dtn://mars/rover   -> dtn://jpl/images length 8096266
        1  : dtn://jpl/commands -> dtn://mars/rover length 18

To the left of the colon is the bundle ID. This number is used internally by dtnd to keep track of bundles. Remote DTN implementations will never see the bundle ID. However, you can use the bundle ID with the following commands to inspect the bundles.

Looking at a bundle

Using bundle info bundle-id, you can see more information about a bundle. Using bundle dump bundle-id, you can see a hex dump of the bundle. If you know the bundle has only printable characters in it, you can see it formatted as a text file using bundle dump_ascii bundle-id.

Injecting a bundle

Syntax: bundle inject source dest payload [ length ]
Example: bundle inject dtn://jpl/commands dtn://mars/rover "turn left 30 degrees, please"

You can use bundle inject to inject a synthetic bundle into dtnd. It will route and deliver that packet just like any other bundle, as long as it is valid. You have more control over bundles you add using the dtnsend client application, so it is probably almost always a better choice, even for testing situations.

Note: It is currently possible to crash the server using bundle inject with incorrect parameters. Please do not use this command unless you can tolerate a server crash. The crash comes from a failing assert, so the daemon notices the bad bundle, it just cannot proceed with the bad bundle in the store. Once it the bad bundle is in the store, you will need to use the "--tidy" option to remove it and any other pending bundles.

The length parameter is optional. If you inject a bundle without using it, the length of the bundle will simply be the length of the string you pass in as the payload. The length parameter can allow you to make huge bundles without having to use a huge payload string. The payload string is used for at the beginning of the bundle and the remainder of the bundle is filled with zeros. (But there's a bug that makes this not work right. Try dumping out a bundle you made this way to see an assert.)

console

The console command is used spawn interpreter on stdin/stdout, set the console prompt string and set the console listening address and port number.

console cmd

Syntax: console set arg
Example: console set prompt "$shorthostname dtn% "

Variable Possible settings Default Comments
stdio None stdio spawn interpreter on stdin/stdout
addr A.B.C.D 127.0.0.1 console listening address
port number 0 console listening port
prompt string shorthostname [lindex [split [info hostname] .] 0] dtn% console prompt string

debug

The debug command exists in all versions of dtnd, but the subcommands are only available if you gave "--enable-debug-memory" to the configure script while building dtnd. It is not enabled by default. You can tell if your dtnd binary has memory debugging support by running help debug.

When memory use debugging is enabled, you can get a dump of memory in use using debug dump_memory. After doing one dump, you can get diffs with debug dump_memory_diffs.

For information on debugging and configuring logging of the dtn daemon please see the logging section and .dtndebug

discovery

The discovery command is used to configure the abstraction of a neighbor discovery agent. Much like Interface, Discovery is generally created by the configuration file / console. Derived classes (such as IPDiscovery) typically bind to a UDP socket to listen for neighbor beacons. Bluetooth has built-in discovery mechanisms, so BluetoothDiscovery polls via Inquiry instead of listening on a socket.

To advertise a local convergence layer, register its local address (and port) by calling "discovery add". For each registered CL, Discovery will advertise (outbound) the CL's presence to neighbors,and distribute (inbound) each event of neighbor discovery to each CL.

The discovery add command

This command is used to add a discovery agent.

Syntax: discovery add discovery_name cl-type [ args ]

Example: discovery add udp0d ip port=9556

Example : discovery add btd bt

Example: discovery add bonjourd bonjour

Variable Possible settings Comments
discovery_name string A name string to identify the discovery agent
cl-type bt | ip | bonjour The convergence layer type.

args Possible settings Comments
port number Discovery port number if IP based
continue_on_error true or false Whether to continue on an error
addr A.B.C.D IPv4 address of ..
local_addr A.B.C.D IPv4 address of ..
multicast_ttl number Multicast time to live
unicast true or false Whether is unicast

The discovery announce command

This command is used to announce the address of a local interface (convergence layer).

Syntax: discovery announce cl-name discovery_name cl-type [ args ]

Example discovery announce udp0 udp0d udp interval=10

Example discovery announce bt0 btd bt interval=1

args Possible settings Comments
cl_addr A.B.C.D IPv4 address of CL to announce
cl_port number (port) port number of CL to announce

The discovery remove command

This command is used to remove an announcement for a local interface.

Syntax: discovery remove announce discovery_name

Example: discovery remove bt0 btd

The discovery del command

This command is used to delete a discovery agent.

Syntax: discovery del discovery_name

Example: discovery del btd

The discovery list command

This command is used to list agents and their announcement parameters.

Syntax: discovery list

Example: discovery list

ecla

The ecla command is used to control the external convergence layer (ECL) is the gateway between DTN2 and convergence layer adapters (CLAs) running outside of DTN2. Please see ecla for details.

Syntax: ecla command
Example: ecla set create_discovered_links

gettimeofday

The gettimeofday command is used to print the result of gettimeofday() in secs.usecs format.

Syntax: gettimeofday
Example: gettimeofday

help

You can get help on any of the additional TCL commands in dtnd's TCL interpreter using the help command.

Syntax: help command
Example: help interface
Command Comments
bundle print bundle and bundle daemon statistics and interact with the bundle daemon. Also used to examine, dump, expire, cancel and inject bundles.
console set console parameters
debug Command for memory debugging. Only available if "--enable-debug-memory" was given to the configure script.
discovery add, delete and list discovery agent and announce parameters
ecla list and set the external convergence layer adapter parameters
gettimeofday print the result of gettimeofday() in secs.usecs format.
help print the help documentation for cmd.
interface add, delete and list interface parameters.
link add, delete, reconfigure and list link parameters and statistics. Also used to modify default CLA parameters.
log set log and debug file pathname and level and prefix. Also used to rotate log file, reparse rule file and list filter rules.
param set various dtnd daemon parameters and policy.
prophet manipulate the prophet routing protocol. These parameters should be manipulated under the route command interface like other DTN routing algorithms and protocols.
quit shutdown the daemon
registration add, delete and list endpoint (EID) registrations and modify registration logger.
route add, delete, list routes, select and configure routing algorithms/protocols. Can be used to set various route parameters including setting of type, next hop routes, route priority, interaction with discovery, DTLSR parameters, and external route parameters.
shutdown gracefully shutdown the dtnd daemon.
storage set storage backend type, parameters and view statistics.
test Command for developer tests

interface

Use the interface command to add and delete interfaces to the networks that your dtnd will talk on.

Adding an interface

Syntax: interface add interface-name convergence-layer [ args ]


Example: interface add tcp0 tcp

Example: interface add udp0 udp local_host=1.2.3.4 local_port=9999

Example: interface add bt0 bt channel=10

Example: interface add eth string://eth0 beacon_interval=1

Example: interface add null

When dtnd encounters an interface add command, it checks to make sure the named interface has not been created before. Next, it looks for a matching convergence layer. If both of those steps succeed, it passes the remaining arguments to the convergence layer to configure a new interface which will listen for incoming bundles.

The arguments, if they exist, are a list of strings (delimited by "", or {}, according to TCL syntax). Each string starts with the parameter name, then an equal sign ("="), then the value.

See the following pages on the different convergence layers, and what arguments they take.

Deleting an interface

Syntax: interface del convergence-layer
Example: interface del tcp0

Deletes an interface from the system. Each convergence layer handles this individually, but generally the convergence layer stops listening for new bundles and cleans up any resources it was using.

Listing the interfaces

Syntax: interface list
Example: interface list

Prints a list of the current interfaces.

log

The log command deals with the log file, and the log messages in it. You can add messages of your own to the log file, or trigger various actions related to the log file.

Logging a message of your own

Syntax: log log-path log-level log-string
Example: log /dtnd info "dtnd parsing configuration..."

You can use the log command to add a log message to the dtnd log file. The log-path and log-level are used to filter out messages, as described in the section on Logging.

Set the log prefix

Syntax: log prefix prefix
Example: log prefix testing

The log prefix shows up in log entries after the left bracket, and before the timestamp. You can set it to any string.

Rotate the log file

Syntax: log rotate
Example: log rotate

Use this command to force dtnd to reopen the log file for writing. Under Unix, even after you have renamed the log file, dtnd will continue writing log entries into the file until it executes the log rotate command.

You can include a procedure like this in your dtnd.conf file to arrange for dtnd to make a new log file every hour:

# Rotate the log every 3600 seconds (1 hour)
# the initial call to rotate (after the proc) is required to
# start the proc running every hour.
proc rotate {} {
    set date [ clock format [ clock seconds ] -format "%Y-%m-%d-%H" ]
    set new "dtnd.$date.log"
    file rename "dtnd.log" $new

    log rotate

    after 3600000 rotate
}
rotate

Of course, for this to work, you need to start dtnd in the directory where the log file will be, and use the "-o dtnd.log" argument to set the log file name.

Change log level

Syntax: log reparse_debug_file
Example: log reparse_debug_file

The system which dtnd uses to choose which messages to log and which to hide is described in the Logging section of the manual. This command forces dtnd to re-read the .dtndebug file and take into account any new rules that it finds for showing or hiding messages.

param

The param command is used to configure policy parameters.

param set

Syntax: param set arg val
Example: param set link_min_retry_interval 30

arg Possible settings Default Comments
payload_test_no_remove true or false false Whether not to remove bundles (for testing).
early_deletion true or false true Whether to delete forwarded / delivered bundles before they've expired
suppress_duplicates true or false true Whether to not route bundles that are a duplicate of any currently pending bundle
accept_custody true or false true Whether to accept custody when requested
reactive_frag_enabled true or false true Whether reactive fragmentation is enabled
retry_reliable_unacked true or false true Whether to retry unacked transmissions on reliable CLs
test_permuted_delivery true or false false Whether to permute the order of bundles before delivering to registrations.
injected_bundles_in_memory true or false false Whether injected bundles are held in memory by default.
is_singleton_default unknown|singleton|multinode TBC How to set the is_singleton bit for unknown schemes.
glob_unknown_schemes true or false false Whether unknown schemes use glob-based matching for registrations and routes.
link_min_retry_interval number (interval in seconds) TBC Default minimum connection retry interval for links.
link_max_retry_interval number (interval in seconds) TBC Default maximum connection retry interval for links.
custody_timer_min number (seconds) TBC Default value for custody timer min.
custody_timer_lifetime_pct number (per cent) TBC Default value for custody timer lifetime percentage
custody_timer_max number (seconds) TBC Default value for custody timer max.

prophet

The prophet command is used to configure the prophet router. This command should not be here but under route like all other DTN routing protocol and algorithm commands. Please see prophet router for detailed infomation.

quit

The quit command is used to shutdown the DTN2 daemon. It is the same as shutdown.

Syntax: quit
Example: quit

registration

A registration is used to represent an "application" endpoint ID registration, loosely defined to also include internal router mechanisms that consume bundles. Registration state is stored persistently in the database.

The registration command is used add, delete and list EID registrations.

registration add

Syntax: registration add opt endpoint
Example: registration add tcl dtn:alex

opt Possible settings Comments
opt logger or tcl Whether to add a logger or tcl representation
endpoint An EID (URI) The EID which you wish to add a registration for

The logger option is used mostly for testing registrations. When created, this sets up a new registration within the daemon, and for any bundles that arrive, outputs logs of the bundle header fields as well as the payload data (if ascii). The implementation is structured as a thread that blocks (forever) waiting for bundles to arrive on the registration's bundle list, then logging the bundles and looping again. The logpath is set to /dtn/reg/logging/.

registration delete

Syntax: registration del reg_id
Example: registration del 14

registration list

Syntax: registration list
Example: registration list

registration dump_tcl

dump_tcl is used to dump a tcl representation of the registration using its registration id.

Syntax: registration dump_tcl reg_id
Example: registration dump_tcl 14

shutdown

The shutdown command is used to shutdown the DTN2 daemon. It is the same as quit.

Syntax: shutdown
Example: shutdown

storage

Syntax: storage set variable value
Example: storage set type berkeleydb

Use the storage command to configure the manner in which DTN2 will store persistent state like registrations. You may set the following variables:

Variable Possible settings Default Comments
dbdir directory /var/dtn/db The directory where the DB files will be stored. Only used for type BerkeleyDB.
dbfile name DTN.db The file name of the BerkeleyDB database.
payloaddir directory /var/dtn/bundles The directory where bundles in transit will be stored.
payload_quota number (bytes) 0 storage quota for bundle payloads (0 is unlimited).
payload_fd_cache_size number 32 number of payload file descriptors to keep open in a cache.
server_port number (port) 0 TCP port for IPC to external data store.
schema name none File containing the XML schema for the external data store interface.
type berkeleydb, mysql, postgres, filesysdb, memorydb, filesysdb berkeleydb Which database backend will be used.
dbname name DB Set the database name (appended with .db as the filename in berkeleydb, used as-is for SQL variants.
init_db true, false false When true, dtnd initialize the database on startup.
tidy true, false false When true, dtnd cleans out the database and the bundle directories at startup.
tidy_wait number (seconds) 3 How long to wait before really doing a tidy.
leave_clean_file true, false true Leave a .ds_clean file on clean.
fs_fd_cache_size number 0 Number of open fds to cache - if > 0 then this # of open fds will be cached when using Filesystem DB.
db_mpool true, false true Use mpool in Berkeley DB.
db_log true, false true Use logging in Berkeley DB.
db_txn true, false true Use transactions in Berkeley DB.
db_sharefile true, false false Use shared database file in Berkeley DB.
db_max_tx number 0 Max # of active transactions in Berkeley DB.
db_max_locks number 0 Max # of active locks in Berkeley DB.
db_max_lockers number 0 Max # of active locking threads in Berkeley DB.
db_max_lockedobjs number 0 Max # of active locked objects in Berkeley DB.
db_lockdetect number (frequency) 5000 Frequency to check for Berkeley DB deadlocks (zero disables locking).

Storage Notes

Tidy is useful when there are pending bundles in the system that you do not want dtnd to continue to try to deliver. If you allow dtnd to tidy up when it has custody of a bundle, that bundle will be lost for all time and the sending application will not be notified.

For SQL backends, it is not possible at this time to configure a hostname, username, or password via the storage command. For MySQL, the defaults are hostname "localhost", Unix user name, and no password. For Postgres, the defaults are taken from the environment variables described in the PostgreSQL manual.

route

Syntax: route set variable value
Example: route set type static

Use the route command to configure the manner in which DTN2 will route. You may set the following variables:

Variable Possible settings Default Comments
type static, prophet, flood, dtlsr, tca_router, tca_gateway, external static Which routing algorithm to use.
add_nexthop_routes true, false true Whether or not to automatically add routes for next hop links .
add dest link/endpoint [opts] N/A Add a static route
del dest link/endpoint N/A Delete a static route
dump N/A N/A print all of the static routes
open_discovered_links true, false true Whether or not to automatically open discovered opportunistic links.
default_priority number 0 Default priority for new routes.
max_route_to_chain number 10 Maximum number of route_to links to follow.
subscription_timeout number 600 Default timeout for upstream subscription.
dtlsr_area string tbc DTLSR Administrative area for the local node.
dtlsr_weight_fn number 10 DTLSR weight function for the graph.
dtlsr_weight_shift number 0 DTLSR scale factor to scale the weight on down links factor by which to age the cost of a link based on its uptimei. As a link's uptime goes to zero, the cost increases by 10x the original cost.
dtlsr_uptime_factor number 10 DTLSR aging pct for cost of down links.
dtlsr_keep_down_links true or false true DTLSR whether or not to keep down links in the graph, marking them as stale.
dtlsr_recompute_delay number (seconds) 1 DTLSR delay (in seconds) after receiving an LSA when we recompute the routes. Needed to prevent some flapping.
dtlsr_aging_interval number (seconds) 5 DTLSR interval after which we locally recompute the routes to properly age links that we believe to be down.
dtlsr_lsa_interval number (seconds) 3600 DTLSR interval at which we proactively send new LSA. Default is once per hour.
dtlsr_min_lsa_interval number (seconds) 5 DTLSR minimum interval between LSA transmission. Default is once per five seconds.
dtlsr_lsa_lifetime number (seconds) 86400 DTLSR expiration time for lsa announcements (default is 24 hours).
server_port number (port) 8001 UDP port for IPC with external router(s)
hello_interval number (seconds) 30 Seconds between hello messages with external router(s)
schema string (pathname) /router.xsd Location of the external router interface message schema
xml_server_validation true or false true Perform xml validation on plug-in interface messages when using external router(s)
xml_client_validation true or false false Include meta-info in xml messages so plug-in routers can perform validation when using external router(s)

Router Notes

TCARouter is an implementation of the TCA bundle routing algorithm. A TCARouter is a specialized TableBasedRouter where the route table is manipulated in response to certain control bundles (for example, a "register" bundle, or a "change-of-address" bundle). Specialized routing logic is then applied in order to route late-bound bundles addressed to a mobile node, to the mobile's current location in the network. The main interface point is the overridden handle_bundle_received function which tests for the special TCA bundles (control bundles and late-bound data bundles).

link

A link is an abstraction for a DTN link, i.e. a one way communication channel to a next hop node in the DTN overlay. Use the link command to configure the manner in which DTN2 will establish a communications channel to a next hop node. You may set the following variables:

link cmd

Syntax: link cmd name
Example: link delete trinity_od

cmd name Comments
Open String open a link
close String Close a link
delete String Delete a link
state String Get state of a link
stats String Get link statistics

link set_available

Syntax: link set_available name avail
Example: link set_available trinity_od true

Variable Possible settings Default Comments
name String N/A Specify a name of a link
avail true or false true hacky way to make the link available (only used with set_available)

link reconfigure

Syntax: link reconfigure name opt=val opt2=val2 optN=valN
Example: link reconfigure trinity_od mtu=1024 idle_close_time=35

link set_cl_defaults

Syntax: link set_cl_defaults name conv_layer opt=val opt2=val2 optN=valN
Example: link set_cl_defaults trinity_od tcp mtu=1024 idle_close_time=35

link add

Syntax: link add name nexthop type conv_layer opt=val opt2=val2 optN=valN
Example: link add trinity_od 192.168.1.2 ONDEMAND tcp mtu=1024 potential_downtime=25

Variable Possible settings Default Comments
name String N/A Specify a name of a link
nexthop String (address) N/A Specify the next hop node. For IP-based links (tcp or udp), the nexthop should contain a DNS hostname or IP address, followed optionally by a : and a port. If the port is not specified, the default of 4556 is used.
type Link type (see note) ALLWAYSON, ONDEMAND, SCHEDULED, OPPORTUNISTIC Specify the link type
conv_layer udp, tcp, bt, file, eth, norm, null, extcl, serial N/A Specify a Convergence Layer Adapter (CLA)
opt Possible settings Default Comments
mtu number (MTU) Set by link type The MTU of the link, used to control proactive fragmentation.
min_retry_interval number (seconds) Set by link type The minimum amount to wait between attempts to re-open the link. Default is set by the various link types but can be overridden by configuration parameters.
max_retry_interval number (seconds) Set by link type The minimum amount to wait between attempts to re-open the link. Default is set by the various link types but can be overridden by configuration parameters.
idle_close_time number (seconds) 30 for ONDEMAND or 0 for OPPORTUNISTIC & ALLWAYSON Idle time before the link is closed. MUST be zero for always on links (i.e. they are never closed). Default is 30 seconds for on demand links, zero for opportunistic links.
potential_downtime number (seconds) 30 A conservative estimate of the maximum amount of time that the link may be down during 'normal' operation. Used by routing algorithms to determine how long to leave bundles queued on the down link before rerouting them.
prevhop_hdr true or false false Indicates whether or not to send the previous hop header on this link.
cost number (abstract cost) 100 The abstract cost of the link, used by routing algorithms.
qlimit_bundles_high number (bundles) tbc The high limits on the number of bundles that should be queued on the link. The high limits are used to indicate whether or not more bundles can be queued onto the link to effect backpressure from the convergence layers.
qlimit_bundles_low number (bundles) tbc The low limits on the number of bundles that should be queued on the link. The low limits can be used by the router to determine when to re-scan the pending bundle lists.
qlimit_bytes_high number (bytes) tbc The high limits on the number of bytes that should be queued on the link. The high limits are used to indicate whether or not more bundles can be queued onto the link to effect backpressure from the convergence layers.
qlimit_bytes_low number (bytes) tbc The low limits on the number of bytes that should be queued on the link. The low limits can be used by the router to determine when to re-scan the pending bundle lists.
retry_interval number (seconds) min_retry_interval The seconds to wait between attempts to re-open an unavailable link. Initially set to min_retry_interval, then doubles up to max_retry_interval

Link Notes

Links are of types as discussed in the DTN architecture ALWAYSON, ONDEMAND, SCHEDULED, OPPORTUNISTIC. The key differences from an implementation perspective are "who" and "when" manipulates the link state regarding availability.

ONDEMAND links are initializd in the AVAILABLE state, as one would expect. It remains in this state until a router explicitly opens it. An ONDEMAND link can then be closed either due to connection failure or because the link has been idle for too long, both triggered by the convergence layer. If an ONDEMAND link is closed due to connection failure, then the contact manager is notified of this event and periodically tries to re-establish the link.

For OPPORTUNISTIC links the availability state is set by the code which detects that there is a new link available to be used. SCHEDULED links have their availability dictated by the schedule implementation.

All links in the OPEN state have an associated contact that represents an actual connection. Every link has a unique name associated with it which is used to identify it. The name is configured explicitly when the link is created.

Getting link statistics

The link dump command shows the following attributes for all links:

The link dump name command shows the following detailed attributes for a specified link:

The link stats name command shows the following counts for a specified link:

test

The test command is used by developers to test the DTN2 daemon. It is capable of generating a segfault, triggering a panic or false assert.

Syntax: test cmd
Example: test segfault