freeVSD User's Guide
====================

Contents
========

1.  Introduction
2.  System Requirements
3.	Installing freeVSD
	3.1. Installing freeVSD from RPMs
	3.2. Installing freeVSD with OpenSSL 
	3.3. Installing freeVSD from Source
	3.4. Completing the Installation
4.  Uninstalling freeVSD
5.	Setting Up a Virtual Server
	5.1. Setting Up Virtual Servers Without Changing Configurations
		 5.1.1.	Creating a Virtual Server
		 5.1.2.	Starting a Virtual Server		 
	5.2. Setting Up Virtual Servers and Changing Configurations
		 5.2.1. Overview of the 'skel'
		 5.2.2. Changing Configurations in the 'vsd.conf' Configuration file
		 5.2.3. Changing Configurations in the 'Workings.txt' File
		 5.2.4.	Creating the 'skel'
		 5.2.5.	Creating a Virtual Server
		 5.2.6.	Starting a Virtual Server
	5.3	 Setting Up a Virtual Server with Certificate Authority
6.	Starting and Stopping Accounts
7.	Setting a Password for the Admin User
8.	Accessing a Virtual Server
9.	Deleting a Virtual Server
10. Administering Accounts as the Admin User
	10.1. Setting Access Control Privileges
	10.2. Listing Access Privileges
	10.3. Displaying Quota Statistics
	10.4. Setting User Quotas
	10.5. Rebooting a Virtual Server


1. Introduction
===============

freeVSD lets you employ multiple secure virtual servers on a single Red Hat Linux 
hosting server. Each virtual server has all the services available in the
hosting server including: FTP, Telnet, POP-3, SSH, DBMS, DNS, 
HTTP and SMTP.

This document provides a basic guide to installing and administering freeVSD 
on a Red Hat Linux 6.1/6.2 system. To gain a proper understanding of freeVSD, 
it is strongly suggested that you read this document. In addition, it is also 
recommended that you read through the following additional documents on freeVSD:

freeVSD Protocol Reference
freeVSD Security Guide
freeVSD FAQ
freeVSD MySQL Setup Guide
NEWS
README

There are two types of freeVSD users: Host Server and Admin users. As the 
Host Server administrator, you can perform the following tasks:

-Install FreeVSD
-Set up a virtual server including configuring, creating and starting one
-Set a password for the Admin user
-Stop a virtual server
-Delete a virtual server

As the Admin user you are responsible for administering users in single virtual servers through the following tasks. 

-Set access control rights for users
-List access control rights for users
-List disk quota allocation for users
-Set disk quota allocation for users

You can also reboot a virtual server.'

To perform Admin user tasks, go to section 10.

This document uses several formatting conventions to make reading easier. 
Angled brackets are used to mark sections in the configuration files, for example <Global>. 
Optional arguments are shown through square brackets in various parts of the document.
This document also includes example data variables IP addresses, domain, user names, passwords, byte measurements and time. In these instances, you must substitute your own data. In addition, these data are also shown as output at various points in the document. The output data displayed on your computer is likely to be different.

2. System Requirements
========================

Operating freeVSD requires a clean system installation of freeVSD on a clean Red Hat Linux 6.2/6.2 server. With a clean Red Hat server no applications must be installed and the server is to be used exclusively for freeVSD.

A clean system installation means that the Red Hat server will use a new set of freeVSD files from the installation. The Red Hat server will not use any files from any previuos installation of freeVSD that could adversely affect the operation of freeVSD. A clean installation ensures that the freeVSD hosting server is in an optimal state to function where it can communicate with other computers on the LAN.

NOTE: You must do a clean installation of freeVSD or you will find problems running the program.

freeVSD will install on virtually any Red Hat Linux 6.1/6.2 system. 
However, each virtual server's functionality will be limited to those services 
available on the hosting server. For instance, a typical Red Hat Linux 
workstation installation may not include Apache. This would preclude any of 
the hosting server's virtual servers from providing web hosting. 

In addition, to the operating system, the following are also required:

-500MB of hard disk space
-one or more server IP addresses
-64MB of memory

3. Installing freeVSD
=====================

There are three types of freeVSD installation:

-Installation from RPMs (see section 3.1)

-Installation with OpenSSL (see section 3.2)

-Installation from Source (see section 3.3)

When you have performed the steps for the installation method of your choice, 
you are ready to complete your installation. 

3.1. Installing freeVSD from RPMs
=================================

This is the recommended method for installing freeVSD as its simpler to perform
and provides the functions for the efficient operation of freeVSD. 
The first RPM installs freeVSD while the second RPM installs a collection 
of 'addon' packages that improve the functionality of the Admin user within each 
virtual server. While only the first RPM is required, it is strongly recommended that 
both be installed for practical virtual server hosting. The 
RPM freevsd-pkgs-1.4.6-1.i386.rpm contain the following 'addon' packages:

  fileutils-4.0-21.i386.rpm         	 glibc-2.1.3-15.i386.rpm
  glibc-devel-2.1.3-15.i386.rpm     	 glibc-profile-2.1.3-15.i386.rpm
  openssh-2.1.0p2-1.i386.rpm        	 openssh-clients-2.1.0p2-1.i386.rpm
  openssh-server-2.1.0p2-1.i386.rpm 	 openssl-0.9.5a-1.i386.rpm
  openssl-devel-0.9.5a-1.i386.rpm   	 procps-2.0.6-5.i386.rpm
  proftpd-core-1.2.0pre10-1.i386.rpm 	 psmisc-19-2.i386.rpm
  qpopper-3.1b1-1.i386.rpm           	 sh-utils-2.0-5.i386.rpm
  util-linux-2.10k-2.i386.rpm

Once downloaded, the RPM packages are installed using the following commands:

  $ rpm -ivh freevsd-1.4.6-1.i386.rpm
  $ rpm -ivh freevsd-pkgs-1.4.6-1.i386.rpm

This will install the files making up the freeVSD system into the following 
locations:

  /usr/sbin	                - freeVSD binaries
  /etc			            - freeVSD configuration
  /usr/share/freevsd/pkgs   - RPMs of 'addon' packages
  /usr/doc/freevsd-1.4.6    - Documentation

3.2. Installing freeVSD with OpenSSL
====================================

As of release 1.4.6, freeVSD can be compiled to use OpenSSL connections 
(Open Source SSL). Once compiled with OpenSSL support, freeVSD will only accept connections authenticated by an appropriate certificate. A series of utility 
scripts have been included in the 1.4.6 distribution that allow users to 
quickly produce a certificate of authority (CA) framework for implementing OpenSSL 
with freeVSD. 

In order to build freeVSD with OpenSSL, the OpenSSL packages (which are 
included in freevsd-pkgs-1.4.6-1.i386.rpm) must be installed using the 
following commands:

  $ rpm -ivh /usr/share/freevsd/pkgs/openssl-0.9.5a-1  
  $ rpm -ivh /usr/share/freevsd/pkgs/openssl-devel-0.9.5a-1
  
To build freeVSD with OpenSSL use the following commands:

  $ cd freevsd
  $ autoconf; autoheader
  $ ./configure --enable-addons --with-openssl
  $ make install

To create your freeVSD certificate of authority run the CA generation script using the 
following command:

  $ /usr/sbin/vsd-genca.pl

Follow the instructions on screen and when prompted for information, 
accept the default values.

To create certificates for the hosting server to communicate with virtual
servers via SSL run another short script using the following command:

 $ /usr/sbin/vsd-genhostcert.pl

Follow the instructions on screen. It is important that during the 
generation of the first certificate, the common name is entered as the host
server's name. In addition during generation of the second certificate (the <root> certificate) the common name is entered as <root>.

When you have finished the generation of certificates for the host server, go to 
section 5 to follow the steps on setting up certificates on individual virtual 
servers.

3.3. Installing freeVSD from Source
===================================

Installing from source provides greater control over the configuration of  
freeVSD, and various compile time options such as multiple directory 
locations and OpenSSL support are used. 

It is strongly advised that the extra 'addon' packages provided in 
freevsd-pkgs-1.4.6-1.i386.rpm be installed for practical virtual server 
hosting. The RPM freevsd-pkgs-1.4.6-1.i386.rpm contain the following 'addon'
packages:

  fileutils-4.0-21.i386.rpm          glibc-2.1.3-15.i386.rpm
  glibc-devel-2.1.3-15.i386.rpm      glibc-profile-2.1.3-15.i386.rpm
  openssh-2.1.0p2-1.i386.rpm         openssh-clients-2.1.0p2-1.i386.rpm
  openssh-server-2.1.0p2-1.i386.rpm  openssl-0.9.5a-1.i386.rpm
  openssl-devel-0.9.5a-1.i386.rpm    procps-2.0.6-5.i386.rpm
  proftpd-core-1.2.0pre10-1.i386.rpm psmisc-19-2.i386.rpm
  qpopper-3.1b1-1.i386.rpm           sh-utils-2.0-5.i386.rpm
  util-linux-2.10k-2.i386.rpm

Once downloaded, the package is installed using the following command:

  $ rpm -ivh freevsd-pkgs-1.4.6-1.i386.rpm

This will install the 'addon' packages into the following location:

  /usr/share/freevsd/pkgs 

Having downloaded the freeVSD source file 'freevsd-1.4.6-1.tar.gz', extract it by entering
the following command:

  $ tar -zxf freevsd-1.4.6-1.tar.gz

Build and install the sources using the following commands:

  $ cd freevsd-1.4.6-1
  $ autoconf; autoheader
  $ ./configure --enable-addons
  $ make install

By default this will install the files making up the freeVSD system into the 
following locations:

  /usr/local/sbin	         		 - freeVSD binaries
  /usr/local/etc		  			 - freeVSD configuration
  /usr/local/share/freevsd/pkgs  	 - RPMs of third party applications

NOTE: This differs from an RPM installation that places the freeVSD 
      binaries into /usr/sbin and the freeVSD configuration files into the 
      /etc directory.
     
3.4. Completing the Installation
=================================

To complete the installation of freeVSD a short script is executed using 
the following command:

  $ /usr/sbin/vsd-install.pl

This will carry out the following steps:

  -Prompt the user for a mount point for freeVSD skel and virtual servers.  
  -Prompt the user for the primary nameserver of the host server.  
  -Prompt the user for the secondary nameserver of the host server.  
  -Update the configuration file /etc/vsd.conf based on the users input.  
  -Virtualise the FTP, Telnet, POP-3 and SMTP services by commenting
   out the following lines in the configuration file '/etc/inetd.conf':

    # ftp stream tcp nowait root /usr/sbin/tcpd in.ftpd -l a
    # telnet stream tcp nowait root /usr/sbin/tcpd in.telnetd
    # pop-3 stream tcp nowait root /usr/sbin/tcpd ipop3d

   and appending the following lines in /etc/inetd.conf:
 
    ftp stream tcp nowait root /usr/sbin/virtuald tcpd /usr/sbin/proftpd -d -l
    telnet stream tcp nowait root /usr/sbin/virtuald tcpd /usr/sbin/in.telnetd
    pop-3 stream tcp nowait root /usr/sbin/virtuald tcpd /usr/sbin/in.qpopper
    smtp stream tcp nowait root /usr/sbin/virtuald tcpd /usr/sbin/sendmail -bs
    vsd stream tcp nowait root /usr/sbin/vsd vsd

NOTE: Virtualising the services will allow the services (originally provided 
	  in the hosting server) to run on the specific IP address of the 
	  virtual server to be created.

  Register vsd as a service on port 1725 in the '/etc/services' directory.
  Disable the automatic startup of HTTPD services.
  Kill any HTTPD processes presently running.
  Send a -HUP (hangup) signal to inetd forcing it to read the configuration changes.

Alternatively, these changes can be made by manually editing the appropriate configuration files. 

NOTE: The mount point specifies where your skel and virtual servers will be 
      mounted. For a Red Hat server installation we put the skel in the /home/vsd 
      directory because it has a suitably large partition. If you are using a custom 
      setup from source, ensure that the partition is large enough as the installation 
      requires as much disk space as your system disk--which can be up to 
      600Mb.

NOTE: It is important to set at least one nameserver entry in '/etc/vsd.conf',
      otherwise you will have difficulties connecting to your virtual servers 
      via Telnet.

4. Uninstalling freeVSD
=======================

To remove freeVSD, execute a short script by entering the following command:

  $ /usr/sbin/vsd-uninstall.pl

This will prompt the user before carrying out the following steps:

  Replace '/etc/services' with the version prior to freeVSD installation.
  Replace '/etc/inetd.conf' with the version prior to freeVSD installation.
  Send a -HUP signal to inetd forcing it to read the configuration changes.
  Remove the freeVSD configuration files.
  Enable the automatic startup of HTTPD services for the host server.
  Remove the freeVSD certificate authority.
  Remove the freeVSD certificates.
  Remove the freeVSD skel.
  Remove all virtual servers.

Alternatively these changes can be made manually by editing the configuration files.

If freeVSD or its 'addon' packages have been installed from RPMs, they may be 
removed using the following commands:

  $ rpm -e freevsd-1.4.6-1.i386.rpm
  $ rpm -e freevsd-pkgs-1.4.6-1.i386.rpm

If freeVSD has been installed from source the remaining installed files may be
removed using the following commands:

  $ cd freevsd
  $ make uninstall

If you installed freeVSD from source, then you need to clean the source tree of files used during compilation by entering the following command:

  $ make clean

To clean the source tree of files used during the auto-configuration process 
use the following command:

  $ make distclean

5. Setting Up a Virtual Server
==============================

Once you have installed freeVSD, you can set up a virtual server for 
operation. You will do the following:

- Generate the 'skel' that contains the configuration files
- Create a virtual server

You can also change the configurations manually before creating a virtual server. 
The configurations will affect the way your virtual server performs its functions. 
To set up virtual servers without changing configurations go to the next 
section 5.1. To set up virtual servers and change configurations, 
go to section 5.2. 

5.1 Setting Up Virtual Servers Without Changing Configurations
==============================================================

Generating the 'skel' used by your virtual servers can take upwards of 20 minutes
depending on your hardware. Generate the skel using the following command:

  $ vsd-genskel.pl

NOTE: If you have installed freeVSD from source, you must enter the command from the
	  directory in which you have installed freeVSD: '/usr/sbin'. Alternatively, enter the 
	  filename as '/usr/sbin/vsd-genskel.pl' 
	  	
Create a virtual server using the command for FreeVSD administration--'vsdadm'. 
The following line adds a <VirtualServer> declaration to '/etc/vsd.conf' as specified. The supplied IP address should be an available address on the same subnet as your LAN.
   
  $ vsdadm vs_create localhost company 192.168.28.1 company.net 200 0

NOTE: If you have installed freeVSD from source, you must enter the command from the
	  directory in which you have installed freeVSD: '/usr/sbin'. Alternatively, enter the 
	  filename as '/usr/sbin/vsd-genskel.pl' 

The creation of the virtual server is carried out by a 
scheduled batch process and takes around 2 minutes depending on your 
hardware. You can run this batch process by entering the following 
command:

  $ vsd-vsbatch.pl

NOTE: If you have installed freeVSD from source, you must enter the command from the
	  directory in which you have installed freeVSD: '/usr/sbin'. Alternatively, enter the 
	  filename as '/usr/sbin/vsd-genskel.pl' 

If you have installed freeVSD with OpenSSL run a short script using the following 
command to generate a certificate for the virtual server:

  $ /usr/sbin/vsd-genvscert.pl <virtual server name>

Follow the instructions on the screen. It is important that during the 
generation of the certificate the common name is entered as the relevant
virtual server's name.

To confirm that freeVSD SSL support is working correctly, enter 
the following command:

  $ vsdadm user_list localhost <virtual server name>

When a certificate has been generated, the output from the same command should be as follows:

  name=admin uid=1000 home="/root" shell="/bin/bash"
  name=mail uid=1001 home="/var/spool/mail" shell="/bin/false"
  name=web uid=1002 home="/home/web" shell="/bin/bash"
  name=ftp uid=1003 home="/home/ftp" shell="/bin/bash"

The virtual server(s) must now be booted using the following command:

  $ vsboot --start

NOTE: If you have installed freeVSD from source, you must enter the command from the
	  directory in which you have installed freeVSD: '/usr/sbin'. Alternatively, enter the 
	  filename as '/usr/sbin/vsd-genskel.pl' 

Set the password for your virtual server's Admin user using the following 
commands:

  $ bevs -r vsone
  $ passwd -u admin -p foobar
  $ exit

You now have a fully functional virtual server.

The following examples let you test the access to your new virtual server. Substitute
the IP addresses given in the example below with your own:

  i) By Telnet:

   $ telnet 192.168.28.1

   Trying 192.168.28.1...
   Connected to 192.168.28.1.
   Escape character is '^]'.
   Server vsone.net
   login: admin
   Password: foobar
   [admin@vsone /root]$ exit
   Connection closed by foreign host.

  ii) By FTP:

   $ ftp 192.168.28.1

   Connected to 192.168.28.1.
   220 ProFTPD 1.2.0pre10 Server (ProFTPD) [vsone.net]
   Name (192.168.28.1:name): admin
   331 Password required for admin.
   Password: foobar
   230 User admin logged in.
   Remote system type is UNIX.
   Using binary mode to transfer files.
   ftp> close
   221 Goodbye.
   ftp> exit
   
  iii) By performing Telnet to an SMTP account:
  
   $ telnet 192.168.28.1 smtp

   Trying 192.168.28.1...
   Connected to 192.168.28.1.
   Escape character is '^]'.
   220 vsone.net ESMTP Sendmail 8.9.3/8.9.3; Thu, 17 Aug 2000 13:37:09 +0100
   QUIT
   221 name.company.net closing connection
   Connection closed by foreign host.

  iv) By performing Telnet to a POP3 account:
   
   $ telnet 192.168.28.1 pop3

   Trying 192.168.28.1...
   Connected to 192.168.28.1.
   Escape character is '^]'.
   +OK QPOP (version ?) at vsone.net starting.  <3482.966515834@vsone.net>
   USER admin
   +OK Password required for admin.
   PASS foobar
   +OK admin has 0 visible messages (0 hidden) in 0 octets.
   QUIT
   +OK Pop server at vsone.net signing off.
   Connection closed by foreign host.

   v) By performing using lynx

   $ lynx 192.168.28.1
  


NOTE: If it takes a long time to telnet to the server then it is likely 
      that you have incorrectly set the PrimaryNS and SecondaryNS entries in 
      /etc/vsd.conf which must refer to your networks name server(s).

5.2. Setting Up Virtual Servers and Changing Configurations
===========================================================

When setting up virtual servers, you can change configurations in the files 
before generating the 'skel'. Once this is done, you are can create a virtual server.

5.2.1. Overview of the Skel
===========================

The 'skel' contains configuration files and any binaries needed for virtual servers to function. For example, it is within the freevsd/site/<os>/ Skel directory that contain the configuration files for setting up a web server. The 'skel' is compact and contains only the files specific to operating the virtual server. However, the files also contain the global Linux host server settings that allow the virtual server to enjoy the same robust functionality of a Linux server.

The 'skel' and virtual servers are created from scripts that can be found in the freevsd/host and freevsd/site directories. The scripts in the freevsd/site build on the scripts located in freevsd/host and provide the configuration files for a more full-featured virtual server setup. As virtual server setups may differ, the site directory is provided as a template for site-specific customisation. Pointers to the script locations are stored in /etc/freevsd.conf which are automatically set up for you by the Configure scripts. 

5.2.2. Changing Configurations in the 'vsd.conf' Configuration File
====================================================================

1.	Refer to the configuration details in the vsd.conf file in the workings.txt file in 
	the 'doc/working' directory. (see the next section: 5.2.3) 
2.	Edit the configuration file: '/usr/local/etc/vsd.conf' with the new configurations. 

Note:	Make sure you set correct values for PrimaryNS and SecondaryNS--the IP addresses 
		of your primary and secondary name servers. If you do not set correct values, the 
		freeVSD hosting server will not run.

5.2.3. Configuration Settings in the Workings.txt File
======================================================

freeVSD includes the /etc/freevsd.conf and /etc/vsd.conf configuration files:

5.2.3.1 ETC/FREEVSD.CONF
========================

The account creation scripts use this file as a reference to parameters and 
directories for the creation and configuration of virtual servers. 
The following is a description of each directive:

i) send_mail = {NO|YES}

If set to YES, then vs-batch.pl will send a mail notification to the user defined 
in `mail_addr' after an account has been created.

ii) mail_addr = <e-mail address>

This is the e-mail address where an e-mail should be sent to when a virtual server 
has been created.

iii) mail_template = <path to a text file>

The mail template text file contains the content of the e-mail that is sent to `mail_addr' 
when an account has been created. The mail template can contain 4 special tokens 
which show the virtual server details. These are described as follows:

#VS#
Replace with the Virtual Server name
#HOSTNAME#
Replace with the hostname of the Virtual Server
#IPADDRESS#
Replace with the IP address of the Virtual Server.
#PASSWORD#	
Replace with the password for the `admin' user.

iv) os_skelrepo = <absolute path to <os>/skel-repo>

Pathname to the skel that holds operating system-specific files.

v) site_skelrepo = <absolute path to <site>/skel-repo>

Pathname to the skel that holds virtual server site-specific files. This is optional.

vi) site_skel_install = <absolute path to a Perl script>

Pathname to the Perl script that does the site specific work on 
creating the virtual server skel. This is optional.

vii) site_vs_install = <absolute path to a Perl script>

Pathname to the Perl script that performs the site specific phase of virtual server 
creation. This is optional.

viii) add_ons = <absolute path to a directory>

Pathname to a directory that contains a set of files that are to be installed into the 
'skel' during the execution of vsd-genskel.pl. Currently only RPMs can be installed into the 'skel'.

viv)  bin_progs =
	  sbin_progs =
      usr_sbin_progs =
      usr_libexec_progs =

These contain a space seperated list of files that are copied from the respective '/bin', '/sbin', '/usr/sbin', '/usr/libexec' directories into the skel. These are environment 
variables used for running the 'genskel' (Skel generation) script.

x)	  delete_progs =

In order to organise your virtual server accounts, manually add a list of files 
(separated by a space) that should be deleted from the Skel. This list can contain
directories (that are acted upon recursively) and wildcard characters.

5.2.3.2. VSD.CONF
=================

Upon execution, all freeVSD applications read their configuration information from a 
configuration file which, by default, is '/etc/vsd.conf'. 

NOTE: Comments are denoted by a `#' at the beginning of a line.  

Configuration File Sections
--------------------------

Global Configurations
---------------------

There are three major sections in the vsd.conf file:

<Global> ... </Global>
<Partition> ... </Partition>
<VirtualServer> ... </VirtualServer>

Each of the sections are described as follows:

i) Global

Syntax:
<Global> ... </Global>
Context: None.
Description:
The Global section contains default configurations for any defined virtual server. 
In addition, it shows the other directives that specify limits imposed during the creation of accounts. An example of the limit is the range of user IDs that can be used for virtual servers.

ii) Partition

Syntax:
<Partition> ... </Partition>
Context: None
Description:
The Partition section specifies the location of virtual servers.  
A server may have many devices and we might want to spread the virtual server 
accounts across the devices in order to balance load on bus and disk use. 
The partition section also lets us specify the device mount point and the 
maximum number of virtual servers that can be created.

iii) Virtual Server

Syntax:
<VirtualServer> ... </VirtualServer>
Context: 
None
Description:
The virtual server section declares the configurations that are specific 
to the virtual server. These include the IP address, the maximum number 
of users, the disk quota, whether it's active or not, and the Partition 
it is located on. The virtual server specific configurations are described as follows.

Virtual Server Specific Configurations
--------------------------------------

BWLimit

Syntax: 
BWLimit <bitrate>
Default:  
BWLimit 0bps
Context: 
Global, Virtual Server
Description:
An informational parameter that can be used by external scripts to configure bandwidth limiting on a virtual server.

BWBurst

Syntax: 
BWBurst <bitrate>
Default: 
BWBurst 0bps
Context: 
Global, Virtual Server
Description: 
An informational parameter that can be used by external scripts to 
configure bandwidth bursting on a virtual server.

PrimaryNS

Syntax: 
PrimaryNS IP-address
Default: 
None
Context: 
Global, Virtual Server
Description
When defined in the Global context, this is the default primary name server 
used for resolving domains. It is mandatory that this is provided in the Global context. The primary name server must be an IP address because its value is used to create the configuration file for resolving domains (/etc/resolv.conf) for each virtual server. The directive can be optionally applied in the virtual server context as virtual servers can use alternative name resolves if they require.

SecondaryNS

Syntax 
SecondaryNS IP-address
Default: 
none
Context: 
Global, Virtual Server
Description:
When defined in the Global context, this is the default secondary name server to be used for 
resolving domains. It is mandatory that this is provided in the Global context. The secondary name server must be an IP address because its value is used to create the configuration file for resolving domains (/etc/resolv.conf) for each virtual server. The directive can be optionally applied in the virtual server context so that these can use alternative name resolves if they require.

Mount

Syntax: 
Mount filename
Default: 
none
Context: 
Partition
Description:
This specifies the mount point under which the 'Skel' and virtual server account 
directories will be created. It should be defined once per Partition 
section - it is a mandatory directive.

MaxVS 

Syntax:
MaxVS number
Default: 
none
Context: 
Partition
Description:
This directive restricts the number of virtual servers that can be created
in a partition. Define this once per Partiton section. This directive
is mandatory.

IP

Syntax: 
IP saddr
Default: 
none
Context: 
virtual server
Description
This defines the main IP address (the other being an alias IP address) that the 
virtual server will listen for connections. saddr must be an IP address in the 
numbers-dots notation.

Quota

Syntax: 
Quota number
Default: 
none
Context: 
virtual server
Description:
Specifies the maximum disk quota assigned to a virtual server.  If the`number' 
is zero, then no disk quota is set. The number is measured in megabytes.

StartUID

Syntax: 
StartUID number
Default: 
none
Context: 
virtual server
Description:
For user disk quotas to work, the UIDs allocated to 
virtual server users on a hosting server must be unique. StartUID is the first 
user-id that the virtual server is allowed to use.

Users

Syntax: 
Users number
Default: 
none
Context: 
Virtual Server
Description
Related to StartUID. Users define the number of UIDs that a virtual server 
is allocated. It's usable UID range is between StartUID and 
StartUID+Users-1.

UIDRange

Syntax: 
UIDRange low high
Default: 
none
Context: 
Global
Description:
As each virtual server has a unique UID, and that there are a finite set of 
UIDs in Unix, low and high boundaries of a UID pool need to be defined. 

Syntax: 
UIDAllocChunk number
Default: 
none
Context: 
Global
Description
To simplify the allocation strategy of UIDs, we define the chunk size that 
UIDs can be allocated to virtual servers.  Therefore UIDs must be allocated 
to virtual servers in multiples of a certain `number'.

Partition

Syntax: 
Partition number
Default: 
none
Context: 
Virtual Server
Description:
The associated disk partition that a virtual server has been created on. 
The partition section defines the number.  The virtual server will 
exist on the partition that has a matching number to that of the virtual server.

Status

Syntax: 
Status active|disabled
Default: 
none
Context: 
virtual server
Description:
The status setting enables and disables virtual servers. If set to disabled, it will 
not be possible to gain access to the virtual server through remote means, 
such as via Telnet, FTP, POP etc. When a server is set to disabled, it is then 
immediately shut down.

AliasIP

Syntax: 
IP saddr
Default: 
none
Context: 
Virtual Server
Description:
This defines the secondary IP address that a virtual server will listen for connections. 
'saddr' must be an IP address in the standard IP address notation (numbers and dots).  


FORMAT OF A VSD.CONF FILE
====================================

An example vsd.conf file might look like this. 

<Global>
PrimaryNS ns1.your_company.net
SecondaryNS ns2.your_company.net
ErrorLog /var/log/vsd.log
UIDRange 1000 30000
UIDAllocChunk 300
BWLimit 32Kbit
BWBurst 256Kbit

</Global>

<Partition 0>
   Mount /virtual/disk0
   MaxVS 40
   </Partition>
   <Partition 1>
   Mount /virtual/disk1

MaxVS 50
   </Partition>
<VirtualServer vsname>
   IP 1.2.3.4
   StartUID 1000
   Users 200
   Quota 300
   Partition 0
   Status active
   PrimaryNS our-ns1.com
   SecondaryNS our-ns2.com
   AliasIP 1.2.3.5
   AliasIP 1.2.3.6
   BWLimit 6Kbit
   BWBurst 12KBit
   </VirtualServer >

5.2.4	Creating the 'Skel'
===========================

Creating the 'skel' takes about 10 minutes. For a Red Hat standard installation,
we put the skel in '/home/vsd' because it has a suitably large partition.

  $ mkdir /vsd
  $ /usr/local/sbin/vsd-genskel.pl /vsd

5.2.5 Creating a Virtual Server
===============================

Create a virtual server using the virtual server administration command-'vsdadm' 
by entering the following line to add a <VirtualServer> declaration to '/etc/vsd.conf'. 
   
  $ vsdadm vs_create localhost company 192.168.28.1 company.net 200 0

Note: The supplied IP address and domain name is an example only. You should substitute your own domain name and Ip address.   

Creation of the virtual server is carried out by a scheduled batch process and takes around 2 minutes depending on your hardware. You can run this batch process by entering the following command:

  $ vsd-vsbatch.pl


If you have installed freeVSD with OpenSSL and have performed the steps as far as generating a hosting server certificate, run a short script to generate a certificate for an individual virtual server by entering the following command:

  $ /usr/sbin/vsd-genvscert.pl <virtual server name>

Follow the instructions on screen. It is important that during the 
generation of the certificate, the common name is entered as the relevant
virtual server's name.

To confirm that freeVSD OpenSSL support is working correctly by entering the
following command:

  $ vsdadm user_list localhost <virtual server name>

When an appropriate certificate has been generated the output from the
same command is as follows:

  name=admin uid=1000 home="/root" shell="/bin/bash"
  name=mail uid=1001 home="/var/spool/mail" shell="/bin/false"
  name=web uid=1002 home="/home/web" shell="/bin/bash"
  name=ftp uid=1003 home="/home/ftp" shell="/bin/bash"

The virtual server(s) must now be booted using the following command:

  $ vsboot --start

Set the password for your virtual server's Admin user using the following 
commands:

  $ bevs -r vsone
  $ passwd -u admin -p foobar
  $ exit

You now have a fully functional virtual server.

The following examples let you test your new virtual server by accessing the virtual server through Telnet and FTP. You can substitute the example IP addresses, server name and password given below with your own:

 i)	By Telnet:

   $ telnet 192.168.28.1

   Trying 192.168.28.1...
   Connected to 192.168.28.1.
   Escape character is '^]'.
   Server vsone.net
   
   login: admin
   Password: foobar
   [admin@vsone /root]$ exit
   
   Connection closed by foreign host.

 ii) By FTP

   $ ftp 192.168.28.1
   
   Connected to 192.168.28.1.
   220 ProFTPD 1.2.0pre10 Server (ProFTPD) [vsone.net]
   
   Name (192.168.28.1:nick): admin
   331 Password required for admin.
   Password: foobar
   230 User admin logged in.
   Remote system type is UNIX.
   Using binary mode to transfer files.
   
   ftp> close
   221 Goodbye.
   ftp> exit

iii) By Telnet to SMTP
   
   $ telnet 192.168.28.1 smtp
   Trying 192.168.28.1...
   Connected to 192.168.28.1.
   Escape character is '^]'.
   220 vsone.net ESMTP Sendmail 8.9.3/8.9.3; Thu, 17 Aug 2000 13:37:09 +0100
   QUIT
   221 name.company.net closing connection
   Connection closed by foreign host.
   
iv) By Telnet to POP3

   $ telnet 192.168.28.1 POP3
   Trying 192.168.28.1...
   Connected to 192.168.28.1.
   Escape character is '^]'.
   +OK QPOP (version ?) at vsone.net starting.  <3482.966515834@vsone.net>
   USER admin
   +OK Password required for admin.
   PASS foobar
   +OK admin has 0 visible messages (0 hidden) in 0 octets.
   QUIT
   +OK Pop server at vsone.net signing off.
   Connection closed by foreign host.

v) By using lynx

   $ lynx 192.168.28.1
   etc...

NOTE: If you are unable to telnet to the server instantly, then it is likely 
      that you have incorrectly set the PrimaryNS and SecondaryNS entries in 
      /etc/vsd.conf which refer to your networks' name server(s).


6. Enabling and Disabling Virtual Server Accounts
==================================================

Once you have created your virtual server, you can start and stop virtual server 
accounts. A virtual server account allows users to use the services of the 
virtual server.

To enable a virtual server account, enter the following 'vsdadm' command:

$ /usr/sbin/vsdadm vs_enable <host server> <virtual server>

NOTE: The <host-server> argument is the fully qualified domain name of the hosting 
server. The <virtual-server> argument is the account name of the virtual server and not its 
FQDN.  

NOTE: This is *not* the FQDN of the virtual server.

To disable a virtual server account, enter the following command:

$ /usr/sbin/vsdadm vs_disable <host server> <virtual server>

NOTE: The <host-server> argument is the fully qualified domain name of the
server that hosts the virtual server. The <virtual-server> argument is the 
account name of the virtual  server. 

7. Setting a Password for the Admin User
=========================================

As the host server user, you will need to set a password for the Admin 
user. If you have changed the '$ send_mail' and '$ mail_addr' lined in /etc/freevsd.conf,
you will not need to set a password for the Admin user of a virtual server. You
can set a password by entering the following commands:

$ /usr/local/bin/bevs -r test1
  $ passwd -u admin -p foobar
  $ exit

Note: Substitute 'foobar' with your own password.

8. Accessing Virtual Server Accounts
=====================================

For ease of access to virtual server accounts, a program called `bevs'
enables you to locate and chroot into a virtual server just by
supplying a virtual server name:

  $ bevs -r <virtual-server>

9. Deleting a Virtual Server
============================

You can delete a virtual server by first disabling it and then entering a delete command. When a virtual server is deleted, its directory as well as its subdirectories is removed. 
The server mapping is also removed from '/etc/vsd.conf'.

To delete a virtual server, first ensure the services on the virtual
server are stopped by entering the following line:

$ /usr/sbin/vsdadm vs_disable host.server <user name>

Then enter the following to delete a virtual server:

$ /usr/sbin/vsdadm vs_delete <host server> <virtual server>

NOTE: The <host-server> argument is the fully qualified domain name of the server that     	 hosts the virtual server. The <virtual-server> argument is the account name of the virtual  server.

The request is then queued and a script running as a cron job performs the deletion. 

10. Administering an Account as the Admin User
==============================================

As the Admin user, you can administer users on your virtual server through any of the following procedures:

-Setting Access Control Privileges (see section 10.1)
-Listing Access Rights (see section 10.2)
-Displaying Quota Statistics (see section 10.3)
-Setting User Quotas (see section 10.4)
-Accessing a Virtual Server (see section 10.5)
-Rebooting a Virtual Server (see section 10.6)

10.1 Setting Access Control Privileges
======================================

You can alter access control privileges for your member users. When altering access
control privileges, you must specify the privilege that you wish to assign to the
user.

Syntax: setrights <user> <+|-><privilege> [<+|-><privilege> ...]

Notes:

The available privileges are:
    Perl - Compile/execute Perl scripts
    GCC - Compile programs using gcc and access /usr/include
    net - ftp and telnet from the virtual server
    FTP - FTP login access
    admin - Alter virtual server user accounts
    mail - Send and receive e-mail (POP3)
    login - Telnet to the virtual server
    chrtFTP - Chroot the FTP session

'chrtFTP' is a special privilege that creates an FTP chrooted 
environment. Upon setting the directories, `bin', `etc', `lib' and `pub' 
are copied into the user's home directory. A `guest group' entry is then added to /etc/ftpaccess. This prevents the user from writing to the `bin', `etc' and `lib' directories. The `FTP' privilege must have previously been assigned to a user before the `chrtFTP' privilege can be set.

Example:

----------------------------------------------------------------------
                                                                      
  To assign gcc, net and mail rights to user bob:
    $ setrights bob +gcc +net +mail

  To assign mail rights but remove Perl and gcc access to user jim:
    $ setrights jim +mail -perl -gcc

  To make a user's home directory suitable for chroot FTP
    $ setrights jim +ftp
    $ setrights jim +chrtftp

----------------------------------------------------------------------

10.2 Listing Access Rights
===========================

You can list the access rights of single or multiple member users 
in a virtual server. 

Syntax: listrights [<user>]

The listrights command displays the access control rights for member
users of a virtual server. If the optional <user> name is supplied,
then the rights are shown for that individual user.

10.3 Displaying Quota Statistics
================================

You can monitor disk usage and quota allocation limits for individual or all users in a 
virtual server. When entering the Quotastats command, you can optionally add a user name. 

quotastats [<user>]

10.4 Setting User Quotas
========================

You can alter the soft limit quota allocation for a user by entering the
following command. 

Syntax: setquota <user> [<+|->]<bytes><K|M>

The quota can be adjusted by an absolute value or relatively by prefixing
a + or - to the <bytes> parameter.

-----------------------------------------------------------------
 Example:	   To set the quota limit for user bob to 100 Kbytes:
 
 				$ setquota bob 100K

				To add 50 Mbytes to user steve's quota limit:

     			$ setquota steve +50M
-----------------------------------------------------------------

Note:	The cumulative total of soft limit quota allocation for each user cannot
		exceed the soft limit allocation for the virtual server itself.


10.5 Accessing a Virtual Server
===============================

For ease of access to virtual server accounts, a program called `bevs'
enables you to locate and chroot into a virtual server just by
supplying a virtual server name. Enter the following command:

  $ bevs <virtual-server>

10.6 Rebooting a Virtual Server
===============================

To restart services on a virtual server that are configured for automatic
startup, enter the following command:

   $ rebootvs

Note:	All running processes of the virtual server are killed when this command is entered.
















