The xvp suite consists of 4 components:
xvp
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® XenServer™. It can be used to gain access to XenServer consoles without having to run XenCenter™, and from any operating system that has a VNC client, not just Windows. xvp itself runs on most recent Linux distributions. By suitable use of VNC passwords, it can provide delegated access to the consoles of particular virtual machines.
xvpviewer
This is a custom Java-based VNC client. It is based on the TightVNC viewer, but with xvp-specific additions to allow clean shutdown and reboot and hard reset to be initiated by clicking buttons on the viewer, and with added support for mouse-wheel scrolling. It has been tested on Linux, Mac OS X, Solaris and Windows.
xvpweb
This is a web-based front end, providing a status view of XenServer pools, hosts and virtual machines, with easy to use facilities to view virtual machine consoles and to boot, shutdown and reboot virtual machines. It makes use of xvp (running on the same machine as the web server) and xvpviewer (supplied in applet form as part of xvpweb). By making use of a database or flat file, it can be made to restrict which users can view and/or manage particular virtual machines or groups of virtual machines. To run xvpweb you need an Apache web server on Linux, and PHP with cURL, mcrypt and PDO support.
xvpdiscover
A small program which can write a configuration file suitable for both xvp and xvpweb. It does this by connecting to one of the XenServer hosts in a XenServer pool, querying the details of the pool, hosts, and virtual machines, and generating a suitable configuration file based on the information it discovers.
These components can also be used with Xen Cloud Platform (XCP), and behave in the same way as when used with XenServer.
Some screenshots (click to enlarge):
|
|
|
|
viewing a Linux VM console on Linux with
xvpviewer |
xvpweb interface for a small XenServer pool - halted |
viewing a Windows VM console |
A separate document describes the XVP Extensions to the RFB Protocol used by xvp and xvpviewer. These extensions are also supported by recent versions of ggivnc.
Before deploying any of the components of the xvp suite, ensure you understand and have addressed the security implications.
Please read the "Security Considerations" section in the README file on this web site (and included in the downloads) for guidelines.
There is a low traffic, moderated mailing list, xvp-users. New versions of the sofware are announced there, and questions, suggestions and general discussion are welcome.
To join the list, visit:
http://list.xvpsource.org/mailman/listinfo/xvp-users/
or send an empty email with subject "subscribe" to:
gro.ecruospvx.tsil@tseuqer-sresu-pvx
You will receive an email in return, to which you must reply to confirm joining, and you'll then receive a second email with your password.
Having joined, you may post to this list, by sending an email to:
As a member, you can also visit the list archive at:
http://list.xvpsource.org/mailman/private/xvp-users/
To unsubscribe from the list, visit:
http://list.xvpsource.org/mailman/listinfo/xvp-users/
or send an empty email with subject "unsubscribe" to:
gro.ecruospvx.tsil@tseuqer-sresu-pvx
To send bug reports, questions or suggestions, please first subscribe to the mailing list, and then post your message there.
Note: All releases prior to 1.3.0 have a security vulnerability in xvpweb: all users of earlier releases of xvpweb are strongly encouraged to upgrade to 1.3.0 or later.
Changes in current release 1.3.4, 19 January 2010:
Details of earlier releases can be found on the Previous Releases Page.
Downloads of current release:
| README | Contains build, install, and configuration information |
|---|---|
| Source Tarball | Buildable on any Linux distribution, includes xvp, xvpconsole and xvpweb |
| Source RPM | Buildable on Red Hat or SUSE based Linux distributions |
| xvp binary RPM | Installable on 64-bit Red Hat Enterprise Linux 5 or CentOS 5 |
| xvpviewer RPM | Installable on Red Hat based Linux distributions |
| xvpviewer ZIP file | Contents runnable on Linux, Mac OS X, Solaris and Windows |
| xvpweb RPM | Installable on Red Hat based Linux distributions |
| Makefile patch for libxenserver | For building libxenserver RPM on Red Hat or SUSE based Linux distributions |
| RPM spec file for libxenserver | For building libxenserver RPM on Red Hat or SUSE based Linux distributions |
To build this software, you must first install the development packages for libxml2, curl, and the the XenServer SDK for C version 5.0.0 or 5.5.0 header files and library (libxenserver). To run it, you just need the corresponding libraries. The SDK can be downloaded from the Citrix Community Web Site.
To build xvpviewer, you need a Java compiler. To run it, you just need the compiled JAR file or class files.
To be able to build without modification, firstly copy your XenServer
SDK header files into /usr/include/xen/api, and the
corresponding built library files into /usr/lib (on 32-bit
systems) or /usr/lib64 (on 64-bit systems).
Download the tar.gz file to a temporary directory, and in a terminal window in that directory, as a normal user, run:
tar xzf xvp-1.3.4.tar.gz cd xvp-1.3.4 make
Then, as user root, in the same directory, run:
make install
This will install the xvp and xvpdiscover executables, Java viewer, and manual pages. To use the xvpweb front end, copy the contents of the web subdirectory to a suitable location in your web server's directory tree.
Now proceed to the configuration section below.
The RPM source package for xvp will allow you to build 3 binary RPMs, for xvp, xvpconsole and xvpweb. The binary xvp package then includes the xvp and xvpviewer executables and manual pages, an init script to stop, start and manage xvp, and a logrotate script.
As a prerequisite, you must first install the curl-devel and libxml2-devel RPMs.
Then you need to build and install libxenserver as an RPM. If you've already installed libxenserver when installing a previous release of xvp, you can skip this step.
Download libxenserver-5.5.0-1-src.tar.bz2 from
the Citrix Community Web
Site.
Download the Makefile patch and the RPM spec file for libxenserver using the links in the Downloads section above.
If using a Red Hat based Linux, then as root,
copy libxenserver-5.5.0-1-src.tar.bz2 and the Makefile
patch into /usr/src/redhat/SOURCES, and the RPM spec
file into /usr/src/redhat/SPECS. If using a SUSE
based Linux, the SOURCES and SPECS
subdirectories are under /usr/src/packages instead:
substitute this in the instructions below.
Run as root:
cd /usr/src/redhat/SOURCES
tar xjf libxenserver-5.5.0-1-src.tar.bz2
mv libxenserver libxenserver-5.5.0
tar cjf libxenserver-5.5.0-1-src.tar.bz2 libxenserver-5.5.0
rm -rf libxenserver-5.5.0
cd ..
rpmbuild -bb SPECS/libxenserver.spec
This will create 3 RPM files
under /usr/src/redhat/RPMS. Install the
libxenserver
and libxenserver-devel ones (you can ignore the
libxenserver-debuginfo one), using rpm
-ivh filename filename.
You can now build and install xvp from RPM. As an alternative, if you wish to install on 64-bit Red Hat Enterprise Linux 5 or CentOS 5, download the xvp binary RPM from the link above, and skips steps 1 and 2 below. There are also pre-built RPMs of xvpviewer and xvpweb.
Download xvp-1.3.4-1.src.rpm using the link in
the Downloads section above, into a temporary directory.
As root, in the same directory, run:
rpmbuild --rebuild xvp-1.3.4-1.src.rpm
This will create several RPM files
under /usr/src/redhat/RPMS. Install
the xvp one (you can ignore
the xvp-debuginfo one), using rpm
-ivh filename, unless you have a previous version
already installed, in which case you should upgrade using rpm
-Uvh filename.
If you are upgrading from a version prior to 1.2.0, any previous
version of xvp already running will be left running, and in this
case you should also run service xvp restart. This is
done automatically if upgrading from 1.2.0 or later.
If you wish to use the supplied Java viewer on Linux, install
the xvpviewer RPM on the relevant machines. You can
install the xvpweb RPM on your web server: the web
front end files are then in the directory
/var/www/html/xvpweb (Red Hat)
or /srv/www/htdocs/xvpweb (SUSE).
Now proceed to the configuration section below.
Refer to the xvp manual page, the xvp.conf manual page, the xvpdiscover manual page and the README for details of command-line options and configuration files.
If you have installed from RPM, and want to run xvp with default
options, you simply need to create the file /etc/xvp.conf
as detailed in the manual page, and then as root run:
service xvp start
To make xvp start every time the system is booted, also run:
chkconfig xvp on
The RPM-based installation reads additional command-line options from
the value of the XVPARGS variable in the
file /etc/sysconfig/xvp, if found. So, for instance, to
provide automatic reconnection to deleted consoles after a 15 second
delay, instead of the default 10 seconds, create this file containing
just the line:
XVPARGS="-r 15"
Refer to the xvpviewer manual page for more information about using the viewer, including how to run it on Windows.
To use the xvpweb front end, you need to configure a web server on the machine that's running xvp. This has been tested using PHP 5.2 running in the Apache 2.2 web server. You will need basic experience of setting up a web server: this is not covered here.
The web server must be configured to run PHP 5 with cURL, mcrypt
and PDO support. It must also be configured to serve files from the
directory you've installed the xvpweb files into (this doesn't have to
be the document root, you can configure your web server to serve it as
any convenient URL). The web server must have access to the xvp.conf
configuration file used by xvp, or a copy of it (the location where
this is looked for is specified in the web file globals.inc, and
defaults to /etc/xvp.conf). For releases of xvpweb prior to 1.3.4,
ensure that in PHP's configuration file
(usually /etc/php.ini), the setting
for short_open_tag is Off (this is not
necessary for version 1.3.4 or later).
When accessing XenServer via the xvpweb front end, users do not need to supply VNC passwords: these are automatically retrieved from xvp.conf by the front end and passed to xvp. However, the front end can restrict which users can view it, and which users can boot virtual machines and view their consoles from it. For instructions on how to configure this feature, refer to the README. See also the manual pages for xvpweb and xvpusers.conf.
If you're running xvp on a Red Hat based Linux distribution, you will
need the httpd, php, php-mcrypt
and php-pdo packages installed and, if you want to use the
web server via HTTPS (recommended if you're restricting users),
the mod_ssl package. On SUSE based distributions, the
prequisite packages are apache2, php5,
php5-curl, php5-mcrypt
and php5-pdo. If you then install the
xvpviewer
RPM, the xvpweb pages will be served (assuming httpd is running)
as the /xvpweb web URL.
If you are using xvpweb, the viewer is included with it as an applet, and launched automatically from the web pages. The users' web browsers must be configured to allow Java to be run.
To help explain how the pieces of xvp fit together, the overall architecture is presented in the diagram to the right (click on it to enlarge). Yellow boxes identify components of the xvp suite and their configuration data. The two dashed vertical lines separate the client tier (left), components which must (as far as the clients are concerned) run on the same server (middle), and backend components (right). You can, if you wish, run the middle tier in a XenServer virtual machine.
By default, and as shown in the above diagram, console connections from xvpweb are made directly to the VNC port(s) on xvp itself. As an alternative, it is possible to tunnel the console connections over the existing HTTP or HTTPS connection, so that, for example, in an Internet-facing environment it is not then necessary to open VNC ports to external access. It is not trivial to set up tunnelling, and it poses its own security risks: for a detailed discussion, see the Tunnelling Guide.
|
Although xvp is (and will continue to be) free software, the project does cost money to run (hardware, software, domain registration and hosting, etc). So if you find the software useful, and would like to make a donation, you can help ensure the continuation of the project. Donations can be made securely using PayPal, by selecting a currency and clicking on the button. Many thanks to those who have already donated to the project. |
|---|
Copyright © 2009-2010 Colin Dean, gro.ecruospvx@niloc
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 and XenServer™ and XenCenter™ trademarks of Citrix Systems, Inc. Linux® is a registered trademark of Linus Torvalds in the U.S. and other countries. Red Hat®, Red Hat Enterprise Linux® and Fedora® are registered trademarks of Red Hat, Inc. openSUSE™ and SUSE™ are trademarks of Novell, Inc. in the United States and other countries. Windows® is a registered trademark of Microsoft Corporation in the United States and other countries. All other relevant trademarks and copyrights acknowledged.
The VNC protocol was originally developed by the RealVNC team while at Olivetti Research Ltd / AT&T Laboratories Cambridge, UK.
The TightVNC versions of all xvp-modified files, and all TightVNC documentation files, are included here renamed as *.tightvnc. For TightVNC copyright information, refer to the file README.tightvnc.
The web-based front end includes "XML-RPC for PHP", Copyright © 1999, 2000, 2002 Edd Dumbill. All rights reserved. The full copyright notice and disclaimer for this can be found in the included file xmlrpc.inc.
A small part of the source code for xvp was based on code supplied in the XenServer C SDK 5.0.0, to which the following copyright statement applies:
Copyright © 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.