At the bottom of the module's main page is the installation form. It offers four options for types of source from which to install a module in tar.gz distribution file format, but the most common and useful is From CPAN. Just select it and enter the name of the module (such as Net::Telnet) into the adjacent text field.

If the module file is already on your system, you can choose the From local file option and enter the path to the tar.gz file into the field next to it. Or if you have the file on the system on which you are running your browser, click on From uploaded file and select the file using the Browse button.

The final source from which a module can be installed is a URL on another server. To have Webmin download it for you, select the From ftp or http URL option and enter the URL into the field next to it.

If the From CPAN option was chosen and this not the first module that you have installed from that source, the Refresh module list from CPAN checkbox next to the module name field will be visible. If checked, Webmin will again download the complete list of modules and the URLs on which they can be found from the CPAN website. Otherwise, it will use a local cache of the list from the previous download.

The module list should be downloaded periodically to ensure that the local copy remains up-to-date. For this reason, the box will be checked by default every 30 days, or whatever period you have set in the Webmin module's configuration.

When you have selected the source, click the Install button. This will take you to a page showing the progress of the downloaded CPAN module list and the module file itself, if necessary. If the Perl module cannot be found on CPAN or the select tar.gz file does not appear to be in the correct format, an appropriate error message will be displayed.

If the module file was downloaded and successfully verified, however, an installation options form like the one in Figure 27.2 will be displayed.

The Install action field determines which steps of the module installation process will be carried out by Webmin. The available options are:

Make only The file will be extracted, its Makefile generated with the command perl Makefile.PL, and then the make command run to build the modules it contains. No actual installation will take place.

Make and test Like the Make only mode, but compiled module will be tested with the make test command as well. Almost all Perl modules include test code to verify that they have been compiled properly.

Make and install The module file will be extracted, the modules it contains built, and then the make install command will be run to copy the compiled files to the appropriate Perl directories on your system. Once they have been installed, the modules will be usable by other Perl scripts and programs (like Webmin).

Make, test, and install Like the Make and install mode, but the make test command will be run on the compiled modules before they are installed to verify that they were built correctly. This is the default mode, but for some modules it may not be appropriate if the testing phase is prone to failing incorrectly.

For some Perl modules, additional parameters may need to be passed to the perl Makefile.PL command for them to be built correctly. If so, you can enter them into the Makefile.PL arguments field. The Net::SSLeay module, for example, requires the path to the OpenSSL directory to be given as a parameter, if it has not already been installed in the standard directory. Generally though, you will not need to fill in this field.

Some Perl modules need certain environment variables to be set before perl Makefile.PL is run. If that is the case with the module you are trying to install, fill in the Makefile.PL environment variables table with the names and values of those that need to be set. The average module does not require any special variables.

To have Webmin carry out the compile and installation steps chosen in Step 4, click the Continue with install button at the bottom of the form. This will take you to page showing each command run to build the module and any output or error messages that it produces. Only if everything is successful will a message like Make, test, and install of Net::SSLeay successful appear at the bottom of the page.

If something goes wrong, check the error messages for clues. Many Perl modules provide an interface to some C library and require that the included files for that library be installed. On many Linux distributions, these are in a different package to the library itself. For example, Net::SSLeay uses the OpenSSL C library, whose included files are often in a separate openssl-devel package. See Chapter 12 “Software Packages” for instructions on how to install packages on your system.

Assuming everything works and you choose to install the module, you can now return to the main page. The new module should be listed there and will be usable in Perl scripts and programs.