Manual entry for xvp.conf:
xvp.conf (5) xvp.conf (5)
NAME
xvp.conf - The configuration file for xvp
SYNOPSIS
The xvp.conf file is the configuration file for xvp(8) and its web-
based front end, xvpweb(7). xvp(8) (standing for Xen VNC Proxy) is a
proxy server providing password-protected VNC-based access to the con-
soles of virtual machines hosted on Citrix XenServer. The web-based
front end provides access to all of the features of xvp(8), and its
associated viewer xvpviewer(1), with facilities for restricting which
users can manage particular virtual machines or groups of virtual
machines.
You can write a configuration file by hand, or use xvpdiscover(8) to
generate one for you.
FILE FORMAT
The file should contain a block of keyword-prefixed lines, of the form:
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 hostname
HOST ...
GROUP groupname
VM port vmname encrypted-vnc-password
VM ...
GROUP ...
POOL poolname
...
If a '#' appears on a line, the rest of the line is treated as a com-
ment. Blank lines and additional whitespace may be used to aid read-
ability, 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.
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 xvp(8), but if
present it causes xvpweb(7) to restrict access to the web pages.
dsn 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
xvpusers.conf(5). If needed to login to the database server, a
username may be supplied, and optionally a password (encrypted
using the -x option of xvp(8)).
Instead of using a database via PDO, it is also possible to use
a text file by specifying dsn as xvp:pathname, where pathname is
the full name of the text file, and the file's format is as doc-
umented in xvpusers.conf(5).
OTP REQUIRE|ALLOW|DENY [ IPCHECK ON|OFF ] [ time-window ]
This line is optional, and if present must appear before any
MULTIPLEX or POOL lines. It controls the use of one time pass-
words.
If REQUIRE is specified, VNC clients may only connect using
time-limited one time passwords, as generated by xvpweb(7). If
DENY is specified, only VNC clients using standard permanent
passwords may connect (this therefore excludes xvpweb(7) users).
IF ALLOW is specified (the default), both types of password are
permitted.
The IPCHECK option only affects clients using one time pass-
words, and determines how they may connect to xvp(8). You must
use the same setting for xvp(8) and xvpweb(7), or no xvpweb(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 xvpweb(7) and the time it is received by
xvp(8). The default value is 60.
The behaviour depends on the IPCHECK option:
ON xvp(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 equip-
ment cause the client address as seen by xvpweb(7) for
the HTTP or HTTPS connection to be different from that
seen by xvp(8) for the VNC connection, you must resolve
this discrepancy or use IPCHECK OFF or IPCHECK HTTP.
OFF No check of the client’s IP address is made. This is the
default setting.
HTTP Using this setting forces xvpweb(7) clients to tunnel
their connection to xvp(8) via their existing web server
connection (HTTP or HTTPS), instead of connecting
directly to the VNC port of xvp(8).
MULTIPLEX port
This line is optional, and if present must appear after any
DATABASE or OTP lines, and before any POOL lines. It instructs
xvp(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, xvpviewer(1) and
xvpweb(7)) can access consoles through the multiplexed port.
xvp(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.
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.
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 xvp must be in the same domain as the
XenServer hosts, or the hosts must be specified by IP address,
as described below.
MANAGER username encrypted-xen-password
The login name of the manager account for the XenServer pool
(usually "root"), and password (encrypted using the -x option of
xvp(8)). This is used to securely login to the XenServer
host(s).
HOST hostname
Each host in the pool should be listed here, one per line, with-
out domain suffix. Alternatively, they may be specified by IP
address, but in this case the DOMAIN previously specified must
be empty. If the DOMAIN specified is not empty, it is appended
(with a leading dot) to host names when connecting to them.
When trying to establish a new console connection, xvp 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, xvp will
determine from it which is the master, and use that instead.
Having connected to the master host, xvp will query it to deter-
mine which host is running the virtual machine the client
requires access to, and then establish the console connection
via that host.
GROUP groupname
This keyword line is optional, and is ignored by xvp(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.
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 :0 to :99, 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 char-
acters are significant, previously encrypted using the -e
option. It is a matter of choice whether to use the same pass-
word 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).
SEE ALSO
xvp(8), xvpweb(7), xvpusers.conf(5), xvpdiscover(8), xvpviewer(1)
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.
AUTHOR
Colin Dean gro.ecruospvx@niloc
COPYRIGHT
Copyright (C) 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 MER-
CHANTABILITY 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 xvp(8) and xvpdiscover(8) was based
on code supplied in the XenServer C SDK 5.0.0, to which the following
copyright statement applies:
Copyright (C) 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 WAR-
RANTIES 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 DAM-
AGES 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.
xvp.conf (5) xvp.conf (5)