twamp-server.conf(5)

📦 version 4.4.6, in nixos 26.05, nixpkgs unstable

🌸 twamp-server.conf(5) — the config file that gives twampd its whole setup 🌸

okay bestie, gather round: this is twamp-server.conf(5), the manual page for the config file behind twampd(8). It’s giving “server settings but make it a text file,” and honestly it’s iconic. 💖

🎀 NAME 🎀

twamp-server.conf — Two-way active measurement daemon configuration file. Periodt.

✨ DESCRIPTION ✨

The twamp-server.conf file is the configuration file for the twampd(8) daemon. It is used to configure the basic operation of the server — for example, what addresses and ports it should listen on, where it should send error messages, and where it should save files.

The policy rules for twampd are configured using the twamp-server.limits file; the details for configuring those policies are described in the twamp-server.limits(5) manual page. Yes, that’s a whole separate bestie — go read it. 🫶

The format of this file is:

  • Comment lines are any line where the first non-whitespace character is #. These lines are counted for the purposes of returning line numbers in error messages but are otherwise ignored by twampd.
  • Lines may be continued using the semi-standard '\' character followed immediately by a newline character. This is the only valid place for the '\' character. If it is found elsewhere, a syntax error is reported.
  • Blank lines are treated as comment lines.
  • All other lines are used to set configuration options. The format of these lines is an initial keyword followed by a variable list of arguments, separated by whitespace.

🫶 CONFIGURATION OPTIONS 🫶

  • authmode 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.
    • 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".

  • controltimeout controltimeout — Number of seconds to wait for protocol messages before timing out.

Default: 900.

  • datadir datadir — Directory path where data files will be placed. The data files are the “receive” session files that are buffered on the server. 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 twamp-server.limits(f) manual page.)

Default: Current directory.

  • dieby dieby — Number of seconds to wait for child processes to gracefully terminate before killing them with SIGKILL. This is in response to the master process receiving SIGTERM or SIGHUP.

This option should no longer be needed. If child processes are not exiting gracefully, please send a bug report to owamp-users@internet2.edu.

Default: 30.

  • diskfudge diskfudge — Fudge factor to use when determining if a buffered owp file should be kept. It creates a hard limit for disk usage. The soft limit is determined by the limitclass that a connection matches [see the twamp-server.limits(5) manual page] and is applied when a test is requested. If the estimated file-size of the test would put the limitclass over the soft limit, then the test is denied. However, it is possible, due to duplicate packets, that a test session file may end up larger than this estimate. If that happens, and if the file is successfully saved to disk, then, upon completion of the test, the actual file-size is used to update the disk usage in the resource broker process. At this point, the hard limit is applied. The hard limit is determined by multiplying the soft limit by the diskfudge. If the final file-size causes the disk space used by the limitclass to be larger than the quota defined by the hard limit then the file is immediately deleted.

A liberal factor is recommended because this factor won’t come in to play unless there are numerous duplicates, and that is precisely the kind of data most users will want to see. However, it is important to have this factor to ensure disk usage is not too vulnerable to replay DOS attacks of the test protocol.)

The valid values for diskfudge are 1.0-10.0.

Default: 1.0 (hard limit is the same as the soft limit).

  • enddelay enddelay — Amount of time for a sender to wait after session completion (last packet send-time plus timeout) before sending the stop sessions message.

This is important if the sender clock is running ahead of the receiver clock.

A session is complete timeout after the send time of the final packet. If the sender clock is ahead of the receiver clock, the sender will declare the session complete before the receiver. The receiver is only allowed to retain records for the packets that were sent at least timeout before it receives the stop sessions message from the sender. Therefore, if the sender clock is running ahead of the receiver clock, the receiver will be forced to delete some number of the final packets from the session.

This parameter directs the sender to wait enddelay after session completion allowing the receiver clock to be essentially enddelay later than the sender clock and still retain full sessions.

Default: 1.0 (seconds).

  • facility facility — Specify the syslog facility to log messages.

Default: LOG_DAEMON.

  • group group — Specifies the gid the twampd process should run as. group can be specified using a valid group name on the system or by using -gid. This option is only used if twampd is started as root.

This option can be useful to limit log-file permissions to only users in this group.

  • loglocation — Directs the twampd process to report source code file and line number information with error messages. This is a particularly useful option to set when sending in messages as part of a bug report.
  • maxcontrolsessions sessions — Specifies the maximum number of control sessions that can be active concurrently. Further connections will be closed until the limit is no longer exceeded.

Default: 0 - unlimited.

  • pbkdf2_count count — This indicates the count parameter for the pseudo-random key derivation function that is used to derive the session key from the long term key stored in the twamp-server.pfs file.

Default: 2048.

  • rootfolly — If present, this disables the requirement that twampd 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 root permissions are only used when explicitly intended.
  • srcnode nodename:port — Specify the address and port that 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 by simply 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 as: [fe80::fe9f:62d8]. This ensures the port number is distinct from the address specification. The address can be wildcarded by only specifying the port portion.

Because the default port for twampd is in the protected range for most operating systems, it is usually required that twampd is started as root. This option can be used to specify a non-standard port value that is not protected.

Default: nodename is wildcarded as any currently available address; port is 862.

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

  • testtimeout testtimeout — Number of seconds to wait for test packets before timing the test session out.

Default: 900.

  • user user — Specifies the uid the twampd process should run as. user can be specified using a valid user name on the system 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 default port 862. (See srcnode 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.

  • vardir vardir — Directory path where the twamp-server.pid and twamp-server.info files will be placed.

Default: Current directory.

  • verbose — If this option is present, it directs the twampd process to generate more verbose messages to syslog.

🌈 SEE ALSO 🌈

twping(1), twampd(8), twamp-server.limits(5), twamp-server.pfs(5), pfstore(1), and 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.

Cute sign-off time, bestie: that’s the whole twamp-server.conf(5) situation — the original footer didn’t hand us a version or date, so we’re ending with accuracy, vibes, and a lil sparkle. Stay slay. 💅💖✨

📦 where this page comes from