owampd(8) owampd(8)
NAME
owampd - One-way latency server.
SYNOPSIS
owampd [options]
DESCRIPTION
owampd is a server program specifically designed to run one side of
one-way latency tests. The client program owping is available to run
the other side of the test.
Aside from actually running the tests, the main function of owampd is
to determine which tests are allowed, based upon the policy restric-
tions configured by the system administrator.
owampd was designed to be run as a stand-alone daemon process. It uses
the classic accept/fork model of handling new requests.
Most of the command line options for owampd have analogous options in
the owampd.conf file. The command line takes precedence.
OPTIONS
-a authmode
Specify the authentication modes the server is willing to use
for communication. authmode should be set as a character string
with any or all of the characters "AEO". The modes are:
A [A]uthenticated. This mode encrypts the control connec-
tion and encrypts part of each test packet.
E [E]ncrypted. This mode encrypts the control connection
and encrypts each test packet in full. (This mode forces
an encryption step between the fetching of a timestamp
and when the packet is sent. This adds more computational
delay to the time reported by OWAMP for each packet.)
O [O]pen. No encryption of any kind is done.
The server can specify all the modes with which it is willing to
communicate. The most strict mode that both the server and the
client are willing to use will be selected.
Default:
"AEO".
-c confdir
Specify the directory that holds the owampd configuration files:
owampd.conf, owampd.limits and owampd.pfs.
Default:
Current working directory.
-d datadir
Specify the directory that holds the buffered data files. The
data files are the result of one-way latency tests where the
server is the receiving host. The data files are used to buffer
the data, at least until a client downloads the file. Policy
restrictions can be used to set how much disk space a given con-
nection can use, as well as to determine when each file is
deleted. (See the owampd.limits(5) manual page.)
Default:
Current working directory.
-e facility
Syslog facility to which messages are logged.
Default:
LOG_DAEMON
-f Disables the requirement that owampd be run with non-root per-
missions. There are legitimate reasons to run owampd as root,
but it is more risky. (For example, some operating systems
require root permissions to set the TOS bits used by the -D
option of owping.) This additional option was added to ensure
that root permissions are only used when explicitly intended.
-G group
Specify the gid for the owampd process. group can be specified
using a valid group name or by using -gid. This option is only
used if owampd is started as root.
This option can be useful to limit logfile permissions to only
users in this group.
-h Print a help message.
-P 0 | lowport-highport
Specify the specific port range to use on the local host for
OWAMP-Test packets. This can be specified in two ways. First, as
0 which would indicate owampd should allow the system to pick
the port (ephemeral). Second, as a range: lowport must be a
smaller value than highport and both numbers must be valid port
values. (16 bit unsigned integer values)
Default:
0
-R vardir
Specify the directory to hold the owampd.pid file.
Default:
Current working directory
-S nodename:port
Specify the address and port on which owampd will listen for
requests. nodename can be specified using a DNS name or using
the textual representation of the address. It is possible to set
the source address, without setting the port, simply by leaving
off the ’:’ and port specification. Likewise, a non-default port
can be specified for all system addresses (wildcard) by starting
the specification string with a ’:’. If an IPv6 address is spec-
ified, note that the accepted format contains nodename in square
brackets, such as: [fe80::fe9f:62d8]. This ensures the port num-
ber is distinct from the address specification.
Default:
nodename is wildcarded as any currently available
address. port is 861.
-U user
Specify the uid the owampd process should run as. user can be
specified using a valid user name or by using -uid. This option
is only used if owampd is started as root.
In the default case, owampd should be started as root so it can
bind the protected port 861. (See -S option.) owampd will
release root permissions shortly after binding to this protected
port and requests will be serviced by processes running with
permissions defined by the user.
-v Set verbose output. Messages will still only go to syslog unless
the -Z option is specified.
-Z Run the master owampd process in the foreground. In this mode,
error messages are printed to STDERR as well as being sent to
syslog. Also, normal terminal controls are available. (i.e.,
will cause the daemon to kill it’s child processes and
exit.) This is useful for debugging.
REQUIREMENTS
The owampd daemon requires a very well synchronized and stable clock.
owampd requires that NTP be running to synchronize the system clock.
NTP needs to be setup in a more methodical way than on most systems for
the results to be meaningful. Please see the OWAMP web site
(http://e2epi.internet2.edu/owamp/) for details concerning proper con-
figuration of NTP for OWAMP.
ERRORS
owampd uses syslog to output error messages including access informa-
tion. The facility configuration option is used to determine what sys-
log facility is used. The levels used are as follows:
LOG_ERR
Used for messages indicating fatal errors. The requested action
will not be performed.
LOG_WARNING
Used for messages indicating an unexpected or dangerous condi-
tion.
LOG_INFO
Used for access messages.
LOG_DEBUG
Used to indicate reasons for actions. For example, if an access
is denied due to policy choices that will be noted with this log
level.
These levels were chosen to give the system-administrator the ability
to separate access log information from error log information in a
straight forward manner.
SIGNALS
The owampd process makes use of a number of signals to perform IPC
between the various processes involved:
SIGALRM
Used throughout to set timers where appropriate.
SIGCHLD
Used to keep track of the state of child processes.
SIGINT
SIGTERM
SIGHUP Used to terminate any owampd process. These signals are caught
by the parent daemon and it manages the complete shutdown of all
the owampd processes.
SIGPIPE
Disabled throughout owampd.
SIGUSR1
Used to tell a spawned off receiver/sender process that all con-
trol setup interaction is complete and the test can continue at
the determined time. (This is an indication that the StartSes-
sions message was received for those familiar with the OWAMP
protocol.)
SIGUSR2
Used to tell a spawned off receiver/sender process to terminate
a session early. (This is an indication that a StopSessions
message was received for those familiar with the OWAMP proto-
col.)
FILES
owampd.pid
owampd.conf
owampd.limits
owampd.pfs
ENVIRONMENT VARIABLES
OWAMP uses environment variables for some debugging options.
OWAMP Environment Variable Description
------------------------------------------------------------------
OWAMP_DEBUG_TIMEOFFSET Offset time by this amount (seconds)
SEE ALSO
There are more details on configuring the owampd daemon in the
owampd.conf(5) manual page. Details on configuring the policy are in
the owampd.limits(5) and owampd.pfs(5) manual pages. Information on
the client is in the owping(1) manual page. For more of an overview of
the full functionality and architecture, see the
http://e2epi.internet2.edu/owamp/ web site.
ACKNOWLEDGMENTS
This material is based in part on work supported by the National Sci-
ence Foundation (NSF) under Grant No. ANI-0314723. Any opinions, find-
ings and conclusions or recommendations expressed in this material are
those of the author(s) and do not necessarily reflect the views of the
NSF.
$Date$ owampd(8)
