freeVSD -  Installation
=======================

This document provides a basic guide to the installation of freeVSD on a Red 
Hat Linux 6.1/6.2 system. More detailed information can be found in the 
following supplied documents:
	  
  install.txt     - installation guide
  NEWS            - latest changes to freeVSD
  README	  - essential information on freeVSD
  INSTALL         - generic installation instructions
  vs-guide.txt    - virtual server administration guide
  host-guide.txt  - hosting server administration guide
  background.txt  - detailed information on freeVSD 
  security.txt    - discussion of security consideratations
  protocol.txt    - detailed information on the freeVSD protocol
  faq.txt	  - frequently asked questions
	
To gain a proper understanding of freeVSD, it is strongly suggested that you 
read all the supplied documents.


Contents
========

1.1. System Requirements
1.2. Installing freeVSD from RPMs
1.3. Installing freeVSD from source
1.4. Completing the installation 
1.5. Creating virtual servers
1.6. freeVSD with OpenSSL
1.7. Uninstalling freeVSD


1.1. System Requirements
========================

freeVSD is intended to be installed on a clean system running a Red Hat Linux 
6.1/6.2 server installation. A clean system is produced by carrying out a clean
install on a clean server. A 'clean server' means that you are not already 
using the server on which you are attempting to install freeVSD for anything 
else. A 'clean install' means that you have installed the operating system 
(Red Hat Linux 6.1/6.2), and that your server can communicate with other 
computers via its local area network (LAN).

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.  


1.2. Installing freeVSD from RPMs
=================================

This is the recommended method for installing freeVSD. freeVSD consists of two
RPM packages. The first RPM installs the freeVSD system while the second RPM
installs a collection of 'addon' applications 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.5-1.i386.rpm contains 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.5-1.i386.rpm
  $ rpm -ivh freevsd-pkgs-1.4.5-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.5  - Documentation


1.3. Installing freeVSD from source
===================================

Installing from source provides greater control over the configuration of  
freeVSD, and allows for various compile time options affecting such things 
as directory locations and OpenSSL support. 

It is strongly advised that the additional 'addon' packages provided in 
freevsd-pkgs-1.4.5-1.i386.rpm be installed for practical virtual server 
hosting. The RPM freevsd-pkgs-1.4.5-1.i386.rpm contains 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.5-1.i386.rpm

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

  /usr/share/freevsd/pkgs - RPMs of third party applications

Having downloaded the freeVSD source file freevsd-1.4.5-1.tar.gz extract it 
using the following command:

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

Build and install the sources using the following commands:

  $ cd freevsd-1.4.5-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 which places the freeVSD 
      binaries into /usr/sbin and the freeVSD confgiuration files into /etc.
      All examples given will refer to the RPM style installation and for a 
      source installation of freeVSD the user must ammend them accordingly.


1.4. Completing the installation
================================

To complete the installation of freeVSD a short script can be 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 /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
  Register vsd as a service on port 1725 in /etc/services.
  Disable the automatic startup of httpd services.
  Kill any httpd processes presently running.
  Send a -HUP signal to inetd forcing it to read the configuration changes.

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

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 /home/vsd 
      because it is a suitably large partition. If you are using a custom 
      setup, 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.


1.5. Creating virtual servers
=============================

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

Create a virtual server using the vsdadm command. 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 vsone 192.168.28.1 vsone.net 200 0

Actual creation of the virtual server is intended to be carried out by a 
scheduled batch process and should take around 2 minutes depending on your 
hardware. This batch process can be run interactively using the following 
comand:

  $ vsd-vsbatch.pl

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!

Test the access to your new virtual server as follows:

   $ 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.

   $ 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
   
   $ 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 diddley.squat.net closing connection
   Connection closed by foreign host.
   
   $ 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.

   $ lynx 192.168.28.1
   etc...

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 your networks nameserver(s).

Now consult admin-guide.txt and background.txt for information on utilising 
your freeVSD virtual servers.


1.6. freeVSD with OpenSSL
=========================

As of release 1.4.5 freeVSD can be compiled to use SSL connections. Once 
compiled with OpenSSL support, freeVSD will only accept connections 
authenticated by an appropriate certificate. A series of utlility scripts have
been included in this distribution which will allow users to quickly produce a
certificate authority (CA) framework for implementing OpenSSL with freeVSD. The
scripts are not intended as an example of how certificates should be created
and managed. 

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

  $ 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

Installation can then proceed as described above until the point when virtual 
servers are to be created. 

To create your freeVSD certificate authority run a short 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 via SSL run 
another short script using the following command:

  $ /usr/sbin/vsd-genhostcert.pl

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

Finally, to generate a certificate for an individual virtual server run 
another short script using the following command:

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

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

Creation and management of virtual servers can then proceed as described 
above for non-SSL freeVSD.

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

  $ vsdadm user_list localhost <virtual server name>

If this command is attempted for a virtual server which has no valied 
certificate the following error will result:

  error: error:02001002:system library:fopen: \
    No such file or directory: (/usr/local/etc/vsd/client/vsone.key)

When an appropriate 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"


1.7. Uninstalling freeVSD
=========================

To assist with the removal of freeVSD from a system, a short script can be 
executed using 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 freeVSD configuration files.
  Enable the automatic startup of httpd services.
  Remove freeVSD certificate authority.
  Remove freeVSD certificates.
  Remove freeVSD skel.
  Remove all virtual servers.

Alternatively these changes can be made manually.

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

  $ rpm -e freevsd-1.4.5-1.i386.rpm
  $ rpm -e freevsd-pkgs-1.4.5-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

To clean the source tree of files used during compilation, use the following
command:

  $ make clean

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

  $ make distclean












