xvp.conf.5

.TH  "XVP.CONF" "5" "21 December 2010" "Colin Dean" "Colin Dean"
.SH NAME
xvp.conf \- The configuration file for xvp

.SH SYNOPSIS
The \fIxvp.conf\fR file is the configuration file for \fBxvp\fR(8) and
its web-based front end, \fBxvpweb\fR(7).  \fBxvp\fR(8) (standing for
Xen VNC Proxy) is a proxy server providing password-protected VNC-based
access to the consoles of virtual machines hosted on Citrix XenServer
and Xen Cloud Platform.  The web-based front end provides access to all
of the features of \fBxvp\fR(8), and its associated viewer
\fBxvpviewer\fR(1), with facilities for restricting which users can
manage particular virtual machines or groups of virtual machines.
.PP
You can write a configuration file by hand, or use \fBxvpdiscover\fR(8)
to generate one for you.

.SH FILE FORMAT
The file should contain a block of keyword-prefixed lines, of the form:
.PP
.nf
    DATABASE dsn [ username [ password ] ]
    OTP REQUIRE|ALLOW|DENY [ IPCHECK ON|OFF|HTTP ] [ time-window ]
    MULTIPLEX port
    POOL poolname
      DOMAIN domainname
      MANAGER username encrypted-xen-password
      HOST [ address ] hostname
      HOST ...
      GROUP groupname
      VM port vmname encrypted-vnc-password
      VM ...
      GROUP ...

    POOL poolname
      ...
.fi
.PP
If a '#' appears on a line, the rest of the line is treated as a
comment.  Blank lines and additional whitespace may be used to aid
readability, provided each keyword line is not split.  The use of double
quotes around names is optional if the name does not contain spaces, or
if it is a poolname or groupname.
.TP
.B DATABASE dsn [ username [ password ] ]
This line is optional, and if present must appear only once, and as the
first keyword line.  It is ignored by \fBxvp\fR(8), but if present it
causes \fBxvpweb\fR(7) to restrict access to the web pages.  \fIdsn\fR
should be a DSN for connecting to an authorisation database.  The format
of the DSN is as supported by the PDO class in PHP, and the required
database schema is described in \fBxvpusers.conf\fR(5).  If needed to
login to the database server, a username may be supplied, and optionally
a password (encrypted using the \fB-x\fR option of \fBxvp\fR(8)).

Instead of using a database via PDO, it is also possible to use a text
file by specifying \fIdsn\fR as \fBxvp:pathname\fR, where \fIpathname\fR
is the full name of the text file, and the file's format is as
documented in \fBxvpusers.conf\fR(5).
.TP
.B OTP REQUIRE|ALLOW|DENY [ IPCHECK ON|OFF|HTTP ] [ time-window ]
This line is optional, and if present must appear before any MULTIPLEX
or POOL lines.  It controls the use of one time passwords.

If REQUIRE is specified, VNC clients may only connect using time-limited
one time passwords, as generated by \fBxvpweb\fR(7).  If DENY is
specified, only VNC clients using standard permanent passwords may
connect (this therefore excludes \fBxvpweb\fR(7) users).  IF ALLOW is
specified (the default), both types of password are permitted.

The IPCHECK option only affects clients using one time passwords, and
determines how they may connect to \fBxvp\fR(8).  You must use the same
setting for \fBxvp\fR(8) and \fBxvpweb\fR(7), or no \fBxvpweb\fR(7)
clients will be allowed access.

The optional time-window is specified in seconds, and can be used to
allow for slight discrepancies between the time the password was issued
by \fBxvpweb\fR(7) and the time it is received by \fBxvp\fR(8).  The
default value is 60.

The behaviour depends on the IPCHECK option:
.RS
.TP
.B ON
\fBxvp\fR(8) will only allow a client access if the password is
consistent with the IP address it has connected from.  Note that if
intervening proxies or other network equipment cause the client address
as seen by \fBxvpweb\fR(7) for the HTTP or HTTPS connection to be
different from that seen by \fBxvp\fR(8) for the VNC connection, you
must resolve this discrepancy or use IPCHECK OFF or IPCHECK HTTP.
.RE
.RS
.TP
.B OFF
No check of the client's IP address is made. This is the default setting.
.RE
.RS
.TP
.B HTTP
Using this setting forces \fBxvpweb\fR(7) clients to tunnel their
connection to \fBxvp\fR(8) via their existing web server connection
(HTTP or HTTPS), instead of connecting directly to the VNC port of
\fBxvp\fR(8).
.RE
.TP
.B MULTIPLEX port
This line is optional, and if present must appear after any DATABASE or
OTP lines, and before any POOL lines.  It instructs \fBxvp\fR(8) to
listen on a single TCP port and to multiplex clients requiring access to
different virtual machine consoles using this single port.  Only clients
supporting the XVP security type extension to the RFB protocol (for
example, \fBxvpviewer\fR(1) and \fBxvpweb\fR(7)) can access consoles
through the multiplexed port.  \fBxvp\fR(8) can support dedicated ports
for particular virtual machines at the same time as a multiplexed port,
if the VM option (as described below) is also used.  All VNC clients
should be able to connect successfully to dedicated ports.
.TP
.B POOL poolname
Declare a XenServer pool.  The name need not match the pool's name as
known to XenServer, but each pool must have a unique name, and the name
may not contain a colon character.
.TP
.B DOMAIN domainname
The Internet domain the pool lives in, e.g. "this.that.com".  This must
be specified, but may be empty (DOMAIN "").  If empty, either the
machine running \fBxvp\fR must be in the same domain as the XenServer
hosts, or the hosts must be specified by IP address, as described below.
.TP
.B MANAGER username encrypted-xen-password
The login name of the manager account for the XenServer pool (usually
"root"), and password (encrypted using the \fB-x\fR option of
\fBxvp\fR(8)).  This is used to securely login to the XenServer host(s).
.TP
.B HOST [ address ] hostname
Each server host in the pool should be listed here, one per line, by
hostname without domain suffix.  If the DOMAIN specified is not empty,
it is appended (with a leading dot) to host names (but not addresses)
when attempting to connect to them.  Optionally, the host's IP address
may be specified as well, to avoid the need for hostname lookups when
connecting to pool hosts.

If the host's name label in the pool is different from its hostname, you
must specify the host's IP address, and specify the name label instead
of the hostname.

When trying to establish a new console connection, \fBxvp\fR will try
each host in turn, in case one or more are down.  If the first one it
successfully logs into isn't the pool master, \fBxvp\fR will determine
from it which is the master, and use that instead.  Having connected to
the master host, \fBxvp\fR will query it to determine which host is
running the virtual machine the client requires access to, and then
establish the console connection via that host.
.TP
.B GROUP groupname
This keyword line is optional, and is ignored by \fBxvp\fR(8).  It can
be used to identify to the web-based front end that the virtual machines
listed below it belong to some common group (e.g. web servers).  The
name may contain spaces.
.TP
.B VM port vmname encrypted-vnc-password
Each virtual machine to which console access is required must be listed
here, one per line.  The port can either be a VNC display number
prefixed by a colon, from \fB:0\fR to \fB:99\fR, corresponding to TCP
ports 5900 to 5999, or an explicit TCP port number, in the range 1024 to
65535.  Take care to avoid port numbers that might clash with other
services: for instance, ports from 6000 upwards are usually used by the
X Window System.  If you have configured a multiplexed port using the
MULTIPLEX option, and do not require an additional dedicated port for a
particular virtual machine, specify the port as "-" on the VM line.

The vmname should be the XenServer name label of the guest VM, or its
XenServer UUID.  The advantage of specifying UUIDs is that you can then
change a VM's name label without having to update the configuration
file.  The disadvantage is that UUIDs aren't easily identifiable
(although you could add the name label or something else meaningful as a
comment).  If the name contains spaces, it must be enclosed in double
quotes.  If you have multiple VMs with the same name label, within the
same pool, you must specify them by UUID.  Alternatively, to provide
console access to a XenServer host, specify vmname as exactly the same
name as already specified on a HOST line.

The password is a VNC password, of which only the first 8 characters are
significant, previously encrypted using the \fB-e\fR option.  It is a
matter of choice whether to use the same password for more than one
virtual machine.  It is this password that the client must supply in
order to access the virtual machine's console (unless using the web-based
front end, which uses its own authorisation database).

.SH "USING MULTIPLE CONFIGURATION FILES"
The configuration file may specify additional ones, by including one or
more lines of the form:
.PP
.nf
    INCLUDE filename
.fi
.PP
An included file is parsed as if it had been pasted into the
original file at that line.  This can be convenient, for instance if you
have multiple pools, and wish to define each pool in a separate file.
Included files may be nested, up to a total depth of 5.  If a filename
contains spaces, it must be enclosed in double quotes.

.SH CHARACTER ENCODING
Names of pools, hosts, groups and virtual machines may contain non-ASCII
characters, provided they are encoded using UTF-8.

.SH "SEE ALSO"
\fBxvp\fR(8),
\fBxvpweb\fR(7),
\fBxvpusers.conf\fR(5),
\fBxvpdiscover\fR(8),
\fBxvpviewer\fR(1)

.SH LIMITATIONS
Within each pool in the configuration file, virtual machine names must
be distinct.  Pool names and group names may contain spaces, but other
items may not.

.SH AUTHOR
Colin Dean <colin@xvpsource.org>

.SH COPYRIGHT
Copyright \(co 2009-2010 Colin Dean

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

Citrix is a registered trademark of Citrix Systems, Inc.

The VNC protocol was originally developed by the RealVNC team while at
Olivetti Research Ltd / AT&T Laboratories Cambridge.

A small part of the source code for \fBxvp\fR(8), \fBxvpdiscover\fR(8)
and \fBxvptag\fR(8) was based on code supplied in the XenServer C SDK
5.0.0, to which the following copyright statement applies:

Copyright \(co 2006-2008 Citrix Systems, Inc.

Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.