#============================================================================# # vHost - one-step solution for all virtual hosting needs # # README - read me! # # # # Copyright(c) Chaogic Systems, LLC. http://chaogic.com # # Author: Jake Fan # # # # This is Free Software; permission to use, copy, modify, and distribute # # this software and its documentation for any purpose - with or without fee # # - is hereby granted, provided that the above copyright information and # # this permission notice appear in all copies and documentations. This # # software is provided "as is" without express or implied warranty. For # # more details, see GNU General Public License as published by the Free # # Software Foundation. # # # #============================================================================# This distribution includes: ChangeLog - changes since version 3.00r0 Makefile - make install/clean README - this file bin/ - directory for post-install third party binaries src/ - directory for third party packages src/IO-Tty/ - IO-Tty perl module, by Roland Giersig et.al. src/Quota/ - Quota perl module, by Tom Zoerner src/phpWebFTP/ - web-based ftp client, by Edwin van Wijk src/vmail/ - vpop3d/vdeliver, by Jacques Gélinas vhost.cc - setuid c wrapper, front-end for /usr/sbin/vhost.pl vhost.d/ - default profile directory vhost.d/V00hostconf - host/dns configuration vhost.d/V01network - network virtualization module vhost.d/V10apache - apache virtualization module vhost.d/V15proftpd - proftpd virtualization module vhost.d/V15wu-ftpd - wu-ftpd virtualization module vhost.d/V20postfix - postfix virtualization module vhost.d/V20sendmail - sendmail virtualization module vhost.d/V25pop3d - pop3d virtualization module vhost.d/V30openwebmail - openwebmail virtualization module vhost.d/V30squirrelmail - squirrelmail virtualization module vhost.d/V35awstats - awstats virtualization module vhost.d/V35webalizer - webalizer virtualization module vhost.d/V40mysql - mysql virtualization module vhost.d/Vxxsample - module template vhost.pl - core module, host/dns virtualization module vhost.web/ - directory for the web gui vhost.web/index.php vhost.web/vhost.img/ - directory for web gui image files vhost.web/vhost.img/foot00.gif vhost.web/vhost.img/head00.gif vhost.web/vhost.img/head01.gif vhost.web/vhost.img/head02.gif vhost.web/vhost.img/spacer.gif vhost.web/vhost.inc/ - directory for web gui include/configuration files vhost.web/vhost.inc/auth.inc vhost.web/vhost.inc/clog.inc vhost.web/vhost.inc/conf.inc vhost.web/vhost.inc/foot.inc vhost.web/vhost.inc/head.inc vhost.web/vhost.inc/hlog.inc vhost.web/vhost.inc/page.inc vhost.web/vhost.inc/user.inc vhost.web/vhost.php - web gui main script vmake - install/upgrade module INSTALL/UPGRADE: To install or upgrade vHost, login as root and run "make install" under the unpacked directory. The installation is successful when it shows the message "installation completed". After "press ENTER to continue", you may encounter a few error messages, which means that you will need to make adjustments to certain configuration variables. The error messages, which can be repeated by running command "/usr/sbin/vhost", will indicate exactly which module files and configuration variables need to be changed. Open each module in a text editor and make changes to relavant variables according to their comments. The system is properly configured when the command usage info appears while running "/usr/sbin/vhost". Note that third-party packages required for virtual services such as Apache, SquirrelMail etc. are not included in this distribution. Make sure those packages are installed and working properly on the system. If you get the "invalid main host name" error while installing, it means that your system's main host name is not a Fully Qualified Domain Name (FQDN) in the form of "host.domain.com". An FQDN is necessary for a host to be uniquely identifiable on the internet. For testing purposes, you can change the main host name to an FQDN like "myhost.com" and put an entry in "/etc/hosts", and vHost will stop complaining. The main host name can be changed with command "hostname myhost.com", or edit "/etc/sysconfig/network" on RedHat or derived systems (other systems vary) to make the change permanent. The entry in "/etc/hosts" should look like "[ip_address] myhost.com", where "[ip_address]" is the main host's IP address. When upgrading from vHost versions older than 3.10, there will be a lengthy but crucial process which updates existing virtual hosts. Please allow the process to finish. If interrupted, it can be resumed with "make install". The update is done by calling command "vhost --uphost", which will rewrite virtual hosts' configurations, among other things. For instance, Apache virtual hosts added in "httpd.conf" will be rewritten with the contents of $apacheC (in "/etc/vhost.d/V10apache"). One side-effect of this behavior is that manual changes made to a virtual host's configurations will be lost. If this is undesired, simply comment out the "# keep this line - by vhost" part (put another "#" in front of the line) for a particular virtual host and it will not be touched by "vhost --uphost". KNOWN ISSUES: The latest shadow-utils package on Linux systems changes the username length limit from the previous 32 to 31. $unameLen (in "/etc/vhost.d/V00hostconf") will be changed accordingly on new vHost installations. Generally speaking, it is important to check the settings of $unameLen and $dotChar to make sure they work on a particular system. Command "vhost --cphost" is not compatible between vHost versions lower than 3.30 and 3.30 or higher. A simple upgrade will solve the problem. It will also have problems when copying virtual hosts between systems with different $dotChar or $unameLen (in "/etc/vhost.d/V00hostconf") settings. For example, if the original system has $dotChar and $unameLen set to "." and "32", but the destination system does not support "." in usernames or has shorter username length limit, alternative logins will not be duplicated at the destination. The default SELinux configuration on most systems has problems in the Apache policy which breaks various aspects of CGI/PHP (shell command execution, tmp file access, MySql connection, etc.) and does not work well with vHost. For that reason, the Apache policy will be disabled during vHost installation ("httpd_disable_trans" set to 1). Extensive SELinux support in vHost will likely be implemented in the future when SELinux becomes more matured for production environments. The "pop relay" feature only works for pop clients authenticated via vpop3d. If a virtual host's IP address does not resolve back to a virtual host on the system (the two hosts do not need to be the same), vpop3d will hand the pop connection to the default pop3 daemon ($pop3d in "/etc/vhost.d/V25pop3d"), and "pop relay" will not work. If that is the case, simply add the main host (or whatever host the IP address resolves to) as a virtual host. It's a good idea to do so anyway on a virtual hosting system. However, beware that this will disable pop authentication for NIS/LDAP users (if NIS/LDAP is enabled), since vpop3d only works with the local passwd/shadow files. The MySql module is disabled by default. To enable the module, run command "mv /etc/vhost.d/X40mysql /etc/vhost.d/V40mysql". Existing virtual host owners (who will also be database owners) will have their MySql passwords set to blank as databases being added. Command "vhost --passwd" can be used to synchronize host owners' MySql passwords to their main login passwords. Newly added host owners will have their passwords automatically synchronized. Some versions of RedHat 8/9 and derived systems have a known bug related to Perl 5.8 regular expression and UTF-8 encoding. If you experience problems on such a system, try setting environment variable "export LANG=C" (sh style) or "setenv LANG C" (csh style) before running vHost commands. To fix this permanently, edit "/etc/sysconfig/i18n" and remove ".UTF-8" from the end of the "LANG=..." line, and reboot the system. QUICK START: Assuming vHost is installed with virtual web enabled, login as root and run the following command-line sequence: mv /etc/hosts /etc/hosts.0 ln /etc/vhosts /etc/hosts vhost addhost test.com test -f vhost lshost mozilla http://test.com #open "http://test.com" in a web browser mv /etc/hosts.0 /etc/hosts MISCELLANEOUS: To uninstall vHost, run "/usr/sbin/vhost --uninstall". To access the web gui, use "http://main-or-virtual.host.name/admin". For version info, run "/usr/sbin/vhost --version". For history info, run "/usr/sbin/vhost --history". For the most up-to-date documentation and discussion, visit: http://chaogic.com/vhost/documentation http://chaogic.com/vhost/forum