Introduction

A module should be written to administer one service or server, such as the Unix password file or the Apache web server. Some complex system functions may even be split over several modules - for example, disk partitioning, mounting disks and disk quota management are 3 separate modules in the standard Webmin distribution.

Modules can theoretically be written in any language. However, to make use of the Webmin API Perl version 5.002 or above should be used. A module should be written entirely in Perl, with no C functions or external binary programs. The aim is for modules to be as portable as possible across different Unix systems and CPU types.

Required Files

For a module to be displayed on the main Webmin menu, it must contain at least the following two files.

images/icon.gif

The icon displayed on the main menu for this module. The icon should be 48x48 pixels, and should use the same colour scheme as the other icons on the main menu.

module.info

This file contains information about the module and the operating systems it runs under. Each line of the file is in the format
  name=value
Required names and their values are:

name

A short name for this module, such as FooAdmin.

desc

A longer description for the module, such as Foo Web Server. This is the text that will appear below the icon on the main menu.

op_support

A space-separated list of operating systems that this module supports. The module will only be displayed on the main menu if the OS Webmin is running on is in the list, or if there is no os_support line at all.

depends

A space-separated list of other modules upon which this module depends. If module A depends upon module B, then Webmin will prevent module B from being deleted while A is still installed. Similarly, Webmin will prevent A from being installed if B has not been.
The list can also contain a Webmin version (such as 0.75) that the module depends upon. In that case, installation of this module by an older version of Webmin will not be allowed. (Versions 0.70 and above)

Module CGI Programs

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).

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.

   ---

   Common Functions

   The file web-lib.pl contains a number of functions useful for generating HTML, parsing files and all the other things Webmin modules need to do. The functions available in Webmin 0.61 are listed below in order of usefulness :

   init_config()

   Initializes global configuration variables. See the example above for more details.
   Note that prior to version 0.73, the init_config function had to be passed the name of the module as a parameter. From 0.73 onwards, the module name is worked out automatically.

   ReadParse()

   This function takes any CGI parameters passed to your program (from form inputs or after the ? in the URL) and places them in the associative array %in. If a CGI parameter has multiple values (for example, from a list that allows multiple selections) then those values are separated by null characters ('\0' in perl).

   header(title, image, [help], [config], [noindex], [noroot], [text], [header])

   The header function is used by almost all programs to output the HTTP header line (Content-type: text/plain), HTML title, background and title image. The parameters passed to this function are :

   • title - The HTML title of this page. Also used as the ALT text for the title image.
   • image - The URL of an image to display at the top of the page. In the standard Webmin modules title images are drawn using The GIMP in 50-point helvetica, with a transparent background.
   • help - If this parameter is defined then a Help link is added to the title on the left hand side, linking to the given help page.
   • config - If this parameter is non-zero, a Config link is added to the left of the title image. This links to a CGI program that allows the user to edit the configuration of this module, as defined by the config.info file. See below for more details.
   • noindex - By default, the header function will add a Module Index link to the left of the title image linking to the index for this module. If this parameter is given and non-zero, this link will not be displayed.
   • noroot - By default, a Webmin Index link to the Webmin main menu will be added to the left of the title image. If given, this parameter will suppress the addition of that link.
   • text - HTML to be displayed to the right of the title image. This can be anything you like, as long as it fits in the small area available.
   • header - HTML to be displayed in the <head> section of the page. This parameter is only supported in Webmin versions 0.74 and above.

   To make the creation of title images easier, I have created a small GIMP scheme script to render a Webmin title. Just put it in your ~/.gimp/scripts directory and run it from the Xtns -> Script-Fu -> Logos -> webmin menu item.

   This script requires you have a scalable bold oblique helvetica font installed. Most Linux systems lack such a font, but you can try this one from my Solaris system. Just put it in your /usr/X11R6/lib/X11/fonts/Type1 directory, and add this line to fonts.scale in the same directory :

   Helvetica-BoldOblique.pfa -adobe-Helvetica-bold-o-normal--0-0-0-0-p-0-iso8859-1

   Then run mkfontdir and xset fp rehash.

   The typical call to the header function by a CGI program other than index.cgi in a module would look like :

   &header("Edit User", "images/edit_user.gif");

   This simply outputs the title image with links to the module and main indexes. However, the call to this function from index.cgi should be more like :

   &header("FooBar Admin", "images/foobar.gif", "", 1, 1);

   footer(link, text)

   Outputs a small left-facing arrow and a link with the text "Return to text". Useful for calling at the bottom of pages generated by your CGI programs.

   redirect(url)

   Given a relative or absolute URL, outputs a HTTP header to redirect the browser to that URL. This function will not work if called after header, and vice-versa.

   error(message)

   This function is typically used by CGI programs that process the input from a form, to inform the user of invalid input or some processing error. It assumes that a global variable called $whatfailed contains the first part of the error message, with the parameter being the rest. For example :

   $whatfailed = "Failed to save user";
   if (!$in{'name'}) { &error("Missing username"); }
   if ($in{'name'} =~ /a/) { &error("'$in{'name'}' is not a valid username"); }
   

   ReadParseMime()

   When writing a CGI program that handles input from a form using enctype=multipart/form-data this function must be called instead of ReadParse() to fill the %in array with form inputs. You must add the enctype tag to any forms using file-upload inputs.

   hlink(text, page) (Versions 0.63 and above)

   Returns HTML for a link to a help page. The first parameter is the text of the link and the second the name of the help page. See the section on help below for more information.

   tempname()

   Returns a pathname in /tmp that can be used as a temporary file.

   indexof(value, array)

   Returns the index of some value in an array, or -1 if not found.

   check_ipaddress(string)

   Returns 1 if the given string is a valid IP address like 10.254.1.100, 0 if not.

   urlize(string)

   Converts an arbitrary string to a form suitable for use in a URL. For example, don't jump! would be converted to don%27t+jump%21.

   find_byname(name)

   Given a name, searches for processes matching that name and returns their PIDs. If none are found, an empty list is returned.

   kill_byname(name, signal)

   Given a name, searches for processes matching that name and kills them with the given signal.

   wait_for(filehandle, [regexp]+)

   Given a perl filehandle and a list of regular expressions, this function reads from the filehandle until one of the expressions matches. It then returns the regexp number, and fills the global array @matches with the values of any bracketed sections of the matching expression.

   has_command(command)

   Searches the PATH for the given command. Returns 1 if found, 0 if not.

   foreign_require(module, file) (Versions 0.70 and above)

   Before calling functions from another module with foreign_call(), you must use this function to bring in the appropriate library. The module parameter is the name of the module you want to call functions in, and the file parameter the name of a library file in that module directory.

   foreign_call(module, function, [arg]*) (Versions 0.70 and above)

   Calls a function in another module, and returns the results. The module parameter must by the module name, function the name of the function to call in that module, and any remaining parameters the arguments to pass to that function. For example :

   &foreign_require("proc", "proc-lib.pl");
   @procs = &foreign_call("proc", "list_processes");
   &foreign_call("proc", "renice_proc", $pid, -10);
   

   The example above calls the proc module to get a list of processes, and then again to change the priority of some process.

   foreign_config(module) (Versions 0.70 and above)

   Returns an associative array containing config options from some other module.

   foreign_check(module) (Versions 0.70 and above)

   Checks if some other module exists and is supported under the current operating system. If yes, return 1 - otherwise, returns 0. You should call this before calling foreign_call to access functions in other modules.

   get_module_acl([user], [module]) (Versions 0.72 and above)

   Returns a hash containing the ACL for the given user and module. If no user is specified, the current user is used. If no module is specified, the caller's module is user. See below for more information on module ACLs.

   save_module_acl(acl, [user], [module]) (Versions 0.72 and above)

   Saves the given module ACL hash. If no user is specified, the current user is used. If no module is specified, the caller's module is user. See below for more information on module ACLs.

   get_system_hostname() (Versions 0.70 and above)

   Returns the hostname of the system Webmin is running on. More reliable that the standard Perl hostname() function.

   file_chooser_button(field, type, form)

   Returns HTML for a javascript button that allows the user to select a file or directory on the server. The parameters are :

   • field - The name of the HTML field into which the chosen filename will be placed.
   • type - 0 for a file chooser, 1 for a directory chooser.
   • form - The form number containing the field. Typically 0.

   user_chooser_button(field, multiple, form) (Versions 0.63 and above)

   Returns HTML for a javascript button that allows the user to select a user or users from those on the server. The parameters are :

   • field - The name of the HTML file into which the chosen user or users will be placed.
   • multiple - 0 for selecting a single user, 1 for selecting multiple users.
   • form - The form number containing the field. Typically 0.

   group_chooser_button(field, multiple, form) (Versions 0.63 and above)

   Just like the user_chooser_button function above, but for the selection of groups instead.

   http_download(host, port, page, destination)

   Makes a HTTP connection to a webserver host and port to request some page. The contents of this page are then stored in the destination file. If the user has configured his Webmin installation to use a proxy server, then the HTTP request will go through that proxy.

   ftp_download(host, file, destination)

   Makes an FTP connection to some host and requests the download of a file. The contents of this file are then stored in the given destination file. If an FTP proxy is configured, the download will be made via the proxy.

   to_ipaddress(hostname)

   Given a hostname, this function returns a string like 10.254.1.100 representing the IP addresss for that hostname.

   generate_icon(image, title, link)

   Outputs HTML for an icon with the given image, title and link. All Webmin icons should be 48 x 48 pixels, with a transparent background.

   icons_table(\links, \titles, \icons, [columns])

   The main Webmin page and many modules use grids of icons, each linking to a different option, domain, share or suchlike. This function generates an icons grid based on the lists given as parameters. links is a reference to an array of URLs, titles a reference to an array of messages to appear below icons, and icons a reference to an array of image URLs.
   If a 4th parameter is given, it is taken as the number of icons to display per row. If unspecified, each row will contain 4 icons.

   replace_file_line(file, line, [newline]*)

   This function removes one line from a file and replaces it with 0 or more new lines. This is done by reading the entire file into memory and writing out the modified version.

   read_file_lines(file)

   Returns a reference to an array containing the lines from the given file, with any newline (\n) characters removed. The caller can then modify this array by adding, removing or changing lines using functions like push and splice. flush_file_lines can then be called to write changes back to the original files.

   flush_file_lines()

   Writes back to disk the arrays of lines for any files requested by calling the read_file_lines function. A newline (\n) character is added to each line.

   read_file(file, \array)

   Reads a file in key=value format into the given associative array.

   write_file(file, \array)

   Writes the contents of an associative array to the given file in key=value format.

   html_escape(string)

   Given a text string, converts the characters <, > and & to &lt;, &gt; and &amp; respectively.

   obtain_lock(file)

   Locks the given file. If the file is already locked, waits until the lock is released and then re-locks it. Locking is done by creating a file with .lock appended and writing the current process ID into it.

   release_lock(file)

   Released the current lock on the given file. A program should only unlock files that it has locked.

   test_lock(file)

   Tests if a file is currently locked.

   trunc(string, length)

   Truncates a string of space-separated words so that it is less than or equals to the given length, without chopping off part of a word.

   unique([value]+)

   Given a list of values, returns an array with duplicates removed.

   sysprint(handle, [value]+)

   Calls the perl syswrite function to print to the given filehandle without any buffering.

   include(file)

   Copies the content from the given file to STDOUT.

   copy_data(fromhandle, tohandle)

   Reads from one filehandle and writes to another until the first runs out of data.

   fast_wait_for(handle, [string]+)

   This function works like wait_for, but matches exact strings instead of regular expressions.

   make_date(time_t)

   Given a Unix time_t value (seconds since 1970), returns a date-time string in the format dd/mm/yyyy hh:mm

   get_webmin_version() (Versions 0.70 and above)

   Returns the version of Webmin this module is running under.

   ---

   Module Configuration

   Almost all modules have a set of configuration parameters, available to module CGI programs in the %config array. When Webmin is installed, a config file appropriate for the chosen operating system is copied from the module directory to the Webmin configuration directory for that module, typically something like /etc/webmin/foobar/config.

   The associative array %gconfig contains global configuration options, typically from the file /etc/webmin/config. Some useful global configuration options are :

   os_type

   The operating system type selected in setup.sh, such as solaris or redhat-linux.

   os_version

   The operating system version selected in setup.sh, such as 2.5 or 5.1

   path

   The Unix path for this operating system, as a : separated list of directories.

   Many modules deal with the configuration of some service that is mostly the same on different operating systems. Apache for example works exactly the same under Solaris and Redhat Linux - the only difference is the standard location of the Apache config files. In the Webmin Apache module the Apache config file directory is itself a configurable parameter that is initially set based on the operating system chosen.

   Configuration parameters can also be used for options that the user may want to occasionally change. For example, the BIND module has a parameter that controls for format of new DNS zone serial numbers. When the 4th parameter of the header() function is set, a link will be generated to a CGI program that allows the user to edit the configuration of the current module. This program reads the file config.info in the module directory to determine the possible values for each config parameter. A typical config.info file might look like :

   foobar_path=Path to foobar config file,0
   display_mode=Index page display mode,1,0-Long,1-Medium,2-Short
   password_file=Foobar server users file,3,None
   file_user=Config files are owned by user,5
   

   Each line is in the format

   config_name=description,type[,values]

   The meanings of the parts of each line are :

   • config_name
     The name of a parameter in the module configuration that this line will apply to.
     
   • description
     A description of this parameter for the user.
     
   • type
     A number that determines how this parameter can be chosen. Possible values are
     • 0 - Free text. Any value can be entered by the user
     • 1 - One of many. The user can choose one of several options. For this type, the values part of the line is a comma-separated list of value-display pairs. The value part of each pair is what gets stored in the config file, while the display part is what is shown to the user.
     • 2 - Many of many. The user can choose zero of more of several options. Available options are specified in the same way as type 2.
     • 3 - Optional free text. The user can either select the default option, or enter some value. The values part of the line is the description of the default option (typically something like 'None' or 'Default mode')
     • 4 - One of many. The same as type 1, but uses a menu instead of a row of radio buttons
     • 5 - Unix user. Displays a list of users from the host Webmin is running on.
     • 6 - Unix group. Displays a list of groups from the host Webmin is running on.

When a module is installed (either as part of a Webmin distribution or separately) a config file appropriate to the OS being used is copied from the module directory to the configuration directory (usually under /etc/webmin). To decide which base config file to use, Webmin uses the OS name and version chosen when setup.sh was run to look for the following files

config-osname-osversion
config-osname
config

Where osname is something like redhat-linux or solaris, and osversion is something like 2.6 or 5.0. A typical module might have the following config files

config-redhat-linux
config-redhat-linux-5.0
config-slackware-linux
config-debian-linux
config-solaris

Webmin treats each of the Linux distributions as a different OS, as each has different locations for things like the Apache config file, crontab files and bootup scripts. The OS version number for Linux should be the distribution version (such as 4.1 or 5.0) rather than the kernel version.

Look and Feel

• All pages should be viewable on any browser that supports images, tables and forms. Browser features such as frames, DHTML, Javascript or Java should not be used unless there is no other option. It should be possible to use Webmin from browsers such as Netscape 1.1 or Pocket IE.

• All CGI programs that generate HTML output should call the header() function. The standard modules use 50-point helvetica text in black with a transparent background, created using The GIMP. Your modules should use the same font, size and style for consistency.

• The header() function outputs HTML tags setting the background, text and link colours for the generated page based on configured colour scheme. The init_config() function sets the global variables $tb and $cb which should be used as the background colour for table headers and body rows respectively, as in this example :

  print "<table border width=100%>\n";
  print "<tr $tb> <td><b>Foo</b></td> <td><b>Bar</b></td> </tr>\n";
  print "<tr $cb> <td>some value</td> <td>another value</td> </tr>\n";
  ...
  

• Try to avoid generating HTML forms that contain a large number of input fields. Some browsers (particularly netscape on Unix) slow down when rendering such pages.

Design Goals

No module should ever corrupt a service config file or remove options that it does not understand. Modules should be able to parse any valid configuration without requiring special comments or a special format. If your module cannot deal with some option in a config file, it should be left alone.

Webmin modules should be designed to be easy for novices to use, but still allow the user to do almost everything that could be done by editing the config file directly.

Online Help

print &hlink("Enter username:", "name"),
      "<input name=username size=20><p>\n";

Per-Module ACLs

Module ACL options are set in the Webmin Users module by clicking on the name of a module next to a user's name. The options available are generated by code from the module itself (except for the Can edit module configuration? option, which is always present). When the user clicks on Update the form parameters are also parsed by code from the module being configured, before being saved in the Webmin config directory.

A module wanting ACL options must contain a file called acl_security.pl in its directory. This file must contain two perl functions :

acl_security_form(acl)

This function takes a reference to a hash containing the current ACL options for this user, and must output HTML for form inputs to edit those ACL options. Because the HTML will be inside a 4-column table, you must generate the appropriate <tr> and <td> tags around your input elements.

acl_security_save(acl, inputs)

This function must fill in the given hash reference with values from the form created by acl_security_form. Form inputs are available in the global hash %in as generated by ReadParse, or from the second parameter to the function.

If a user has not yet had any ACL options set for a module, a default set of options will be used. These are read from the file defaultacl in the module directory, which must contain name=value pairs one per line. These options should allow the user to do anything, so that the admin or master Webmin user is not restricted by default.

To actually enforced the chosen ACL options for each user, your module programs must use the get_module_acl function to get the ACL for the current users, and then verify that each action is allowed. When called with no parameters this function will return a hash containing the options set for the current user in the current module, which is almost always what you want. For example :

#!/usr/local/bin/perl
require './foo-lib.pl';
%access = &get_module_acl();
$access{'create'} ||
	&error("You are not allowed to create new foo users");

When designing a module that some users will have limited access to, remember the user can enter any URL, not just those that you link to. For example, just doing ACL checking in the program that displays a form is not enough - the program that processing the form should do all the same checks as well. Similarly, CGI parameters should never be trusted, especially hidden parameters.

User Update Notification

To have your module notified when a user is added, updated or deleted you must create a perl script called useradmin_update.pl in your module directory. This file must contain three perl functions :

useradmin_create_user(user)

This function is called when a new Unix user is created. The parameter is a hash containing the details of the new user, described in more detail below.

useradmin_modify_user(user)

This function is called when an existing Unix user is modified in any way. The parameter is a hash containing the new details of the user.

useradmin_delete_user(user)

This function is called when a Unix user is deleted. Like the other functions, the hash containing the user's details.

user	The login name of the new or modified user
uid	The Unix UID of the user
gid	The Unix GID for the user's primary group
pass	The user's password, encrypted with the crypt() function
plainpass	The user's password in plain text. This is only available when the passmode key is equal to 3
passmode	This number depends on the choice made for the Password field in the Create User or Edit User form. No password is set for this user, typically meaning that no password is required to login This user is not allowed to login at all Only the encrypted password for this user is available A new or initial plain-text password is available in the plainpass key. The user's password is unchanged. Only possible when useradmin_modify_user is called.
real	The user's real name
home	The user's home directory
shell	The user's login shell

If the system has shadow passwords enabled, other keys may also be available - but it is not a good idea to rely on them.

When your functions are called, they will be in the context of your module. This means that your useradmin_update.pl script can require the file of common functions used by other CGI programs. The functions can perform any action you like in order to update other config files or whatever, but should not generate any output on STDOUT, or take too long to execute.

Module Packaging

drwxrwxr-x 3001/10       0 Aug 12 21:53 1998 dfsadmin/
drwxrwxr-x 3001/10       0 Nov  7 01:10 1997 dfsadmin/images/
-rw-rw-r-- 3001/10     245 Aug  1 23:41 1998 dfsadmin/images/icon.gif
-rw-rw-r-- 3001/10    1438 Aug  1 23:41 1998 dfsadmin/images/dfsadmin.gif
-rw-rw-r-- 3001/10    1541 Aug  1 23:41 1998 dfsadmin/images/create_share.gif
-rw-rw-r-- 3001/10    1265 Aug  1 23:41 1998 dfsadmin/images/edit_share.gif
drwxrwxr-x 3001/10       0 May 16 18:32 1997 dfsadmin/test/
-rw-r--r-- 3001/10     493 May 16 18:32 1997 dfsadmin/test/dfstab
-rw-r--r-- 3001/10     483 May 16 18:15 1997 dfsadmin/test/dfstab.bak
-rw-rw-r-- 3001/10    2774 Jul 29 22:22 1998 dfsadmin/dfs-lib.pl
-rwxr-xr-x 3001/10    1582 Mar 31 15:45 1998 dfsadmin/index.cgi.bak
-rw-rw-r-- 3001/10      49 Aug 12 21:53 1998 dfsadmin/module.info
-rwxr-xr-x 3001/10    1596 Mar 31 15:45 1998 dfsadmin/index.cgi
-rw-rw-r-- 3001/10    2775 Jul 29 22:22 1998 dfsadmin/dfs-lib.pl.bak
-rw-rw-r-- 3001/10     199 Mar  5 19:30 1998 dfsadmin/help.html
-rw-rw-r-- 3001/10     175 Mar  5 19:30 1998 dfsadmin/config.info
-rw-r--r-- 3001/10     140 Mar  5 19:30 1998 dfsadmin/config-solaris
-rwxr-xr-x 3001/10     142 Mar  5 19:30 1998 dfsadmin/delete_share.cgi
-rwxr-xr-x 3001/10    4842 Mar  5 19:30 1998 dfsadmin/edit_share.cgi
-rwxr-xr-x 3001/10     657 Jun  8 15:02 1998 dfsadmin/restart_sharing.cgi.bak
-rwxr-xr-x 3001/10    3000 Mar  5 19:30 1998 dfsadmin/save_share.cgi
-rw-rw-r-- 3001/10      57 Aug 12 21:53 1998 dfsadmin/module.info.bak
-rwxr-xr-x 3001/10     573 Jun  8 15:02 1998 dfsadmin/restart_sharing.cgi

API Changes

Version 0.74

• The header function now accepts an additional parameter for adding extra HTML to the <head> section of the page.
• Added link to a font used for creating Webmin headers.

Version 0.73

• The init_config function no longer needs the module name to be passed as a parameter, in order to support the cloning of modules. Modules should no longer have their name hard-coded anywhere in CGI programs or perl scipts - instead, the $module_name variable should be used.

Version 0.72

• Added the get_module_acl and save_module_acl functions for use with the per-module ACL feature. See above for more details.
• Changed the way the Users and Groups module notifies other modules when users are added, updated and deleted. The API for notification is now documented above.

Version 0.70

• Module library files should now include web-lib.pl with the statement do '../web-lib.pl'; instead of require '../web-lib.pl';. This is required to make foreign function calls to your module possible.
• It is now possible to call functions from other modules' libraries, using the foreign_require and foreign_call functions. See the documentation above for more details.
• The function get_system_hostname has been added, to return the hostname of the system Webmin is running on. The hostname function in Sys::Hostname was failing on some Linux systems.
• Added the function get_webmin_version.
• ACL checking is now automatic. The old acl_check function now does nothing, and so no longer needs to be called.

Version 0.63

• Added the hlink function, which returns HTML for a pop-up window for some module help page.
• Added the user_chooser_button and group_chooser_button functions, for more scalable selection of users and groups.