owampd(8)

💅 owampd(8) — the one-way latency server, bestie edition 🎀

okay so first things first: this is the manual page for owampd, straight out of the System Manager's Manual, and yeah it's a whole vibe. it's giving "quiet competent daemon that runs the server side of things while you panic about clocks." iykyk.

✨ NAME ✨

owampd — the One-way latency server. that's it, that's the job. 👑

🌸 SYNOPSIS 🌸

owampd [options]

🦋 DESCRIPTION 🦋

owampd is a server program, and it was literally built for exactly one mission: running one side of one-way latency tests. the other side? that's the client program owping, which is a whole separate manual page and a whole separate vibe. 🫶

aside from actually running the tests (the main character energy part), owampd's big job is deciding which tests are allowed — based on the policy restrictions your system administrator configured. so it's a daemon and a bouncer. iconic. 💅

owampd was designed to run as a stand-alone daemon process, and it uses the classic accept/fork model for handling new requests. old school, still slays. ✨

most of the command line options for owampd have analogous options in the owamp-server.conf file — but heads up, the command line takes precedence. so if they disagree, command line wins, no debate. 💀

---

👑 OPTIONS 👑

• -a authmode — tells the server which authentication modes it's willing to use for communication. authmode is a character string made of any or all of the characters "AEO". here's what they mean:
  • 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. important note: this mode forces an encryption step between the fetching of a timestamp and when the packet is sent, which adds more computational delay to the time reported by OWAMP for each packet. 😭 (worth it though)
  • O — [O]pen. no encryption of any kind is done. bold choice. 🙈

the server can specify all the modes with which it's willing to communicate, and the most strict mode that both the server and the client are willing to use gets selected. mutual agreement, we love to see it. 🤝

Default: "AEO"

• -c confdir — specify the directory that holds the owampd configuration files: .conf, .limits and .pfs. that's the whole config trio. 🗂️

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, and they're used to 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 they also determine when each file gets deleted. (see the .limits(5) manual page for the deets.) 💾

Default: Current working directory.

• -e facility — the syslog facility that messages get logged to. 📝

Default: LOG_DAEMON

• -f — disables the requirement that owampd be run with non-root permissions. yes, there are legitimate reasons to run owampd as root, but ngl it's more risky. (for example, some operating systems require root permissions to set some DSCP values requested by a client.) this extra option was added so that root permissions are only ever used when they're explicitly intended. no accidental root era. 🚨
• -G group — specify the gid for the owampd process. group can be given as a valid group name, or by using -gid. this option is only used if owampd is started as root. 🫶

this one's lowkey useful for limiting logfile permissions to only users in this group.

• -h — print a help message. short king. 💖
• -P 0 | lowport-highport — specify the specific port range to use on the local host for OWAMP-Test packets. two ways to do it:
  • first, as 0, which means owampd 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).

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 owampd will listen for requests. nodename can be a DNS name or the textual representation of the address. some cute tricks:
  • you can set just the source address without setting the port, simply by leaving off the ':' and port specification. ✨
  • likewise, you can specify a non-default port for all system addresses (wildcard) by starting the specification string with a ':'.
  • if you're specifying an IPv6 address, note that the accepted format contains nodename in square brackets, like this: [fe80::fe9f:62d8]. that's what keeps the port number 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 given as 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 the -S option.) owampd will release root permissions shortly after binding to this protected port, and requests will be serviced by processes running with the permissions defined by user. so: brief root moment, then it hands over the crown. 👑

• -v — set verbose output. heads up though: 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, and normal terminal controls are available. (i.e., Ctrl+C will cause the daemon to kill its child processes and exit.) super useful for debugging. 🔍

---

🌈 REQUIREMENTS 🌈

owampd requires a very well synchronized and stable clock — like, this is not a drill. owampd requires that NTP be running to synchronize the system clock. and NTP needs to be set up in a more methodical way than on most systems for the results to actually be meaningful. please see the OWAMP web site (http://e2epi.internet2.edu/owamp/) for details concerning proper configuration of NTP for OWAMP. ⏰💖

🍓 ERRORS 🍓

owampd uses syslog to output error messages, including access information. the facility configuration option determines which 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 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 straightforward manner. thoughtful. we stan a considerate design decision. 👏

⭐ 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 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 OWAMP protocol.) 🎬
• SIGUSR2 — used to tell a spawned-off receiver/sender process to terminate a session early. (this is an indication that the StopSessions message was received, for those familiar with the OWAMP protocol.) ✂️

🎀 FILES 🎀

• owamp-server.pid
• owamp-server.conf
• owamp-server.limits
• owamp-server.pfs

🧚 ENVIRONMENT VARIABLES 🧚

OWAMP uses environment variables for some debugging options. here's the one on the list:

• OWAMP_DEBUG_TIMEOFFSET — Offset time by this amount (seconds). 🕰️

🔥 SEE ALSO 🔥

there are more details on configuring the owampd daemon in the owamp-server.conf(5) manual page. details on configuring the policy live in the owamp-server.limits(5) and owamp-server.pfs(5) manual pages. information on the client is in the owping(1) manual page. and 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 🫶 — brought to you by the $Date$ of the owampd(8) manual page. go forth and sync your clocks. 💖🦋🌸⭐👑