twampd(8)
| twampd(8) | System Manager's Manual | twampd(8) |
NAME
twampd - Two-way active measurement server.
SYNOPSIS
twampd [options]
DESCRIPTION
twampd is a server program that allows a client to perform two-way or round-trip latency measurements. The application of timestamps in the reflector enables greater accuracy over the other most common facility for round-trip measurements, ICMP Echo Request/Reply.
Aside from running the tests, the main function of twampd is to determine which tests are allowed, based upon the policy restrictions configured by the system administrator.
twampd 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 twampd have analogous options in the twamp-server.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 connection 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 TWAMP 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 twampd configuration files: .conf, .limits and .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 connection can use, as well as to determine when each file is deleted. (See the .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 twampd be run with non-root permissions. There are legitimate reasons to run twampd as root, but it is more risky. (For example, some operating systems require root permissions to set some DSCP values requested by a client.) This additional option was added to ensure that root permissions are only used when explicitly intended.
- -G group
- Specify the gid for the twampd process. group can be specified using a valid group name or by using -gid. This option is only used if twampd 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 TWAMP-Test packets. This can be specified in two ways. First, as 0 which would indicate twampd 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 .pid file.
- Default:
- Current working directory
- -S nodename:port
- Specify the address and port on which twampd 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 specified, note that the accepted format contains nodename in square brackets, such as: [fe80::fe9f:62d8]. This ensures the port number is distinct from the address specification.
- Default:
- nodename is wildcarded as any currently available address. port is 862.
- -U user
- Specify the uid the twampd process should run as. user can be specified using a valid user name or by using -uid. This option is only used if twampd is started as root.
In the default case, twampd should be started as root so it can bind the protected port 862. (See -S option.) twampd 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 twampd 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., <Cntr-C> will cause the daemon to kill it's child processes and exit.) This is useful for debugging.
REQUIREMENTS
Unlike OWAMP, the TWAMP protocol does not require a well synchronized clock. However, the clock should be stable.
ERRORS
twampd uses syslog to output error messages including access information. The facility configuration option is used to determine what syslog 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 condition.
- 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 twampd 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 twampd process. These signals are caught by the parent daemon and it manages the complete shutdown of all the twampd processes.
- SIGPIPE
- Disabled throughout twampd.
- SIGUSR1
- Used to tell a spawned off receiver/sender process that all control setup interaction is complete and the test can continue at the determined time. (This is an indication that the StartSessions message was received for those familiar with the TWAMP 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 TWAMP protocol.)
FILES
twamp-server.pid
twamp-server.conf
twamp-server.limits
twamp-server.pfs
ENVIRONMENT VARIABLES
twampd uses environment variables for some debugging options.
| Environment Variable | Description |
| OWAMP_DEBUG_TIMEOFFSET | Offset time by this amount (seconds) |
SEE ALSO
There are more details on configuring the twampd daemon in the twamp-server.conf(5) manual page. Details on configuring the policy are in the twamp-server.limits(5) and twamp-server.pfs(5) manual pages. Information on the client is in the twping(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 Science Foundation (NSF) under Grant No. ANI-0314723. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the NSF.