Manual entry for xvpappliance:
xvpappliance (8) xvpappliance (8)
NAME
xvpappliance - Configuration program for xvpappliance
SYNOPSIS
/usr/sbin/xvpappliance
DESCRIPTION
This program is part of the xvp(8) suite, which provides web-based man-
agement of virtual machines running on Citrix Xen Server and/or Xen
Cloud Platform.
The xvpappliance program can be used to manage the configuration of a
self-contained xvpappliance virtual machine. It is currently only sup-
ported in a virtual machine running 64-bit CentOS 5.
It has a simple menu-driven text-based interface.
FIRST TIME CONFIGURATION
The first time the the xvpappliance configuration program is run, the
user is presented with initial configuration questions. These are to
set the appliance root password, timezone, network and email configura-
tion, and to specify the initial set of XenServer and/or Xen Cloud
Platform pools to manage, and to create an initial web user account.
This first time configuration must be run from the appliance's console.
After this is complete, a menu is available from which further configu-
ration can be performed. The menu options are detailed below and,
except where stated otherwise, can be used either from the console or
via an ssh(1) session.
ABOUT THIS PROGRAM
This option displays details of the program's version, and the versions
of all installed xvp-related packages.
CONFIGURE TIMEZONE
This option allows the appliance's timezone to be set: follow the menu
options to pick the closest location. The underlying clock of the VM is
synchronised with the server host's clock, and should not need adjust-
ing.
CONFIGURE NETWORK
This allows the appliance's hostname, IP address, netmask, default
gateway and DNS server settings to be changed. This option must be
used from the appliance's console.
CONFIGURE EMAIL
Using this option, the email address to which notification of available
updates is sent, and the SMTP gateway through which emails are sent,
can be changed. If the gateway requires authentication, the username
and password can be specified here.
CONFIGURE XVP POOLS
This menu option displays a submenu allowing you to list, add and
remove from the set of pools (and/or standalone server hosts) that the
appliance manages.
This submenu item also allows you to rediscover pool details. By
default, although the state of existing VMs is tracked in quasi real
time, the addition and removal of hosts and/or VMs from a pool is not
tracked, so when you make such changes to your pools, the web interface
does not reflect this. There are two ways to update the interface to
reflect these changes: using the submenu option "Rediscover details for
all pools now" to update immediately, and/or the option "Schedule regu-
lar rediscovery of pool details", to enable automatic update every
hour, day, week or month.
Note: Regular rediscovery does not take place until you explicitly use
the schedule option.
CONFIGURE XVP USERS
This option allows you to add and remove web users: to add one, you
will need to give a username (and password, unless using LDAP-based
authentication) and you then set whether the user should have access to
all pools and VMs, or all VMs in a single pool or group, or a single
VM. In addition, you will be asked to set the user’s rights: there are
5 possible settings (List, Read, Write, Control and All), and there is
a Help option which explains exactly what these mean. You also have
the choice of whether the user should be able to see the server hosts,
or whether these should be hidden.
CONFIGURE WEB SERVER
This option allows the web server built into xvpappliance to be config-
ured. It provides a choice of whether web users connecting via HTTP
should be redirected to HTTPs or not, whether VM console VNC connec-
tions should be tunnelled over HTTP/HTTPS or not, and allows re-genera-
tion of a self-signed SSL certificate for HTTPS.
It also allows you to choose whether to authenticate users using an
external LDAP server (e.g. Active Directory), or to use built in user
accounts.
MANAGE SOFTWARE UPDATES
This option allows you to change the schedule of how often new updates
are checked for, and to apply any available updates. There are 2 sorts
of updates: Linux updates (which you should apply for security rea-
sons), and xvp updates (check the website for details of these before
applying).
UNCONFIGURE APPLIANCE
Should you wish to completely unconfigure your appliance, and return it
to its initial state (apart from software updates), use this option.
This will throw away everything you have previously configured, and
reset the root password to "xvpappliance". You can then configure again
from scratch, by rebooting or running /usr/sbin/xvpappliance.
QUIT FROM PROGRAM
This removes any temporary files and terminates the program.
ESCAPING SHELL COMMANDS
Whenever the program presents you with a numbered menu, you can escape
any Linux command by entering it prefixed with "!" instead of entering
a number. When the command completes, the menu is re-displayed.
FILES
/usr/sbin/xvpappliance
The configuration program.
/usr/share/xvp
Directory containing menu files used by the program.
/tmp/xvpappliance.*.*
Temporary files used by the program.
CHARACTER ENCODING
Names of pools, hosts, groups and virtual machines may contain non-
ASCII characters, provided they are encoded using UTF-8. Owing to lim-
itations in the Xen API, non-ASCII characters may not be displayed cor-
rectly on the appliance console, but will be displayed correctly if
using an ssh(1) session, provided the ssh client program is set to use
UTF-8 encoding.
SEE ALSO
xvp(8), xvpdiscover(8), xvpweb(7), xvpviewer(1), ssh(1)
AUTHOR
Colin Dean gro.ecruospvx@niloc
COPYRIGHT
Copyright (C) 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.
xvpviewer(1), which provides access to virtual machine consoles for
xvpappliance, is based on the TightVNC viewer. The TightVNC versions of
all xvp-modified files, and all TightVNC documentation files, are dis-
tributed with xvpviewer, renamed as *.tightvnc. For TightVNC copyright
information, refer to the file README.tightvnc.
The web interface, xvpweb(7) includes "XML-RPC for PHP", Copyright (C)
1999, 2000, 2002 Edd Dumbill. All rights reserved. The full copyright
notice and disclaimer for this can be found in the included file xml-
rpc.inc.
xvpweb(7) also includes the jQuery library, Copyright (C) 2010 The
jQuery Project, and the jQuery Context Menu Plugin, Copyright (C) 2008
A Beautiful Site, LLC. Both are dual-licensed under the GNU General
Public License and the MIT License.
A small part of the source code for xvp(8), xvpdiscover(8) and
xvptag(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.
xvpappliance (8) xvpappliance (8)