Virtualmin can be installed in a number of ways, including an automated install script which uses the standard package management features of your OS, and software repositories containing our software in native package formats. We strongly recommend that you use the automated install script to install Virtualmin, if at all possible.
Automated Installation - Installation of the full Virtualmin stack using our automated install script. This is the recommended way to install Virtualmin.
Manual Installation - Installation of Virtualmin and related packages manually. This method is time-consuming, and requires a high level of technical experience. This is not recommended, except in cases where the automated installation is inappropriate or impossible.
Installation Troubleshooting - Troubleshooting common problems encountered during installation.
Uninstalling Virtualmin - Uninstallation, downgrading from Virtualmin Professional to Virtualmin GPL, and selective removal of packages.
There are two methods for installing Virtualmin: a fully automated shell script and package-based install, as documented here, and a manual installation using either native packages or .wbm Webmin packages, as documented in the Manual Virtualmin Installation page. When possible, the automated installation is recommended, as it removes many possible errors during configuration and insures that all applications are built with appropriate options for virtual hosting within the Virtualmin system.
Installation involves first installing a basic install of your preferred Operating System, according to the documentation provided by your OS vendor. If the vendor provides a "server" version of the system, it is generally recommended you use it, as it will include fewer extraneous packages. A list of supported Operating Systems is provided at the OS Support page. There are a few simple guidelines for your system that must be met for proper operation of all Virtualmin features, which are detailed in the rest of this section.
The partitions on your Virtualmin server should be allocated in one of the the following two ways, depending on your requirements and preference. Either partition scheme is supported by the Virtualmin Professional Installer. Other partition layouts may lead to incorrect configuration of filesystem quotas, but can be corrected after installation is completed if other partitioning schemes are preferred.
In this partition layout, you will only have one system partition plus a swap partition and /boot partition. The system partition contains /home for users, /var for logs and databases, as well as all of the normal system executable files, documentation and libraries. It is often simpler to deploy. Traditionally, "one big partition" was considered problematic from an administration standpoint, but most such issues have been resolved by modern filesystems, backup utilities, and improved hardware reliability. If you are unsure what to choose for your needs, this is probably the right option.
swap: The swap partition should be at least twice the size of RAM on the system.
/boot: The /boot partition should be large enough to accomodate a few system kernels and initrd images. Your OS vendor probably knows best what size this should be.
/: The remainder of the disk(s) should be devoted to /. This is where all system and user data will go.
This layout spreads files across a few partitions, in order to facilitate usage of some types of backup utility as well as making some types of administrative task easier (for example, installing larger disks for some partitions at a later time). Historically, multiple partitions were considered wise administrative policy, but most modern systems and backup utilities eliminate the reasons for utilizing multiple partitions. Unless you know why you are dividing your disks into lots of partitions and can't achieve your goals any other way, you probably shouldn't.
/: This partition is used for all of the operating system files, executables, and configuration files. This partition should be at least 3.5 GB for most operating systems.
/boot: The /boot partition should be large enough to accommodate a few system kernels and initrd images. Your OS vendor probably knows best what size this should be.
swap: The swap partition should be at least twice the size of RAM on the system.
/var: The /var partition is where system logs, various changing data, and MySQL and PostgreSQL databases are stored. Depending on whether you will allow your domain users to use the database features, this partition may be between 2 GB and 10 or more GB. If users are expected to be heavy database users, you may opt to divide the remaining disk space between /var and /home.
/home: The home partition is where all of your domain users data, email, CGI scripts, logs etc. will be stored. Pretty much anything that belongs to your users, except for MySQL and PostgreSQL databases, will reside on /home. Devote the remainder of your disk to /home, as usage will likely grow rapidly if you have many users.
In order for the install.sh installation method to work, your system must have a working package management system. Supported systems are yum and up2date on RPM-based systems, and apt-get on Debian and Ubuntu systems. The FreeBSD ports and pkg system is used, when possible, though limitations of package management on FreeBSD only allows system packages to be installed via these means, while the Virtualmin packages are installed from our own wbm package repository. The Virtualmin Professional installer uses the native package manager in order to cleanly and safely install all of the appropriate software dependencies. The installer will then install the Virtualmin-provided packages, including some custom versions of packages that include features necessary for all features of Virtualmin to operate. If your native package management tool requires configuration to operate correctly, this step should be done before running the Virtualmin install script. Most distributions come with a working package management system; CentOS and RHEL will use yum, Debian and Ubuntu will use apt, and FreeBSD will use the ports system and the remote installation capability of pkg_add.
Packages in Virtualmin depend on a lot of OS-standard packages in addition to the packages our repositories provide. And most package managers are a bit temperamental about dependencies; sometimes they'll refuse to install a package because an older version of one of its dependencies is installed. So, in order to avoid dependency problems of this sort it is best to fully update your system using your native package manager prior to running the install script.
The Virtualmin installer requires network connectivity, including DNS resolution. The speed of your connection may impact the speed of installation, as up to 200 MB of packages will be downloaded and installed (if your system already has the majority of the dependencies installed, the download size will be reduced). Latency and bandwidth usage can be reduced significantly for multiple system installations by running a local caching proxy server like Squid, or by operating a mirror of the Operating System being used. It is also possible to pre-install most of the packages during OS installation, and only updates will need to be downloaded over the network.
So, let's boil down all of those preliminaries into a simple checklist. These are the things you need to do before running the install.sh:
Note: If you are installing on a low memory system, the package manager (both yum and apt-get/dpkg) can be very memory intensive during installation. A possible solution is to disable all but the necessary repositories (the OS standard repositories and the Virtualmin repositories. This is generally a good idea, anyway, as packages from non-OS sources may conflict with the Virtualmin packages and lead to unpredictable results.
Installation is performed automatically by the OS-neutral Virtualmin install.sh script. This script sets up the license key in /etc/virtualmin-license and configures the appropriate package management and installation tool for use with the password-protected Virtualmin software repository. It will then install the virtualmin-base package, which performs the remainder of the installation, appropriate for your OS and version.
Download the file from the Software Registrations page at [[http://www.virtualmin.com/serial/]]. All of your purchased products will be available for download throughout the life of your license period. Copy the file on to the server to be installed, using scp on Linux or Mac OS X client machines or WinSCP or PSCP on Windows.
Note: A frequent source of trouble is the use of FTP to make the transfer to your server. Because Windows uses different line endings than UNIX and Linux systems, the script can become corrupted if care is not taken to insure a "binary" mode transfer. scp and FTP over SSH are not generally subject to this problem, and so using the scp protocol for the transfer avoids many possible troubles.
Then, as root, run this:
# sh ./install.sh
Depending on your OS and the state of your system, the install.sh script may ask one or more questions.
If your system does not have a fully qualified domain name (FQDN), the installer will stop and ask you to choose one. This is mandatory because many services rely on having a fully qualified domain name in order to function. Mail, in particular, but some Apache configurations and many of the Virtualmin-created configuration files, also require a valid fully qualified domain name to function correctly. A fully qualified domain name is one of the form "www.virtualmin.com", or simply "virtualmin.com". We recommend you choose a name that is not one for which you will be receiving mail, in order to simplify later configuration. A good choice is to use a name server designator, such as "ns1.virtualmin.com". Some customers also choose something like "host1.virtualmin.com" or "primary.virtualmin.com". Any of these would be valid and would satisfy the install script and the services that rely on this option. The install script will add this name to /etc/hosts, which will satisfy all local services. It is even better if this name resolves correctly when looked up from outside of the system--this requires the name be added to your DNS zone for the second level domain. If the Virtualmin server you are installing will be the authoritative name server for this zone, you can later use Webmin to add a record for this name to the zone.
Once the necessary questions have been answered, installation will proceed automatically. After 15-45 minutes, depending on the speed of your network connection, your system will be configured for Virtualmin and ready to login to. You can then login to Virtualmin. Virtualmin runs on port 10000 and is encrypted using SSL. Thus, you can connect to your system with an address of the form:
https://example.com:10000
Or:
https://192.168.1.1:10000
And then log in as the "root" user, or any user with sudo access.
The final step in the installation is to perform the configuration check, by clicking the Check Configuration button at the top of the Virtualmin System Information page.
If your system does not have a password set for the root user, you will need to set a Virtualmin root password before you can login on port 10000. This can be the case when installing on an EC2 instance that uses an SSH key to login as root, or an Ubuntu system that uses sudo.
To set a root password for Virtualmin, run the command :
/usr/{share,libexec}/webmin/changepass.pl /etc/webmin root XYZ
where XYZ is the password you want to use. Make sure it is strong, as an attacker who guesses this password would have full control over your system.
Unlike the Automated Virtualmin Installation, to make use of this installation type, your OS does not need to be freshly installed, nor does it need to be a supported operating system. This method, however, requires significantly more knowledge on the part of the person doing the installation, and a much larger time investment to insure that all necessary configuration is performed and all Virtualmin managed services are working correctly.
If you are not extremely comfortable with your operating system, the services used in a hosting system, and performing various configuration tasks from the command line, you are advised to use the automatic installation on a Grade A supported operating system.
The partitions on your Virtualmin server should be allocated in one of the the following two ways, depending on your requirements and preference. Either partition scheme is supported by the Virtualmin Professional Installer. Other partition layouts may lead to incorrect configuration of filesystem quotas, but can be corrected after installation is completed if other partitioning schemes are preferred.
In this partition layout, you will only have one system partition plus a swap partition and /boot partition. The system partition contains /home for users, /var for logs and databases, as well as all of the normal system executable files, documentation and libraries. It is often simpler to deploy. Traditionally, "one big partition" was considered problematic from an administration standpoint, but most such issues have been resolved by modern filesystems, backup utilities, and improved hardware reliability.
swap: The swap partition should be at least twice the size of RAM on the system.
/boot: The /boot partition should be large enough to accomodate a few system kernels and initrd images. Your OS vendor probably knows best what size this should be.
/: The remainder of the disk(s) should be devoted to /. This is where all system and user data will go.
Note If you plan to use disk quotas, you should be aware of a few potential gotchas with this type of deployment. Quotas apply to all files on a given partition, regardless of the directory. In the case of mail delivery and processing, there are several very sneaky ways for this to cause failures of various types. Because of this, if you are using disk quotas, you probably want to make /home its own very large partition.
This layout spreads files across a few partitions, in order to facilitate usage some types of backup utility as well as making some types of administrative task easier (for example, installing larger disks for some partitions at a later time). Historically, multiple partitions were considered wise administrative policy, but most modern systems and backup utilities eliminate the reasons for utilizing multiple partitions.
/: This partition is used for all of the operating system files, executables, and configuration files. This partition should be at least 3.5 GB for most operating systems.
/boot: The /boot partition should be large enough to accommodate a few system kernels and initrd images. Your OS vendor probably knows best what size this should be.
swap: The swap partition should be at least twice the size of RAM on the system.
/var: The /var partition is where system logs, various changing data, and MySQL and PostgreSQL databases are stored. Depending on whether you will allow your domain users to use the database features, this partition may be between 2 GB and 10 or more GB. If users are expected to be heavy database users, you may opt to divide the remaining disk space between /var and /home.
/home: The home partition is where all of your domain users data, email, CGI scripts, logs etc. will be stored. Pretty much anything that belongs to your users, except for MySQL and PostgreSQL databases, will reside on /home. Devote the remainder of your disk to /home, as usage will likely grow rapidly if you have many users.
Install the following applications, using whatever method is appropriate for your operating system:
With the exception of Apache, standard versions of these applications are usually sufficient, as long as they are reasonably modern and have all security patches applied.
Additionally, if your system supports disk quotas, and you will be using them with Virtualmin, you need the management tools for disk quotas. Webmin also provides support for firewall management on most UNIX and Linux platforms, assuming the appropriate command line tools are available.
Note The Apache web server package provided with most operating systems requires customization to be suitable for use in a virtual hosting system, specifically it must be rebuilt with suexec_docroot set to /home. The standard OS Apache package will not work with applications in home directories, and thus is not suitable for virtual hosting usage. A custom build of Apache is not optional. This configuration cannot be done without a rebuild of the suexec binary, for security reasons. Debian and Ubuntu provide an apache-suexec-custom package that can be used, instead of rebuilding the binary; it must be installed and configured appropriately for executing scripts in /home (but, Debian and Ubuntu LTS are both Grade A supported operating systems by our install script, and so there should rarely, if ever, be a need to perform a manual install on these operating systems).
Download and install Webmin and Usermin, from http://www.webmin.com Webmin.com. There are multiple package types of available, so choose the most appropriate one for your OS. Installation instructions can be found on the Webmin site.
Once Webmin is operational you can download and install the Virtualmin modules and theme in either RPM format (for RPM-based Linux distributions), deb format (for deb-based Linux distributions), or wbm format (for any other UNIX or Linux system), and install them using the Webmin Modules module found in Webmin:Webmin Configuration.
The modules and themes can be found in the following locations:
http://software.virtualmin.com/wbm - wbm format modules
http://software.virtualmin.com/universal - RPM format modules for all RPM-based Linux distributions
http://software.virtualmin.com/debian/dists/virtualmin-universal/main/ - Debian module packages
http://software.virtualmin.com/ubuntu/dists/virtualmin-hardy/main/ - Ubuntu Hardy Heron (8.04 LTS) packages
http://software.virtualmin.com/ubuntu/dists/virtualmin-universal/main/ - Ubuntu Lucid Lynx (10.04 LTS) packages
You will need to make a note of your serial number and license key, found on the http://www.virtualmin.com/serial/|Serial Numbers page at Virtualmin.com, so that you can login using the serial number as the username and the license key as the password.
http://software.virtualmin.com/gpl/wbm - wbm format modules
http://software.virtualmin.com/gpl/universal - RPM format modules
http://software.virtualmin.com/gpl/debian/dists/virtualmin-universal/main/ - Debian module packages
http://software.virtualmin.com/gpl/ubuntu/dists/virtualmin-hardy/main/bi... - Ubuntu Hardy Heron (8.04LTS) packages
http://software.virtualmin.com/gpl/ubuntu/dists/virtualmin-universal/main/ - Ubuntu Lucid Lynx (10.04 LTS) packages
On most platforms Apache must be built with suexec_docroot set to /home. This requires a recompile of Apache. We provide packages for the most popular operating systems in our GPL repositories at http://software.virtualmin.com/gpl/. For other systems, you will need to download a source package from your OS vendor and rebuild it with the necessary change.
On Debian and Ubuntu systems, you can instead use the apache2-suexec-custom package. This option requires no rebuild of Apache. Configuring the custom suexec package is performed in /etc/apache2/suexec/www-data, and is as simple as changing the first line from /var/www to /home.
If installing on Ubuntu, you'll need to edit /etc/apache2/conf.d/php5.conf, and comment out the two SetHandler lines.
BIND needs to be installed, and configured to accept queries from any address. Also, it is recommended that you configure the system to query the local name server by adding 127.0.0.1 to /etc/resolv.conf.
Postfix should be installed, and configured for virtual hosting. The best way to do this for the vast majority of deployments is to use a simple map file.
Edit main.cf and add the following line:
virtual_alias_maps = hash:/etc/postfix/virtual
Save it, and restart Postfix.
Procmail is necessary if you plan to make use of the spam and anti-virus filtering capabilities in Virtualmin. A reasonable starting procmailrc might be:
LOGFILE=/var/log/procmail.log TRAP=/usr/libexec/webmin/virtual-server/procmail-logger.pl VERBOSE=true :0wi VIRTUALMIN=|/etc/webmin/virtual-server/lookup-domain.pl $LOGNAME :0 * ?test "$VIRTUALMIN" != "" { INCLUDERC=/etc/webmin/virtual-server/procmail/$VIRTUALMIN } DROPPRIVS=yes DEFAULT=$HOME/Maildir/ ORGMAIL=$HOME/Maildir/
The procmail-wrapper program is necessary for for mail to work properly, and in particular, spam and virus processing.
First, put the following code into a file named procmail-wrapper.c:
#include <stdio.h>
#ifndef REAL_PROCMAIL
#define REAL_PROCMAIL "/usr/bin/procmail"
#endif
int main(int argc, char **argv)
{
setuid(geteuid());
setgid(getegid());
execv(REAL_PROCMAIL, argv);
}Then, run the following commands to compile the code, install it into /usr/bin, and give it the proper permissions:
gcc -o /usr/bin/procmail-wrapper procmail-wrapper.c chmod 6755 /usr/bin/procmail-wrapper
Lastly, edit /etc/postfix/main.cf, and set mailbox_command to the following:
mailbox_command = /usr/bin/procmail-wrapper -o -a $DOMAIN -d $LOGNAME
SpamAssassin should be installed if you will be using the spam filtering features of Virtualmin.
ClamAV should be installed if you will be using the anti-virus features of Virtualmin.
Dovecot should be installed and configured for use with Maildir mail spools.
PAM or shadow authentication should be used.
ProFTPd should be installed.
PAM or shadow authentication should be used.
If you plan to use MySQL, or any of the Install Scripts in Virtualmin Professional that rely on MySQL, it should be installed, and accessible to localhost. The root account should have a password set. Once Webmin is installed, you will need to configure the MySQL module to know the root MySQL password.
Note - Virtualmin does not require MySQL, and no Virtualmin-related user data is stored in MySQL. If you've read setup guides on the web for virtual mail hosting that require MySQL, we strongly recommend you ignore them. This is a very common source of confusion for new users, and there's simply no reason to introduce the complexity of this kind of deployment.
If you plan to use PostgreSQL or any of the Install Scripts in Virtualmin Professional that rely on PostgreSQL, it should be installed, and accessible to localhost.
If users will be sending email through your server, you will need to configure saslauthd. This requires interaction with your MTA (probably Postfix), and it should be configured to use PAM or shadow authentication.
When enabled, Virtualmin can allow your users to create and manage Mailman mailing lists.
Most installation problems are related to network connectivity, package management, or attempting to run the install script on an unsupported operating system or architecture.
Check the virtualmin-install.log. It is possible that your package manager is configured to use a local CD ROM device for packages, and the disk is unavailable. Another possibility is that connections to one or more repositories are timing out, and causing the system to install packages very slowly.
If your system has low memory (512MB or less), things may take much longer to install than normal, as the package manager (yum or apt) may grow larger than physical memory and push the process into swap memory. So, installation on small VPS systems may take an hour or more.
If your package manager is configured to use non-OS package repositories, or if you have installed alternative versions of packages before installation, conflicts are likely to occur during installation. If you plan to use non-OS standard packages (other than those provided by Virtualmin repositories), they should be installed after installation of Virtualmin, and you should add an exclude directive to the yum or apt-get configuration in order to insure similar conflicts do not happen in the future.
Also note that if you are using non-OS standard packages, you may need to configure the relevant Webmin module to make it aware of the location of the configuration files.
Note that if your Linux distribution was installed by your ISP (such as with a VPS image), you may want to verify that no additional repositories were setup.
If you have run any so-called "hardening scripts" on your system before running install.sh, your /tmp directory may be mounted noexec. It is always best to run the install script on a freshly installed supported Operating System, though this particular issue can be resolved. The install script cannot complete if this is the case, and /tmp will need to be remounted to allow executables.
To do that:
# mount -o remount,exec /tmp
If you wish to switch back to your original settings after installation, you can use this command to reset the noexec option:
# mount -o remount,noexec /tmp
ClamAV is updated frequently by the upstream developers. Your OS repository may not have the latest version, which causes ClamAV to issue very scary warnings. These warnings are non-fatal, and can generally be safely ignored.
If you are using CentOS, the ClamAV packages come from our repositories, and are updated every few weeks, as time and testing schedules allow. So, if you see this error, it will go away with the next update.
If you are using Debian, you may consider enabling the "volatile" apt-get repository, as it includes newer versions of ClamAV and SpamAssassin, which are both rapidly moving targets and worth running recent versions of.
Virtualmin Professional customers receive free installation service if the automated installation process fails to work correctly on any Grade A or B supported operating system listed on the OS Support page. Open a ticket in the issue tracker with a description of your problem and the relevant portion of the virtualmin-installation.log, and we will try to walk you through to a solution, or log into your system and complete the installation free of charge.
Virtualmin GPL users can make use of the forums to ask for assistance with any problems that arise during installation.
There are many levels of "uninstalling" Virtualmin, but the most common is simply that you don't want the Virtualmin GUI or any of its plugins installed. The simplest way to accomplish this, assuming you used the automated installation process (install.sh), is to re-run install.sh with the - -uninstall flag:
sh install.sh --uninstall
This is a rather haphazard uninstall routine, but it will remove pretty much everything Virtualmin-specific while leaving behind the services that it manages (like Apache and BIND).
Note This will remove Virtualmin related meta-data. This should never be used to allow you to "reinstall" Virtualmin on a production system. If you have Virtualmin running on a production system with accounts, you should not try to install Virtualmin again. If there are any problems with your running installation, let us know and we'll help you fix the problems. However, it can be used to cleanup after a prior failed install--perhaps after we've fixed a bug or something in the installer and you'd like to run it again but run into conflicts (perhaps virtualmin-release is in the way).
If you no longer need the features of Virtualmin Professional, but wish to continue to use Virtualmin on your system, you can downgrade quite easily.
In its simplest form, you merely install the Virtualmin GPL module over the Virtualmin Professional module. How that is done depends on your OS and how Virtualmin was initially installed.
On RPM-based distributions, like CentOS or RHEL, download the latest Virtualmin GPL RPM from http://software.virtualmin.com/gpl/universal/
Then install it using RPM with the --oldpackage option. For example:
rpm -Uvh --oldpackage wbm-virtual-server-3.64.gpl-2.noarch.rpm
If you were also using our yum repository (which is true if you used install.sh to install Virtualmin), you will need to switch the the GPL repository. To do that, install the latest version of the virtualmin-release package for your operating system and version. For example, for CentOS 5, you could run the following command:
rpm -Uvh --oldpackage http://software.virtualmin.com/gpl/centos/5/i386/virtualmin-release-latest.noarch.rpm
On Debian and Ubuntu systems update /etc/apt/sources.list to point to the GPL version of the Virtualmin repository for your OS (merely insert gpl into the path just after the domain name).
Once apt has been reconfigured, you can use apt-get to install the GPL version of the webmin-virtual-server module.
If you didn't use packages, and instead used the .wbm format of module, download the latest version of the virtual-server module from http://software.virtualmin.com/gpl/wbm and install it using the Webmin modules module, found in the Webmin menu under Webmin:Webmin Configuration:Webmin Modules.
Once you've downgraded the virtual-server module to the GPL version, you can change the /etc/virtualmin-license file to :
SerialNumber=GPL LicenseKey=GPL
Then remove the /etc/webmin/virtual-server/licence.pl , sendratings.pl and fcgiclear.pl cron jobs. You can use the Webmin System:Schedule Cron Jobs module to locate and delete that job, if you like.
In a standard install of Virtualmin using our scripts, upgrades are typically done using APT or YUM. When a new version is available, you will see a message on the System Information page after logging in like :
Other packages may be listed too, depending on what is available to be updated. To install, just click the Install All Updates Now button.
Alternately, you can install the same packages from the command line as root. On CentOS or Redhat Enterprise, the command to use will be like :
yum install wbm-virtual-server bind perl python
On Debian or Ubuntu, you could use :
apt-get install webmin-virtual-server bind perl python
When upgrading Virtualmin Professional licenses, it is never necessary to re-install or perform any changes to your license on your system. Once a license upgrade has been applied on our server (usually immediately after confirmation of your purchase, but if there is any delay, you can open an issue identifying the serial number and your order number, and we will manually process it), you can click the "Re-check Virtualmin License" in the System Information page to immediately update the license details on your system.