freeVSD User's Guide ==================== 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 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. This document describes the freeVSD specific configuration files, and the commands available to the host server & virtual server administrators. This document uses several formatting conventions to make reading easier. Angled brackets are used to mark sections in the configuration files, for example . Optional arguments are shown through square brackets in various parts of the document. This document also contains 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. FreeVSD Configuration Files =========================== /etc/freevsd.conf ----------------- The account creation scripts use this configuration file as a reference to parameters and directories for the creation and configuration of virtual servers. The following is a description of each directive: 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. mail_addr = This is the e-mail address where an e-mail should be sent to when a virtual server has been created. mail_template = 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. os_skelrepo = /skel-repo> Pathname to the skel that holds operating system-specific files. site_skelrepo = /skel-repo> Pathname to the skel that holds virtual server site-specific files. This is optional. site_skel_install = Pathname to the Perl script that does the site specific work on creating the virtual server skel. This is optional. site_vs_install = Pathname to the Perl script that performs the site specific phase of virtual server creation. This is optional. add_ons = 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'. 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. 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. /etc/vsd.conf ------------- When executed, freeVSD applications read their configuration information from /etc/vsd.conf. NOTE: Comments are denoted by a `#' at the beginning of a line. There are three major sections in the vsd.conf file: ... ... ... Each of the sections are described as follows: Global Syntax: ... 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. Partition Syntax: ... 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. Virtual Server Syntax: ... 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. Managed Domain Syntax: ... Context: None Description: The domain section declares the various variables associated with the different configurable options within a freeVSD managed virtual domain. Complete list of valid directives --------------------------------- BWLimit Syntax: BWLimit 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 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). Skel Syntax: Skel Default: none Context: Global, Partition, Virtual Server Description: This either defines the name of the skel as the default for all newly created virtual servers (Global), states that a skel of that name is available on the particular partition (Partition), or the name of the skel that the virtual server is linked to (Virtual Server). Hosting Server Syuntax: HostingServer Default: none Context: Virtual Server, Virtual Domain Description: This defines the name of the machine that the virtual server physically resides on or the name of the virtual server that a virtual domain resides on. CertificateAuthorityServer Syntax: CertificateAuthorityServer Default: none Context: Virtual Server Description: This defines the name of the of the machine that is the certificate authority server. MaxVD Syntax: MaxVD Default: none Context: Virtual Server Description: This defines the maximum number of Virtual Domains allowed to created on the virtual server. MaxIP Syntax: MaxIP Default: none Context: Virtual Server Description: This defines the maximum number of IPs that can registered to the virtual server. MaxVUser Syntax: MaxVUser Default: none Context: Virtual Domain Description: This defines the maximum number of virtual users allowed on a particular virtual domain. MaxVMailbox Syntax: MaxVMailbox Default: none Context: Virtual Domain Description: This defines the maximum number of virtual mailboxes allowed on a particular virtual domain. MaxVMesg Syntax: MaxVMesg Default: none Context: Virtual Domain Description: This defines the maximum number of autoresponder messages allowed for a particular virtual user on a virtual domain. Example vsd.conf file --------------------- An typical vsd.conf file might look like this. PrimaryNS ns1.isp.net SecondaryNS ns2.isp.net ErrorLog /var/log/vsd.log UIDRange 1000 30000 UIDAllocChunk 300 BWLimit 32Kbit BWBurst 256Kbit Skel skel Mount /virtual/disk0 MaxVS 40 Skel skel Mount /virtual/disk1 MaxVS 50 IP 1.2.3.4 StartUID 1000 Users 200 Quota 300 MaxVD 4 MaxIP 2 Partition 0 Status active PrimaryNS ns1.isp.net SecondaryNS ns2.isp.net AliasIP 1.2.3.5 AliasIP 1.2.3.6 BWLimit 6Kbit BWBurst 12KBit StartUID 1000 Users 3 MaxVUser 30 MaxVMailbox 30 MaxVMesg 1 HostingServer vsclient Host Server Administration Commands =================================== Create a virtual server ----------------------- Syntax: svsdadm vs_create Where is the FQDN of the host server, eg 'host.isp.net' is the name of the virtual server, eg 'vsclient' is the IP address of the virtual server to be created is the FQDN of the virtual server to be created is the number of UIDs allocated to the virtual server is the total quota allocated to the virtual server NOTE: When this command is issued, the virtual server is queued for creation in /tmp/vsd.accounts and its configuration parameters placed in /etc/freevsd.conf. This command must be issued once for each of the virtual servers you wish to create example usage: $ svsdadm vs_create host.isp.net client 192.168.28.1 client.net 200 100 Delete a virtual server ----------------------- Syntax: svsdadm vs_delete > Where is the FQDN of the host server, eg 'host.isp.net'. is the name of the virtual server, eg 'vsclient' NOTE: When this command is issued, the virtual server is queued for deletion in /tmp/vsd.accounts and its configuration parameters removed from /etc/freevsd.conf. This command must be issued once for each of the virtual servers you wish to delete. example usage: $ svsdadm vs_delete host.isp.net client Running the batch processing script ----------------------------------- Syntax: vsd-vsbatch.pl Upon execution of this script, all virtual servers queued for creation or deletion are processed accordingly. This command can take several minutes to execute depending on your hardware and the number of virtual servers to be processed. example usage: $ vsd-vsbatch.pl Starting a virtual server ------------------------ Syntax: vsboot --start [ ...] Where is the name of the virtual server, eg 'vsclient' This command starts all of the virtual servers specified. If no virtual server is specified the script attempts to start all virtual servers on the host server. example usage: $ vsboot --start vsclient Stopping a virtual server ------------------------- Syntax: vsboot --stop [ ...] Where is the name of the virtual server, eg 'vsclient' This command stops all of the virtual servers specified. If no virtual server is specified the script attempts to stop all virtual servers on the host server. NOTE: This command simply stops the virtual server. It does not prevent the virtual server administrator from restarting it. If you need to prevent this from happening, please see below : 'Temporarily disabling a virtual server'. example usage: $ vsboot --stop vsclient Restarting a virtual server --------------------------- Syntax: vsboot --restart [ ...] Where is the name of the virtual server, eg 'vsclient' This command restarts all of the virtual servers specified. If no virtual server is specified the script attempts to restart all virtual servers on the host server. example usage: $ vsboot --restart vsclient Login to a virtual server without providing a password ------------------------------------------------------ Syntax: bevs [-r] Where is the name of the virtual server, eg 'vsclient' This command enables the host server administrator to log into a virtual server as the 'admin' user without having to provide a password. The '-r' option enables the host server administrator to log in to a virtual server as the 'root' user. Type 'exit' to leave the virtual server environment. example usage: $ bevs vsclient Temporarily disabling a virtual server -------------------------------------- Syntax: svsdadm vs_disable Where is the FQDN of the host server, eg 'host.isp.net' is the name of the virtual server, eg 'vsclient' This command stops the specified virtual server and prevents the virtual server administrator from restarting it. NOTE: Before disabling a virtual server it should be stopped using the 'vsboot --stop' command. example usage: $ svsdadm vs_disable host.isp.net vsclient Re-enabling a virtual server ---------------------------- Syntax: svsdadm vs_enable Where is the FQDN of the host server, eg 'host.isp.net' is the name of the virtual server, eg 'vsclient' This command enables the virtual server to be started agin, but does not actually restart the virtual server. This must be done using the 'vsboot --start' command. example usage: $ svsdadm vs_enable host.isp.net vsclient Virtual Server Administration Commands ====================================== The virtual server administrator has the ability to configure most services running within the virtual server environment, however these are beyond the scope of this document. The following commands are freeVSD-specific, that is, supplied by freeVSD in order to simplify many common housekeeping tasks such as: Adding/removing users Changing user passwords Managing user privileges Managing user quotas Rebooting a virtual server Adding a user ------------- Syntax: useradd Where is the name of the user to be added This command creates a new user within the virtual server environment. Each user created within the virtual server must have a unique name. example usage: $ useradd bob Removing a user --------------- Syntax: userdel Where is the name of the user to be removed This command removes a user from the virtual server environment. example usage: $ userdel bob Setting/changing a user's password ---------------------------------- Syntax: passwd Where is the name of the user whose password is to be modified This command will prompt twice for a password and then modify /etc/passwd accordingly. example usage: $ passwd bob Managing user privileges ------------------------ Syntax: setrights <+|-> [<+|-> ...] Where is the name of the user to be managed is the privilege to be added or removed 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 NOTE: '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 main `bin', `etc' and `lib' directories on the virtual server. The `FTP' privilege must have previously been assigned to a user before the `chrtFTP' privilege can be assigned. example usage: $ setrights bob +gcc +net +mail Listing user privileges ----------------------- Syntax: listrights [] Where is the name of the user to be displayed This command displays the privileges assigned to the specified user. If no username is supplied, the access rights for all users on the virtual server will be displayed. example usage: $ listrights bob Managing user quotas -------------------- Syntax: setquota [<+|->] Where: is the name of the user to be modified This command sets the quota assigned to a user. The quota can be adjusted by an absolute value or relatively by prefixing a + or - to the parameter. NOTE: The cumulative total of soft limit quota allocation for each user cannot exceed the soft limit allocation for the virtual server itself. example usage: $ setquota bob 100K Listing user quotas ------------------- Syntax: quotastats [] Where is the name of the user to be displayed This command lists the quota assigned to a user of the virtual server. If no user name is supplied, a summary of all quota usage on the virtual server is displayed. example usage: $ quotastats bob Rebooting a virtual server -------------------------- Syntax: rebootvs When this command is issued, all processes running on the virtual server are terminated, and those scheduled for automatic startup are reinitialised. example usage: $ rebootvs