Manual entry for xvpdiscover:
xvpdiscover (8) xvpdiscover (8)
NAME
xvpdiscover - Discover XenServer hosts and virtual machines
SYNOPSIS
xvpdiscover options
DESCRIPTION
This tool is part of the xvp(8) suite.
xvp (standing for Xen VNC Proxy) is a proxy server providing password-
protected VNC-based access to the consoles of virtual machines hosted
on Citrix(R) XenServer.
The xvpdiscover program can be used to interrogate a XenServer pool,
determine the hosts and virtual machines in the pool, and write an out-
put file in the format of xvp.conf(5), the configuration file for
xvp(8) and xvpweb(7).
If used interactively, xvpdiscover will prompt for common options,
alternatively, all options can be supplied on the command line, allow-
ing it to be used in non-interactive scripts.
OPTIONS
-s server | --server server
The hostname or Internet address of one of the XenServer hosts
in the pool. xvpdiscover will connect to this server to dis-
cover information about the pool. If not supplied, the program
will prompt for this.
-u username | --username username
A valid username to use to connect to the server. This is usu-
ally the administrative account, "root". If not supplied, the
program will prompt for a username.
-x password | --xenpassword password
The XenServer password for the specified user. If supplied on
the command line, this should be in encrypted form, as generated
using the -x option of xvp(8). If not specified, the program
will prompt for the password (without echoing), which in this
case should be supplied in unencrypted form, and must be between
1 and 16 characters long.
-v password | --vncpassword password
A VNC password to be used for all the virtual machines in the
pool. If supplied on the command line, this should be in
encrypted form, as generated using the -e option of xvp(8). If
not specified, the program will prompt for the password (without
echoing), which in this case should be supplied in unencrypted
form, and must be between 1 and 8 characters long. This option
cannot be used in conjunction with the -r option.
-r | --randompasswords
This option cannot be used in conjunction with the -v option.
If used, the program does not prompt for a VNC password: instead
it generates a different 8-character pseudo-random VNC password
for each virtual machine. For a virtual machine with a given
UUID, the same password will be generated each time this program
is run. This option would make no sense to use if you connect
to xvp(8) directly using a VNC viewer such as xvpviewer(1), but
is ideal if all connections are made using the web-based
interface that is available with xvp(8).
-m [ port-number ] | --multiplex [ port-number ]
By default, xvpdiscover(8) writes a configuration file to
instruct xvp(8) to listen on a separate TCP port for each vir-
tual machine. However, if this option is used, it will instruct
it to listen on a single TCP port instead, and to multiplex
clients requiring access to different virtual machine consoles
using this single port. If a port number is not specified, it
defaults to 5900.
If the -m option is specified, the configuration file will not
instruct xvp(8) to listen on dedicated ports for individual vir-
tual machines as well, unless the -p option, described below, is
also specified.
Only clients supporting the XVP security type extension to the
RFB protocol (for example, xvpviewer(1) and xvpweb(7)) can
access consoles through a multiplexed port, but all VNC clients
should be able to connect successfully to dedicated ports.
-p port-number | --portbase port-number
Individual VNC port numbers are automatically generated for all
virtual machines, starting at this base value, and increasing
one by one, unless the -m option is specified. By default, the
base value is 5900, but it only makes sense to use this if the
pool has less than 100 virtual machines with dedicated ports.
In cases where there are more virtual machines, you should sup-
ply a sensible base value such that the port numbers used by
xvp(8) will not clash with those used by other programs: a value
that is often suitable is 50000.
If you specify the -m option, port numbers for dedicated ports
are not generated unless you use the -p option as well. If
using both options, choose the two port numbers so that the port
for any individual virtual machine will not clash with the mul-
tiplex port.
-n | --names
By default, xvpdiscover lists virtual machines in its output
identified by UUID (with name labels as comments). Using this
option forces it to use name labels instead of UUIDs. Both for-
mats are acceptable to xvp(1), refer to xvp.conf(5) for a dis-
cussion of the differences.
-g tagprefix | --grouptag tagprefix
This option allows xvpdiscover to use the GROUP keyword in its
output, to group virtual machines for use with the associated
web interface. If this option is not used, groups are not out-
put: all virtual machines appear in a single alphabetically
sorted list. To make use of this option, you need to have
tagged all the virtual machines you're interested in (e.g. using
XenCenter) with tags that are of the form "tagprefix Group
Name", no more than one such tag per virtual machine. The choice
of prefix is entirely yours, for example you might use tags like
"Group: Web Server" and "Group: Database Server" : in this case,
you would specify the tag prefix as "Group:". Groups are output
in alphabetical order, with virtual machines within each group
also alphabetically sorted by name label, and virtual machines
without a suitable tag are ignored.
-o filename | --output filename
The name of the file to write the configuration to. If not
specified, the program will prompt for a name. To use standard
output, specify as "-".
-f | --force
By default, an output file will not be overwritten if it already
exists. Using this option overrides the restriction.
DIAGNOSTICS
If successful, xvpdiscover exits with a status value of zero. If it
has a problem, it writes a message to standard error and exits immedi-
ately with a non-zero status value.
SUGGESTED USE
Generally, you are recommended not to directly overwrite a configura-
tion file that's in use, without some sort of sanity check that the new
file is correct. If you want your xvp.conf(5) file to be updated regu-
larly and automatically, you might write a script, to be run from
cron(8) every hour or every day. In the script, you could run xvpdis-
cover(8) to a temporary file. If that's identical to the version of
the file currently in use, it would exit, if there were lots of differ-
ences it might make no changes but email you, and if there were a small
number of differences it could overwrite the configuration file in use
and send a SIGUSR1 signal to xvp(8) to cause it to re-read the file.
Note that xvpdiscover(8) does not write a DATABASE or OTP line into the
configuration file: if you need these you must add them afterwards.
EXAMPLES
To write a configuration to a new file /etc/xvp.conf, with one port per
virtual machine, starting at port 5900, with the same password for each
virtual machine, for a pool one of whose XenServer hosts is named
"xen1", and to identify virtual machines by UUID:
xvpdiscover -s xen1 -o /etc/xvp.conf
To do the same, except to use a single multiplex port 5900, to use ran-
dom virtual machine passwords, to identify virtual machines by name
label, and to allow any existing file to be overwritten:
xvpdiscover -r -n -f -m 5900 -s xen1 -o /etc/xvp.conf
In both examples, the program prompts for the XenServer username and
password, and in the first case for the VNC password as well.
SEE ALSO
xvp(8), xvpweb(7), xvp.conf(5), xvpviewer(1), cron(8),
AUTHOR
Colin Dean gro.ecruospvx@niloc
COPYRIGHT
Copyright (C) 2009 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.
xvpdiscover (8) xvpdiscover (8)