freeVSD-1.4.10-1 INSTALL Copyright (c) 1999-2001 Idaya Ltd. All rights reserved. This document provides a brief guide to installing freeVSD on all supported platforms. Contents -------- 1.......Overview 1.1.......Recommended Installation 1.2.......Alternative Installation 1.3.......Source Installation 1.4.......Upgrading 2.......RPM Installation 2.1.......Quick Start Installation 2.2.......Detailed Installation 3.......Source Installation 3.1.......OpenSSL Source Installation 4.......Uninstalling 5.......Getting Started 5.1.......Creating a VSD Certificate Authority 5.1.1.......Managing Multiple Hosting Servers 5.2.......Creating a Virtual Server 5.3.......Testing a Virtual Server 5.4.......Deleting a Virtual Server 6.......Getting Advanced 6.1.....Quota Support 6.2.....VSD Security 6.2.1.....Securing Remote Access to VSD 6.2.2.....Securing Apache 6.3.....Secure VSD 6.3.1.....Secure VSD Communication 6.3.2.....Certificate Storage / Distributions Models 6.3.3.....Certificate Authorities 6.3.4.....Certificate Hierarchy 6.3.5.....Certificate Revocation 6.3.6.....Creating VSD Certificates 6.3.7.....Revoking VSD Certificates 6.3.8.....Listing VSD Certificates 6.3.9.....Creating sub-CAs 6.3.10....Deleting sub-CAs 6.3.11....Listing sub-CAs 6.3.12....Distributing VSD Server Certificates 6.3.13....Export And Retrieval 6.3.14....Exporting VSD Certificates 6.3.15....Retrieving VSD Certificates 6.3.16....Exporting CA certificates 6.3.17....Retrieving CA certificates 6.3.18....Exporting CRLs 6.3.19....Retrieving CRLs 6.3.20....Example Configuration 6.3.21....Multiple CAs 6.3.22....Single CA / Nameserver 6.3.23....VSD SSL Configuration 6.4.....Skels 6.4.1.....Managing skels 6.4.2.....Customising skels 6.4.3.....The mod_part command set 6.5.....Virtual Domains and Users 6.5.1.....Initial Configuration 6.5.2.....Daemon Configuration 6.5.3.....Pop Before SMTP 6.5.4.....Adding Domains and Users 6.5.5.....Autoresponders 1. Overview ---------------- freeVSD is currently supported on the following platforms: RedHat-6.2 RedHat-7.1 freeVSD has the following minimum installation requirements: Two or more free IP addresses 750MB of free diskspace 32MB of RAM freeVSD is available for download from ftp://ftp.freevsd.org/freevsd/ in the following formats: RedHat-6.2 RPM - ftp://ftp.freevsd.org/freevsd/RPMS/freevsd-1.4.10-1rh6.i386.rpm SRPM - ftp://ftp.freevsd.org/freevsd/SRPMS/freevsd-1.4.10-1rh6.src.rpm Skel - ftp://ftp.freevsd.org/freevsd/skels/freevsd-skel-1.4.10-1rh6.tar.bz2 Pkgs - ftp://ftp.freevsd.org/freevsd/pkgs/freevsd-pkgs-1.4.10-1rh6.i386.rpm RedHat-7.1 RPM - ftp://ftp.freevsd.org/freevsd/RPMS/freevsd-1.4.10-1rh7.i386.rpm SRPM - ftp://ftp.freevsd.org/freevsd/SRPMS/freevsd-1.4.10-1rh7.src.rpm Skel - ftp://ftp.freevsd.org/freevsd/skels/freevsd-skel-1.4.10-1rh7.tar.bz2 Pkgs - ftp://ftp.freevsd.org/freevsd/pkgs/freevsd-pkgs-1.4.10-1rh7.i386.rpm SOURCE - ftp://ftp.freevsd.org/freevsd/SOURCES/freevsd-1.4.10-1.tar.gz For secure remote administration of virtual servers freeVSD implements secure encryption/authentication of control requests by default. SSL support in freeVSD is provided through the open-source SSL library OpenSSL (www.openssl.org) and there is a dependancy that OpenSSL-0.9.6 or higher and its development libraries are already installed on the system prior to installing freeVSD. If you do not have OpenSSL already installed on your server, suitable RPMs are provided as part of the freeVSD add-on packages, see above. Having installed the freevsd-pkgs RPM the OpenSSL RPMs can be installed using the following commands: # rpm -ivh /usr/share/freevsd/pkgs/openssl-0.9.6.i386.rpm # rpm -ivh /usr/share/freevsd/pkgs/openssl-devel-0.9.6.i386.rpm Advanced users who may not be making virtual servers available over the internet may choose to '--force' installation of the freeVSD RPMs or build from source using the '--without-openssl' configure option. In either case it will then only be possible to use the insecure plain-text VSD protocol which must be specifically enabled by specifying the '-p' option when executing vsd-install. 1.1. Recommended Installation -------------------------------- freeVSD installation consists of two stages. Installation of freeVSD server software and installation of a skel on which hosted virtual servers are based. For normal installation using a pre-built skel the following files are required: RedHat-6.2 RPM - ftp://ftp.freevsd.org/freevsd/RPMS/freevsd-1.4.10-1rh6.i386.rpm Skel - ftp://ftp.freevsd.org/freevsd/skels/freevsd-skel-1.4.10-1rh6.tar.bz2 RedHat-7.1 RPM - ftp://ftp.freevsd.org/freevsd/RPMS/freevsd-1.4.10-1rh7.i386.rpm Skel - ftp://ftp.freevsd.org/freevsd/skels/freevsd-skel-1.4.10-1rh7.tar.bz2 1.2. Alternative Installation -------------------------------- While it is recommended that a pre-built skel be downloaded and used for installation, skel files, despite being heavily compressed, are large (50MB+). For the bandwidth-challenged, freeVSD provides an alternative method whereby the skel is generated locally, based on the host server's own services and configuration. For this alternative installation in which the skel is generated locally the following, smaller files are required: RedHat-6.2 RPM - ftp://ftp.freevsd.org/freevsd/RPMS/freevsd-1.4.10-1rh6.i386.rpm Pkgs - ftp://ftp.freevsd.org/freevsd/pkgs/freevsd-pkgs-1.4.10-1rh6.i386.rpm RedHat-7.1 RPM - ftp://ftp.freevsd.org/freevsd/RPMS/freevsd-1.4.10-1rh7.i386.rpm Pkgs - ftp://ftp.freevsd.org/freevsd/pkgs/freevsd-pkgs-1.4.10-1rh6.i386.rpm If generating your skel locally using the provided addon packages it is strongly recommended that freeVSD be installed on a 'clean system' running a Red Hat Linux 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 only installed the standard server operating system and have carried out basic configuration to ensure your server can communicate with other computers via its local area network (LAN). This basic installation must include setting the server's fully qualified domain name and configuring /etc/resolv.conf to correctly reference the relevant name servers. Installing on a clean system is recommended because the freeVSD skel will be generated based on the hosting server's own services and configuration and a clean installation provides a starting point which is known to work. When virtual servers have been successfully established and tested it will be possible to begin customising the skel, which may then be transferred and used on other hosting servers. 1.3. Source Installation --------------------------- Installing freeVSD from source provides greater control over freeVSD's configuration, functionality and installed file locations. For an installation from source using a pre-built skel the following files are required: SOURCE - ftp://ftp.freevsd.org/freevsd/SOURCES/freevsd-1.4.10-1.tar.gz RedHat-6.2 Skel - ftp://ftp.freevsd.org/freevsd/skels/freevsd-skel-1.4.10-1rh6.tar.bz2 RedHat-7.1 Skel - ftp://ftp.freevsd.org/freevsd/skels/freevsd-skel-1.4.10-1rh7.tar.bz2 For an installation from source in which the skel is generated locally the following files are required: SOURCE - ftp://ftp.freevsd.org/freevsd/SOURCES/freevsd-1.4.10-1.tar.gz RedHat-6.2 Pkgs - ftp://ftp.freevsd.org/freevsd/pkgs/freevsd-pkgs-1.4.10-1rh6.i386.rpm RedHat-7.1 Pkgs - ftp://ftp.freevsd.org/freevsd/pkgs/freevsd-pkgs-1.4.10-1rh7.i386.rpm 1.4. Upgrading ----------------- The process of upgrading a freeVSD installation has been greatly simplified with the release of version 1.4.10. The script vsd-install has been enhanced and now includes a '-u' option that will attempt to upgrade the freeVSD configuration so that it is able to support all of the new features associated with this release. To upgrade an installation, install the freeVSD rpm using the following commands: # rpm -Uvh freevsd-1.4.10-1rh6.i386.rpm # vsd-install -u NOTE: It is not necessary to execute vsd-uninstall.pl before upgrading an installation. Doing so will remove all of your existing configuration. If you wish to use any of the new versions of the freeVSD packages you will also need to install the latest version of the freevsd-pkgs RPM before executing vsd-genskel.pl: # rpm -ivh freevsd-pkgs-1.4.10-1rh6.i386.rpm The upgrade process will perform the following steps: 1. The host server 'loopback' configuration will be inserted into the existing vsd.conf file, and the loopback link will be generated. 2. If a skel exists on any partition that has not been named, ie it resides on the partitions mount point skel directory, and not under a directory with the same name as the skel, a directory called skel will be created, the skel will be moved below it. This skel will then be registered with freeVSD and any existing virtual servers will be registered to this skel. 3. Each existing virtual server will have a HostingServer and a CertificateAuthorityServer entry added. 4. Any DNS configuration files produced by the mod_bind module will be moved to the /var/named/virtual directory, and all relevant paths in those files will be altered to point to this new directory. 5. Syslog will be configured so that all of the output from the svsd daemon will be logged to /var/log/vsd.log. 2. RPM Installation ------------------------ The following steps assume a RedHat-6.2 server installation. If installing onto a different server installation, ie RedHat-7.1, the appropriate tag, ie rh7, should be used in place of the rh6 tag stated. 2.1. Quick Start Installation -------------------------------- For the recommended installation using a pre-built skel execute the following commands. # rpm -ivh freevsd-1.4.10-1rh6.i386.rpm # mkdir -p /home/vsd/skel # tar -xIf freevsd-skel-1.4.10-1rh6.tar.bz2 -C /home/vsd/skel # vsd-install For the alternative installation in which the skel is generated locally, execute the following commands. # rpm -ivh freevsd-1.4.10-1rh6.i386.rpm # rpm -ivh freevsd-pkgs-1.4.10-1rh6.i386.rpm # vsd-genskel.pl # vsd-install To begin using freeVSD go to section 5, 'Getting Started'. 2.2. Detailed Installation ----------------------------- freeVSD installation consists of two stages. Installation of freeVSD server software and installation of a skel on which hosted virtual servers are based. To install freeVSD and install/generate a skel perform the following steps: 1. Install the freeVSD server software: # rpm -ivh freevsd-1.4.10-1rh6.i386.rpm This will install the freeVSD files to the following locations: /etc/vsd - configuration /usr/sbin - binaries and scripts /usr/doc/freevsd-1.4.10 - documentation 2. Create a mount point for the skel: # mkdir -p /home/vsd/skel This will be the location of the skel on which virtual servers will be based. It is important to ensure there is sufficient diskspace to accommodate the resulting skel which can be 500MB+ after being extracted. If performing the recommended installation using a pre-built skel, the next step is to extract the chosen skel into the skel directory. 3. Extract the pre-built skel: # tar -xIf freevsd-skel-1.4.10-1rh6.tar.bz2 -C /home/vsd/skel This will extract a complete server file system into a directory named skel beneath your chosen mount point to which virtual servers will be linked. If performing the alternative installation and generating a skel locally, the next step is to install the freeVSD addon packages before generating a skel locally based on the host server's own services and configuration. 3. Install the freeVSD addon packages: # rpm -ivh freevsd-pkgs-1.4.10-1rh6.i386.rpm This will install the freeVSD addon packages to the following location: /usr/share/freevsd/pkgs - addon packages 3.1. Generate a skel: A skel can be generated using the following command: # vsd-genskel.pl This command will generate a complete server file system in a directory named skel beneath you chosen mount point. The resulting skel will be based on the host server's own services and configuration. The command supports command line options for the name of the skel and the partition it is to be created on. See vsd-genskel.pl --help for further information. Finally, for both methods of installation some final system configuration is required. 4. Complete the installation configuration: # vsd-install This command will carry out the required system configuration changes for freeVSD. The command supports a number of options, see vsd-install --help, and uses sensible defaults if none are supplied. To begin using freeVSD go to section 5, 'Getting Started'. 3. Source Installation --------------------------- The following steps assume a RedHat-6.2 server installation. If installing onto a different server installation, ie RedHat-7.1, the appropriate tag, ie rh7, should be used in place of the rh6 tag stated. 1. Extract the freeVSD source: # tar -xzf freevsd-1.4.10-1.tar.gz # cd /usr/local/src/freevsd-1.4.10-1 2. Configure the build environment: # autoheader; autoconf; ./configure --enable-addons 3. Compile the source: # make 4. Install the compiled binaries and scripts: # make install This will install the freeVSD files to the following locations: /usr/local/etc/vsd - configuration /usr/local/sbin - binaries and scripts /usr/local/doc/freevsd-1.4.10 - documentation 5. Create a mount point for the skel: # mkdir -p /home/vsd/skel This will be the location of the skel on which virtual servers will be based. It is important to ensure there is sufficient diskspace to accommodate the resulting skel which can be 500MB+ after being extracted. If performing the recommended installation using a pre-built skel, the next step is to extract the chosen skel into the skel directory. 6. Extract the pre-built skel: # tar -xIf freevsd-skel-1.4.10-1rh6.tar.bz2 -C /home/vsd/skel This will extract a complete server file system into a directory named skel beneath your chosen mount point to which virtual servers will be linked. If performing the alternative installation and generating a skel locally, the next step is to install the freeVSD addon packages before generating a skel based on the host server's own services and configuration. 6. Install the freeVSD addon packages: # rpm -ivh freevsd-pkgs-1.4.10-1rh6.i386.rpm This will install the freeVSD addon packages to the following location: /usr/share/freevsd/pkgs - addon packages 6.1. Generate a skel: # vsd-genskel.pl This command will generate a complete server file system in a directory named skel beneath you chosen mount point. The resulting skel will be based on the host server's own services and configuration. The command supports command line options for the name of the skel and the partition it is to be created on. See vsd-genskel.pl --help for further information. Finally, for both methods of installation some final system configuration is required. 7. Complete the post-install configuration: # vsd-install This command will carry out the required system configuration changes for freeVSD. The command supports a number of options, see vsd-install --help, and uses sensible defaults if none are supplied. To begin using freeVSD go to section 5, 'Getting Started'. 4. Uninstalling -------------------- The following steps assume a RedHat-6.2 server installation. If freeVSD has been installed on a different server installation, ie RedHat-7.1, the appropriate tag, ie rh7, should be used in place of the rh6 tag stated. Uninstall freeVSD using the following command: # vsd-uninstall.pl This script will prompt for the freeVSD files, configuration and virtual servers to be removed, and whether to roll-back changes made by freeVSD to the following files: /etc/services /etc/inetd.conf (rh6) /etc/xinetd.conf (rh7) Default values can be accepted by pressing when prompted. To complete the removal of freeVSD from a system, if freeVSD or the addon packages were installed from RPM, they should now be removed using the following commands: # rpm -e freevsd-1.4.10-1rh6.i386.rpm # rpm -e freevsd-pkgs-1.4.10-1rh6.i386.rpm If freeVSD was installed from source any remaining installed files may be removed using the following commands: # cd /usr/local/src/freevsd-1.4.10-1 # make uninstall The freeVSD source tree may then be removed with the following command: # rm -rf /usr/local/src/freevsd-1.4.10-1 5. Getting Started ----------------------- Once freeVSD has been installed and a skel is in place, virtual servers can be created and tested. The svsdadm (Secure VSD Administrator) utility provides a command-line interface to VSD. Commands are grouped depending on which module they are implemented by and hence the configuration they manipulate. A list of the supported commands is given with the following command: # svsdadm ? This command lists each of the svsdadm commands currently available along with a brief description. By default freeVSD enables the svsd (VSD over SSL) service which listens on port 1726. All communications through the svsd service are encrypted and require proper authentication through the use of certificates. The command utility svsdadm handles the necessary encryption and authentication but requires that valid certificates are already in place. Certificates are created and managed by a VSD Certificate Authority (CA) which must be created on each hosting server. The steps involved in establishing a VSD CA are described below. If the hosting servers and virtual servers are already in a secure environment freeVSD can optionally be installed to use an un-encrypted, plain-text protocol, by specifying the '-p' option when executing vsd-install. If plain-text protocol is being used on all virtual servers it is not necessary to configure any VSD CA's and you can proceed to creating a virtual server, and in all subsequent examples, the call to 'svsdadm' should be replaced with a call to 'vsdadm'. 5.1. Creating a VSD Certificate Authority ----------------------------------------- The VSD CA provides the services to issue, store, manage and revoke certificates for hosting servers and virtual servers (VSD servers). The VSD CA ensures that when a connection is made to a secure VSD service the certificate supplied by the client to authenticate the connection is valid and was issued by the VSD CA. Create your VSD CA using the following command: # vsd-mkca This command will establish the CA directory structure beneath the VSD configuration directory, generate a private key for the CA and establish a certificate/key pair for the VSD server on which the VSD CA resides. The command will prompt for information which will be contained within the VSD CA and will be used to identify the certificates the VSD CA creates. You may accept the defaults by pressing but should provide accurate information for the following fields: Country Name State or Province Name Locality Organization Name The certificate key/pair which has been generated for the hosting server grants control access to all the virtual servers and domains which are hosted. The certificate/key pairs are held in the VSD CA but copies are also issued into the following locations, respectively: /etc/vsd/ssl.crt/ /etc/vsd/ssl.key/ Individual certificates granting access to specific virtual servers and domains as well as certificate revocation lists (CRL), root CA certificates and sub-CAs can also be generated and issued by a VSD CA. A list of the supported commands provided by the mod_ca modules is given with the following command: # svsdadm | grep ca For further information on managing a VSD CA see section 6.3, 'Secure VSD'. 5.1.1 Managing Multiple Hosting Servers --------------------------------------- svsdadm looks for host server certificates and keys in the following locations: /etc/vsd/ssl.crt /etc/vsd/ssl.key If a machine is to be used to issue requests to multiple hosting servers the relevant host server certificates must be retrieved from the corresponding directory on those machines and placed on the local machine. For further information on managing a VSD CA and manipulating certificates see section 6.3, 'Secure VSD'. 5.2. Creating a Virtual Server ------------------------------ Consider the following command: # svsdadm vs_create hostone vsone 192.168.10.11 vsone.net 200 0 5 skel This command adds a entry to the vsd.conf file in the VSD configuration directory and queues a request for the virtual server's file system to be generated. The syntax of the command can be displayed by executing the command as follows: # svsdadm vs_create ? To understand the command, it can be broken down as follows: svsdadm - command-line interface to VSD vs_create - specific command provided by the vs module hostone - name of hosting server on which virtual server is to be created vsone - unique name of virtual server 192.168.10.11 - unique IP address of virtual server vsone.net - fully qualified domain name (fqdn) of virtual server 200 - number of user IDs from the hosting server which are to be allocated to the virtual server 0 - quota of hosting server's disk space that is to be allocated to the virtual server (only effective when quota support has been enabled) 5 - number of virtual domains allowed to be registered skel - name of skel virtual server is to be linked to The creation of the virtual server's file system would normally be carried out by a scheduled batch process which would regularly service queued requests. To complete the creation of the virtual server specified above the batch process should be run interactively with the following command: # vsd-vsbatch.pl This command will service all queued requests and will create/delete the virtual servers which have been specified. During creation of the virtual server the virtual server's admin user is given a randomly generated password. This password would normally be emailed to the host server administrator on successful creation of the virtual server. The admin password for a virtual server may be explicitly set by the host server administrator as follows: [root@hostone /]# bevs vsone [admin@vsone /]# passwd -u admin -p foobar [admin@vsone /]# exit [root@hostone /] This sequence of commands places the host server root user into the specified virtual server as that virtual server's admin user. The password is then explicitly set before exiting the virtual server file system and returning back to the host server's. 5.3. Testing a Virtual Server -------------------------------- Start all virtual servers by issuing the following command: # vsboot --start Alternatively, start the individual virtual server you created above by issuing the following command: # vsboot --start vsone Connect to the different services offered by your new virtual server as follows: NOTE: If you have not established a lookup for your virtual server's fqdn, by adding an entry to your networks nameserver or adding an entry to /etc/hosts the fqdn in the following examples should be replaced by the IP address of the virtual server you are testing. [root@hsone /]# ftp vsone.net Connected to vsone.net. 220 ProFTPD 1.2.2rc2 Server (ProFTPD) [vsone.net] Name (vsone.net:userone): admin 331 Password required for admin. Password: 230 User admin logged in. Remote system type is UNIX. Using binary mode to transfer files. ftp> bye 221 Goodbye. [root@hsone /]# [root@hsone /]# telnet vsone.net Trying 192.168.10.11... Connected to vsone.net. Escape character is '^]'. Server vsone.net login: admin Password: [admin@vsone /]$ exit Connection closed by foreign host. [root@hsone /]# [root@hsone /]# telnet vsone.net smtp Trying 192.168.10.11... Connected to vsone.net. Escape character is '^]'. 220 vsone.net ESMTP Sendmail 8.9.3/8.9.3; Mon, 13 May 1996 19:15:11 GMT QUIT 221 vsone.net closing connection Connection closed by foreign host. [root@hsone /]# [root@hsone /]# telnet vsone.net pop3 Trying 192.168.10.71... Connected to vsone.net. Escape character is '^]'. +OK ready <4623.832015080@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. [root@hsone /]# [root@hsone /]# lynx vsone.net 5.4. Deleting a Virtual Server --------------------------------- Delete the virtual server you created above using the following command: # svsdadm vs_delete hostone vsone This command removes the corresponding entry from the vsd.conf file in the VSD configuration directory and queues a request for the virtual server's file system to be deleted. The syntax of the command can be displayed by executing the command as follows: # svsdadm vs_delete ? To understand the command, it can be broken down as follows: svsdadm - command-line interface (CLI) to VSD vs_delete - specific command provided by the vs module hostone - name of hosting server on which virtual server resides vsone - name of virtual server The deletion of the virtual server's file system would normally be carried out by the same scheduled batch process which services queued requests to create virtual servers. To complete the deletion of the virtual server specified above the batch process should be run interactively with the following command: # vsd-vsbatch.pl This command will service all queued requests and will create/delete the virtual servers which have been specified. 6. Getting Advanced ------------------------ freeVSD has many advanced features. Whilst none of these extra features are essential for the basic functionality of freeVSD, if you intend to use freeVSD in a production environment you will find most, if not all, will be required. 6.1. Quota Support --------------------- If you intend to use disk quotas for managing your virtual servers, you can either supply 'vsd-install' with a '-q' command line argument during the installation or, after installation, perform the following steps: 1. Enable quota support on your virtual server filesystems by editing /etc/fstab: # vi /etc/fstab Enable quota support for the filesystem on which your virtual servers will reside by modifying the appropriate entry in /etc/fstab. For example, if virtual servers are being generated beneath /home/vsd the entry corresponding to this location should be modified. The entry could refer to /home or / depending on the partitioning of your disk, eg. /dev/hda1 /home ext2 defaults 1 2 Modify the entry as follows: /dev/hda1 /home ext2 defaults,usrquota,grpquota 1 2 2. Generate quota files for the filesystems: # quotacheck -avug q 3. Enable quotas at startup by editing /etc/rc.d/rc.sysinit: # vi /etc/rc.d/rc.sysinit Locate the following line: action "Turning on user and group quotas for local filesystems" \ /sbin/quotaon -a Modify the line as follows: action "Turning on user and group quotas for local filesystems" \ /sbin/quotaon -avug 4. Reboot the server for changes to take effect: # reboot Check the resulting startup messages to ensure quotas are being correctly enabled. 6.2. VSD Security -------------------- If a hosting server has not been securely configured the server and all the virtual servers which it hosts may be vulnerable to a malicious attack. For this reason anyone intending to implement freeVSD in production setting should take the necessary steps to ensure their servers are secure. Allowing virtual server owners telnet/ssh access to virtual servers increases the possibility that a malicious user might gain root access of a hosting server. For this reason, telnet/ssh access should be strictly controlled and special care should be taken to secure machines on which telnet/ssh access is provided. This should include precautions against possible chroot exploits. 6.2.1 Securing Remote Access to VSD ------------------------------------- If you are running a non-SSL installation of freeVSD, it is strongly recommended that port 1725 be placed behind a firewall to protect access from external sites. If you are using the Linux 2.4 kernel running iptables, it is possible to set up an appropriate firewall using the following commands: # iptables -A INPUT -p tcp -s 1.2.3.4 --dport 1725 -j ACCEPT # iptables -A INPUT -p tcp -s 0/0 --dport 1725 -j REJECT If you are using the Linux 2.2 kernel running ipchains the following commands perform the same function: # ipchains -A input -p tcp -s 1.2.3.4 --dport 1725 -j ACCEPT # ipchains -A input -p tcp -s 0/0 --dport 1725 -j REJECT This would ensure that only one machine, with an IP address of 1.2.3.4, can perform remote administration of freeVSD. Such a machine would typically be a system administrator's machine or a web server on which the freeVSD web-administration scripts have been implemented. 6.2.3 Securing Apache ----------------------- The default Apache installation, provided in the sample site specific scripts, is defined to listen on port 8080 and 8443 for web traffic, and start as the user `web'. Originally the web server was started as user root (to listen on ports 80 and 443) and then made to drop its privileges and run as user `web'. However, two problems were found: A malicious admin user could create his own Apache module and edit 'httpd.conf' to start it. The module initialisation runs as user root, so it is possible to create a setuid '/bin/sh' directory. This would allow a user to operate as root and thus gain full access to the hosting server and all hosted virtual servers. Changing Apache's directives for CustomLog, ErrorLog or AccessLog to log to a pipe rather than a file, then the program that is on the other end of the pipe runs as root. Again, a malicious admin user could then create a setuid '/bin/sh' directory. The are several methods supplied with freeVSD to solve this problem, two of which address the problem of port forwarding, and the other is a patch that can be applied to the 2.2 kernel which allows any ordinary user to connect to port 80 and 443, so that Apache can be started on those ports as a non-root user. The default method of port forwarding is provided by 'vsdredirect'. A vsdredirect processes must be started from within /etc/rc for each port redirection. These processes are stopped along with all others when the virtual server is halted. Using vsdredirect port redirection is preferable to allowing the root exploits detailed above, however, it can delay virtual server reboots and cause problems with remote rebootvs requests. It also causes IP addresses of requesting clients to be incorrectly logged in virtual servers http access logs. The preferred method for port redirection, which avoids all of these problems, is to use iptables, see below. If you are using the Linux 2.4 kernel running iptables freeVSD will establish suitable port-forwarding if 'vsd-install' is executed with a '-t' command line argument. If freeVSD is already installed, the necessary port-forwarding can be setup by using the following commands: # iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080 # iptables -t nat -A PREROUTING -p udp --dport 443 -j REDIRECT --to-port 8443 If you are using the Linux 2.2 kernel an alternative arrangement using ipchains involves establishing a rule for each virtual server, so that both tcp and udp packets are forwarded to a unique port number for each virtual server. For example, your first virtual server on IP address 1.2.3.4 would require the following commands: # ipchains -A input --dst 1.2.3.4 --dport 80 -p tcp -j REDIRECT 8081 # ipchains -A input --dst 1.2.3.4 --dport 80 -p udp -j REDIRECT 8081 The default httpd configuration file /etc/httpd/conf/httpd.conf within the virtual server must then be modified to set the Port and Listening directives as follows: Port 8081 Listen 8081 Please note that the IP address has been removed from the 'Listen' directive. Finally, the relevant entries for vsdredirect should be removed from/etc/rc. The second virtual server, with IP address 1.2.3.5 would require the following commands: # ipchains -A input --dst 1.2.3.5 --dport 80 -p tcp -j REDIRECT 8082 # ipchains -A input --dst 1.2.3.5 --dport 80 -p udp -j REDIRECT 8082 And the following entries then need to be set in /etc/httpd/conf/httpd.conf Port 8082 Listen 8082 Please note that the IP address has been removed from the 'Listen' directive. Again, the relevant entries for vsdredirect should be removed from/etc/rc. However, this is far from ideal as each virtual server needs to be configured individually to listen on its own port. As a result of this, a patch is available in the freeVSD CVS tree for the 2.2 kernel which allows any user to bind to both ports 80 and 443 allowing Apache to be started as a normal user, on the correct ports. To apply the patch, the easiest method is to obtain a copy of the 2.2 kernel source rpm, replace the following file: /usr/src/redhat/SPECS/kernel-2.2.spec with: freevsd/patches/redhat-rpms/SPECS/kernel-2.2.spec Then the file containing the relevant patch needs to be copied to the following directory: /usr/src/redhat/SOURCES Then rebuild and install the new kernel RPM. 6.3. Secure VSD ------------------ VSD provides a framework for secure administration of VSD servers, using SSL. With the use of certificates, any "object" on a VSD server can be remotely and securely administered. The "object" could be a VSD hosting server, a VSD virtual server, a VSD hosted domain, or even an individual user account. In order to communicate remotely with VSD, it is necessary to associate a certificate/key pair with the item for authentication purposes. Secure administration allows an ISP or other organisation to provide its customers or clients with remote administration tools for their virtual servers and hosted domains, and provide them with certificates to authenticate access, ensuring that they and only they can administer their servers and domains. A certificate/key pair consists simply of a certificate and a key created by a Certificate Authority (CA). VSD allows the creation and management of CAs, capable of issuing and revoking these certificate/key pairs. Each VSD Server may have a Certificate Authority, used for creating certificates for virtual servers and domains hosted on that server. Alternatively, a single CA can be located on a dedicated VSD server, and all certificates for the hosting operation can be created from that single authority. For more details on the available options, see Section 6.3.2 - 'Certificate Storage/Distribution Models'. NOTE: VSD installs with SSL communications enabled and non-SSL communications disabled by default. This means that on a default installation, you must create a CA and valid certificate/key pair before issuing commands to the local VSD service. 6.3.1 Secure VSD Communication -------------------------------- In order to use a certificate/key pair for authenticating connections to a VSD Server, the certificate and key must have a `Common Name' (CN) matching the name of the item with which it will be associated. For example, a VSD Server named hsone.net would have a certificate named hsone.net.crt and a key name hsone.net.key. Similarly, a virtual server with an FQDN (Fully Qualified Domain Name) vsone.hsone.dmone.net would have a certificate named vsone.hsone.net.crt and a key named vsone.hsone.net.key. Both the certificate and the key must be present on the server end and on the client in order for successful authentication to occur. The authentication procedure is best described by example. Consider the following command: # svsdadm vs_details hsone.net This command instructs svsdadm to attempt a connection to the VSD server hsone.dmone.net. In order to attempt the connection svsdadm requires a local copy of the key file hsone.net.key and certificate file hsone.net.crt to be present in the /etc/vsd/ssl.key and /etc/vsd/ssl.crt directories, respectively. If either file is not present a connection cannot be attempted and an error will be reported. If the key file and certificate are found, svsdadm will use them to negotiate an SSL connection with the secure VSD service on hsone.net. The VSD service on hsone.net requires a local copy of the certificate file hsone.net.crt to be present beneath /etc/vsd/ssl.crt. If this certificate is found and confirmed to be valid (by authentication against the root CA certificate of the CA which issued it and the CRL of the CA which issued it) the connection can be authenticated and the request carried out. 6.3.2 Certificate Storage / Distributions Models -------------------------------------------------- There are two common models for the storage and distribution of VSD certificates: 1. Each VSD Server has its own CA 2. A single VSD server exists as a dedicated CA. In the first case, a CA is created on each VSD server and is used for issuing/revoking certificates for all virtual servers and domains on that server. In order to communicate with a given VSD server from another VSD Server, the certificate/key pair for the target server must first be exported to the requesting server. Since this scenario involves exporting the certificate/key of each VSD server to every other VSD Server, it is best suited to organisations with a small number of hosting servers. As the number of hosting servers increases, it could become cumbersome to export the necessary certificates. In the second case, a single VSD server exists as a dedicated CA. All certificates are created on this server and are then exported to the servers for which they are created. This scenario works well for organisations with larger numbers of hosting servers. It can also be useful for the primary nameserver to exist on the same machine as the CA, as this removes the need to export all created virtual server certificates to the nameserver. In either scenario, some exporting of VSD certificates is required to enable remote administration of each server. Sections 6.3.12 - 6.3.18 detail the commands and methods available for exporting certificates from one VSD server to another. 6.3.3 Certificate Authorities ------------------------------- In order for a VSD Server to manage certificates, a Certificate Authority must first be created on the server, see Section 5.1 - `Creating a VSD Certificate Authority'. Once created, certificates can be issued for virtual servers, virtual domains and other VSD Servers. However, it is also useful for a virtual server owner to be able to create certificates for domains hosted on that virtual server without intervention from the hosting server administrator, or ISP. To this end, VSD allows sub-CAs to be created on the virtual server level. Once created, the virtual server can then use a remote administration tool to connect to the virtual server and create certificates for domains hosted on that virtual server. See section 6.3.9 for details of how to create a sub-CA. 6.3.4 Certificate Hierarchy ----------------------------- In order to facilitate tiered remote administration, VSD operates a certificate hierarchy, which allows certificate/key pairs for VSD servers to be used to authenticate requests to child items. This means that a certificate for a hosting server can be used to remotely connect to a virtual server hosted on that hosting server and, similarly, that a certificate for a virtual server can be used to remotely connect to a domain hosted on that virtual server. This hierarchy makes remote administration of VSD over SSL a much simpler task, since an entire hosting server, including all virtual servers and domains on that hosting server can be administered with a single certificate/key pair, as opposed to requiring a certificate for each item. 6.3.5 Certificate Revocation ------------------------------ Issued certificates are set to expire after 1 year by default. However, there may be circumstances under which a certificate must be revoked before that period. For example, if a certificate is issued by an ISP to one of its clients, but that client withholds payment, the ISP may revoke the certificate to deny the client access to their services. Alternatively, if a certificate were compromised and became available to other parties, the certificate should also be revoked. When a certificate is revoked, an entry is added to the Certificate Revocation List (CRL) for the Certificate Authority that created the certificate. When a certificate is presented in a request, the appropriate CRL is checked by the Secure VSD service to ensure that the certificate has not expired or been revoked. If it has, the connection is refused. It is important to ensure that CRLs are regularly re-distributed from the relevant CAs and sub-CAs to all other VSD servers using certificates created by that authority. Section 6.3.17 -'Exporting CRLs' describes how a CRL can be exported from a CA. 6.3.6 Creating VSD Certificates --------------------------------- To create a certificate for use with VSD, use the following command: # svsdadm ca_certadd where is the VSD server on which the CA resides, is the name of the CA to which you wish to add a new certificate, and is the common name of the object to which the new certificate/key pair is to refer. The resulting unique certificate/key pair is registered in the CA database and stored within the VSD CA directory structure. Note that the supplied must be unique within the VSD CA database. If a certificate/key pair with the same already exists in the VSD CA database it must be deleted (revoked), before a new certificate with the same can be added. By default all VSD key/key pairs are valid for 1 year. After this period the certificate/key pair's validity expires. If a client attempts to establish a connection to a VSD server using a certificate/key pair that has expired (or has been revoked), the connection will be refused and an error logged on the VSD server. 6.3.7 Revoking VSD Certificates --------------------------------- To revoke a VSD certificate, use the following command: # svsdadm ca_certdel where is the VSD server on which the CA resides, is the name of the CA in which the certificate exists, and is the common name of the object to which the certificate/key pair to be revoked refers. The relevant certificate/key pair is flagged as revoked in the VSD CA database and can no longer be retrieved or issued. As part of the revocation process a new certificate revocation list (CRL) is generated by the VSD CA and should be distributed to the relevant VSD hosting server to allow subsequent connection attempts to be refused. If a client attempts to establish a connection to a VSD server using a certificate/key pair that has been revoked the connection will be refused and an error logged on the VSD server. 6.3.8 Listing VSD Certificates -------------------------------- To list the certificates belonging to a CA, use the following command: # svsdadm ca_certlist where is the VSD server on which the CA resides, is the name of the CA whose contents you wish to list, offset is the position in the list from which to start returning results and records is the number of records to return (maximum 250). 6.3.9 Creating sub-CAs ------------------------ To create a sub-CA, use the following command: # svsdadm ca_add where is the VSD server on which the top-level CA resides and is the name to be given to the new CA. Certificate/key pairs may now be created within this sub-CA. Any certificates/keys created and any CRLs generated are stored in the CA directory under ssl.crt/virtual/, ssl.key/virtual/ and ssl.crl/virtual/ respectively. 6.3.10 Deleting sub-CAs ------------------------ To delete a sub-CA, use the following command: # svsdadm ca_del where is the VSD server on which the top-level CA resides and is the name of the sub-CA to be deleted. Note that when a sub-CA is deleted, all certificates and keys created within that CA are also permanently deleted. 6.3.11 Listing sub-CAs -------------------------------- To list the sub-CAs on a VSD server, use the following command: # svsdadm ca_list where is the name of the top-level CA. 6.3.12 Distributing VSD Server Certificates -------------------------------------------- In order to securely administer one VSD server from another, it is necessary to import the certificate/key pair from the server you want to administer into the server you want to issue administrative commands from. The certificates should be transferred from the server you want to communicate with via any preferred method (such as scp, secure ftp, floppy disk) to the server you want to communicate from. The certificate should be put into the following directory on your server: RPM Install: /etc/vsd/ssl.crt/ Source Install: /usr/local/etc/ssl.crt/ while the key should be put into the following directory: RPM Install: /etc/vsd/ssl.key/ Source Install: /usr/local/etc/ssl.key/ Once the certificate and key have been retrieved, you can administer any object on that VSD server, and certificates/keys can be retrieved from or exported to that VSD server. 6.3.13 Export and Retrieval ---------------------------- If a certificate/key for an object is created by a CA on a different VSD Server than the object itself, it is necessary to put that certificate/key pair onto the VSD server hosting the object for authentication to take place. It is also necessary to put the CA certificate for the CA that signed (created) the certificate/key pair onto the VSD server. If the signing CA was itself created by a higher-level CA (that is, if it is a sub-CA), then the higher-level CA certificate must also be put onto the VSD server. This process must be continued until a top-level CA certificate resides on the VSD server hosting the object. In order for a user to administer an object using the object's certificate/key pair for authentication, it is essential that a complete chain of certificates exists on the VSD server as described above. If the chain is incomplete, or invalidated at any point connection will be refused. The commands provided by VSD for exporting certificate/key pairs, CA certificates and CRLs from one VSD server to another are detailed in the following sections. 6.3.14 Exporting VSD Certificates ---------------------------------- To export a certificate from one VSD server to another, use the following command: # svsdadm ca_certput where is the VSD server on which the CA resides, is the name of the CA in which the certificate exists, is the common name to which the certificate refers, and is the destination for the certificate. Similarly, to export the key: # svsdadm ca_keyput The certificate and key will be put into the CA directory structure under the ssl.crt/virtual and ssl.key/virtual directories respectively. 6.3.15 Retrieving VSD Certificates ----------------------------------- To retrieve a certificate from a VSD server, use the following command: # svsdadm ca_certget where is the VSD server on which the CA resides, is the name of the CA that created the certificate and is the common name to which the certificate refers. Similarly, to retrieve the key: # svsdadm ca_keyget Note that both of these commands pipe the server response to STDOUT. If you wish to save the certificate to a suitably named text file, the recommended syntax is as follows: # svsdadm ca_certget > .crt # svsdadm ca_keyget > .key 6.3.16 Exporting CA certificates --------------------------------- To export a root CA certificate from one VSD server to another, use the following command: # svsdadm ca_cacertput where is the VSD server on which the CA resides, is the name of the CA whose root certificate you wish to export and is the destination for the certificate. The CA root certificate will be put into the CA directory structure on the target server under the ssl.crt/virtual directory. 6.3.17 Retrieving CA Certificates ---------------------------------- To retrieve a CA root certificate, use the following command: # svsdadm ca_cacertget where is the VSD server on which the CA resides, and is the name of the CA whose root certificate you wish to retrieve. Note that this command pipes the server response to STDOUT. If you wish to save the certificate to a suitably named text file, the recommended syntax is as follows: # svsdadm ca_cacertget > -ca.crt 6.3.18 Exporting CRLs ---------------------- To export a CRL from one VSD server to another, use the following command: # svsdadm ca_cacrlput where is the VSD server on which the CA resides, is the name of the CA whose CRL you wish to export and is the destination for the certificate. The CRL will be put into the CA directory structure on the target server under the ssl.crl/virtual directory. 6.3.19 Retrieving CRLs ----------------------- To retrieve a CRL, use the following command: # svsdadm ca_cacrlget where is the VSD server on which the CA resides, and is the name of the CA whose CRL you wish to retrieve. Note that this command pipes the server response to STDOUT. If you wish to save the certificate to a suitably named text file, the recommended syntax is as follows: # svsdadm ca_cacrlget > .crl 6.3.20 Example Configuration ----------------------------- As stated previously, there are two main options for certificate and storage distribution. The first involves having a Certificate Authority on every machine; the second involves having a single Authority on a dedicated VSD Server. The following examples detail the basic configuration for each of these cases: 6.3.21 Multiple CAs -------------------- For simplicity, this example details the setup for two hosting servers each capable of administering the other. The example can be easily extrapolated to more hosting servers. 1. Install VSD on each of two servers, with FQDNs hsone.net and hstwo.net. 2. If your primary nameserver is located on another machine and you wish to use VSD to manipulate your nameserver, then install VSD on your nameserver. We will assume that the FQDN of the nameserver is nsone.net 3. Generate the top-level CA on each server (and the nameserver if appropriate) # vsd-mkca Generating the Certificate Authorities will also generate certificate/key pairs for each hosting server. 4. For each hosting server, copy the resulting VSD certificate/key pairs to each of the other hosting servers you are configuring, including the nameserver if appropriate (you do not need to copy the nameserver certificate/key pair unless you intend to perform administration tasks on the hosting servers from the nameserver). 5. If you have installed VSD on your nameserver, you need to issue the CA certificate and CRL for the top-level CA on each hosting server to the nameserver: # svsdadm ca_cacertput hsone.net hsone.net nsone.net # svsdadm ca_crlput hsone.net hsone.net nsone.net # svsdadm ca_cacertput hstwo.net hstwo.net nsone.net # svsdadm ca_crlput hstwo.net hstwo.net nsone.net You are now in a position to perform administration tasks for any of your hosting servers and your nameserver from any other hosting server. However the following maintenance tasks must be performed: * Whenever a new hosting server is added, its certificate/key pair must be distributed to every other hosting server and to the nameserver. Also, the CA certificate and CRL must be exported to the nameserver. Finally, to allow the secure transfer of certificates between all hosting servers the certificate/key pairs for all other hosting servers must be copied to the new hosting server. * If a sub-CA is created on any hosting server, the CA certificate for that authority must be issued to the nameserver. * Whenever a certificate is created for a virtual server (or any other object that requires nameserver entries), that certificate must be exported to the nameserver. * All CRLs should be regularly exported to the nameserver. 6.3.22 Single CA / Nameserver ------------------------------ This example details the case where a single CA exists on a dedicated VSD Server, which also maintains the primary nameserver for the ISP. Note that if the nameserver was to be located on a different server, you would need to install VSD on that server also, and export all certificate/key pairs, CA certificates and CRLs to that server, as described in the previous example. 1. Install VSD on two hosting servers with FQDNs hsone.net and hstwo.net and a third server, caone.net. The latter is to be used as the dedicated CA/Nameserver. 2. Generate the top-level CA on each server (and the nameserver if appropriate) # vsd-mkca Generating the Certificate Authorities will also generate certificate/key pairs for each hosting server. 3. Copy the certificate/key pair generated for each hosting server to the CA server. 4. Export the certificate/key pair, CA certificate and CRL from the CA server to each hosting server. You are now in a position to perform administration tasks for any of your hosting servers from your CA server. The CA server could be seen as a gateway to each of the other servers. However, the following maintenance tasks must be performed: * Whenever a new hosting server is added, its certificate/key pair must be copied to the CA server. Also the top-level certificate/key pair, CA certificate and CRL of the CA server must be exported to the new hosting server. * Whenever a virtual server or virtual domain is created, a certificate/key pair must be created for that object on the CA server and exported to the host server on which the object was created. * Whenever a sub-CA is created on the CA server, the CA certificate and CRL must be exported to all hosting servers that are to host objects to which certificates created in the new sub-CA are to be associated. It is a good idea to export to all hosting servers irrespective of whether you expect there to be a correlation. * All CRLs on the CA server should be regularly exported to all hosting servers. 6.3.23 VSD SSL Configuration ----------------------------- VSD SSL configuration is taken from the openssl.cnf file. VSD will search for the openssl.cnf file to use according to the following order: Environment variable: VSD_OPENSSL_CONF Environment variable: OPENSSL_CONF Environment variable: SSLEAY_CONF Location: /etc/vsd/openssl.cnf Location: /usr/local/etc/vsd/openssl.cnf Location: /etc/ssl/openssl.cnf Location: /usr/local/etc/ssl/openssl.cnf The VSD CA integrates with the ca application provided with OpenSSL. For details of the openssl.cnf configuration file and the applications utilized by VSD CA, see the following man files: openssl(1) ca(1) req(1) x509(1) config(5) VSD CA supports three additional entries in [ ca ] sections of openssl.cnf which are described as follows: keys = $certs # Where the issued keys are kept crls = $certs # Where the issued crls are kept cacerts = $certs # Where the issued CA root certs are kept In the simplest case (where only one certificate authority is used or supported) these may all be set to the standard 'certs' directory, as shown. 6.4. Skels ------------- The functionality provided with freeVSD to manipulate skels consists of a subset of commands provided by the mod_part module and the vsd-linkvs.pl perl script. 6.4.1 Managing skels ---------------------- To register a skel with VSD, the following command needs to be executed: # svsdadm part_skeladd This adds a skel entry to the relevant partition section with the name to the VSD hosting server . Once a skel has been registered, an existing virtual server can be migrated to this new skel by executing the vsd-linkvs.pl script: # vsd-linkvs.pl -v -s The script first unlinks the virtual server from its existing skel, leaving the /home /etc directories intact, and then links the virtual server to the skel called . This has the effect of making any of the utilities that are included in the skel , that were not included in the original skel, available to the virtual server. Before a skel can be registered it needs to be created, which can be done either by using the vsd-genskel.pl script, or by downloading a pre-built skel. 6.4.2 Customising skels ------------------------- At present there is no functionality provided by freeVSD to customise a skel, however, using the rpm command, combined with the '--root' argument, standard redhat RPMs can be installed into a skel. To do this, the host server's /var/lib/rpm directory needs to be copied into the skel's file system: # cp -r /var/lib/rpm /home/vsd/skel/skel_upgrade/var/lib # rpm --root /home/vsd/skel/skel_upgrade utility_to_add.i386.rpm These two commands will install the utility_to_add.i386.rpm into the skel named skel_upgrade. It is highly recommended that before customising a skel, if it is in use, to make a copy of the original, install the new utilities into the copy and then migrate virtual servers to the new skel. 6.4.3 The mod_part command set -------------------------------- The list of commands provided by the mod_part module are as follows: part_skeladd - Register a new skel within an existing partition part_skeldel - Unregister an existing skel from a partition part_setskelglobal - Register the skel 'skel name' to be the global skel part_delskelglobal - Unregister the skel 'skel name' from the global section part_skellist - List all of the defined skels part_setskelvs - Set the skel definition for a virtual server 6.5. Virtual Domains and Users. -------------------------------- Virtual users are users on the virtual server that do not have any "real" account on the machine, this enables you to set up POP3 mail for users on the system, whilst at the same time having a user with a actual shell/ftp login sharing the same login name. This is achieved via the third party package vm-pop3d which instead of using the default UNIX /var/spool/username uses /var/spool/virtual//username. This allows you to have multiple domain names, and multiple usernames. For example, Bob has an account bob@fly-bob-pop3.com and also bob@freevsd-rocks.com, but little known to Bob, both accounts are on a virtual server, on the same machine. The spool directories would look like this; /var/spool/virtual /fly-bob-pop3.com/bob /freevsd-rocks.com/bob 6.5.1 Initial Configuration. ---------------------------- vm-pop3d has been modified so the log format allows pop before SMTP authentication, and is hereafter referred to as vm-pop3d-vsd. vm-pop3d-vsd is included with the freevsd-pkgs rpm and installed in freevsd-skel-1.4.10-1rh6.tar.bz2. If you are using freevsd-skel-1.4.10-1rh6.tar.bz2 please skip to Section 6.5.2. If you are not using a suitable pre-built skel but already have a skel or virtual server you wish to use then please see Section 6.4.2, 'Customising Skels', for instructions on how to install the RPM into your existing skel/virtual server. 6.5.2 Daemon Configuration. --------------------------- Firstly, vm-pop3d needs to be uncommented/enabled in /etc/inetd.conf/xinetd.conf and should look similar to this: (inetd) vsd stream tcp nowait root /usr/local/sbin/virtuald tcpd /usr/local/sbin/vsd svsd stream tcp nowait root /usr/local/sbin/virtuald tcpd /usr/local/sbin/vsd ftp stream tcp nowait root /usr/local/sbin/virtuald tcpd /usr/sbin/proftpd -d -l telnet stream tcp nowait root /usr/local/sbin/virtuald tcpd /usr/sbin/in.telnetd #pop-3 stream tcp nowait root /usr/local/sbin/virtuald tcpd /usr/sbin/in.qpopper pop-3 stream tcp nowait root /usr/local/sbin/virtuald tcpd /usr/sbin/vm-pop3d -i --group admin --user admin --debug=5 smtp stream tcp nowait root /usr/local/sbin/virtuald tcpd /usr/sbin/sendmail -bs (xinetd) service pop-3 { socket_type = stream protocol = tcp wait = no user = root server = /usr/sbin/virtuald server_args = /usr/sbin/vm-pop3d -i --group admin --user mail --debug=5 disabled = yes <-- ****remove this line entirely.**** } 6.5.3 Pop before SMTP authentication. ------------------------------------- freeVSD includes the third party "popauthd" collection of scripts, which allow POP before SMTP authentication allowing relaying for "roaming" users. Popauthd works simply by monitoring /var/log/maillog, watching for a successful POP3 login, when it finds one, it adds that users IP address to the sendmail access database, which then allows that user to send mail. Situations where this can be useful are for instance when a Virtual pop3 user (or actual user) dials in from home or from any host that is not part of your local domain(s). Popauthd has included crontab entries that: 1. Remove stale entries from the sendmail access database (set to one day but can be set to any value if required). 2. Restart Popauthd after a log rotation, so that popauthd will continue to read the correct log file (not the rotated one). If you choose to use Popauthd with either vm-pop3d or Qpopper you will need to edit crontab, and rc.conf. These files are located in: /etc/ (on a virtual server) or /usr/local/share/freevsd/skel-repo/etc/ (on the vsd server) You can either edit these files on a per virtual server basis, or edit the files in /usr/local/share/freevsd/skel-repo/etc/ so that every virtual server you create thereafter will have those changes included. Popauthd scripts and documents are located in /etc/mail/POPauthd please read them for further understanding. NOTE: Popauthd, is by default configured to operate with vm-pop3d-vsd, if you wish to use Qpopper and do not wish to have Virtual POP3, then you must rename the popauthd script that is modified to vm-pop3d log format like so; cd /etc/mail/POPauthd mv popauthd popauthd-vm-pop3d-vsd mv popauthd.orig popauthd Remember to check your (x)inetd.conf to ensure the correct daemon is enabled. 6.5.4 Adding Domains and Users. -------------------------------- Adding virtual users and domains, is a simple process of five steps. 1. Create a virtual domain. # svsdadm vd_add hsone.net vsone vdone.net 50 50 50 2 2. Add a virtual user to the domain. # svsdadm vuser_add hsone.net vdone.net vusrone 3. Add a mailbox for the virtual user. # svsdadm vuser_mbxadd hsone.net vdone.net vusrone mypassword 4. Enable the mailbox. # svsdadm vuser_mbxenable hsone.net vdone.net vusrone 5. Set the default forwarder for the virtual user to the enabled mailbox. # svsdadm vuser_dfltadd hsone.net vsone.net vusrone vusrone NOTE: If the default is not set mail will be passed to the domains admin user. The new virtual user can be tested by sending a message as follows: # bevs -r vsone # mail -v -s testing vusrone@vdone.net This is a test (CTRL-D) All being well this message will be delivered to the following file: /var/spool/virtual/vdone.net/vusrone The message can be retrieved remotely by connecting to the relevant virtual server with a mail client and logging in as 'vusrone"vdone.net'. 6.5.5. Autoresponders. ---------------------- For an existing virtual user, autoresponders can be configured in two steps: 1. Define an autoresponder message. # svsdadm vuser_msgadd hsone.net vdone.net vusrone myresponse 2. Set the autoresponder message. # svsdadm vuser_msgset hsone.net vdone.net vusrone myresponse myfile.txt