The pgipfauth daemon accepts the following command line options: 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: 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:

IP authorization uses the following SQL statement: A sample SQL table and pgipfAuthorize function are worth a thousand words of prose description: Host groups should be setup be creating a table named hostGroup. The table must at least include the following fields: The hdId must be an integral field, and the auto-incrementing SERIAL works nicely. The name field must be a textual type: a CHARACTER VARYING(32) UNIQUE NOT NULL would work equally well. To use host groups, a pgipfAuthorizeWithHostGroup function must be created and the validIPAddress table might be redeclared as The reason an SQL function is used for authorization is quite simply the fact that it affords the greatest amount of flexibility in how the actual lookup should be accomplished. For example, if we wanted to generate some database usage statistics for pgipfauth we could make the following modifications within the database: Each time the database is queried for an IP authorization, the IP, host group, and result of the query is added to the lookupLog table with a timestamp for the request. This data can then be mined for database lookups per minute, etc.

It is quite possible that the following situtation could arise:

1. A user attempts to connect to the IPF host and is blocked since his/her IP is not in the authorization table
2. User adds his/her IP address to the authorization table
3. User attempts to connect again, and is still blocked; user must wait at most the cache TTL for his/her traffic to pass

There are two solutions to this problem: one, drop the cache TTL to a relatively short time (say 30 seconds). Of course, this decreases the usefulness of the cache since an increased number of database lookups will be experienced relative to a longer TTL. The second option is to provide for on-the-fly eviction of IPs from the cache. There are two cache eviction methods available in pgipfauth:

• Evict all lines from the cache
• Evict lines matching a specific IP address

Purging the cache in its entirety is done by passing the USR2 signal to the running instance of pgipfauth. Unless you used the --quiet command line option, you'll see this signal be processed in the program's stdout: To evict specific IP addresses, the addresses must be written (in textual form, separated by whitespace and/or newlines) to a FIFO which pgipfauth opens. By default, this FIFO is available in the etc directory inside the install directory of pgipfauth and is named cache-invalidate. The FIFO must at least be readable by the user under which pgipfauth is running: If I wished to invalidate the two IP addresses observed in the stdout output above: Watching the stdout for pgipfauth: In short, the program written to add or remove IP addresses from the authorization table (through a web interface, etc) should also utilize the selective eviction FIFO to keep the cache in-sync with those database changes. For example, a Postgres trigger function could be written such that any changes to the table are accompanied by the function's writting to the invalidation FIFO: This chunk of code is compiled and linked as a shared object which can be dynamically loaded into Postgres. Within Postgres: Now, when a row is added or deleted or modified in the validIPAddress table, Postgres will automagically write the IP address (or IP addresses, in the case of an UPDATE) to the cache invalidation FIFO! Does it work, though? with the following pgipfauth output: