GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
VHOSTCNAME(1) User Contributed Perl Documentation VHOSTCNAME(1)

vhostcname - synchronize DNS with Apache virtual host configuration

vhostcname [OPTIONS] COMMAND

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;
    }

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.

-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 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.

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.

direvent(8).

Sergey Poznyakoff <gray@gnu.org>

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
2016-07-07 perl v5.32.1

Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.