Download Webmin 1.441

Webmin Documentation

Tip of the Day

Other Sites

Module CGI Programs

The Webmin web server treats files with the extension .cgi as CGI programs, just like most other web servers. All the forms, menus and other pages in your module will be generated by CGI programs, so knowledge of the basic concepts of CGI programming and HTML is necessary for writing a module.

All CGI programs are run with root privileges, which is generally necessary for them to be able to edit configuration files. In some cases your code may drop those privileges by switching to another user, for example if the module's access control settings for some Webmin user specify it.

Assuming your module is being written in Perl, you should begin by writing a Perl script that contains functions used by the CGI programs in your module. This script is usually called something like lib.pl or foobar-lib.pl. A minimal example of such a script might look like :

# foobar-lib.pl
# Common functions used for managing the foobar user list

do '../web-lib.pl';      (1)
&init_config();          (2)

# list_users()           (3)
# Returns a list of all foobar users
sub list_users
{
...
}

The 3 important features of the example above are :

1. do '../web-lib.pl';
   The file web-lib.pl in the Webmin root directory contains a large number of functions that are useful for developing Webmin modules. All CGI programs should indirectly or directly require this module.

2. &init_config();
   This function (defined in web-lib.pl) initializes the following global variables :
   
   • %config
     Contains the current configuration for this module. This typically is used to store user editable options and operating system specific information. Module config files are described in more detail below.

   • %gconfig
     Contains the global Webmin configuration. See below for more details.

   • $module_name
     The name of this module, which is just the name of the directory the module is in.

   • $module_config_directory
     The directory in which this module's config file is stored. If your module creates permanent files or programs for some reason (such as print driver scripts), they should be created in or under this directory.

   • $tb
     The background colour for table headers.

   • $cb
     The background colour for table bodies.

   • $scriptname
     The name of the CGI program currently being run, relative to the directory it is in (such as save_foo.cgi).

   • $remote_user
     The username that the current user logged into Webmin with.

   • $base_remote_user
     The username whose permissions are currently in effect. Most of the time this will be the same as $remote_user, but if you have the 'Configure Unix user authentication' option setup in the Webmin Users module, this will be set to the name of the user whose permissions are used.

   • $current_theme
     The name of theme in effect for the current user.

   • $root_directory
     The root directory of the Webmin install, such as /usr/libexec/webmin.

   • $module_root_directory
     The root directory of the current module, such as /usr/libexec/webmin/modulename.

   • %module_info
     Information about the current module, from its module.info file.

3. The list_users function
   This is an example of a function that might be used by various CGI programs in this module. Some module library files may also include another file containing functions specific to the current operating system or configuration. See the proc-lib.pl in the proc module as an example.

A CGI program called list.cgi in a module might look something like :

#!/usr/bin/perl                        (1)
# list.cgi
# Display the list of foobar users

require './foobar-lib.pl';             (2)
&header($text{'list_title'}, "");      (3)
print "<hr>\n";

print "<table border>\n";              (4)
print "<tr $tb>\n";
print "<td><b>$text{'list_user'}</b></td>\n";
print "<td><b>$text{'list_real'}</b></td>\n";
print "</tr>\n";

@users = &list_users();                (5)

foreach $u (@users) {                  (6)
        print "<tr $cb>\n":
        print "<td><a href='edit.cgi?user=",
              &urlize($u->{'user'}),"'>$u->{'user'}</a></td>\n";
        print "<td>$u->{'real'}</td>\n";
        print "</tr>\n";
	}

print "</table>\n";                    (7)
print "<hr>\n";
&footer("", $text{'index_return'});    (8)

The important lines in the example above are :

1. All CGI programs must start with a #! line containing the path to the Perl interpreter on your system. This should be the same as the path that Webmin itself uses, found in the /etc/webmin/perl-path file.

2. CGI programs should include the module's library with a line like this, so that init_config is called and functions defined in the library are available.

3. Any CGI that is going to produce HTML output should called the header function to produce a page title. In this case, the actual title is coming from a file in the lang/ directory which has been read into %text. Traditionally a horizontal line is output directly after the header as well, as in this example.
   Only programs that are going to later call redirect should not call header, or produce any HTML with print statements.

4. These five lines output the HTML for the header of the table that the CGI is going to generate.

5. This line is a call to the list_users function defined in foobar-lib.pl, which presumable returns an array of users.

6. This loop outputs the table rows, each of which contains a link to another CGI program in the module. Note the use of the urlize function to convert the username into a form suitable for a URL parameter.

7. These lines produce the HTML for the end of the table and the traditional final horizontal line.

8. Every CGI program that calls header must call footer as well, which generates the HTML needed to properly finish the page.

The corresponding parts of the lang/en file for this CGI program might look like :

list_title=Foobar User List
list_user=Username
list_real=Real name

All modules that use internationalization must include a lang/en file, and can also include other files in lang/ for other languages.