Installation

There are two methods for installing Virtualmin Professional: 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.

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.

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 systems. 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, Inc. 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 Professional install script. For example, up2date has to be configured before it will successfully install packages, which can be done by simply running the up2date utility manually from the command line or the GUI. The installer will attempt to configure apt-get to use the universe repository on Debian and Ubuntu.

On Red Hat Enterprise Linux and CentOS systems, in all 3.x and 4.x versions, the up2date system is used to install some components from the system repository. Please run up2date (or the up2date GUI client) at least once prior to running the Virtualmin Professional Installer. If you do not, the installer will stop when the standard component installation phase is reached, and will require human intervention.

up2date must be run once before running install.sh or installation will fail.

On FreeBSD the automated installation makes use of both the ports system and the remote installation capability of pkg_add. You must insure both of these tools are in full working order before attempting to install Virtualmin using install.sh. Documenting these utilities is well beyond the scope of this guide. Consult with the FreeBSD documentation for further details.

See also: FreeBSD Installation and Configuration

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:

1. Confirm that networking is fully functional. Ping software.virtualmin.com. If it doesn't work, you'll need to fix it.
2. Confirm that your package management tool (up2date, yum, urpmi, yast, or apt-get) works correctly and is configured to use sources that are available.
3. Fully update your system with the native package manager before beginning installation.
4. Confirm you have perl and either wget, curl, or fetch installed.

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 Professional 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 is a RHEL or CentOS version 3 or 4 system, you will be asked to confirm that you have run up2date at least once before running install.sh. If you have not run up2date before running install.sh, exit the installer and run "up2date -u". This will insure the forced non-interactive configuration process of up2date is already completed--if you haven't run up2date before running install.sh the process will hang forever while trying to install system-provided packages. This does not effect versions 5 and above of these systems, or any other supported OS.

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 Professional 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

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.