Webmin and Apache

WARNING : Running Webmin under Apache is almost never necessary unless you are on a very low-memory system that is already running Apache. Doing so will make Webmin slower, break some features and force use of the old ugly UI.

Webmin comes with a very simple webserver called miniserv.pl that is capable of doing all that is necessary for Webmin to run. However, it is not as fast or memory efficient as a well-developed server such as Apache. To use Apache instead of miniserv.pl, follow these steps :

  1. Create a new Apache virtual server with the document set to the directory where you installed Webmin, using a directive like DocumentRoot /usr/local/webmin.

  2. Configure Apache to treat all files with the .cgi extension as CGI programs, with the AddHandler cgi-script .cgi directive.

  3. Add index.cgi to the DirectoryIndex directive.

  4. Webmin CGI programs have their config directory passed to them in the WEBMIN_CONFIG, WEBMIN_VAR and MINISERV_CONFIG environment variables. For Apache to do this, you need to add the directives

    SetEnv WEBMIN_CONFIG /etc/webmin
    SetEnv WEBMIN_VAR /var/webmin
    SetEnv SERVER_ROOT /usr/local/webmin
    SetEnv MINISERV_CONFIG /etc/webmin/miniserv.conf

  5. Create a new <Directory> section for the root directory, like
    <Directory /usr/local/webmin>
    </Directory>

  6. Add the directive Options ExecCGI to the new <Directory> section.

  7. Password-protect the virtual server by putting directives like
    AuthName Webmin
    AuthType basic
    AuthUserFile /etc/webmin/htusers
    require valid-user
    Inside the <Directory> section. The file /etc/webmin/htusers must contains users who match up with those in /etc/webmin/webmin.acl.

  8. Make all the Webmin programs owned by root and setuid with the commands
    chown -R root:root /usr/local/webmin
    chmod -R 6755 /usr/local/webmin

  9. Add the -U flag to the perl line in all the Webmin scripts. This can be easily done with the following command run from the webmin directory
    find . -name "*.cgi" -o -name "*.pl" | perl perlpath.pl "/usr/bin/perl -U" -
    This assumes that Perl is installed as /usr/bin/perl on your system.

  10. Configure Webmin to use the 'Old Webmin Theme', as Apache cannot support Webmin's theming system.

  11. Make sure that the setuid scripts cannot be run by other users on your system, by setting the permissions on /usr/local/webmin to 700 and changing its ownership to the user your webserver runs as. Otherwise any user would be able to execute any command as root by running some of the scripts.

You should now be able to start Apache and login to Webmin at whatever URL your Apache server is running on. Note that the Webmin Users and Webmin Configuration modules will not work, as they configure miniserv.pl and cannot deal with Apache.

Some versions of Perl refuse to run in setuid mode, and fail with an error like can't do setuid. The solution is to install the special suidperl program and edit the Webmin CGI scripts to use it instead.

Apache In A Sub-Directory

In Webmin versions 0.965 and above, it is possible to run Webmin under Apache in a subdirectory rather than at the top level of a virtual server. This means that Webmin could be accessed at a URL like http://www.yourdomain.com/webmin/ . The steps to take to set this up are :

  1. Create a new Alias that maps some URL path like /webmin to the directory where Webmin is installed, such as /usr/local/webmin.

  2. Add the line webprefix=/webmin to /etc/webmin/config.

  3. Add a <Directory> section to Apache for /usr/local/webmin.

  4. In the directory section, configure Apache to treat all files with the .cgi extension as CGI programs, with the AddHandler cgi-script .cgi directive.

  5. Add the directives DirectoryIndex index.cgi and Options ExecCGI to the directory section.

  6. Webmin CGI programs have their config directory passed to them in the WEBMIN_CONFIG, WEBMIN_VAR and MINISERV_CONFIG environment variables. For Apache to do this, you need to add the directives

    SetEnv WEBMIN_CONFIG /etc/webmin
    SetEnv WEBMIN_VAR /var/webmin
    SetEnv SERVER_ROOT /usr/local/webmin
    SetEnv MINISERV_CONFIG /etc/webmin/miniserv.conf

  7. Password-protect the virtual server by putting directives like AuthName Webmin
    AuthType basic
    AuthUserFile /etc/webmin/htusers
    require valid-user
    Inside the <Directory> section. The file /etc/webmin/htusers must contains users who match up with those in /etc/webmin/webmin.acl.

  8. Make all the Webmin programs owned by root and setuid with the commands
    chown -R root:root /usr/local/webmin
    chmod -R 6755 /usr/local/webmin

  9. Add the -U flag to the perl line in all the Webmin scripts. This can be easily done with the following command run from the webmin directory
    find . -name "*.cgi" -o -name "*.pl" | perl perlpath.pl "/usr/bin/perl -U" -
    This assumes that Perl is installed as /usr/bin/perl on your system.

  10. Configure Webmin to use the 'Old Webmin Theme', as Apache cannot support Webmin's theming system.

  11. Make sure that the setuid scripts cannot be run by other users on your system, by setting the permissions on /usr/local/webmin to 700 and changing its ownership to the user your webserver runs as. Otherwise any user would be able to execute any command as root by running some of the scripts.

Webmin In A Sub-Directory Via A Proxy

If you just want Webmin to be accessible via an URL subdirectory (like /webmin) on an Apache server without going to the trouble of configuring Apache to run the CGI scripts directly, there is a simpler method that can be used. This is also useful if your system is only accessible on port 80, and you want access to both Webmin and a normal website. The steps to follow are :

  1. Make sure mod_proxy is installed on your Apache webserver.

  2. Add the following directives to the Apache configuration file:
    ProxyPass /webmin/ http://localhost:10000/
    ProxyPassReverse /webmin/ http://localhost:10000/
    <Proxy *>
    allow from all
    </Proxy>

  3. Add the lines webprefix=/webmin and webprefixnoredir=1 to /etc/webmin/config.

  4. In /etc/webmin/config, add the line referer=apachehost, where apachehost is the hostname from the URL used to access Webmin via Apache. If the referer line already has some hosts listed, add apachehost to it.

  5. Re-start Apache to apply the configuration.

All requests to /webmin on the Apache server will then be passed through to the Webmin server on localhost port 10000. All features should work fine, including themes, with the exception of IP access control (because as far as Webmin is concerned, all connections will be coming from localhost).

Webmin In A Virtual Host Via A Proxy

This method can also be used to make Webmin accessible via an Apache virtual host, like http://webmin.yourdomain.com/. The steps to follow are :

  1. Make sure mod_proxy is installed on your Apache webserver.

  2. Add a virtual host to your Apache configuration file like:
    <VirtualHost _default_>
    ServerName webmin.yourdomain.com
    ProxyPass / http://localhost:10000/
    ProxyPassReverse / http://localhost:10000/
    <Proxy *>
    allow from all
    </Proxy>
    </VirtualHost>

  3. If the virtual host uses a port other than 80 (like 9000), add a line to your Apache configuration like :
    Listen 9000

  4. In /etc/webmin/config, add the line referer=apachehost, where apachehost is the hostname from the URL used to access Webmin via Apache. If the referer line already has some hosts listed, add apachehost to it.

  5. Re-start Apache to apply the configuration.

No changes need to be made to /etc/webmin/config, because no prefix is appended to the URL path.