In this chapter the Webmin module for listing other servers on
your network is explained, and its relationship to the Cluster
modules and RPC is documented.
The Webmin Servers Index module
This module really serves two purposes, one simple and one quite
complex. You can use it to create a master index of other systems
running Webmin on your network, each of which is shown as an icon
that you can click on to link to the server. Each icon can either
be a normal link, or a 'tunnel' that logs you into another server
automatically with all traffic sent via the first system.
As well, the module can be used to define systems which can be controlled
by a master Webmin server, using the System and Server Status
module and the modules in the Cluster category. Each of these
other systems must also have Webmin installed, and a special
RPC (Remote Procedure Call) protocol is used by the master to
communicate with and control the slaves. How this all works is
explained in detail in this chapter.
When you click on the module's icon in the Webmin category, a page
like the one shown in the image below will be displayed. Most of the
page is taken up with a table of icons, one for each of the other
servers that you have added. Of course, if this is the first time
the module has been used, no server icons will appear initially.
At the bottom are buttons for automatically finding other Webmin
servers on your local network.
The Webmin Servers Index module
Even though it was designed for creating an index of Webmin web
servers, there is not reason that you cannot create icons for
other types of web server instead. However, the module's RPC
features will naturally only work when communicating with a
host running Webmin.
Adding a Webmin server
To add a new server to this module, either to provide a link to it
or so that it can be managed with one of the Cluster group modules,
follow these steps :
- Click on the Register a new server link on the main page above or below the existing icons.
- In the Hostname field enter the Internet hostname or IP address of the other server, such as server.example.com.
- In the Port field enter the port that Webmin is listening on, usually 10000.
- From the Server type menu choose the operating system that the other host runs. This only sets the icon that will be used to represent the server.
- If the other Webmin server is in SSL mode, select Yes in the SSL server? field. This option can only be used if the master system has the Net::SSLeay Perl module and the OpenSSL? library installed, so that it can make a client-mode SSL connection.
- When the Description field is set to From hostname and port, the server's hostname and port number are shown under its icon on the module's main page. However, you can select the second option and enter an alternate description to be shown instead, such as Corporate Web Server.
- Servers defined in this module can be categorized into groups for easier addition in the Cluster category modules. In the Member of server group field you can select one of the following options : *None *The system you are adding will not be in any group. *Existing group *If some groups have already been defined, this server will be in the group selected from the menu next to this option. If no groups exist yet, this option will not even appear. *New group *The server will be added to the new group whose name you enter in the adjacent text field. A group will cease to exist as soon as all the of servers in it have been deleted or changed to another group.
- The Link type field is possibly the most important on this form, as it determines if the new server can be used in the Cluster modules and System and Server Status module. It also determines if the icon is a normal link, or a tunnel. Your options are : *Normal link to server *RPC calls cannot be made to the other server, and its icon on the module's main page will just be a normal web link. If the system is running some other webserver specified port you should select this option. *Login via Webmin with username *This option must be chosen if you want to use Webmin's RPC features to control this server, such as with the Cluster category modules. If selected, you must enter a username and password for Webmin on the remote host into the fields next to it. The user should be root or admin, as other Webmin users are not by default allowed to receive RPC calls unless specifically authorized. RPC can be used to run any command or modify any file on a server, which is why access to it must not be granted to un-trusted Webmin users. If this mode is chosen, the server's icon on the main page will be a tunnel that automatically logs whoever clicks on it into the remote server as the specified user. *Login when icon is clicked on *If this option is chosen the server cannot be used for RPC, but its icon will still be a tunnel to the remote host. However, when first clicked on it will prompt the user for a login and password for the remote system, which will be stored in a cookie in the user's browser. This option is handy if you want various users to be able to to make use of the tunneling feature, but still login to the remote system as themselves.
- If Login via Webmin with username was selected above, the Make fast RPC calls? field determines if the new fast RPC protocol will be used, or the older slow protocol. You can either select Yes to force the use of fast mode, No to force slow mode or Decide automatically to have Webmin use fast mode only if it is available. If the automatic option is chosen and the server cannot be contacted or logged into, an error message will be displayed when you hit the Create button later. Versions of Webmin before 0.89 did not support the fast protocol, but most systems should have been upgraded beyond that by now. Generally you will want to use the faster mode all the time, unless a firewall is blocking the direct TCP connections that it uses. See the 'How RPC works' section later in the chapter for more details on the differences between the two modes.
- Finally, hit the Create button to add this new server. As long as there were no errors in the form you will be returned to the module's main page, which should include a new icon.
The icons for servers not created in Normal link to server
will actually be links to a program on this master server that
connects to the remote system for you. This can actually be useful
if your master server is accessible from the Internet but internal
hosts are not, for example if you only have a single Internet IP
address and are using NAT. When you access those internal servers
by clicking on their icons in this module on the master system,
your browser is only really connecting to the master server,
which is then tunneling the requests though to the chosen slave.
On a Webmin system with multiple users you should be careful about
giving access to this module to un-trusted users. Anyone who
can click on an icon for a server in Login via Webmin with username
mode will be connected to the remote system as the user specified
for that server, not himself. This will probably allow him to
do things with root privileges on that remote host that he would
not be able to do on the master system.
The 'Module access control' section later explains how you can
control which server icons a particular user can use, so that
un-trusted people can be limited to those in the safe *Normal
link to server* or *Login when icon is clicked *on modes.
Editing or deleting a Webmin server
Once a server has been added to this module you can edit all of its
details or even delete it altogether. The steps to follow are
- On the main page, click on the (edit) link next to the name of the server that you want to change. This will bring up an editing form almost identical to the one for adding a server.
- All of the fields can be edited, and have the same options and meanings as explained in the 'Adding a Webmin server' section. The only exception is the Make fast RPC calls? field, which will not have the Decide automatically selection if the module has already worked out the RPC mode that the remote server supports.
- Hit the Save button to activate your new settings. Or if you want to remove this server from the module, hit Delete instead. Any other modules (such as those in the Cluster category) that made use of this server will automatically remove it from their lists.
Using server tunnels
When you click on an icon for a Webmin server in one of the tunnel
modes you will be connected to it via this master system. The user
interface of the remote host will be almost exactly the same as
if you logged in normally, except that every page will include
a special Webmin Servers
link. When clicked on this will take
you back to the Webmin Servers Index module on the master system,
which is more convenient than hitting the back button in your
browser a few hundred times.
For tunneling to work, the master server must analyze and modify
the HTML sent back by the remote host that you are logging in to.
Currently this works well for Webmin servers, but may fail if
you are tunneling through to some other web-based application
or website that uses HTML not supported by this module. Symptoms
of this include links pointing to non-existent pages on the master
server, and images that are not loaded properly.
Clicking on the icon for a server *Login when icon is clicked *mode
will initially display a login form for entering a username and
password for the remote system. This will appear even if the remote
host does not actually run Webmin on the chosen port, but can be
used to login to any web server that uses standard HTTP authentication.
After you login your username and password will be remembered
until you either quit your browser (thus discarding the cookie),
or click on the (logout)
link that appears below server's icon
on the module's main page.
Broadcasting and scanning for servers
If you have a large number of Webmin servers on your network, adding
them one by one to this module can be tedious. There is a better
way though - the master system can broadcast on your local LAN
for other Webmin servers, or send requests to hosts within a specific
network to probe for servers. Any found will be automatically
added to this module, although only in Normal link to server
mode. There is no way for the master system to automatically determine
a login and password for a remote system as this would be a huge security
hole if it were possible!
To find other Webmin servers, follow these steps :
- If you only want to search your local LAN, click on the Broadcast for servers button at the bottom of the module's main page. To search some other network, enter its address into the field to the right of the Scan for servers button before hitting it. This must be a class C network, entered like 192.168.1.0.
- A page listing the URLs of servers found will be displayed. New ones will have Found new server before their URLs, those already on the main page will have Found known server, and responses from the master system itself will have Found this server.
- When the process is complete you can return to the main page, which will now contain an extra icon for each of the newly found servers. Then can be edited to switch to Login via Webmin with username mode to use them for RPC.
All versions of Webmin since 0.75 listen on UDP port 10000 for
the broadcast and scan packets sent out by this module, and reply
with their hostname, port number and SSL mode. A server will not
be found if a firewall is blocking this port or if UDP listening
has been turned off for security reasons.
How RPC works
RPC is a protocol that one Webmin system can use to control another.
An RPC request is usually a call to a function in the library of
some module, and includes the parameters to that function. However,
there are other RPC request types for transferring data to and
from a server, checking if a module is available, getting a module's
configuration and executing a piece of Perl code. This section
explains the technical details of how it works, and can be skipped
if you are not a programmer and are not having any trouble with
When you set up the System and Server Status module to fetch some
status information from a remote system, an RPC call is made to
functions in the same module on that system to determine if a service
is up or down. Similarly, when a user is added in the Cluster Users
and Groups module, multiple RPC calls are made to add him to the
password file, create his home directory and copy files into
it. Chapter 56 explains how to make use of RPC in your own modules,
and what its limitations are.
As explained earlier, RPC has two different modes - fast and slow.
Slow mode is simplest, as it uses an HTTP request from the master
to the slave for each RPC function call, file transfer or request
for information. All parameters, data and return values are
included in that request and its response, and no other TCP connections
are made. The advantage of this mode is that it can work through
firewalls and proxies, as long as HTTP requests to port 10000
Apart from being slow, this mode has one big down-side - HTTP is
a stateless protocol, but Webmin RPC calls are not stateless.
It is quite possible for one function call to set a global variable
that the next function call depends upon. This means that a background
process in which state is kept must be started on the remote system
for each master that opens an RPC session. But there is no way for
a slave system to automatically detect when the master CGI program
has finished and thus shut down the background process, because
no direct connection between the two exists!
Webmin's solution is to have the process exit when the master
makes a special RPC call, or after 30 seconds of inactivity. If
a master CGI program does not invoke the remote_finished function
the remote process will hang around consuming memory until the
timeout elapses. If for some reason more than 30 seconds passed
between RPC calls to the same host, the background process will
exit and future RPC calls will fail.
The newer fast RPC protocol solves these problems using only
one initial HTTP request to have a background process started
on the remote system. The master server then makes a TCP connection
to this process (which is listening on a free port), and sends
RPC requests through that connection instead. When the master
program exits this connection will be automatically torn down,
and the remote background process will exit. No special function
calls or timeouts are needed.
Fast RPC mode has much better support for transferring large
files to and from remote systems. The slow mode attempts to encode
files inside an HTTP request, which can fail if they are two large.
The newer mode instead transfers them un-encoded through a separate
TCP connection, which is quicker and far more reliable. The Cluster
Software Packages and Cluster Webmin Configuration modules
may fail when installing a large package in slow mode.
The only problem with fast mode is that some firewalls may block
the TCP connection, which is typically made on a port 1 or 2 above
the remote host's base Webmin port, such as 10001 or 10002. Multiple
connections may be made if data is transferred with RPC, so any
firewall on your network between the two servers must be configured
to allow connections from the master to the remote host on ports
in the range 10000 up to 10100.
Module access control
If you have more than one Webmin user on your system, you may want
to make this module available to other people without giving
them access to all server icons or the ability to add servers.
This is useful if you want others to see only icons for servers
not in Login via Webmin with username
mode, thus turning the
module into just an index of other systems on your network.
The first step is to assign this module to a user, as explained
. You can then restrict him to only being able to see
and use the tunnels for certain servers by following these steps
- Click on Webmin Servers Index next to the name of the user or group in the Webmin Users module to bring up the access control form.
- Change the Can edit module configuration? field to No, so that he cannot change the user interface for other people.
- In the Can use servers field chose Selected and select the ones that you want to make visible from the list below.
- Change the Can edit servers? and Can find servers? fields to No.
- Hit the Save button to activate the new restrictions.
Hiding a server from a user in this module does not stop him from
using it in other modules that make use of RPC.
Configuring the Webmin Servers Index module
This module has several settings that control how its user interface
appears and how scans for servers are done. You can edit them by
clicking on the Module Config
link on the main page, which will
bring up a form containing the following fields :