twampd(8)

📦 version 4.4.6, in nixos 26.05, nixpkgs unstable

💅 twampd(8) — the system manager's manual page, but make it make sense ✨

okay so real talk, this is twampd(8) from the System Manager's Manual, and it's literally the server side of the two-way latency measurement universe. buckle up bestie 🎀

✨ NAME ✨

twampd — the Two-way active measurement server. she serves. she measures. she's the main character of round-trip latency 🔥

🦋 SYNOPSIS 🦋

twampd [options]

💖 DESCRIPTION 💖

okay so twampd is a server program that lets a client do two-way or round-trip latency measurements. the way it does this is by stamping timestamps right in the reflector, which means it's way more accurate than the other most common round-trip facility, ICMP Echo Request/Reply. no cap, that timestamping is the whole glow-up ✨

besides actually running the tests, the main job of twampd is deciding which tests are allowed, based on the policy restrictions that the system administrator configured. she's the bouncer at the club 🫶

twampd was designed to run as a stand-alone daemon process, and it uses the classic accept/fork model for handling new requests. old school? maybe. iconic? absolutely 👑

most of the command line options for twampd have analogous options in the twamp-server.conf file — but the command line takes precedence, so if they disagree, the CLI wins, periodt 💅

🌸 OPTIONS 🌸

  • -a authmode — specify the authentication modes the server is willing to use for communication. authmode should be a character string containing 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. (heads up though: this mode forces an encryption step between the fetching of a timestamp and when the packet is sent, so it adds more computational delay to the time reported by TWAMP for each packet. worth knowing 💀)
    • O — [O]pen. no encryption of any kind is done. we're all friends here 🙈

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. compromise, but make it secure 💜

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. these data files are the result of one-way latency tests where the server is the receiving host. the data files buffer the data, at least until a client downloads the file. policy restrictions can set how much disk space a given connection can use, and can determine when each file gets deleted. (see the .limits(5) manual page for that.) Default: current working directory.
  • -e facility — the syslog facility that messages get logged to. 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 exists specifically so that root permissions are only used when explicitly intended. be careful with her 😭
  • -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. short and sweet 🎀
  • -P 0 | lowport-highport — specify the specific port range to use on the local host for TWAMP-Test packets. two ways to do it: first, as 0, which means twampd should let the system 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, iykyk) 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 a DNS name or the textual representation of the address. it's possible to set the source address without setting the port, simply by leaving off the ':' and the 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, like: [fe80::fe9f:62d8]. that's so the port number stays 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 the -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. she drops the crown after the entrance, respect 💅
  • -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. Ctrl+C will cause the daemon to kill its 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. that's it. that's the requirement ⭐

🍓 ERRORS 🍓

twampd uses syslog to output error messages, including access information. the facility configuration option determines what syslog facility gets 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 gets 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 straightforward manner. organized queen behavior 👑

🌈 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:

  • 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. 🫶

and that's the whole page bestie — straight out of the System Manager's Manual, twampd(8), no cap, every flag intact 💖 go configure something iconic ✨

📦 where this page comes from