Internet2

One-Way Ping (OWAMP)

About     |     Downloads      |     Manual Pages     |     Cookbook (PDF)     |     License

owampd.limits(5)                                              owampd.limits(5)



NAME
       owampd.limits - One-way latency server policy configuration file

DESCRIPTION
       The  owampd.limits  file is used to define the policy configuration for
       the owampd program. It allows the system administrator to allocate  the
       resources in a variety of ways.

       There are two parts to the policy configuration:

       Authentication
              Who is making the request? This can be very specific to an indi-
              vidual 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
              owampd allow it to do?

       The authentication is done by assigning a limitclass to each  new  con-
       nection  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.

       Within the owampd.limits file, assign lines are used to assign a limit-
       class  to  a  given connection. limit lines are used to define a limit-
       class 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.

       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
                     owampd.

              ·      Lines  may be continued using the semi-standard ’\’ char-
                     acter followed immediately by a newline. This is the only
                     valid  place  for the ’\’ character. If it is found else-
                     where 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 for-
              mat of the limit directive is:

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

              limitclassname defines the name of the class with the given lim-
              its. Whitespace is used as a separator but is otherwise ignored.
              limitclassname may be used as a directory name component  within
              owampd,  so  take  care  not  to  use  characters  that would be
              invalid. (i.e. ’*’ or ’/’ would be particularly bad.)

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

              limtype           valid values                     default
              -----------------------------------------------------------------
              allow_open_mode   on/off                           on
              bandwidth         integer (bits/sec)               0 (unlimited)
              disk              integer (bytes)                  0 (unlimited)
              delete_on_fetch   on/off                           off
              parent            already defined limitclassname   null

              allow_open_mode
                     This limit is only useful if the class is assigned  to  a
                     netmask.  It is used to limit specific IP/netmask identi-
                     ties to only encrypted or authenticated mode transactions
                     or to allow open mode.

              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 lim-
                     itclass, your root must be unlimited as well as the whole
                     path down to the given limitclass.)

              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.

              delete_on_fetch
                     Indicates that buffered data files  should  be  automati-
                     cally be deleted by the owampd server as soon as they are
                     fetched.

              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.)

       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. lim-
              itclassname  must  have  been  previously defined with the limit
              directive earlier in the file.

              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  net-
                             work.

                     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.

              user user
                     Assign a specific user to a given limitclass.   The  user
                     must be defined in the owampd.pfs file.

AUTHENTICATION PROCESS
       owampd 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 -A option to owping and the
       authmode option in owampd.conf.)  In these modes owampd simply uses the
       identity  of  the connection to determine the limitclass limits. If the
       connection is made in open mode,  then owampd  first  uses  the  source
       address  to  determine  if  owampd 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 owampd.limits file.

EXAMPLES
       An initial limit line might look like:

              limit root with \
                     bandwidth=900m, \
                     disk=2g, \
                     allow_open_mode=off

       This  would create a limitclass named root. Because no parent is speci-
       fied, this must be the first limitclass defined in the file. This  lim-
       itclass  has  very liberal limits (900m limit on bandwidth, and 2 GB of
       disk space). 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
       owampd.pfs file.

       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, \
                     disk=1, \
                     allow_open_mode=off

       This would create a limitclass named jail. Because the limits for band-
       width  and  disk  are  so  low,  virtually  all  tests  will be denied.
       allow_open_mode is off, so initial connections that are not in  authen-
       ticated  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 owampd.pfs file.)

       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, \
                     disk=10m, \
                     allow_open_mode=on

       This  could  be used to allow testing by random connections.  It limits
       those tests to 10 kilobits of bandwidth and 10 Mbytes of buffer  space.

       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.

SEE ALSO
       owping(1),  owampd(8),  owampd.limits(5),  owampd.pfs(5), aespasswd(1),
       and the http://e2epi.internet2.edu/owamp/ web site.

ACKNOWLEDGMENTS
       This material is based in part on work supported by the  National  Sci-
       ence  Foundation (NSF) under Grant No. ANI-0314723. Any opinions, find-
       ings and conclusions or recommendations expressed in this material  are
       those  of the author(s) and do not necessarily reflect the views of the
       NSF.



                                    $Date$                    owampd.limits(5)