Global settings

jobs N

Define the maximum number of concurrent feed XML retrievals.

Defaults to 10.

persist_dir path

Define the path where crossbow(1) will persist the seen entry identifiers for each monitored feed.

Defaults to ~/.crossbow.

compat v

Declare the compatibility value of the configuration file.

The software execution will fail if the configuration file is found to be marked with a compat value different from the expected, or if the setting is missing. If this happens, the expected compat value is printed on stderr(3). The purpose of this setting is to avoid surprising behaviours after the upgrade to a new release of crossbow(1). See Compatibility Migration for information on how to migrate the configuration to be compatible with the current release.

Feed settings

chdir path

If the feed handler is exec or pipe, execute the subprocess in the given directory.

Defaults to ./

command format-string

If the feed handler is exec or pipe, use format-string as a command template, expanding it into the argument vector of the subprocess.

The template is split on white-space, with the first item being the command to execute and the subsequent items being the arguments. The accepted syntax allows to use printf(3)-like placeholders that are substituted with the fields of the processed entry, so that they can be made available to the subprocess.

Security remark: Doing proper shell escaping against untrusted input is really hard which is why the template is not parsed by means of a shell interpreter. Constructing an interpreted code snippet within a command template (e.g. by invoking ‘sh -c’) is strongly discouraged, as it might result in accidental or malicious code injection.

See crossbow-format(5).

feed name

Declare a new feed.

This setting is special in that it marks the beginning of a feed section in the configuration file. Every settings that follows, up to the next feed section or to the end of file (whichever comes first) will be applied to the declared feed.

The provided name identifies the feed. All feeds must have distinct names. Feed names are forbidden to contain the ‘/’ character.

format format-string

If the feed handler is print, use format-string as a template for the textual representation of each handled feed entry. The template uses the same printf(3)-like syntax as the command setting. See crossbow-format(5).

This setting is optional: if not provided, the print handler will use the default representation.

handler handler

Use the selected handler to process new feed entries. The handler argument must be one of the following:

print

Print a textual representation of each new entry to stdout(3). A custom template can optionally be defined by specifying a format setting.

This is the default handler for feeds that do not define one.

exec

Handle new entries by means of a subprocess. This handler requires the command setting to be defined.

pipe

Like exec, but the content (corresponding to the ‘%c’ placeholder, see crossbow-format(5)) is also made available to the subprocess by means of a pipe(2), This handler requires the command setting to be defined.

inherit group

Inherit settings from a previously defined group named group. By specifying inherit multiple times it is possible to inherit from multiple groups. In case of clash, the settings from the last inherited group take precedence. Settings specified within the feed section take precedence over those inherited by any group.

url URL

Define the URL of the feed XML.

The allowed remote protocols are HTTP, HTTPS, and Gopher (using the ‘http://’, ‘https://’ and ‘gopher://’ URL schemas respectively). Local file-system access (using ‘file://’)is possible too. HTTPS is the default protocol when no schema is specified.

This setting must be defined for each feed.

Group settings

Here follows a list of settings that can be specified for a group. The meaning is the same as defined above for feeds.

• chdir path
• command format-string
• format format-string
• handler handler

Compatibility Migration

This section explains how to migrate the configuration from compat value 0 to 1. By compat value 0 here we mean a configuration compatible with crossbow(1) 3.0.0, although versions before 4.0.0 do not recognize any versioning information in the configuration file.

Concerning the format strings (See crossbow-format(5)):

• The following placeholders are no longer available: ‘%cm’ (‘contributor email’), ‘%cr’ (‘rights’), ‘%ct’ (‘rights type’), ‘%cu’ (‘contributor uri’), ‘%d’ (‘summary’ / ‘content’), ‘%dt’ (‘summary type’ / ‘content type’), ‘%el’ (‘enclosure length’), ‘%en’ (‘enclosure’), ‘%et’ (‘enclosure type’), ‘%eu’ (‘enclosure url’), ‘%sr’ (‘source’), ‘%su’ (‘source url’), ‘%tt’ (‘title type’).
• ‘%c’ (‘contributor name’) has been redefined as ‘content’.
• The following placeholders have been added: ‘%ca’ (‘category’), ‘%s’ (‘summary’).

Furthermore, care should be taken concerning the use of the pipe handler, since the new implementation takes advantage of the ‘<content:encoded>’ element (extension of RSS). ‘<content:encoded>’ is preferable to ‘<content>’ because it is more likely to contain full article, but as a drawback it might turn out to be HTML-encoded.