NAME

vhostcname - synchronize DNS with Apache virtual host configuration

SYNOPSIS

vhostcname [OPTIONS] COMMAND

DESCRIPTION

The program takes a list of DNS zones and scans Apache virtual host configuration files. For each hostname found in ServerName and ServerAlias statements, it checks whether this name ends in a zone from the list, and if so, attempts to register this hostname using the DNS dynamic updates mechanism (RFC 2136). For each such name a CNAME record is created, pointing to the name of the system's host. The program will refuse to update the hostname if a CNAME record already exists and points to another host.

A reverse operation is also supported: deregister all host names registered during the previous run.

The mode of operation is requested by the COMMAND argument. The available COMMANDs have been chosen so as to allow vhostcname to be run as one of the machine's startup scripts. The exact ways to register it to be run on server startup and shutdown depend on the operating system and distribution in use. For example, on Debian-based GNU/Linux:

    cd /etc/init.d
    ln -sf /usr/bin/vhostcname /etc/init.d
    update-rc.d vhostcname defaults

The program can also be used as a direvent(8) handler. This use allows for immediate updates of the DNS records upon any modifications to the Apache configuration files. The following example shows the corresponding direvent.conf(5) entry:

    watcher {
        path /etc/apache2/sites-available;
        path /etc/apache2/sites-enabled;
        event (create,delete,write);
        timeout 10;
        option (stderr,stdout);
        command /usr/bin/vhostcname;
    }

COMMANDS

Unless the program is started as a direvent(8) handler, exactly one command must be given in the command line. A command may be supplied in full or abbreviated form. Any unambiguous abbreviation is allowed.

Available commands are:

start: Scan the apache configuration files and register all server names that match the configured zones.
stop: Deregister all hostnames registered previously.
restart, reload: Builds a list of names from the apache configuration (apache-list) and compares them with the names registered at the previous run (cache). If the two lists differ, the names present in apache-list, but absent in cache are registered. The names present in cache, but lacking in apache-list are deleted from the DNS.
force-restart: Deregister all hostnames registered previously, rescan Apache files, and register all names that match the configured zones.
status: Displays registered host names.

OPTIONS

-c, --config=FILE: Read configuration from FILE instead of the default location (/etc/vhostcname.conf).
-d, --debug: Increases the debug level. Multiple -d options are allowed.
-n, --dry-run,: Enables dry-run mode: print what would have been done without actually doing it.
--help: Displays vhostcname man page.
-h: Displays a short help summary and exits.
--usage: Displays a short command line syntax reminder.

CONFIGURATION FILE

Configuration is read from /etc/vhostcname.conf or a file specified by the --config (-c) command line option. The file consists of a number of variable assignments (variable = value), grouped into sections. Whitespace is ignored, except that it serves to separate input tokens. However, value is read verbatim, including eventual whitespace characters that can appear within it.

A section begins with the line containing its name within square brackets (e.g. [core]). The name can be followed by one or more arguments, if the section semantics requires so (e.g. [zone example.com]).

The following sections are recognized:

[core]

apache-config-directory = DIR: Sets the Apache configuration directory. DIR should be either a directory where virtual configuration file are located or a directory which hosts the sites-available and sites-enabled directories. In the latter case, vhostcname will look for files matching apache-config-pattern in DIR/sites-enabled.
If this option is not given, vhostcname will try to deduce where the configuration files are located. It will issue a warning message and terminate if unable to do that.
apache-config-pattern = PATTERN: Shell globbing pattern for virtual host configuration files. By default, * is used, meaning that vhostcname will scan all files in the configuration directory (note: that includes backup copies too!).
cache = FILE: Name of the cache file where vhostcname keeps successfully registered host names. Default is /var/run/vhostcname.cache.
hostname = HOSTNAME: Sets the target hostname. This name will be used at the right side of CNAME records created. Defaults to the system's hostname.
allow-wildcards = BOOL: Allow the use of wildcard (*) in host names. When this option is in effect, a wildcard will be allowed if it is the very first label in a domain name and it is separated from the base zone (see the zone section) by one more labels.
BOOL is one of yes, true, t, on, or 1 to allow wildcards, or one of no, false, f, nil, off, 0 to disallow them (the default).

The following variables provide defaults for zones that lack the corresponding settings:

server = HOST: Name of the DNS server to use. Normally vhostcname determines what server to use based on the SOA record of the zone to be updated, so this option is rarely needed.
ttl = SECONDS: TTL value for new DNS records. Default is 3600.
ns-key = NAME=HASH: Defines the TSIG key.
ns-key-file = FILE: Name of the key file. The argument should be the name of a file generated by the dnssec-keygen utility. Either .key or .private file can be used.
If both ns-key and ns-key-file are used, the latter is given preference.

[zone NAME]: The zone section informs vhostcname that it should handle names in zone NAME. Any number of [zone] sections can be defined. If none is defined, vhostcname will use the name of the host it runs on as the name of the zone to update.
The variables in a zone section define parameters to be used for that particular zone. As such, none of them is mandatory. If the zone NAME uses default settings (or settings, defined in the [core] section), the section can be empty.

server = HOST: Name of the DNS server to use when updating this zone.
ttl = SECONDS: TTL for records in this zone.
ns-key = NAME=HASH: TSIG key.
ns-key-file = FILE: Name of the key file. The argument should be the name of a file generated by the dnssec-keygen utility. Either .key or .private file can be used.
If both ns-key and ns-key-file are used, the latter is given preference.
hostnames = NAME [NAME...]: Define immutable hostnames. Each NAME will be registered unconditionally.

EXIT CODE

0: Success
1: Some of the host names could not be updated.
64: Command line usage error.
66: Required input file cannot be opened.
73: Required output file cannot be created or written.
78: Configuration error.

AUTHOR

Sergey Poznyakoff <gray@gnu.org>

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 1036:: Expected text after =item, not a number
Around line 1040:: Expected text after =item, not a number
Around line 1044:: Expected text after =item, not a number
Around line 1048:: Expected text after =item, not a number
Around line 1052:: Expected text after =item, not a number