Mail and FTP Users Guide

Using Usermin Webmail

To access the Usermin Webmail system, browse to port 20000 on your domain name, using the HTTPS protocol.

For example:

https://www.domain.tld:20000

Login using your mailbox username and password.

Navigating Usermin

Usermin provides a left-hand menu, and a right-hand content pane.

In the left-hand menu, there is a Mail tab and a Usermin tools tab. The Mail tab includes a list of available mail folders, a search box, and links for folder management, address book, mail preferences, change passwords, system information, and switch user.

The right pane displays either the active folder, mail message, or Usermin tool that has been selected in the left-hand menu.

Virtualmin Resellers Guide

A guide for Virtualmin Reseller account holders. Documents domain creation, editing, maintenance, and script installation.

Introduction

Virtualmin, combined with Webmin and Usermin, provides a complete virtual hosting administration system, allowing for four tiers of operation, "administrator", "reseller", "domain owner", "mail user". This guide is for the second, or reseller, tier of the system. The reseller account type has the ability to create, update and delete domains, manage email addresses within the domains under her control, and optionally install scripts and monitor bandwidth and disk usage. This guide covers only Virtualmin's extensive virtual hosting features that are available to Reseller account holders.

Navigating Virtualmin

Any web browser can be used with Virtualmin, though some themes use advanced browser features that work better in browsers with good CSS support (Firefox, Safari, Opera and Konqueror all fit this description, while Internet Explorer currently does not). It is even possible to use a text-mode browser like lynx or links to use Virtualmin.

To login to Webmin (because Virtualmin is part of Webmin, one logs into Webmin and browses to the Virtualmin module), browse to the address of your server using the HTTPS protocol on port 10000. For example, if your Virtualmin server was running on hostname hosting1.virtualmin.com, you would enter https://hosting1.virtualmin.com:10000 in the URL field of your browser.

Your administrator will provide you a username and password to use for logging in.

Online Help

Within most Webmin modules, there will be a help link in the upper left corner of the page. Clicking it will open a help window with documentation about the specific page you are on. Most options in Webmin can be clicked on to get a popup help window describing that specific option. The Virtualmin module has extensive online help in addition to this manual, so if any option or feature confuses you, you don't have to find the appropriate section in this guide. Clicking on it will popup the help window with help specific to the item you clicked.

Logging Out

At the bottom of the left-hand menu, you'll find a Logout link. Clicking this link will, obviously, log you out of Webmin.

Creating Your First Domain

To create a new virtual server, click the Create Server* menu heading in the left menu bar, and then click the *Create Virtual Server item.

A new page full of options will be displayed in the right content window. We'll assume that most default settings are appropriate for our domain for the sake of simplicity in this example, but later on we'll dive into the depths of custom Server Templates, skeleton directories and customization of the default settings for new domains. After a fresh install, Virtualmin has pretty reasonable defaults for the vast majority of environments, though, so we can create a domain easily and expect it to be useful right away.

image:images/first-domain.png["Screenshot of Virtualmin Create Domain page"]

In the above, I have filled in everything that is needed to create a domain with most features enabled. I only specified a few options: Domain name, Description, Contact email address, and Administration password. The rest I've left at their default values. If you aren't sure what a particular option means, click on the name of the option, and a help window will pop up to describe the option. Every option in Virtualmin has a popup help link, and most pages have a general overview help link in the upper left corner of the page.

Domain Name

You must always provide a domain name for a virtual server account (there are ways to create websites for users without domains using Virtualmin, but that is a much simpler problem and isn't the focus of Virtualmin).

Description

The description is simply a short description of the domain. It is free text, and does not impact any aspect of the virtual server, so it can be just about anything. It will appear as the "Real Name" of the domain user in the Users and Groups module.

Contact email address

Here, you select what email address should receive notifications about this domain, including the creation email that lists the available services, provides login instructions, etc. If you choose to generate the password later on, this may be the only way for the user to find out the password, so it may be appropriate to choose Other address.. and enter the users preferred address in the field provided.

Administration password

You can choose to have a password generated randomly, which is a good idea from a security standpoint. Virtualmin will generate a reasonably long (8+ characters) random password, which will be sent to the user via email. They can, of course, immediately change the password when they login.

Other options

All of the other options can generally be left alone. We'll discuss many of them in more detail later on, but for now, let's just assume that the defaults are perfect.

When you click the Create Server button, Virtualmin will spin into action...it will create the new user and group, add Apache virtual host configuration, add a zone and domain to BIND, add virtual domain configuration to Postfix, create new databases and users in MySQL and PostgreSQL, configure SpamAssassin and ClamAV for the domain, configure log rotation and Webalizer log reports, (woo! I'm getting tired just talking about it...that Virtualmin works hard so you don't have to) and configures any optional Virtualmin Plugin features, like Mailman mailing lists or SubVersion revision control repositories.

Now you can return to the Virtualmin main page and you'll see your new domain in the list of available domains. Clicking on the domain allows you to edit all of the options we just configured, so you can always return to the domain to alter the settings (be careful with that feature, however, as turning off a feature may delete user data...Virtualmin will warn you before destructive changes).

The domain owner can also login using the new domain account and the password you assigned (or that was randomly generated).

Bandwidth Monitoring

Bandwidth monitoring is a standard feature of Virtualmin, allowing the administrator to limit bandwidth usage or simply notify users and administrators when a domain is approaching and has surpassed their allotted network bandwidth.

To find out bandwidth usage of your domains, click the Bandwidth Usage link in the left-hand menu (if unavailable, bandwidth monitoring has not been enabled for your account).

Install Scripts

Virtualmin Professional provides the ability for domain owners, resellers, and administrators to easily install dozens of PHP and Perl scripts within a Virtualmin domain. It also allows for one or more scripts to be installed automatically on server creation, based on the selec ted Server Template for the new domain. New Script Installer scripts can also easily be writ ten using the Install Scripts to add support for internally developed applications.

To install a new script select the domain you'd like to install for in the dropdown menu at the top of the left-hand menu, and then click Install Scripts. Then, click the radio button next to the script you'd like to install, and optionally select a version (often both a stab le and development version are provided). Finally, scroll to the bottom of the page and clic k the Show Install Options button.

On this page, you'll be able to select the database to use from existing databases, optionally create a new database, and choose the name of the subdirectory to install the script under. Clicking Install Now will then install the script and setup the database with the appropr iate items. Some scripts don't need a database, and so the database-related option will be unavailable.

Virtualmin Virtual Server Owners Guide

Introduction

Virtualmin allows you, the domain virtual server account holder, to manage your website files, mailboxes, databases, DNS entries, and install scripts.

Getting Started

Logging in to Virtualmin

Virtualmin is the administrative interface, or control panel, you will use for most of the administrative functions you'd like to accomplish. You can open your account using any browser (modern browsers like Firefox, Safari, and Opera are recommended), by browsing to port 10000 on the server address using the HTTPS protocol.

For example, if your domain were virtualmin.com, you could access it at the URL: https://virtualmin.com:10000

Enter your username and password, as provided by your system administrator.

Navigating Virtualmin

When you login to Virtualmin, you'll see a left-hand menu bar and a right-hand content page, as shown in the diagram below:

image:/images/first-look.png

The left menu contains all of the options available for your domain. Some shown here might not be available in your menu, it depends on the options available for your domain.

The right content page opens with a summary of your virtual server data, such as number of domains, disk usage, mailboxes etc.

Uploading Files

There are several ways to upload content to your Virtualmin account. You can use any of them or all of them, based on your needs and skills.

SSH, SCP and FTP over SSH

The preferred method for sending many files, directories of files, or very large files, is the SSH protocol. SSH is a fast and secure protocol, that allows you to safely login, upload and download files, and manage existing files. SCP is the name for file transfer commands that work using the SSH protocol. Likewise, FTP over SSH (sometimes also called FISH, or SFTP) is a mechanism for providing FTP-like service over a secure link.

There are many graphical and textmode clients for the SSH protocol available for free and commercially.

We'll cover where to find SSH-capable clients for your Operating System, and we'll provide a few examples of using them to manage the files in your Virtualmin account.

Windows SCP Clients

pscp

The best free command line SCP client is called pscp.exe and it can be found at:

http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html

It is related to PuTTY, which is a very nice free SSH client.

After you've placed the pscp.exe file into your system path, using it is quite simple. In a DOS shell, simply enter a command like the following:

C:\> pscp.exe myfile.htm user@domain.tld:/home/user/public_html

Then, enter your password at the prompt, and hit enter. This will copy the file "myfile.htm", located in the current directory, to the /home/user/public_html folder on the Virtualmin server.

Windows graphical FTP clients

Filezilla

A free graphical FTP client that supports FTP over SSH is Filezilla. http://filezilla.sourceforge.net/|Filezilla Home Page.

To Configure Filezilla:

1. Download and Install Filezilla
2. Run Filezilla
3. File -> Site Manager ->
4. Click "New Site" -> Give it a name such as "example"
5. In the top right "Host" box fill in "example.com"
6. In the "Servertype" box choose "SFTP using SSH2"
7. "Logontype" choose "Normal"
8. Fill in the "User" and "Password" boxes with the virtual server owner username and password respectively.
9. In Virtualmin -> Webmin -> Servers -> SSH Server
10. Access Control -> Only allow users -> add the above virtual server username
11. Click "Save" -> Click "Apply Changes"

Your admin user will be able to use a graphical FTP style program or Dreamweaver to upload their pages now.

WinSCP

Another good free graphical FTP over SSH option is WinSCP:

http://winscp.net/eng/index.php|WinSCP Home Page

After installation, simply start it up. It will ask for your login information. Enter the details as provided by your system administrator for hostname, username, and password. Then click Login.

Now you'll see a window displaying the files in your Virtualmin account home directory. You can copy files into your public_html directory to make them accessible via the webserver, or into the cgi-bin directory, if the files are executable CGI scripts.

Mac OS X SCP Clients

scp

Mac OS X includes the free OpenSSH SCP client, called simply scp. Usage is just like Linux and UNIX scp clients. Open a Terminal and execute a command like the following:

$ scp myfile.htm user@domain.tld:/home/usr/public_html

After this hit enter, and then enter your password.

Cyberduck

Cyberduck is a popular Mac-native Open Source graphical FTP client that supports SCP, SFTP, FTP over SSL, WebDAV/SSL, and Amazon S3 secure connections.

It also integrates very cleanly with most favorite external OSX text editors, like SubEthaEdit, BBEdit, TextWrangler, Text-Edit Plus, TextMate, mi, Smultron, JeditX, CSSEdit, CotEditor and Tag, skEdit, and PageSpinner.

Download it for free from here:

[http://cyberduck.ch_ Cyberduck Home Page]

Linux SCP Clients

scp

Like Mac OS X, all Linux distributions include a complete SSH implementation, including the scp command. Run the following to copy a file named "myfile.htm" to the domain.tld server using the username "user":

$ scp myfile.htm user@domain.tld:/home/usr/public_html

After this hit enter, and then enter your password.

gftp

gftp is a popular Gnome-based graphical FTP client that also supports scp and FTP over SSH protocol connections.

Download it for free from here:

[http://gftp.seul.org/ gftp Home Page]

Or, preferably, simply install the package provided by your OS vendor. gftp is very popular and is available from the majority of Linux distributions, so you don't need to build it yourself.

WebDAV

FTP

Your FTP client should be configured to connect to yourdomain.tld, or, if DNS has not yet propagated, you could use the IP address or temporary hostname given to you by your administrator (which will be of the form youdomain.hostdomain.tld). You will use the domain account name and password given to you by your system administrator. Note that, by default, only the domain account has FTP access to the website data for your account, and additional users are only email users.

Webmin File Manager Applet

Cloudmin Paid AMI

• Cloudmin Paid AMI on EC2
  • Introduction to Paid AMIs
  • Pricing
  • Using the paid AMI
  • Using Cloudmin on EC2

Cloudmin Paid AMI on EC2

Introduction to Paid AMIs

Pricing

Using the paid AMI

Using Cloudmin on EC2

Virtualmin GPL AMI

• Virtualmin GPL AMI on EC2
• Virtualmin EC2 Image in Europe
• Virtualmin GPL Debian Etch Image

Virtualmin GPL AMI on EC2

Virtualmin EC2 Image in Europe

export EC2_URL=https://eu-west-1.ec2.amazonaws.com

Virtualmin GPL Debian Etch Image

ec2-run-instances ami-dd13f7b4 -k vgpl-keypair

Virtualmin Professional Paid AMI

• Virtualmin Pro Paid AMI on EC2
  • Introduction to Paid AMIs
  • Pricing
  • Using the paid AMI
  • Using Virtualmin Pro on EC2

Virtualmin Pro Paid AMI on EC2

Introduction to Paid AMIs

Pricing

Using the paid AMI

Using Virtualmin Pro on in Europe

Using Virtualmin Pro on EC2

Account Plans

Introduction to Plans

In Cloudmin, an account plan is a set of restrictions that can be applied to a system owner. Plans can limit the following :

• Number of systems the owner can create
• Total RAM assigned to virtual systems
• Total disk space assigned
• Total CPU assigned
• Number of IP addresses assigned to virtual systems
• Disk space used for backups created by the system owner
• Combined bandwidth for virtual systems
• Allowed actions, such as shutting down, creating systems and managing virtual disks
• Allowed host systems
• System images the owner can use

All limits apply to the total usage of all systems owned by the user the plan is applied to.

Creating and Managing Plans

Cloudmin comes with one default plan that is created when installed. To add your own plans, do the following :

1. Open the Cloudmin Settings category on the left menu, and click on Account Plans.
2. Click on Add a new account plan , and fill in the Plan name field.
3. Enter any other limits you want, such as on disk space or RAM.
4. If needed, take away some actions in the Plan restrictions section. Those selected by default are generally safe and reasonable.
5. In the Host system restrictions section, choose hosts that owners on this plan should be able to use for new systems. You can also select the method via which a host is chosen.
6. To prevent use of some images (such as those containing commerical software), limit the selection in the System images section.
7. Click the Create button.

To edit a plan after it is created, go to the Account Plans page and click on its name. Any changes in limits or restrictions will be immediately applied to system owners on the plan.

To delete a plan, check the box next to its name in the Account Plans list, then hit the Delete Selected Plans button.

Applying Plans to Owners

Once a plan has been created, you can apply it to an owner as follows :

1. Go to Cloudmin Settings -> System Owners, and click on an owner.
2. Under Limits and restrictions, select your new plan.
3. Make sure that other settings are set to From plan, so that the owner's individual limits will not be used.
4. Click the Save button.

Adding an EC2 Account

EC2 is different from other virtualization systems supported by Cloudmin, as it is a hosted service run by Amazon on their machines. They charge by the hour of machine time, and also for storage of any machine images that you create and host on their S3 service.

Cloudmin can manage virtual systems running under EC2 in almost exactly the same way as it does for other virtualized systems. The biggest difference is that they cannot be shut down without losing the contents of the system, which makes them a little risky for web hosting, as Amazon gives no guarantees of the stability of EC2 instances. Fortunately, Virtualmin makes it easy to backup hosted domains to Amazon's S3 service, which is fast and cheap when accessed from EC2 instances.

Signing Up With Amazon

Adding Your Account to Cloudmin

Creating an SSH Key

Automatic Failovers

Automatic Host Failovers in Cloudmin

Cloudmin's automatic failover feature provides protection against host system failures, by moving virtual systems off a down host to a new host with shared storage. The running state (memory contents and network connections) of virtual systems will be lost in this case, but they will be re-started on the new host with minimal interruption.

For failovers to work, your host systems must share the storage location for virtual system disk images or filesystems. This can be done via NFS, Cluster LVM, iSCSI, or other network filesystem technologies. Cloudmin's failover feature does not yet include automatic replication of disk images between host systems, and cannot setup shared storage for you.

Currently automatic failovers are supported only for Xen, OpenVZ and KVM virtual systems.

Failover Groups

A failover group is a collection of host systems that support some virtualization type, and share storage used for virtual systems. Some or all systems running on those hosts will be failed over to another host in the group if one goes down, assuming that there is enough free RAM available. Groups can contain an explicit list of hosts, members of some location group, or hosts in a Cloudmin system group.

The steps to create a new failover group are :

1. Login to Cloudmin as root, and go to Host Systems -> Host Failover Groups
2. Click the Add a new failover group link
3. Select a virtualization type from the Virtual system type menu.
4. Enter a name for the group in the Group description field.
5. If you want Cloudmin to automatically perform failovers, set the Failover group enabled? to automatic mode. Otherwise you can select manual mode to trigger failovers manually when you detect a host system has gone down.
6. In the Host systems in failover group section, select the hosts that will be part of this group.
7. To limit automatic failovers to only certain virtual systems, select them in the Virtual systems to failover section. You might want to do this for only important systems, or those on shared storage.
8. Click the Create button.

Once a group has been created, it can be edited or deleted at any time by clicking on its description on the *Host Failover Groups * page.

Failover Notification

When automatic failovers are enabled, they will be triggered by Cloudmin's regular status collection process. When it detects that a virtual system's host is down, it will wait for the Host downtime timeout set on the failover group page, and then attempt to move the virtual system to a new host.

Upon success or failure, email will be sent to the master administrator and possibly the owner(s) of a virtual system. If the virtual system was running before its old host failure, it will be re-started on the new host after the failover completes.

The move can fail for several reasons :

• No hosts in the failover group share the storage for this virtual system.
• No hosts have enough free RAM
• All other hosts in the group are down
• Any error occurred copying configuration files to the new host

Triggering a Manual Failover

If you have set a failover group to manual mode, Cloudmin will not automatically move virtual systems off down hosts in the group. However, you can force a failover at System Operations -> Force Failover. On this page you can optionally select a specific new host system, and decide if the virtual system should be started up on the new host or not.

A manual failover can also be done using the failover-system API command.

Backup and Restore

Introduction to Cloudmin Backups

Cloudmin allows the master administrator and system owners to create backups of virtual systems running under Xen, OpenVZ, Vservers or Solaris Zones. This provides protection against accidental deletion of files within the filesystem, for example by an accidental rm * command.

Backups can be either run manually or on a regular schedule, such as once per day. When a backup is taken the virtual system can be either shut down to ensure a consistent filesystem state, or left running to avoid downtime.

What is and is not Backed Up

Currently, backups only include the contents of the virtual system's filesystem or disk images. For Xen systems the backup contains a compressed copy of all virtual disks, while for other virtualization types it is just a TAR file of the filesystem.

When backing up a running Xen system using LVM logical volumes to store disk images, LVM snapshots are used to take an instantaneous copy of the filesystem while it is copied. Each will consume 10% of the space in the volume group as the underlying disk images, so make sure you leave some LVM space free.

Other configuration files and data are not included - so if a virtual system is completely destroyed, it must be first re-created before the backup can be restored.

Backup Destinations

Cloudmin can backup virtual systems to a variety of different destinations - via SCP, FTP or to any system it manages. In a typical Cloudmin setup a single system with plenty of disk space is chosen as backup destination, perhaps the master system itself. Backups are taken on the host systems and then transferred to this backup machine. Alternately, you can choose to store backups on the hosts themselves, to avoid the need to transfer large backup files over the network.

Each host system defines a default backup destination for its virtual systems. You can set this as follows :

• Login to Cloudmin, open the Host Systems category and click on the link for your virtualization type, such as Xen Host Systems.
• Click on the first of your hosts, and open the Default backup destination section.
• Select a destination type and fill in the fields next to it - for example, in you have a dedicated backup system you could select Directory on system, choose it from the menu, and enter a path like /backup.
• Click the Save button, then repeat the same steps for other host systems.

When a backup is made it will be saved to the specified directory in a file whose name is that of the virtual system with .tar.gz appended. Each subsequent backup of the same system to the same destination will overwrite that file.

Creating a Scheduled Backup

Once a default destination has been set, you can schedule a backup like so :

• Open the Backup and Restore category on the left menu and click on System Backups.
• Click the Add a new system backup link.
• From the Systems to backup list select the virtual systems you want to include.
• To have them shut down during the backup process, change Shut down systems? to Yes.
• In the Backup destination, you can typically leave Default destination for host system selected unless you want the backup to be sent to an FTP or SSH server outside of Cloudmin's control.
• Change Scheduled backup enabled? to Yes, and select a schedule in the When to backup field.
• To be notified on backup failures, enter your address in the Email results to field.
• Click the Create button.

It is possible to leave Scheduled backup enabled? set to No if you just want to define a backup that will always be run manually.

After a backup has been defined, you can edit or remove it by clicking on its entry in the System Backups list.

Running a Backup Manually

To kick off a backup, just click on it in the System Backups list and then hit the Backup Now button. Progress messages will be displayed as it runs, and a final summary of systems completed and backup sizes when it finishes. Depending on the sizes of the systems being backed up, it may take minutes or hours.

Testing a scheduled backup after creating it is strongly recommended. Also, you should create, backup and restore a test system that uses the same configuration and destination as your production systems to ensure that all steps in the process are working properly.

Backup Logs and Restoring Backups

Cloudmin logs all backups it performs, including their final status, systems included, disk used and possibly the complete progress report. To view logs, go to Backup and Restore -> Backup Logs, and enter a hostname or destination path into the Find backup logs box, then click Search.

The simplest way to restore a backup is to click on its destination in the search results, which will open a restore form. You can also restore some or all systems from a scheduled backup as follows :

• Go to Backup and Restore -> System Backups, and click on a backup.
• Click the Restore button.
• Select the systems to restore - typically you only want one, instead of everything that was included.
• Click Restore Now.

Cloning Systems

Introduction to Cloning

A clone is a copy of a virtual system that has the same disk contents, accounts, root password and number of network interfaces as the original. However, it is assigned a new hostname, IP address(es) and description.

Creating a clone is easier than imaging a system and then creating a new system from it, as it is done in a single operation. Cloning is also available to system owners, subject to limits on disk, RAM and CPU use, and assuming that the owner is allowed to create new systems at all.

Virtual systems using Xen, KVM, OpenVZ, Vservers and Citrix Xen can be cloned in Cloudmin versions 4.5 and later. The process is the same regardless of the virtual system type.

Cloning a System

The steps to follow to clone an existing system are :

1. Select it from the left menu, then go to System Operations -> Clone System
2. Enter a new system name into the New hostname prefix field. This typically only has to be a prefix, as the domain will be automatically appended.
3. Enter a description for the new system.
4. By default, Cloudmin will allocate new IP addresses for the clone in the same way that it does allocation for any new system. However, you can alternatively select Entered below in the IP addresses for clone and enter an address for each interface on the new system.
5. Click the Create Clone button, and wait for the process to complete.

Cloning is generally faster than creating a new system, as there are fewer steps involved. However, if the system being cloned has large disks, it will take proportionally longer.

Cloning will be disallowed if the host system does not have enough free RAM or disk space, or if your usage is too close to the limits set in your plan.

Cloudmin GPL

Introduction to Cloudmin GPL

The GPL version of Cloudmin is a designed to manage Xen instances on only a single host system, rather than supporting multiple hosts and virtualization types as in the full (Pro) version. It lets users try out Cloudmin and virtualization concepts without having to purchase the full package.

Installing Cloudmin GPL

Cloudmin's installer can be used on CentOS, Redhat Enterprise, Debian and Ubuntu systems. It will both install Cloudmin and setup the system as a Xen host, by installing a Xen-capable kernel and associated tools.

You can download the install script for CentOS and Redhat from : http://cloudmin.virtualmin.com/gpl/scripts/cloudmin-gpl-redhat-install.sh

The install script for Debian and Ubuntu can be downloaded from : http://cloudmin.virtualmin.com/gpl/scripts/cloudmin-gpl-debian-install.sh

In either case, it needs to be copied to the system you plan to run Cloudmin on and then executed with a command like :

sh cloudmin-gpl-redhat-install.sh

Cloudmin can co-exist with Webmin or Virtualmin GPL on the same system. The installer uses YUM or APT to add the required packages, some from our repository and some from the repository provided by your distribution vendor.

Once installation is complete, you will need to reboot your system. Then go to https://yoursystem:10000 in your browser , download some system images, and type creating a Xen instance.

Differences between Cloudmin GPL and Pro

Features missing from the GPL version of Cloudmin include :

1. Support for Xen, OpenVZ, KVM, VServers, Solaris Zones virtual systems.
2. Can create and manage EC2 accounts, instances, images, addresses and storage volumes.
3. The ability to manage multiple host systems (each of which can run multiple virtual systems) from a single interface.
4. Support for managing multiple non-virtual systems, such as machines running Virtualmin.
5. Live replication of settings from a Cloudmin master to one or more backup systems.
6. Multiple locations for storing system images, to avoid repeated copies to distant datacenters.

Upgrading from Cloudmin GPL to Pro

Cloudmin can be upgraded to the Pro version without effecting any existing settings as follows :

1. Go to the Virtualmin shop at http://www.virtualmin.com/catalog/43 and purchase a Cloudmin licence.
2. Go to http://www.virtualmin.com/serial and note down your serial number and licence key. There is no need to download the new install script though.
3. Login to your Cloudmin GPL install, and go to Cloudmin Settings -> Upgrade Cloudmin.
4. Enter your new serial number and licence key, then click the Upgrade button.

The full version packages should then be downloaded and installed, and your APT or YUM configuration updated to use the correct repositories.

Cloudmin Glossary

Cloudmin and its documentation uses the following terms to refer to different types of systems and other objects :

• System
  A machine with its own IP addresses, filesystems and accounts. This can either be an actual physical computer, or a virtual machine running under some virtualization technology such as Xen, OpenVZ, EC2, Vservers or Solaris Zones. Systems are the primary object managed by Cloudmin.

• Virtual System
  A system that runs under some virtualization type, such as Xen or OpenVZ.

• Real System or Physical System
  An actual computer with its own hardware.

• Host System
  A real machine that can host virtual systems of some type(s).

• Cloudmin Master
  The system on which the Cloudmin software is installed and runs. This may also be a host system, or in some rare cases a virtual system that it also controls. System images are also primarily stored here.

• Server
  A process that provides some service, such as Apache or BIND.

• Virtual Server
  A combination of services provided by several servers, typically associated with a domain name. Virtual servers are the object primarily managed by Virtualmin.

• System Image
  A template from which virtual systems can be created, containing the contents of its filesystem.

• System Owner
  An additional login to Cloudmin will access to a subset of systems and functions.

• Account Plan
  A set of limits on disk, CPU, RAM and network use that can be applied to a system owner.

Command Line API

Explains how to use the command-line scripts included with Cloudmin to manage users, aliases, servers, databases and resellers.

Introduction

Command Categories

Creating IP Pools

If you plan to have more that one host machine for virtual systems (like Xen instances or OpenVZ containers), we recommend defining the IP allocation range for those systems in a single place. This way the range only has to be created once, and can be changed in a single place.

The steps to create a common IP range are :

1. Open the Host Systems category on the left menu, and click on IP Addresses.
2. Go to the Common IP pools tab.
3. In the first empty row, enter starting and ending IP addresses for your allocation range, such as 192.168.1.1 and 192.168.1.200.
4. Enter a netwask for the range, like 255.255.255.0.
5. If you have one, enter a description for this IP range.
6. Click the Save button.
7. To add another range, repeat the steps above.

Once the range has been created, it will be available when creating or editing host systems.

Creating a Citrix Xen Virtual Machine

Creation From a Cloudmin System Image

Once you have at least one system setup to host Citrix Xen instances and registered with Cloudmin, and have downloaded at least one Citrix Xen system image, you can create your first virtual system. The steps to do this are :

1. On the left menu, open the Create System link and click on Create Citrix Xen VM. This will open the Create New System page.
2. In the System hostname field, enter a short hostname for the new instance. This does not need to include a domain name - it will be appended automatically based on the Xen host selected.
3. In the System description field enter a short description, like Foo Corp's webserver.
4. From the Initial system image menu, select the OS image to install. We provide images for CentOS and Debian.
5. In the Root login mode section, select Using password and enter the root password to set for the new system into the adjacent field.
6. In the Webmin installation mode section you do not have to select anything if you have chosen to use an image with Virtualmin, as Webmin will be installed automatically.
7. Because the selected image may include old packages, you should set the Update Virtualmin packages? field to Yes, so that Cloudmin will install all available updates after instance creation.
8. From the Citrix Xen hosting system menu, select the host on which this Xen system should be created. It is generally a good idea to spread your instances across hosts to avoid putting too much load on a single system.
9. If the new Xen system with run Virtualmin, you should increase the Memory allocated to instance field to 512 MB, or even more if the host system has enough RAM.
10. By default, Citrix Xen VMs created from images with Virtualmin Pro have 2 GB filesystems, while those without it get 1 GB. In both cases, there is only about 500 MB free. To increase the size of the instance's filesystem, use the Disk space allocated to instance field.
11. If the image contains Virtualmin Pro, you will need to select a license for it using the License for Virtualmin from image field. See the Virtualmin Licenses page for more details on aquiring and registering licenses, so that they can be easily allocated at system creation time.
12. Finally, click the Create System button to start the creation process.

Because Xen instance creation involves the copying and uncompression of large filesystem images, the creation process may take up to 5 minutes. However, Cloudmin will display each step in the process as it is run, including copying the image file, un-compressing it, modifying the Xen filesystem to set the root password and IP address, and finally starting up the instance.

Assuming that everything works, the new virtual system will be added to the left menu. You will be able to use Cloudmin to rebooting, shut it down, start it up, or create Virtualmin domains on it, just as you could for any real system. If you no longer need this Xen VM2, it can be completely removed with the Delete System link on the left menu.

Creation From a Xen Template

Citrix Xen also allows a virtual system to be created empty, and setup to boot the installer for some Linux distribution or other operating system. This allows you to create a new VM into which you install Debian, CentOS or even Windows. The steps to do this are :

1. On the left menu, open the Create System link and click on Create Citrix Xen VM. This will open the Create New System page.
2. In the System hostname field, enter a short hostname for the new instance. This does not need to include a domain name - it will be appended automatically based on the Xen host selected.
3. In the System description field enter a short description, like New CentOS install.
4. From the Initial system image menu, select From Citrix Xen template.
5. In the Root login mode section, select Using password and enter the root password to set for the new system into the adjacent field.
6. From the Citrix Xen hosting system menu, select the host on which this Xen system should be created. It is generally a good idea to spread your instances across hosts to avoid putting too much load on a single system.
7. If the OS being installed needs more than the default of 128 MB of rAM, increase the Memory allocated to instance field.
8. From the Citrix Xen template menu select a template for the OS you plan to install, such as Debian Lenny 5.0.
9. In the Repository URL for template field enter the base URL appropriate for the selected Linux distribution. For Debian 5.0 this would be http://ftp.debian.org/ , while for CentOS 5 it would be like http://mirror.centos.org/centos-5/5.4/os/i386/ .
10. Click the Create System button to start the creation process.
11. Creation will be relatively quick, as only the installer for the new VM gets set up. Cloudmin will report the status as Ping failed, which is expected as networking has not been enabled yet.
12. Open the System State menu category and then click on Graphical Console. This will allow you to complete the install process as though you were accessing a physical system at the console. Be sure to enter the same root password, hostname and IP address that you chose above, or else Cloudmin will be unable to manage the new system.

    When it comes to disk partitioning, we recommend creating a single partition that does not use LVM or RAID - otherwise Cloudmin will be unable to access files in the VM when it is shut down. If you must use swap, put the swap partition at the start of the disk so that the partition with the filesystem on it can be expanded later.

13. Once installation is complete and the virtual system has been rebooted, click Refresh Status on the left menu - if all went well the status should show up as SSH.

Creating a KVM Virtual Machine

Once you have at least one system setup to host KVM instances and registered with Cloudmin, and have downloaded at least one KVM system image, you can create your first virtual system. The steps to do this are :

1. On the left menu, open the Create System link and click on Create KVM instance. This will open the Create New System page.
2. In the System hostname field, enter a short hostname for the new instance. This does not need to include a domain name - it will be appended automatically based on the KVM host selected.
3. In the System description field enter a short description, like Foo Corp's webserver.
4. From the Initial system image menu, select the OS image to install.
5. In the Root login mode section, select Using password and enter the root password to set for the new system into the adjacent field.
6. In the Webmin installation mode section you do not have to select anything if you have chosen to use an image with Virtualmin, as Webmin will be installed automatically.
7. Because the selected image may include old packages, you should set the Update Virtualmin packages? field to Yes, so that Cloudmin will install all available updates after instance creation.
8. From the KVM hosting system menu, select the host on which this KVM system should be created. It is generally a good idea to spread your instances across hosts to avoid putting too much load on a single system.
9. If the new KVM system with run Virtualmin, you should increase the Memory allocated to instance field to 512 MB, or even more if the host system has enough RAM.
10. By default, KVM instances created from images with Virtualmin Pro have 2 GB filesystems, while those without it get 1 GB. In both cases, there is only about 500 MB free. To increase the size of the instance's filesystem, use the Disk space allocated to instance field.
11. If the image contains Virtualmin Pro, you will need to select a license for it using the License for Virtualmin from image field. See the Virtualmin Licenses page for more details on aquiring and registering licenses, so that they can be easily allocated at system creation time.
12. Finally, click the Create System button to start the creation process.

Because KVM instance creation involves the copying and uncompression of large filesystem images, the creation process may take 5 to 10 minutes. However, Cloudmin will display each step in the process as it is run, including copying the image file, un-compressing it, modifying the KVM filesystem to set the root password and IP address, and finally starting up the instance.

Assuming that everything works, the new virtual system will be added to the left menu. You will be able to use Cloudmin to rebooting, shut it down, start it up, or create Virtualmin domains on it, just as you could for any real system. If you no longer need this KVM instance, it can be completely removed with the Delete System link on the left menu.

Creating a Solaris Zones Virtual Machine

Once you have at least one system setup to host Solaris Zones and registered with Cloudmin, you can create your first virtual system. The steps to do this are :

1. On the left menu, open the Create System link and click on Create Solaris Zone. This will open the Create New System page.
2. In the System hostname field, enter a short hostname for the new instance. This does not need to include a domain name - it will be appended automatically based on the Zones host selected.
3. In the System description field enter a short description, like Foo Corp's webserver.
4. From the Initial system image menu, select the OS image to install. Or you can select None - base OS only, which tells Cloudmin that the zone should be created by copying packages from the host system. If you do use an image, make sure you select one of the same architecture (X86 or Sparc) as the host system.
5. In the Root login mode section, select Using password and enter the root password to set for the new system into the adjacent field.
6. In the Webmin installation mode section you do not have to select anything if you have chosen to use an image with Virtualmin, as Webmin will be installed automatically.
7. Because the selected image may include old packages, you should set the Update Virtualmin packages? field to Yes, so that Cloudmin will install all available updates after instance creation.
8. From the Zones hosting system menu, select the host on which this zone should be created. It is generally a good idea to spread your instances across hosts to avoid putting too much load on a single system.
9. Finally, click the Create System button to start the creation process.

If you chose to create the zone from an image, the process will take 5 to 10 minutes, as the image needs to be transferred from the Cloudmin master and un-compressed on the host system. If you selected the base OS option it will take longer, as all packages that need to be copied from the host system. Either way, Cloudmin will display each step in the process as it is run, including copying the image file, un-compressing it, modifying the zones's filesystem to set the root password and IP address, and finally starting up the instance.

Assuming that everything works, the new virtual system will be added to the left menu. You will be able to use Cloudmin to rebooting, shut it down, start it up, or create Virtualmin domains on it, just as you could for any real system. If you no longer need this zone, it can be completely removed with the Delete System link on the left menu.

Creating a VServers Virtual Machine

Once you have at least one system setup to host Linux VServer instances and registered with Cloudmin, you can create your first virtual system. The steps to do this are :

1. On the left menu, open the Create System link and click on Create VServer. This will open the Create New System page.
2. In the System hostname field, enter a short hostname for the new instance. This does not need to include a domain name - it will be appended automatically based on the VServer host selected.
3. In the System description field enter a short description, like Foo Corp's webserver.
4. From the Initial system image menu, select the OS image to install. Or you can select None - base OS only, which tells Cloudmin that the VServer should be created by downloading and installing packages for the host system's Linux distribution.
5. In the Root login mode section, select Using password and enter the root password to set for the new system into the adjacent field.
6. In the Webmin installation mode section you do not have to select anything if you have chosen to use an image with Virtualmin, as Webmin will be installed automatically.
7. Because the selected image may include old packages, you should set the Update Virtualmin packages? field to Yes, so that Cloudmin will install all available updates after instance creation.
8. From the VServer hosting system menu, select the host on which this VServer should be created. It is generally a good idea to spread your instances across hosts to avoid putting too much load on a single system.
9. Finally, click the Create System button to start the creation process.

If you chose to create the VServer from an image, the process will take 5 to 10 minutes, as the image needs to be transferred from the Cloudmin master and un-compressed on the host system. If you selected the base OS option it will take longer, as all packages that need to be installed will be downloaded from the appropriate Linux distribution repository. Either way, Cloudmin will display each step in the process as it is run, including copying the image file, un-compressing it, modifying the VServer's filesystem to set the root password and IP address, and finally starting up the instance.

Assuming that everything works, the new virtual system will be added to the left menu. You will be able to use Cloudmin to rebooting, shut it down, start it up, or create Virtualmin domains on it, just as you could for any real system. If you no longer need this VServer instance, it can be completely removed with the Delete System link on the left menu.

Creating a Xen Virtual Machine

Once you have at least one system setup to host Xen instances and registered with Cloudmin, and have downloaded at least one Xen system image, you can create your first virtual system. The steps to do this are :

1. On the left menu, open the Create System link and click on Create Xen instance. This will open the Create New System page.
2. In the System hostname field, enter a short hostname for the new instance. This does not need to include a domain name - it will be appended automatically based on the Xen host selected.
3. In the System description field enter a short description, like Foo Corp's webserver.
4. From the Initial system image menu, select the OS image to install. We recommend CentOS 5 with Virtualmin Pro.
5. In the Root login mode section, select Using password and enter the root password to set for the new system into the adjacent field.
6. In the Webmin installation mode section you do not have to select anything if you have chosen to use an image with Virtualmin, as Webmin will be installed automatically.
7. Because the selected image may include old packages, you should set the Update Virtualmin packages? field to Yes, so that Cloudmin will install all available updates after instance creation.
8. From the Xen hosting system menu, select the host on which this Xen system should be created. It is generally a good idea to spread your instances across hosts to avoid putting too much load on a single system.
9. If the new Xen system with run Virtualmin, you should increase the Memory allocated to instance field to 512 MB, or even more if the host system has enough RAM.
10. By default, Xen instances created from images with Virtualmin Pro have 2 GB filesystems, while those without it get 1 GB. In both cases, there is only about 500 MB free. To increase the size of the instance's filesystem, use the Disk space allocated to instance field.
11. If the image contains Virtualmin Pro, you will need to select a license for it using the License for Virtualmin from image field. See the Virtualmin Licenses page for more details on aquiring and registering licenses, so that they can be easily allocated at system creation time.
12. Finally, click the Create System button to start the creation process.

Because Xen instance creation involves the copying and uncompression of large filesystem images, the creation process may take 5 to 10 minutes. However, Cloudmin will display each step in the process as it is run, including copying the image file, un-compressing it, modifying the Xen filesystem to set the root password and IP address, and finally starting up the instance.

Assuming that everything works, the new virtual system will be added to the left menu. You will be able to use Cloudmin to rebooting, shut it down, start it up, or create Virtualmin domains on it, just as you could for any real system. If you no longer need this Xen instance, it can be completely removed with the Delete System link on the left menu.

Creating an EC2 Image

Introduction to EC2 Images

Unlike other virtual system types, EC2 images (called AMIs or Amazon Machine Images) are not stored on your Cloudmin master system. Instead they are stored as files inside Amazon's S3 storage service, and can be selected when creating a virtual system on EC2.

Each image has a unique ID, like ami-7c1df915, and a manifest path in S3 like centos-virtualmin-gpl-3.63/image.manifest.xml . An image can be either made available to everyone, or limited to certain EC2 accounts. Images can also be associated with production codes, indicating that customers must pay to use them.

Creating an EC2 Image

An image is created from a virtual system running on Amazon's EC2 service. The steps to make an image are :

1. Select your EC2 system from Cloudmin's left menu, then go to System Operations -> Create EC2 Image.
2. Enter a unique directory name for the image in S3 in the S3 bucket for image field. This should typically contain the operating system, version and purpose, such as //centos-5.3-webserver// .
3. If you have multiple EC2 accounts, select the one who will own this image from the Save under S3 account menu.
4. The size of an image determines the filesystem size of virtual systems create from it. The default is 5GB, but you can enter a larger size in the Size of image filesystem field. Make sure this is at least as big as the root filesystem on the system being imaged.
5. If you want anyone to be able to use this image, change Make image publicly available? to Yes.
6. If the bucket already contains an image and you want to replace it, change Overwrite AMI in same bucket? to Yes.
7. Click the Create Image button.

Once started, Cloudmin will display the progress of the image creation process. This can take up to an hour depending on the size and speed of the system.

Once creation is complete, Cloudmin will display the new image's ID. You can select this on the Create New System page to generate a new EC2 instance that will be a duplicate of the one you imaged. In additional, if you made the AMI publicly available the ID can be shared with any other EC2 users to use.

Managing EC2 Images

You can see all EC2 images Cloudmin knows about at Amazon EC2 -> EC2 Images. By default this includes those you created, images provided by Amazon, and public images from selected other accounts. The accounts to show are set at Cloudmin Settings -> Module Config -> EC2 accounts to display AMIs from.

To change the permissions on an image you created, just click on its ID in the list. On the page that appears you will be able to select if it is public (with the Grant access to everyone checkbox), or only available to a list of EC2 account numbers that you enter.

To remove an image, check the box next to it in the image list and hit the Delete Selected Images button at the bottom of the page. On the confirmation page that appears you will have the option of removing the associated files from S3 too, which is generally a good idea as you are charged for S3 usage by disk space and time.

Creating an EC2 Virtual Machine

Once you have at least one EC2 account registered with Cloudmin and one EC2-generated SSH key, you can create your first EC2 system. The steps to do this are :

1. On the left menu, open the Create System link and click on Create EC2 instance. This will open the Create New System page.
2. In the System description field enter a short description, like Foo Corp's webserver.
3. From the SSH key for root menu, select one of your keys. Typically you will only have one.
4. If you have multiple EC2 accounts registered, select one from the EC2 account menu. At the time of writing, Amazon only allowed 20 active instances per account.
5. From the EC2 image to start menu, select the image that defines the initial operating system and software stack for the instance. For webhosting you can use the virtualmin-pro image, or you can go with one of the base operating systems supplied by Amazon. Or if you have created your own EC2 images, you can select one of those.
6. Because the selected image may include old packages, you should set the Update Virtualmin packages? field to Yes, so that Cloudmin will install all available updates after instance creation.
7. Finally, click the Create System button to start the creation process.

Amazon is generally pretty fast to create new instances, and no data needs to be copied from the Cloudmin master to the new system. Typically this takes about 5 minutes, and Cloudmin will display each step taken in the system creation process.

Assuming that everything works, the new virtual system will be added to the left menu. You will be able to use Cloudmin to reboot it, update it, or create Virtualmin domains on it, just as you could for any real system. If you no longer need this zone, it can be completely removed with the Delete System link on the left menu.

Downloading System Images

A system image is effectively a file containing the entire filesystem of a virtual system, either in tar.gz or EXT3 format. When a virtual system is created by Cloudmin, it can use an image as the basis of the system's filesystem, rather than needing to download and install packages, or copy files from the host system.

Cloudmin customers have access to system images for a variety of operating systems and virtualization types, but by default none are included when it is installed. To download images that you can use to create systems, do the following :

1. On the left menu under Cloudmin Settings click on New System Images.
2. A page listing all available images will be displayed. Choose the ones you want based on the virtualization technology you prefer (such as Xen or Zones), and the Linux distribution that will run in the image.
3. Check the boxes next to the ones you want to use, and click the Download Selected Images button.
4. Depending on the speed of your network connection and the total size of those you choose, images may take minutes or hours to download. The progress of each download will be displayed.

You can now create virtual systems using the selected images, assuming that one or more host systems of the corresponding virtualization type have been registered.

If you are using Solaris Zones, only images for the architecture that matches the physical Solaris host systems will work. For Xen or VServers, I recommend selecting images of the same type as your host systems, just to keep management easier.

Some images include the full Virtualmin stack, such as Webmin, Apache, Postfix, BIND, MySQL, ProFTPd and so on. If you plan to create virtual systems for web hosting, we recommend using these images rather than manually installing Virtualmin on created systems - even though VM2 is capable of doing this for you.

VM2 does not limit you to provided images - once you have some virtual systems running, you can create your own, as documented on the Making Your Own Images page.

EC2 Security Groups

Introduction to Security Groups

An EC2 security group is basically a set of firewall rules that can be applied to EC2 instances. Each rule specifies a protocol (TCP or UDP), starting and ending port numbers, and an optional network. When a group is applied to a system, only traffic matching one of the rules will be allowed through. All other traffic will be dropped.

In addition, a security group can list other groups to allow traffic from, regardless of port or address. This will then match other EC2 systems using one of the selected groups. This feature is useful for allowing arbitrary connections between your own machines, while applying stricter restrictions on other systems.

By default every EC2 account has a security group named default that allows connections on a limited number of ports. Cloudmin will create a group named virtualmin when you create a system that allows all the ports typically used for web hosting, such as 110, 80, 443 and 25.

Editing a Security Group

If you want to change the rules for an existing group, the steps to take are :

1. Go to Amazon EC2 -> EC2 Security Groups, and click on the group you want to edit.
2. On the page that appears all current rules will be listed. You can change the port range, protocol or allowed addresses for some rule, or use the empty row at the bottom to add a new rule.
3. To allow network traffic from systems on some other group (or this group), select an EC2 account in the Allowed security groups section and enter the group name in the adjacent field.
4. Click the Save button to activate your changes.

To create a new group, go to the EC2 Security Groups page and click the Create group for link for the EC2 account you want to add it under. Then fill in rules form with protocols and ports to accept. Make sure you allow at least port 22 (for SSH) and port 10000 (for Webmin), or Cloudmin's access to systems using this security group may be blocked.

To delete a security group that is not in use, check the box next to it on the EC2 Security Groups page and hit the Delete Selected Security Groups button.

Applying a Security Group

A security group can be selected when creating a new EC2 system, using the EC2 security groups field under Advanced options. Actually, you can choose several groups, and traffic matching rules from any of them will be allowed. If you have multiple EC2 accounts in Cloudmin, only groups for the account selected to own the new system can be used though.

If no security group is chosen, just the default group will be used. If a group is changed after system creation (such as to add a new port), it will be immediately applied to all virtual systems using that group. There is no way to select different groups for a system after it is created though.

EC2 Static IP Addresses

IP Addresses on EC2

Every EC2 instance has two IP addresses - the real one on its eth0 interface (typically in the 10.0.0.0/8 network), and an external Internet-accessible address. The Amazon using NAT to foward all traffic to the external address to the internal one, and back again for outgoing connections.

Both addresses are dynamically assigned when a system is created. Because an EC2 instance may need to be destroyed and re-created, there is no guarantee that a replacement instance will get the same IP address that a previous system did, even one under the same account.

However, Amazon does allow EC2 accounts to request static IP addresses, which they call Elastic IPs. Each static IP can be associated with a single EC2 instance at a time, and can be moved between instances. This allows you to keep your external addresses consistent in the face of virtual system creation and deletion.

Creating and Managing Static Addresses

To request a new static EC2 address, follow these steps :

1. Login to Cloudmin, and go to Amazon EC2 -> EC2 Static IP Addresses.
2. Select an EC2 account from the menu at the bottom of the page (if you have more than one), and click the Allocate New Address button.
3. If all goes well, the new IP will show up in the list on the same page.

Amazon bills for each static IP address associated with your access, so don't request too many of them!

To give back an address, check the box next to it and click the Return Selected IP Addresses button. Be careful doing this, as you will not be able to request the same address again. Only addresses not assigned to any system can be returned.

Assigning a Static Address

Once an address has been requested, you can assign it to an EC2 system as follows :

1. Select the system from the left menu, and go to System Operations -> Assign EC2 Address.
2. Select the address from the IP address to assign menu, and click Update IP Address.
3. Wait for Cloudmin to detect that the new address has been applied. This may take several minutes.

You can also dis-associate an address from a system on the same page, by selecting <None> from the IP address to assign menu.

EC2 Volumes

Introduction to EC2 Volumes

EC2 Volumes (called Elastic Block Storage by Amazon) are essentially disk images that can be mounted on any system running on EC2, and continue to exist even if the system they were attached to is deleted. They are a more permanent place to store data than the filesystem of an EC2 instance, and more easily accessible than S3.

Each volume is typically formatted with a filesystem like EXT3, and is mapped to a device like /dev/sdb1 on the system it is connected to. It can then be mounted with the standard Linux mount command. The size of a volume is typically several GB, and is chosen at creation time. Amazon charges for volumes based on their size and the amount of time they exist.

EC2 Volume Snapshots

An EC2 volume snapshot is a copy of a volume taken at some point in time, and stored in S3. Once a snapshot has been created, additional volumes can be created from the data in that snapshot. They can be used for backup purposes, or to duplicate or fork the contents of a volume.

Snapshots are differential backups, meaning that only the blocks on the device that have changed since your last snapshot will be incrementally saved. This means that if you have a device with 100 GBs of data, but only 5 GBs of data has changed since your last snapshot, only the 5 additional GBs of snapshot data will be stored back to Amazon S3.

Creating and Managing EC2 Volumes

To create an EC2 volume in Cloudmin, do the following :

1. Login to the UI as root and go to Amazon EC2 -> EC2 Volumes.
2. In the New volume details form, choose your account from the EC2 account menu.
3. Enter a size in the EC2 account field, or select a snapshot to copy this volume from.
4. From the Availability zone menu, select the zone that your EC2 systems have been created in. A volume can only be attached to systems in the same zone.
5. Click the Create button.

Once a volume has been created, it will appear in the list on the EC2 Volumes page. To remove it, check the box next to it's ID and click the Delete Selected Volumes button. Be careful, as the data on the volume will be lost forever (unless you made a snapshot first).

Creating and Managing EC2 Snapshots

Once you have at least one EC2 volume, Cloudmin will allow you to create a snapshot of it as follows :

1. Go to Amazon EC2 -> EC2 Volumes, and click on the EBS Snapshots tab.
2. In the New volume snapshot details section, select the volume to copy from the Copy from volume menu.
3. Click the Create button.

Once a snapshot has been created, it can be used to create new volumes as explained above. Snapshots can be deleted on the EBS Snapshots* tab by checking the boxes next to their names and clicking the Delete Selected Snapshots button.

Assigning Volumes to Systems

Once a volume has been created, it can be attached to an EC2 instance as a block device, and typically mounted a filesystem. This can be done within Cloudmin like so :

1. Select your system from the left menu, and go to Resources -> Attached EC2 Volumes.
2. In the Volume attachment options form, select the volume from the Volume to attach menu.
3. If this is a new volume that has not been mounted anywhere yet, change the Format with filesystem to EXT3. Otherwise, leave it set to Dont format to preserve existing data.
4. To have Cloudmin attempt to mount the volume, enter a path in the Mount on directory field like /mnt/disk2 or /home.
5. Click the Attach EC2 Volume button.

Once a volume has been attached and mounted, you can use it on your EC2 system however you wish. To detach a volume, go to the ttached EC2 Volumes page, check the box next to its ID and click the Detach Selected Volumes.

Empty Systems

Introduction to Empty Systems

Cloudmin uses the term "empty system" to refer to one that is created without any operating system initially installed on its virtual disk. Empty systems are always connected to a CD image or physical CD-ROM drive, from which any operating system can be installed. Once the install is complete, the formerly empty system can be managed like any other Cloudmin virtual machine.

The open-source Xen, KVM and Citrix Xen virtualization types all support the creation of systems that are initially empty. In the case of Xen, full hardware virtualization (HVM) is used, which has a performance overhead as compared to para-virtualization. However, HVM allows any operating system to be run inside the virtual system, such as OpenBSD, Windows or other Linux distributions.

Cloudmin will not be able to fully manage non-Linux virtual systems though, as it cannot access files inside their filesystems. This prevents Cloudmin from editing network interfaces unless the system is up and running Webmin, and from fully managing virtual disks.

Creating CD Images

Before creating an empty system, you should add the CD image that you plan to install it from to Cloudmin's system images list. This can be done as follows :

1. Login as root and go to Cloudmin Settings -> New System Images.
2. Click Create image for Xen (or whatever virtualization type you are using).
3. In the Image file format field, select CD or DVD ISO.
4. In the Image source field, enter the path or URL to the .iso file for the CD image.
5. Enter a short name for the image in the Unique ID for image field, like xen-debian5-cd.
6. Enter a longer description in the Description for image field.
7. Change Compress image file to No.
8. Click the Create button.

Depending on where the image file has to be fetched from and whether it is initially compressed or not, the creation process may take from seconds to minutes. Once it is complete, you should see it appear on the New System Images page.

Setting up DHCP

When Cloudmin creates an empty virtual system, the IP address that it selects for that system cannot actually be inserted into the appropriate configuration files until after the OS install is complete. Because the OS install is done manually, it is possible that the virtual system might be assigned a different IP address to what Cloudmin expects it to have, which will cause the status to be falsely shown as "Ping failed". This prevents the system from being fully managed by Cloudmin.

The best solution to this issue is to setup a DHCP server on your Cloudmin master system, which will then be automatically configured for each new virtual system so that systems can obtain the correct IP address. The steps to do this are :

1. Login to Cloudmin at root , and go to Webmin -> Servers -> DHCP Server
2. If the DHCP server is not installed yet, you may be prompted to have Webmin install it on that page. If this prompt doesn't appear, you will need to install it manually using whatever package or method is appropriate for your operating system.
3. If the Start Server button appears at the bottom of the page, click it to start DHCPd.
4. On the left menu, go to System -> Bootup and Shutdown, check the box next to the dhcpd or dhcp-server action, and click the Start on Boot button.
5. Go to Cloudmin -> Cloudmin Settings -> Cloudmin Configuration -> DHCP settings and change Add DHCPd host for virtual systems? to Yes.

Once this is done, Cloudmin will add a DHCP host entry for each new virtual system it creates. However, this will only be actually used if your master system and Xen or HVM hosts are on the same subnet. If not, you will need to setup the appropriate firewall rules or router configurations to forward DHCP packets from other networks to your Cloudmin master.

Creating Empty Systems

The process of creating a new empty virtual system is mostly similar to that for creating a full system. The steps to follow are :

1. Open the Create System category on the left menu, and click on Create Xen instance (or whatever virtualization type you want to use).
2. Select the Create empty system tab.
3. Enter a short name in the Internet hostname field, like gentoobox.
4. Enter a longer description in the System description field, like Gentoo Linux install.
5. In the *Installation CD image * field, either select a CD image that you added to Cloudmin as documented above, or enter the path to an ISO format CD or DVD file on the host system.
6. If you entered a CD image page, make sure the correct host is selected in the Xen hosting system field.
7. In the Resource limit options section, enter the size of the system's empty virtual disk in the Disk space allocated to instance field.
8. Click the Create System button.

Creation should take less time than in would for a Cloudmin system created from an image. At the end of the process, you will have a virtual system whose status is Ping failed, which indicates that Cloudmin could not contact it on the assigned IP address. This is expected, as the system will be waiting for you to complete the OS install process as follows :

1. Open the System State menu category, and click on Graphical Console.
2. You should now see the initial installation screen of the operation system whose CD image you selected. Begin the install process, just as you would on a real system.
3. When you reach the disk partitioning step, make sure that the virtual drive is given only a single partition which contains the root filesystem. Having multiple partitions may make it impossible for Cloudmin to expand the disk later.
4. When prompted for the system's IP address and hostname, if they do not get correctly assigned by DHCP, make sure you enter the same IP and hostname that Cloudmin selected when the empty system was created.
5. Complete the rest of the install process as normal. Keep a note of the root password that you select.
6. Go to System State -> Change Boot Method , and set the boot device to Hard disk only.
7. Click on Edit System, and in the Authentication options section change the SSH login mode to Using password and enter the password you chose during the install process.
8. Shut down the virtual system, then start it up again.
9. Make sure that Cloudmin now shows the system's status as SSH.

If the new system is not contactable by Cloudmin after rebooting, use the Graphical Console page to ensure that it has fully booted from the hard disk, and has the correct IP address.

Managing Empty Systems

Once an empty system has been fully installed, it can be managed by Cloudmin like any other virtual machine. However, Xen instances created this way will always use HVM virtualization, as will any clones created from them. If you create an image of an initially empty Xen instance and then create a new virtual system from that image, it will also use HVM.

Open source Xen systems that were initially created empty will use virtual disks that are in whole-disk format, rather than single-partition format. This generally has no impact on the user, but if the disk has more than one partition it may be impossible to expand its size if both partitions are mounted.

Getting Started With Cloudmin

Recommended Systems

Techically you can run Cloudmin on just a single system, which will be both the master that runs the UI and the host for your virtual systems. However, a more common setup has multiple host systems, one of which is typically also the Cloudmin master on which the install script is run.

If you have a choice of operating systems and are planning to host Xen or OpenVZ instances, we recommend running the latest version of CentOS if possible. The CentOS YUM repository includes a kernel with Xen support and all the needed Xen tools. For more details on how to setup each host system, see the Xen documentation.

If you plan to host OpenVZ containers, a kernel for CentOS that supports them is available from the OpenVZ website. The same website has a kernel that can run both Xen and OpenVZ on the same host, which is fully supported by Cloudmin.

Regardless of the virtualization type you choose, your host systems should have plenty of RAM - a typical Xen instance will consume at least 512MB of RAM, while OpenVZ containers are usually assigned 256MB or more. For Xen hosts, we recommend 4-8 GB RAM and plenty of CPU cores. Running a 64-bit distribution is not generally needed for systems with less than 4GB of RAM, and can actually be counter-productive due to the increased RAM use.

SSH Key Configuration

Once Cloudmin is installed, the first thing you should do is add an SSH key that can be used to login to your host systems as root. The steps to do this are :

1. Go to Cloudmin Settings -> SSH Keys, and click on Add a new SSH key.
2. Fill in the Key description field, and enter the path to the private key file into the In existing file box, such as /root/.ssh/id_rsa
3. Change the Add to root's authorized keys field to Yes.
4. Click the Create button.

Alternately, you can have Cloudmin generate a new key or use one that you paste in on that same form.

DNS Configuration

Cloudmin adds all newly created virtual systems to a DNS zone hosted on the master system. If your company's domain is example.com, you might name this xen.example.com, and add an NS record to the example.com zone for this sub-domain.

To create this DNS zone on your Cloudmin master, do the following :

1. Go to Webmin -> Servers -> BIND DNS Server, and click on Create master zone.
2. Enter the name you chose into the Domain name field, such as xen.example.com.
3. In the Master server field, enter the externally resolvable name for your Cloudmin master system, such as cloudmin.example.com.
4. Enter your email addresss in the Email address field.
5. Click the Create button, then the Apply Configuration link in the top-right corner of the page.

Adding Host Systems

Before you can use a real system to host virtual systems (like Xen or OpenVZ containers), it must be added to Cloudmin. For a host other than the Cloudmin master, the steps to follow are :

1. Go to Add System -> Add physical system .
2. Fill in the Internet hostname field with the resolvable hostname or IP address of the machine.
3. Fill in the SSH login mode section, possibly selecting the key you added above.
4. If the system already has Webmin installed, fill in the Webmin login mode section.
5. Click the Add System button.
6. Assuming the details you entered were correct, the new system should appear on Cloudmin's left menu.
7. If the system doesn't have Webmin installed yet, select it from the left menu, then go to System Operations -> Install Webmin.

To enable this system for hosting virtual machines, you should first ensure that it has the kernel and tools installed for the virtualization type you are using. Then follow these steps :

1. Open the Host Systems category on the left menu, and click on the link for the VPS type that you want to host, such as Xen Host Systems.
2. Click the Register a system for Xen hosting link, and select it from the System hosting Xens menu.
3. In the IP address allocation range section, select an IP range that you defined earlier. Alternately, you can enter a starting and ending IP address to assign to Xen instances. This should be on the same subnet as the host system's primary network interface. This is typically supplied by your ISP or hosting company.
4. Select the DNS domain you created earlier from the Add Xen systems to DNS domain field.
5. If your host system has plenty of disk space, open the System image cache section and fill in the Maximum image cache size field. A cache of 5 to 10 GB is generally enough.
6. If your host system has LVM setup, we recommend using it for storing Xen disk image due to the performance benefits. Enter the volume group name in the LVM volume group field.
7. Finally, click the Register button.

If Cloudmin does not detect any problems with the host system, it can now be used to host new virtual instances.

Downloading Images

Cloudmin comes with pre-created images for creating virtual systems of all the supported types. However, they must be first downloaded to your master system before they can be used, as follows :

1. Go to Cloudmin Settings -> New System Images, and check the boxes next to the images you want.
2. Click the Download Selected Images button at the bottom of the page, and wait for the downloads to complete.

For each virtualization type (such as Xen and OpenVZ), images are available with CentOS and either Debian or Ubuntu Linux, plus possibly other distributions. For each Linux variant, an image containing just the base operating system is available, plus images containing Virtualmin GPL and Pro.

Creating Your First System

Once all the steps above are complete, you can create a new virtual system as follows :

1. Open the Create System menu category, and click on the link for the VPS type that you want to create.
2. Enter a short hostname for the new system in the System hostname field, such as myvps.
3. Select the image for the new system from the Initial system image menu.
4. Enter a root password in the SSH login mode field.
5. Optionally enter memory and disk limits in the Resource limit options section.
6. Click the Create System button.

How to use the Cloudmin documentation

Organization

Documentation is divided into a few categories, such as "Virtualization", "Installation", and "Administrative and User Accounts", which covers the common types of service you'll be managing with your Cloudmin installation. Within each category you'll find a few types of document, such as "FAQ", "Troubleshooting", and specific task guides.

Pages labeled "FAQ" or "Frequently Asked Questions" are intended primarily for common questions new users, or potential users, ask about Cloudmin and the machines it manages. For example, the FAQ for Xen includes a brief, non-technical, description of the Xen virtualization layer and how Cloudmin interacts with it. The FAQs are generally non-technical in nature, and do not generally provide solutions to problems. They are conceptual and broad, merely to describe the way Cloudmin does things.

Pages labeled "Troubleshooting" are intended to help you solve specific problems. If you are receiving an error message from a service or Cloudmin, the troubleshooting section for that particular area may have solutions. Troubleshooting pages are specific and technical, and are intended to help you solve problems.

Search

You can also search just the documentation by opening the search form and using the Advanced Search form to search within content "Only of the type(s)" and choosing "Book page".

The search page, by default, searches all of the content on Virtualmin.com, including forums, issues, and documentation. This may, or may not, be what you want, depending on the questions you have.

Installing Cloudmin

Cloudmin 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 Cloudmin Installation - Installation of the full Cloudmin stack using our automated install script. This is the recommended way to install Cloudmin.

Manual Cloudmin Installation - Installation of Cloudmin and related packages manually. This is the method recommends for systems that are not currently supported by the automated install script.

Installation Troubleshooting - Troubleshooting common problems encountered during installation.

Uninstalling Cloudmin - Uninstallation of Cloudmin and selective removal of packages.

rpm -e webmin wbm-server-manager wbt-virtual-server-theme wbt-virtual-server-mobile wbm-security-updates
rm /etc/yum.repos.d/cloudmin

dpkg --remove webmin-server-manager webmin-virtual-server-theme webmin-virtual-server-mobile webmin-security-updates
grep -v cloudmin.virtualmin.com /etc/apt/sources.list >/etc/apt/sources.list.tmp && mv /etc/apt/sources.list.tmp /etc/apt/sources.list

Introduction to Virtualization Concepts

What is Virtualization?

In Cloudmin, virtualization refers to running a virtual system that appears from the inside to be a real computer, but is actually being emulated on a real machine. The terms "virtual machine" and "VPS" are also used to refer to these, as are type-specific terms like "Xen guest", "OpenVZ container" and "EC2 instance". There are several different technologies that can be used to implement virtualization, which varying support for different operating systems, resource isolation and resource overheads.

Why Use Virtualization?

The most common case is to provide customers or users with what appears to be their own system on which they have full root access and control of all services, but without the overhead of maintaining an actual physical machine. For example, a hosting company might sell virtual systems to customers which in turn use them for web hosting, database hosting or email.

A single physical machine can host multiple virtual systems, each of which is granted a slice of its memory, disk space and CPU time. Each virtual system is protected from others on the same host system. Because many applications or customers do not require the full CPU, RAM or disk capacity of a real systems, virtualization can be used to safely host several on a single physical system, thus saving resources.

Another advantage of Virtualization is the ability to easily move virtual systems between hosts without interruption or the need to re-install applications. If a hardware problem is detected on a host system, all virtual machines on it can be moved to a new host without changing their IP addresses or other settings, and possibly without even interrupting running processes.

Virtualization Types

Not all virtualization technologies are created equal - some (like Xen) provide more isolation between systems but at the cost of additional CPU and RAM overhead, while others (like OpenVZ) can be used to host more virtual systems per physical system, but with more chance of cross-system disruption.

Virtualization types can be generally separated into two categories :

• Separate Kernels
  Examples : Xen, KVM, Amazon EC2
  These types run a separate kernel for each virtual system, and typically store system files within a disk image or logical volume instead of on the host system's filesystem. RAM used is higher due to the need to run a copy of the kernel for each system, and free disk space and RAM cannot be used by other systems. However they provide more protection and isolation between systems, allow different kernels to be used, and provide more flexibility in filesystem and disk usage within the virtual systems.

• Shared Kernel
  Examples : OpenVZ, Vservers, Solaris Zones
  These types run under the host system's kernel, which provides filesystem and process isolation between systems. Typically each system's files are stored under some directory on the host, possibly with common files like binaries being shared. They offer less isolation and force use of the same kernel, but the per-virtual-system RAM, CPU and disk overhead is lower. Also, RAM and disk space can potentially be over-committed to make better use of host system resources.

Which Virtualization Type to Use?

If you are running Solaris systems, you really only have one choice - Solaris Zones.

On Linux, your choice depends on the level of isolation you want and how much RAM and CPU overhead you are willing to tolerate. Given the ample CPU and RAM on most modern systems, we recommend using Xen as the overhead is usually tolerable unless you plan to run a large number of small virtual systems. In that case, OpenVZ is the best solution. KVM is similar to Xen in its resource use, but tends to have more overhead as it does not support paravirtualization.

Cloudmin also supports Linux Vservers, but this appears to be poorly maintained and offers no advantages over OpenVZ.

Amazon EC2 is different from other virtualization types in that the virtual systems don't actually run on your own machines - instead, they are hosted by Amazon for an hourly cost. It is worth using if your needs are highly variable, for example if you plan to run a hundred systems for a few hours a day then shut them down.

Location Groups

Introduction to Location Groups

A location group contains a set of host systems, typically in the same physical location. When a virtual system is created you can select a location group instead of a specific host, and Cloudmin will choose a host from that group based on some selection method. The selection may be random, or based on free memory or disk space.

Location groups are most useful when you have a large number of host systems in different locations, and want to avoid selecting an appropriate one manually for each new virtual system. It is quite possible to have just a single location group if all your host systems are in the same datacenter and treated equally for allocation purposes.

Creating a Location Group

To add a new location group, do the following :

1. Login to Cloudmin and go to Host Systems -> Location Groups.
2. In the first empty row check the box in the Active column.
3. Enter a name for the group in the Description column.
4. Select an allocation method from the Host selection method column. We recommend Most free RAM, as that is the resource likely to run out first.
5. Click the Save button.

Once a group has been created, you can assign a host system to it as follows :

1. Open the Host Systems category on the list menu and click on the link for your host system type, such as Xen.
2. Click on the host you want to assign.
3. Select the group from the Location group menu, then click Save.

Once at least one running host system is in a group, you will be able to select it on the Create System page.

Making Your Own Images

Images for Xen, VServers or Zones

Image Storage Locations

Images for EC2

Managing CPU Limits

Virtual System CPU Limits

Xen, OpenVZ and Vserver virtual systems can have limits imposed that restrict the amount of CPU they can consume on the host system. This limit is typically expressed as a percentage, where 100% means the right to use a full CPU core. On a multi-core host system, a limit could thus be set to more than 100%. It is also possible to turn off the CPU limit for a virtual system completely, which allows it to consume as much of the host's resources as it wants.

CPU limits can be used to prevent a single virtual system from overwhelming others on the same host. For example, you might want each customer to be limited to 50% CPU, meaning that 8 such systems could run on a 4-core host without impacting each other. CPU can also be over-committed, which is typically safe as most systems use CPU in bursts.

Setting Limits in Cloudmin

The CPU limit for a new system can be set on the creation form, in the Resource limit options section. After creation it can be modified at Resources -> Resource Limits, and takes effect immediately without the need for a reboot.

Xen systems also support setting a CPU weighting, which determines how much CPU it is granted when the host system is over-committed. A system with a weight of 200 will get twice as much CPU as one with a weight of 100, but only if the total CPU percentages granted to running systems exceeds the host's capacity.

Xen CPU Pinning

Xen also supports multiple virtual CPU cores within a system, each of which can be mapped to a core on the host. This can be configured at Resources -> Manage Virtual CPUs. It can be useful for separating Xen systems by assigning each to a different core on the host, so that there is no possibility of contention.

CPU Limits and System Owners

Account plans can be used to define a total CPU limit for system owners, which applies to the sum of all limits applied to systems belonging to the owner. For example, if an owner has a limit of 80% CPU he could assign 40% to one system, and 40% to another. Or he could create just a single system with a 80% limit. In no case will he be allowed to set a virtual system to unlimited CPU though.

Managing Network Interfaces

Introduction to Network Interfaces

Each virtual system managed by Cloudmin has at least one network interface / IP address, which the system's hostname typically resolved to in DNS. On the virtual machine this usually appears as eth0 - how it appears on the host system differs depending on the type of virtualization being used.

It is possible for virtual system to have multiple network interfaces. For Xen and KVM instances on host systems with more than one bridge, the virtual machines can have one ethN interface per bridge. Typically each is connected to a different physical network or VLAN on the host system.

Cloudmin lets you add extra IP addresses to a virtual system, although these will usually be virtual interfaces like eth0:5. This is useful if you want a VPS to host multiple SSL-protected websites, each of which needs its own IP address.

System owners can be either completely denied access to page for managing network interfaces, or limited in how many IP addresses they can use across all their virtual machines. This can be done either at the plan level, or on an owner-by-owner basis.

Cloudmin can manage network interfaces on any system running Webmin, or with a Debian-based or Redhat-based Linux distribution installed. It can even manage interfaces on a down system, assuming it is running Debian, Ubuntu, RHEL, Fedora or CentOS. This allows you to fix networking errors even if a system is in-accessible, by first shutting it down and then using Cloudmin to edit interfaces.

Adding a Virtual Network Interface

To create a new network interface, the steps to follow are :

1. Select the system from the left menu, open the System Configuration category and click on Network Interfaces.
2. Underneath the list of existing interfaces, click the Add a virtual interface link.
3. If the virtual system has more than one bridged interface, select the one you want to add a virtual interface to from the Real interface menu.
4. Either enter an IP for the new interface from the IP address menu, or select Allocate automatically to have Cloudmin pick one from the allocation range you have specified for its host system.
5. Change the netmask if needed - but typically the default will work fine.
6. Click the Create button.

The new IP address should be immediately activated and pingable, and will be added to both the networking configuration files on the virtual system, and any virtualization config files on the host system.

Adding a Real Network Interface

Xen and KVM virtual systems also support creation of non-virtual interfaces, which appear like eth1 on the virtual machine. If the host system has multiple network bridges you can select which bridge each new real interface is connected to - it is also possible to have multiple real interfaces bridged to the same real interface on the host.

To create a new real network interface, the steps to follow are :

1. Select the system from the left menu, open the System Configuration category and click on Network Interfaces.
2. Underneath the list of existing interfaces, click the Add a real interface link.
3. The Network interface name field can generally be left un-changed, as Cloudmin will pick the next free ethN device on the virtual system.
4. If the virtual system has more than one bridge, select the one you want from the Network bridge on host menu.
5. Either enter an IP for the new interface from the IP address menu, or select Allocate automatically to have Cloudmin pick one from the allocation range you have specified for its host system.
6. Change the netmask if needed - but typically the default will work fine.
7. Click the Create button.

The new IP address should be immediately activated and pingable, and will be added to both the networking configuration files on the virtual system, and any virtualization config files on the host system.

Editing and Deleting Interfaces

To change or remove an interface, do the following :

1. Select the system from the left menu, open the System Configuration category and click on Network Interfaces.
2. Click on the address for the interface you want to manage.
3. If it is a virtual interface (like eth0:5) or a real interface other than the first, you can click the Delete button to remove it.
4. Otherwise, change any of its details such as the IP, netmask or MAC address, and click Save.

Again, all changes will be activated immediately with the exception of a change in the MAC address. That will only take effect when the virtual system is shut down and started up again. Only Xen and KVM systems can have their MAC addresses changed, and only for non-virtual interfaces.

Changing the Default Gateway

Cloudmin can edit the default router on a running system with Webmin installed, or a down system with a support Linux distribution (Redhat or Debian based). The steps to do this are :

1. Select the system from the left menu, open the System Configuration category and click on Network Interfaces.
2. Below the list of interfaces is a Default gateway options form.
3. Change or clear the gateway in the Gateway IP address field.
4. Click Save.

Be careful doing this on a running virtual system though, as you may cut off access to the Cloudmin master.

DHCP and MAC Addresses

Cloudmin can be configured to setup the DHCP server on your master system to supply virtual machines with IP addresses. This can be useful if you want to use system images for operating systems that Cloudmin cannot configure the network on directly, such as Windows or FreeBSD.

The steps to setup a DHCP server are as follows :

1. Make sure the ISC DHCPd software is installed. On Redhat or CentOS systems, this can be done with the command : yum install dhcp On Debian or Ubuntu, the command is : apt-get install dhcp3-server
2. In Cloudmin, go to Webmin -> Servers -> DHCP Server , and add a subnet for the IP network that your virtual systems will be on.
3. Make any other configuration changes to the DHCPd settings that you want, such as on the Edit Client Options page. Here you can set default nameservers and gateways for your virtual systems.
4. Click the Start Server or Apply Changes button, and verify that DHCPd starts OK.
5. Go to Cloudmin -> Cloudmin Settings -> Module Config -> DHCP settings.
6. Change the Add DHCPd host for virtual systems option to Yes.
7. In the Add DHCPd hosts to subnet field, enter the IP address of the subnet that you added in step 2 above.
8. Click Save.
9. Create a new KVM or Xen virtual system, and ensure that it successfully adds a DHCP host entry during the creation process.

Managing RAM Limits

Virtual System RAM Limits

For Xen, OpenVZ and Vserver virtual systems, Cloudmin can define a limit on the amount of RAM the virtual system can consume. This prevents a single system from consuming all the RAM on the host, and allows you to parcel out memory based on how much a customer pays or what an application requires.

OpenVZ and Vserver systems can also be configured with no RAM limit, which allows them to potentially consume all RAM on the host. Memory that is not actually used by processes running within the system is potentially available to other virtual systems or processes on the host, which means that RAM can potentially be over-committed.

Xen systems always have a fix RAM limit, and do not allow that block to be shared with other systems while the Xen instance is running. Thus there is no possibility of over-committing RAM.

Setting Limits in Cloudmin

When you create a virtual system, the initial RAM limit can be set in the Resource limit options section of the creation form. After creation, it can be adjusted at Resources -> Resource Limits. In most cases, RAM available can be changed without needing to reboot the virtual system. However, setting it lower than the amount actually consumed by the kernel and running processes may cause the system to crash.

In all cases the new RAM limit will be saved in the appropriate config file for the virtual system, and re-applied if it is rebooted.

RAM Limits and System Owners

Account plans can be used to define a total RAM limit for system owners, which applies to the sum of all limits applied to systems belonging to the owner. For example, if an owner has a limit of 1GB RAM he could assign 512M to one system, and 512M to another. Or he could create just a single system with a 1GB limit. In no case will he be allowed to set a virtual system to unlimited RAM though.

Managing Virtual Disks

Virtual Disks on Xen and KVM

Cloudmin currently only supports management of virtual disk images for Xen and KVM systems, as other virtualization types use a directory on the host filesystem to store files instead of images.

Each open source Xen system has one or more files or devices on the host system (like /xen/mysystem.img mapped to devices on the virtual system (like /dev/sda1). The disks on the host can be regular files, LVM logical volumes, or actual disk partitions. In the virtual system, these are typically mapped to partitions, but can be an entire disk.

When Cloudmin creates a new Xen system, it will also build at least one virtual disk whose contents are a copy of the selected system image. If you select to enable swap as well, another disk will be created for the swap file. These will be mapped to /dev/sda1 and /dev/sda2 on the virtual system respectively.

For KVM, files or devices on the host system (like /kvm/mysystem.img) are mapped to entire disks on the virtual system (like /dev/hda). This disk image then contains one or more partitions, which can be mounted as filesystems on the virtual machine, or used for LVM or RAID.

When Cloudmin creates a new KVM system, it will create a disk image typically with a single partition. This is then mounted as the root filesystem on the virtual machine. In some cases, there may be an additional partition that is used for the /boot filesystem.

Citrix Xen virtual systems also use whole-disk images, on which Cloudmin creates partitions. However, the underlying storage is managed entirely by the Citrix Xen API, so you never need to select a filename or LVM volume group for a new disk.

Expanding a Virtual Disk

The most common operation to perform on a disk image is expanding it when the filesystem is full. The steps to do this are :

1. Login to Cloudmin, and select the system from the left menu.
2. If the system is running, shut it down. A virtual system's filesystem cannot be modified while it is running, unless it is a non-root filesystem that is not currently in use.
3. Go to Resources -> Manage Disks .
4. Click on the appropriate disk, which is typically mapped to SCSI device A partition 1 for the root filesystem.
5. Increase the Disk file size , then click Save.
6. After the resize is complete, start the system up again if needed.

This process is identical for disk images stored in regular files or logical volumes. In both cases, the size increase will fail if the underlying host filesystem or volume group does not have enough free space.

This same procedure can be used to shrink a disk, assuming that the filesystem on is not using more space than the new disk size. However, Citrix Xen does not support the shrinking of disk images.

For KVM and Citrix Xen whole-disk images, expansion of a disk is only possible if there is a single partition or if the final partition contains the filesystem being expanded.

Unsafe Disk Resizes

Cloudmin attempts to work out what filesystem is on a virtual disk by looking at the /etc/fstab file on the virtual system. It then uses this information to properly expand the filesystem.

However, if the filesystem type cannot be worked out then Cloudmin will warn you about possible data loss before resizing a disk. After expanding a disk you will need to login to the virtual system and possibly expand partitions and filesystems on the disk, or create a new partition in the empty space. Disks used for RAID, LVM or by un-supported operating systems like Windows or BSD cannot have their filesystems expanded by Cloudmin.

Scheduled Disk Expansion

Because expanding the size of a disk typically requires a virtual system be shut down, you may want to schedule this for a time when the system is not being heavily used, like 3 AM. This can be done as follows :

1. Login to Cloudmin, and select the system from the left menu.
2. Go to Resources -> Manage Disks .
3. Click on the appropriate disk, which is typically mapped to SCSI device A partition 1 for the root filesystem.
4. In the Scheduled disk resize section, enter a new size and select a time for it to take effect - the default is 3 AM tomorrow morning.
5. Click the Add Scheduled Change button.

When the selected time arrives, the system will be shut down if needed, the selected disk resized, and then the system started up again. Only one scheduled change can be created at a time for each disk on each system. Once created, a change can be cancelled before it takes effect on the same page.

Creating a Virtual Disk

You might want to add a disk to a system for use as virtual memory, or to move some files onto. The steps to do this are :

1. Login to Cloudmin, and select the system from the left menu. It does not have to be shut down.
2. Go to Resources -> Manage Disks , and click on Create a new virtual disk.
3. In general, the disk file and device fields will be automatically filled in with reasonable defaults. All you need to enter is the New disk file size.
4. To have Cloudmin create a filesystem on the disk, select it from the Filesystem to create menu. You can also choose to mount it somewhere on the virtual system by entering a path in the Mount new disk as field.
5. Click the Create button.

A reboot of the virtual system will be needed before the new disk is available.

Deleting Virtual Disks

If a virtual system no longer needs a disk, you can remove it as follows. All data on the disk will be lost though! Removal of the disk for the system's root filesystem is not possible.

1. Login to Cloudmin, and select the system from the left menu.
2. If the system is running, either shut it down or kill any processes on the system using the disk.
3. Go to Resources -> Manage Disks , and click on the disk.
4. Click the Delete button.

OpenVZ Disk Limits

OpenVZ virtual systems can limit disk usage in a different way - instead of using fixed-size virtual disks, each system can have an optional limit on the amount of disk space its filesystem can consume. This can be set on the Create New System page in the Resource limit options section, or modified later on the Resource Limits page.

Virtual Disks and System Owners

Account plans can be used to define a total disk limit for system owners, which applies to the sum of all disks on all systems belonging to the owner. For example, if an owner has a limit of 10GB of disk he could create a virtual system with two 3GB disks, and other with 1 2GB disk.

For OpenVZ systems, the disk space limit is counted towards the owner's total disk space. If an owner has a disk limit, he will not be allowed to create an OpenVZ system without a limit.

Managing Virtual Domains

Once you have systems registered with Cloudmin that run Virtualmin, you can use the Cloudmin interface to create, find and manage domains on those systems. In a company with many real and virtual systems, this makes domain management much easier than logging into every one of your Virtualmin hosts individually to find a domain.

Creating Domains

IP Address Allocation

Finding Domains

Deleting and Disabling Domains

Moving Domains

Configuring Default Features

Multiple Interfaces for Xen

Why Use Multiple Interfaces?

On a simple Xen host system there is only one network interface (such as eth0), typically connected to the Internet. All Xen systems have their own virtual eth0 interface which is bridged to the host system via Xen's xenbr0 interface.

However, you may want to configure host systems with two interfaces, one connected to the Internet and one on a private network for transfers between host or virtual systems. This involves adding an additional bridge (usually xenbr0) to the Xen configuration on the host, and configuring Cloudmin to create new Xen systems with a second interface this is connected to the bridge.

Configuring Xen on the Host System

This configuration must be done manually, as Cloudmin does not yet support managing the xend configuration file on a host. The steps to follow are :

1. SSH into the host system as root, and create the file /etc/xen/scripts/multiple-bridge with the following contents :

   #!/bin/sh
   dir=$(dirname "$0")
   "$dir/network-bridge" "$@" vifnum=0 netdev=eth0 bridge=xenbr0
   "$dir/network-bridge" "$@" vifnum=1 netdev=eth1 bridge=xenbr1

2. Make the file executable with the command chmod +x /etc/xen/scripts/multiple-bridge
3. Edit the file /etc/xen/xend-config.sxp and find the line like (network-script network-bridge) line, and change it to (network-script multiple-bridge)
4. Restart Xen with the command /etc/init.d/xend restart
5. Verify that the xenbr1 bridge has been created with the ifconfig -a command.

If you have multiple host systems, these steps must be performed on each of them.

Configuring Cloudmin

Once the additional bridge is active on the Xen host, you can configure Cloudmin to use it as follows :

1. Go to Host Systems -> Xen Host Systems, and click on the host.
2. In the Bridges on host system for Xen interfaces field, select both xenbr0 and xenbr1.
3. In the IP address allocation range table, add a row with a range of IPs to use on your internal network, such as 192.168.1.1 to 192.168.1.254, with CIDR set to 24. Select your new xenbr1 bridge in the For interface column.
4. Click the Save button.

How you can create a new Xen virtual system, and it should be configured with two network interfaces, with eth1 connected to eth1 on the host system, and an IP assigned from the 192.168.1 range.

Registering Host Systems

Before a system can be used to host Xen instances, Solaris Zones or Linux VServers, Cloudmin must be informed that is will be used for this purpose, and must verify that needed software and kernel support is installed. The steps to do this are similar for the various virtualization types, but they all start with the registration of the host system itself, documented on the Using Cloudmin page.

Setting up DNS

Registering a Xen Host

Registering a VServer Host

Registering a Solaris Zones Host

Remote API

Cloudmin Remote HTTP API

The Remote API

Reading Output

JSON and XML Output

wget --http-user=root --http-passwd=smeg 'https://yourserver:10000/server-manager/remote.cgi?program=list-systems'

Replicating Virtual Domains

Introduction to Domain Replication

If you use Cloudmin to manage one or more systems running Virtualmin, you can have it replication domains and global Virtualmin settings (like plans and templates) from a source system to multiple destinations. This can be useful for :

• Distributing common settings like plans, styles and custom scripts to multiple Virtualmin systems to avoid having to create them manually.
• Creating a hot-spare system that gets a copy of one or more domains on a regular basis, so that it can serve if the primary system goes goes.
• Replicating websites for load-balancing purposes, so that multiple machines can serve the content for a single website.

Domain replication is most useful when the systems share home directories via NFS and possibly connect to a remote MySQL database, so that dynamic content is always up to date. In this case, Cloudmin should be configured to not replicate home directory and database content.

To limit replication to just some Virtualmin features, open the Advanced replication settings section when adding or editing and select them from the Virtualmin features to replicate field. For example, you may want to select everything except home directory content and MySQL databases if they are stored on a separate system used by both the source and destinations.

Setting Up Domain Replication

To configure Cloudmin to replicate one or more virtual servers from a source system to one or more destinations, follow these steps :

1. On the left menu, go to Virtualmin Settings -> Virtual Server Replication.
2. Click on Add a new replication configuration.
3. Choose the machine to copy from in the Source system menu.
4. Select the machines to copy to in the Destination systems field, by using the right-arrow button to move them to the right-hand list.
5. Select the virtual servers to copy from the Virtualmin domains to replicate. Only those on the source system can be selected.
6. Assuming you want replication to happen automatically on schedule, change the Replication enabled? field to Yes.
7. Select a schedule in the When to replicate field.
8. Enter an email address to notify about failures in the Send email on failure to field.
9. Click the Create button.

One replication has been setup, you can change what gets copied and to where by clicking on an entry in the Virtual Server Replication list. Replication configurations can also be deleted and started manually on the same page.

Setting Up Global Configuration Replication

To instead copy global settings like plans between systems running Virtualmin, follow these steps :

1. On the left menu, go to Virtualmin Settings -> Virtual Server Replication.
2. Click on Add a new replication configuration.
3. Choose the machine to copy from in the Source system menu.
4. Select the machines to copy to in the Destination systems field, by using the right-arrow button to move them to the right-hand list.
5. Open the Advanced replication settings section, and check the boxes for the global settings you want copied.
6. Assuming you want replication to happen automatically on schedule, change the Replication enabled? field to Yes.
7. Select a schedule in the When to replicate field.
8. Enter an email address to notify about failures in the Send email on failure to field.
9. Click the Create button.

Replication

Cloudmin replication allows you to setup one or more additional systems as backup replicas, which can take over management of all your other systems if the primary master fails. It is only available in Cloudmin 4.0 or later, and each replica must also be running Cloudmin 4.0 or above.

What Gets Replicated

When replication is enabled, Cloudmin will copy the following to all replicas :

1. The details of all managed systems, such as their hostnames, IPs, current status and login information.
2. Global settings like plans, bandwidth monitoring, alerts, backup schedules, Virtualmin replication configurations and module configuration.
3. System owner accounts and all associated statistics.
4. Any system images stored on the Cloudmin master.

Replication is done by default every 5 minutes, just after the status of all managed systems is collected. It is always done in the background, so any delay sending changes to replicas does not effect the Cloudmin user interface.

Replication does not include the status of the Cloudmin master system itself, as it makes no sense to replicate this to backup masters which will be collecting their own status. It also does not include any system images that are not stored on the master.

If the Cloudmin master is also acting as a host for virtual systems, they will not be included in replication - except for their status.

Setting Up a Replica

The process for setting up a new Cloudmin replica is :

1. Choose a system to be the backup replica, and install Cloudmin 4.0 or later on it. Either an empty system or one running Virtualmin can be used.
2. Login to Cloudmin on the replica, and go to Cloudmin Settings -> Cloudmin Replication.
3. Select the Replica of another system option, and click Save.

From this point on, the system will be switched to a read-only replica state, and will wait for replication connections from the master you setup in the next section. You can still use Cloudmin on the replica to view the details of all managed systems and global settings, but will not be able to change anything.

Setting Up the Master

To configure a system to copy settings to one or more Cloudmin replicas, the steps to follow are :

1. Make sure the replicas are already on the list of managed systems - if not, add them first.
2. Login to Cloudmin, and go to Cloudmin Settings -> Cloudmin Replication.
3. Select Replicate configuration to, and choose the replica systems from the list to the right.
4. Click Save.

After saving, all replicas will be checked to ensure that they are reachable and are setup as replicas. An initial replication of all settings will then be done - this may take several minutes or more if the current master has a large number of system images stored locally, as they will need to be sent to all replicas.

Dealing With Master Failure

If your original Cloudmin master system fails and you have a single replica, it can be switched to become the new master as follows :

1. Login to Cloudmin, and go to Cloudmin Settings -> Cloudmin Replication.
2. Select Stand-alone Cloudmin system, and click Save.

The system should now be a fully usable Cloudmin replica, with all global settings and system state from the last replication sync from the old master.

If you had multiple replicas to start with, in the case of master failure the steps are :

1. Pick one replicate to be the new master, and login to Cloudmin on it.
2. Go to Cloudmin Settings -> Cloudmin Replication.
3. Select Replicate configuration to, and make sure only the other replicas are selected. Then click Save.

Running Windows under Xen

This documentation was contributed by Scott Grayban ( sgrayban @ gmail.com ). They are specific to Debian, and may need modification for other Linux distributions :

1. Pre-Requisites for Installing a Windows Xen Guest

   A XEN kernel must be installed and running at boot time.

   Make sure you have HVM/VMX enabled in the bios - if you don't have this you can't run windows

   In console type xm dmesg | grep VMX

   You should see...

   (XEN) HVM: VMX enabled

   If you don't you will need to restart the server and get into the BIOS and look for an option related to virtualization support.

   If your BIOS does not have this you can not run any HVM guests, that means you can not run any version of Windows.

2. Turn off VNC for all xen linux guests and restart them.

3. Run vi /etc/xen/scripts/qemu-ifup and enter :

   #!/bin/sh
    
   echo -c 'config qemu network with xen bridge for '
   echo $*
    
   ifconfig $1 0.0.0.0 up
   brctl addif eth0(your bridge) $1
    

4. Change to the xen directory for the rest of the steps with cd /xen/

   Create blank 80GB disk image with : dd if=/dev/zero of=xenwin.img bs=1024k seek=81920 count=0

   apt-get install libcdio-utils

   Get cd/dvd info and make sure its the right one cd-info /dev/(s|h)da

   Create the WindowsXP ISO dd if=/dev/(s|h)da of=Windows.iso

5. Run vi xenwin.cfg and enter :

   kernel = "/usr/lib/xen-default/boot/hvmloader"
   builder = 'hvm'
   vif = [ 'type=ioemu,bridge=eth0,ip=assigned-ip,mac=22:61:34:00:00:01' ] MAC address has to start with 22:61:34 or 00:16:3e
   address = 'assigned-ip'
   netmask = '255.255.255.XXX'
   memory = 1024
   shadow_memory = 8
   name = "xenhvm" # domain prefix name
   cdrom = 'file:/xen/Windows.iso' # name of iso image you created above
   disk = [ 'file:/xen/xenwin.img,hdc,w', 'file:/xen/Windows.iso,hdb:cdrom,r' ]
   device_model = '/usr/lib/xen-default/bin/qemu-dm'
    
   # boot on floppy (a), hard disk (c) or CD-ROM (d)
   # default: hard disk, cd-rom, floppy
   #### boot must be dc to install windows after that you change it to c or cd
   boot = "dc"
   #boot = "c"
    
   vnc = 1 # use VNC to insall and setup windows after that is done you can disable this
   vncconsole = 0
   vncpasswd = 'password'
   vncviewer = 1
   vncunused = 1
   vnclisten = 'Domain-0 IP'
   vcpus = 2 # number of cpu's to assign
   stdvga = 0
   serial = 'pty'
   usbdevice = 'tablet' # Required for USB mouse
   on_reboot = 'restart'
   on_crash = 'restart'
    

6. Run the next 2 commands at the console

   xm create xenwin.cfg

   brctl show

   Make sure that the tapX interface is assign to ethX you set in bridge= vif setting

7. Type the next command at the console :

   vncviewer assigned-ip

   and continue with the windows install and setup

8. Setup your windows networking using the correct IP/mask/gateway/dns Setup remote desktop access if you need/want it

9. Turn VNC off in the xenwin.cfg file by setting vnc = 0

   This step has to be done because XEN/qemu-dm will force the port to be 5900 and it will interfere with the other xen linux vnc guests.

10. Re-enable vnc for the xen linux guests if you turned them off in Step 2 and restart the guests.

11. Import the windows instance into Cloudmin at Add System -> Add Xen instance

12. You're done.

    You should be able to access the windows server via RDP(remote desktop) as Administrator and start/stop/reboot and manage the windows guest as a normal windows server.

    That means you can run the updates or install any windows apps that you might need.

    Note - The default passwords for Administrator and new user is temp1234 if you are using the paid version of my WindowsXP img file that is fully functional and ready to use.

    YOU MUST HAVE already bought WindowsXP and have a valid license to get the XEN img file, at order time you will have to electronically sign that agreement. Cloudmin might offer a free Windows ISO at some point.

    For information above pricing of Xen Windows images, see http://www.borgnet.net/clients/knowledgebase/13/Debian-Lenny-WindowsXP-H...

Setting Up Citrix Xen Virtualization

Citrix Xen (formerly from XenSource) is a commercial variant of Xen that uses the same underlying concepts and kernel as open source Xen, but a completely different set of command-line tools. Cloudmin supports Citrix Xen as a virtualization type, but treats it differently from regular Xen due to differences in the disk format used, API and capabilities.

Installing a Citrix Xen Host System

Citrix provides an ISO image for a Linux installer that can setup a new system as a Xen host, which can be downloaded from http://www.xensource.com/ . As far as I know, they do not have an installer which works on existing Linux systems, so you will need to dedicate one or more physical systems to Xen hosting.

Once a host system has been setup for Citrix Xen, you can configure Cloudmin to manage it as follows :

1. Login to Cloudmin and go to Add System -> Add physical system , and add the new Citrix Xen host. You will need to enter the SSH password you selected when the host was setup.
2. Go to Host Systems -> Citrix Xen Host Systems and click on Register a system for Citrix Xen hosting.
3. Select the host you added in step 1, and select a DNS zone to add new VMs to in the Add Citrix Xen systems to DNS domain menu.
4. Under Network options select or enter the IP ranges you want to assign to VMs on this host.
5. Click the Save button.
6. Go to Cloudmin Settings -> New System Images and download at least one Citrix Xen image.
7. You should now be able to create new virtual systems at Create System -> Create Citrix Xen VM

Adding an Existing Citrix Xen Host System

If you are already using Citrix Xen on your network, you can have Cloudmin take over management of existing VMs as follows :

1. Login to Cloudmin and go to Add System -> Add physical system , and add the existing Citrix Xen host. You will need to enter the SSH password you selected when the host was originally setup.
2. Go to Host Systems -> Citrix Xen Host Systems and click on Register a system for Citrix Xen hosting.
3. Select the host you added in step 1, and select a DNS zone to add new VMs to in the Add Citrix Xen systems to DNS domain menu.
4. Under Network options select or enter the IP ranges you want to assign to any future VMs on this host.
5. Click the Save button.
6. Go to Add System -> Add Citrix Xen VM.
7. In the Internet hostname field, enter either the IP address or a resolvable hostname for the VM being added.
8. In the SSH login mode section, enter the root password for Linux on the VM.
9. From the Citrix Xen VM menu select the name of the VM you want to import.
10. Click the Add System button.
11. Repeat steps 6 to 10 for each system you want to import.

Setting Up KVM Virtualization

KVM virtualization is included in the 2.6 Linux kernel, so all recent distributions support it without the need to install a custom kernel. However, it depends on the CPU supporting either the Intel VT or AMD-V virtualization extensions in order to run virtual systems at a reasonable speed.

On some systems, these extensions are disabled in the BIOS by default. Enabling them requires booting the system from the console, entering the BIOS menu and finding the option to turn on virtualization extensions. In some cases the system must then be fully shut down and started up again for this change to take effect.

For KVM instances to access the host system's network, you must setup a network bridge. These instructions assume that your host system has only one network interface, and it is eth0 .

Setting up a Fedora, CentOS or Redhat Host System

To setup a Redhat-based system to host KVM instances, the steps to follow are :

1. SSH in as root and install the KVM packages with the command yum install kvm qemu qemu-img parted
2. In the /etc/sysconfig/network-scripts directory, copy ifcfg-eth0 to ifcfg-br0.
3. Edit the new file and change the DEVICE line to DEVICE=br0.
4. Edit the ifcfg-eth0 file, and at the bottom add the line BRIDGE=br0
5. Apply the network settings with the command service network restart . This should be done at the console, as it will break network access to the host system if anything goes wrong.

Setting up a Debian or Ubuntu Host System

1. SSH in as root and install the KVM packages with the command apt-get install kvm qemu parted
2. Edit the /etc/network/interfaces file and change it to be like :

   auto eth0 lo br0
    
   iface lo inet loopback
    
   iface eth0 inet manual
    
   iface br0 inet static
      address 192.168.1.1
      netmask 255.255.255.0
      broadcast 192.168.1.255
      network 192.168.1.0
      gateway 192.168.1.10
      bridge_ports eth0
      bridge_fd 9
      bridge_hello 2
      bridge_maxage 12
      bridge_stp off

3. Apply the network settings with the command /etc/init.d/networking restart or by rebooting . This should be done at the console, as it will break network access to the host system if anything goes wrong.

Adding a New Host System

1. Install Webmin on the host system, if it isn't already.
2. Create a directory for storing KVM instance image files, typically /kvm . This can be located anywhere on the system though.
3. Add the host system to Cloudmin at Add System -> Add physical system, if it isn't already.
4. Go to Host Systems -> KVM Host Systems, click the Register a system for KVM hosting link and select your new host machine.
5. Enter the directory you want to use for storing KVM instances, an IP range to allocate to virtual systems, and a DNS domain to add new systems to.
6. Click the Register button.

Setting Up LVM for Xen or KVM

Why Use LVM?

Cloudmin supports storing Xen and KVM disk images in LVM logical volumes, instead of regular files. This has the speed advantage of avoiding the overhead of going through the filesystem layer on the host system, and can also make adding disk space for virtual systems easier. However, the downside is increased management complexity, as disk images in LVs cannot be easily managed with Linux tools like mv and scp.

Host System Requirements

For a Xen or KVM host system to use LVM, it must either have been installed with its filesystems on LVM already, or have free disks that can be used to create an LVM volume group. If a volume group already exists, it must have some free space for new logical volumes.

For increased reliability, we recommend running LVM on top of RAID. For example, a system with 4 disks could have them combined into a Linux software RAID 5 group, which is then used as the underlying physical volume for an LVM volume group. If this ever fills up, 4 more disks could be installed as another RAID 5 set and then added to the volume group as other physical volume.

For Cloudmin to make use of LVM on a host system, it must have Webmin installed. The simplest way to do this is to select the host from the left menu, then go to System Operations -> Install Webmin. Once Webmin is installed on the host, you can use its LVM and RAID modules under the Hardware category to setup volume group.

In the simplest case where you have two extra empty disks and want to add them to a new volume group, you could do the following in Webmin on the host system :

1. Go to Hardware -> Partitions on Local Disks, and click on the first new disk.
2. If any partitions exist already, delete then. Then create a new primary partition that spans the whole disk with the Type menu set to Linux LVM.
3. Do the same for the second and any other disks.
4. Go to Hardware -> Logical Volume Management.
5. If a volume group already exists, click the Physical volumes tab, then click Add a physical volume and add the disk you setup above. Then do the same for any other disks.
6. If no volume groups exist yet, click the Add a new volume group link. Enter a name like "xenvg" and select the first of your new disks, then click Create. Once the creation is done, add any other disk to the volume group.

Host System Configuration

Once a volume group has been created, you can configure Cloudmin to use it as follows :

1. Login to the Cloudmin master system, and go to Host Systems -> Xen Host Systems (or KVM Host Systems) , and click on the host you just setup LVM on.
2. From the LVM volume group for disk images menu, select the new volume group, then click Save.
3. Create a test Xen or KVM system on this host, and make sure it works properly. Once it is done, go to Resources -> Manage Disks, and you should see the first virtual disk stored in a logical volume.

Setting Up Linux Open Source Xen Virtualization

Cloudmin GPL

CentOS 5

Redhat Enterprise 5

Setting Up Linux OpenVZ Virtualization

Installing the OpenVZ Kernel

The simplest Linux distribution to setup OpenVZ hosting support for is CentOS, as a kernel and packages are supplied by the OpenVZ developers at http://wiki.openvz.org/Main_Page . The steps to install the kernel are on a CentOS 5 system are :

1. Setup the OpenVZ YUM repository with the commands :

   cd /etc/yum.repos.d
   wget "http://download.openvz.org/openvz.repo"
   rpm --import "http://download.openvz.org/RPM-GPG-Key-OpenVZ"

2. Install the kernel with the command yum install ovzkernel . Or if you want a kernel that can host both Xen and OpenVZ, use yum install ovzkernel-xen .
3. Edit /boot/grub/menu.lst and make sure the default= line refers to the new OpenVZ-capable kernel section - typically this will need to be set to default=0
4. Edit /etc/sysctl.conf and append the following lines :

   # On Hardware Node we generally need
   # packet forwarding enabled and proxy arp disabled
   net.ipv4.ip_forward = 1
   net.ipv6.conf.default.forwarding = 1
   net.ipv6.conf.all.forwarding = 1
   net.ipv4.conf.default.proxy_arp = 0
    
   # Enables source route verification
   net.ipv4.conf.all.rp_filter = 1
    
   # Enables the magic-sysrq key
   kernel.sysrq = 1
    
   # We do not want all our interfaces to send redirects
   net.ipv4.conf.default.send_redirects = 1
   net.ipv4.conf.all.send_redirects = 0

5. Edit /etc/sysconfig/selinux and change the SELINUX= line to SELINUX=disabled
6. Reboot the system, and verify that it boots into the new kernel.

Installing OpenVZ Utilities

Once you have the kernel on the host system, other needed utilities can be installed as follows :

1. Install the OpenVZ tools with : yum install vzctl vzquota
2. Start the OpenVZ daemon with : /etc/init.d/vz start
3. Run the command vzlist -a to verify that the tools are working and kernel support is usable.

Once this is done, you can add this system as an OpenVZ host in Cloudmin at Host Systems -> OpenVZ Host Systems .

Setting Up Linux VServer Virtualization

Kernel Installation

Mandriva Install

urpmi kernel-vserver-latest kernel-vserver-source-latest util-vserver util-vserver-build util-vserver-core util-vserver-sysv util-vserver-lib

Binding Ports to Primary IP Address

Setting Up Solaris/OpenSolaris Zones Virtualization

System Monitoring and Alerts

Introduction to Alerts

A Cloudmin system alert monitors one or more managed systems, and checks if variables such as free memory, CPU load or free disk space are above or below some threshold. If so, it can send email to the master administrator, system owners or other addresses.

Alerts can be used to detect overloaded systems, lack of resources, or system crashes. They can be limited to a sub-set of the hosts managed by Cloudmin, either selected explicitly or by group membership, virtualization type or owner. This allows alert thresholds to be tailored based on the systems be monitored.

Alerts can be found under the System Monitoring category on the left menu, on the System Alerts page. They are only available in Cloudmin versions 3.7 and later though.

Creating a New Alert

Before you create a new alert, you need to decide which system variable(s) it is going to monitor, what thresholds it will trigger at, and for how long it must be exceeded. For example, you might want to check if CPU load exceeds 1.0 for 30 minutes, or free memory is under 64M for 1 hour.

To create an alert, follow these steps :

1. Open the System Monitoring category on the left menu, and click on System Alerts .
2. Click the Add a new system alert link to bring up the alert creation page.
3. In the Systems to monitor for this alert section, choose the hosts that you want to monitor. They can be chosen by hostname, group, owner or type, or you can select to monitoring all systems. 1 The Exclude down or un-managable systems box can be checked to ignore systems that have been intentionally shut down. This should not be used if you are creating an alert to actually fire when a system is down though.
4. In the Conditions to trigger alert section, you can enter one or more rules that will be checked when this alert is evaluation. Each rule has the following columns :
   • Variable - The data point collected from each system that the rule will compare
   • Comparison - Set this to Over to have the rule trigger if the variable is over some limit (ie. CPU load), or Under to trigger if below (ie. Memory free).
   • Value - The threshold at which the rule will match. You can use suffixes like MB and GB for rules matching memory or disk space.
   • Time period - How long the variable must be over or under the threshold value for this rule to trigger. Don't enter anything less than the Cloudmin status collection interval of 5 minutes, or the rule will never match.
   • Minimum systems - The number of hosts on which this rule must match for the alert to fire.
5. By default all conditions must be true for the alert to trigger. However, you can select Trigger alert when any condition is true to change this.
6. In the Alert notifications, select who will receive email notifications when the alert fires. The default is to only email the Cloudmin master administrator, whose address is set on the Email Settings page.
7. To limit the rate at which email is sent if the alert continues to fire, fill in the Interval between messages field.
8. Click the Create button.

Once the alert is created, it will appear in the list of alerts, with its current status shown in the right-hand column.

When creating an alert rule that matches if a system is down (using the System up variable), the comparison should be set to Under and the value to 1. Cloudmin uses the value 0 to indicate a system is completely down, 0.5 when it is up by not contactable via SSH, and 1 for a fully operational host.

Managing Alerts

To edit an alert, just click on it in the System Alerts page. All the same settings that you entered when creating it originally can be modified.

To remove one or more alerts, check the boxes next to them on the System Alerts page, and click the Delete Selected Alerts button.

When any rule on any alert matches at least one system, it will be displayed in the Firing alerts section of the System Alerts page - even if not enough systems or rules match to cause the alert to email. You can view the history of the variable that caused it to fire by clicking the Graph link in the right-most column.

Silencing Alerts

To stop an alert from sending email without actually deleting it, check the box next to it on the System Alerts page, and click the Silence Alerts button. Similarly, to remove the silence use the Un-Silence Alerts button. This can be useful when you are creating or debugging a new alert and don't want it sending out spurious email notifications.

System Owners

Introduction To System Owners

A system owner in Cloudmin is an additional account who is granted limited access to some virtual systems. They are typically created for customers of a VPS hosting business, and given permission to manage only their own systems. Owner accounts can also be granted the right to expand, delete and move virtual systems, up to limits defined by a plan.

Cloudmin also supports the creation of new virtual systems by owners, if enabled on their plans. You can define an upper limit on the number of systems each owner can create, and any additional disk, RAM or CPU use will count towards plan limits. A VPS hosting company can then create an owner account for each customer and leave the actual creation and deletion of systems up to the owners.

Creating and Managing Owner Accounts

To create a new system owner account, do the following :

1. First create or edit a plan that contains the limits you want applied to this owner, as documented on the Account Plans page.
2. Go to Cloudmin Settings -> System Owners , and click Add a new system owner.
3. Fill in the Login username field with a unique username, like "joe".
4. Fill in the Login password field.
5. Enter the customer's email address in the Contact email address field.
6. To allow the new owner to manage some existing systems, select them the Systems that can be managed list.
7. Under Limits and restrictions, select the account plan the defines the limits for this owner.
8. Click the Create button.

Once an owner has been created, he will appear in the list on the System Owners page. Click on his name to edit him, or check the box next to his username and click Delete Selected Owners to remove him.

Owner accounts can also be temporarily disabled or enabled on the same page, such as for non-payment. To disable, check the boxes next to the names of accounts to turn off and click the Disable Selected Owners button. Use the Enable button to turn the accounts back on. Disabling an owner has no effect on his running virtual systems.

System Owners and Backups

Cloudmin has backup and restore capabilities to save the filesystem contents of virtual systems. System owners can also be allowed to create their own backups, either to a central storage location defined by the master administrator or remote SSH and FTP servers.

To allow owners to create their own backups, do the following :

1. Make sure that each of your host systems has a default backup location set, as documented on the backup and restore page.
2. Go to the Account Plans page and click on a plan whose owners you want to allow.
3. Fill in the Maximum space for backups field with the amount of disk space each owner should be able to consume for backups on central storage.
4. In the Plan restrictions section, check the Backup and restore systems box.
5. Click Save and Apply.

System owners will now see the backup and restore category on the left menu when they login.

When backing up to the destination defined by the host system, a sub-directory will be created for each owner to avoid over-writing of each others files. Each owner can create his own scheduled backups for his systems, and will be notified via email if they fail. Owners can also find, restore and delete old backups using the Backup Logs page.

Usage Accounting

Cloudmin keeps track of the uptime, CPU and RAM used by each virtual system over time, and can summarize it for the current accounting period (such as the current week or month). For example, if an owner had two systems with 512MB RAM and 1GB of disk each that were up for 2 and 3 days respectively over the week and used 10% CPU on average, his usage would be :

• Uptime : 2 x 24 + 3 x 24 = 125 hours
• Memory used : 2 x 24 x 512MB + 3 x 24 x 512MB = 62.5 GB hours
• CPU used : 2 x 24 x 10% + 3 x 24 x 10% = 125 percent hours
• Disk allocated : 2 x 24 x 7 = 336 GB hours

To see usage for an owner, click on his name in the System Owners list and open the Usage by all owned systems section. This is also available from the list-owners API command. How you use this information is up to you, but it could be used for usage-based billing for VPS hosting customers.

The accounting period is the same as that set for Bandwidth Monitoring, at Cloudmin Settings -> Bandwidth Monitoring.

API Access By System Owners

If the Call remote API action is allowed for a system owner or his plan, the owner will be able to call the Cloudmin API via HTTP to manage his systems. Owners will only be able to perform the same actions on the same systems via the API that they would be able to do via the web interface, so there is no additional security risk to enabling this. In Cloudmin 4.1 and later, it is turned on by default.

For more documentation on the API, see http://www.virtualmin.com/documentation/cloudmin/devel/remote

Upgrading Cloudmin Software

Upgrading via the Cloudmin UI

In a standard install of Cloudmin 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.

Upgrading from the command line

Alternately, you can install the same packages from the command line on the master system as root. On CentOS or Redhat Enterprise, the command to use will be like :

yum install wbm-server-manager

On Debian or Ubuntu, you could use :

apt-get install webmin-server-manager

Usage Accounting

What is Usage Accounting?

Cloudmin checks the state of all virtual systems every 5 minutes and collects their status (up or down), assigned RAM, CPU limit, CPU load and disk space. Each sample is recorded in an internal database, and can be used to generate usage totals over an accounting period (such as a week or month). This can then be used to charge customers based on the actual resources used by their system or systems.

The accounting period over which usage is display is the same one used for bandwidth monitoring, set at Cloudmin Settings -> Bandwidth Monitoring. The default is the current month, but it can be changed to the current day, week, or any number of days in the past. In the latter case, the period is actually a sliding window of time instead of fixed non-overlapping blocks.

Usage Accounting Examples

Imagine a virtual system that has 512MB of RAM, 1 GB of disk and a CPU limit of 50%, which has been up for 1 hour a day over the last month, and used an average of 10% CPU during that time. Cloudmin would calculate its resource usage as follows :

• System uptime : 30 hours
• Memory used : 512MB x 30 hours = 15 GB hours
• CPU allocated : 50% x 30 hours = 1500 percent hours
• CPU used : 10% x 30 hours = 300 percent hours
• Disk allocated : 1GB x 24 hours x 30 days = 720 GB hours

Note that disk use is still counted even when the system is down, as the space is still consumed on the host system. For Xen systems Cloudmin considers the disk space assigned and used to be the same, as free space on a disk image cannot be used by other systems. For OpenVZ containers it tracks the disk limit and disk usage separately.

Extracting Usage Information

The simplest place to see usage for a virtual system is on the Edit System page, in the Resource usage section. If you need to extract this for billing purposes, you can use the list-systems API call with the multiline parameter, which will include the current accounting period's usage in the output. To select a previous period, use the period-ago parameter following the a number of weeks or months in the past.

To get individual usage samples for a system, use the list-usage API command. For example, you could call this from the command line like so :

# vm2 list-usage --host xencentos.home
xencentos.home
 Start              End                Up?  Memory     CPU    Load   Disk
 17/Oct/2009 23:50  18/Oct/2009 00:40  Yes  768 MB     100%   8%     11 GB
 18/Oct/2009 00:40  18/Oct/2009 00:45  Yes  768.17 MB  100%   40%    11 GB
 18/Oct/2009 00:45  18/Oct/2009 11:00  No   -          -      -      -
 18/Oct/2009 11:00  18/Oct/2009 11:50  Yes  768 MB     100%   21%    11 GB

It takes start and end parameters to select a specific date range to display samples for. Sample are aggregated by Cloudmin where possible, so a long period of downtime or consistent CPU load will appear as a single row possibly spanning many hours.

Accounting and System Owners

Cloudmin combines the usage for all virtual systems each owner manages and computes a total usage for each owner. For example, if an owner had two systems with 512MB RAM and 1GB disk each that were up for 2 and 3 days respectively over the week and used 10% CPU on average, his usage would be :

• Uptime : 2 x 24 + 3 x 24 = 125 hours
• Memory used : 2 x 24 x 512MB + 3 x 24 x 512 = 62.5 GB hours
• CPU used : 2 x 24 x 10% + 3 x 24 x 10% = 125 percent hours
• Disk allocated : 2 x 24 x 7 = 336 GB hours

To see usage for an owner, click on his name in the System Owners list and open the Usage by all owned systems section. This is also available from the list-owners API command. How you use this information is up to you, but it could be used for usage-based billing for VPS hosting customers.

Using Cloudmin

Introduction to the User Interface

System Status

Adding Systems

Managing Systems

Connecting to a Managed System

Changing Passwords

Updating Multiple Systems

Virtualmin Licenses

Before you can use Cloudmin to create a virtual system with Virtualmin installed, you must have at least once license that can be used for Virtualmin on that system. Fortunately, Cloudmin has a built-in license management and registration tool, which makes it easy to add and use the licenses you have purchased.

Registering Licenses

Using Licenses

Xen Kernels

Xen Kernel Booting

In a default Cloudmin install, all Xen virtual systems are setup to boot from a kernel file on the host system, typically in the /xen directory and named like vmlinuz-vm2-xenU. However, you may want to use a kernel from within the virtual system instead - this allows different systems to run different kernels, and for the kernel to be upgraded from within the Xen instance.

Xen uses with PyGrub or Pv-Grub to run grub , which in turn reads the /boot/grub/menu.lst file from within the Xen system. The Grub config file contains the path the kernel and other related files, which is then booted when the system is started.

Cloudmin will configure a Xen system to use the newer Pv-Grub bootloader if available, and fall back to PyGrub otherwise. Pv-Grub is recommended as it runs entirely within the virtual system, while PyGrub runs on the host system and thus is considered less secure.

Booting a Xen System From its own Kernel

To create a new Xen virtual system that boots from its own kernel, you will first need a system image that contains a kernel and Grub configuration file. The latest CentOS and Debian images provided by Virtualmin include these - if you have already downloaded images for those distributions, make sure you have version 1.7 or later, and if not re-download them.

Once you have an image that includes a kernel, you can create a system that uses it as follows :

1. On the left menu, go to Create System -> Create Xen instance.
2. Fill in the form as you would normally, making sure to select an image that contains a kernel.
3. Under Advanced options, change the Kernel for Xen instance option to Use kernel from Xen system.
4. Click the Create System button.

If all goes well, you will see a line in the creation output like setup to boot Xen system's kernel with PyGrub .

If you are creating a system from using the API and want to use the virtual system's kernel, add the --xen-pygrub true command line flag, or xen-pygrub=true URL parameter.

Booting an In-System Kernel By Default

If you want Cloudmin to always setup virtual systems to boot from their own kernels without having to select this at creation time, do the following :

1. Go to Cloudmin Settings -> Module Config.
2. Choose Xen settings from the menu.
3. Change the Default Xen kernel source to From Xen system using PyGrub or Pv-Grub.
4. Click Save.

This will also effect systems created using the API. You can force the host kernel to be used instead with the --xen-pygrub false command line flag.

Command Line API

Explains how to use the command-line scripts included with Virtualmin to manage users, aliases, servers, databases and resellers.

Introduction

Command Categories

Creating Install Scripts

Script Installers

Script Installer Files and Directories

sub script_phpbb_desc
{
return "phpBB";
}

sub script_phpbb_uses
{
return ( "php" );
}

sub script_phpbb_longdesc
{
return "A high powered, fully scalable, and highly customizable Open Source bulletin board package.";
}

Script Installer IDs

The Lifetime of a Script

Script Installer Implementation

script_scriptname_desc

sub script_wordpress_desc
{
return "WordPress";
}

script_scriptname_uses

sub script_wordpress_uses
{
return ( "php" );
}

script_scriptname_versions

sub script_wordpress_versions
{
return ( "2.2.1" );
}

script_scriptname_category (optional)

sub script_wordpress_category
{
return "Blog";
}

script_scriptname_php_vers (PHP scripts only)

sub script_wordpress_php_vers
{
return ( 4, 5 );
}

script_scriptname_php_modules (PHP scripts only)

sub script_wordpress_php_modules
{
return ("mysql");
}

script_scriptname_pear_modules (PHP scripts only)

sub script_horde_pear_modules
{
return ("Log", "Mail", "Mail_Mime", "DB");
}

script_scriptname_perl_modules (Perl scripts only)

sub script_twiki_perl_modules
{
return ( "CGI::Session", "Net::SMTP" );
}

script_scriptname_python_modules (Python scripts only)

sub script_django_python_modules
{
return ( "setuptools", "MySQLdb" );
}

script_scriptname_depends(&domain, version)

sub script_wordpress_depends
{
local ($d, $ver) = @_;
&has_domain_databases($d, [ "mysql" ]) ||
        return "WordPress requires a MySQL database" if (!@dbs);
&require_mysql();
if (&mysql::get_mysql_version() < 4) {
        return "WordPress requires MySQL version 4 or higher";
        }
return undef;
}

script_scriptname_dbs(&domain, version)

sub script_wordpress_dbs
local ($d, $ver) = @_;
return ("mysql");
}

script_scriptname_params(&domain, version, &upgrade)

sub script_wordpress_params
{
local ($d, $ver, $upgrade) = @_;
local $rv;
local $hdir = &public_html_dir($d, 1);
if ($upgrade) {
        # Options are fixed when upgrading
        local ($dbtype, $dbname) = split(/_/, $upgrade->{'opts'}->{'db'}, 2);
        $rv .= &ui_table_row("Database for WordPress tables", $dbname);
        local $dir = $upgrade->{'opts'}->{'dir'};
        $dir =~ s/^$d->{'home'}\///;
        $rv .= &ui_table_row("Install directory", $dir);
        }
else {
        # Show editable install options
        local @dbs = &domain_databases($d, [ "mysql" ]);
        $rv .= &ui_table_row("Database for WordPress tables",
                     &ui_database_select("db", undef, \@dbs, $d, "wordpress"));
        $rv .= &ui_table_row("Install sub-directory under <tt>$hdir</tt>",
                             &ui_opt_textbox("dir", "wordpress", 30,
                                             "At top level"));
        }
return $rv;
}

script_scriptname_parse(&domain, version, &in, &upgrade)

sub script_wordpress_parse
{
local ($d, $ver, $in, $upgrade) = @_;
if ($upgrade) {
        # Options are always the same
        return $upgrade->{'opts'};
        }
else {
        local $hdir = &public_html_dir($d, 0);
        $in{'dir_def'} || $in{'dir'} =~ /\S/ && $in{'dir'} !~ /\.\./ ||
                return "Missing or invalid installation directory";
        local $dir = $in{'dir_def'} ? $hdir : "$hdir/$in{'dir'}";
        local ($newdb) = ($in->{'db'} =~ s/^\*//);
        return { 'db' => $in->{'db'},
                 'newdb' => $newdb,
                 'multi' => $in->{'multi'},
                 'dir' => $dir,
                 'path' => $in{'dir_def'} ? "/" : "/$in{'dir'}", };
        }
}

script_scriptname_check(&domain, version, &opts, &upgrade)

sub script_wordpress_check
{
local ($d, $ver, $opts, $upgrade) = @_;
$opts->{'dir'} =~ /^\// || return "Missing or invalid install directory";
$opts->{'db'} || return "Missing database";
if (-r "$opts->{'dir'}/wp-login.php") {
        return "WordPress appears to be already installed in the selected directory";
        }
local ($dbtype, $dbname) = split(/_/, $opts->{'db'}, 2);
local $clash = &find_database_table($dbtype, $dbname, "wp_.*");
$clash && return "WordPress appears to be already using the selected database (table $clash)";
return undef;
}

script_scriptname_files(&domain, version, &opts, &upgrade)

sub script_wordpress_files
{
local ($d, $ver, $opts, $upgrade) = @_;
local @files = ( { 'name' => "source",
           'file' => "latest.tar.gz",
           'url' => "http://wordpress.org/latest.zip",
           'nocache' => 1 } );
return @files;
}

script_scriptname_commands

sub script_wordpress_commands
{
return ("unzip");
}

script_scriptname_install(&domain, version, &opts, &files, &upgrade, username, password)

sub script_wordpress_install
{
local ($d, $version, $opts, $files, $upgrade) = @_;
local ($out, $ex);
if ($opts->{'newdb'} && !$upgrade) {
        local $err = &create_script_database($d, $opts->{'db'});
        return (0, "Database creation failed : $err") if ($err);
        }
local ($dbtype, $dbname) = split(/_/, $opts->{'db'}, 2);
local $dbuser = $dbtype eq "mysql" ? &mysql_user($d) : &postgres_user($d);
local $dbpass = $dbtype eq "mysql" ? &mysql_pass($d) : &postgres_pass($d, 1);
local $dbphptype = $dbtype eq "mysql" ? "mysql" : "psql";
local $dbhost = &get_database_host($dbtype);
local $dberr = &check_script_db_connection($dbtype, $dbname, $dbuser, $dbpass);
return (0, "Database connection failed : $dberr") if ($dberr);

# Create target dir
if (!-d $opts->{'dir'}) {
        $out = &run_as_domain_user($d, "mkdir -p ".quotemeta($opts->{'dir'}));
        -d $opts->{'dir'} ||
                return (0, "Failed to create directory : <tt>$out</tt>.");
        }

# Extract tar file to temp dir
local $temp = &transname();
mkdir($temp, 0755);
chown($d->{'uid'}, $d->{'gid'}, $temp);
$out = &run_as_domain_user($d, "cd ".quotemeta($temp).
                               " && unzip $files->{'source'}");
local $verdir = "wordpress";
-r "$temp/$verdir/wp-login.php" ||
        return (0, "Failed to extract source : <tt>$out</tt>.");

# Move html dir to target
$out = &run_as_domain_user($d, "cp -rp ".quotemeta($temp)."/$verdir/* ".
                               quotemeta($opts->{'dir'}));
local $cfileorig = "$opts->{'dir'}/wp-config-sample.php";
local $cfile = "$opts->{'dir'}/wp-config.php";
-r $cfileorig || return (0, "Failed to copy source : <tt>$out</tt>.");

# Copy and update the config file
if (!-r $cfile) {
        &run_as_domain_user($d, "cp ".quotemeta($cfileorig)." ".
                                      quotemeta($cfile));
        local $lref = &read_file_lines($cfile);
        local $l;
        foreach $l (@$lref) {
                if ($l =~ /^define\('DB_NAME',/) {
                        $l = "define('DB_NAME', '$dbname');";
                        }
                if ($l =~ /^define\('DB_USER',/) {
                        $l = "define('DB_USER', '$dbuser');";
                        }
                if ($l =~ /^define\('DB_HOST',/) {
                        $l = "define('DB_HOST', '$dbhost');";
                        }
                if ($l =~ /^define\('DB_PASSWORD',/) {
                        $l = "define('DB_PASSWORD', '$dbpass');";
                        }
                if ($opts->{'multi'}) {
                        if ($l =~ /^define\('VHOST',/) {
                                $l = "define('VHOST', '');";
                                }
                        if ($l =~ /^\$base\s*=/) {
                                $l = "\$base = '$opts->{'path'}/';";
                                }
                        }
                }
        &flush_file_lines($cfile);
        }

if (!$upgrade) {
        # Run the SQL setup script
        if ($dbtype eq "mysql") {
                local $sqlfile = "$opts->{'dir'}/tables-mysql.sql";
                &require_mysql();
                ($ex, $out) = &mysql::execute_sql_file($dbname, $sqlfile, $dbuser, $dbpass);
                $ex && return (0, "Failed to run database setup script : <tt>$out</tt>.");
                }

local $url = &script_path_url($d, $opts).
             ($upgrade ? "wp-admin/upgrade.php" : "wp-admin/install.php");
local $userurl = &script_path_url($d, $opts);
local $rp = $opts->{'dir'};
$rp =~ s/^$d->{'home'}\///;
return (1, "WordPress installation complete. It can be accessed at <a href='$url'>$url</a>.", "Under $rp using $dbphptype database $dbname", $userurl);
}

script_scriptname_uninstall(&domain, version, &opts)

sub script_wordpress_uninstall
{
local ($d, $version, $opts) = @_;

# Remove the contents of the target directory
local $derr = &delete_script_install_directory($d, $opts);
return (0, $derr) if ($derr);

# Remove all wp_ tables from the database
local ($dbtype, $dbname) = split(/_/, $opts->{'db'}, 2);
if ($dbtype eq "mysql") {
        # Delete from MySQL
        &require_mysql();
        foreach $t (&mysql::list_tables($dbname)) {
                if ($t =~ /^wp_/) {
                        &mysql::execute_sql_logged($dbname,
                                "drop table ".&mysql::quotestr($t));
                        }
                }
        }
else {
        # Delete from PostgreSQL
        &require_postgres();
        foreach $t (&postgresql::list_tables($dbname)) {
                if ($t =~ /^wp_/) {
                        &postgresql::execute_sql_logged($dbname,
                                "drop table $t");
                        }
                }
        }

# Take out the DB
if ($opts->{'newdb'}) {
        &delete_script_database($d, $opts->{'db'});
        }

return (1, "WordPress directory and tables deleted.");
}

script_scriptname_passmode(&domain, version)

sub script_wordpress_passmode
{
return 1;
}

Other Installation Methods

HTTP Requests

# Make config.php writable
&make_file_php_writable($d, $cfile);

# Trigger the installation PHP script
local @params = (
        [ "lang", "english" ],
        [ "dbms", $dbtype eq "mysql" ? "mysql4" : "postgres" ],
        [ "upgrade", 0 ],
        [ "dbhost", $dbhost ],
        [ "dbname", $dbname ],
        [ "dbuser", $dbuser ],
        [ "dbpasswd", $dbpass ],
        [ "prefix", "phpbb_" ],
        [ "board_email", $d->{'emailto'} ],
        [ "server_name", "www.".$d->{'dom'} ],
        [ "server_port", $d->{'web_port'} ],
        [ "script_path", $opts->{'path'}."/" ],
        [ "admin_name", $d->{'user'} ],
        [ "admin_pass1", $d->{'pass'} ],
        [ "admin_pass2", $d->{'pass'} ],
        [ "install_step", 1 ],
        [ "current_lang", "english" ],
        );
local $params = join("&", map { $_->[0]."=".&urlize($_->[1]) } @params);
local $ipage = $opts->{'path'}."/install/install.php";

# Make an HTTP post to the installer page
local ($iout, $ierror);

&post_http_connection("www.$d->{'dom'}", $d->{'web_port'},
                      $ipage, $params, \$iout, \$ierror);
if ($ierror) {
        return (0, "phpBB post-install configuration failed : $ierror");
        }
elsif ($iout !~ /Finish Installation/i) {
        return (0, "phpBB post-install configuration failed");
        }

Ruby On Rails Installation

sub script_typo_install
{
local ($d, $version, $opts, $files, $upgrade) = @_;
local ($out, $ex);

# Check for the gem command (here instead of earlier, as it may have been
# automatically installed).
&has_command("gem") || return (0, "The Ruby gem command is not installed");

# Create target dir
if (!-d $opts->{'dir'}) {
        $out = &run_as_domain_user($d, "mkdir -p ".quotemeta($opts->{'dir'}));
        -d $opts->{'dir'} ||
                return (0, "Failed to create directory : <tt>$out</tt>.");
        }

# Install mongrel first
local $err = &install_ruby_gem("mongrel");
if ($err) {
        return (0, "Mongrel GEM install failed : <pre>$err</pre>");
        }

# Install typo itself
local $err = &install_ruby_gem("typo");
if ($err) {
        return (0, "Typo GEM install failed : <pre>$err</pre>");
        }
if (!&has_command("typo")) {
        return (0, "Install appear to succeed, but the <tt>typo</tt> command ".
                   "could not be found");
        }

$out = &run_as_domain_user($d, "cd ".quotemeta($opts->{'dir'})." && ".
                               "typo install .");
if ($?) {
        return (0, "Typo setup failed : <pre>$out</pre>");
        }

$out = &run_as_domain_user($d, "cd ".quotemeta($opts->{'dir'})." && ".
                               "typo start .");
if ($?) {
        return (0, "Failed to start Typo server : <pre>$out</pre>");
        }

&setup_mongrel_proxy($d, $opts->{'path'}, $opts->{'port'},
                     $opts->{'path'} eq '/' ? undef : $opts->{'path'});

if (!$upgrade) {
        # Configure server to start at boot
        local $typo = &has_command("typo");
        local $startcmd = "cd ".quotemeta($opts->{'dir'})."; ".
                          "$typo start . 2>&1 </dev/null";
        local $stopcmd = "kill `cat ".quotemeta($pidfile)."`";
        &setup_mongrel_startup($d, $startcmd, $stopcmd, $opts,
                               1, "typo-".$opts->{'port'}, "Typo Blog Engine");
        }

Ruby On Rails Un-Installation

sub script_typo_uninstall
{
local ($d, $version, $opts) = @_;

# Shut down the server process
local $pidfile = "$opts->{'dir'}/tmp/pid.txt";
local $pid = &check_pid_file($pidfile);
if ($pid) {
        kill('KILL', $pid);
        }

# Remove bootup script

&delete_mongrel_startup($d, $opts, "typo start .");

# Remove the contents of the target directory
local $derr = &delete_script_install_directory($d, $opts);
return (0, $derr) if ($derr);

# Remove proxy Apache config entry for /typo
&delete_mongrel_proxy($d, $opts->{'path'});
&register_post_action(\&restart_apache);

return (1, "Typo directory deleted.");
}

sub script_typo_stop
{
local ($d, $sinfo) = @_;
local $pidfile = "$sinfo->{'opts'}->{'dir'}/tmp/pid.txt";
local $pid = &check_pid_file($pidfile);
if ($pid) {
        kill('KILL', $pid);
        }
&delete_mongrel_startup($d, $sinfo->{'opts'}, "typo start .");
}

Creating New Content Styles

• Creating New Content Styles
• Directory Structure
• Packaging