Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
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:

	   Scan	the apache configuration files and register all	server names
	   that	match the configured zones.

	   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.

	   Deregister all hostnames registered previously, rescan Apache
	   files, and register all names that match the	configured zones.

	   Displays registered host names.

       -c, --config=FILE
	   Read	configuration from FILE	instead	of the default location

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

	   Displays vhostcname man page.

       -h  Displays a short help summary and exits.

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

       The following sections are recognized:

	   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

		   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

	   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

		   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

	   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

       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.


       Sergey Poznyakoff <>

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

       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

perl v5.32.1			  2016-07-07			 VHOSTCNAME(1)


Want to link to this manual page? Use this URL:

home | help