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)