Module Configuration

Almost all modules have a set of configuration parameters, available to module CGI programs in the %config array which is set by the init_config function. When Webmin or a module 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.
    • 7 - Directory. Like the free text input, but with a directory chooser next to it.
    • 8 - File. Like the free text input, but with a file chooser next to it.
    • 9 - Multiline free text. The first value after the type is the width of the input, and the second the height.
    • 10 - Like type 1, but with an additional option for entering free text of the user's choice.
    • 11 - A parameter of this type does not allow the user to enter anything, but instead puts a section header row containing the description into the configuration form at this point.
    • 12 - A field for entering a password, without actually displaying the current value.
    • 13 - Like type 2, but uses a list box instead of a menu for the options.
    • 14 - This type triggers the execution of a Perl function in the file config_info.pl in the module's directory, which must return an alternate set of values for this configuration item. The function called is determined by the first value, and all values for this option are passed as parameters to the function.
    • 15 - When editing the configuration, this type triggers the execution of a Perl function in the config_info.pl file, whose name is the value for this option with show_ prepended. The function must return HTML for this configuration input.
      When saving, a function with parse_ is called instead. It can make use of the %in hash to find out what the user entered, and must return a new value for this module configuration setting.
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.

On Linux systems, the file config-*-linux will be used if no specific file exists for the Linux distribution installed. This can be useful if you want to create settings for all variants of Linux, without having to define a file for each individually. However, actually creating such a file can be a bit tricking in most shells, as * is the wildcard character. Just precede it with a backslash to escape it.