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.

Modules written in other languages will not be displayed using the default theme included with recent versions of Webmin. This theme replaces the standard Perl header function with its own that displays category icons at the top of every page. For this reason, using Perl is strongly recommended.

At their simplest, modules are really just directories of CGI programs that Webmin's web server runs. However, there are certain rules that should be followed to make sure that they work with the Webmin API, main menu and access control system. Even though you can just stick any existing CGI script into a module directory, this is not a good idea.

Required Files

For a module to be displayed on the main Webmin menu, it should contain at least the following files. Only module.info is mandatory though.

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.

os_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. Unless your module configures some service that only exists on a few operating systems (such as XFree86), this line should be omitted instead of trying to list all of those supported by Webmin.

The actual operating system codes used in this line can be see in the third column of the os_list.txt file in the Webmin root directory, and are the same as those that can be appended to the names of config- files, as explained in the "Module Configuration" section. To specify only a certain version of some OS, add it to the OS name after a slash. For example, a module.info file might contain :

os_support=redhat-linux open-linux suse-linux/8.1

If your module supports all Linux distributions both no other operating systems, you can use the OS code *-linux in this line.

depends

A space-separated list of other modules upon which this module depends. If module foo depends upon module bar, then Webmin will prevent module bar from being deleted while foo is still installed. Similarly, Webmin will prevent foo from being installed if bar 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.

category

This value determines which tab on the main Webmin page your module will be categorised under. Supported values are webmin, system, servers and hardware. If your module.info file has no category line, it will appear under the Others category.

hidden

In Webmin versions 1.140 and above, if this value is set to 1 the module will not appear on the main menu, but will otherwise be fully accessible. Useful for modules that contain only library functions or scripts for command-line use.

lang/en

The text strings used by this module, as explained in the "Internationalization" section.

When you first create a new module, it will not be in the ACL of any Webmin user and so you will not be able to see it in the main menu. You must first delete the file /etc/webmin/module.infos.cache to clear the cache of known modules. Then to make your module visible, either edit the file /etc/webmin/webmin.acl, or use the Webmin Users module to grant yourself access.

Module CGI Programs

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.

#!/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

Common Functions

acl_filename()

Returns the filename in which the list of users and their modules is stored. For internal use only.

additional_log(type, object, data) (Versions 0.81 and above)

When using file-change logging, this function adds an entry to the logs for the current action. Useful if Webmin has not done this for you automatically, for example if your code has run a command with a piped open statements. You might use it like this :

open(PIPE, "somecommand |");
&additional_log("exec", undef, "somecommand");

The parameters to this function are :

• type - Must be one of exec (for logging commands run), modify (for a file change) or sql (for an SQL statement executed).
• object - The full path to the file modified for file change logs, or undef otherwise.
• data - The shell command run, diff output for the file modified or the SQL statment executed.

available_usermods(allmods, usermods) (Versions 1.000 and above)

Given a list of all modules and access control information, returns a list of modules that the current Usermin user has access to. Mainly for internal use by the Usermin main menu and themes. allmods must be a reference to an array of module details as returned by get_all_module_infos, while usermods must a reference to the array returned by list_usermods.

backquote_command(command, safe) (Versions 1.210 and above)

Executes the given command like the Perl ` operator, unless the current user is in read-only mode or the safe parameter (new in Webmin 1.220) is set.

backquote_with_timeout(command, timeout, [safe]) (Versions 1.190 and above)

This function is similar to the Perl backquote ` operator in that it executes the given command and returns its output. However, if the command fails to complete within the specified timeout (in seconds), it will be terminated and any partial output returned. The safe parameter (new in Webmin 1.220) indicates if the command is safe for running in readonly mode or not.

backquote_logged(command) (Versions 0.81 and above)

This function is similar to the Perl backquote ` operator in that it executes the given command and returns its output, but it also records the command executed for later logging by webmin_log.

can_lock_file(filename) (Versions 1.180 and above)

Returns 1 if locking will be done on some filename by lock_file, or 0 if not. This function is really for internal use only.

capture_function_output(function, arg, ...) (Versions 1.210 and above)

Executes the specified function (passing it the given arguments) and captures everything that the function prints to STDOUT. This function returns the output produced by the called function, and an array reference to the function's return value. This can be useful for dealing with older code that insists on printing out HTML, which you would rather capture for further manipulation before displaying.

check_clicks_function() (Versions 1.110 and above)

Returns Javascript defining a function called check_clicks that returns true the first time it is called, but false every subsequent time. This is useful to prevent the submit buttons of forms from being clicked multiple times, with code like :

print &check_clicks_function();
    print "<input type=submit value='Delete' onClick='return check_clicks(form)'>>n";

As the example shows, the check_clicks function can take the current Javascript form object as an optional parameter. If so, it will disable all buttons on that form the second time it is called.

check_ipaddress(string)

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

check_ip6address(string)
(Versions 1.200 and above)

Returns 1 if the given string is a valid IPv6 address like aaaa:bbbb::7 or ::1 or 1234:3456:5678:aabc:5314:ab13:aa88:9900, or 0 if not.

check_os_support(moduleinfo)

Determines if the module whose details are in the moduleinfo parameter is supported on this operating system or not. This must be a hash reference of the kind returned by get_module_info or get_all_module_infos. This function is mainly for internal use - if you just want to find out if a module is available on this system, use foreign_check instead.

check_pid_file(file) (Versions 1.170 and above)

Checks the given file to see if it contains the PID of a running process. Returns the PID if so, or undef if not.

clean_environment() (Versions 0.91 and above)

Delete from the global environment %ENV all entries set by the Webmin webserver, such as REMOTE_USER and anything starting with HTTP_. This should be called before your CGI script starts a server process such as Apache or Squid, so it doesn't get confused by environment variables normally only visible to CGI programs.

close_http_connection(handle) (Versions 0.90 and above)

Closes an HTTP session handle created by make_http_connection.

close_tempfile(handle) (Versions 1.190 and above)

Like the standard Perl close function, but re-names the temporary file created by open_tempfile over the real target if all writes have been successful. May call error if the file cannot be closed properly.

command_as_user(user, env, command) (Versions 1.220 and above)

Given a shell command, returns a new command suitable for running it as the specified user (typically by wrapping it in su). If the env parameter is set to 1, all of the user's environment variables from their .profile or .cshrc files will be available to the command as well.

complete_http_download(handle, destfile, [error], [callback])

This function is used internally by http_download and ftp_download, and should never be called directly by module developers.

convert_osdn_url(url) (Versions 1.220 and above)

Given a url that refers to a SourceForge download page or specific mirror site instance for a file, returns a URL for the actual download location from the best available mirror. The best is determined using the user's preference in the Webmin Configuration module.

copy_source_dest(source, dest) (Versions 1.230 and above)

Copies the source file or directory to the dest path. For directory copies, all permissions and ownerships are preserved by doing a recursive copy using the tar command. If any Webmin file path translation is in effect, it will be applied to the copy source and destination.

copydata(in, out)

Reads data from the filehandle in and writes it to out until there is no more to read.

create_user_config_dirs() (Versions 0.93 and above)

In Usermin, modules cannot store persistent configuration data in their configuration directory $module_config_directory because it is only writable by root. If you code wants to store settings on a per-user basis, it should call this function which will set the global variable $user_module_config_directory to ~currentuser/.usermin/modulename and ensure that the directory exists.

The files defaultuconfig in the module's directory, uconfig in the module configuration directory under /etc/webmin and config in the user's module configuration directory will be read in that order into the global hash %userconfig. See the "Creating Usermin Modules" section for more details.

date_chooser_button(dayfield, monthfield, yearfield, [formno]) (Versions 0.83 and above)

Returns HTML for a button that when clicked allows the user to select a date. The dayfield parameter must be the name of a text input into which the day will be placed, monthfield the name of select input for the month, and yearfield the name of a text input for the year. The formno if given is the number of the form on the current page that contains the inputs.

decode_base64(string)

Takes a string in base-64 encoded format and converts it back to the normal form. This format is often used for email attachments and passwords in HTTP requests. The opposite is encode_base64.

disk_usage_kb(directory) (Versions 0.86 and above)

Returns the number of kilobytes used by the given directory and all the files in it.

encode_base64(string) (Versions 0.75 and above)

Returns the given string encoded in base64 format, with a return at the end of each line (even if only one line is produced).

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 by displaying the message parameter and exiting. It assumes that error_setup has been called first to set the first part of the error message, to which the parameter will be appended. For example :

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

error_setup(message)

Any code that calls error should call this function first to specify that the message parameter should be prepended to all future errors displayed.

execute_command(command, stdin, stdout, stderr, translate, safe) (Versions 1.210 and above)

This function executes the specified command, feeding it input and capturing output. The stdin, stdout and stderr parameters can all either be filenames to read or write, scalar references to either fetch input from or capture output to, or undef indicating that input or output should be ignored.

If the translate parameter is set to non-zero, any input or output filenames will be subject to possible filename translation. If the safe parameter (which is new in Webmin 1.220) is set, the command will still be allowed to run even if the current user is in read-only mode.

fast_wait_for(handle, string, ...)

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

file_chooser_button(field, type, form, [chroot], [addmode])

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.
• chroot - If set, the file browser will not display files outside of this directory.
• addmode - If set to 1 in Webmin versions 1.170 and above, the selected filename will be appended to the field instead of overwriting.

filter_javascript(html) (Versions 0.93 and above)

Given the html for an entire webpage, this function attempts to strip out or disable all Javascript and returns the result. If your module displays HTML from an untrusted source (such as an email message or file on the server), it should call this function on the HTML in order to remove the potential security risk of malicious Javascript, which could capture the session key for the current Webmin login.

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.

flush_file_lines([file], [eol])

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.

In Webmin versions 1.170 and above, the file parameter can be given to specify a particular file to flush, rather than all those read by read_file_lines. Also, if the eol parameter is supplied lines written out will end with whatever it is set to, rather than the default of \n.

flush_webmin_caches() (Versions 0.980 and above)

Clears all the in-memory and on-disk caches used by web-lib.pl. This function is really for internal use only.

footer(link, text, [link, text], ...)

Outputs a small left-facing arrow and a link with the text "Return to text". Any CGI program that calls header must also call this function at the end in order to complete the page's HTML properly.

In Webmin versions 0.92 and above, you can specify multiple link and text parameters to have the function generate multiple footer links, like so :

&footer("", "module index", "list.cgi", "users list");

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.

In Webmin versions 0.960 and above, you can use the normal Perl syntax for calling functions in other modules, like :

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

foreign_available(module) (Versions 1.190 and above)

Checks if some other module exists, is supported under the current operating system, and is available to the current Webmin user.

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.

foreign_config(module, [user-config]) (Versions 0.70 and above)

Returns a hash containing config options from the specified other module, just like the %config hash set by init_config for this module.

If you are writing a module for Usermin, the user-config flag can be set to indicate that you want the user preferences for the module, rather than the global config.

foreign_defined(module, function) (Versions 1.170 and above)

Checks if some function is defined in another module for which foreign_require has been called, and returns 1 if yes, 0 if not.

foreign_installed(module, mode) (Versions 1.110 and above)

Checks if the server or service that some module manages is installed on the system. If the mode parameter is set to 0, this function either returns 1 if the service is installed, or 0 if not. However, when mode 1 is used, then the function will return 2 if the service is installed and configured for use by Webmin, 1 if installed but not configured, or 0 if not installed at all. An example of a module that needs to be configured before it can be used is MySQL Database Server - the user must provide login information for the server before the module can be used.

Some Webmin modules do not support being queried to determine if their server is installed, as explained in the "XXX" section. If this is the case for the specified module, then this function will always return 1 (or 2 if mode is set to 1).

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.

ftp_command(command, expected, [error])

Used by the ftp_download function to send a command to the connected FTP server. Your module code should never call this function.

ftp_download(host, file, destination, [error], [callback], [user, pass], [port])

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.

The optional error and callback parameters are only supported in Webmin versions 0.93 and above, and behave in exactly the same way as in the http_download function, documented above.

In Webmin versions 1.120 and above, the user and pass parameters can be supplied to have the function login to the FTP server as a particular user. If they are omitted, it will login with the username anonymous and the password root@your.hostname. In Webmin versions 1.270 and above, the optional port parameter can be used to specify a different FTP server port than the default of 21.

ftp_upload(host, file, source, [error], [callback], [user, pass])
(Versions 1.170 and above)

Makes an FTP connection to some host and uploads the local source file to file on that host. The upload will never be made via a proxy, even if one is set in the Webmin configuration.

The optional error and callback parameters behave in exactly the same way as those to the http_download function, documented above. The user and pass parameters can be supplied to have the function login to the FTP server as a particular user. If they are omitted, it will login with the username anonymous and the password root@your.hostname.

generate_icon(image, title, link, [href], [width], [height], [before], [after])

Outputs HTML for an icon with the given image, title below it and as a hyperlink to the relative or absolute URL in the link parameter (if set). If the href parameter is supplied it will be included in the <a href=> tag, so that you can point the link to a different frame. The icon's size will be set to 48 x 48, unless the width and height parameters are given.

In Webmin version 1.220 and later, the before and after parameters can be given to specify non-linked HTML that appears before or after the title below the icon. This can be used for additional links, checkboxes and so on.

get_all_module_infos(cachemode) (Versions 0.950 and above)

Returns a list of hash references, each containing the details of one installed module in the same format as returned by the standard get_module_info function. In order to avoid having to read one file from each module, this function usually caches the module details in the file /etc/webmin/module.infos.cache, which can be read much faster.

If the cachemode parameter is set to 0, normal caching of known modules is done. If it is set to 1, the cache is not used at all. If set to 2 any existing cache will be read but not written out.

get_available_module_infos(cachemode)

Like get_all_module_infos, but only returns modules available to the current Webmin or Usermin user instead of every one on the system. The cachemode parameter is passed on to get_all_module_infos and thus has exactly the same meaning.

get_charset (Versions 1.130 and above)

Returns the character set that should be used for HTML pages in the current language. This should only need to be called by modules that output their own Content-type: header, instead of calling the header function.

get_current_dir (Versions 1.230 and above)

Returns the directory in which the current script is running, in an OS-independent way.

get_display_hostname (Versions 1.130 and above)

Like get_hostname, but returns the hostname that should be displayed to the user. This is effected by settings in the Webmin Configuration and Usermin Configuration modules.

get_goto_module (Versions 1.150 and above)

Returns details of a module (as a hash reference) that the current user should be directed to after logging in. This is mostly useful for theme developers.

get_group_module_acl(group, [module]) (Versions 1.210 and above)

Like get_module_acl, but returns the ACL for a group instead of a user.

get_miniserv_config(hashref)

Fills in the hashref Perl hash reference parameter will the configuration from Webmin's built-in web server, miniserv.pl. This is generally read from /etc/webmin/miniserv.conf. The opposite function is put_miniserv_config for writing out a new configuration.

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 calling module is user. See the "Module Access Control" section for more information on module ACLs.

get_module_info(module, noclone) (Versions 0.76 and above)

Returns a hash containing information about the given module, with the keys desc, os_support and dir. If the noclone parameter is set to 1, details of the underlying module will be returned when requesting information on a cloned module.

get_mod_lib() (Versions 1.170 and above)

Returns the best matching library for the current OS in the current module's directory.

get_perl_path() (Versions 1.140 and above)

Returns the full path to Perl being used by Webmin on this system. Useful for modules that create their own Perl scripts.

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, as it tries several different methods.

get_theme_info(theme) (Versions 0.92 and above)

Like get_module_info, but returns the details of a theme from it's theme.info file.

get_visible_module_infos() (Versions 1.140 and above)

Like the get_all_module_infos function, but only returns modules that do not have the hidden flag set in their module.info file. This function should be called by themes that generate menus of modules available to the user.

get_webmin_version() (Versions 0.70 and above)

Returns the version of Webmin this module is running under.

get_windows_root() (Versions 1.230 and above)

When running Webmin on Windows, this function returns the base directory for the Windows install, such as c:/winxp.

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.

guess_mime_type(filename, [default]) (Versions 1.180 and above)

Given a filename, returns the MIME type typically associated with that filename's extension. If none can be guessed, returns the value of the default parameter (on Windows 1.230 and up), or application/octet-stream instead.

has_command(command)

Searches Webmin's PATH for the given command. Returns 1 if found, 0 if not. If an absolute path is specified, the function instead checks to see if it exists and is executable or not.

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

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 instead of the text from title. This should always be set to an empty string.
• 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.
• body - Extra HTML tags to be include in the <body> tag. This parameter is only supported in Webmin versions 0.79 and above.
• below - HTML to be displayed below the header. Often this is used on modules' main pages to show the version of the server that the module is configuring.

If a theme is in use that defines its own theme_header function, all of the above parameters will be passed to that function instead. This means that they may be interpreted quite differently, and the supplied title and other information placed in unexpected locations depending on the theme in use.

If this function is called by a Usermin module and the config parameter is set, your code must have called create_user_config_dirs beforehand, in order to setup the ~/.usermin/modulename directory. Instead of a Module Config link being included in the header, one called Preferences will be instead, which allows the user to edit his own personal settings for the module. The actual settings that can be changed are determined by the uconfig.info file in the module directory, which has the same format as config.info described below.

Some themes have a custom header function that puts all HTML output after the heading into a table. Unfortunately, some browsers will not display a table's contents until its ending HTML tag has been output. This means that if your CGI program is producing some progressive output (such as the new contents of a log file) or takes a long time to run, nothing will be visible to the user until it completes. To avoid this, the special global variable $theme_no_table should be set to 1 before header is called, indicating that page content should not be put in an HTML table.

help_file(module, page)

Returns the full path to the file containing the HTML for the given help page in the specified module. Files for the user's chosen language are used in preference to English, if they exist. This function is mainly for internal use only though.

help_search_link(terms, section, ...) (Versions 0.86 and above)

Returns HTML for a link to the System Documentation module for searching for the given terms. The section parameters after the terms determine what documentation is searched, and each can be one of

• man - Manual pages
• doc - Package documentation
• kernel - Kernel documentation
• howto - HOWTO documents
• kde - KDE documentation
• perl - Perl module documentation
• help - Webmin help
• google - The Google search engine

The return value from this function can be passed as the 7th parameter to the header function on the main page of your module, creating a link to additional info in man pages or README files. For example :

&header("The Foo Module", undef, undef, 1, 1, undef,
 	&help_search_link("foo", "man", "doc", "google"));

hlink(text, page, [module], [width, height]) (Versions 0.63 and above)

Returns HTML for a link to a help page. The text parameter is the text of the link and page the name of the help page. See the "Online Help" section for more information.

In Webmin version 1.240 and above, the optional module parameter can be used to request a help page from a different module. The optional width and height parameters can set a different size for the popup help window, rather than the Webmin or user-selected default.

html_escape(string)

Given a text string, converts the characters <, > and & to &lt;, &gt; and &amp; respectively, among others. It should be used when text from some source that may contain HTML characters is going to be included in a page generated by your module, so that the text appears exactly as it should and potentially malicious HTML code (perhaps containing Javascript) is neutralized.

http_download(host, port, page, destination, [error], [callback], [sslmode], [user, pass])

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.

The optional error and callback functions are only supported in Webmin versions 0.93 and above. If error is supplied, it must be a reference to a scalar that will be set with an error message if the download fails, instead of the function simply calling the standard error function in the case of a failure.

In Webmin versions 1.080 and above, if the sslmode parameter is set to 1 the function will make an HTTPS instead of HTTP connection to the remote webserver. And in Webmin 1.120 and above, the user and pass parameters can be used to have the function do HTTP authentication when making the request.

The callback parameter can be a reference to a function that will be called back to at various stages of the download process. When called, the first parameter indicates the status, and the second some additional information. Possible status codes are :

1. Server has been contacted
   The second parameter is 1 if the requested URL is a redirect, or 0 if a normal file.
2. Download has started
   The second parameter is the size of the file being downloaded, if it is known.
3. Some data has been received
   The second parameter is the amount of data received so far. This will be called for every 1kb (or less) of data received.
4. Download complete
   The URL has been totally downloaded. No second parameter is supplied.
5. Redirected to new URL
   The second parameter is the new URL to which the request has been redirected.

If you just want to display the progress of a download in the way that some of the code Webmin modules do, the standard function progress_callback can be passed as the 6th parameter to http_download. However, you must set the global variable $progress_callback_url to the URL or name of the file being downloaded, for use in the progress messages.

icons_table(links, titles, icons, [columns], [href], [width], [height])

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 the columns parameter is given, it specified the number of icons to display per row. The default is for each row will contain 4 icons. The href, width and height parameters have exactly the same meaning as in the generate_icon function, which this one actually calls to create each icon.

include(file)

Copies the content from the given file to STDOUT.

indexof(value, array)

Returns the index of some value in the array which comprises the rest of the parameters, or -1 if not found.

indexoflc(value, array) (Versions 1.250 and above)

Works just the same as the indexof function, but does a case-insensitive comparison.

init_config()

Initializes global configuration variables. See the "Module CGI Programs" section 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.

is_readonly_mode() (Versions 1.220 and above)

Returns 1 if the current Webmin user is not allowed to make changes to the system's configuration. Many internal functions use this to avoid actually updating files or running commands, while still returning success so that CGIs still appear to work.

is_under_directory(directory, file) (Versions 1.030 and above)

Returns 1 if the given file is under the specified directory, 0 if not. Both must be absolute paths. If the file is actually a symbolic link, its target must be under the directory for the function to return 1. This can be useful in modules that enforce restrictions on the directories that users are allowed to edit files in.

kill_byname(name, signal)

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

kill_byname_logged(name, signal) (Versions 0.91 and above)

Like the kill_logged function, but also records the command executed for later logging by webmin_log.

kill_logged(signal, pid, ...) (Versions 0.81 and above)

This function is exactly the same as the Perl kill statement, but also records the signal and PIDs for later logging by webmin_log.

list_categories(&modules) (Versions 1.220 and above)

Given a reference to an array of Webmin modules (as returned by get_all_module_infos or similar), this function returns a hash from module category codes to their descriptions. It is mainly useful for theme developers.

link_file(src, dest) (Versions 1.220 and above)

Creates a hard link from the src file to the dest path. Any active Webmin filename translation is applied to the given filenames first.

list_languages() (Versions 0.76 and above)

Returns a list of hash references, each containing the details of a supported language. This function is generally for internal use only.

list_mime_types() (Versions 1.180 and above)

Returns an array of MIME types known to Webmin. Each entry is a hash reference, with two keys - type being the mime type, and exts an array of possible filename extensions for that type.

list_osdn_mirrors(project, file) (Versions 1.220 and above)

Returns list of URLs from which the given file can be downloaded from the given project from SourceForge. Modules that perform automatic updates of other packages from SourceForge may find this useful, but it is primarily for internal use.

list_usermods() (Versions 1.000 and above)

Returns an array containing information about which Usermin users can have access to which modules. For internal use only.

load_language(module, [directory])

Returns a hash containg translations for some module, just like the %text hash that init_config sets for this module.

In Webmin versions 1.140 and above, the directory parameter can be specified to have language strings read from a directory other than lang. This can be useful if your module contains multiple language directories, and you want to merge them together with code like :

%text = ( %text,
          &load_language($module_name, "lang2"),
          &load_language($module_name, "lang3") );

load_theme_library()

Reads the theme.pl file for the current theme, if one exists and if it has not been loaded yet. This is another internal use only function that module writers should not call.

lock_file(file) (Versions 0.81 and above)

Obtains an exclusive lock on the given file, if necessary waiting until the lock is released if it is held by another program. Locking is done by creating a .lock file contain the PID of the process, which guarantees that locks will not be held forever by dead processes. Locks can be made on files, directories and symbolic links, and should be made before any of those are created, modified or deleted.

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

make_dir(dir, perms, recursive) (Versions 1.220 and above)

Creates the directory given by the dir parameter, with Unix permissions specified by perms. If the recursive parameter is set to non-zero, any needed parent directories will be created as well. If Webmin filename translation is in effect, it will be applied to the directory path.

make_http_connection(host, port, ssl, method, page) (Versions 0.90 and above)

A general function for making an HTTP connection, possibly using SSL. The function will attempt to connect to the given host and port (in SSL mode if the ssl flag is set), through a proxy server if you have one configured in Webmin. It will then make an HTTP request using the given method and page, and return a session handle reference if no errors are encountered. If any error does occur in the connection, a scalar error string will be returned.

The returned session handle should be used with the read_http_connection and write_http_connection functions to send any additional headers and to read back the response headers and body. When done, the close_http_connection function should be called with the session handle.

module_root_directory(module) (Versions 1.180 and above)

Given the directory name of a module (like apache), returns the full path to it's root directory. Because Webmin 1.180 supports multiple root directories, this should be used instead of code like $root_directory/apache.

modules_chooser_button(field, multiple, [form]) (Versions 1.210 and above)

Returns HTML for a button that when clicked will pop up a list of modules. When one is selected, it's directory name will be placed into the specified named field. If the multiple parameter is set to non-zero, more than one module can be selected.

nice_size(number, [minimum]) (Versions 1.140 and above)

Given a number of bytes, converts it into a number of gigabytes, megabytes, kilobytes or bytes with the appropriate suffix. Useful for displaying file sizes and the like to users in a friendly way.

If the minimum parameter is set, it is taken to be the minimum level of precision for the returned value. For example, if it was set to 1048576 then the result would always be in MB or GB.

month_to_number(month) (Versions 1.190 and above)

Given an english-language month name like feb or june, returns the number for that month (counting from zero) such as 1 or 5. Useful for parsing log files in which human-readable dates are used.

no_proxy(host)

Returns 1 if Webmin will connect directly to the given host for HTTP requests, or 0 if a proxy will be used. Mainly for internal use by the various HTTP-related functions.

month_to_number(number) (Versions 1.210 and above)

Given a month number like 1, returns the short English-language name for that month, like Jan.

open_execute_command(handle, command, output, [safe]) (Versions 1.210 and above)

Runs the specified command, attaching either its input or output to the given file handle, depending on the value of the output parameter. When the current user is in read-only mode, the command will not be run unless the optional safe parameter is set to 1, if using Webmin 1.220 or later.

open_lock_tempfile(handle, file, no-error) (Versions 1.190 and above)

This function behaves identically to open_tempfile, but also calls lock_file on the target file before opening it. When the file handle is closed with close_tempfile, it will be automatically unlocked as well.

open_readfile(handle, file) (Versions 1.210 and above)

Opens the specified file for reading, on the given file handle.

open_socket(host, port, handle, [error])

Attempts to open a TCP connection to the specified host and port using the given Perl file handle. Once this function returns the caller can read from or write to the handle to communicate with a remote system, and call close on it when done. If the connection cannot be made the error function is called with a message explaining what went wrong, unless the error parameter to this function has been set as a scalar reference. If so, the error message is place in that variable and the function returns 0 (instead of the usual return value of 1).

open_tempfile(handle, file, no-error) (Versions 1.190 and above)

Like the standard Perl open function, but writes to a temporary file in the same directory as the specified destination file instead. Only when close_tempfile is called will the temporary file be re-named over the real target. This protects config files from being over-written if the system runs out of disk space.

Code to use this function should be like :

&open_tempfile(FILE, ">/tmp/blah");
&print_tempfile(FILE, "hello world\n");
&close_tempfile(FILE);

If any error occurs opening the file, the standard error function will be called. This can be avoided by setting the no-error parameter to 1, in which case the function will return 0 to indicate a failure.

other_groups(user) (Versions 0.82 and above)

Returns a list of secondary groups to which the Unix user belongs.

print_tempfile(handle, text) (Versions 1.190 and above)

Like the standard Perl print function, but calls error if any error occurs when writing to the file handle. Should be used in conjunction with open_tempfile.

PrintHeader([charset])

Outputs the Content-type: text/html header (and possibly others) that all CGI programs which produce HTML much generate. If the charset parameter is given, it specifies the character set of the HTML. Normally this function is not called directly - instead, header will it for you with the right character set for the user's language.

popup_error(message)
(Versions 1.270 and above)

This function should be used instead of error to display an error message in a popup window. It will simply display the error without the usual Webmin category icons and links.

popup_footer()
(Versions 1.220 and above)

This function must be called instead of footer at the end of any page for which popup_header was used.

popup_header([title], [head], [body])
(Versions 1.220 and above)

This function should be called instead of header in any popup window (such as a user or file chooser) that doesn't need the full Webmin set of category icons and links. The title parameter sets the window type, the optional head parameter is for adding extra HTML to the <head> section, and the body parameter is for extra attributes in the <body> tag.

progress_callback(action, details)

This function exists to be passed to http_download so that download progress reports will be printed. Calling it directly from your code makes no sense.

put_miniserv_config(hashref)

Writes the configure from the hash reference parameter hashref to the configuration file used by Webmin's built-in webserver. You will need to call restart_miniserv for this change to have any effect though.

quote_path(path)
(Versions 1.230 and above)

Returns the given path with quoting to make it suitable for safe inclusion in a shell command. On Unix systems this is done with \ characters, while on Windows double-quotes are used.

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

ReadParseMime([max-size])

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.

In Webmin versions 1.140 and above, an optional max-size parameter can be specified to limit the total size of uploaded data. This can be handy for stopping people from uploading huge files that take up all of the servers bandwidth, memory or disk space.

read_acl([hashref1], [hashref2])

This function fetches the current list of which Webmin user has access to which modules and stores it in the hashes referenced by the two parameters. hashref1 will be filled in as a two-key hash, in which the first key is a username and the second a module name. hashref2 will be filled in with usernames, each referring to an array of modules that the user has. For example :

&read_acl(\%hash1, \%hash2);
print "User $remote_user has access to Users and Groups<br>\n"
        if ($hash1{$remote_user,'useradmin'});
print "User $remote_user has access to ",
        join(" ", @{$hash2{$remote_user}}),"<br>\n";

read_env_file(file, hash) (Versions 0.79 and above)

Reads a file of /bin/sh variable assignments in key=value or key = "value" format into the given hash reference.

read_file(file, hash, [lowercase], [split-char])

Reads a file in key=value format into the given hash reference. If the lowercase parameter is set, all keys are converted to lower case before addition to the hash. If the split-char parameter is set (in Webmin 1.160 and above), it is used as the character instead of = to split the key and value on each line.

read_file_cached(file, hash) (Versions 0.950 and above)

Like the standard read_file function documented above, but keeps a cache of files read in order to avoid reading them multiple times. Mostly for internal use at the moment.

read_file_contents(file) (Versions 1.230 and above)

Returns the complete contents of the given file as a scalar. Not recommended for use on large files!

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.

read_http_connection(handle, [amount]) (Versions 0.90 and above)

Reads either a single line from the given session handle returned by make_http_connection, or the specified number of bytes if the amount parameter is supplied.

recursive_disk_usage(directory) (Versions 1.260 and above)

Returns the number of bytes used by all files in the given directory (subject to any Webmin filename translation in effect). Unlike disk_usage_kb, this function will not round up to block sizes, and so may produce a different result.

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.

reload_miniserv()
(Versions 1.220 and above)

This function is similar to restart_miniserv, but instead of completely restarting the Webmin webserver, it instead simply signals it to reload most configuration files. It should be used after making most changes to miniserv.conf or miniserv.users, as it is much faster and imposes less CPU load than restart_miniserv.

remote_error_setup(handler) (Versions 0.93 and above)

Normally, when one of the remote_* functions encounters an error (such as the remote Webmin server being down), it will call the standard error function which will cause your CGI program to exit. However, if you use this function to register an alternate error handler, it will be called instead, and the remote function will return its return value.

remote_eval(server, module, code) (Versions 0.82 and above)

Executes some perl code on a remote Webmin server in the context of the given module. This can be very useful if you want to do something that is not possible by calling a function with remote_foreign_call. However, you must first call remote_foreign_require with the same server and module before using this function.

remote_finished() (Versions 0.82 and above)

This function should be called by any CGI that makes use of any of the other remote_ functions once it has finshed calling them, in order to clean up connections to the remote servers. It is not strictly necessary though as the connections will timeout after 10 seconds of inactivity. Also, when using fast RPC this never needs to be called as remote sessions will exit as soon as your CGI finishes.

remote_foreign_call(server, module, function, [arg], ...) (Versions 0.82 and above)

Calls a function in some module on another server and returns the results. You must already have called remote_foreign_require for the same server and module before trying to use this function. The function parameter is the name of a function to call in the remote module, and the arg parameters after it are arguments that will be passed to it. For example :

&remote_foreign_require("www.blah.com", "apache", "apache-lib.pl");
@servers = &remote_foreign_call("www.blah.com", "apache", "get_config");

As the example shows, the remote_foreign_call function returns whatever is returned by the function on the remote server.

remote_foreign_check(server, module) (Versions 0.82 and above)

Checks if a module exists and is supported on a remote Webmin server. If yes, return 1 - otherwise, returns 0. If in doubt, you should call this before calling remote_foreign_call to access functions in other modules on another server.

remote_foreign_config(server, module) (Versions 0.90 and above)

This function is similar to foreign_config, but is for fetching a module configuration from a remote server instead. But unlike foreign_config it returns a hash reference rather than a hash.

remote_foreign_require(server, module, file) (Versions 0.82 and above)

The remote_ series of functions are similar to the foreign_ functions, but instead of just allowing you to call code in another module they allow you to call code on another Webmin server. Each server that you want to call remote functions on must first be registered in the Webmin Servers module, with the Link type option set to Login via Webmin and a username and password entered.

Before calling functions from a module on another server with remote_foreign_call, you must use this function to bring in the appropriate library. The server parameter is the hostname of the remote Webmin server, 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.

remote_write(server, localfile, [remotefile]) (Versions 0.90 and above)

If when making remote function calls you need to transfer a large amount of data to a remote server, this function should be used instead of passing it in a scalar through remote_foreign_call. The localfile parameter is a file on the server the function is called on, and the remotefile parameter the name of a file on the remote server to which the contents of localfile will be copied. If remotefile is omitted, a random temporary filename will be chosen instead and returned from the function.

remote_read(server, localfile, remotefile) (Versions 0.90 and above)

This is the opposite of remote_write, in that it copies data from a file on a remote webmin server into a local file.

remote_rpc_call(server, command) (Versions 0.90 and above)

This internal function is used by all of the other remote_* functions to actually open a connection to the specified server and send the command structure tell it what to do. You should never call it directly.

rename_file(old, new) (Versions 1.220 and above)

Renames a file from an old path to a new one. This is superior to the Perl built-in rename function, as it can move files across filesystems if needed. In addition, the supplied filenames are converted by any filename translation currently in effect.

rename_logged(old, new) (Versions 0.81 and above)

Renames a file like the Perl rename function, but also records the event for later logging by webmin_log. While you could just lock the old and new files before renaming, that would generate two large and rather useless diffs.

replace_file_line(file, line, [newline], ...)

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

reset_environment() (Versions 0.91 and above)

Returns the environment to the state it had before the last call to clean_environment.

resolve_links(file) (Versions 0.950 and above)

Given a file name that may contain symbolic links somewhere in it's path, returns the actual real filename that it refers to. Unlike the Perl readlink function, this also resolves symbolic links in directories along the path as well.

restart_miniserv()

Re-starts Webmin's built-in webserver, forcing it to re-load its configuration. This function is mainly used by the Webmin Configuration module, and is probably of little use to the average module coder.

running_in_zone() (Versions 1.210 and above)

Returns 1 if the current Webmin install is running inside a Solaris zone or similar virtual environment.

same_file(file1, file2) (Versions 0.950 and above)

Returns 1 if file1 and file2 refer to the same actual file, by comparing inode numbers.

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 the "Module Access Control" section for more information on module ACLs.

In Webmin versions 1.160 and above, if the user has received the access control settings for the module from a group, then the group's ACL is updated as well. This is necessary because it is really the group's access control settings that determine the user's.

save_module_config([&config], [modulename]) (Versions 1.140 and above)

Updates a module's configuration file in the /etc/webmin/modulename directory. If the config parameter is supplied, it must be a reference to a hash of values to save - otherwise, the global %config is used. If modulename is not supplied, the current module's configuration will be updated.

save_user_module_config([&config], [modulename]) (Versions 1.170 and above)

Like save_module_config, but updates a Usermin user's personal preferences instead of the module's global configuration.

seed_random() (Versions 0.85 and above)

Seeds the Perl random number generator so that calls to rand will return truly random results. Uses /dev/urandom if available, or the current time and process ID otherwise.

select_all_link(field, form, text) (Versions 1.160 and above)

Returns HTML for a link that when clicked on selects all the checkboxes named field on form number form. The text of the link is determined by the text parameter if set, otherwise defaulting to Select all. This function is useful for giving the user a way to select all checkboxes on a form at once, such as in the standard Read User Mail module.

select_invert_link(field, form, text) (Versions 1.160 and above)

Like the select_all_link function, but inverts the state of all specified checkboxes. If the text parameter is not given, the text defaults to Invert selection.

serialise_variable(variable)

Converts the given Perl scalar or reference variable into a text string. This function is mainly used by the various RPC-related remote_* functions for encoding parameters and return values, but you may find it useful for persistently storing Perl objects. The unserialise_variable function does the reverse.

set_ownership_permissions(user, group, perms, file, ...) (Versions 1.220 and above)

Changes the Unix file ownership and permissions on one or more files specified by the file parameters. The user and group arguments can be given as usernames or UIDs, or left as undef to leave the ownership unchanged. The perms parameter must be either a new octal permissions number, or undef to not make any changes. All file paths will be subject to any Webmin filename translation currently in effect.

simplify_path(path) (Versions 1.190 and above)

Given a path that may contain . or .. directories, removes them to create a basic pathname. For example, /tmp/foo/../bar would be converted to /tmp/bar.

split_quoted_string(string) (Versions 1.250 and above)

Given a string like foo "bar baz" quux, returns an array like ( "foo", "bar baz", "quux" ).

substitute_template(text, &hash) (Versions 1.210 and above)

Given some text and a hash reference, for each ocurrance of $FOO or ${FOO} in the text replaces it with the value of the hash key foo.

supports_symlinks() (Versions 1.230 and above)

Returns 1 if the current operating system supports symbolic links. Unix based operating systems do, Windows does not.

supports_users() (Versions 1.230 and above)

Returns 1 if the current operating system supports Unix users (and thus the getpw* and getgr* series of functions), 0 if not (as on Windows).

switch_to_remote_user() (Versions 0.93 and above)

This function should only be called by code in Usermin modules, and will switch the UID and GID of the current process to those of the Unix user whose login matches the current Usermin login. If your Usermin module can run with normal user permissions (and most can), you should call this function after init_config in your module's library.

In addition to switching the UID, this function also sets the global variable @remote_user_info to the details of the Unix user, as returned by the getpwnam Perl function.

symlink_file(src, dest) (Versions 1.220 and above)

Creates a symbolic link from the src file to the dest, subject to any active Webmin filename translation.

symlink_logged(src, dest) (Versions 1.220 and above)

Creates a symbolic link from the src file to the dest, and logs this in Webmin's actions log. The supplied filenames are also subject to any active filename translation.

sysprint(handle, value, ...)

Calls the perl syswrite function to print the values to the given file handle without any buffering.

system_logged(command) (Versions 0.81 and above)

This function is exactly the same as the Perl system statement, but also records the command executed for later logging by webmin_log.

tempname()

Returns a pathname in /tmp that can be used as a temporary file. The actual filename will always be under the /tmp/.webmin directory, unless overridden by the tempdir variable in /etc/webmin/config. The directory is only writable by root but world readable, so if your temp file is going to contain security-critical information it should be chowned to mode 700 before writing.

terror(string)

Like a combination of the error function and the %text array. A call to &terror('foo') is exactly the same as &error($text{'foo'}). This function really just exists to make calling error more convenient in an internationalized module.

test_lock(file) (Versions 1.220 and above)

Returns 1 if some file is currently locked, 0 if not.

text(message, [parameter], ...) (Versions 0.75 and above)

Looks up the given message in the appropriate language translation file, replaces the text $1, $2 and so on with the rest of the parameters, and returns the result. See the section on "Internationalisation" for more.

to_ipaddress(hostname)

Given a hostname, this function returns a string like 10.254.1.100 representing the IP addresss for that hostname, or undef if none was found. If the parameter is already an IP address it is returned unchanged.

transname([filename])
(Versions 1.190 and above)

Like the tempname function, but marks the returned temporary file as transient, to be automatically deleted when the current script executes. This should be used for any temp files that do not need to be passed to other programs, to avoid the need to manually delete them.

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.

unix_crypt(password, salt)
(Versions 1.240 and above)

Returns the standard Unix DES encrypted version of the given password with the given salt. This function is better than the Perl crypt method, as it will fall back to using the Crypt::UnixCrypt Perl module if crypt is disabled on your operating system for some reason.

unix_group_input(field, group, [form])

Returns HTML for a text box named field for entering a group name, with a button next to it that pops up a window for selecting a group. The group parameter sets the initial value for the field. If the field is not on the page's first form, the form parameter should be set to the correct form number.

unix_user_input(field, user, [form])

Returns HTML for a text box named field for entering a username, with a button next to it that pops up a window for selecting a user. The user parameter sets the initial value for the field. If the field is not on the page's first form, the form parameter should be set to the correct form number.

unlock_all_files() (Versions 0.81 and above)

Releases all locks currently held by this program, by calling unlock_file multiple times.

unlock_file(file) (Versions 0.81 and above)

Releases a lock on file grabbed by the lock_file function. If the logging of file changes is enabled, a diff of the old and new file contents will be done when this function is called.

unserialise_variable(string)

Converts a string created by serialise_variable back into a Perl scalar or reference of some kind.

unlink_file(file, ...)
(Versions 1.220 and above)

Deletes multiple files or directories specified by the file parameters. Any directories given are deleted recursively, using the rm -rf command. All paths are subject to any Webmin filename translation currently in effect.

unlink_logged(file, ...)
(Versions 1.220 and above)

Like the unlink_file function, but also logs the deletion and removed contents in Webmin's actions log.

un_urlize(string)

Decodes the special URL escape sequences in the given string and returns the original text. For example, hello%20world%21 would be converted to hello world!.

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%20jump%21.

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

Returns HTML for a javascript button that allows the Webmin 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.

wait_for(filehandle, regexp, ...)

Given a perl filehandle and a list of regular expressions in the regexp parameters, 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. It can be useful for interacting with other programs or servers that would normally take user input, as this example shows :

&open_socket("somehost", 23, TELNET);
select(TELNET);
$| = 1;
select(STDOUT);
while(1) {
	my $rv = &wait_for(TELNET, "login:", "password:", ">");
	if ($rv == 0) {
		print TELNET "fred\n";
		}
	elsif ($rv == 1) {
		print TELNET "mypassword\n";
		}
	elsif ($rv == 2) {
		print TELNET "ls -la\n";
		close(TELNET);
		break;
		}
	else {
		&error("Telnet failed!");
		}
	}

webmin_log(action, type, object, params) (Versions 0.81 and above)

As explained in the "Action Logging" section, this function writes to the detailed logfile the given parameters identifying the action performed by the calling program.

write_env_file(file, hash, export) (Versions 0.79 and above)

Writes the contents of a hash reference to the given file in /bin/sh variable assignment format. If the export parameter is non-zero each variable assignment is preceded with export.

write_file(file, hash, [join-char])

Writes the contents of a hash reference to the given file in key=value format. This can be read in by the read_file function. If the join-char parameter is set, it is used as the character instead of = to separate the key and value on each line.

write_http_connection(handle, [data], ...) (Versions 0.90 and above)

Writes the given data strings to the HTTP session handle.

User Interface Functions

Developers writing modules for Webmin versions above 1.130 should make use of these functions where possible. This ensures consistency between modules, and allows themes to change the appearance of Webmin in more detail. In particular, the ui_print_header and ui_print_footer functions should be called instead of header and footer, as they allow a theme to supress the <hr> lines that normally appear below the title and above the footer.

All of the functions in ui-lib.pl can be over-ridden by a theme, by simply defining a function with the same name with theme_ prepended in the theme's functions file. This function will called with the same parameters, and must return compatible HTML.

The following functions can be used to generate a table of input elements, as is used in many Webmin forms :

ui_table_start(heading, [tabletags], [cols])


Returns HTML for a table with the given heading, as used on the editing pages of most Webmin modules. The optional tabletags parameter can be used to specify extra attributes for the <table> tag, like width=100%. The cols parameter defines the number of columns inside the table, which defaults to 4.

ui_table_end()


Returns HTML to finish a table started by ui_table_start.

ui_table_row(label, input, [cols], [&td-tags])


Returns HTML for a pair of cells containing the label and input, within a table started by the ui_table_start function. The optional cols parameter can be used to specify that the second cell spans multiple columns. The optional td-tags parameter can be an array reference of extra HTML attributes to include in the <td> tags.

ui_columns_start(&headings, [width-percent], [noborder], [&td-tags])


Returns HTML for the start of a table. The headings parameter must be a reference to an array of titles for the columns in the table. The width-percent is the width of the table as a percentage of the page, to force a width other than the default. The noborder parameter can be set to 1 to turn off the table border. The td-tags parameter is an array reference of extra HTML attributes to include in the heading's <td> tags.

ui_columns_row(&columns, [&td-tags])


Returns HTML for some row in the table. The columns parameter must be a reference to an array of HTML to display in the actual columns, and the td-tags can be an array of extra HTML attributes to include in the row's <td> tags.

ui_checked_columns_row(&columns, &td-tags, checkboxname, checkboxvalue)


This function is similar to ui_columns_row, but adds an extra column at the start containing a checkbox for selecting the row. The checkboxname parameter gives the input name of the checkbox (which is typically the same for all rows), while the checkboxvalue parameter sets its value (always different for each row).

ui_columns_end


Returns HTML for the end of a multi-column table.

The following functions are for generating HTML forms :


ui_form_start(script, method)


Returns HTML for the start of a form. The script parameter is the URL or program that the form submits to, and the method parameter is the request method for the form to use (get, port or form-data).

ui_form_end([&buttons], [width])


Returns HTML for the end of a form. If the optional buttons parameter is given, a row of submit buttons will be added to the end of the form. The parameter must be a reference to an array, each element of which is a array reference containing the name and label for a button. The width parameter can be used to specify the size of the table that contains these buttons, such as 100%.

ui_textbox(name, value, size)


Returns a text input box named name with value as its initial contents, of size characters in width.

ui_upload(name, size)


Returns a file upload input box, named name and of size characters in width. These will only work properly in forms using the form-data method.

ui_password(name, value, size)


Like ui_textbox, but the input box displays stars instead of the actual password entered by the user.

ui_hidden(name, value)


Returns HTML for a form input with the specified name and value which is not visible to the user.

ui_select(name, value, &options, [size], [multiple])


Returns an input for selecting one or many items from a list, depending on the multiple flag. The value can either by a single scalar or an array reference, the latter case indicating that multiple items are selected by default. The options parameter must be an array reference, and each member of the array must be itself a two-element array ref. The first member of each element is the value for one option, while the second is the text to display for that option. When multiple options are being selected, the size parameter determines the number of rows in the selection list.

ui_radio(name, value, &options)


Returns HTML for one or more radio buttons, of which only one can be selected by the user. The name parameter determines the name of these inputs, and the value which one is initial selected. The options parameter must be an array reference, and each member of the array must be itself a two-element array ref. The first member of each element is the value for one radio button, while the second is the text to display next to that button.

ui_yesno_radio(name, value)


Like ui_radio, but always returns a pair of checkboxes with values 1 and 0 and names 'Yes' and 'No' respectively.

ui_checkbox(name, value, label, selected)


Returns a single checkbox input, named name and with value as the value to submit when it is selected. The label parameter determines the text to display next to it, and the box will be initially checked if selected is non-zero.

ui_oneradio(name, value, label, selected)


Like ui_checkbox, but returns a single radio button instead.

ui_textarea(name, value, rows, cols, [wrap-mode])


Returns HTML for a multi-line text input field, with name as its name and value as the initial value. The rows and cols parameters determine the size in characters of the text area. If the wrap-mode is specified, it can be either on, off or auto.

Javascript Functions