55.3. Module CGI Programs
The Webmin web server treats files with the.cgi extension 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';
&init_config();
# list_users()
# Returns a list of all foobar users
sub list_users
{
...
}
The three important lines in this example are:
do '../web-lib.pl';
The web-lib.pl file 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. You should use do instead of require, as the latter statement will not reread a file that has already been read in the same Perl program. This causes problems if your module is called from some other module with the foreign_require function.
This function (defined in web-lib.pl) initializes the following global variables:
%config Contains the current configuration for this module. This is typically used to store user editable options and operating system-specific information. Module config files are described in more detail in the following list.
%gconfig Contains the global Webmin configuration. See the following descriptions for more details.
$module_name The name of this module, which is just the name of the directory in which the module resides.
$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 color for table headers.
$cb The background color for table bodies.
$scriptname The name of the CGI program currently being run, relative to the directory in which it is (such as save_foo.cgi).
$remote_user The username with which the current user logged into Webmin.
$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 set up 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.
$current_lang The short code for the language currently being used, such as en or de.
%current_lang_info A hash containing information about the current language, with keys like desc for the language name and titles indicating whether graphical titles can be used. Mostly useful to theme developers.
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. The proc-lib.pl file in the proc module is one example.
A CGI program called list.cgi in this same module might look something like:
#!/usr/bin/perl
# list.cgi
# Display the list of foobar users
require './foobar-lib.pl'
&header($text{'list_title'}, "");
print "<hr>
";
print "<table border>
";
print "<tr $tb>
";
print "<td><b>$text{'list_user'}</b></td>
";
print "<td><b>$text{'list_real'}</b></td>
";
print "</tr>
";
@users = &list_users();
foreach $u (@users) {
print "<tr $cb>
":
print "<td><a href='edit.cgi?user=",
&urlize($u->{'user'}),"'>$u->{'user'}</a></td>
";
print "<td>$u->{'real'}</td>
";
print "</tr>
";
}
print "</table>
";
print "<hr>
";
&footer("", $text{'index_return'});
The important lines in this example are:
#!/usr/bin/perl
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.
require './foobar-lib.pl';
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.
&header($text{'list_title'}, "");
Any CGI that is going to produce HTML output should call the header function to produce a page title. In this case, the actual title is coming from a file in the lang directory that has been read into %text. Traditionally, a horizontal line is generated 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.
The five lines starting with print "<table border> ";
These lines output the HTML for the header of the table that the CGI is going to generate.
The seven lines starting with foreach $u (@users) {
This loop creates the table rows, each of which contains a link to another CGI program in the module. You should note the use of the urlize function to convert the username into a form suitable for a URL parameter.
print "</table> ";
These lines produce the HTML for the end of the table and the traditional final horizontal line.
&footer("", $text{'index_return'});
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. Of course, there is no requirement that you actually make use of Webmin's internationalization features. You can just put hard-coded text strings into the code instead.