---

4.1.2 File-based Conditions

Most conditional directives take -file and -filewatch options. When specified either option, the argument immediately following it is treated as the name of a file from which to read the list of regular expression patterns or other conditional parameters, depending on the directive. The file is read at startup and cached in memory, so that applying the conditional does not result in disk accesses.

If the -file option is used, the file is read at startup and its contents is remembered for the lifetime of the program. It is an error if the file does not exist. Any errors in the file are treated as configuration file errors and cause immediate program termination.

In the contrast, if the -filewatch option is used, the file is read at startup and a file system monitor is set up to catch its modifications. Once a change to the file is detected, it will be reloaded without interrupting the operation of the server. Consequently, when the -filewatch option is used, it is OK if the file does not exist at startup. Furthermore, any errors in the file contents are reported, but don’t cause program termination.

The support for that option depends on the operating system. On GNU/Linux systems, pound uses inotify kernel API ⁴. On BSD systems (FreeBSD, OpenBSD, NetBSD, Darwin), it uses kqueue⁵. To check which API your pound binary is compiled with, examine the output of pound -V.

Both inotify and kqueue allow pound to react immediately on file system changes. On systems that don’t support either API, pound falls back to periodic checking of file modification time (mtime). In that case, the reload is initiated if mtime changes. The interval between two successive checks is defined by the WatcherTTL statement (see WatcherTTL) and defaults to 60 seconds.

Following is a list of conditional statements that implement file monitoring support: BasicAuth, Header, Host, Path, Query, QueryParam, StringMatch, URL.

See request matching directives, for a detailed discussion of these.