Webmin Module Writers Help

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.
Not every config parameter needs an entry in config.info - only those that the user may want to edit.
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.