Manual entry for xvpusers.conf:
xvpusers.conf (5) xvpusers.conf (5)
NAME
xvpusers.conf - The user configuration file for xvpweb
SYNOPSIS
The xvpusers.conf file is a user rights configuration file for xvp-
web(7), the web based front end for xvp(8). There is also a corre-
sponding relational database schema, also described here. Either may
be used to restrict which users can view and manage particular virtual
machines or groups of virtual machines.
USER AUTHENTICATION AND AUTHORISATION
When accessing XenServer or Xen Cloud Platform virtual machines via the
web-based front end, users do not need to supply VNC passwords: these
are automatically retrieved from xvp.conf(5) by xvpweb(7) and passed to
xvp(8). However, the web interface can restrict which users can view
it, and which users can perform operations such as booting virtual
machines and access their consoles from it.
By default, any user who can access xvpweb has full access to all vir-
tual machines. To enforce per-user access restrictions:
1. The web server must be configured to authenticate users, so that the
variable $_SERVER['REMOTE_USER'] is available to PHP as the user's
name. The user's passwords need to be be checked by the web server
(for example, by using HTTP basic or digest authentication, with pass-
words stored in .htaccess or .htdigest files or in an LDAP directory).
The user names referred to below are the ones passed to PHP by the web
server.
2. Note that the passwords set in xvp.conf(5) are per VM, not per user,
are unrelated to the web server passwords, and do not need to be sup-
plied by users when using the web front end. However, you need to
ensure that the front end and xvp(8) are both looking at either the
same xvp.conf(5) file, or separate ones containing matching VNC and
XenServer passwords.
3. Choose whether to maintain user rights in a text file or in a rela-
tional database. With small numbers of users, or for testing purposes,
a text file is ideal, but with larger numbers of users in a production
environment, using a database such as MySQL, PostgreSQL or SQLite would
probably give better performance.
USING A TEXT FILE
A text configuration file can be used to restrict user rights, by spec-
ifying it in xvp.conf(5) using a line such as:
DATABASE xvp:/etc/xvpusers.conf
The xvpusers.conf file should contain lines of the form:
username:poolname:groupname:vmname:rights
The names of pools, groups and virtual machines should correspond to
those specified in xvp.conf(8). Any value can be wildcarded by speci-
fying it as "*". Note that if virtual machines are listed by UUID
instead of name label in xvp.conf(5), you must use UUIDs here too.
The value for rights can be any one of the following:
none The relevant virtual machine(s) will be invisible and inaccessi-
ble to the user in the web interface.
list The relevant virtual machine(s) will be included in those shown
to the user in the web interface, but the user will not be able
to access their consoles or perform power operations on them.
read The same as for list, except the user will be able to view the
consoles (although not send keyboard or mouse input to them, and
not perform power operations), and view the properties of the
virtual machine(s).
write The same as for read, except the user can send keyboard and
mouse input (but not perform power operations).
control
The same as for write, except the user can perform power opera-
tions that don't specify a particular server host or DVD drive.
all The user can perform all possible operations, including those
that specify particular server hosts (e.g. booting or resuming a
virtual machine on a specific host, including booting in recov-
ery mode, or migrating it to a specific host) or DVD drives
(inserting or ejecting).
If more than one line matches, the one with the most rights takes
precedence. The order lines appear in the file is not important.
For example, to grant all users list rights to all virtual machines in
all pools, and to allow user "fred" to fully control all virtual
machines in the "Web Servers" group of the "Production Pool" pool:
*:*:*:*:list
fred:Production Pool:Web Servers:*:control
Comments can be included in this file using "#".
USING A DATABASE
In order to use a database instead of a text file, the file xvp.conf(5)
must instead contain a DATABASE line of the form:
DATABASE dsn [ username [ password ] ]
where dsn is a DSN for connecting to an authorisation database. The
format of the DSN is as supported by the PDO class in PHP. If needed
to login to the database server, a username should be specified, and
optionally a password (encrypted using the -x option of xvp(8).)
For example, to use a MySQL database named xvpwebusers, on MySQL server
host named mydbserver, the DSN should be:
mysql:host=mydbserver;dbname=xvpwebusers
The database must contain a table named "xvp_users", with a schema of
the form:
CREATE TABLE xvp_users (
username varchar(64) NOT NULL,
poolname varchar(64) NOT NULL,
groupname varchar(64) NOT NULL,
vmname varchar(64) NOT NULL
);
Each record (row) in the table is interpreted in effectively the same
way as each line when using a text file, as described above.
If the database system supports enum types, you may wish to use an
alternative schema:
CREATE TABLE xvp_users (
username varchar(64) NOT NULL,
poolname varchar(64) NOT NULL,
groupname varchar(64) NOT NULL,
vmname varchar(64) NOT NULL,
rights enum('list','read','write','control') NOT NULL
);
This works, for instance, using MySQL, but not using SQLite.
CONTROLLING ACCESS TO SERVER HOSTS
By default, xvpweb(7) shows the names and status of all server hosts in
any pool to which the user has access to one or more VMs. You can hide
the hosts from the user by adding a line to the xvpusers.conf file (or
a corresponding record if using a database), with both groupname and
vmname set to '-', and specifying rights as 'none'. For example:
fred:Production Pool:-:-:none
If you use 'list' instead of 'none', then the hosts are shown, as is
the case if there is no such line at all. Other rights values are cur-
rently treated as equivalent to 'list', but may grant permission to
perform additional operations on hosts in future releases.
OTHER SECURITY CONSIDERATIONS
Before deploying any of the components of the xvp suite, ensure you
understand and have addressed the security implications.
If there is no DATABASE line in xvp.conf(5), then full control of all
virtual machines shown by the web front end is granted to anybody who
can access its web pages via the web server.
It is possible to fine tune the relationship between the rights users
have and the operations they may perform. For instance, to raise the
rights needed to suspend virtual machines, from control to all, or to
lower the rights needed to connect ISO images as virtual DVD drives
from all to control or to write. Refer to the xvprights.conf(5) manual
page for details.
Please read the "Security Considerations" section in the README file,
which is included with the software, and also available on the xvp
project web site at www.xvpsource.org.
CHARACTER ENCODING
Names of pools, hosts, groups and virtual machines may contain non-
ASCII characters, provided they are encoded using UTF-8.
SEE ALSO
xvp.conf(5), xvprights.conf(5), xvp(8), xvpweb(7), xvpdiscover(8),
xvpviewer(1)
AUTHOR
Colin Dean gro.ecruospvx@niloc
COPYRIGHT
Copyright (C) 2009-2011 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), 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.
xvpusers.conf (5) xvpusers.conf (5)