Git is a source-code control system that allows multiple developers to work on the same project. Each developer has a copy of the repository on his workstation, and can check in changes to that repository and synchronize it with a central server. Other developers can then fetch those changes by synchronizing their local repository with the central one.
This documentation assumes that you already have a basic understanding of Git and source code control systems. Rather than explaining how Git works, it focuses on setting up repositories using Virtualmin.
Before you can use Git with Virtualmin, you must first enable the plugin at System Settings -> Features and Plugins. Just check the box next to Git repositories , then click the Save button. If this plugin does not appear, you may need to first install it. On a Redhat, Fedora or CentOS system, this is easiest done with the following commands, run as root :
On CentOS or RHEL, the install command is :
yum install wbm-virtualmin-git
on Debian or Ubuntu, the command is :
apt-get install webmin-virtualmin-git
If activating the plugin fails due to Git not being installed on your Virtualmin system, you will need to install it first. On Redhat, Fedora or CentOS the commands for this are :
rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarc... yum install git gitweb rm -f /etc/httpd/conf.d/git.conf apachectl graceful
while on Debian or Ubuntu, the command is :
apt-get install git gitweb
If neither of those work, you can install the plugin from a Webmin module package as follows :
Once the plugin is installed, you can enable it in Virtualmin as follows :
Once the plugin is installed, you can allow a virtual server to create Git repositories as follows :
This will perform the setup needed for repositories to be accessed under the /git URL path on this domain, but will not yet create any Git repositories.
Once a domain has Git enabled, you can add a repository to it like so :
myproject into the Repository name field.My cool program into the Repository description field.Once this is done your new repository will appear in the list on the Git Repositories page. It can then be accessed using the Git client with a URL like http://yourdomain.com/git/myproject.git . For more information on exactly which commands to use, click the Repository Commands button.
All Git repositories created using Virtualmin allow write access only to authenticated users. Accounts can be created in the same way that you would create mailbox or FTP users, and existing users can be granted access to Git repositories.
When creating or editing a user, the Other user permissions section of the Edit Mailbox page will have a field named Git login enabled?. Just select Yes, and in the Read/write access to repositories field select one or more repos to grant full access to. As soon as the user is saved or created his login and password will be able to checkin to and checkout from the selected repositories.
When logging in you only need to use the user's short username, which is the part to the left of the @ in his email address. For example, if the address was bob@webmin.com he would be able to login to Git as just bob , even though his IMAP and FTP is bob-webmin.
Once a repository has been created you can manage it using buttons on the Git Repositories page. These are :
SSL is an encryption protocol that protects data sent to and from websites from snooping or modification when they are accessed using https URLs. In addition, it allows browsers to be sure they are connecting to the correct web server, and not one setup by an attacker that is intercepting network traffic.
A critical component of the SSL protocol is the certificate, which web servers present to browsers to prove their ownership of a domain name. They are typically issued by Certificate Authorities (CAs), following the submission of a certificate request and validation of the submitter's ownership of a domain. Thanks to the magic of public-key cryptography, browsers can check that the certificate presented by a web server was actually signed by one of the CAs that it knows about.
If you want to setup an SSL website that will be visited by customers or users, obtaining a valid certificate is important. Although Virtualmin will allow you to use a self-signed certificate that costs nothing and can be generated immediately, users accessing your website will see a warning message in their browsers. And they will have no real assurance that they are accessing your webserver, rather than that of an attacker.
However, a certificate signed by a CA costs time and money to obtain. You can find out how much by looking at the websites of some major CAs : http://www.google.com/search?hl=en&q=ssl+certificate+authority
Enabling SSL For a Virtual Server
An SSL website can be enabled for a virtual server either when it is first created, or later using the Edit Virtual Server page.
In most cases, each SSL website needs to have its own IP address that is not shared with any other domain using SSL. This is due to the nature of the SSL protocol, which conflicts with name-based web virtual hosting. There are some exceptions though, as documented below.
Every Virtualmin system has at least one default shared IP address, and so can host at least one SSL website. However, to host more than one you will need to activate another IP on your system. For a typical system at a colo/hosting facility you will have several addresses available.
When creating a virtual server with SSL enabled, specify the new IP address as follows :
This is not necessary when creating your first SSL website though, as it can use the default shared IP address.
To actually have an SSL website created for a new virtual server, you need to check the Setup SSL website too? box under Enabled features. Fill in all the other details of your new virtual server, then click Create Server to begin the process. However, if Virtualmin detects any errors (such as another SSL website using the same IP), an error message will be displayed.
As part of the SSL setup process, a self-signed certificate will be generated for your domain. When you access https://example.com/ in your browser, a warning about the self-signed cert will be displayed - but once you get past that, the website contents should appear as normal.
Unless your SSL website is for use on an internal or personal network only, getting a real SSL certificate is a good idea. This is a two step process, most of which can be performed within Virtualmin.
A Certificate Signing Request or CSR contains information about your company and domain name for verification by a CA. To create one using Virtualmin, do the following :
This will create both a CSR and an SSL private key, and display them in Virtualmin. The CSR is just a block of text starting with —--BEGIN CERTIFICATE REQUEST—--, and must be send to the CA of your choice using whatever means they require.
Do NOT generate a new CSR after this point, as this will over-write your private key. The key and certificate must match for them to be used by Apache!
After the CA verifies your request, you will receive back from them a signed certificate. This just a file starting with —--BEGIN CERTIFICATE—--. followed by several lines of base-64 encoded data. To use the new certificate, do the following :
Now try accessing your website at https://example.com/ in a browser, and make sure that its SSL certificate is recognized as valid.
In Virtualmin version 3.64 and later, more than one SSL website can share the same IP address. This can be very useful if IP addresses are hard to get - however, most of the same SSL protocol restrictions still apply.
Older Virtualmin releases would display an error message when trying to enable SSL for a virtual server on the same IP as an existing website. New versions instead check if the certificate for the existing site can also cover the new domain, and if so allow the SSL setup to process. If not, a warning message is displayed indicating that SSL certificate errors may occur - but you can click past it if desired.
When Virtualmin detects that multiple virtual servers are sharing the same certificate, the Manage SSL Certificate page will only be available for the first server. And any changes such as the creation of a new certificate will be applied to all domains that share it.
A wildcard cert is one that matches any sub-domain under some top-level domain, like *.example.com . Browsers will not complain if this certificate is used for www.example.com , office.example.com and so on. This means that all those virtual server websites can share the same IP address.
Using wildcard certificates in Virtualmin is simple - all you need to do is enter *.example.com as the Server name when generating the CSR. Once the certificate has been installed, you will be able to create sub-domain virtual servers on the same IP address with no warnings.
Unified Communications Certificates (UCC) are like regular certs, but contain more than one domain name that they are considered valid for. This allows the same certificate to be used for several websites on the same IP address, such as example.com , example.net and example.org . Internally, these additional domain names are stored in the certificate's subjectAltName field.
Requesting a UCC certificate in Virtualmin is easy - just enter all the extra domain names in the Alternate hostnames field when creating a CSR. Make sure your registrar knows about and can handle UCC requests though, as they are relatively new.
Once a UCC certificate is installed, you can create SSL virtual servers for the additional domain names on the same IP address as the primary domain name. Virtualmin will detect this, and will not display any warnings.
One catch with UCC certificates is that not all web browsers recognize the additional domain names. For example, the wget command will complain about a certificate mismatch.
Subversion (also known as SVN) is a source-code control system that allows multiple developers to work on the same project. Each developer has a copy of some or all of the source code of the project on his workstation, and can check in changes to that repository which are then uploaded to a central server. Other developers can then fetch those changes by synchronizing their files with the repository.
This documentation assumes that you already have a basic understanding of SVN and source code control systems. Rather than explaining how SVN works, it focuses on setting up repositories using Virtualmin.
Before you can use SVN with Virtualmin, you must first enable the plugin at System Settings -> Features and Plugins. Just check the box next to Subversion repositories , then click the Save button. If this plugin does not appear, you may need to first install it. On a Redhat, Fedora or CentOS system, this is easiest done with the following command, run as root :
yum install wbm-virtualmin-svn
on Debian or Ubuntu, the command is :
apt-get install webmin-virtualmin-svn
If activating the plugin fails due to SVN not being installed on your Virtualmin system, you will need to install it first. On Redhat, Fedora or CentOS the command for this is :
yum install subversion
while on Debian or Ubuntu, the command is :
apt-get install subversion
Once the plugin is installed, you can allow a virtual server to create SVN repositories as follows :
This will perform the setup needed for repositories to be accessed under the /svn URL path on this domain, but will not yet create any SVN repositories.
Once a domain has SVN enabled, you can add a repository to it like so :
myproject into the Repository name field.Once this is done your new repository will appear in the list on the Subversion Repositories page. It can then be accessed using any SVN client with a URL like http://yourdomain.com/svn/myproject .
All SVN repositories created using Virtualmin allow write access only to authenticated users. Accounts can be created in the same way that you would create mailbox or FTP users, and existing users can be granted access to SVN repositories.
When creating or editing a user, the Other user permissions section of the Edit Mailbox page will have a field named Subversion login enabled?. Just select Yes, and in the Read/write access to repositories field select one or more repos to grant full access to. As soon as the user is saved or created his login and password will be able to checkin to and checkout from the selected repositories.
When logging in you only need to use the user's short username, which is the part to the left of the @ in his email address. For example, if the address was bob@webmin.com he would be able to login to SVN as just bob , even though his IMAP and FTP is bob-webmin.
Users can also be given permissions to read from selected repositories, using the Read-only access to repositories field on the Edit Mailbox page.
Once a repository has been created you can manage it using buttons on the Subversion Repositories page. These are :
Nginx is a lightweight webserver that supports most of the functionality of Apache, but is faster and uses less memory. It is suited to websites that have a large amount of static content, or virtual machines with limited memory. For more information, see http://wiki.nginx.org/Main
Switching a system from the Apache webserver (installed by default by Virtualmin to Nginx should only be done if no virtual servers with websites have been created yet. Ideally the change should be done on a freshly installed system, running RHEL 6.0, CentOS 6.0 or Debian 6.0 or later. Virtualmin version 3.89 or above is also required.
The steps to remove Apache and install Nginx are :
/etc/init.d/httpd stop ; service httpd off (on RHEL or CentOS), or /etc/init.d/apache2 stop ; update-rc.d apache2 remove (on Debian).yum install nginx (on RHEL or CentOS) or apt-get install nginx (on Debian)./etc/init.d/nginx startyum install wbm-virtualmin-nginx wbm-virtualmin-nginx-ssl (on RHEL or CentOS) or apt-get install webmin-virtualmin-nginx webmin-virtualmin-nginx-ssl (on Debian).Once this is done, you can configure Virtualmin to use it as follows :
Once Nginx support has been configured, you should be able to create virtual servers just as you would with Apache. However, on the Create Virtual Server page you will need to select Enable Nginx website? in the Enabled features section, instead of Enable Apache.
When creating a domain from the command-line API, you will need to use the --virtualmin-nginx flag instead of --ssl . For SSL websites, you will need to use --virtualmin-nginx-ssl instead of --ssl .
Similarly, when creating a domain via the remote API, you will need to use the virtualmin-nginx= parameter instead of web= .
Nginx as configured by Virtualmin lacks some features of Apache, such as :
Only one virtual server can have SSL enabled per IP address, even if a wildcard or UCC certificate would potentially allow multiple SSL sites to share the same IP.
Nginx does not support CGI, so any applications or Virtualmin scripts that use CGI will not work. Virtualmin should prevent the installation of scripts that require CGI, mod_perl or Apache-specific features.
PHP can only be executed via FastCGI, and all PHP scripts run with domain owner permissions. Execution via CGI or mod_php is not supported. For PHP to work, Virtualmin will setup a PHP FastCGI server process that Nginx communicates with for each virtual server.
Only one PHP version is supported, and Virtualmin will pick the highest version available on the system. This typically means that PHP v4 scripts cannot be run.
Virtualmin supports a few of methods of "previewing" a site before the DNS stuff is pointing to the right place.
A quick way to do this is to log into Virtualmin, and click Services -> Preview Website. When you click that, Virtualmin will retrieve the website, and you will be able to navigate it from within the control panel GUI.
Another method, and the way we'd recommend, is to setup an alias so that your customer could access their site using http://username.mydomain.tld. You can do that by going into System Settings -> Server Templates -> Default Template -> Virtual Server Creation, and adding your primary domain in "Automatically create alias domain". This makes it so that any new Virtual Server created will have not only the domain you setup, but also an alias your customer can use before the DNS is pointing to your server.
Some have asked why Virtualmin doesn't use the UserDir (http://www.mydomain.com/~username) feature they've seen used in other virtual host administrative tools. This method of access is discouraged by the Apache developers as it is potentially a security issue, particularly in shared virtual hosting environments where Virtualmin is usually used. How large a security issue is debatable and depends on the environment, but we trust the Apache folks to know their own software and what is and isn't a good default, so we don't enable it by default. Those issues are increased exponentially by allowing CGI/PHP scripts to run in this way, and we strongly discourage use of UserDir with executable applications, as it introduces serious security problems.
However, you can use this mode, if you wish.
To switch your Virtualmin server to behaving the way you're used to, you just need to turn it on in Apache. Here's how:
Browse to the Apache Webmin module.
Click on the Default virtual server (just be sure you know what your default Domain is so you can point folks to the right place).
Click on the Automatic Virtual Hosts icon.
Switch the radio button by Automatic virtual host root to the one beside the empty field, and fill in the field with, /home/%0/public_html. Note that if you've configured Virtualmin to create domains with a different path convention (e.g. "/home/a/abc") things get more complicated and you'll need to construct a path using the variables documented here:
http://httpd.apache.org/docs/1.3/mod/mod_vhost_alias.html
It's possible to use Roundcube as the default webmail program, in place of Usermin. To do that, our recommendation is to install Roundcube into one specific Virtual Server, and then update the webmail redirects so that going to webmail.domain.tld on any domain hosted on your server will redirect to your Roundcube installation.
The first step would be to choose a Virtual Server that should host Roundcube, and to install it. If you have Virtualmin Pro, you can use the Install Script to perform the installation. If you have Virtualmin GPL, you can download Roundcube from roundcube.net, and perform the installation manually using the instructions on their site.
Once Roundcube is working -- the next step is to setup the webmail redirects to point to your installation. To do that, log into Virtualmin, and browse to System Settings -> Server Templates -> Default Settings -> Apache Website. Scroll down, and look for the setting "URL for webmail redirect". You'll want to set that to the URL for which you've installed RoundCube (such as http://roundcube.your_domain.tld).
Making the above update will only change new Virtual Servers. To update existing Virtual Servers with your new webmail redirect, you would need to use the Virtualmin command line tools. First, run this command from the command line as root to disable the webmail redirect for all Virtual Servers:
virtualmin modify-web --no-webmail --all-domains
Then, you can re-enable the webmail redirect (but with the new settings) by using this command:
virtualmin modify-web --webmail --all-domains
After you complete the above, going to webmail.domain.tld for any domain hosted on your server should then take the user to your central Roundcube installation.
If you're able to log into FTP, but you receive an error like this when trying to change directories or list files:
Connection timed out Error: Failed to retrieve directory listing
That may mean you need to load the FTP connection tracking module on your server.
You can do that by running this command as root:
modprobe ip_conntrack_ftp
Website HTML content and PHP applications reside in public_html within the home directory of the virtual server. For example, the website content for virtualmin.com would reside in /home/virtualmin/public_html.
Sub-servers reside within a sub-directory of their parent virtual server home. For example, software.virtualmin.com resides in /home/virtualmin/domains/software.virtualmin.com, and thus web content would be located in /home/virtualmin/domains/software.virtualmin.com/public_html.
CGI scripts reside in the cgi-bin directory within the virtual server home directory. For example, the CGI applications for virtualmin.com would reside in /home/virtualmin/cgi-bin.
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.
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.
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.
Filezilla
A free graphical FTP client that supports FTP over SSH is Filezilla. Filezilla Home Page.
To Configure Filezilla:
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:
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.
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.
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:
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.
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.
The Webmin File Manager applet is documented in detail in the Webmin Documentation.
Problems with the web server are usually relatively easy to troubleshoot, but some common problems are tricky, because they aren't usually errors of configuration and so might not show up as reasonable errors in the error_log.
The first place to look for clues in any webserver problem is in the logs. Every virtual server or sub-server in Virtualmin has its own webserver log files. You can find them in the logs directory in the virtual servers home directory. The error_log is usually the most useful when troubleshooting, but the access_log can contain clues
If you browse to one of your virtual server domain names and see the wrong site content, there is a mismatch between the NameVirtualHost and VirtualHost sections of your Apache configuration. This can happen if you've modified the Apache configuration file manually or using other tools, or used Webmin to make changes. Other sources of trouble are misconfiguring Virtualmin to use * for the IP address (this can never work, as it will also break the DNS records, among other things).
Correcting this problem is a simple as making the IP address in the NameVirtualHost directives match the right VirtualHost directives.
There are several possible causes of this problem, and once corrected in the Apache configuration, you should also find the source of the incorrect configuration. It is likely to be found in the Virtualmin Module Configuration under the Other Server Settings category. Specifically, the following options could lead to incorrect IP addresses, or * being used in the VirtualHost sections of your Apache configuration. Incorrect settings here could also lead to invalid or incorrect DNS records being generated.
The options to check are:
Network interface for virtual addresses - This is automatically detected by Virtualmin during the configuration check, but could be detected incorrectly, if you have multiple physical interfaces, or your system is some virtualized system like a vserver or Zone or OpenVZ instance.
Default virtual server IP address - If you've manually configured this to *, for ease of moving a virtual server later, you'll need to instead set it to one of the IP addresses on your system. Moving Virtualmin virtual servers from one IP to another is easy, but getting virtual servers configured correctly with * in place of an IP can be challenging (also note that if you use *, the behavior of other virtual hosts that have explicit IPs set may become unpredictable, if extreme caution isn't used). We strongly recommend you never use * in a virtual hosting environment. But, if you do, you must configure the next option.
Default IP address for DNS records - This option is generally only needed in two circumstances: Your server is behind a NAT router or firewall, and you need the address in DNS records to be a public IP, while the Apache configuration needs to get the private IP; or, you really want to use * based VirtualHost sections in Apache. * is not a valid address for a DNS record, and so you must set an address here. As mentioned above, using * in a virtual hosting environment is not recommended.
This error is the bane of every Apache administrator's existence, as it rarely results in a useful error message in the error_log. And, to compound matters, permission problems show up in the suexec_log, which users don't have access to.
A common problem in an environment using suexec is that permissions on the executable files are too loose. There is a lot of bad advice on the web about setting permissions to 777 for testing, and then figuring out the tighter security later. If group or other users can write your scripts in a suexec environment, they will not execute. Correct permissions for scripts in a suexec equipped system are 750 or less. The script will be executed as the owner of the domain, so as long as the owner has appropriate permissions the script will be executable by the Apache suexec process.
Scripts may have errors in syntax, or be incompatible with the default version of PHP. You may be able to check the syntax from the command line by explicitly calling PHP and the script, like so:
php -l scriptname.phpIf you think it might be a version mismatch you could see if the script runs with each of the available versions (Virtualmin provides both PHP4 and PHP5 on most supported platforms).
php4 scriptname.php
And:
php5 scriptname.php
Scripts may also not have the correct permissions for the files it needs to access. A common problem is unzipping or untarring a script archive as root for use by a domain account user. This will result in files that may not be readable or writable by the domain owner, and thus unreadable or unwritable by the suexec process. Check to be sure the files are all owned by the owner of the domain using ls -l. If they aren't, you can use:
chown -R domainname:domainname scriptdirectory
The Webmin Wiki contains the following article that may be also be useful: