twamp-server.limits(5)

📦 version 4.4.6, in nixos 26.05, nixpkgs unstable

💖 NAME 💖

twamp-server.limits — Two-way active measurement server policy configuration file. Also hi bestie, this is twamp-server.limits(5) from the File Formats Manual, and it’s literally the policy config file for twampd. 🫶

✨ DESCRIPTION ✨

Okay so the twamp-server.limits file is where you define the policy configuration for the twampd program. It lets the system administrator allocate resources in a whole bunch of different ways. Very “you get a limit, you get a limit” energy. 💅

There are two parts to the policy configuration:

  • Authentication — who is making the request? This can be very specific to an individual user, or it can be more general in that the connection is coming from some particular network.
  • Authorization — now that the connection has been generally identified, what will twampd allow it to do?

Authentication happens by assigning a limitclass to each new connection as it comes in. Each limitclass has a set of limits associated with it. The limitclasses are hierarchical, so a connection must pass the limit restrictions of the given limitclass as well as all parent classes. It’s giving family-tree rules, honestly. 🌳

Within the twamp-server.limits file, assign lines are used to assign a limitclass to a given connection. limit lines are used to define a limitclass and set the limits associated with that limitclass. The file is read sequentially, and it is not permitted to use a limitclass before it is defined using a limit line. Respect the order, bestie. 😭

The format of this file is:

  • Comment lines are any line where the first non-whitespace character is '#'. These lines are counted to return 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. 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 must conform to the syntax of a limit line or an assign line.

🎀 CONFIGURATION OPTIONS 🎀

🌸 limit

This directive is used to define the limitclass hierarchy. It defines the limitclassname as well as the limits associated with that class. A limitclassname may only be defined once. The format of the limit directive is:

limit limitclassname with limtype=value[,limtype=value]*

limitclassname defines the name of the class with the given limits. Whitespace is used as a separator but is otherwise ignored. limitclassname may be used as a directory name component within twampd, so take care not to use characters that would be invalid. (i.e. '*' or '/' would be particularly bad.) Like, do not name your class * and then act surprised. 🙈

limtype and value indicate the particular type of limit and value to apply to this limitclass. The available settings for limtype are:

  • allow_open_mode — valid values: on/off; default: on.
  • bandwidth — valid values: integer (bits/sec); default: 0 (unlimited).
  • disk — valid values: integer (bytes); default: 0 (unlimited).
  • delete_on_fetch — valid values: on/off; default: off.
  • parent — valid values: already defined limitclassname; default: null.
  • test_sessions — valid values: integer sessions; default: 0 (unlimited).

💫 allow_open_mode

This limit is only useful if the class is assigned to a netmask. It is used to limit specific IP/netmask identities to only encrypted or authenticated mode transactions or to allow open mode. Gatekeeping, but make it network policy. 🚪

🔥 bandwidth

Maximum amount of bandwidth to allow limitclass to use concurrently in all one-way tests. 0 indicates unlimited by policy, but remember this is checked all the way to the root of the hierarchy. (If you want an unlimited limitclass, your root must be unlimited as well as the whole path down to the given limitclass.) No sneaky unlimited leaves on a limited tree, bestie. 🌈

🍓 disk

Maximum amount of disk space to allow a given limitclass to consume. This defines a limit that is used during the authorization of a given test request (this is a soft limit). If the estimated file size for a test request is larger than the disk limit, the test request will be denied. Additionally, because a given test can actually consume more space than this estimate due to duplicate packets, the diskfudge factor is used upon the completion of a test to decide if the file should be kept. If the new file causes the disk space used by a limitclass to be larger than the disk limit multiplied by the diskfudge factor (this defines the hard limit) the file will be deleted. Soft limit says maybe, hard limit says delete. 💀

🦋 delete_on_fetch

Indicates that buffered data files should be automatically be deleted by the twampd server as soon as they are fetched. Fetch it and yeet it. 🧚

⭐ test_sessions

This limits the number of test sessions that can be requested per control session. 0 indicates unlimited by policy, but remember this is checked all the way to the root of the hierarchy. (If you want an unlimited class, your root must be unlimited, and the whole path down to the given class.) Same hierarchy vibe check as bandwidth, no cap. 👑

🌈 parent

The first limit line cannot have a parent since none have been defined yet. As such, the first line defines the root of your class hierarchy. All remaining limit lines MUST assign a parent. (It is hierarchical, after all.) Everybody needs a parent except the root. Periodt. 🌳

💜 assign

The assign directive is used to assign a limitclass to a given connection. Basically, it authenticates the connection. The format of the assign directive is:

assign authtype [args] limitclassname

authtype identifies the type of authentication being used. Whitespace is used as a separator but is otherwise ignored. limitclassname must have been previously defined with the limit directive earlier in the file. Earlier in the file means earlier in the file, bestie. No time travel. ⏳

The available settings for authtype are:

  • default — Used if no other assignment matches. It takes no args.
  • net subnet — Assign a specific subnet to a given limitclass. subnet must be specified using VLSM notation (IP/nbits). The only arg is the subnet. For example:
    • 127.0.0.1/32 — would match only the loopback IPv4 address.
    • ::1/128 — would match only the loopback IPv6 address.
    • 192.168.1.0/24 — would match all hosts on the 192.168.1.XXX network.

There must be no set bits in the non-masked portion of the address part of the subnet specification. i.e., 192.168.1.1/24 would be an invalid subnet due to the bit set in the fourth octet. That fourth-octet bit said “not today.” 😭

  • user user — Assign a specific user to a given limitclass. The user must be defined in the twamp-server.pfs file. If they’re not in the pfs file, they’re not in the group chat. 🫶

🦋 AUTHENTICATION PROCESS 🦋

twampd determines if it should allow a connection from the client based upon the authentication mode of the request and the source IP address of the connection. If the client connection is in authenticated or encrypted mode, the daemon does not do any filtering based upon the source address of the connection. (See the authmode option in twamp-server.conf.) In these modes twampd simply uses the identity of the connection to determine the limitclass limits. If the connection is made in open mode, then twampd first uses the source address to determine if twampd should allow an open mode connection from that subnet at all. (This is the purpose of the allow_open_mode limtype described above.) If open mode is allowed from this subnet, then the limitclass is determined by the closest subnet match defined by the assign net lines in the twamp-server.limits file. Closest match wins, like a subnet-based game of “who wore it best.” 💅

🌸 EXAMPLES 🌸

An initial limit line might look like:

              limit root with \
                     bandwidth=900m, \
                     allow_open_mode=off

This would create a limitclass named root. Because no parent is specified, this must be the first limitclass defined in the file. This limitclass has a very liberal limit for bandwidth (900m). However, open mode authentication is not enabled for this limitclass, so the connections that get these limits must successfully authenticate using an AES key derived from the pass-phrase in the twamp-server.pfs file. Root is generous with bandwidth but strict about the group chat invite. 🔐

If an administrator also wants to create a limitclass that is used to deny all requests, they might add:

              limit jail with \
                     parent=root, \
                     bandwidth=1, \
                     allow_open_mode=off

This would create a limitclass named jail. Because the limit for bandwidth is so low, virtually all tests will be denied. allow_open_mode is off, so initial connections that are not in authenticated or encrypted mode will be dropped immediately. (It would not make much sense to assign a user identity to this limitclass. If you don’t want connections from a particular user identity the best thing to do is to remove that user from the twamp-server.pfs file.) Jail is jail. 💀

If the administrator wanted to allow a limited amount of open tests, they could define a limitclass like:

              limit open with \
                     parent=root, \
                     bandwidth=10k, \
                     allow_open_mode=on

This could be used to allow testing by random connections. It limits those tests to 10 kilobits of bandwidth. Open mode but on a tiny little leash. 🎀

Now, these three limitclasses might be assigned to specific connections in the following ways:

              # default open
              assign default open

              # badguys subnet
              assign net 192.168.1.0/24 jail

              # network admins
              assign user joe root
              assign user jim root
              assign user bob root

This set of assign lines specifically denies access from any open mode connection from the badguys subnet. It specifically allows access to authenticated or encrypted mode transactions that can authenticate as the identities joe jim or bob (even from the badguys subnet). All other connections would match the assign default rule and get the limits associated with the open limitclass. Default catches everyone else, and the badguys subnet is on notice. 👑

🌈 SEE ALSO 🌈

okay bestie, when you're done here and you still have brain cells left (you do, i believe in you 💅), go read these:

ngl, half the flex of knowing this stuff is knowing where to look next. iykyk 🦋

💜 ACKNOWLEDGMENTS 💜

okay so credit where credit is due, because we always give credit 🫶 — this material is based in part on work supported by the National Science Foundation (NSF) under Grant No. ANI-0314723. iconic of them, honestly 👑

and the fine print, which we respect: 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. periodt. that's the disclaimer, and it's staying exactly as serious as it needs to be 💀

and that's a wrap on twamp-server.limits(5) 🎀 you made it to the very last line, which is lowkey just the page name in its little footer fit — twamp-server.limits(5) — no version drama, no extra dates, just vibes and the name. go forth and configure responsibly, bestie 💖✨

📦 where this page comes from