Table of Contents
The Webmin virtual servers module provides a means to create, modify, and delete user mailboxes and virtual server user accounts. With its domain management features you can quickly and easily create a new website with domain records, Apache VirtualHost configuration, a home directory, a user account to manage it, mail server configuration, disk usage quotas and email addresses and aliases, database creation, and per-domain Webalizer configuration. It is a two-tiered system (with a third tier being provided by Usermin), providing both an administrative panel for creation and deletion of accounts, and a domain owner panel for the management of email accounts and aliases, Apache configuration, BIND records, and more, within each individual domain.
Installation of the module itself is straight-forward. If you have never installed Webmin before, you will want to refer to the Book of Webmin for full documentation. After Webmin installation, browse to the Webmin:Webmin Configuration:Webmin Modules module. There you can install the module.
Apache must be configured for Virtual Hosting, and must be capable of using suexec to execute user CGI programs. The first can be accomplished from within Webmin by browsing to the Apache:Networking and Addresses module, and entering either a local address or selecting the Include all addresses option. Then click Save. This will add a line like the following to the http.conf file:
NameVirtualHost 192.168.1.248
A line like this can instead be added manually, using your favorite text editor.
![[Note]](images/note.png) | Note |
|---|---|
If you would like for virtual hosts to operate on all active addresses, you may instead choose an address of *. | |
Next, Apache needs to be able to run CGI scripts on behalf of users using a suexec mechanism. In version 1.3, no changes are needed. In 2.0, you'll need to load mod_suexec, using a line like the following:
LoadModule suexec_module modules/mod_suexec.so
However, things may get a bit trickier, because we plan to put the web root for each new virtual domain user into the /home directory. The SuExec module requires the base directory to be specified at build time for security reasons...if you compile from source, you've probably already thought of this. If you use RPMs, you'll need to rebuild from the SRPM with the suexec docroot altered to point to /home. For example, my SPEC file has the following in the configure section:
--with-suexec-docroot=/home \
Postfix on most systems is very nearly ready for use as the mail server for the Virtual Servers module. The only thing missing is the configuration for a virtual mapping database and, if using quotas, moving the spool directory to the same partition that user data lives on. The first can be added easily using Webmin. Browse to Postfix:Virtual Domains. Enter a type of database, and a filename for the virtual map database into the Domain mapping lookup tables field. Generally, this will be something along the lines of hash:/etc/postfix/virtual. In this example the type is a dbm hash, and the filename is virtual in the /etc/postfix directory. Save and apply your change.
Next, you'll need to move your mail spool to the /home partition. Browse to the Postfix:Local Delivery module. Edit the Spool directory option and enter /home/mail. Save and Apply your changes.
| Note |
|---|---|
It is useful to choose mail as the subdirectory here, because there will already exist a mail user on most systems and so there is no way to accidentally create a new user that would end up getting your mail spool as their home directory! If you don't use Red Hat Linux, you should probably first check to be sure there is a user named mail on your system (I believe most UNIX systems do have a user of this name). | |
In order for POP or IMAP to work, those servers will need to know how to find the mail spool. The easiest thing to do for this is probably to create a symbolic link from /var/spool/mail to /home/mail. The command to do this:
# ln -s /home/mail /var/spool/mail
BIND requires no explicit configuration for the Virtual Servers module, but it must be up and running, and configured for use with Webmin. In most cases, you can simply install BIND, and the browse to the Webmin BIND module page. Webmin will offer to setup BIND for you, and offer a few choices for how to begin. I recommend you have Webmin download the list of root name servers. After Webmin has setup BIND for you, start BIND. That's all for BIND.
Quotas on Linux are tricky, not because they are difficult to setup, but because they are so poorly documented, and what documentation exists is more often than not incorrect to the point of not working. If you are using a relatively recent Linux version, the following instructions should work without difficulty.
Virtualmin uses standard system disk quotas to limit user disk usage. Because of this, all user data must reside on the same disk partition so that the system can maintain an accurate accounting of disk use. The /home partition is an excellent choice for the user data directory, due to UNIX tradition and user expectations. This is why we moved the mail spool to a directory on the /home partition in the mail server sections, so that all mail will reside on the same partition.
The first step to enabling quotas is to turn them on in the /etc/fstab configuration file. You can do this in Webmin by browsing to the System:Disk and Network Filesystems module. Then click on the /home partition link. Finally, locate the Use Quotas? option and select User and Group from the dropdown list. Save your changes.
You can also make this change manually, by editing the /etc/fstab in your favorite editor, and modifying the /home mount point entry to look something like this:
/dev/hda2 /home ext3 defaults,usrquota,grpquota 1 1
The important bit of the above example is the addition of the usrquota and grpquota directives. These two items enable both user and group quotas.
After adding quota support to your fstab, you'll need to remount the filesystem, or reboot the system, to make the changes take effect.
Linux filesystem quotas store the disk usage data in files in the root of the filesystem being managed. The files are named quota.user and quota.group. These files must be manually created before quotas can be enabled for the first time. So use touch to create each file:
# touch /home/quota.user # touch /home/quota.group
The final step in enabling quotas is to run the quotacheck utility to add initial usage values to the quota files. To do this, simply run the following command:
# quotacheck -vug /home
This will scan the filesystem, and add values to your quota files. The first time it is run, it will complain with errors about truncated quota files. This is expected and harmless.
To test to be sure your quotas are actually enabled, you can use the repquota utility to see what the current quota usage looks like. It should looke something like this:
bash-2.05a# repquota /home
*** Report for user quotas on device /dev/ubd/2
Block grace time: 7days; Inode grace time: 7days
Block limits File limits
User used soft hard grace used soft hard grace
----------------------------------------------------------------------
root -- 18 0 0 142 0 0
apache -- 1 0 0 1 0 0
user -- 6 0 0 7 0 0
guest -- 6 0 0 7 0 0
| Note |
|---|---|
PostgreSQL is not yet supported, but will be in the next revision. | |
MySQL and/or PostgreSQL just needs to be up and running for Virtualmin to make use of it. There is no complicated configuration required. First, you need to make sure the necessary tools are installed. On a Red Hat system, you can run the following command for MySQL:
bash-2.05a# rpm -qa | grep mysql mysql-server-3.23.56-1.73 mysql-3.23.56-1.73
If you get the results above, or similar, then you have the required packages installed. For PostgreSQL:
bash-2.05a# rpm -qa | grep postgre postgresql-libs-7.3.2-3 postgresql-server-7.3.2-3 postgresql-7.3.2-3
As above, if you have those packages, you can setup PostgreSQL and have it to work with Virtualmin.
To set them up for Virtualmin control, now all you have to do is start them. Browse to the Servers:MySQL Database Server module, and/or the Servers:PostgreSQL Database Server module, and click the start button.
In Figure 1 the main Virtual Servers module page is shown. The page header provides links to the Webmin Index (if available to your user), and the Webmin configuration for this module, as well as the title of the module. The middle portion of the page lists any existing virtual servers that have been created with the Virtual Servers module. This lists the domain name, the Unix user that owns the account, the real name of the owner or administrative contact of the domain, whether a website is enabled, whether DNS service is configured, the number of email addresses and aliases that exist for this domain, and information about the disk space usage quotas. The bottom portion of the page provides information about the status of the various servers that provide service for these accounts, and buttons to start or stop them.
To create a new user mailbox, click the Add a new local mail user link in the local mailboxes section of the page. This will open a new page where you can enter the username (this will be the users mail address, without an @ or a domain name). In the next field enter the users full name. Enter a password in the Password field. Finally, select a disk space quota for the user, if the quota will be different than the default. Finally, click the Create button to save the new account.
To create a new virtual server, click the Add a new virtual server link to open the Create Virtual Server page Figure 2. Here you fill in the domain name of the new account in the Domain name field. The domain name should be the parent domain under which all other domains will live, for example, if I wanted to set up www.swelltech.com for a website and swelltech.com for receiving mail at joe@swelltech.com I would enter simply swelltech.com. The corresponding www.swelltech.com and mail.swelltech.com will be created for you, as will an MX record to direct mail for the domain swelltech.com to mail.swelltech.com.
After a domain has been created, it can have any number of mailboxes that are specific to that domain. These mailboxes will be given unique user names constructed from the domain name of the virtual server, and the username specified. This allows the same address to exist within multiple domains, for example joe@swelltech.com and joe@penguinfeet.org.
To add a mailbox to a virtual server, click the List link beside the domain for which you would like to add a new mailbox. From this point, you will use the same steps discussed in the section called “Adding a new user mailbox”. The options are the same. The only difference is in how the user will access their account from a POP3 or IMAP mail client.
A mailbox within a virtual domain will behave the same as a local mailbox, but users will append their domain name to their username when configuring POP3 or IMAP mail clients, like Outlook or Netscape Mail. For example, a new user named joe within a domain named swelltech.com will have a POP3 login name of joe.swelltech.com when configuring an email client.
| Note |
|---|---|
When logging into the Usermin webmail interface, users are not required to include their domain in the login name. The system will automatically append the correct information to the login name, if they are browsing to the appropriate domain name. If the user logs into Usermin using the default domain (i.e., not a virtual domain), and their mailbox is within a virtual domain, they will have to include the full username, including domain. | |
To delete a local mailbox or a virtual domain mailbox, you must first select the mailbox to be deleted. For local mailboxes, simply click the name of the user that you would like to delete in the Local mailboxes section. For virtual domain mailboxes, you must click the List link for mailboxes for the domain. Then, click the user to be deleted.
The user details page will appear. In the lower right corner of the page is a Delete button. Click the button, and confirm the removal.
![[Caution]](images/caution.png) | Caution |
|---|---|
Removing the user will remove the user account, the Usermin configuration details, the home directory and any web content within it, as well as the users mail spool. An account deletion cannot be reversed. If an account may ever be active again, the account should be disabled rather than deleted. | |
The behavior of the Virtual Servers module can be configured by clicking on the Module Config link in the upper left-hand corner of the page. Usually, this information will only need to be entered once, though it may be useful to change some default values to account for system upgrades or new requirements.
This page is divided into four sections. The first is devoted to server settings, including which types of services will be configured, the mail server to configure, etc.
- Mailbox and alias configuration enabled?
Virtualmin can also configure local email addresses and aliases, if this option is enabled. Local mailboxes create normal local users, or local aliases.
- Apache setup and configuration enabled?
If enabled, Virtualmin will setup virtual hosts in the Apache httpd.conf file.
- BIND setup and configuration enabled?
If enabled, Virtualmin will create a set of domain name records for the new virtual host. It will automatically create a host record for www and mail, as well as the domain name itself. It also creates an MX record.
- MySQL/PostgreSQL setup and configuration enabled?
If enabled, Virtualmin will provide options to setup database users and permissions for new domain users.
- Webalizer report generation enabled?
If enabled, and Webalizer is installed, Virtualmin will setup automatic Webalizer report generation for each new domain.
- Mail server to configure
The module supports both Postfix and Sendmail mail servers for mail services. Because these two mail servers have a few differences in the way they are usually configured to provide virtual domain mailboxes, it is useful for Webmin to know which mail server you are using. Once usage of the module has begun, this option should not be changed, without first manually migrating the configuration from the old server type to the new server type.
- Quota setup for domain and mail users?
If enabled, and your system supports quotas on the /home and/or mail spool partitions, this option will setup the hard and soft quota limits for each new domain user and mailbox user on the system, based on the defaults specified below or from administrator input values at user creation time.
- Network interface for virtual addresses
New IP-based virtual domains will be configured to listen on the network interface specified here, and new virtual IP addresses will be added to this interface.
- Default virtual server IP address
The Virtual Servers module will, if possible, choose for virtual hosts to listen on all IPs. If there is not an appropriate VirtualHost directive to permit this, Webmin will use the IP address specified here. The default is the address of the network interface specified in the Network interface for virtual addresses option above.
- Maximum number of domains to display
If there are a large number of domains, the domain list may become difficult to manage. Virtualmin can be configured to list domains only if the total number of domains is smaller than the specified value. A search box will be displayed instead, which can be used to search for domains.
- Shell for mailbox users
This option specifies the default shell of new local and virtual domain mailbox users. If the users should be able to login using SSH, ftp, telnet, etc. specify /bin/sh. If no shell access is required, specify /bin/false. Note that for users that will have websites, shell access is mandatory.
- Shell for domain users
New virtual domain users, i.e. the domain owner account, will default to the shell specified here. Since domain users generally have websites, this should usually be /bin/sh.
- Include domain name in usernames?
This option specifies how new usernames will be created for virtual domain mail users. If Always is selected, the domain name will always be appended to the end of the username. For example, the username joe in the domain penguinfeet.org would have a user name of joe.penguinfeet.org, or joe.penguinfeet, depending on the value of the below Automatic Unix username style. If Only to avoid a clash is selected, then the domain name will only be appended to the username if a user already exists with the name given in another domain or in the local domain.
- Format for usernames that include domain
This option configures how the group and usernames are generated for virtual domains. If Full domain name is selected, the fully qualified domain name will be appended to domain mailbox users (as needed to satisfy the requirements of the previous option). To return to the previous example, the user joe@penguinfeet.org would have a username of joe.penguinfeet.org. If First part of domain is selected, the name will exclude the top level domain. For example, joe@penguinfeet.org would have a username of joe.penguinfeet.
- Primary group for local users
New users will be added to the user group specified here. By default this is the users group. It is rarely necessary to change this.
- Default quota for new server Unix users
When creating a new virtual server, a new user is created, that is the master user for the domain. The account can receive mail, and will own the website for the domain. The quota specified here will be the default for the domain master user. Thus, this quota will restrict the size of the website and mail directed to the domain owner mailbox. This limit does not directly impact the quotas for users within this domain (though disk usage by this user will apply to the server quota, just like other users within the domain). If multiple values are specified, they will be provided in a dropdown list. Other values may be chosen by the administrator when creating users.
- Default quota for new mailboxes
A new mailbox user, whether local or within a domain, will have a default quota specified by this option. This quota is a limit imposed on an individual users mailbox and private homepage. Multiple values may be specified, in a whitespace separated list.
- Default quota for new servers
Virtual servers also have a disk usage quota imposed on them. This value specifies the default for newly created virtual servers. This quota is a group quota, that applies to the combined usage of all of the users within a virtual domain for both websites and mailboxes. Thus, if the basic service level of a virtual host includes 5 mailboxes, then the server quota should probably be five times the quota for the individual users so that all of them can use their full quota. Multiple values may be specified, in a whitespace separated list.
- Initial files directory for virtual server users
When a new virtual server domain is created, Virtualmin can be configured to copy the files within a directory into the newly created home directory of the virtual server. This is akin to the /etc/skel directory used on most UNIX systems to preconfigure a normal system user home directory. This directory can be used to setup a default homepage, default cgi-bin scripts, etc.
- Initial files dircetory for local users
New local users will have a home directory generated from the contents of this directory. Normally, this is /etc/skel, but it can be altered if you need to treat users created here separately from those created by your local useradd command or by the Webmin Users and Groups module.
- Initial files directory for mail users
As in the above two options, this is a directory which can contain any files you'd like every new mail user to have in their generated home directory.
- Apache directives for new websites
This option allows you to specify exactly what options will be enabled on a newly generated virtual server in the VirtualHost section of the httpd.conf file. For example, you may wish to disable server-side includes, or add other cgi-bin directories with the ScriptAlias option. Be careful what options you enable here, as it is possible to create security issues with some Apache options.
- Add SuExec directives for new websites?
If your Apache has SuExec capabilities and the binary has been built to use them on your domain home directory, Virtualmin can enabled SuExec features, which allows CGI scripts within each users domain to be executed with only the permissions of the owner of the domain. This is an important security consideration if you allow users to install arbitrary CGI scripts. Think carefully about the consequences before disabling this option. There are a number of special variables which are interpretted by Virtualmin when writing to the file. They are identified beside the field.
- MX record servers for non-mail domains
When you create a new domain without local email support, Virtualmin can create an MX record to point to some other mailserver. This can be useful if you use a different server for web and mail.
- From: address for email sent when a domain is created, Template file for email to new domain owners, Template file for email to new mailboxes
An email can be sent to new domain and mailbox user accounts on creation, which can be used to inform the user of important information about the account. Nice templates are provided for you in the /etc/webmin/virtual-server/domain-template and /etc/webmin/virtual-server/user-template files, which you can modify to suit your needs. The templates interpret a few special variables, which make it easy to construct a custom message for each new user, including username, home directory, hostnames, etc. The available variables are:
- ${DOM}
Domain name.
- ${HOSTNAME}
Host name of the server.
- ${IP}
The IP address of the virtual interface for the domain, if it is an IP-based domain.
- ${USER}
The login name of the user. In the case of a domain creation, it will be the administrators username. For mailbox creations, it will be the POP3 login name for the user.
- ${MAILBOX}
This variable contains the mail name for a mailbox user. If, for example a new user were created in the penguinfeet.org domain, with a username of joe, the ${USER} variable might contain joe.penguinfeet.org or joe.penguinfeet, while the ${MAILBOX} variable would contain simply joe.
- ${PASS} or ${PLAINPASS}
This variable contains the password of the user being created. The ${PASS} variable is used for mailbox users and the ${PLAINPASS} variable for domain administrators.
- Command to run before making changes to a domain, Command to run after making changes to a domain
If you have some other actions that you would like to be performed before or after the creation of a new domain, you may enter a command or a script name here. This can be used, for example, to add users to a RADIUS system, add a domain to a monitoring schedule, add specific configuration for your virus scanner, perform some accounting function, or add a user or domain to an appserver not under the control of Webmin.
The final section allows you to select which Webmin modules will be available to newly created domain owners. The modules that are enabled will be pre-configured with ACLs to limit access to those appropriate for the new user.