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.
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. |
You can use the bundle command to see the status of bundles currently being held by your dtnd. While testing a DTN, you can also inject bundles.
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.
At present there is no way to zero the counters other than by restarting the server.
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.
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.
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.)
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.
You can get help on any of the additional TCL commands in dtnd's TCL interpreter using the help command.
Use the interface commands to add and delete interfaces to the networks that your dtnd will talk on.
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
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.
Syntax: interface del convergence-layer
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.
Syntax: interface list
Prints a list of the current interfaces.
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.
Syntax: log log-path log-level log-string
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.
Syntax: log prefix prefix
The log prefix shows up in log entries after the left bracket, and
before the timestamp. You can set it to any string.
Syntax: 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:
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.
Syntax: 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.
Syntax: storage set variable value
Use the storage command to configure the manner in which
DTN2 will store persistent state like registrations. You may set the
following variables:
Deleting an interface
Example: interface del tcp0
Listing the interfaces
Example: interface list
log
Logging a message of your own
Example: log /dtnd info "dtnd parsing configuration..."
Set the log prefix
Example: log prefix testing
Rotate the log file
Example: log rotate
# 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
Change log level
Example: log reparse_debug_file
storage
Example: storage set type berkeleydb
Variable | Possible settings | Default | Comments |
---|---|---|---|
dbdir | any directory name | /var/dtn/db | The directory where the DB files will be stored. Only used for type BerkeleyDB. |
dbfile | any file name | DTN.db | The file name of the BerkeleyDB database. |
payloaddir | a directory name | /var/dtn/bundles | The directory where bundles in transit will be stored. |
tidy | true, false | false | When true, dtnd cleans out the database and the bundle directories at startup. |
type | berkeleydb, mysql, postgres | berkeleydb | Which database backend will be used. |
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.