pgipfauth 0.1

This document contains information pertinent to the pgipfauth (version 0.1) executable.

The pgipfauth daemon accepts the following command line options:

usage:

/usr/local/pgipfauth/current/bin/pgipfauth {options}

options:

  --help/-h                 this info
  --quiet/-q                don't print anything except critical information
  --annoying/-a             print so much that the sysadmin will go crazy trying to read
                            our log files
  --daemon/-d               run as a daemon (not in the foreground)
  --invalidator/-i [path]   use [path] as the FIFO we should watch for cache invalidation
                            requests; default is /usr/local/pgipfauth/0.1/etc/cache-invalidate
  --config/-c [path]        use [path] as the configuration file; default configuration file
                            is at: /usr/local/pgipfauth/0.1/etc/pgipfauth.conf

signals:

  HUP                 force the daemon to dump its cache, close the database connection,
                      and re-read the configuration file
  USR1                write current info for the cache and database to the daemon's
                      stdout
  USR2                force the daemon to purge its cache
  TERM,ABRT,QUIT,INT  terminate the daemon gracefully

The –daemon option just means that the process forks off a child and exits (the usual daemon behavior). Cache coherency issues and their relation to the USR2 signal and –invalidator CLI option are covered later in this document.

An XML configuration file is used to provide the majority of the startup parameters to the pgipfauth daemon:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pgipfauth-conf PUBLIC "-//UDEL//DTD pgipfauth configuration 1.0//EN"
      "http://metal1.nss.udel.edu/DTDs/pgipfauth-conf_1.0.dtd"
    >
<pgipfauth-conf
      version="1.0"
      authoritative="yes"
      ipf-logging="yes"
      ipf-keep-state="yes"
      ipf-return-reset="yes"
    >
  <database>
    <dbname>ipfauth</dbname>
    <schema>alternate</schema>
    <host-group>FlexLM</host-group>
  </database>
  <cache enabled="yes" size="256" ttl="600" honor-ip-port="no">
    <search method="stateful"/>
    <adaptive enabled="yes" grow-by="64" critical-fraction="0.10"/>
  </cache>
</pgipfauth-conf>

The version attribute MUST be included in the pgipfauth-conf tag; it can also have the following attributes:

• authoritative: whether or not we're to be authoritative in our passing/blocking of IPs
• ipf-logging: whether or not we should always OR the FR_LOG option into the returned packet disposition (as well as FR_LOGFIRST for packets that are not blocked)
• ipf-keep-state: whether or not a PASSed packet should be added to the IPF state table
• ipf-return-reset: whether or not the blocked packet should have a TCP RESET returned to the remote host

In the configuration above, pgipfauth is instructed to return the following dispositions back to IPF:

• For PASS, also set the QUICK, KEEP STATE, and LOG flags in the disposition
• For BLOCK, also set the QUICK, LOG, and RETURN-RST flags in the disposition

The database element provides the connection information pgipfauth needs in order to connect to the database for authorization queries. The following sub-elements are used when connecting to the database:

• host: Database server hostname — honestly, the database should live on the IPF host itself and be accessed via a file socket, so don't even add this element! It's there in case it's needed for testing, etc.
• hostaddr: Database server IP address. Same story as for host — you probably don't need this one. Used if the database host has no DNS name, e.g.
• port: Used in conjunction with host or hostaddr to specify a non-standard TCP port on which the database server is listening
• user: Database user to connect as
• password: Password for the specified database user. Can be an explicit password or a file path from which pgipfauth should read the password. Use the type="inline" attribute for the former and type="external" for the latter.
• dbname: Name of the database to connect to

There are two additional sub-elements that configure the nature of the database queries:

• schema: Use this sub-element if the IP authorization SQL lives in a schema other than public in the database
• host-group: If the database maintains authorization data for multiple systems, then the value of this sub-element is the "name" that identifies only those authorizations meant for this IPF host

The nature of the authorization SQL and host-groups will be covered in the next chapter.

By default, no caching is done by pgipfauth. The cache is configured by the cache element; this element has two attributes:

• enabled: "yes" or "no", default is "no"
• size: initial number of cache lines available
• ttl: the number of seconds a cache line remains valid
• honor-ip-port: "yes" or "no", default is "yes". If "no" then the cache will not store distinct lines for multiple inbound IP ports that are hit from the same remote IP address – in other words, once one IP+inbound port has been PASSed/BLOCKed, the cache will return the same disposition for all inbound ports for that IP.

The honor-ip-port option is available to conserve cache lines in the instance where the inbound port is just not important. An example is the application for which pgipfauth was created: an license daemon that listens on a random TCP/IP port needs a large port range to be "open" but access still needs to be controlled to keep unauthorized users from grabbing licenses. In this case, the connection profile dictates that the TCP/IP port is not integral in authorizing a connection.

A search sub-element specifies which algorithm should be used when searching the cache for an IP. The algorithm is selected by providing the method attribute, which may have the values:

• default: use whatever pgipfauth chooses
• oldest-first: search from the head of the cache (oldest authorizations first)
• newest-first: search from the tail of the cache (most recent authorizations first)
• stateful: search from the cache line that the last search stopped at; the search proceeds simultaneously forward- and backward- through the cache lines from this point

Finally, the adaptive sub-element is used to enable/disable pgipfauth's ability to automatically add more cache lines if the cache is full and the miss ratio reaches some critical value:

• enabled: "yes" or "no", default is "no"
• grow-by: number of cache lines to add
• critical-fraction: A real number between 0 and 1; once the cache is full and this percentage of cache lookups are cache misses, increase the cache size by the value of the grow-by attribute

The configuration file is stored by default in an etc directory inside the install directory of pgipfauth. An alternate configuration can be passed to the daemon by use of the –config command-line option:

% pgipfauth --config /etc/pgipfauth.conf