How To Install The Zimbra Desktop (Outlook) On Ubuntu

source: http://www.howtoforge.com/how-to-install-zimbra-desktop-on-ubuntu8.04

1 Installing Zimbra Desktop

Go to http://www.zimbra.com/products/desktop_download.html and click on the Linux download link:

(JavaScript must be enabled in your browser to view the large image as an image overlay.)

In the Firefox download dialogue, select Save File and save the file somewhere on your hard drive (e.g. your desktop – my desktop folder is /home/falko/Desktop):

(JavaScript must be enabled in your browser to view the large image as an image overlay.)

Zimbra Desktop is being downloaded:

(JavaScript must be enabled in your browser to view the large image as an image overlay.)

After the download has finished, open a terminal (Applications > Accessories > Terminal):

(JavaScript must be enabled in your browser to view the large image as an image overlay.)

(The following commands must be executed as a normal user, so please make sure you’re not looged in as root!)

Go to the folder where you’ve stored the Zimbra file (e.g. your desktop):

cd /home/user/Desktop/

Next, make the file executable:

chmod 755 zdesktop_0_90_build_1249_linux_i686.sh

Then start the installation:

./zdesktop_0_90_build_1249_linux_i686.sh

Great themes for Ubuntu 9.04

source: http://www.unixmen.com/linux-distributions/ubuntu/265-great-themes-for-ubuntu-904-jaunty-jackalope

Now i will show you the steps you have to follow to install the themes.

To add the repository ,open the source list :

sudo gedit /etc/apt/sources.list

add these 2 lines at the end of the sources.list:

deb http://ppa.launchpad.net/bisigi/ppa/ubuntu jaunty main 
deb-src http://ppa.launchpad.net/bisigi/ppa/ubuntu jaunty main

after open the terminal and add the repository verification key :

sudo apt-key adv –recv-keys –keyserver keyserver.ubuntu.com 0×1781bd45c4c3275a34bb6aec6e871c4a881574de

Now update the cache

sudo apt-get update

Now, If you want to install the  themes one by one ,then you will have to type the command correspondent to the theme you want to install (first follow the steps above to add the repositories)  :

1-Showtime for Gnome :

sudo apt-get install showtime-theme 

2- Balanzan

sudo apt-get install balanzan-theme 

2-Infinity

sudo apt-get install infinity-theme 

3-Wild shine

 sudo apt-get install wild-shine-theme 

4-Exotic

sudo apt-get install exotic-theme

5- Tropical

sudo apt-get install tropical-theme 

6-Bamboo Zen

sudo apt-get install bamboo-zen-theme

7- Ubuntu sunrise

  sudo apt-get install ubuntu-sunrise-theme 

8-  Aqua Dreams

sudo apt-get install aquadreams-theme 

To remove thethemes you have to use the command :

sudo apt-get remove theme-name 

Firewall Configuration – Webmin

source: http://doxfer.com/Webmin/LinuxFirewall

If your system is connected to the Internet, it may be useful to protect it with a firewall to prevent unauthorized access. This page covers the process of setting up and configuring a firewall with Webmin and IPtables.

Introduction to firewalling with IPtables

A firewall is a system that protects itself and other hosts on a network from attackers on untrusted networks, such as the Internet. It can block packets and connections based on a variety of criteria, such as the source address, destination address, port and protocol. Typically a firewall is also a router, forwarding packets between a secure local network and the untrusted Internet – however, it is also possible for a system to protect just itself.

A firewall system can also be configured to hide multiple hosts behind a single IP address, using a process known as NAT (Network Address Translation). Typically, the hidden hosts are on an internal LAN using a private IP network (such as 192.168.0.0) and the firewall has a single Internet IP address. NAT allows these internal hosts to communicate with others on the Internet, even though they do not have real public IP addresses.

The Linux kernel has included several different firewall implementations over the years, such as IPfwadm and IPchains. The 2.4 series of kernels include the IPtables firewall, which is more powerful and flexible than its predecessors. All Linux distributions that use the 2.4 kernel has IPtables support enabled, and include the commands needed to configure it. This chapter and the Linux Firewall module only cover the setting up of a firewall using IPtables, not any of the older implementations like IPchains or IPfwadm.

All IP network traffic is broken up into packets, which are chunks of data with a source, destination and protocol information. Even a continuous flow of data such as the download of a large file is broken into packets when sent, and re-assembled at its destination. Because the IPtables firewall operates at the IP level, all of its rules and chains evaluate and operate on individual packets, not TCP connections or HTTP requests.

An IPtables firewall is made up of three different kinds of object – tables, chains and rules. Each of the three tables contains two or three standard chains, and possibly many user-defined custom chains. Each chain contains zero or more rules, which are applied to packets received by or sent out from the firewall to determine their fate. The three tables and their standard chains are :

• Packet filtering (filter)
  The INPUT, OUTPUT and FORWARD packets chains in this table apply to packets received by, sent out from or forwarded by the firewall respectively. If the firewall system is acting as a router, only the FORWARD chain applies to routed packets. Network traffic destined for the system itself is processed by the INPUT chain, and traffic sent out by local process by the OUTPUT chain. For a system that is an ordinary router and not doing any masquerading, or a system that only needs a firewall to protect itself, this is the only table that rules need to be added to.

• Network address translation (nat)
  This table is used only for packets that start a new connection. The rules in its PREROUTING chain are applied to packets as soon as they are received by the system for routing, and the POSTROUTING for packets about to leave after routing. The OUTPUT chain rules are applied to locally generated packets for modification before routing. Rules are typically added to this table to set up masquerading, transparent proxying or some other kind of address translation.

• Packet alteration (mangle)
  This table is used only for specialized packet alteration. It contains two chains – PREROUTING for modifying packets before routing, and OUTPUT for modifying locally generate packets. This table is rarely used at all in a typically firewall configuration.

When a network packet is processed by a chain, each rule in the chain is executed in order. Every rule has a set of conditions that determine whether the rule matches or not, and an action that is taken in the case of a match. This action may be to immediately accept the packet, immediately drop it, perform some modification or continue execution. If the end of a chain is reached, its default action will be taken instead, which is usually to allow the packet through.

The screenshot below shows the tables and chains that a packet passes through, and the order in which they are checked. Packets coming in from the network enter the diagram at the top, and are processed by both the PREROUTING chains. At this point, a decision is made – packets destined for the local system go to the left, while those being forwarded to some other destination take the right hand branch. Those that go left are processed by the Incoming packets chain before being delivered to local processes, such as servers. Forwarded data is processed by the Forwarded packets and After routing chains before being send on to its destination.

The firewall can also effect packets send out by processes on the local system. These are checked against the three Output chains and the After routing chain before being transmitted via the appropriate network interface to their destinations. This means that an IPtables firewall can be used to limit the addresses that local processes can connect to, and the protocols they can use.

An overview of IPtables

The Linux Firewall module

This module can be used to set up a firewall on a Linux system with IPtables enabled, or edit any part of an existing firewall. It stores the firewall configuration in a save file created and read by the iptables-save and iptables-restore commands, not in a shell script containing calls to the iptables command. Redhat, Debian and Gentoo Linux all use a save file like this as standard, which Webmin knows about and will work with.

If you have manually created a firewall using a shell script and want to use this module to edit it from now on, it will have to be converted to an IPtables save file so that Webmin can edit it. Fortunately, the module can do this for you automatically � all you have to do is stop your custom script from being run at boot time, and tell the module to create its own firewall setup script instead.

This also applies to firewalls created by tools such as YaST? or fBuilder, which write out shell scripts of iptables commands. Unless the tool can also edit an IPtables save file (such as knetfilter), it should not be used alongside Webmin’s Linux Firewall module, or they will probably overwrite each other’s settings.

When you enter the module from the Networking category, the main page will usually display a list of all chains and rules in the first table that contains any (usually Packet filtering), as shown in below. However, if Webmin detects that the iptables or iptables-save commands are not installed, an error message will be displayed instead – check your distribution CD or website for a package containing them.

The Linux Firewall module

If this is the first time you have used the module and no firewall has been set up on your system yet, the main page will instead display a form to simplify the initial firewall creation. Three options will be displayed – select one and click the Setup Firewall button to set it up. If necessary, Webmin will also display an Enable firewall at boot time? checkbox which if selected will cause a boot-up script to be created so that the firewall is enabled at boot time as well. The firewall setup options are :

• Allow all traffic
  If selected, the firewall will be created ‘empty’ and all traffic allowed through.

• Do network address translation on external interface
  The firewall will be set up for NAT, so that hosts on an internal LAN can access the Internet via a host with a single public IP address. You must select the network interface that is connected to the Internet from the list next to this option, such as ppp0.

• Block all incoming connections on external interface
  If chosen, the firewall will be set up to block all traffic coming into your system on the selected network interface, except for established connections, DNS replies and harmless ICMP packets. The interface you select should be the one connected to the Internet, such as ppp0.

If this is the first time the module has been used and Webmin detects that an firewall already exists on your system, its rules will be displayed and you will be prompted to convert it to a save file so that the module can be used to edit it. If you choose to do this by clicking the Save Firewall Rules button, all existing tables, chains and rules will be safely recorded. An *Enable firewall at boot time?* checkbox will also be displayed if necessary, which if selected will cause Webmin to create a boot script to activate the saved firewall rules at boot time.

If you choose to convert an existing manually created firewall configuration, be sure to disable any existing script that sets it up at boot time. Otherwise both the old script and the one created by Webmin will be run, possibly causing the rules set up in this module to be cancelled out by the older manual configuration.

Allowing and denying network traffic

To restrict the types of connections and packets that your firewall will accept or forward, you need to create additional firewall rules. The best place for these rules is the Packet filtering table, in either the Incoming packets or Forwarded packets chain. If your firewall is acting as a router and you want to protect systems on the secure network that it is attached to but not the firewall itself, the Forwarded packets chain should be used. However, if you want to protect both the firewall and other systems that it routes to, rules should be added to the Incoming packets chain.

It is also possible to restrict data being sent out by your system, which may come from local processes or be forwarded from other hosts. To do this, you can add rules to the Outgoing packets chain. This can be useful for limiting what addresses and ports local users can connect to, if you desire.

To create a new rule to block traffic, the steps to follow are :

1. On the main page of the module, select Packet filtering from the list next to the Show IPtable button, and then click it to switch to the filtering table.
2. To add a rule that applies to all incoming traffic, click the Add Rule button in the Incoming packets section. If you want to restrict only forwarded traffic, click the button under Forwarded packets instead. Either way, you will be taken to the rule creation form, shown in the screenshot below.
3. Change the Action to take to Drop, so that packets matching this rule are silently discarded by the firewall.
4. In the Condition details section, select the conditions that determine which packets will be matched and thus dropped. Only packets matching all conditions that are not set to Ignore will be dropped. Some examples of the conditions to select to block certain kinds of traffic are :
   • Blocking all connections to a certain TCP port
     Set the Network protocol field to Equals and select TCP. To block a port, a protocol must always be selected. Set the Destination TCP or UDP port to Equals and enter a port number into the Port(s) field next to it. You can block several ports by entering a list of numbers separated by commas into the Port(s) field, or block an entire range by selecting Port range and entering the start and end ports into the fields next to it.
   • Blocking all traffic from a particular address
     Set the Source address or network to Equals and enter the IP address to block into the field next to it. You can also block an entire network by entering a network/prefix pair like 130.194.164.0/24 into the field. Set the Connection state to Does not equal and select Existing connection from the menu next to it. This step will allow your system to connect to the blocked addresses, but not vice-versa.
   • Blocking traffic to a particular address
     Set the Destination address or network to Equals and enter the IP address or network to block into the field next to it. Because this will effectively stop the blocked system from connecting to yours as well, it may be a good idea to set the Connection state to Does not equal and select Existing connection from the menu next to it. In all cases, it is usually a good idea to set the Incoming interface to the network interface that is connected to the Internet (such as ppp0), so that the restriction does not apply to connections from your local LAN.
5. When you are done selecting conditions, click the Create button. As long as there are no errors in your input, you will be returned to the module’s main page on which the new rule will be listed.
6. To make the new rule active, click the Apply Configuration button at the bottom of the page.

The rule creation form

The rules in each chain are evaluated in order from top to bottom, and the action taken is determined by whichever one matches first. If none match, then the chain’s default action is taken, which is usually to accept to the packet. You can make use of this evaluation order to create a rule that allows a single IP address, followed by a rule to deny an entire network. The final effect will be that every host within the network is denied except one.

Because the ordering of rules is important, you may sometimes want to add a rule in the middle of an existing chain. To do this, use on of the arrow buttons under a chain’s Add column on the module’s main page to create a new rule either before or after an existing one.

The most common actions and their meanings are listed below. Not all are available in all chains and tables.

• Do nothing If a rule with this action is matched, nothing will be done and processing will continue to the next rule.

• Accept Matching packets will be immediately accepted, and no further processing will be done in the chain. However, rules in other tables may still effect the packet.

• Drop Matching packets will be silently discarded, as though they were never received at all. No further processing will take place is this chain or any other.

• Userspace Packets will be passed to a normal userspace process. This action is rarely used.

• Exit chain Jump immediately to the end of the chain, and execute its default action instead. If this is used in a user-defined chain, processing will return to the rule that called it.

• Masquerade Matching packets will have their source address changed to appear to come from the firewall system, and no further rules in the chain will be processed. When this action is selected, you can use the Source ports for masquerading field to control which ports the firewall will use for masqueraded connections. See the Setting up network address translation section for more details. The Masquerade option is only available in the Network address translation table, in the Packets after routing chain.

• Source NAT Similar to the Masquerade option, but better suited to systems that have a fixed Internet IP address. If selected, you can use the IPs and ports for SNAT field to control which addresses and ports are used for NAT, as explained in the â��Setting up network address translationâ�� section. This option is only available in the Network address translation table, in the Packets after routing chain.

• Destination NAT Matching packets will have their destination address and port modified based on the IPs and ports for DNAT field. This is the basis for transparent proxying, so to learn more see the Setting up a transparent proxy section below. This action is only available in the Network address translation table, in the Packets before routing and Output chains.

• Redirect This action redirects all matching packets to a port or ports on the firewall box, specified by the Target ports for redirect field. It can also be used for transparent proxying, although destination NAT is more flexible. The redirect action is only available in the Network address translation table, in the Packets before routing and Output chains.

You can also choose the Run chain option for the Action to take, which will pass the packet on to the user-defined chain or custom target entered into the field next to it. See the *Creating your own chain* section below for more information on user-defined chains. Some of the targets available are LOG (for logging packets to syslog), MIRROR (for reflecting packets back to their sender) and MARK (for marking a packet for later conditions).

For each condition, the options Ignored, Equals and *Does not equal* can be selected. The first means that the condition is not used at all when checking if a packet matches the rule. The second means that a packet must match the condition for it to match the entire rule, and the third means that the packet must NOT match the condition for the rule to be executed. If for example the *Incoming interface condition was set to *Does not equal and eth0 selected, the rule would match only packets coming in on any interface except the primary Ethernet card.

Because almost all network protocols involve traffic flowing in two directions, attempting to block just incoming traffic from some address using the Source address or network condition will also block connections to the address as well, because reply packets that are part of the connection will be dropped. The same goes for blocking incoming data on a particular port using the Destination TCP or UDP port condition – if in the unlikely case the randomly chosen source port of a connection from your system matches the blocked port, any replies to it will be dropped. For these reasons, it is usually a good idea when creating deny rules to set the Connection state condition to Does not equal and select Existing connection from menu next to it. This will cause IPtables to keep track of outgoing connections made by your server, and not block them.

As you can see, there are many different conditions available which can be combined to create quite complex rules. To learn more about what each of the available conditions do, see the *Firewall rule conditions* section below. Because there are so many conditions, Webmin allows you to create new rules that are almost identical to existing ones. To do this, click on an existing rule to edit it and use the Clone rule button at the bottom of the page to go to the rule creation form with all conditions and actions set based on the original rule.

Changing a chain’s default action

Packets that do not match any rule in a chain will be processed using the default action, which is usually to accept the packet. On the module’s main page, the default action for each chain is shown next to the Set default action to button. To change it, the steps to follow are :

1. Select the new action from the menu next to the Set default action to button. Only the Accept, Drop, Userspace and Exit chain actions are available – see the Allowing and denying network traffic section above for their meanins. Typically, only Allow and Drop make sense as a default action.
2. Click the Set default action to button to save the new default.
3. If changing to Drop, add any additional firewall rules needed so that your system can still access other servers and supply important services.
4. When done, click the Apply Configuration button to make the new default active.

Just changing the default action to Drop for incoming packets is an easy way to totally cut your system off from the network, and possibly make it unusable. Before you do so, make sure you allow at least the following kinds of traffic :

• All established connections. Create an Allow rule with the Connection state set to Equals and Existing connection chosen.

• Connections related to those that are established, such as FTP data connections. Create an Allow rule with the Connection state set to Equals and Related connection chosen.

• All traffic on the loopback interface. Create an Allow rule with Incoming interface set to Equals and lo chosen.

• Traffic from your system to itself on its primary network interfaces. For each interface create an Allow rule with both the Source address or network and Destination address or network set to the interface IP address.

• Safe ICMP types. Create four Allow rules with the ICMP packet type set to Equals and echo-reply, destination-unreachable, source-quench and time-exceeded chosen.

Changing the default action for forwarded packets to Drop will not cause as many problems – it will just be the equivalent of turning off forwarding altogether. Changing the default action for outgoing packets to Drop is a bad idea as it will cut off all network access, and probably makes very little sense in most cases.

Editing firewall rules

Webmin can be used to edit any of the existing firewall rules that have been created manually, in another program or using this module. Even though the module does not support all of the available IPtables condition and action options, you can still use it to safely edit rules containing unknown options. Only those known to Webmin can be changed, and others will be left untouched.

To edit a rule, the steps to follow are :

1. On the main page of the module, select the table the rule is in from the list next to be Showing IPtable button before clicking it.
2. Click on the action of the rule you wish to change in the table for its chain. This will take you to an editing form, which is identical to the creation form shown in Figure 19-3.
3. Change the action or any of the conditions, and click the Save button to return to the list of chains and rules. Or to delete the rule altogether, click the Delete button.
4. To make the changes active, click on Apply Configuration.

Rules can be moved up and down within their chain using the arrows under the Move column on the main page. Because rules are evaluated in order by the firewall, changing their ordering can effect which traffic is allowed or denied. Whenever you create a new rule, it will be added to the end of its chain, so it may be necessary to move it up the correct position to get the desired effect.

Creating your own chain

It is possible to create your own custom chains of rules in addition to the standard ones. The difference is, they will only be executed if a rule in one of the standard chains has its action set to explicitly jump to a custom chain. When execution of a custom chain finishes (or a rule with the Exit chain action is matched), evaluation will return to the calling chain. This means that custom chains can be used to define rules that are shared by several standard chains, instead of repeating the same rules in multiple places. In a way, a custom chain is like a subroutine in a programming language.

To create your own chain, the steps to follow are :

1. On the main page of the module, select the table you want the chain to be in from the menu next to Showing IPtable, and click the button. Custom chains can only be called from other chains in the same table.
2. Enter the name of your new chain into the text box next to the Add a new chain named button, and then click the button to create it. Chain names must be unique, and are generally composed of only lower-case letters and numbers.
3. Once the new chain has been created, it will appear at the bottom of the page. You can use its Add rule button to append rules to it, just as with one of the normal chains.

Custom chains do not have a default policy, so they have no *Set default action to* button on the main page. If execution of the chain reaches the end, control will always return to the caller. Custom chains can be deleted though, using the Delete chain button underneath their tables of rules.

A custom chain can contain rules that jump to other custom chains. However, a chain cannot jump to itself, nor can you create loops by jumping to another chain the jumps back to the first. Even if this were possible, it would be a very bad idea!

Setting up network address translation

If you have several systems in your home or office connected by a LAN and only one Internet IP address, network address translation can be used to give all those systems almost complete Internet access. NAT hides the addresses of all systems on the internal LAN behind a single Internet address, converting addresses and ports back and forth as needed. This allows all internal systems to make connections to any host on the Internet, such as web servers, DNS servers, POP3 servers and so on. The only limitation is that internal systems cannot receive connections from other Internet hosts, which can cause some protocols (such as Internet telephony and network games) to fail.

Because of this limitation, internal systems are protected from most attacks from other hosts on the Internet, just as if you were to block all forwarded packets coming in on the external interface. NAT also makes IP address assignment easier, as there is no need to worry about running out of real Internet addresses to assign to internal hosts that do not really need then. For these reasons, it may make sense to set up NAT in your organization even it is not totally necessary from a networking point of view.

NAT works by modifying the source address and port of packets sent by internal hosts and routed through the firewall. The source address is always changed to the external IP address of the firewall system, and the source port to a randomly chosen unused port. When a reply packet comes back, its destination port is used to determine the original internal client IP address and port to which the packet should be forwarded.

To set up NAT, all you really need is a system with two network interfaces – one for the internal LAN, and one that is connected to the Internet via dial-up, ISDN or broadband. Once you have this, the steps to follow are :

1. On the internal LAN, every system’s Ethernet interface should be assigned an address on a private IP network such as 192.168.0.0, including the gateway system.
2. Set the default router on all internal systems to the LAN IP address of the gateway system.
3. Make sure that the gateway has IP forwarding enabled in the Network Configuration module under Routing and Gateways. See NetworkConfiguration for more information on how to do this.
4. On the main page of the Linux Firewall module on the gateway system, select Network address translation from the list next to the Showing IPtable button. Then click the button to display chains in the NAT table.
5. Click the Add rule button in the Packets after routing section, which will take you to the rule creation form.
6. Set the Action to take to Masquerade.
7. To control which ports the firewall will use for masqueraded connections, set the Source ports for masquerading option to Port range and enter starting and ending port numbers into the fields next to it. Usually just selecting Any to let the firewall use any available port will work fine.
8. Change the Outgoing interface condition to Equals and select the external network interface from the list next to it, such as ppp0.
9. Click the Save button at the bottom of the page to return to the list of chains and rules.
10. Click on Apply Configuration to make the new rule (and NAT) active.

It is possible to combine NAT with other firewall rules in the Packet filtering table to block connections to the firewall host itself. You can also prepend deny rules to the *Packets after routing* chain to stop certain internal hosts from accessing the Internet, or limit the ports to which they can connect.

The instructions above will work on any network that has a gateway system with a single Internet IP address. However, if your gateway’s address is static it is better to select Source NAT in step 6 instead of Masquerade. When using masquerading, any connections being forwarded by the firewall will be lost if the external network interface goes down, even if it comes back up again with the same IP address. If the external interface has a dynamically assigned address, this doesn’t matter as the connections would be lost anyway. But when using a static IP address, it is possible for a connection to be maintained even through a short network outage.

To use it, in step 6 set the Action to take to Source NAT. Then set the IPs and ports for SNAT to IP range and enter your system’s static external IP address into the field next to it. All other steps in the NAT setup process are the same.

Setting up a transparent proxy

Many networks use proxy servers like Squid to cache commonly accessed websites and thus cut down on the amount of bandwidth used by web browsing clients. However, normally each client must be configured to use the proxy server instead of making direct connections to websites. On a large network with many clients systems or at an ISP where they are owned by many different people, this individual configuration can be difficult. It is made worse by each browser having its own proxy server settings, so if a user installs a new browser it will probably default to not using a proxy at all.

Fortunately, there is a solution – transparent proxying. If all client systems access the Internet through a gateway running an IPtables firewall, it can be configured to re-direct connections to port 80 (used by most websites) to a proxy server on the some other system. This means that clients do not need to be configured to access a proxy, as any HTTP requests that they make will be transparently sent to the proxy server without their knowledge.

To set up transparent proxying, the steps to follow are :

1. On the main page of the Linux Firewall module on the gateway system, select Network address translation from the list next to the Showing IPtable button before clicking it.
2. In the Packets before routing section, click on Add rule to go to the rule creation form. The rule being added will redirect all traffic on port 80 forwarded by the firewall system to a proxy server.
3. Set the Action to take to Destination NAT.
4. In the IPs and ports for DNAT field, select IP range and enter the address of the proxy server system into the field next to it. If the proxy is running on the same system, enter its Ethernet IP address (not 127.0.0.1). In the field next to Port range, enter the port the proxy server is running on, such as 8080.
5. Set the Incoming interface to Equals and select the internal LAN interface, such as eth0.
6. Set the Network protocol to Equals and select TCP.
7. If the proxy is on another system that is also on the internal LAN, make sure that its connections on port 80 will not be proxied by the firewall as well! To do this, set the Source address or network condition to Does not equal and enter the IP address of the proxy server into the field next to it. If the proxy is on a different LAN or is the firewall system, this is not necessary.
8. Set the Destination TCP or UDP port to Equals and enter 80 into the Port(s) field.
9. Click the Create button to save the rule and return to the module’s main page.
10. Click on Add rule under Packets after routing to bring up the rule creation form again. This rule will forward packets back in the other direction from the proxy to the client. If your firewall system is also running the proxy server, this rule is not necessary and you can skip to step 16.
11. For the Action to take, select Source NAT.
12. In the IPs and ports for SNAT field, select IP range and enter the LAN IP address of the firewall server into the field next to it.
13. Set the Destination address or network to Equals and enter the IP address of the proxy server into the field next to it.
14. Set the Network protocol to Equals and select TCP.
15. Click the Create button to add the new rule.
16. Back on the main page, click the Apply Configuration button. All packets on port 80 forwarded by your firewall will now be sent to the proxy server instead.
17. Assuming you are running the Squid proxy server (version
18. 4 or above) on the proxy system, you can use Webmin to configure it. Otherwise, there is no point reading beyond this step.
19. On the proxy system, enter the Squid Proxy Server module and click on Miscellaneous Options.
20. Set the HTTP Accel Host field to Virtual, and the HTTP Accel Port to 80.
21. Set both the HTTP Accel With Proxy and HTTP Accel Uses Host Header fields to Yes.
22. Finally, click Save to return to the main page of the Squid module, and click the Apply Changes link near the top of the page to activate the new configuration.

From now on, any HTTP requests on port 80 forwarded by your firewall will be sent to the proxy server for processing. Transparent proxying can be safely used at the same time as conventional NAT by creating a masquerade rule in the packets after routing chain, as explained in the instructions in the *Setting up network address translation* section above.

Setting up port forwarding

On a network that uses NAT to hide internal systems from the Internet, outside hosts cannot connect directly those on the internal network. This is great for security, but can be annoying if there is some internal service that you do want to make available to the outside world. For example, your mail server system may not be the firewall host, which would normal make it inaccessible from the Internet. Fortunately, there is a solution to this problem – port forwarding.

This lets you re-direct all connections to some port on the firewall system to a different host and port on your internal network. For a mail server, all data received on port 25 might be send to the same port on the host that is actually being used to host user email. Of course, this would make it impossible for your firewall system to receive email itself.

To set up port forwarding, follow these steps :

1. On the main page of the Linux Firewall module on the gateway system, select Network address translation from the list next to the Showing IPtable button before clicking it.
2. In the Packets before routing section, click on Add rule to go to the rule creation form. The rule being added will redirect all external traffic received by the firewall to some internal address.
3. Set the Action to take to Destination NAT.
4. In the IPs and ports for DNAT field, select IP range and enter the address of the internal host into the adjacent text box, such as 192.168.1.10. In the Port range box, enter the port number on the internal host to which data should be sent, such as 25 for SMTP, 110 for POP3 or 80 for HTTP.
5. Set the Network protocol to Equals and select TCP.
6. In the Destination TCP or UDP port field, select Equals from the menu and enter the external port number for which forwarding should be done into the adjacent text field. Typically this will be the same as the port entered in step 4.
7. Hit the Save button to create the rule and return to the main page, and then click the Apply Configuration button.

The only problem with this method is that connections from inside your network to the firewall system will not be forwarded to the other host.

Firewall rule conditions

When creating a firewall rule, you can select many different conditions to control which packets the rule matches. A rule’s action will only be executed if all the conditions are matched. Each condition can be in one of three states, chosen by the menu next to it on the rule creation form :

• Ignore The condition will be totally ignored when deciding whether the rule matches or not.

• Equals The rule will only match if the packet matches the address, port, interface or whatever was selected for this condition.

• Does not equal The rule will only match if the packet does NOT match whatever was selected for this condition.

The available conditions and what each matches are listed in the table below. Note that some are not available in all tables and chains.

Remember that each condition is applied on a per-packet basis, and that a single TCP connection may involve multiple packets flowing in both directions.

Apache virtual hosts seting

source: https://help.ubuntu.com/community/ApacheMySQLPHP

# sudo tasksel install lamp-server

or

#sudo apt-get install drupal

Virtual Hosts

Apache2 has the concept of sites, which are separate configuration files that Apache2 will read. These are available in /etc/apache2/sites-available. By default, there is one site available called default this is what you will see when you browse to http://localhost or http://127.0.0.1. You can have many different site configurations available, and activate only those that you need.

As an example, we want the default site to be /home/user/public_html/. To do this, we must create a new site and then enable it in Apache2.

To create a new site:

• Copy the default website as a starting point. 
• sudo cp /etc/apache2/sites-available/default-ssl /etc/apache2/sites-available/mysite
• Edit the new configuration file in a text editor “sudo nano” on the command line or “gksudo gedit”, for example:
• gksudo gedit /etc/apache2/sites-available/mysite
• Change the DocumentRoot to point to the new location. For example, /home/user/public_html/
• Change the Directory directive, replace <Directory /var/www/> to <Directory /home/user/public_html/>
• You can also set separate logs for each site. To do this, change the ErrorLog and CustomLog directives. This is optional, but handy if you have many sites
• Save the file

Now, we must deactivate the old site, and activate our new one. Ubuntu provides two small utilities that take care of this: a2ensite (apache2enable site) and a2dissite (apache2disable site).

sudo a2dissite default-ssl && sudo a2ensite mysite

Finally, we restart Apache2:

sudo /etc/init.d/apache2 restart

If you have not created /home/user/public_html/, you will receive an warning message

To test the new site, create a file in /home/user/public_html/:

echo '<b>Hello! It is working!</b>' > /home/user/public_html/index.html

Finally, browse to http://localhost/

phpMyAdmin

source: https://help.ubuntu.com/community/phpMyAdmin

Introduction

phpMyAdmin is a very famous MySQL mangement software package. To use it you should install and configure PHP, Apache and php mysql (or mysqli) extension see ApacheMySQLPHP for instructions.

# sudo tasksel install lamp-server

or

#sudo apt-get install drupal wordress

Installing

Install phpMyAdmin from the Universe repository see InstallingSoftware for detailed instructions on using repositories and package managers.

From console:

sudo apt-get install phpmyadmin

• If you’re using Ubuntu 7.10 (Gutsy) or later select Apache2 from the “Configuring phpmyadmin” dialog box.

To set up under Apache all you need to do is include the following line in /etc/apache2/apache2.conf.

Include /etc/phpmyadmin/apache.conf

Once phpMyAdmin is installed point your browser to http://localhost/phpmyadmin to start using it. You should be able to login using any users you’ve setup in MySQL.

Apache Webserver Configuration -Webmin

source: http://doxfer.com/Webmin/ApacheWebserver

This page explains how to use Webmin to configure the Apache webserver. It covers virtual hosts, IP access control, password restrictions and much more.

Introduction to Apache

Apache is the Internet’s most popular HTTP server, due to its zero cost, wide availability and large feature set. All Linux distributions include it as a standard package, and it can be installed on or compiled for every other Unix variant supported by Webmin. However, it has a very large number of option directives defined in a text configuration file, and so can be hard for an inexperienced administrator to set up.

Over the years since it was first introduced, many versions of Apache have been released. Starting with 1.0 and moving through to the current 1.3 and 2.2 series, each version has included more features and options. The basic webserving functionality and configuration file layout has remained essentially the same throughout, even though the internal implementation has changed significantly.

Apache has a modular design, in which each module is responsible for some part of its overall feature set. There are several standard modules that are included with almost every install of Apache, and many more that are optional or have to be downloaded separately. Modules can be compiled into the webserver executable, or dynamically loaded from shared libraries at run time. This modular architecture can be used to save memory by avoiding the need to load modules that do not provide any useful functionality for a particular system.

Apache takes its configuration from multiple text files, each of which contains a series of directives, usually one per line. Each directive has a name and one or more values, and sets an option such as the path to a log file or the MIME type for some file. The directives that Apache recognizes are dependant on the modules in use. Most modules add support for several directives to configure the functions they provide.

Often, you will want to host more that one website on a single server. Apache can be configured to use a different configuration depending on the web site that was requested by a browser. Each one of these sites is called a virtual host, and is defined in the configuration file with a special <Virtualhost> section. All directives inside this virtual host section apply only to requests that match its IP address or hostname.

Similarly, <Directory> and <Files> sections can be defined in the configuration file to contain directives that apply to only a certain directory or to files matching some pattern. These are often used to deny access to certain files on your system, to password protect them, or to control the way that they are displayed to clients.

Another method of creating directives that apply to only to a single directory is to put them in a special configuration file named .htaccess that resides in the directory itself. Often these files will be created by regular users, so that they can configure their own websites without needing full access to the master configuration file. This is very useful on a system that hosts multiple sites that are each owned by a different Unix user, rather than on a system with only one website that is set up by the server’s owner.

The Apache Webserver module

This is one of the most complex and powerful Webmin modules, as it allows you to configure almost every feature of Apache. It can determine the version of Apache that is installed on your system and the modules that it uses, and adjusts its user interface accordingly so that you can edit only those directives that the webserver understands. However, the interface is generally the same for all versions of Apache.

Because there are so many directives and the module attempts to allow configuration of all of them, it groups directives into categories like Processes and Limits, Networking and Addresses and CGI Programs. These categories are represented by icons that will appear when you open a virtual server, directory or options file in the module. In all cases, you can view and edit the settings under each category by clicking on its icon.

Apache has a large number of standard modules, and an even larger number of separate modules that were developed by other people. Webmin does not support the editing of directives in most of these non-standard, such as mod_perl and mod_php. However, it will safely ignore any configuration file directive that it does not understand, so that any settings for unsupported modules that you make manually will not be harmed.

When you open the Apache module, the tabbed page shown below will be displayed :

The Apache Webserver module main page

In the first tab are icons for the various categories of global options, as well as a few extra features. In the second is a list of all current virtual servers, and in the third is a form for adding a new virtual host. If you have a very large number of virtual servers on your system (more than 100 by default) a search form for finding servers will be displayed instead. The first server will always be the special Default Server, which contains directives that apply to all other virtual servers and handles requests that other servers do not.

Naturally, the Apache module will not work if you do not have Apache installed on your system. If this is the case, the main page will display an error message instead of the module configuration form or list of virtual servers. All Linux distributions include a package or packages for it on their CD-ROM or website, so install it from there using the Software Packages module (covered in SoftwarePackages) before continuing.

Because the module assumes that the Apache executable and configuration files will be in the locations used by your distribution’s package, it will report the same error about the software not being installed if you have compiled and installed it manually. If this is the case, click on the Module Config link and adjust the paths to the correct locations for your system.

On versions of Unix that do not include Apache by default, Webmin assumes that it will be installed from the standard source distribution from http://www.apache.org. If you have installed the webserver from an optional package that has been made available for your OS, then the main page will complain that it is not installed and you will need to adjust the module configuration.

The module’s user interface is quite complex and has a large number of pages, forms and sub-pages due to the complexity and power of the Apache configuration files. However, there are elements of the interface that are repeated on many pages throughout the module, such as :

• Category icons When you click on the icon for a virtual server, directory or options file, a table of icons with names like MIME Types and CGI Programs is displayed at the top of the page. Under each of these icons are fields and tables for configuring options related to the label of the icon they are under. This commonly used layout breaks down the vast number of editable Apache options into categories, as there are far too many fields to display on a single page. The exact icons that appear and the fields under them differ depending on the part of the webserver configuration you are editing, and the version of Apache that is installed. However, their basic layout is always the same.

• Tables fields On many forms, some fields use tables for entering multiple values such as MIME types and their associated file extensions. There is no limit on how many rows each table can have, but Webmin will only display a single empty row in each table at any one time. This keeps down the size of forms that have lots of tables, but means that you can only add one new row to a table at a time. To add more than one, you will need to save the form and then re-enter it again, which will cause a new blank row to be displayed below the one you just filled in.

The sections below explain in more detail exactly which icons to click and which tables to fill in when doing things like enabling CGI scripts and setting MIME types.

Starting and stopping Apache

Before browsers can connect to the Apache webserver on your system, its server process must be started. You can check if it is currently running by looking at the top of any of the pages in the module. If links labelled Apply Changes and Stop Apache appear, then it is currently active. However, if only the link *Start Apache* appears them it is not yet running.

To start it, click the Start Apache link. If all goes well, the page that you are currently on will be re-displayed and the links at the top should change to indicate that it is now running. Otherwise, an error message will appear explaining what went wrong – most likely the cause will be an error in the configuration file.

To stop the webserver once it is running, click the Stop Apache link on any of the module’s page. In the unlikely event that Webmin is unable to stop the server, an error message page will be shown. If it is stopped successfully, the same page will re-displayed with the links at the top changed to show that it is no longer running.

When Apache is active, every page will have an Apply Changes link at the top that can be used to signal the webserver to re-load its current configuration. After you make any changes in this module (except those in .htaccess files), this link must be clicked to make them active. Unlike other Webmin modules that have an Apply button on the main page, this one has it on every page so that you do not have to return to the index every time you make a change.

Editing pages on your webserver

This section explains how to find and edit the files on your system that are displayed when a client connects to your Apache webserver. If you already know how to do this, feel free to skip it and move on to the next section.

When Apache is first installed from a package or from source, its initial configuration will typically not have any virtual servers set up. Instead just the default server will exist, serving pages to any client that connects on port 80. You can view the default pages by running a web browser and going to the URL http://_yourhostname_/ , or http://_localhost_/ if you are running the browser on the same system that Webmin is on. The page that appears will probably just be one supplied with Apache or your Linux distribution.

The document root directory that Apache serves files out of will be shown on the module’s main page next to the Default Server icon. On Redhat Linux for example, this directory is /home/httpd/html by default. The files in this directory can be edited by logging in as root, or by using Webmin’s File Manager module. Any changes that you make will be immediately reflected on the website.

If your system is just going to host a single static website, it may not be necessary to configure any other aspects of Apache. You can just upload or copy HTML, image and other files to the directory and its subdirectories to create the site that you want. The most important file is index.html, which is served by Apache whenever a browser does not request a specific page. Because most people will go to http://_yourserver_/ first, the index.html page will be the first one that they see.

To make editing easier, you may want to change the ownership of the document root directory and all its files to a non-root user. However, you must make sure that they are still readable by the user that the Apache server process runs as, which is typically named httpd. The easiest way to do this is to make all files and directories world-readable and world-executable.

Creating a new virtual host

If you want to host multiple websites on your system, then you will need to create an Apache virtual host for each one. Before you can add a site, its address must first be registered in the DNS, either on a DNS server on your system or on another host. If the site’s files are to be owned by a different Unix user to the one who owns the document root directory, then he must be created first as well.

The entire process for adding a virtual server, including the above steps, is :

1. Decide on a hostname that will be used in the URL for the new website, such as http://www.example.com.
2. Decide if your new site is going to be IP-based, or name-based. A name-based site will work fine with all except for old browsers, and so is by far the best choice these days. An IP-based site will work with any browser, but needs its own separate IP address to be added to your system. Because IP addresses are often scarce, this only makes sense if you need to set up a virtual FTP or POP3 server for the domain as well.
3. If your site is going to be IP-based, use the Network Configuration module (covered on NetworkConfiguration) to add a new virtual IP address to the external network interface on your system. Make sure that it will be activated at boot time and is active now. If your system has only a single static internet IP address assigned by your ISP, then any extra virtual IP addresses that you add to it will not work. In that case, you will have to use a name-based virtual server instead, or request that your ISP assign you multiple addresses.
4. If the example.com domain already exists on a DNS server, add a record for http://www.example.com with the external IP address of your system (for a name-based site) or the address chosen in the previous step (for an IP-based site). If the domain does not yet exist, you will need to add it to a DNS server and register it with a DNS registrar like Network Solutions. Either way, the BINDDNSServer page explains how to add records and domains in detail.
5. If the site is going to use the standard HTTP port 80 (which is almost always what you want), then you can skip to step 8. Otherwise, on the Apache Webserver module’s main page click on the Networking and Addresses icon to bring up the form shown in the first screenshot below.
6. In the empty row in the Listen on addresses and ports table, select All under the Address column and de-select Default under the Port column. Then enter the TCP port number for your website into the field next to it, and click the Save button at the bottom of the page.
7. On the module’s main page, scroll down to the Create a New Virtual Server form below the list of existing virtual hosts.
8. If you are setting up an IP-based virtual server, in the Address field you should enter the virtual IP address that was added in step 3. If setting up a name-based virtual server, enter the external IP address of your system into the field instead. If your Apache server has been configured to accept name-based connections on any IP address, you can select the Any option for this field instead. See the explanation below for more details. If your new virtual server is going to use a port other than 80 and will be the only server on that port, you can select the Any option as well so that it handles all requests that come in on the port.
9. If you are setting up an IP-based virtual server, de-select the Add name virtual server address checkbox. For name-based servers, it should be left enabled.
10. If the new virtual host is going to use a non-standard port, select the last option for the Port field and enter the number into the field next to it.
11. In the Document Root field, enter the full path to the directory that will contain files for this website. For example, this might be /home/example/www.
12. In the Server Name field, enter the hostnames that clients will use to refer to this website such as http://www.example.com. You can enter more than one name, such as web.example.com and example.com if this is going to be a name-based server that should be accessible at several different URLs.
13. Unless you have a separate file on your system that contains all virtual hosts, leave the Add virtual server to file field set to Standard httpd.conf file. Otherwise you can choose Selected file and enter the path into the field next to it. Make sure that the chosen file is actually used by Apache (such as by an Include directive in httpd.conf) or the virtual server will be useless and will not appear in Webmin. If you always use the same separate file for storing virtual hosts, the File to add virtual servers to field explained in the Configuring the Apache Webserver module section below may be useful. If it is set, another option is add to the Add virtual server to file field for adding to the file set by this module configuration option.
14. To have Webmin copy all of the directives from another virtual server to the one that you are creating, select it from the Copy directives from menu. This can be useful if all of your virtual hosts have a similar configuration.
15. When you are done filling in the form, click the Create button. The new virtual server will be added to the Apache configuration file and to the list of servers on the main page.
16. Click on the icon for the new virtual server, which will take you to its options page, shown in the second screenshot below.
17. Scroll down to the form under Per-Directory Options, and enter the document root directory that you chose in step 11 into the Path field. Make sure the Type is set to Directory, and the Regexp? field to Exact match.
18. Click the Create button to add a new section to the configuration file for the directory. This is necessary so that you can grant clients the rights to browse files that it contains, which the default Apache directory configuration denies.
19. Click on the new icon for the directory that has been added to the virtual server options page. This will take you to the directory options page, shown in the third screenshot below.
20. Click on the Document Options icon, and on the form that appears change the Directory options field to Selected below. Under the Set for directory column, change the entry for Generate directory indexes to Yes. Then click the Save button at the bottom of the page.
21. To make all your changes active, click the Apply Changes button at the top of any page.
22. You or the user who owns the virtual server can now start adding files to the document root directory. You can test it out by opening the URL (such as http://_www.example.com_/) in your web browser to make sure that everything is working properly.

The global networking and addresses page

The virtual server options page

The directory options page

When Apache receives an HTTP request, it must first work out which virtual server the request is for. It will first look for a name-based virtual server whose hostname matches the host requested by the client, and whose address and port are the same as the ones that the client connected to. If none is found, the first defined virtual server for the address and port will be used instead, or if there are none then the request will be handled by the default server.

Name-based virtual servers can only be used on addresses listed in the Addresses for name virtual servers field on the global Networking and Addresses page. If you follow the instructions above, an address will be added to this list automatically when you create a new virtual server. If all the virtual servers on your system are going to be name-based, you can open this page, enter * into the field and click Save so that Apache will handle such requests on any IP address. This also makes sense if you system has a dynamically assigned IP address and you want to serve multiple virtual hosts.

Once a virtual server has been created, you can edit its settings or delete it by following these steps :

1. On the module’s main page, click on the virtual server’s icon. This will take you to the server options page shown in screenshot above.
2. Scroll down to the Virtual Server Details form at the bottom of the page.
3. Change the Address, Port and other fields to whatever you want and click the Save button. These fields have the same meanings as on the virtual server creation form. However, if the address is changed on a name-based virtual server you may need to change it on the global Networking and Addresses page as well. Or if you want to get rid of the virtual server and all the configuration directives that it contains, click the Delete Virtual Server button instead.
4. Back on the module’s main page, click on the Apply Changes link to make the new settings active.

You cannot change the settings for the default server, nor can you delete it.

Setting per-directory options

Apache allows you to specify different options for certain directories, either for all virtual servers or just to a single one. Including directories, you can actually set options that apply to three types of object on your Apache server :

• Directory The options apply to a specified directory and all files in it or in sub-directories that it contains.

• Files The options apply to files with a specified name in any directory.

• Location The options apply to any files or directories requested by a URL whose path starts with the specified location. For example, in the URL http://www.example.com/foo the path would be /foo.

Whenever Apache processes a request, it checks for the options that apply to it in a fixed order. Those from directory sections and .htaccess files are read first ordered so that the most specific directories are checked first. They are then followed by files and then location sections. Then options from the virtual server that the request was made to (if any) are read, and finally options from the default server.

This means that options set for a directory will override the same options set in a higher level directory, or in the virtual server that it is a member of. To set options for a directory, files or URL location the steps to follow are :

1. Even though the options you are going to set apply to a directory, they must be defined under one of the virtual servers or the default server. If they are under a virtual host, then they will apply only to requests to that server for files in the chosen directory or URL location. But if they are under the default server, requests to any virtual host for files in the directory will be effected. On the module’s main page, click on either the Default Server icon or the icon for a virtual server that you want the directory options to be limited to. For directories, it is usually simplest to put their options under the default server as each virtual host typically has its own separate document root directory. URL location options however should be put under the virtual server that they are related to, because the same URL path may be used in different ways on more than one virtual host. The same goes for file options.
2. On the server options page that appears (shown in Figure 29-4), scroll down to the Create Per-Directory, Files or Location Options form.
3. From the Type menu, choose one of the options described above.
4. If you are setting options for a directory, enter it into the Path field such /home/example/www/images. You can also enter a wildcard path such as /home/example/w*, which will cause the options to apply to all directories that match. If the options are being set for a URL location, enter the part of the URL after the hostname into the Path field, such as /images. You can also use shell wildcard characters like * and ? in the URL as well. If setting options for files, enter a filename into the Path field such as secret.html. Once again, wildcard characters can be used in the filename, for example secret*.
5. If you want to be able to used complex regular expressions in the directory, filename or URL location, set the Regexp? field to Match regexp. This will allow you to use Perl regular expression characters like [, ], +, . and * in the path.
6. Click the Create button to add the new directory section to the Apache configuration. The virtual server options page will be displayed again, but with a new icon for the directory.

Now that you have created a new icon for a directory, URL location or filename, you can set options that apply to it. One of the most common per-directory changes is configuring how files are listed when a browser requests a directory with a URL like http://www.example.com/images/. By default, if there is an index.html file in the directory it will be displayed, or if not a page listing all files that it contains will be shown instead.

If you want to change the name of the index file, the style of the directory listing or any other settings related to indexing, the steps to follow are :

1. Click on the icon for the directory that you want to configure on the virtual server options page. This will take you to the directory options page shown in Figure 29-5.
2. Click on the Directory Indexing icon to bring up a form for setting indexing and listing options.
3. To change the appearance of directory listings, set the Directory index options field to Selected below and change the fields in the box below it. The defaults will generate a very plain list of files, but you can enhance it by setting the following options :
   • Display fancy directory indexes If enabled, the list of files will include their icon, size and modification date.
   • Display HTML title as description If enabled, the description for HTML files will be taken from their <title> tags.
   • Icon height This option allows you to change the height of icons included in the directory listing. If it is set to Default, the height of the standard Apache options will be used.
   • Icon width Like the previous option, this one allows you to specify the width of icons in the directory listing.
   • Allow user sorting of column When this is enabled users will be able to sort the list of files by clicking on the column headings, assuming they are being displayed.
   • Show file descriptions If enabled, the directory listing will include a description for each file taken from its MIME type or HTML title.
   • Output HTML header tags When enabled, the directory listing will include the normal <html> and <head> tags that should begin every HTML page. You would only want to turn it off if providing your own header and footer files.
   • Show last modified times When enabled, the directory listing will include the last modified date for each file.
   • Show file sizes When enabled, the listing will include the size of each file.
   • Include icon in link If this option is enabled, the icon in the listing will be a link to the file itself. Otherwise only the filename is a link.
   • Filename width This option controls the length of the filename column in the directory listing. You can either enter a number of characters or * to size the column to the length of the longest filename.
   • Description width This option controls the length of the description column in the directory listing, if any. You can either enter a number of characters or * to size the column to the length of the longest description.
   • Display directories first If enabled, the listing will show any directories above any files regardless of any other files. The options that are available depend on the version of Apache that you have installed on your system. Those listed above are valid for version 1.3.19, but if you have a newer release more options may be available.
4. If you want Apache to return a file other than the default (usually index.html) when a browser requests the directory, enter a list of filenames into the Directory index files field. More that one can be entered, and the first that is found will be used. If none of the index files are found a directory listing using the options chosen in step 3 will be returned to the browser instead.
5. To have the webserver ignore certain files when generating the list of files in the directory, enter their filenames into the Files to ignore in directory index field. You can use shell wildcards in the regular expressions, such as *.doc.
6. To have an HTML file inserted at the start of the directory listing, enter its filename (relative to the directory) into the Directory index header file field.
7. Similarly, to have a file added at the end of the directory listing, enter its into the Directory index footer file field.
8. To control the default ordering of the directory, de-select Default in the Sort directory index by field and select an order and column to sort on from the two menus next to it.
9. You can set descriptions for files by filling in the Directory index descriptions table. In the table’s empty row, enter a short message describing the file in the Description column, and a list of filenames or wildcard names in the Filenames column. Because only one empty row is shown at a time, you will need to re-visit this page after adding each description if you want to enter more than one.
10. Finally, click the Save button at the bottom of the page to store your changes and return to the directory options page. To activate them, click the Apply Changes link anywhere in the Apache module.

Most of these options can be set for an entire virtual server by clicking on the Directory Indexing icon on the virtual server options page as well. In this case, they will apply to all files requested from the virtual host unless overridden by options for a directory or URL location.

On the directory options page there are many more icons that you can click on to set options that apply only to that directory, URL path or filename. Some of these are explained in other sections later in this chapter, such as Aliases and redirects and *Password protecting a directory*.

You can change the directory, filenames or URL location that settings apply to using the Options apply to form at the bottom of the directory options page. It has the exact same fields as the creation form described at the start of this section. If you make any changes, click the Save button to update the Apache configuration and then the Apply Changes link to make them active. Or to remove the directory configuration and all its options, click on Delete instead.

Creating aliases and redirects

Normally, there is a direct relationship between the path in URL and the file that is returned by the webserver. For example, if a browser requests http://www.example.com/images/foo.gif and the document root for http://www.example.com is /home/example/www, then the file /home/example/www/images/foo.gif would be read by the webserver and returned to the client.

This can be changed though by using what Apache calls aliases. An alias maps a particular URL path to a file or directory, which does not necessarily have to be under the document root. So in the example above, the /images URL path might actually be aliases to the directory /www/images, which would cause the file /www/images/foo.gif to be read instead.

Aliases can be defined globally or in a virtual server. To create one, the steps to follow are :

1. On the module’s main page, click on the icon for the virtual server that you want to create the alias under. If you want it to apply to all virtual servers (or you don’t have any), click on the *Default Server *icon instead.
2. On the virtual server options page that appears, click on the Aliases and Redirects icon. This will take you to the page in the screenshot below.
3. Fill in the empty row in the Document directory aliases table with the URL path (under From) and the file or directory that it should map to (under To). If you are editing the default server, there may already be several entries in this table that are part of the standard Apache configuration. There will always be exactly one empty row in the table. If you need to add more than one alias, you will need to re-visit this page after filling in the row and saving.
4. Click the Save button to have your new alias stored in the Apache configuration. The browser will return to the virtual server options page.
5. To make the alias active, click on the Apply Changes link at the top of the page.

The aliases and redirects form

Existing aliases can be editing by just changing the entries in the Document directory aliases table and then clicking Save. You should not change the alias for /icons in the default server though, as this is used by Apache when it generates icons for directory listings. If you want to delete an alias, just delete the contents of both its fields in the table.

Aliases can also be created that use Perl regular expressions to match more complex URL paths. These must be entered into the Regexp document directory aliases table on the Aliases and Redirects form, which has the same columns as the *Document directory aliases* table described above. The difference is that any regular expression can be entered into the From field, such as ^/images/(.*)\.gif$. The To field can taken a string that refers to bracketed sections in the expression, such as /images/$1.jpg. This would convert any request for a GIF file into one for the JPEG with the same name.

Redirects are similar to aliases, but have a different purpose and work in a different way. Whenever a client requests a URL path that has been redirected, Apache will tell it to go to another URL (possibly on another server) instead. For example, you might redirect all requests to http://www.example.com/webmin/ to http://www.webmin.com/. Unlike the way aliases behave, if a browser requests a page like /webmin/foo.gif it will not be redirected to http://www.webmin.com/foo.gif – it will just go to the URL http://www.webmin.com/ instead.

Redirects are implemented by the webserver sending the special 302 status code to the browser, which tells it to go to a new location. It is quite possible for the new URL to be a redirect itself, and you can even create a loop of redirects – not that this is a good idea.

To set up redirection for a path on your server, the steps to follow are :

1. On the module’s main page, click on the icon for the virtual server that you want to create the redirect under. If you want it to apply to all virtual servers, click on the *Default Server *icon instead.
2. On the virtual server options page that appears, click on the Aliases and Redirects icon to go to the page in Figure 29-6.
3. In the empty row of the URL redirects *table, enter the URL path on your server under the *From column, such as /webmin. Under the To column, enter the URL that requests should be redirected to, such as http://www.webmin.com/. The Status field is optional, but can be filled in if you want to change the HTTP status code that will be used for this redirect. The default is 302, which indicates a temporary redirection. However, you can 301 to tell browsers that the direction is permanent, or 303 to tell them that the original content has been replaced. There will always be exactly one empty row in the table. If you need to add more than one redirect, you will need to re-visit this page after filling in the row and saving.
4. Click the Save button to have your new redirect stored in the Apache configuration. The browser will return to the virtual server options page.
5. To make the redirection active, click on the Apply Changes link at the top of the page.

As with aliases, existing redirects can be edited by just changing the entries in the URL redirects table and then clicking Save. To delete a redirect, just delete the contents of all of its fields in the table.

You can also create regular expression redirects that behave in a similar way to regexp aliases, using the Regexp URL redirects table on the same page. Under the From column you can enter a URL path expression such as ^/webmin/(.*)$, and under the To column a URL that can refer to bracketed parts of the path, such as http://www.webmin.com/$1. In this example, an request by a client for a page under /webmin would be redirected to the same file at http://www.webmin.com.

Also on the Aliases and Redirects page are two more tables labelled Permanent URL redirects and Temporary URL redirects. The first behaves exactly the same as a normal redirection, but with the status code always set to 301, indicating a permanent redirection. The second also behaves like a normal redirect, but always uses a status code of 302 (temporary redirection). This option is really quite useless, as normal redirections default to using status 302 if one is not specified.

Redirects can also be defined in the options for directories, URL locations, filenames and .htaccess files. When editing the options for one of these (described in the *Setting per-directory options* section), the exact same icon and table are available as when setting up aliases for a virtual server. Naturally, a redirect in a directory only makes sense if the URL path being redirected actually refers to that some file or sub-directory that it contains. The same goes for redirects in URL locations – the path being redirected must start with the location’s path.

If Apache on your system has been compiled with or dynamically loads the proxy module (covered in the *Configuring Apache as a proxy server* section below), tables labelled *Map locale to remote URLs* and Map remote Location: headers to local will appear on the Aliases and Redirects form under the virtual server options page. These allow you to specify a URL path that when requested will cause Apache to itself request pages from another website and return them to the browser. Even though the URL that the user is accessing is on your server and their browser is connecting only to your system, the content is actually being loaded from elsewhere.

To set up this URL mapping, the steps to follow are :

1. On the module’s main page, click on the icon for the virtual server that you want to create the mapping under. If you want it to apply to all virtual servers, click on the *Default Server *icon instead.
2. On the virtual server options page that appears, click on the Aliases and Redirects icon to go to the page in Figure 29-6.
3. In the empty row in the Map locale to remote URLs table, enter a URL path on your server (like /webmin) into the first field, and the full URL that you want the pages to be requested from into the second (like http://www.webmin.com/).
4. In the empty row in the Map remote Location: headers to local table, enter the same full remote URL into the first field and the URL path on your server into the second. This second table controls the conversion of redirects issued by the remote server, and should almost always be set. If it is not set, whenever the remote server issues a redirect the browser will end up connecting directly to it instead of to your server.
5. Click the Save button to have your new mapping stored in the Apache configuration. The browser will return to the virtual server options page.
6. To make the mapping active, click on the Apply Changes link at the top of the page.

You can test it out by going to the mapped URL path on your system, and you should see pages that have been requested from the remote server. The process is not totally transparent though, because it does not convert HTML files in any way. So if in the example above the remote server contained an HTML page with a link like <a href=/foo.html>, following it would take the browser to /foo.html on your system, not /webmin/foo.html as you might expect. There is no solution to this problem, apart from making sure that the remote server always uses relative links and image paths.

Running CGI programs

CGI stands for Common Gateway Interface, and is a standard method for webservers to run external programs, pass them details of a browser’s request, and read back any content that the program generates. CGI programs are one of the simplest way of adding dynamic pages to your webserver, and are relatively easy to set up and develop. Server-side includes (covered in the next section) are even simpler, but very limited in what they can do.

A CGI program can be written in any language as long as it follows certain rules. The most common is Perl, but C, Python, PHP or any other language that can access environment variables and produce output can be used. You can even write shell scripts that are valid CGI programs. This section is not going to explain the details of how to write them though – there are plenty of books that cover that already.

CGI programs are just files on your system, like any other HTML or image file. The difference is that when they are requested by a browser, Apache executes them and returns their output instead of the contents of the file. Because you only want this to happen for programs and not for HTML files, the server must be configured to identify certain files as CGI programs. This is normally done in one of two ways – by putting all CGI programs into a certain directory, or by giving them all a file extension like .cgi.

The choice is yours, but the latter option is simpler to use as you can freely mix CGI scripts, HTML and image files in the same directory. To set it up, the steps to follow are :

1. On the module’s main page, click on the icon for the virtual server that you want to set up CGI programs for. Or click on the *Default Server *icon if you want to use them on all servers.
2. Click on the icon for the directory that you want CGI programs to be enabled under. Typically each virtual server will have an icon for options for its document root directory, but if not you can create one by following the steps in the Setting per-directory options section above. If you only want to allow CGI programs to be run in some sub-directory of the website, you can create a new directory icon for that as well.
3. On the directory options page, click on the Document Options icon and change the Directory options field from Default to Selected below. Then set the rows Execute CGI programs and Generate directory indexes to Yes, and click the Save button at the bottom of the page. This tells Apache that CGI programs can be executed in the directory.
4. Back on the directory options page, click on the MIME Types icon. In the Content handlers table, select cgi-script from the first blank menu under the Handler column, and enter .cgi into the field next to it under the Extensions column. Then click the Save button at the end of the form. This tells Apache to treat all files in the directory ending in .cgi as CGI programs.
5. Finally, click the Apply Changes link on any page. You should now be able to create a file with a .cgi extension in the chosen directory, and test it out in a web browser.

An alternative to this approach is to specify a directory in which all files are treated as CGI programs. This has the advantage that they can be given any name you like, instead of being forced to have a .cgi extension. You can also set permissions on this directory to restrict who is allowed to create CGI programs, while still allowing others to edit normal HTML pages.

To set up a directory for CGI scripts, the steps to follow are :

1. On the module’s main page, click on the icon for the virtual server that you want to set up a CGI directory for. Or click on the *Default Server *icon if you want to set it up for all servers.
2. Click on the CGI Programs icon to bring up a page for setting various CGI options.
3. The CGI directory aliases table works in a very similar to the Document directory aliases table described in the previous section. However, in addition to mapping a URL path to a directory on your server it also tells Apache that any files accessed through that path should be treated as CGI programs. In the first empty row of the table, enter a URL path like /cgi-bin/ into the From field and a directory like /home/example/cgi-bin/ into the To field.
4. Click the Save button at the bottom of the page to return to the virtual server options page. Then click the Apply Changes link to make the CGI directory active.

You should now be able to create CGI programs in the directory, and test them out in a web browser. On some Linux distributions, the default Apache configuration will already have a CGI directory available at the URL path /cgi-bin/, mapped to a directory like /home/httpd/cgi-bin/. If this is good enough for you, there is no need to follow the steps above – instead, you can just put CGI programs in that directory.

Normally, all CGI programs execute as the Unix user that the webserver runs as, typically named httpd or apache. On a system with multiple users who cannot be fully trusted, this is not a good thing – anything that one user’s CGI program can do, everyone else’s can as well. So for example if a user writes a CGI program that edits some file, he would have to make that file writeable by the httpd user, meaning that everyone else’s CGI programs could write to it as well.

Fortunately, there is a solution. Apache comes with an optional program called suexec that can be used to have CGI programs run as some other Unix user, rather than as the webserver user. Typically the CGI programs under each virtual server will be run as the Unix user who owns that server’s files. To set this up, the steps to follow are :

1. Make sure that the suexec program exists on your system, and that it has setuid-root permissions. Apache typically expects to find it in /usr/sbin or /usr/local/apache/sbin, and most Linux distributions include it as a standard part of their Apache package. However, some do not have it setuid by default, so you may need to run chmod 6711 /usr/sbin/suexec to make it so.
2. On the main page of the module, click on the icon for the virtual server that you want to have CGI programs run as a different user on. This will take you to the options page shown in Figure
3. -4.
4. Click on the User and Group icon on the virtual server options page.
5. For the Run as Unix user field, select User name and enter the name of the user who owns the virtual server into the field next to it.
6. Similarly, for Run as Unix group select Group name and enter the primary group of the user specified in the previous step.
7. Click the Save button to return to the options page for the virtual server.
8. To activate suexec for the first time, you need to stop and re-start Apache. Use the Stop Apache link at the top of the page to halt it, and then the Start Apache link to start it up again.
9. To check that suexec is actually working, check the Apache error log file for a line containing suEXEC mechanism enabled that was logged when the webserver was re-started.

Because it can execute commands as any user on your system, suexec has many security restrictions to prevent misuse by normal users. It will only run CGI programs that are owned by the user and group specified in steps 4 and 5, and only if they are not writeable by any other user, or in a directory that is writeable by another user. The IDs of the user and group must be above minimums that are compiled into the program, to prevent programs owned by system users such as root or bin from being run. Finally, the program must reside under a directory that is compiled into suexec, and nowhere else on the filesystem.

This last restriction can be very annoying if you have a large number of virtual servers and want to enable the execution of CGI programs in their directories. The default allowed directory is typically the standard CGI directory for Apache, such as /home/httpd/cgi-bin. To change this, you will need to re-compile suexec with a different directory, such as /home.

Whenever suexec fails to run a CGI program, it fails with HTTP status code 500. Because there are many things that can go wrong, you should check the file suexec_log in the same directory as the other Apache logfiles to see why it is refusing to execute a particular program. For each failure, a line is written to this file explaining the problem, such as incorrect permissions or a file ownership mismatch.

Writing CGI programs can be difficult because when they fail, very little information is displayed in the browser. All you see is a message like 500 server error, which no explanation of the real cause. However, more detailed error information is written to the Apache error log file. This is usually named error_log, and can be found in the same directory as the Apache access log files. See the section below on Configuring logging for more details on how to find and change it.

Anything that a CGI programs outputs to STDERR will also be written to the error log, which is useful if you want your program to generate debugging information that is not sent to the web browser. Because many programming languages like Perl output error messages on STDERR if a script fails to compile or run, all such messages will also be written to the error log file.

The biggest problem with CGI programs is that the webserver has to launch a new process every time one is requested. If the CGI is written in Perl or PHP, the process then has to load the interpreter for that language which can itself be a large program. The end result is that processing a request for a CGI page takes much longer than a request for a static HTML or image file, and generates much more load on the server system.

For this reason, optional modules have been developed that allow the webserver to run Perl and PHP scripts using an interpreter that is part of the Apache process. These modules are called mod_perl and mod_php, and are included in the Apache package in many Linux distributions. Installing and configuring them is not covered in this chapter though.

Setting up server-side includes

Server-side includes allow you to create simple dynamic web pages without the complexity of writing an entire CGI program in a language like Perl. When active, some of the HTML files served by Apache are checked for special tags starting with <!–. The contents of each tag is then replaced by dynamically generated text that depends on the tag's parameters, and the resulting page sent to the web browser.

The most common use of server-side includes is including the contents of one HTML page into another. This can be useful if you have a common header or footer that you want to share among multiple pages without repeating it over and over again. Where a special tag like <! include file=_something.html_ > appears in the HTML of page, it is replaced with the contents of the file something.html.

Server-side includes can also be used to access and set environment variables, to conditionally display HTML based on variables and to run CGI programs or shell commands and have their output included in the page. This section will not cover the tags that are available and the purposes though – instead, you should read the documentation on the Apache website or a good book on HTML.

Normally, allowing un-trusted users to create HTML pages containing server-side include tags is perfectly safe because they cannot be used to perform potentially dangerous operations like editing files on the server. The exception to this is the <! #exec > tag, which can be used to run an arbitrary shell command and have its output included in the web page. Because the command runs as the Unix user that Apache is running as (normally httpd), a user who is not allowed to create CGI programs may be able use this kind of tag to read or modify files that he would not normally be able to. For this reason, Apache can be configured to enable server-side includes with or without the risky exec tag.

Because checking an HTML file for server-side include tags is CPU intensive, they are often only activated for files with the .shtml extension. This way you can put static HTML in .html files and dynamic content into .shtml files, so that the server does not have to waste time looking for tags in files that do not contain them. However, it is also quite possible to have all .html files checked for server-side includes if you wish.

To turn on includes for a virtual server, the steps to follow are :

1. On the module’s main page, click on the icon of the virtual server that you want to enable server-side includes on. Or click on the Default Server icon to enable them for all virtual hosts.
2. Click on the icon for the directory that you want server-side includes to be enabled under. Typically each virtual server will have an icon for options for its document root directory, but if not you can create one by following the steps in the Setting per-directory options section above. If you only want to enable server-side includes in some sub-directory of the website, you can create a new directory icon for that as well.
3. On the directory options page, click on the Document Options icon and change the Directory options field from Default to Selected below. If you want to enable server-side includes without the exec tag, change the Server-side includes row to Yes. If you want to enable the potentially risky exec tag as well, change Server-side includes and execs row to Yes instead. Either way, when they have been enabled click the Save button at the bottom of the page.
4. Click on the MIME types icon on the directory options page. If you want to enable includes on all HTML files, find the Content handlers table to select server-parsed from the first empty menu under the Handler column, and enter .html into the field next to it under the Extensions column. This tells Apache that files ending in .html should be checked for server-side include tags. If you want to enable includes for only .shtml files, enter .shtml instead of .html under the Extensions column. Then in the Extra MIME types table enter text/plain into the first empty field under the Type column and .shtml into the field under Extensions next to it. This tells Apache that .shtml files should be checked for server-side include tags, and that they actually contain HTML.
5. Finally, click the Save button at the bottom of the MIME Types page, and then the Apply Changes link back on the directory options page.

Once server-side includes are enabled, you can test them by creating an .html or .shtml file in the chosen directory with some special tags it in. Then open the page in your web browser to see the result. If for some reason server-side includes were not enabled properly, nothing will show up at all because the There is another method of indicating to Apache that certain HTML files should have server-side include processing performed on them. The webserver can be configured so that any .html file with the Unix execute permission set is processed for includes, by following the steps below. You can set this permission with a command like chmod +x file.html.

1. Follow steps 1 to 3 of the instructions above to enable server-side includes for some directory.
2. On the directory options page, click on the CGI Programs icon.
3. On the page that appears, change the Process includes on files with execute bit? field to Yes. You can also set it to Yes and set last-modified date to have Apache read the modification time each processed HTML file and use that to set the Last-Modified HTTP header.
4. Click the Save button at the bottom of the CGI Programs page, and then the Apply Changes link on any page.

You should now be able to set execute permissions on HTML files in the directory, and Apache will parse them for server-side include tags when they are requested. This allows you to selectively turn on include processing, while avoiding the problem of having to rename a file (and break links) just because it now contains include tags.

Configuring logging

By default, every request that Apache finishes processing is written to a log file in a standard format. For each request the client IP address, website username, date, time, URL path, status code and number of bytes transferred is logged. In the default Apache configuration, there is only a single log file that is used for all virtual servers. However, you can re-configure the webserver to use different files for different virtual hosts, and even to log additional information for each request.

Apache also has a log file for recording error messages, which are generated when a browser requests a page that does not exist, when an HTTP connection is terminated, or if some other unexpected condition occurs. As the Running CGI Programs section explains, this log file also contains error output from CGI programs and failure messages from server-side include directives.

To see which log files are being used by Apache on your system and to change them, follow these steps :

1. On the Apache Webserver module’s main page, click on the Default Server icon. This will bring you to the default server options page similar to the one shown earlier.
2. Click on the Log Files icon to being up the log files configuration form shown in the screenshot below.
3. The Error log to field controls where CGI and webserver error messages are written to. Typically the File option is selected and the path to a file into which error messages should be written is displayed int the field next to it. You can select the System Log option if you want to have messages sent to syslog instead (covered in chapter 13). All messages will use the local7 facility. The other available option is Program, which when selected will cause Apache to run the command entered into the field next to it and feed error log messages to it as input. This can be useful for performing your own filtering or analysis of errors as they are reported.
4. The Named log format table lists pre-defined formats that can be used for logfiles defined in the next step. Each has as Nickname *which is used to refer to it, and a *Format string which specifies the fields written to the log for each request. When a log line is written, each of the % fields in the format string is replaced by some detail of the request, such as the client address, HTTP status code or virtual server name. See the online Apache documentation for more details on which % fields are available. Several standard formats such as common and combined are already defined in the default Apache configuration. To create your own log format, fill in the empty row at the bottom of the table. Each format much have a unique nickname.
5. The Access log files table specifies the files that are used for logging actual requests processed by the Apache webserver. Multiple files can be specified, and the format of each can be selected independently from one of those explained in the previous step. All requests will be written to all listed logfiles. Each row of the table defines one logfile. Under the Format column you can choose the format for the file, or select the Default option to use the standard Apache logfile format. Under the Write to column you can choose if the logging is being done to a file or to the input of a program. The path to that file or program must be entered into the field in the File or program column. If you want to add an additional logfile, fill in the fields in the empty row at the bottom of the table.
6. If you have made any changes to the logging configuration, click the Save button at the bottom of the page, then the Apply Changes link.

Default server log files configuration form

Apache also allows you to define different logfiles for each virtual server, so that requests to the various virtual hosts on your system do not all get mixed up into one file. By default, all requests are written to a single access log file without any field that identifies the virtual server that processed them. To change this and have a virtual server write to its own separate logfile, the process is :

1. On the module’s main page, click on the icon of the virtual server that you want to configure a new logfile for.
2. Click on the Log Files icon, which will take you to a page similar to the one in the screenshot above.
3. If you want this virtual server to have its own separate error log file, change the Error log to field from Default to one of the other options.
4. To add a log format that exists only for this virtual server, fill in the empty row in the Named log formats table. It is usually a better idea to define all log formats in the default server though, so that they can be used in any virtual host.
5. Add a row to the Access log files table for the separate logfile for this virtual server. As soon as one is defined, requests to the virtual host will be written only to it instead of the access log list on the Log Files page under the default server.
6. When done, click the Save button at the bottom of the page to have your new logfile settings written to the Apache configuration. Then back on the virtual server options page, hit the Apply Changes link at the top to make them active.

If you have multiple virtual servers and want to identify which one each request was made to, another solution to change the format of the default access log file to include the virtual server hostname in each log line. To set this up, the steps are :

1. On the module’s main page, click on the Default Server icon, and then the Log Files icon on the default server options page.
2. In the Named log formats table find the row for the common format and change its Format field so that it reads %h %l %u %t “%r” %<s %b %{Host}i “%{Referer}i” “%{User-Agent}i” The extra fields will tell Apache to include the virtual server hostname, referrer URL and browser name for each request on every log line.
3. In the Access log files table, find the row for your server’s main logfile, and make sure that the Format field is set to common, not to Default or some other named format.
4. Click the Save button, and then the Apply Changes link. All entries written to the logfile from now on will include the additional information.

Setting up custom error messages

When a browser attempts to access a page that does not exist, a directory that is password protected or a CGI program that is malfunctioning, Apache returns one of its built-in error messages. Because these error message pages are not always friendly or nice to look at, you can configure the webserver to use your own pages instead. This can be set up to apply to all virtual servers, a single server or just one directory. The steps to follow are :

1. On the module’s main page, click on either a virtual server or the Default Server icon if you want to define a custom error message that applies to all servers.
2. If you only want the custom message to be displayed for requests to a particular directory, URL path or filename, click on its icon on the server options page. If no icon for the directory exists yet, you will need to define one by following the steps in the section on Setting per-directory options.
3. In the directory or virtual server options page, click on the Error Handling icon.
4. The Custom error responses table is where you can enter error codes and their corresponding custom messages. Any existing error messages for the directory or server will be listed, followed by a blank row. To add a new one, start by entering the HTTP error number into the Error code field. Some of the more common codes and their causes are :
   • 404 The requested page does not exist
   • 403 Access to the page is denied
   • 401 The browser must login first before accessing the page
   • 500 A CGI program failed, or some other internal error occurred If you just want to change the message that Apache displays when the error occurs, select Show message under the Response column and enter the text of your new message into the field under URL or message. On the other hand, if you want the contents of another page to be displayed instead, select Goto URL and enter either a URL page (like /errors/500.html) or full URL (like http://www.error.com/505.html) into the URL or message field. In the latter case, the browser will be re-directed to the URL when an error with the chosen code occurs.
5. Click the Save button at the bottom of the page. If you want to add another custom error message, click on the Error Handing icon again and fill in the new blank row in the table.
6. Click the Apply Changes button on any page to make the new custom error message active.

Some web browsers, such as IE in its default configuration, will not display the text of error messages sent by the webserver. Instead, only the error code number and a more friendly message generated by the browser is displayed.

Adding and editing MIME types

MIME types are the method used by Apache, mail clients and many other programs to indicate the type of files and other date. A MIME type consists of two words separated by a slash, such as text/html, image/gif or video/mpeg. As those examples show, the first word is the general category of type, while the second is the actual type name.

Every response sent by a webserver to a browser is accompanied by a type, so that the browser knows how to display it. When a normal file is requested, the webserver typically works out the type by looking at the file’s extension, such as .gif or .html. CGI programs must supply their type to the webserver before any other content that they output, which is then forwarded on to the browser. This allows a CGI program to output HTML, plain text, images or any other kind of data, regardless of the filename of the CGI script itself.

Browsers never attempt to work out the type of a page by looking at the filename extension in the URL – instead, they always rely on the MIME type sent by the webserver. Apache gets its global list of MIME types and the extensions that they are associated with from a configuration file that applies to all virtual servers. To edit and add to this list of types, the steps to follow are :

1. On the module’s main page, click on the MIME Types icon in the Global Configuration section. This will bring you to a page listing all the types that Apache currently knows about, along with the filename extensions. Almost every type that you would ever need to use should already be listed.
2. To create a new type, click on the Add a new MIME type link above or below the list.
3. In the *MIME type *field of the form that appears, enter the type name such as text/foo. It is acceptable for the same type to be defined twice, as long as each entry has different associated filename extensions.
4. In the Extensions text box, enter all the filename extensions what you want associated with this type, such as .foo and .fo. Make sure that no other MIME types are using the same extensions.
5. Click the Save button below the form. The browser will return to the types list, which will include your new entry.
6. Click the Apply Changes link on any page to make the new type active.

You can edit or delete an existing global MIME type by clicking on its name in the list, which will bring up the type editing form. Either change the MIME type or Extensions fields and click Save, or hit the Delete button to totally remove it. Either way, afterwards you must use the Apply Changes link to make the changes active.

MIME types can also be defined on a per-virtual server or per-directory level in the Apache configuration. This can be useful if you want to override a type for some extension in a particular directory, or create a type that is only needed by one virtual server. To do this, follow these steps :

1. On the module’s main page, click on the icon for the virtual server that you want to define the MIME type for.
2. If you only want the type to be used for requests to a particular directory, URL path or filename, click on its icon on the server options page. If no icon for the directory exists yet, you will need to define one by following the steps in the section on Setting per-directory options.
3. In the directory or virtual server options page, click on the MIME Types icon.
4. The Extra MIME types table is for entering types that apply only to this virtual server or directory. In the first blank field under the Type column, enter a type like text/foo. In the field next to it under Extensions, enter one or more filename extensions like .foo.
5. Click the Save button at the bottom of the page. If you want to add more than one type, you will need to click on the MIME Types icon again so that a new blank field appears in the table.
6. When you are done, use the Apply Changes link at the top of any page to make the new type mapping active.

On the MIME Types page, there is a useful field labelled *Default MIME type*. If set, any files that Apache cannot identify the type for will be treated as whatever is entered into this field instead. Normally, this is set at the default server level to text/plain, but you may want to change it to something else for a particular directory that contains lots of files that have no filename extension.

There is a similar field on the MIME Types page for directories, URL paths and filenames labelled Treat all files as MIME type. When it is set, Apache will identify all files in that directory as the specified type, no matter what their extension. This can be used to forcibly set the types of files that have names that do not follow the normal convention of ending with a type extension.

Password protecting a directory

The HTTP protocol has a standard method of indicating that a directory or site requires a username and password to be supplied before it can be accessed. Apache can be configured to force users to login before being able to view some or all of the pages on your system. Logins are typically checked against a separate password file, instead of the Unix user list.

Password protection can be useful for securing a directory that only some people should be allowed to access, or for setting up a website that uses CGI programs to display different content to different users. To protect a directory, the steps to follow are :

1. On the module’s main page, click on the icon for the virtual server that you want password protection to be enabled under.
2. Click on the icon for the directory, URL location or filename that you want to protect. If one does not exist yet, follow the steps in the Setting per-directory options section earlier in this chapter to create it.
3. Click on the Access Control icon, which will bring you to the page shown in the screenshot below.
4. In the Authentication realm name field, de-select Default and enter a description for the protected directory, such as Private files. This will be displayed to the user in the browser when he tries to login.
5. Change the Authentication type to Basic. The Digest type is more secure, but is not supported by a lot of browsers.
6. Change the Restrict access by login field to All valid users. This tells Apache that any of the users in the password file set in step 7 will be allowed to login. You can restrict access to only a subset of users by selecting the Only these users option and entering their names of users to allow into the text field next to it. Alternatively you can select Only these groups and enter the names of groups whose members you want to allow into its field. These options can be useful if the same authentication files are entered on this page for several directories.
7. In the Text file authentication box, enter the full path to the file that you want to use to store usernames and passwords into the text field next to User text file. This authentication file must contain one line per user, each in the format username:_encrypted-password_. Standard Unix encryption is used for the passwords, just like in the /etc/shadow file. The file doesn’t necessarily have to exist yet, as it will be created when the follow the instructions in the later steps to add users. It should not be under of your webserver’s document root directories though, as this might allow an attacker to download it, crack the passwords and login to your website.
8. If you want to categorize users into groups for further restriction as explained in step 6, enter the full path to a group file into the Group text file field. This file must contain one line per group, in the format groupname:_ username1 username2 etc_. The file does not have to already exist, because it will be created when you add groups in the later steps. If you just want to set up simple username and password authentication, then this step is unnecessary.
9. Click the Save button at the bottom of the page, and you will be returned to the directory options page again.
10. If the user and group files already exist or if you are planning to edit them manually, you can skip to step 21. Otherwise, click on the Access Control icon again to re-display the form.
11. Click on the Edit users link next to the User text file field. This will bring up a page listing all webserver users currently listed in the file, if any.
12. To create a new user, click on the Add a new user link above or below the list.
13. On the user creation form, enter a login name into the Username field.
14. In the Password field, select the Plain text option and enter the user’s password into the field next to it.
15. Click the Save button to have the user added and the list of users re-displayed. You can edit an existing user by clicking on its name in the list, changing its details and hitting the Save button. To remove a user, click the Delete button on the user editing form instead.
16. When you are done creating users, use the Return to access control link to go back to the Access Control form.
17. If you are using a group file as well, click on the Edit groups link next to the Group text file field to bring up a list of existing groups and their members.
18. To create a new group, click on the Add a new group link and fill in the Group name and Members fields on the creation form that appears, then click Save. Members must be entered as a space-separated list of usernames.
19. Existing groups can be edited and deleted by clicking on their names in the list, just like users can.
20. When you are done creating groups, follow the Return to access control link to go back to the Access Control form.
21. Finally, click on the Apply Changes link on any page to activate password protection for the directory. You can test it out by trying to visit the protected page and logging in as one of the users that you created.
22. You can add an edit users and groups in future by editing the text files directly, or by following the relevant steps above. There is no need to use the Apply Changes link after changing the user or group lists though, as Apache re-reads the files on every request.

The access control form

The instructions above explain how to create text files for storing users and groups, but if your website is going to have a very large number of users text files are not the best way to store them. Because Apache re-reads the user file on every request, the large it gets the longer it will take for the webserver to lookup a user and generate a response. When editing or deleting a user, the entire file must be read in and written out again by the program that is changing it, which can take some time if the file is large. This increases the chance of file corruption if more than one process attempts to manipulate the same user file at the same time.

The solution is to use DBM files for storing users and groups instead. These are binary format database files that are indexed by a key (such as the username), and can be safely edited in-place. Their only down-side is that they cannot be viewed or changed by Unix programs that deal with plain text, like cat and vi.

The process of setting up authentication from DBM files is almost identical to the steps above. The only difference is that the user and group filenames must be entered into the User DBM file and Group DBM file fields in the DBM file authentication box. The User text file and Group text file fields must be left set to Default. Unfortunately, Webmin does not allow you to edit users or groups in DBM files as you can with text files. Instead, you will need to write a Perl script or use a program like makemap to create them at the command line.

Apache user and password files are totally separate from the system’s Unix user list. However, this module can be configured to add, update or remove a user in a password file when a user with the same name is created, edited or deleted in the Users and Groups module. This is done using that module’s synchronization feature, covered in more detail on UsersAndGroups.

Synchronization can be useful if you want to grant access to some web directory to some of the Unix users on your system, and want their usernames and passwords to remain in sync if they are ever changed/. To set up synchronization between an Apache text authentication file and Unix users managed by the Users and Groups module, the steps to follow are :

1. On the module’s main page, click on the icon for the virtual server that the protected directory is under, then on the icon for the directory.
2. Click on the Access Control icon, then on the Edit users link next to the User text file field.
3. Below the list of users is a form for setting up synchronization for this users file. The checkboxes labelled Add a user when a Unix user is added, Change the user when a Unix user is changed and Delete the user when a Unix user is deleted are fairly self-explanatory. Typically you would select all three, or maybe just the last two if you want to add new users to this file manually.
4. After selecting the options that you want, click the Save button. Any changes made in the Users and Groups module from now on will cause this user list to be updated as well.

Each Apache users text file has its own separate synchronization options. Because they are associated with the name of the file, if it is renamed the options will be reset to their defaults. Only changes made in Webmin’s Users and Groups or Change Passwords modules will be synchronized with the Apache users file – if a user changes his password with the command-line passwd program, his web password will not be changed to match.

If you want to turn off authentication for a directory so that any browser can access it, there is no need to delete the entire directory configuration icon. Instead, you can just follow these steps :

1. On the module’s main page, click on the icon for the virtual server that the protected directory is under, then on the icon for the directory.
2. Click on the Access Control icon to go to the page shown in the screenshot above.
3. Change the Authentication realm name, Authentication type, Restrict access by login, User text file and Group text file fields all back to Default. If you are using DBM files instead of text, change the User DBM file and Group DBM file fields to Default as well.
4. Click the Save button, and then the Apply Changes link back on the directory options page.

Restricting access by client address

Apache can also be configured to limit access to a directory, URL location or filename to certain client systems. The webserver knows the IP address of every browser that connects to it, and can use that address to determine whether the browser is allowed to request certain pages or not.

In some situations, the client’s real IP address will not be available to the webserver. If the client is accessing the web through a proxy server or a firewall doing NAT, then the IP address that the request appears to come from will be that of the proxy or firewall system. There is way to get the real address, but generally it is not a problem because all clients behind the proxy or firewall are usually treated the same from an access control point of view.

Apache determines whether a client is allowed access or not by checking its IP address and hostname against a list of rules. There are two types of rule – those that allow access, and those that deny it. Depending on its configuration, the webserver will either check all of the allow rules before the deny rules, or vice-versa. The first one to match determines if the client is denied or not, and no further rules are checked.

Most people who set up IP access control want to allow access from certain addresses and networks, and deny everyone else. For example, you might want to give hosts on your company LAN access to your intranet, but prevent others on the Internet from accessing it. To set up this kind of access control, the steps to follow are :

1. On the module’s main page, click on the icon for the virtual server that you want IP access control to be enabled under.
2. Click on the icon for the directory, URL location or filename that you want to restrict access to. If one does not exist yet, follow the steps in the Setting per-directory options section earlier in this chapter to create it.
3. Click on the Access Control icon, which will bring you to the page shown above.
4. Scroll down to the Restrict access table, and change the Access checking order field to Allow then deny. This tells Apache that any request which is not specifically allowed by access control rules should be denied, and that all rules that allow access should be checked before rules that deny. If the alternative Deny then allow option is chosen, requests that do not match any rule will be allowed, and deny rules will be checked before allow rules. The Mutual failure option has the same effect as Allow then deny, and should not be used.
5. At first, this table will contain only one empty row for entering your first access control rule. Because you are going to allow only certain clients and block the rest, select Allow from the menu in the Action column. The menu and field under the Condition column determine what kind of check is done to see if the client is allowed or not. The available condition types are :
   • All requests If chosen, all client requests will have the selected action performed.
   • Request from host If chosen, only clients whose hostname is the same as or ends with the text entered into the field next to it will have the action performed. Apache gets the hostname by performing a reverse DNS lookup on the client’s IP address, which may not always work.
   • Request from IP If the client’s IP address is the exactly same as the one entered into the field next to the menu, the selected action will be performed.
   • Request from partial IP If chosen, clients whose IP addresses start with the partial IP entered into the field next to the menu will have the selected action performed. For example, you could enter 192.168 to match all clients on that network.
   • Request from net/netmask If the client’s IP address is within the network specified by the network address and netmask entered, the selected action will be performed. An example network specification would be 192.168.1.0/255.255.255.0.
   • Request from net/CIDR If the client’s IP address is within the network specified by the network address and prefix bits entered, the selected action will be performed. 192.168.1.128/25 is an example of this kind of network specification.
   • If variable is set If this option is chose, the selected action will only be performed if the environment variable whose name is entered into the adjacent field is set. Apache provides several ways to set variables based on request headers and browser types and are too complex to cover here.
6. Click the Save button at the bottom of the form, and if there are no errors in your selections you will be returned to the directory options page. To allow more than on client IP address or network, click on the Access Control icon again and fill another next blank row in the Restrict access table. You can build up complex access control rulesets by adding many allow and deny rules.
7. When you are totally done, use the Apply Changes link on any page to make the restrictions active.

It is possible to combine both IP address restrictions and username/password access control for the same directory. This can be done in two ways – either clients are checked for any IP restrictions and then forced to enter a password, or they are only prompted for a password if they do not pass the IP restrictions.

The mode that Apache uses is determined by the Clients must satisfy field on the Access Control form. If you set it to All access controls then they must pass both password and IP checks. However, if *Any access control* is selected then a password will only be prompted for if the IP checks fail. This can be useful for granting access to a directory to everyone on your internal network, and to people on the Internet who have a valid username and password.

Encodings, character sets and languages

As the Adding and editing MIME types section explains, Apache attempts to determine a MIME type for every file that it sends to a browser. In addition to the type, files can also have an encoding that is usually used to indicate how they were compressed. The encoding is determined by the file extension (such .gz for gzipped data), and can be used by the browser to uncompress the file before displaying it.

For example, this would allow you to create a file called foo.html.gz which contains compressed HTML data and is identified by the webserver as such. For large files, sending them in compressed format can save bandwidth and reduce the time it takes for them to be downloaded. Unfortunately, not all browsers support the common .gz and .Z encoding formats, so this feature is not always useful. At the time of writing, Mozilla and Netscape supported compressed encoding, but IE did not.

Encodings can be defined globally, on a per-virtual server basis, or just for a single directory or URL location. They are usually defined globally though, and can be viewed and edited by following these steps :

1. On the Apache Webserver module’s main page, click on the Default Server icon.
2. Click on the MIME Types icon, and scroll down to the Content encodings table. Each row in the table defines two encodings, and there is always at least one pair of empty fields for adding a new one. Typically entries for the x-compress and x-gzip encodings will already exist, as they are included in the default Apache configuration.
3. To add a new encoding, enter its name into the first empty field under the Content encoding column. In the field next to it, enter a space-separated list of filename extensions that are used by files encoded in that format.
4. To change the name or extensions for an existing encoding, just edit its fields in the table. For example, you can add extra extensions for an encoding by just entering them into same field as existing ones.
5. If you want to delete an encoding, just clear its entries in the fields under the Content encoding and Extensions fields.
6. When you are done editing encodings, click the Save button at the bottom of the page, and then the Apply Changes link.

Apache takes all filename extensions into account when determining a file’s MIME type, encoding, language and character set, and does not care about their order. This means that a files named foo.html.gz and foo.gz.html are both identified as containing gzip compressed HTML data.

Another piece of information that Apache can supply to browsers requesting a file is the character set used by text in the file. If all your web pages are in English or a language like Malay that does not use any non-English letters, then you don’t need to care about this. However, if you are creating HTML pages in a different language that uses characters outside the standard ASCII character set then it is useful and often necessary to indicate to browsers what character set each page is in.

Languages like German and French use special characters like Ä and à that are represented by bytes above 128. Others like Chinese and Russian have so many characters that each must be represented by two bytes, using special character sets like Big5 and KOI8. For these languages, it is vital that the browser be informed of the character set of each page so that it can decode the text that it contains and use the correct font to display characters.

As with encodings, Apache determines the character set of each file by looking at its filename extension. So for example a file named foo.html.Big5 would be identified as HTML in which the text was encoded in the Chinese Big5 format. A file can have both a character set and an encoding, such as foo.html.Big5.gz, and the order that its extensions are in does not matter.

Character sets can be defined globally or for individual virtual servers and directories. To view and edit the global list of character sets, follow these steps :

1. On the Apache Webserver module’s main page, click on the Default Server icon.
2. Click on the Languages icon, and scroll down to the *Extra character sets *table. Each row in the table defines two character sets, and there is always at least one pair of empty fields for adding a new one. In the default Apache configuration several commonly used character sets are already defined.
3. If you need to add a new character set, enter its standard ISO name into the first empty field under the Charset column, and the filename extensions associated with it into the adjacent field under Extensions. Many common character sets are defined by default, so you may just be able to use one of the existing recognized extensions for your files. Multiple extensions must be separated by spaces.
4. You can change the name or extensions for existing characters sets by just editing the fields in the table. It is not usually a good idea to rename the default sets, because they use the standard names that are recognized by browsers. Adding extensions is perfectly safe though.
5. To delete a character set, just clear out the fields containing its name and any associated extensions.
6. When you are done editing, click the Save button. If you used up all the blank fields in the Extra character sets table and want to add more, click on the Languages icon again. Otherwise, use the Apply Changes link to make your changes active.

Because most of the commonly used character sets are defined by default in the Apache configuration, it is not usually necessary to add new ones. Instead, you can just find the associated extensions and use them on your filenames.

Apache can also identify the language that an HTML or text file is written in by looking at its filename extensions. At first it may seem that there is no difference between a file’s language and its encoding, but that is not always the case. For example, the ISO-8859-2 character set is used for many different European languages, and the Chinese language can be represented by both the Big5 and GB character sets.

Unfortunately, few browsers actually make any use of the language that a file is written in. However, some can be configured to request pages in a language chosen by the user, and Apache can be set up to use this information to identify the correct file to return. This happens when the Generate Multiviews option is turned on for a directory, in the Directory Options page.

When that option is active, a request for a page like /documents/foo which does not actually exist will cause Apache to scan the directory for /documents for all files starting with foo, identify their types and languages, and return the one that best matches the client’s specified language. This is useful if you want to be able to have multiple versions of the same page in different languages, but have them all accessible via the same URL.

To view and edit the languages and file extensions recognized by Apache, the steps to follow are :

1. On the Apache Webserver module’s main page, click on the Default Server icon.
2. Click on the Languages icon, and find the *Content languages *table. Each row in the table defines two languages, and there is always at least one pair of empty fields for adding a new one. The default Apache configuration contains several commonly used languages.
3. To add a new language, enter its ISO code into the first empty field under the Language column, and a list of extensions separated by spaces for files in that language under the Extensions column.
4. Existing languages can be editing by just changing their codes and extensions in the table, or deleted by clearing out their fields. It is wise not to change the standard codes for existing default languages.
5. When you are done editing languages, click the Save button at the bottom of the page. If you ran out of blank fields when adding new ones, click on the Languages icon again to return to the table. Otherwise, use the Apply Changes link to activate your new settings.

As with encodings and character sets, Apache does not care about the ordering of extensions in a filename when working out its type and language. So both the files foo.html.de and foo.de.html would be identified as HTML documents written in German.

Editing .htaccess files

As explained in the introduction, Apache options can be set for a directory by creating a file named .htaccess in the directory. These are often created by normal users who do not have permissions to edit the master webserver configuration file, and want to change the way Apache behaves when accessing their directories. .htaccess files can be used to set almost all of the options that you can configure on a per-directory basis, as explains in other sections of this chapter.

The options in one of these files apply to all the files in its directory and in any subdirectories. However, they can be overridden by another such file lower down in the directory tree. Per-directory options in the main Apache configuration will be overridden by those in a .htaccess file for the same directory, but directory options for a subdirectory will override those in a parent .htaccess file!

Webmin can be used to create and edit .htaccess files as well. If some already exist on your system that were created manually, they must be discovered by Webmin first before you can use it to edit them. To have it search for existing files on your system, the steps to follow are :

1. On the module’s main page, click on the Per-Directory Options Files icon. This is what Webmin calls .htaccess files.
2. On the page that appears, there is a button labelled Find Options Files with two options next to it. If Automatically is selected, Webmin will look in the document root directory of each virtual server for options files. If From directory is chosen, you can enter a directory that will be searched instead. The latter option is useful if the websites on your system have some pages that are outside of the document roots due to the user of aliases or user web directories.
3. Click the button to have the module search the select directories and any under them. The same page will be re-displayed, but with a table of all .htaccess files at the top, assuming some were found.

To edit the options set in a file, just click on its path from the Per-Directory Options Files list. This will bring up a page similar to the directory options page shown in Figure 29-5. You can click on the icons to edit redirects, username and password access control, IP address restrictions, MIME types and custom error messages. The instructions in previous sections that apply to directories can be followed here as well – the only difference is that you do not have to use the Apply Changes link after making changes, as Apache always re-reads the .htaccess files that it encounters on every request.

You can also create a new .htaccess file by entering the path to the directory that it should be created in into the field next to the Create Options File button. When the button is clicked, the file will be created empty and have its ownership set to the user and group configured on the User and Group page of the default server. It will be added to Webmin’s list of known options files, and your browser will be redirected to the options file for the page.

To delete an per-directory options file, click on the *Delete File* link that appears at the top of the page that appears when you click on its name from the list. As soon as it is removed, Apache will cease using any options that it defines in it for the directory it was in.

The Setting Per-Directory Options section earlier in this chapter explains how to set options that apply only to files of a particular name, no matter which directory they are in. It is also possible for a .htaccess file to contain options that apply to only some of the files in the directory that contains it. This can be useful to do things like denying access to all files matching the pattern *.c in the directory /usr/local/src, which you cannot do just using per-directory or per-file options.

To set options like this, the steps to follow are :

1. On the module’s main page, click on the Per-Directory Options Files icon. Then click on the .htaccess file in the directory that you want the options to apply to. If it doesn’t exist yet, use the Create Options File button to create it as explained above.
2. Scroll down to the Create Per-File Options form, and enter the filename or pattern into the Path field. Patterns can only use shell wildcard characters like * and ?, unless you change the Regexp? field to Match regexp, in which case you can enter a Perl regular expression using characters like |, [, ] and +.
3. When you click the Create button, the same page will be re-displayed but with an additional icon for the filename or name pattern that you just entered.
4. Click on the new icon, which will bring up another page of icons for different categories of options that can be applied to files whose names match the specified filename or pattern. This page is very similar to the directory options page shown in above, and the pages that it links to are mostly identical.
5. The instructions in other sections of this chapter for creating redirects, custom error messages or IP access control can be followed on this page as well to set the same options for matching files in the directory. The only difference is that there is no need to click on the Apply Changes link to made new settings active.

You can change the filename or pattern that the options are for by editing the Path field in the Options apply to form, and then clicking Save. Or you can remove them altogether so that the options for the directory apply instead by clicking on the Delete button in the same form.

On a system that has many virtual websites run by un-trusted users, you may want to restrict the directives that those users are allowed to enter into .htaccess files. This can also be useful if you have user web directories enabled, explained in the next section. It is possible for a user to enable CGI scripts for his directory by putting the right directives into an options file, which could pose a security risk on your server.

You can restrict the directives that can be used in .htaccess files on a per-directory basis. To do this, the steps to follow are :

1. On the main page of the Apache Webserver module, click on the icon for the virtual server that the directory is under.
2. Click on the icon for the directory that you want to restrict .htaccess files in, or if one does not exist yet follow the instructions in the Setting Per-Directory options section to create it.
3. Click on the Document Options icon.
4. In the Options file can override field, select the Selected below radio button. The de-select those categories of directives in the table below that you don’t want users to be able to include in .htaccess files. The available categories are : *Authentication options *De-select this option to prevent the use of directives related to password authentication. *MIME types and encodings *De-select this option to prevent the setting of MIME types, character sets, encodings and languages for files. This will also stop files with certainly extensions being indicated to be CGI programs. *Indexing and index files *This option controls the use of directives for directory indexing. *Hostname access control *De-select this option to stop the use of IP access control directives. *Directory options *This option controls the use of directives that set options for the directory, such as whether indexing is done and if CGI programs are enabled.
5. Click the Save button, and then the Apply Changes link.

Whenever a user tries to use directives that he is not allowed to, Apache will display an error message when files in the directory containing the .htaccess file are requested. It will not simply ignore the disallowed directives.

Setting up user web directories

On a system with many Unix users, you may want to allow each user to create his own set of web pages. Instead of creating a subdirectory for each user under some document root directory, you can instead designate a subdirectory in each user’s home directory as a location for web page files. Typically this subdirectory is called public_html, and its contents are made available at a URL like http://www.example.com/~_username_/.

The special ~username path in the URL is converted by Apache to a directory under the home of the user username, no matter what document root directory is being used for the rest of the files on the website. It is also possible for files in the user’s actual home directory to be made available instead, so that ~username actually maps to the user’s home directory and not a subdirectory. However, this is a bad idea as it makes all of the user’s files available to anyone with access to the website.

To turn on Apache’s user web directories feature so that ~username URL paths can be used, the steps to follow are :

1. On the module’s main page, click on the icon for the virtual server that you want to activate user directories for. To activate them for all virtual servers, click on the Default Server icon instead.
2. Click on the Document Options icon.
3. In the User WWW directory field, de-select the Default option and enter public_html into the field next to it. Or if you want a different subdirectory to be used for users’ web pages, enter its name instead. To make users’ entire home directories available via ~username URL paths, enter . into the field. On many systems, this option will already be set to public_html in the default Apache configuration, meaning that user web directories are already enabled.
4. If the All users accessible option is selected, Apache will allow the pages in any user’s web directory to be accessed. To configure the webserver to only allow access to the pages belonging to certain users, select the Only users option and enter the names (separated by spaces) into the field next to it. This can be useful if there is a small fixed list of Unix users who should be allowed to publish web pages. To block only a few users’ web pages and allow the rest, select the All users except option and enter the names of the blocked users into its field. This is useful for protecting files belonging to important system users such as root.
5. Click the Save button at the bottom of the page, then use the Apply Changes link to activate the new settings. Try creating a public_html subdirectory in the home directory of a user, putting some HTML files in it and seeing if they can be accessed using the ~username/filename.html URL path..
6. It is also possible to have ~username URL paths mapping to directories outside users’ home directories by entering values starting with / into the User WWW directory field. For example, if you were to enter /www and a browser requested ~jcameron/foo.html, then the file returned by Apache would be /www/jcameron/foo.html. If you entered /home/*/public_html, then the file returned would be /home/jcameron/public_html/foo.html, even if the user jcameron did not have his home directory at /home/jcameron. As that example shows, any occurrence of a * in the user web directory is replaced by the username.

Similarly, you can enter a URL into the directory field, which will be used by Apache to generate a URL to re-direct browsers to when a user web directory is requested. For example, if you enter http://home.example.com/users/ and the URL path ~jcameron/foo.html is requested by a browser, it will be re-directed to http://home.example.com/users/jcameron/foo.html instead. This is useful if you want to move user web directory hosting to a separate server, while allowing URLs on your main server to be used to access them.

Even though the above are sufficient to enable user web directories, there are some other things that you might want to do. As the *Editing .htaccess files* section above explains, you may want to limit the kinds of directives that users can put in their .htaccess files so that they cannot execute CGI programs or use server-side includes. You can also change the default directory indexing and document options that apply to user web directories. The steps to do both of these are :

1. On the module’s main page, click on the icon for the virtual server that user web directories were enabled in, or the default server.
2. Assuming all your users have their home directories under /home and the web subdirectory is named public_html, enter /home/*/public_html into the Path field of the Create Per-Directory, Files or Location Options form at the bottom of the page.
3. Leave the Type field set to Directory, and the Regexp? field to Exact match.
4. Click the Create button to create a new set of options that will apply to users’ web directories, then on its newly created icon. This will bring up the document options page shown in a screenshot earlier on this page.
5. Click on the Document Options icon.
6. Change the Directory options field to Selected below, and set to Yes those options that you want to apply to user web directories. It is advisable to turn on Generate directory indexes and safe to enable Server-side includes, but not Execute CGI programs or Server-side includes and execs. The Follow symbolic links option is relatively safe to turn on as well, but will allow users to make available via the web files that are not in their public_html subdirectory by creating links to them.
7. To prevent users overriding these settings in .htaccess files, change the Options file can override field to Selected below and de-select the MIME types and encodings and Directory options checkboxes. The others control options that present no security risk, and so can be safely left selected.
8. Click the Save button and then the Apply Changes link to save and activate the restrictions.
9. If you want to turn on server-side includes, set some custom MIME types or IP access controls for user web directories, you can do it by following the instructions in the appropriate sections for this directory. Because server-side includes are quite harmless with the ability to execute external programs disabled, they can be safely enabled for users by setting the right content handler for .html or .shtml files as the Setting up server-side includes section explains.

Configuring Apache as a proxy server

An HTTP proxy is a server that accepts requests for web pages from browsers, retrieves the requested pages from their servers and returns them to the browser. They are often used on networks on which clients are not allowed to connect to webservers directly, so that restrictions on who can access the web and what sites they can view can be enforced. A proxy can also cache commonly accessed pages, so that if many clients visit the same site its pages only have to be downloaded once. This speeds up web access and reduces bandwidth utilization.

Apache is not the best proxy server available for Unix systems – Squid (covered on SquidProxyServer) takes that honour. Squid has many more configurable options, is more efficient and can deal with much larger caches. However, if you want to set up a proxy on a system that is already running Apache, then it may make sense to use the existing webserver as a proxy instead of installing and running a separate server process for Squid.

Apache’s proxy support is only available if the mod_proxy module has been compiled into the webserver or is available to be dynamically loaded. You can see if the module is available by clicking on the Re-Configure Known Modules icon on the main page. If mod_proxy is checked, then your server can be used as a proxy. If so, you can skip the next paragraph which deals with loading the proxy module.

On some Linux distributions, the proxy module is included with the Apache package but not loaded by default. If this is the case on your system, you can enable it by following these steps :

1. On the Apache Webserver module’s main page, click on the Edit Config Files icon. This will bring up a page showing the contents of the primary configuration file, called httpd.conf.
2. Look for a line starting with LoadModule? proxy_module which is currently commented out with a # at the start. If no such line exists, then the proxy module is probably not installed at all and so cannot be used.
3. Delete the # at the start of the line, and then click the Save button at the bottom of the page.
4. Click the Stop Apache link on any page to shut down Apache, and then the Start Apache link to start it again. This is necessary for the webserver to load the enabled proxy module.
5. On the module’s main page, click on the Re-Configure Known Modules icon, and then on the Save button at the bottom of its page. This tells Webmin to re-analyse the Apache configuration so that it detects that the mod_proxy module is now available.

If Apache on your system was compiled from source, then you will need to re-compile it with mod_proxy enabled in order to use the proxy features. Once mod_proxy has been enabled, you can set your system up as a proxy server by following these steps :

1. On the module’s main page, click on the icon for the virtual server that you want to use as a proxy. This must be an IP-based virtual server or the default, as it is impossible to turn on proxying for just a single name-based virtual server. However, the normal operation of whichever server you choose will not be effected.
2. Click on the Proxying icon which should be visible on the virtual server options page. If the icon does not exist, then the proxy module has not been detected by Webmin.
3. Change the Act as proxy server? field to Yes.
4. By default, Apache will not cache any pages that are requested though it when acting as a proxy server. To change this, create a directory that is writable by the web server user (usually httpd) and enter it into the Cache directory field.
5. To limit the amount of data that will be cached, enter a number of kilobytes into the Cache size field. If this is left set to Default, Apache will only cache 5 kB of pages.
6. To turn off caching for particular websites, enter a space-separated list of hostnames and domains into the Domains not to cache field. This can be useful for avoiding the caching of sites that change frequently.
7. To stop users of the proxy accessing certain domains, enter a space-separated list of full or partial hostnames into the Block requests to domains field. For example, to deny access to all sites in the foo.com domain you could just enter foo.com.
8. If you have another proxy server on your network and want to pass all requests on to that proxy, enter its URL (like http://proxy.example.com:8080/) into the empty field under Forward to in the Requests to pass to another proxy table, and leave the All option selected. Alternately, you can have just some requests passed on by selecting the Matching option and entering a partial URL or URL type (like http://www.foo.com / or ftp) into the field next to it. Like other tables in the Apache module, this one only displays one blank row at a time. If you want to set up several other proxies to forward different requests to, you will need to re-edit this page after saving and fill in the next blank row. For example, you might want to forward all FTP requests to one proxy, but all other types of request to another.
9. To exclude some requests from being passed to the other proxies (for example if they are on your local network), you can fill in the Don’t pass requests to another proxy for table. In each empty row you can choose from one of the following types : *IP address *If this type is chosen, you must enter a complete IP address into the field next to it. Any requests to the webserver with this IP will not be passed on to another proxy. *Hostname *When this type is chosen, any requests to the webserver whose hostname is entered into the adjacent field will not be passed on. *Domain *Any requests to websites in the domain entered into the field next to the menu will be retrieved directly and not passed on. *IP network *Any requests to websites in the specified IP network (entered as a partial IP address, like 192.168) will not be passed on to another proxy. *Network/bits *Any requests to websites in the IP network (entered in address/prefix, like 192.168.1.0/24) format into the adjacent field will not be passed on. To add more than one row, you will need to save the form and edit it again so that a new blank row is displayed.
10. Most of the other options on the form control the layout of the cache directory and the amount of time pages are cached for. In most cases, the defaults will work fine so you can just leave them set to Default.
11. When done, click the Save button to update the Apache configuration file with the proxy settings, then the Apply Changes link to make them active.

You should now be able to try your settings by configuring a web browser to use your Apache server as a proxy, and visiting some web pages. All proxy requests that Apache processes will be written to the access log file for the virtual server in the usual format, but with the full URL recorded instead of just the page.

Sometimes you may want to limit who has access to proxy, either by client IP address or by username and password. This can be done by following the instructions in the *Restricting access by client address* and Password protecting a directory sections, but for the special directory proxy:*. If you set up client address access control, then only hosts will allowed addresses will be able to use your server as a proxy. However, they will still be able to access normal web pages, as IP address restrictions for the special proxy:* directory only apply to proxy requests.

If you set up username and password authentication for your proxy server, then any web browsers that attempt to use it will be forced to login first. This login is to the proxy server, not to any website that is being access through it – so if a user visits a password-protected website using the proxy, then he will have to login separately to that site.

It is also possible to set up IP or password restrictions that apply only to some protocols or sites accessed through the proxy, by creating them for special directories like proxy:http or proxy:http://www.example.com/. Only requests for URLs that start with the text after proxy: will be effected by restrictions like these. They can be useful for blocking or limiting access to certain sites, or preventing the proxy from being used to request certain protocols like http or ftp.

Setting up SSL

SSL is a protocol for making secure, authenticated connections across an insecure network like the Internet. It encrypts network traffic, so that an attacker cannot listen in on the network and capture sensitive information such as passwords and credit card numbers. It allows servers to authenticate themselves to clients, so that a web browser can be sure that it is connecting to the website that is thinks it is. It also allows clients to authenticate themselves to servers, which can be used to replace usernames and passwords with digital certificates.

The SSL protocol can be used to encrypt any kind of data that would normally travel over an unencrypted TCP connection. However, in this chapter we are only concerned with the encryption of web page requests and responses, which is done by encrypting HTTP protocol data with SSL. The result is a new protocol called HTTPS, which is used by all websites that want to operate securely. Almost every browser supports the HTTPS protocol, and uses it when retrieving URLs that start with https:// instead of the normal http://. Whereas the normal HTTP protocol use TCP port 80, the HTTPS protocol uses port 443.

You can configure Apache to use HTTPS on a per-virtual server basis, or to use it for all servers. However, this depends on having the mod_ssl Apache module compiled in or available for dynamic loading, which is not always the case. The *Configuring Apache as a proxy server* section explains how to check for and possibly enable the mod_proxy module, and you can follow those same instructions for mod_ssl as well. Most modern Linux distributions include SSL support in their Apache package as standard though.

At the heart of the SSL protocol are digital certificates, which are used for both authentication and encryption. Typically the server sends its certificate to the client to prove its identity, so that the client knows that its connection to the website has not been re-directed by an attacker. Certificates issued by a proper certificate authority such as Verisign or Thawte are impossible for forge, because they have been signed by the authority’s master certificate. All web browsers include a list of authorities that they can use to validate signatures and thus ensure the authenticity of web site certificates.

The down side of this method of certificate validation is that you cannot simply generate your own certificate for your website that will be accepted without complaint by web browsers. It is possible to create a self-signed certificate that Apache will happily use, but any browser connecting to that webserver in SSL mode will display a warning message to the user because the certificate is not signed by a recognized authority. Self-signed certificates are fine for encrypting HTTPS traffic, but if you want browsers to be able to validate your site you will need a ‘real’ certificate signed by a proper authority – and that costs money.

Before you can enable SSL in Apache, you must have a certificate. The easiest way to get one for testing purposes is to generate your own self-signed certificate, which can be done by following the steps below. To generate a real certificate from a recognized authority, follow the steps at the end of this section instead. To create a certificate, you will need the openssl command, which is included with most modern Linux distributions and freely available for download from http://www.openssl.org/. If Apache on your system already includes the mod_ssl module, then openssl is probably already installed or on your distribution CD or website.

1. Login to your system as root.
2. Change to the directory in which you want to store your certificate files, such as /usr/local/apache/conf or /etc/httpd.
3. Run the command openssl req -newkey rsa:512 -x509 -nodes -out cert.pem – keyout key.pem
4. The command will ask the following question, in order to obtain attributes for your new key. To leave any of the requested fields blank, just enter a single period. Country name *The two-letter code for the country your webserver is in, such as AU or US. *State or Province Name *The name of the state your server is in, such as California. *Locality Name *The city your server is in, such as San Francisco. *Organization Name *The name of your company or organization, such as Example Corporation. *Organizational Unit Name *The name of your division within the company, such as Engineering. *Common Name *The hostname of your webserver as used in the URL. For example, if browsers usually access the server as http://www.example.com/, then you should enter http://www.example.com for this question. Unfortunately you can only enter a single hostname, so if your webserver is accessed by more than one name (such as http://www.example.com and example.com), then only one will match the certificate. However, the hostname can contain the wildcard character *, so you can enter .example.com or even just *. *Email Address *The email address of the administrator for this webserver, such as jcameron@example.com.
5. When all the questions have been answered, the files cert.pem and key.pem will be created in the current directory. These are your website’s certificate and its private key respectively.
6. Because the private key must be kept secure to ensure the security of SSL connections to your server, change its ownership to the user that Apache runs as, with a command like chown httpd key.pem. Then set the permissions so that no other user can read it, with the command chmod 600 key.pem.

How that a certificate and private key have been created, you are ready to configure your web server to use SSL. The best way to do this is to create a new virtual server that handles all requests to port 443 (the HTTPS port) in SSL mode. This way any existing virtual servers on your system will not be effected. The exact steps to follow are :

1. On the main page of the Apache Webserver module, click on the Networking and Addresses icon.
2. In the blank row at the end of the Listen on addresses and ports table, select All under the Address column and enter 443 under the Port column. Then click the Save button at the bottom of the page.
3. Back on the main page, scroll down to the Create a New Virtual Server form.
4. Set the Address field to Any, and the Port field to 443.
5. If you want the pages that browsers see when connecting in SSL mode to be the same as those that they see when making a normal HTTP connection, enter the document root directory for your default server into the Document Root field. Otherwise, you can enter a different directory so that clients will see different pages when making HTTPS requests.
6. In the Server Name field, enter the same hostname that you specified for the Common Name when creating the SSL certificate.
7. Click the Create button to have the new virtual server added to your Apache configuration. An icon for it will be added to the module’s main page.
8. Click on the icon for your new server to go to the virtual server options page. An icon labelled SSL Options should be visible – if not, either your Apache webserver does not have the mod_ssl module, or Webmin hasn’t detected it yet.
9. Click on the SSL Options icon to bring up the page shown in the screenshot below.
10. Change the Enable SSL? field to Yes. This tells Apache that the virtual server should treat all connections as HTTPS.
11. In the Certificate/private key file field, de-select Default and enter the full path to the cert.pem file that you created earlier.
12. In the Private key file field, enter the full path to the key.pem file. If you only have a single file that contains both the certificate and private key, you can leave this field set to Default and enter its path into the field above.
13. Click the Save button, and then the Apply Changes link back on the virtual server options page.
14. Unless an error is reported when applying the configuration, your webserver should now be running in SSL mode on port 443. Test it out by using a web browser to go to https://www.example.com/ or whatever the URL of your site is. Note that there is no need to specify port 443 in the URL, as it is used by default for HTTPS, just like port 80 is the default for HTTP.

The SSL Options page

It is also possible to create IP-based virtual servers that use SSL and handle connections to port 443 on particular IP addresses. However, it is not possible to create several name-based virtual servers that use SSL, because the server sends its certificate to the client before any HTTP protocol data is exchanged. Normally the Host: HTTP header is used by Apache to determine which name-based virtual server a request is being made to, but this header has not been send by the browser at the time the webserver selects the certificate to send to the client. The end result is that having multiple named-based virtual servers on the same IP address in SSL mode will not work properly, if at all.

On some Linux distributions, the included Apache package may already include an example virtual server running on port 443 with SSL enabled. It will probably also come with usable certificate and private key files, although they are likely to be self-signed and to have a different hostname for the common name. In this case, there is no need to follow the steps above to set it up – all you need to do is generate your own SSL certificate files, and then visit the SSL Options page in the existing virtual server to change the Certificate/private key file and Private key file fields.

If you want to use Apache to host a real Internet website running in SSL mode, you will need to request a certificate signed by a recognized authority. To do this, you must generate a CSR (certificate signing request) and send it to the authority for verification along with your website’s name, company name and other details to prove that you really do own the website and domain. After they have verified your details, the CA will sign the certificate and send it back to you for use in your webserver.

The exact steps to follow for generating a CSR are :

1. Login to your system as root.
2. Change to the directory in which you want to store your certificate files, such as /usr/local/apache/conf or /etc/httpd.
3. Run the command openssl genrsa -out key.pem 1024. This will create just the private key file key.pem.
4. Make sure that the file can only be read by the webserver user, with commands like chown httpd key.pem and chmod 600 key.pem.
5. Run the command openssl req -new -key key.pem -out csr.pem to generate the CSR.
6. The command will ask the following question, in order to obtain attributes for your new key. To leave any of the requested fields blank, just enter a single period. *Country name *The two-letter code for the country your webserver is in, such as AU or US. *State or Province Name *The name of the state your server is in, such as California. *Locality Name *The city your server is in, such as San Francisco. *Organization Name *The name of your company or organization, such as Example Corporation. *Organizational Unit Name *The name of your division within the company, such as Engineering. *Common Name *The hostname of your webserver as used in the URL. For example, if browsers usually access the server as http://www.example.com/, then you should enter http://www.example.com for this question. Wildcards cannot generally be used in the hostname of certificates signed by CAs. *Email Address *The email address of the administrator for this webserver, such as jcameron@example.com.
7. When all the questions have been answered, the file csr.pem will be created in the current directory. This is your certificate signing request, which should be sent to the certificate authority for signing.
8. After your details have been verified and your money taken, the authority will send you back a signed certificate. It should be a text file that starts with the line —–BEGIN CERTIFICATE—–. Put it in the same directory as the private key, in a file named cert.pem.

If you have over-written existing self-signed private key and certificate files, it is best to stop and re-start Apache to force the new ones to be used. You should now be able to connect to your webserver in SSL mode with no warning displayed in the browser.

Viewing and editing directives

The Apache Webserver module can be used to view and edit directives manually, instead of the usual method of editing them through the module’s forms and pages. Manual editing is only recommended if you are familiar with the configuration file format, as no checking will be done to make sure that you have entered valid directives or parameters. However, it is often faster to configure the webserver in this way, especially if you are an experienced Apache administrator.

On the options page for every virtual server, directory, URL location, filename and .htaccess file there is an icon labelled Show Directives. When clicked on, it will display all of the directives inside that virtual server or directory as shown in the screenshot below. Any directive that the module knows how to edit will be linked to the appropriate form for editing it, which will be one of those that can be reached by clicking on another icon on the virtual server or directory’s options page. Next to each directive is the name of the file that it is located in and the line number in that file, so that you can use another program like vi or emacs to edit it manually if you wish.

Below the list are two buttons, labelled Manually edit directives and Edit Apache directive. The first will take you to the editing form described in the next paragraph. The second will bring you to the form for editing the directive selected from the menu next to it, which will be one of those linked from an icon on the previous page. This can be useful if you know the name of the Apache directive that you want to use, but not where in Webmin it can be edited.

Viewing directives for a directory

To directly edit the text of directives in a virtual server or directory, you can click on the Edit Directives icon located next to Show Directives on every options page. This will display a text box containing the exact text that appears in the Apache configuration file for that server or directory, including any comments and indentation. When the Save button is hit, any changes that you have made will be written back to the file without any verification. To make then active, you will need to click on the Apply Changes link on any of the module’s pages.

It is also possible to edit entire an Apache configuration file at once using the Edit Config Files icon on the module’s main page. When clicked on, the complete contents of the primary configuration file (usually httpd.conf) will be displayed in a text box. Above it is a menu for selecting another file to edit, and a button labelled Edit Directives in File that will switch to the contents of the chosen file. Your Apache webserver may use several different files which Webmin normally hides from you. Only on this page can you see all files that the module has detected are being used, either by default (such as httpd.conf, srm.conf or access.conf) or through Include directives in the default configuration files.

This page is the only place that you can view and manually edit directives that apply to all virtual servers, which are normally editable under the Default Server icon in the module. Because these default directives are usually split across multiple files, no Show Directives or Edit Directives icons appear on the options page for the default server.

If you change any of the directives in the text box, click the Save button below it to have the configuration file re-written. No validation will be done, so be careful with your changes – a mistake with a container directive like <Directory< or </IfModule> may make it impossible for Webmin to parse some or all of the file. As usual, to make the changes active you will need to click on the Apply Changes link back on the module’s main page.

Module access control

As the WebminUsers explains, you can use the Webmin Users module to give a user limited access to some modules. In the case of the Apache Webserver module, a Webmin user or group can be restricted so that he can only edit a subset of the available virtual servers. This can be very useful in a virtual hosting environment in which you want to give people the rights to edit the settings for their own servers, but not those belonging to everyone else.

It is also possible to restrict the pages in the module that the user is allowed to edit, as some allow the setting of directives that could be used to subvert security on your system. For example, you would not want a user to be able to change the user and group that CGI programs on his virtual server run as.

To set up the Apache module for a user so that he can only edit a few virtual servers, the steps to follow are :

1. In the Webmin Users module, click on Apache Webserver next to the name of a user who has been granted access to the module.
2. Change the Can edit module configuration? field to No, so that he cannot change the paths that the module uses for the webserver configuration files.
3. For the Virtual servers this user can edit field, choose the Selected option and select those servers that he should be allowed to manage from the list below. It is generally a bad idea to allow an untrusted user to edit the default server, as its configuration effects all other virtual servers.
4. Change the Can edit global options? field to No, so that he cannot change settings like the ports and addresses that Apache listens on.
5. Change the Can create virtual servers? field to No, so that he is not allowed to add new virtual hosts.
6. To stop him changing the user and group that CGI programs are run as, set the Can change virtual server users? field to No. This only really matters if you have suexec installed, as explained in the Running CGI programs section.
7. Unless you want him to be able to change the address and port that the virtual server accepts requests on, set the Can change virtual server addresses? field to No. If they are changed, they could interfere with other virtual servers.
8. If the Can pipe logs to programs? field is set to Yes, he will be able to configure the virtual server to log to a command which will be run as the user that Apache normally runs as (usually httpd). This may be a security risk on your system, so it is usually a good idea to set this field to No.
9. Change the Can start and stop Apache? field to No. He will be able to apply changes, but not shut down the entire webserver.
10. The Limit files to directory field controls where he can configure the server to write its logfiles to. Allowing them to be written anywhere may allow him to overwrite files, so it is best to set this to something under his home or document root directory, such as /home/jcameron/logs.
11. The Directive types available field determines which icons appear in the virtual server options page, and thus which kinds of directives he is allowed to edit. If you choose All, then all of the icons will be visible, along with the Show Directives and Edit Directives icons for manually editing the configuration files. If you choose Selected instead, only those pages chosen from the list below will be visible, and the manual editing icons will not be. It is usually a good idea to deny access to the User and Group and Log Files pages, and always good to prevent inexperienced users editing the configuration files manually. An error in the httpd.conf file might cause the entire webserver to stop working next time is it re-started.
12. Finally, click the Save button at the bottom of the page. The restrictions will be applied to the user or group immediately.

You should be aware that these restrictions will not stop a truly malicious user causing problems with your Apache configuration. It is quite possible to use the forms to introduce intentional syntax errors into the configuration files which could interfere with the proper working of the webserver. Fortunately, you can always track who has done what using the Webmin Actions Log module, covered on WebminActionsLog.

The MySQL Database -Webmin

source: http://doxfer.com/Webmin/MySQLDatabaseServer

On this page the MySQL? database and the Webmin module managing it are explained, and the steps to follow to create databases, tables and users are listed.

Introduction to MySQL?

MySQL? is a free, easy to use database server that supports multiple databases and tables, and allows clients to query them with SQL. It is most useful for programmers writing applications that need to use a simple database to store information. Popular languages like Perl, C, Java and PHP all have APIs for accessing a MySQL? database.

A MySQL? server can host multiple databases, and each database can contain multiple tables. A table in turn contains fields, each of which has a type and size. Tables contain records, each of which usually contains information about some object, such as a person, product or purchase. Fields can be thought of as the columns in a table, and the actual records of data as the rows.

SQL (which stands for Structured Query Language) is a language for extracting data from or updating data in a database. Almost all databases use SQL, and its syntax is generally the same across all the different database packages, such as Oracle, PostgreSQL? and MySQL? . This chapter does not cover the SQL syntax though, as it is too complex – there are plenty of other good books devoted entirely to it.

Compared to other databases, MySQL? lacks some features. It does not support transactions for most table types, which means that every SQL command is executed immediately and cannot be undone. It cannot execute certain complex SQL commands, particularly those that involve nested queries. Other databases like PostgreSQL? and Oracle support transactions and more complex SQL, and deal better with extremely large tables. PostgreSQLDatabaseServer explains how to use PostgreSQL? , but Oracle being an expensive commercial product is not covered in this book.

Packages for MySQL? come with almost all Linux distributions, and it can be compiled on most Unix variants. Its behaviour is identical on all systems, with the exception that some versions of Unix support larger table sizes due to their filesystems’ support for larger files. On a standard Linux ext2 or ext3 filesystem, a table cannot be bigger than 4 GB. However, the Webmin MySQL? module will behave exactly the same on all operating systems.

MySQL? is divided into two parts – the server which manages the actual files that contain tables and records, and client programs that communicate with a server. The standard mysql client program allows users to execute SQL commands and display their results, while the mysqladmin program is for performing basic administrative tasks, and the mysqldump program is for making backups. Other applications which query the database (such as Webmin itself) are also clients.

The data files in which tables are actually stored are located in subdirectories under a directory like /var/lib/mysql or /usr/local/mysql/var. These files are never read or written by any programs except the MySQL? server, and should not even be copied for backup purposes unless the server process has been shut down.

The MySQL? Database Server module

This module allows you to create databases, tables and fields, edit records and manage MySQL? users through a simple web interface. Its icon can be found under the Servers category, and when you click on it the module’s main page will display a table of icons for existing databases as shown in the screenshot below (assuming MySQL? is installed and running).

The MySQL? Database Server module main page

If the database server is running but Webmin does not know the correct password to login to it with, the main page will display a *MySQL Login* form instead. You should enter the administration username into the Login field (usually root), and the corresponding password into the Password field. Even though it is possible to enter the username and password for any MySQL? user, non-root users cannot perform tasks such as creating databases and tables – and so neither will the module be able to.

By default, the module is configured to login with the username and password that the MySQL? package for your distribution uses by default. Only if you have changed it manually or through Webmin will the MySQL Login page appear.

If the database server is not installed at all on your system, the main page will display an error message like *The MySQL? client program /usr/bin/mysql was not found on your system*. Check your distribution CD or website for all MySQL? -related packages, and install them using the Software Packages module. Often there are several, named something like mysql, mysql-client, mysql-server and mysql-devel. Each Linux distribution seems to use a different set of packages, so make sure you install them all.

On FreeBSD? and NetBSD? , the module expects the MySQL? package for those operating systems to be installed. On other Unix variants, it assumes that you have compiled and installed MySQL? from the source code distribution, available from http://www.mysql.com/.

If the module complains that it cannot find the mysql program even though you have it installed, you will need to adjust the paths that it uses. This can happen if you installed it from the source instead of using the package that comes with your Linux distribution.

The MySQL? module uses SQL commands to perform actions like creating tables, adding fields and editing records. To execute these commands Webmin must connect to the database server, which can be done in one of two ways. It can either run the mysql command with the correct parameters and parse its output, or use the Perl DBI library to connect directly.

The former method is always available, because the mysql command is always installed when the database server is. However, it is not totally reliable as certain kinds of table data produce output that cannot always be parsed. For this reason, you should install the DBI and DBD::mysql Perl modules. If either is missing, a message will be displayed at the bottom of the main page prompting you to install one or both by clicking on a link. This will take you to a page in the Perl Modules module (covered in chapter 27) where DBI and/or DBD::mysql are downloaded and installed for you.

Creating a new database

When MySQL? is first installed, a database called mysql is created that contains authentication and access control related tables. If you want to store your own data, it is best to create your own database to add tables to instead of messing with the mysql database. To do this, the steps to follow are :

1. On the module’s main page, click on the Create a new database link above or below the table of existing database icons. This will take you to a form for entering the new database’s details.
2. Enter a name for the new database into the Database name field. Names should contain only letters and numbers, and no spaces.
3. It is possible to use the form to create an initial table for the new database. However, you can just as easily add one after it is created as the Create a new table section explains.
4. Click the Create button at the bottom of the form to create the database. You will be returned to the module’s main page, which will now include a new database icon.

Creating a new table

Tables can be added to newly created or existing databases at any time. Every table has one or more fields, each of which has a type (such as integer, decimal or text) and a size. Fields can also be indexed, to speed up SQL queries that look up records based on the values in that column.

To add a new table to a database, the steps to follow are :

1. On the module’s main page, click on the database icon. This will bring you to the database editing page shown in the screenshot below, which contains an icon for each existing table and buttons for performing various actions.
2. Enter the number of fields that you want your new table to have into the Fields text box next to the Create a new table button, and then click the button. This brings up a form for entering the details of the new table and its initial fields.
3. Enter a name for this table into the Table name field. It should consist of letters, numbers and the _ character, and must be unique within this database.
4. To have its fields copied from an existing table, select it from the Copy fields from table menu. Any additional fields that you enter below in the Initial fields table will be added after the copied one.
5. The Table type menu can be used to choose a different storage type for this table. The most commonly used types are :
   • MyISAM The standard table type for MySQL? versions 3.23 and above. On operating systems that support large files, tables of this size can be approximately 2,000,000,000 GB in size. Table files are OS independent, keys can be 500 bytes long and 32 key columns can be used in a single table.
   • InnoDB A superior table type that supports transactions, huge amounts of data, and runs much faster that MyISAM? .
   • ISAM The old standard MySQL? table type, now replaced with MyISAM? . An ISAM table file can only be 4 GB in size, keys can only be 256 bytes long, and a table can have at most 16 key columns.
   • Heap The data in Heap tables is stored only in memory. This makes them very fast, but useful only for temporary data as the table’s contents will be lost of MySQL? is shut down. If you select the Default option or if the chosen type is not supported by MySQL? on your system, the MyISAM? type will be used.
6. The Initial fields section is for entering the details of the actual fields that your new table will contain. Each row that you fill in defines a single field, based on the values that you enter under each of the following headings :
   • Field name A unique name for this field, which should consist of letters, numbers and the _ character. It is not a good idea to choose a name that is the same as an SQL reserved word, such as select, update or index.
   • Data type From this menu you must select the type for data in this field. The most common are varchar (for variable length text strings) and int (for integer numbers). See the Field types section below for a complete list of supported types.
   • Type width The size of data that can be stored in this field. This has different meanings depending on the type – for example, for a varchar field the width is the maximum text length, but for an int field it is the maximum number of decimal digits. Once again, the Field types section of this chapter covers widths in more detail. If you leave this text box blank for a field, the default width will be used. Many types (such as blob, text and date) have fixed sizes and so should not have a width entered at all.
   • Primary key? If this box is checked, this field will be part of the primary key for the table. Key fields are indexed by MySQL? , so that SQL statements that refer to all of them in the where clause run faster. However, no two records can have the same values in their primary key field(s). Traditionally, the first field in a table is the key. Not all types can be used – typically, a primary key field is an int or varchar. All tables should have a primary key, so that data in them can be edited in Webmin.
   • Autoincrement? If this option is checked for a numeric field, MySQL? will automatically insert a number one higher than the maximum in the table whenever a record is added (unless the record creation statement specifies a value explicitly). This can be useful for the automatic generation of ID numbers, and is often enabled for primary key fields.
7. Once you have entered all fields, hit the Create button at the bottom of the form. If the table cannot be created for some reason, the SQL error message from MySQL? will be displayed. This can occur if a field name is invalid, or if a type width does not make sense for a type. If this happens, use your browser’s back button to return to the form and fix the problems. Once the table is successfully created, you will be returned to the database editing page which will now include a new table icon.

The database editing page

Adding and editing fields

New fields can be added to a table and existing ones changed or deleted. Adding a field poses no risk to existing data, but changing the type or size of one may – and deleting a field will cause the data that it contains to be lost. To add a new field, the steps to follow are :

1. On the module’s main page, click on the icon for the database that contains the table, and then on the table icon. This will bring up the page shown in the image below, which lists the names, types and other details of all existing fields.
2. Select the type for the new field from the menu next to the Add field of type button before clicking it. See the Field types section below for a list of types and their purposes.
3. On the field addition form that appears, enter a unique name for this field into the Field name text box. No two fields in the same table can have the same name, and only letters, numbers and _ can be used.
4. If you are adding a char or varchar field, you must enter a maximum number of characters into the Type width text box. If adding a float, double or decimal field, you must enter two numbers into the Width and decimals text boxes. The first is the total number of digits that a value can contain, and the second the number of digits to the right of the decimal point. For negative numbers, the minus sign counts as a digit – so a field with Width and decimals set to 5 and 2 could store numbers from 99.99 to 999.99. For date, datetime, time, blob and text fields, there is no width input at all, as these types have fixed or unlimited sizes. For enum and set fields, you must enter a list of possible values into the Enumerated values text box. For all other field types (such as int) the Type width can be either set to Default to have the field use the default size for the chosen type, or a width can be entered. For int fields, this is the maximum number of digits that a value in this field can contain.
5. For integer field types (such as int and smallint), the Type options radio buttons allow you to choose if values in this field should be left-filled with zeros (the Fill with zeros option), or if they should be unsigned (the Unsigned option). If None is selected, values will be signed and no additional zeros will be added. For float, double and decimal fields, the same Type options are also displayed but without the Unsigned option. Fields of these types are always signed. For char and varchar fields, Type options has two different choices – Case sensitive and Case insensitive. If insensitive is selected, SQL queries that match values in this field will ignore case differences.
6. To prevent SQL NULL values being inserted into this field, change the Allow null? input to No. This can be useful if every record should have a value for this field, and must be selected if this field is going to be part of the primary key for the table.
7. To have a default value inserted when a record is added to the table and no value is specified for this field, fill in the Default value text box. Naturally, the value must be of the correct type for the field. If your table already contains some rows, their values for this field will be set to whatever you enter here when the new field is added.
8. If this field is going to be the key for the table, change the Part of primary key? selection to Yes. More than one field part of the key, in which case it is a combination of all of them.
9. Finally, click Create. If there are no errors in your inputs, the field will be added to the table and you will be returned to the table editing page shown in Figure 35-3.

The table editing page

Newly created or existing fields can be edited as well, by following the steps below. However, making changes to the type of a field or reducing its size may result in data loss if the old values are not compatible with the new type. For example, converting a varchar to an int will cause all non-numeric values to be lost – however, converting an int to a varchar is generally safe as long as the new size is large enough.

1. On the module’s main page, click on the icon for the database that contains the table, and then on the table icon. This will bring up the page shown in the screenshot above, which lists the names, types and other details of all existing fields.
2. Click on the name of the field that you want to modify to go to the field editing form.
3. To re-name the field, edit the Field name text box.
4. To change the field’s type, select a new one from the Data type menu. As explained above, this should be done with care.
5. Depending on the current type, different inputs will be displayed for editing its size. These are the same ones as explained in step 4 of the field creation instructions above. Increasing the size of a field will not harm any data that it contains, but decreasing it will cause values to be truncated if they are longer than the new size.
6. The Type options, Allow nulls?, Default value and Part of primary key? inputs have the same meanings here as in the field creation steps. Change them if you want to adjust these options for the existing field.
7. When you are done, hit the Save button at the bottom of the form. The field will be immediately updated, and any data that it contains will be modified or truncated as appropriate.

An existing field can be removed by clicking the Delete button on the field editing form instead of Save. Any data that it contains will be immediately deleted forever. Naturally, you cannot delete the last field in a table.

Field types

MySQL? supports most of the same field types as other SQL databases. The best source of information on types is the official MySQL? documentation, at http://dev.mysql.com/doc/refman/4.1/en/data-types.html (for MySQL? 3 and 4), or http://www.mysql.org/doc/refman/5.0/en/data-types.html (for MySQL? 5).

Newer versions of MySQL? may introduce more types, but you should still be able to edit the data in fields of unsupported types though.

Viewing and editing table contents

The MySQL? module allows you to view the contents of any table in any database. Tables that have a primary key can have their records modified or deleted and new ones added as well. Unfortunately, there is no way to edit the contents of a table without a key, as the module needs some way of identifying specific records. All tables in a database should have one though.

To view the contents of a table, follow these steps :

1. On the main page, click on the icon for the database that contains the table, and then on the icon for the table itself.
2. On the table editing form, click on the View Data button at the bottom. This will bring you to a page containing a table of the first 20 rows in the table.
3. If the table contains more rows than can be displayed on one page, the start and end of the visible range and the total number of rows will be displayed at the top. Next to it are left and right arrows for moving to the next or previous 20 records.
4. For large tables, a search form is also displayed at the bottom of the page. To use it, select a field name from the first menu, a comparison type from the second and enter a value to search for into the final text box. When the Search button is clicked, only rows for which the chosen field matches will be displayed. To switch back to viewing all records, click the Reset search link that now appears above the table. The contains comparison type finds records in which the field contains the entered text, while the matches type finds records for which the field value matches an SQL pattern as used in a like clause. In such a pattern, % matches any string of characters, and _ matches any single character – just like * and ? do at the shell prompt.
5. When viewing a large table, a button labeled Jump to is also displayed at the bottom of the page. If a number is entered into the adjacent field and the button clicked, the display will move immediately to that row.

If the table has a primary key, this same page can also be used to edit, delete or add records. Records to edit must first be selected using the checkboxes to the right of each row, or the Select all and Invert selection links. When you click the *Edit selected rows* button, the page will be re-displayed with the values of all chosen records in text boxes. Make whatever changes you like, and click the Save button at the bottom of the page to update the database. Or hit Cancel if you want to stop editing without saving your modifications.

To delete records, select them using the same checkboxes and selection links, and click the Delete selected rows button. The chosen records will be immediately removed from the database with no further confirmation.

To add a new record, hit the Add row button below the table. An additional row will appear containing empty text boxes for you to enter new details. Clicking Save will add the new record to the table, and move the display so that you can see the new row. Alternately, you can click Cancel if you change your mind about adding a record.

Normally, records are edited or added in text fields that appear in the table in the appropriate columns. However, if you are editing a table that contains a blob or text field, or if the *Use vertical row adding interface* module configuration option is enabled, a different layout is used. Instead, text boxes for fields are listed in a separate box inside or below the table, with field name labels to the right. For text or blob fields, a text box is displayed so that you can enter multiple lines of text if necessary.

Deleting tables and databases

When a table is removed from a database, all records and fields that it contains will be lost. You can remove any table, although deleting those in the mysql database is a bad idea as they contain important MySQL? access control information.

To remove one, the steps to follow are :

1. On the module’s main page, click on the icon for the database that you want to remove the table from, and then on the icon for the table itself.
2. Click on the Drop Table button below the list of fields. This will take you to a confirmation page that asks if you are sure and tells you how many records will be deleted.
3. To go ahead, click the Drop Table button again. Once it has been removed, you will be return to the list of surviving tables in the database.

It is also possible to delete an entire database and all the tables and records in it. Any database can be removed, but deleting the mysql database is a very bad idea. As usual, unless you have made a backup there is no way to undo the deletion.

Assuming you really want to delete a database, follow these steps :

1. On the main page, click on the icon for the database that you want to remove.
2. Hit the Drop Database button below the list of tables. A confirmation page will be displayed, telling you how many tables and records will be lost if you go ahead.
3. To continue with the deletion, click the Drop Database button and you will be returned to the module’s main page when it is done.
4. Alternately, you can choose to remove all the tables and their records by clicking on Just delete all tables instead. The database itself will be left empty.

Executing SQL commands

The MySQL? module also provides a simple interface for running SQL commands on a database and displaying their output. The steps to use it are :

1. On the main page, click on the icon for the database that you want to run commands in.
2. Click on the Execute SQL button below the list of table icons. This will take you to a page for entering SQL commands, running files of commands and loading data into the database.
3. Enter any one SQL command into the text box at the top of the page and hit the Execute button. If there was a mistake in your SQL syntax or the command cannot be executed, the error message from MySQL? will be displayed. Otherwise, a table of results from the SQL (if any) will be shown. Only SELECT statements produce results – UPDATE, INSERT and other commands that modify records do not.
4. When you are done viewing the results, use the Return to Execute SQL form to return to the form.
5. Every command that is executed successfully is added to a history for the database. You can re-run a previous SQL command by leaving the text box empty and selecting it from the menu below, then hitting Execute. To clear out the command history, click the Clear History button instead. This can be useful if it is getting cluttered up with old statements that you don’t need to re-use.

The same page can be used to run multiple commands from a text file and display their output. Because the process is exactly the same as restoring a backup, it is explained in the restore part of the Backing up and restoring a database section below.

Backing up and restoring a database

If one of your databases contains important information, it should be backed up regularly in case a disk failure or SQL mistake causes data loss. It is also a good idea to create a backup before performing some potentially risky operation, such as changing the type of a field or running a complex SQL statement that modifies lots of records.

To use the module to make a backup, the steps to follow are :

1. On the main page, click on the icon for the database that you want to backup.
2. Click on the Backup Database button below the list of tables. This will take you to a form for entering the backup destination and options.
3. In the Backup to file field, enter the full file path that the backup should be written to, such as /tmp/backup.sql. If the file already exists, it will be overwritten.
4. To restrict the backup to only some records, de-select the All rows option for the Only backup rows matching where clause field and enter an SQL WHERE clause into the adjacent field, for example foo = ‘bar’. This only works if the clause is valid for all tables in the database, so in the example all tables would need to have a foo field.
5. If the Add drop table statements to backup? field is set to Yes, the backup will include SQL statements to delete existing tables of the same name when restoring. This means that if you restore it on another system, data in those tables will be replaced with the new data from the backup. If No is selected, the restored data will be added to any that already exists. The best choice really depends on what you are trying to do. For a normal backup, you should select Yes so that any corrupt or conflicting data is removed when the backup is restored. However, if you are transferring records to another system or database No should be selected instead so that existing records in the target table are not lost.
6. To make the backup, hit the Backup Now button at the bottom of the form, and page showing its success or failure will be displayed.

MySQL? backup files are in fact just lists of SQL CREATE TABLE and INSERT statements that when run restore the database to the state it was in when the backup was made. Although this uses more disk space than a more compressed binary format would, it allows you to easy view and modify the file if you wish. It also means that a backup file can be used on a system with a different architecture, as the file contains only ASCII text.

If you have a database that is being used for an important production purpose, it should be backed up regularly, such as once per day. Instead of following the instructions above every day, you can use the Scheduled Cron Jobs module (covered in chapter 10) to create a job that does the backup for you. To find out what command to run, use the instructions above to make a backup first and then visit the Webmin Actions Log module (covered in chapter 54) to see command that it used.

Once a backup file has been created, it can be restored on the same system or on another server running MySQL? . Depending on what the Add drop table statements to backup? field was set to at backup time, the contents of any existing tables with the same names as those in the backup may be deleted. Therefore you should generally only restore if the tables do not exist, or contain outdated or invalid data that you want to overwrite.

Because a backup file is just a list of SQL statements, the restoration process just involves running all the commands in the file. This means that you can follow these same steps to execute a file of your own commands as well :

1. On the module’s main page, click on the icon for the database that the backup should be restored into.
2. Click on the Execute SQL button, and scroll down to the Select SQL commands file to execute on database section.
3. If the backup file is on the system running MySQL? and Webmin, choose the From local file option and enter the full path to the file into the adjacent text field. If the backup is on the PC that your browser is running on, choose From uploaded file and use the Browse button to select the backup file.
4. Hit the Execute button to restore the backup or execute the SQL commands in the file. A page listing all output from MySQL? as the execution proceeds will be displayed. Generally there will be none unless an error occurs or the file contains SELECT statements.

Managing MySQL? users

Your MySQL? database server requires all clients to authenticate themselves with a username and password before they can execute SQL commands. It has its own tables of users, passwords and permissions that are consulted when a client tries to login, rather than the Unix user files /etc/passwd and /etc/shadow. Detailed permissions can be defined for each user, in order to limit the kinds of SQL statements that he can use, the client hosts he can connect from, and the databases, tables and fields that he can modify.

Typically after MySQL? has been first installed, only the root user is able to login. This user will have permissions to access all databases and tables and perform all actions, and so is generally used for administration purposes only. If you want to write an application that uses a database, it is a good idea to create another user for that purpose and set up the application to login as that user.

The standard MySQL? install also creates an Anonymous user with no password and access to databases starting with test. This special user is used for any login attempt for which no other matching user is found. Anonymous users are explained in more detail below.

To add a user, the steps to follow are :

1. On the module’s main page, click on the User Permissions icon. This will take you to a page listing existing users, as shown in the screenshot below.
2. Click on the Create a new user link above or below the table to go to the user creation form.
3. In the Username field, select the second radio button and enter a name for this user. Even though it is possible to create multiple user entries with the same name as explained later, this new one should be unique.
4. Assuming you want the user to have a password, change the Password field to Set to and enter it in the adjacent field. If you choose None, then no password needs to be given, and attempts to login with a password will be rejected.
5. To allow this user to login only from a specific host, select the second radio button in the Hosts field and enter a host name into the text box. The hostname must be the same as the one returned by a reverse lookup of the client’s IP address, which will almost always be a complete hostname like pc.example.com instead of just server. You can enter an IP address instead, or a hostname or IP address SQL pattern like %.example.com. To allow a user to connect only from the same system as the database server is running on, enter localhost as the host. If Any is selected, this user will be able to connect from any host. Be careful when creating a user who has a host specified – if he tries to connect from somewhere else and an Anonymous user exists with a matching host, he will be logged in as the Anonymous user instead!
6. In the Permissions list, select the entries for the actions that you want the user to be able to perform. For an application user, being able to select, insert, update and delete records is usually enough. Un-trusted users should never be given permissions beyond Drop tables, as that would allow him to harm the database, access arbitrary files or enhance his own permissions. If a user does not have any permissions at all, he will be unable to connect unless some have been granted for a specific database or host (as explained in the next section).
7. To create the user, click the Save button at the bottom of the page. The new MySQL? login will be usable immediately, and will have access to all databases and tables with the permissions specified in step 6. See the next section in this chapter for information on how to restrict a user to only certain databases or tables.

The MySQL? user list

When a client tries to login, MySQL? searches for the first matching user and host in the list of users. The server always checks entries with specific hostnames before those that allow any host, and Anonymous user entries before those for a specific user. This means that a user may end up with the Anonymous permissions even though he is in the user list with greater privileges. Due to the confusion this can cause, I recommend deleting all Anonymous user entries unless you fully understand their effects.

It is possible and even useful to have multiple entries for the same user in the list, as long as they have different hostnames. For example, if you want to allow the user fred to login from only clients server.example.com and http://www.foo.com, you would need to create two entries from fred with the Host field set differently. The should have the same password and permissions though, unless you want to require a different password or grant different permissions depending on the host the user is connecting from.

New and existing users can be edited by clicking on their names in the list, which brings up an editing form almost identical to the one used for creating a user. The only different is that the Password field has a Don’t change option which is selected if the user has a password, and which tells Webmin to leave the password unchanged when the user is saved. After making changes, click the Save button at the bottom of the form to update the user in the database. Or to delete it, hit the Delete button. If there are multiple entries for the same user, you will have to update them all individually if changing the password or permissions.

Unless you have already created another administration user with full privileges, the root user should not be deleted. Because this Webmin module normally logs in a root itself, modifying or removing this user may force you to login to MySQL? again as explained in the introduction to the module earlier in the chapter. By deleting the root user or removing its privileges, it is possible to deny yourself access to the database, which can only be fixed using command-line programs like mysqladmin.

Like many other modules, the MySQL? Database Server module can be configured to automatically create, update or delete a MySQL? user when the same thing happens to a corresponding Unix user. This can be useful if you allow some of the Unix users on your system to access databases, and want to keep their passwords and usernames synchronized.

To set up synchronization, the steps to follow are :

1. On the module’s main page, click on the User Permissions icon. Scroll down to the form below the list of existing MySQL? users.
2. If you want a new MySQL? user to be created for each new Unix user, check the Add a new MySQL? user when a Unix user is added box. Then select the permissions that should be granted to the user from the list to the right. When a MySQL? user is automatically added, its will be allowed to login from any host.
3. If you want MySQL? users to be renamed or have their passwords changed when the same thing happens to matching Unix users, check the Update a MySQL? user when the matching Unix user is modified box. If more than one entry exists for the same user, they will all be effected.
4. To have a MySQL? user deleted at the same time as the Unix user of the same name, check the Delete a MySQL? user when the matching Unix user is deleted box. If more than one entry exists for the same user, they will all be deleted.
5. Click the Save button to make the new synchronization settings active.

Managing database, host, table and field permissions

Users created by following the instructions in the previous section have access to all databases on the server with the same permissions. However, it is possible to give a user access to only specific databases by following the steps below :

1. Make sure the user does not have any permissions on the User Permissions page. Any that he has set here will apply to all databases, which is not what you want.
2. On the module’s main page, click on the Database Permissions icon. This will bring up a list of users and the privileges they have for specific databases.
3. Click on the Create new database permissions link above or below the list.
4. In the form that appears, the Databases field controls which databases he will have access to. You can either select the Any radio button to grant permissions for all databases, select the second radio button to grant access to the database selected from the menu, or choose the final button to grant access to databases whose names match the SQL pattern entered into the adjacent field. Typically the second option is the one that you want to select, so that you can grant access to a single database. If the user should have access to more than one, you will need to add multiple database permissions entries.
5. In the Username field, select the second radio button and enter the name of the MySQL? user to whom access should be granted.
6. The Hosts field allows you to choose which client host(s) the user will be able to connect to the database from. You should normally select Any, which gives him access from anywhere – unless the user himself is prevented from connecting from some hosts, explained in the Managing MySQL? users section.
7. From the Permissions list, select the privileges that the user should have for the chosen database. These will be added to any that are set for the user on the User Permissions page.
8. Click the Save button to add and activate the new permissions. You will be returned to the database permissions list.

You can edit database permissions by clicking on a database name from the list. This will take you to an editing form identical to the creation form in which the database, username, hosts or permissions can be changed. The Save button saves and activates any changes, while the Delete button removes the permissions from the database.

When MySQL? is first installed, database permissions for the Anonymous user in the test and test_% databases will be created automatically. Assuming the Anonymous user exists in the User Permissions page, these give anyone who can connect to MySQL? access to records in those databases. Unless you are making use of anonymous logins, these database permissions can be safely deleted.

MySQL? also allows permissions to be granted on databases to all users connecting from certain client hosts. This can be useful if you want to increase the privileges that a particular client system has, such as a web server connecting to your database server. To add host permissions, the steps to follow are :

1. On the module’s main page, click on the Host Permissions icon. This will take you to a page listing existing permissions granted to client hosts, if any. When MySQL? is installed, no permissions of this type are initially defined.
2. Click on the Create new host permissions to bring up a form for adding a new host permissions entry.
3. If the permissions should apply to all databases, select the Any radio button in the Databases field. If they are for only a specific database, select the second radio button and choose a database from the menu next to it. If you want to grant permissions to databases whose names match an SQL pattern, select the final radio button and enter the pattern into the adjacent text field.
4. In the Hosts field, select the second radio button and enter a hostname, IP address or hostname or IP pattern (like %.example.com or 192.168.1.%) into the field next to it. Selecting the Any button isn’t particularly useful.
5. From the Permissions menu, choose those privileges that will be granted to all users connecting to the chosen database from the specified host. These will be added to any other permissions that are granted on the User Permissions or Database Permissions pages.
6. Click the Save button to activate the new client host permissions.

As usual, you can edit existing an host permissions entry by clicking on the database name from the list, editing fields and clicking Save. Or you can remove it with the Delete button.

MySQL? also supports the granting of permissions to specific tables and fields to users connecting from certain hosts. Webmin allows you to set these up by clicking on the Table Permissions and Field Permissions icons on the main page. However, as they are quite complex and rarely used, they are not covered in this chapter.

Module access control

Normally a Webmin user who has access to the MySQL? Database Server module can manage all databases and use all of the module’s features. However, as WebminUsers explains it is possible to restrict what a user can do with a module. In this case, you can grant access to only certain databases, control the directory that backups can be written to, and restrict the creation and deletion of databases. This can be useful if various databases on your server are owned by different people, and you want to give each of them a Webmin login to manage only those that belong to them.

To set up this kind of module access control, the steps to follow are :

1. In the Webmin Users module, click on MySQL? Database Server next to the name of a user or group who has access to the module.
2. On the access control form, change the Can edit module configuration? field to No. This is necessary to prevent the user changing the programs that the module uses for accessing the database.
3. In the Databases this user can manage field, choose the Selected option. Then select the databases he should have access to from the list below.
4. Change the Can create new databases? field to No. There is no reason that a restricted user of this type should be able to add new databases.
5. Unless you want the user to be able to delete his own databases, change the Can drop databases? field to No. Leaving it set to Yes is harmless though, as he will only be able to delete those that you have granted him access to.
6. Change the Can stop and start MySQL? server? field to No.
7. If you want this Webmin user to be able to control access by MySQL? users to his databases, change the Can edit permissions? field to Only for managed databases. This will give him access to the Database, Host, Table and Field Permissions pages, but limit him to viewing and editing entries for the databases he is granted access to. To deny access to MySQL? permission management altogether, select No instead. Choosing Yes is a bad idea, as it would allow the user to create MySQL? users with access to all databases on the server.
8. If the Can edit table data? field is set to No, the user will not be able to create tables, edit fields, run SQL commands or make backups. Instead, he will only be able to use the module’s record viewing and editing feature.
9. When the Login to MySQL? as field is set to Username from Module Config, all database actions performed by this user will be done as the MySQL? user set in the module configuration, typically root. However, you may want the Webmin user to login as a less-privileged MySQL? user as an additional security precaution. This way, even if the user finds a way to defeat the module’s restrictions he will still not be able to execute SQL commands as root. To use a different login, select the Username option and enter a valid MySQL? login and password into the adjacent fields. This alternate user must have the privileges to perform everything that the module needs to do though, such as creating tables and possibly granting permissions.
10. Normally Webmin runs the mysqldump command to make backups as the root Unix user, and allows the backup file to be created anywhere on your system. Because this may allow important files to be overwritten, you should change the Backup file directory field to a safe directory for creating backups in, such as /home/someuser/backup. Better still, the Write backup as Unix user field should be changed to a user other than root, such as the Webmin user’s Unix login. The mysqldump command will be run as this user instead, which prevents it from being used to overwrite files.
11. Finally, to make the new access control restrictions active, click Save.

If you want to give a large number of users access to MySQL? though a web interface, an alternative to configuring the Webmin module for each user is to install Usermin. It has a MySQL? module with an identical interface, and can be easily configured to limit which databases are visible. See chapter 47 for more information.

Configuring the MySQL? Database Server module

Like many other modules, this one has several options that you can set by clicking on the Module Config link in the top-left corner of the main page. Those fields listed under *Configurable option* relate to the module’s user interface and the method it uses to connect to the database, while those under *System configuration* define the paths to the MySQL? programs and files.

Unless you have installed the database server in a different directory to the default for your operating system, fields in the second section do not generally need to be changed. This can happen if you installed MySQL? from the source code instead of using the package supplied with your Linux distribution, or if you have two copies of MySQL? installed and are configuring a clone of the module (covered in WebminConfiguration) to manage the second install.

If you have multiple copies of MySQL? installed on your system, you should clone this module once for each server. The last three configuration options can then be customised to connect to each of the MySQL? installs, which will probably be listening on different ports or use different socket files.

DNS Server Configuration (BIND) -Webmin

source: http://doxfer.com/Webmin/BINDDNSServer

On this page the DNS protocol and the BIND DNS server are explained, as is the Webmin module for creating and managing DNS domains.

Introduction to the Domain Name System

DNS is a protocol used primarily for converting hostnames like http://www.example.com into IP addresses like 192.168.1.10, and vice-versa. At the IP level, all hosts on the Internet refer to each other by IP addresses, not by the hostnames that users enter into programs like web browsers and telnet clients. This means that a system needs a way of finding out the IP address associated with a hostname before they can communicate. Although there are several ways this can be done (such as reading the /etc/hosts file or querying an NIS server), DNS is the most common.

As well as looking up IP addresses for hostnames, the DNS protocol can also be used to find the hostname associated with an IP address. This is most often used for finding the hostname of a client that is connecting to a server, such as a webserver or SSH daemon. DNS can also be used to look up the address of a mail server for a domain, and additional information about a host such as its location, operating system or owner. However, by far its most common application is converting hostnames to IP addresses.

Most systems use the DNS protocol to send requests to a server, which does most of the work of resolving a hostname into an IP address. A normal system is only a DNS client, and never has to answer requests from servers. Almost all companies, organizations and ISPs will already have one or more DNS servers on their network that all the other hosts can use. If your company already has a DNS server, then there is no need to read this page – instead, see the NetworkConfiguration page for information on how to set up your Linux system as a DNS client.

The domain name system is divided into zones (also called domains), each of which has a name like example.com or foo.com.au. Zones are arranged in a hierarchy, which means that the foo.com.au zone is part of the com.au zone, which in turn is part of the au domain. At the very top of the hierarchy is the . or root zone, upon which the entire DNS system depends.

For each zone, there is at one DNS server that is primarily responsible for providing information about it. There may also be several secondary or slave servers that have copies of information from the primary, and act as backups in case the master server for the zone is unavailable. A single DNS server may host multiple zones, or sometimes may not host any at all. A server is typically responsible for providing information about the zones that it hosts, and for looking up information in other zones when requested to by DNS clients.

For a zone hosted by a server to be available to DNS clients that do not query that server directly, it must be registered in the parent zone. The most common parent domains like .com, .net and .com.au are managed by companies that charge for zones registered under them. This means that you cannot simply set up a DNS server that hosts a domain like example.com and expect it to be visible to the rest of the Internet – you must also pay for it to be registered with one of the companies that adds sub-domains to the .com domain.

Each zone contains multiple DNS records, each of which has a name, type and values. The most common type of record is the address or A record, which associates a hostname with an IP address. Other types include the NS or name server record which specifies the DNS server for the zone or a sub-domain, and the MX or mail server record type which defines a host that should receive mail for the zone.

Every zone should have at least one secondary server in case the primary is down or un-contactable for some reason. Secondaries can also share the load on the primary server, because other servers looking up records in the domain will randomly choose a server to query instead of always asking the primary first. In fact, there is no way for other systems to know which server is the master and which are the slaves for a particular zone.

Slave servers can request a copy of all the records in a zone at once by doing a zone transfer. This is done a secondary DNS server when a zone is first added to it, and periodically when it detects that the zone has changed or the records in it have expired. A master server can also be configured to notify slaves when a zone changes so that they can perform a zone transfer immediately, ensuring that they are always up to date.

Every zone has a serial number, which is simply a counter that must be incremented each time any record in the zone is changed. The serial is used by slave servers to determine if a zone has changed, and thus if a transfer is needed. Most of the time, it does not matter what the serial number is as long as it gets incremented. However, some domain authorities require it to be in a certain date-based format, such as YYYYMMDDnn.

Normally a single server hosts either entirely master zones, or entirely slaves. However, this does not have to be the case- a DNS server can be both a master for some zones and a slave for others. There is no upper limit on the number of servers a zone can have, although few have more than three. The important .com and root domains have 13 servers, as they are critical to the functioning of the Internet and frequently accessed. Generally, the more slaves a domain has the better, as long as they can all be kept synchronized.

When a server receives a request from a client to lookup a record, it first checks to see if the record is in one of the zones that it hosts. If so, it can supply the answer to the client immediately. However, if the record is not in a hosted zone then the server must query other servers to find it. It starts by querying one of the servers responsible for the root zone, which will reply with the address of another DNS server. It then queries that other server, which will either provide an answer, or the address of yet another DNS server to ask. This process continues until a server that is responsible for the domain is found and an answer retrieved from it. If the record that the client asked for does not actually exist, then one of the servers in the query process will say so, and the search will be terminated.

For example, imagine if a DNS client asked a server for the IP address of http://www.webmin.com. The steps that would be followed by the server to find the address are :

1. Ask one of the root servers, such as a.root-servers.net (198.41.0.4) for the address of http://www.webmin.com. The server would reply with a list of servers for the .com domain, one of which is a.gtld-servers.net (192.5.6.30).
2. Ask the .com server for the address of http://www.webmin.com. The reply would be a list of servers, one of which is au.webmin.com (203.89.239.235), the master server for the webmin.com domain.
3. As the server for webmin.com for the address of http://www.webmin.com. The reply would be 216.136.171.204, which is the correct IP address.
4. The resulting IP address is returned to the client, along with a TTL (time to live) so that the client knows how long it can cache the address for.

As you can see, a DNS server can find the address of any host on the Internet by following the simple process used in the steps above. The only addresses that it cannot discover are those of the root servers – instead, they read from a file when the server program starts. Because the addresses of the root servers very rarely change, it is safe for a DNS server to store them in a fixed file.

If the steps above were followed exactly for every DNS request, then the root servers would have to be queried every time a client anywhere in the world wanted to lookup an IP address. Even though there are 13 of them, there is no way that they could deal with this massive amount of network traffic. Fortunately, DNS servers do not really query the root servers for every request – instead, they cache results so that once the IP address of a server for the .com domain is known, there is no need to ask for root servers for it again. Because every response from a server includes a TTL, other servers know how long it can be safely cached for.

The relationships between IP addresses and their hostnames are stored in the DNS in a different way to the relationship between hostnames and addresses. This is done so that it is possible to lookup a hostname from an IP using a similar process to the steps above. However, this means that there may be a mismatch between the relationship between an IP address and hostname, and between the hostname and IP address. For example, http://www.webmin.com resolves to 216.136.171.204, but 216.136.171.204 resolves to usw-pr-vhost.sourceforge.net! This can be confusing, but is an inevitable result of the way that queries for IP addresses work.

When a client wants to find the hostname for an IP address like 216.136.171.204, it converts this address to the record 204.171.136.216.in-addr.arpa. As you can see, this is just the IP address reversed with in-addr.arpa appended to the end. The special in-addr.arpa zone is hosted by the root DNS servers, and its sub-domains are delegated to other DNS servers in exactly the same way that forward zones are. Typically each of the final class C zones (like 171.136.216.in-addr.arpa) will be hosted by the DNS server for the company or ISP that owns the matching class C network, so that it can create records that map IP addresses in that network to hostnames. All of these records are of the special PTR or reverse address type.

The biggest problem with this method of reverse zone hosting is that there is no easy way for anything smaller than a class C network (which contains 256 addresses) to be hosted by a single DNS server. So if a server hosts the zone example.com which contains just a single record, http://www.example.com with IP address 1.2.3.4, the same server cannot also control the reverse mapping for the IP address 1.2.3.4. Instead, this will be under the control of the ISP or hosting company whose network the webserver for http://www.example.com is on. Only organizations big enough to own an entire class C network can host the reverse zone for that network on their own DNS server.

Many organizations have an internal network that uses private IP addresses such as those starting with 192.168. A network like this might not be connected to the Internet at all, or connected only through a firewall doing NAT. Some people even have networks like this at home, with several machines connected to a small LAN. Only one of these machines (the gateway) might have a single real Internet IP address assigned by an ISP.

On a private network like this, it can also make sense to run a DNS server to assign hostnames to the systems on the internal LAN. It is quite possible to host a zone called something like home or internal that contains records for internal systems, as well as a reverse zone for the 192.168 network so that IP addresses can be looked up as well. The server can also be set up to resolve real Internet hostnames by querying the root servers, just as any normal Internet-connected DNS server would. However, it will never receive queries from outside the LAN for records in the home network, because as far as the rest of the Internet is concerned that zone does not exist.

The BIND DNS Server module

BIND (Berkeley Internet Name Domain) is the most common DNS server for Unix systems. Several versions have been released over the years, the most recent being version 9. The BIND DNS Server module (found under the Servers category) supports the configuration of versions 8 and 9. The older version 4 has a different configuration file format, and can be configured using the BIND 4 DNS Server module, documented in a later section of this chapter.

Because BIND is available for almost all Unix systems and works identically regardless of operating system, the instructions in this chapter apply not just to Linux but to other versions of Unix as well. Most versions of Unix and Linux include BIND 8 or 9 as a standard package, so it is rarely necessary to install it. If the module cannot find the DNS server, an error message will be displayed on the main page – if this happens, check your operating system CD or website for a BIND package, or download and compile the source from http://www.isc.org/.

BIND’s primary configuration file is /etc/named.conf, which contains all of the zones that the server hosts, and global configuration settings that apply to all zones. The records in each zone are stored in separate files, usually found in the /var/named directory. This Webmin module always updates all of these files directly, instead of by communicating with the running BIND process. This means that if you are running some other program that dynamically updates zones by communicating with BIND (such as a DHCP server), then this module should not be used as it may interfere with these changes. However, very few systems have this kind of dynamic updating activated.

Versions 9 of BIND has some features that version 8 does not. The most important one that is supported by this Webmin module is views. A view is a set of zones that are visible to only some DNS clients. Normally all clients see the same zones, but with BIND 9 you can restrict the visibility of some domains to only particular clients, identified by their IP addresses. This can be useful for creating zones that are only visible to systems on an internal network, even if your DNS server is connected to the Internet.

If you have never set up BIND on your system, when you enter the module for the first time the main page will display a form for setting up the DNS server, as shown below. This form is only shown if Webmin detects that the configuration file named.conf does not exist, or if the zone files directory that is specifies is non-existent. If you are certain that your BIND configuration is valid and that the DNS server is already running, do not click the Create button, as your named.conf file will be overwritten. Instead, click on the Module Config link and check that all the paths are correct for your system.

The BIND setup form

If you are setting up BIND for the first time, the setup form gives you three choices :

• Setup nameserver for internal non-internet use only
  If you choose this option, your DNS server will be set up so that it can only resolve records in zones that it hosts. This is only useful on a private network that has no Internet connection at all.

• Setup as an internet name server, and download root server information
  This is the most useful option – it sets your DNS server up to be able to host zones and to lookup records on the Internet. In order to query other Internet domains, a list of the root zone servers is needed, as explained in the introduction. When this option is selected, Webmin will FTP to rs.internic.net and download a file listing the server names and IP addresses for inclusion in the BIND configuration.

• Setup as an internet name server, but use Webmin’s older root server information
  This option is identical to the previous one, but does not download the root zone file. Instead, it uses a copy of the file that comes with Webmin which may not be as up to date. However, if for some reason your system cannot connect to the rs.internic.net FTP server, this is your best choice.

Depending on which option you choose, a basic named.conf file will be created the root zone added to it. The module’s main page will then be re-displayed, so that you can add more zones or configure the server further.

When BIND has been set up on your system, the main page will appear as shown in the screenshot below. At the top is a table of icons for setting global options that apply to your entire DNS server. Below them are icons for each of the zones your server hosts, followed by icons for views if you are running BIND version 9. At the very bottom are buttons for applying the current DNS configuration or starting the BIND server.

If you have just set up BIND for the first time, there will probably be only one zone icon – the root zone. Some Linux distributions that include a BIND package come with a basic configuration file that defines zones like localdomain and 127.0.0, which are used for resolving the localhost and 127.0.0.l loopback hostname and IP address.

The BIND DNS Server module main page

Creating a new master zone

A master zone is one for which your DNS server is the authoritative source of information. A single zone may be hosted by multiple servers, but only one is the master – all the rest are slaves. If you want to add a new master zone to your server’s configuration, the steps to follow are :

1. Decide on a name for the new zone, such as example.com or internal. If this is going to be Internet domain that will be visible to other everyone in the world, the domain name must not have been registered by anyone else yet. However, you cannot normally register it yourself until your DNS server has been set up to host it.
2. On the module’s main page, click on the Create a new master zone link below the table of existing zones. This will take you to the page shown in the image below for entering the details of the new zone.
3. If this is to be a forward zone like example.com or foo.com.au, leave the Zone type field set to Forward. However, if it is a reverse zone for looking up hostnames from IP addresses, set the field to Reverse.
4. In the Domain name / Network field, enter the name of the zone without any trailing dot. For a reverse zone, just enter the network address like 192.168.1. Webmin will automatically convert this to the in-addr.arpa format for you when the domain is created.
5. The Records file field controls where the configuration file containing the zone’s records is stored. If you leave it set to Automatic, the filename will be determined automatically based on the module’s configuration and the directory setting in the named.conf file. This is usually the best option, as it will result in the records file being created in the same directory as any existing zones, such as /var/named. However, if you de-select the Automatic option and enter a filename instead, all records for the zone will be written to that file. If you enter the name of an existing file, it will be overwritten when the domain is created.
6. In the Master server field, enter the full domain name of the master DNS server for this zone. This must be the canonical name of your system, such as server.example.com, not a short name like server. This server (and the values from the next
7. fields) are used to create the new zone’s SOA record.
8. In the Email address field, enter the address of the person responsible for this zone. You can use the @ symbol in the address, which Webmin will automatically convert to a dot for inclusion in the SOA record.
9. The Refresh time field determines how often secondary servers should check with this master server for updates to the zone. The default is reasonable, but you may want to increase it for zones that rarely change, or decrease it for those that are frequently updated.
10. The Transfer retry time field determines how long a secondary server should wait after a failed zone transfer before trying again.
11. The Expiry time field controls the maximum amount of time that a secondary DNS server for the zone should cache records for before re-transferring them from the master.
12. The Default time-to-live field determines the TTL of records in the zone that do not have one set explicitly.
13. Click the Create button at the bottom of the page. As long as the form has been filled in correctly and the zone does not already exist on your server, you will be taken to a page for adding new records to the zone.
14. Return to the module’s main page which will now include an icon for your new zone, and click the Apply Changes button at the bottom to activate it.

The master zone creation form

A newly created zone will contain only one record (unless you have set up a template). To add more, follow the instructions in the next section. Once you have set up the basic records in your domain, you can register it with the authority that manages the parent domain, such as .com or .com.au. Some domain authorities will not allow you to register zones that do not have at least two servers (one master and one slave), and name server records in the zone for those servers.

Adding and editing records

The most useful feature of the BIND DNS Server module is the ability to add, edit and delete records in the master zones hosted by your server. For example, if you wanted to set up a webserver in your domain example.com, you would need to add an Address record for http://www.example.com with the IP address of the server. To add a new record like this, the steps to follow are :

1. On the module’s main page, click on the icon for the zone that you want to add to. This will bring up the page shown below, at the top of which is a table of icons, one for each record type.
2. Click on the icon for the type of record that you want to add. The most common type is Address, which associates an IP address with a hostname. See the Record types section below for a complete list of all the supported record types.
3. Clicking on the icon will take you to a page listing all existing records of that type. Above the list is a form for entering a new record.
4. In the Name field, enter the name of the new record relative to the zone name. For example, if you wanted to add the record http://www.example.com, you should just enter www. It is also possible to enter the full record name, as long as it has a dot at the end to indicate that it is not relative to the zone. Do not enter just http://www.example.com, as it will be converted to http://www.example.com.example.com, which is probably not what you want.
5. If this record is going to change more frequently than the rest of the zone, change the Time-To-Live field from Default to the estimated time between changes. This determines how long DNS clients and other servers will cache the record for.
6. If you are adding an Address record, enter the complete IP address of the host into the Address field. See the table below for a description of the fields that appear when adding other types of records and what they mean.
7. The field Update reverse? only appears when adding an Address record. It controls the automatic creation of a corresponding record in a reverse zone which associates the hostname with the IP address. Naturally, this can only be done if the IP that you enter is in a network that your system is the primary reverse DNS server for. This keeps the forward and reverse zones synchronized, which can be very useful. If Yes is selected, a reverse address record will be added as long as one does not already exist in the reverse zone for the same IP address. Often many hostnames will have the same IP, such as those use for name-based virtual hosting. In cases like these, you don’t want to change the reverse mapping if one already exists. The Yes (and replace existing) option works the same as Yes, but if a reverse record for the IP address already exists it will be updated with the new hostname. This can be useful if you know there is an existing record that you want to replace. If No is selected, no reverse address will be created even if it is possible.
8. When you are done filling in the form, click the Create button at the bottom. As long as it is filled in correctly, the record will be added to the list below the form. When writing to the zone’s records file, Webmin will use the full canonical format for the record name, such as http://www.example.com., even if you just enter www.
9. To activate the new record so that it can be looked up by DNS clients and other servers, you will need to click the Apply Changes button on the module’s main page. If you are planning to add or edit several records, it is usually better to wait until all the changes are complete before hitting the apply button. If it is available, you can instead use the Apply Changes button at the bottom of the master zone page shown below. This uses the ndc command to tell BIND to re-read only the file for this zone, which can be much faster on a system that hosts are large number of domains.

The master zone editing page

Although the instructions above are focused on adding an Address record, the process of adding other record types to a forward zone is almost identical. The Update reverse? field does not exist, and the Address field is replaced with one or more different fields. The Record types section below explains in detail what fields are available for each type of record known to Webmin.

When adding a Reverse Address record to a reverse zone, the form is quite different. The Address field appears before the Hostname, and the hostname must always be entered in canonical form with a dot at the end, like http://www.example.com.. The Update reverse? field is replaced with Update forward?, which controls the automatic creation of a record in the corresponding forward zone. However, there is no option to overwrite an existing forward record – if one with the same name already exists, it will not be touched even if Yes is selected.

Every time a record is added to or updated in a zone using Webmin, its serial number will be automatically incremented. This also applies to reverse zones that are automatically updated when adding an Address record, and vice-versa. This means that when you apply the changes, other DNS servers will be able to detect that the zone has changed by comparing the new serial number with the old one that they have cached.

To edit an existing record in a zone, the steps to follow are :

1. On the module’s main page, click on the icon for the zone that you want to edit, which will bring you to the page show above.
2. Click on the icon for the type of record that you want to change, which will display a page listing all records of that type in the zone. Alternately, you can click on the All Record Types icon which will bring up a list of every single record in the zone regardless of type.
3. Click on the name of the record that you want to edit. Your browser will display a form similar to the one used for adding a record, but with the fields already filled in with the details of the existing address.
4. To re-name the record, edit the contents of the Name field. It will be shown in canonical form with a dot at the end initially, but you can change it to a name relative to the domain if you wish.
5. Adjust the Time-To-Live field in you want this record to have a different TTL, or set it to Default to make it the same as the rest of the zone.
6. If this is an Address record, change the IP in the Address field. For other record types, the fields are the same as those on the record creation form, and have the same meanings.
7. For Address records, the field Update reverse? is displayed. Selecting Yes will cause the corresponding record in the reverse zone to be have its name and address changed to match this forward record. If you change the IP so that the reverse address is no longer in the same network, it will be removed from the old reverse zone and added to the new reverse zone (if it is hosted by your server).
8. For Reverse Address records, the field Update forward? is shown instead. If Yes is selected, the corresponding Address record in its forward zone will be changed to match any changes that you make on this form.
9. Click the Save button to update the record in the zone file, and return to the list of record types.
10. To activate the changes, click the Apply Changes button back on the module’s main page.

To delete a record from a zone, click on the Delete button on the editing form instead of Save. For Address records, if the Update reverse? field is set to Yes, the corresponding Reverse Address record will be deleted as well. Apart from that, the process of deleting a record is identical no matter what type it is. The same thing happens when deleting a Reverse Address record – the matching Address record is deleted as well, as long as the *Update forward?* field is set to Yes.

The list of records in a zone is initially sorted according to the module configuration, which usually means that records will be displayed in the order that they were added. To change this, you can click on a column heading like Name, Address or Real Name to sort them by that column instead. The sorting is only temporary though, and will be lost if you return to the main page and re-open the zone. To change it permanently, see the Order to display records in field in the section on *Configuring the BIND DNS Server module*.

Record types

Webmin does not support all of the record types that BIND knows about, only those that are most commonly used. The list below covers all of the supported types, and explains what they are used for and what fields are available when adding or editing a record of that type in Webmin. Next to each type name is the short code used by BIND itself for identifying the type in the records file.

• Address (A) An Address records associates an IP address with a hostname. Any system that you want to be able to connect to via HTTP, telnet or some other protocol using its hostname must have an address record so that clients can look up its IP. A single hostname can have more than one Address record, which is often done to spread the load for a website across multiple servers. It is also valid to create multiple records of this type with different names but the same IP, such as when setting up name-based Apache virtual servers. When creating or editing an Address record, the field Address is displayed for entering the IP associated with the hostname. A field labelled Update reverse? also appears, which controls the automatic creation and modification of a Reverse Address record in the appropriate reverse zone. See the Adding and editing records section above for more details.

• Name Sever (NS) Records of this type defines a name server that is responsible for a zone. Every zone must have at least one Name Server record for itself, and may have additional records that specify the DNS servers responsible for subdomains. If you set up a secondary DNS server for a zone, be sure to add a Name Server record for the zone on the master server. In this case, the name of the record will be the canonical name of the zone, such as example.com.. When creating or editing a record of this type, a field labelled Name Server will be displayed. This must be filled in with the IP address or hostname of the DNS server that is responsible for the zone. If you enter a hostname, it must have an IP address set by an Address record in some zone on your server.

• Name Alias (CNAME) This type of record creates an additional name for an existing Address or Reverse Address record. When a DNS client requests the IP address of a record of this type, it will get the IP of the record that the Name Alias points to instead. This kind of record can be useful if you have a single host that needs to be accessible under several different names, such as a web server doing name-based virtual hosting. Even though this could also be done by creating multiple Address records, creating just a single Address and multiple Name Aliases is more flexible as it allows easier updating if the IP address of the host ever changes. The forms for editing and creating Name Alias records contains a field labelled Real Name. This must be filled in with either the canonical name of the record that the alias points to (such as webserver.example.com.), or with a short name that is relative to the zone that the Name Alias record is in.

• Mail Server (MX) Mail Server records tell mail delivery programs like Sendmail and Qmail which system to contact when delivering mail to a domain or host. Without a record of this type, mail for a domain will be delivered to the system whose IP is specified in the Address record for the zone itself. This is not always desirable, as you may want that IP to be the address of a webserver, so that web browsers can connect to http://example.com/ as well as http://www.example.com/. A Mail Server record can solve this problem by having only email for example.com sent to another hosts, and all other traffic to the webserver. Each Mail Server record has a priority, which tells mail delivery programs which mail server should be tried first. The record with the lowest priority should point to the system that actually receives and stores email for the domain, while those with higher priorities generally point to systems that will simply relay mail. Delivery programs will try each in turn starting with the lowest, so that if the primary mail server is down email will still be sent to a relay that can hold it until the primary comes back up.

When adding or editing a Mail Server record, two additional fields are displayed. The first is labelled Mail Server, and must be filled in with the canonical or relative hostname of a system that can accept mail for the domain or hostname entered in the Name field. The second is labelled Priority, and must be used to specify a numerical priority for this particular mail server. Normally a priority of 5 is used for the primary mail server, and 10 for backup relays. If you only have one mail server for your domain, it doesn’t really matter what number is entered into this field. It is possible for two servers to have the same priority, in which case one will be chosen randomly to deliver to. A Mail Server record can use the * wildcard in its name, which indicates to mail programs that a particular mailserver is responsible for all hosts in a domain. For example, a record named like *.example.com would match the hostname pc1.example.com and any other hosts in the zone. This can be useful if you want to force mail that would otherwise be delivered directly to workstations in your domain to go through a central mailserver instead. Webmin will not let you use wildcards unless the Allow wildcards module configuration option is set to Yes though, as explained in the *Configuring the BIND DNS Server module* section.

• Host Information (HINFO) Records of this type are used to record information about the hardware and operating system of a particular host. For example, you might create one that says that server1.example.com is an x86 PC running Linux. However, they are very rarely used and are in fact considered a security risk, as they give out information to potential attackers that could be used to take over a server. When creating or editing a Host Information record, the fields Hardware and Operating System are displayed for entering the architecture and operating system type of a host. The values you enter must not contain any spaces – typically, they are replaced in the hardware type and operating system strings with _ characters.

• Text (TXT) A Text record associates an arbitrary message of some kind with a name. Although they are hardly ever used, they can be useful for attaching comments to hostnames. Be aware though that any such comments will be available to anyone on the Internet that can look up records in your domain, and so should not contain sensitive information. The field Message is displayed when entering or editing a Text record. You can enter any text that you like, including spaces.

• Well Known Service (WKS) A record of this type associates a hostname, port and protocol with a name. It can be thought of as a generalized variant of the Mail Server record, which tells clients which host provides a particular service for some domain or hostname. However, almost no programs actually look up WKS records, so in practice they are pretty much useless. When adding or editing one of these records, the fields Address, Protocol and Services are available. The first is for entering the IP address of a host that provides the services for the host or domain entered into the Name field. The second is for selecting the network protocol that the services use, either TCP or UDP. The last is for entering a list of port numbers or names (from the /etc/services file) for services that the host provides.

• Responsible Person (PR) This type of record is used for specifying the person or group responsible for a particular host. Each of these records has two values associated with it – an email address, and the name of Text record containing the person’s name. Responsible Person records are rarely seen, and are not used by any mail delivery program or Internet client. The Email Address field shown when editing or adding one of these records is for entering the complete address (like jcameron@example.com) of the person responsible for the host whose name is entered into the Name field. The Text Record Name field is for entering the relative or canonical name of a Text record that contains the person’s real name.

• Location (LOC) Location records are used to specify the physical location in latitude and longitude of a host. They are hardly ever seen, and thus not used by many programs. However, they can be useful in large organizations that have hosts in many countries. When adding or editing a Location record, the field Latitude and Longitude is displayed for entering the location of the host in the Name field. It must be formatted like 42 21 43.528 N 71 05 06.284 W 12.00m 30.00m 10000.00m 10.00m.

• Service Address (SRV) Records of this type are used to associate a domain name, service name and protocol with a particular host. They allow you to specify which server a client should contact for a particular service and hostname, instead of just connecting to the host. In a way, they are like Mail Server records but far more flexible. For example, you can specify that the POP3 server for example.com is mail.example.com, but the webserver is http://www.example.com. At the time of writing, SRV records are mostly used by Windows client systems.

When adding or editing a Service Address record, the fields Protocol and Service name are displayed near the Name text box. For the protocol, you must select either TCP or UDP from the menu. For the service name, you must enter a well-known name from the /etc/services file, such as pop3 or telnet. To look up an SRV record, a client combines the service name, protocol and name to get a record name like ___telnet.___tcp.example.com. Webmin does this for you automatically when editing or adding a Service Address record, but you can see the combined name on the page listing records of this type. Webmin also automatically added the _s before the service and protocol, but hides them when a SRV record is being displayed or edited. This means that there is no need to enter then manually when creating or editing a record of this type. The Priority field must be used to enter a numeric priority for this server, which has the same meaning as the priority in a Mail Server record. The Weight field must contain a weighing for this particular server, or zero if there is only one record with the same name, protocol and service name. A higher weighting tells clients to try this server more often than one with a lower weight. The Port field must contain a port number for clients to connect to on the server, which does not necessarily have to be the standard port for the service. In the Server field, you must enter the hostname or IP address of the system that actually provides the service, and that clients actually connect to.

The record types support by Webmin in reverse zones are :

• Reverse Address (PTR) A reverse address record associates a hostname with an IP address in a reverse zone. For DNS clients to be able to lookup hostnames from IP addresses in your network, you will need to create one record of this type for each host. However, most of the time this is done automatically by Webmin when adding and editing Address records. If you create your own Reverse Address records, make sure that they are synchronized with the matching Address records. When adding or editing a record of this type, the fields Address and Hostname are displayed. The first is for entering a complete IP address, like 192.168.1.10. This will be automatically converted by Webmin to the in-addr.arpa format used internally by the DNS system for reverse addresses. The second field is for entering a hostname in canonical form, such as pc1.example.com., be sure to always put a dot at the end, or else the hostname will be relative to the reverse zone, which is definitely not what you want.

• Name Server (NS) Name Server records in a reverse zone have an identical purpose to those in a forward domain – they tell other DNS servers the IP address or hostname of a server responsible for the zone or a sub-domain. This means that one must be added for each primary or secondary DNS server for the zone. The Zone Name field that appears when adding or editing a record of this type is for entering the name of the zone that the server is responsible for, which will typically be the zone that contains the record. However, unlike Reverse Address records this field is not automatically converted to in-addr.arpa format. Instead, you must enter it in fully qualified form like 1.168.192.in-addr.arpa. if defining an nameserver for the 192.168.1 network. In the Name Server field, you must enter an IP address or canonical form hostname for the DNS server, such as ns1.example.com..

• Name Alias (CNAME) Records of this type behave exactly the same in reverse zones as they do in forward domains. However, you must fill in the Name and Real Name fields with reverse names in in-addr.arpa format, as Webmin will not convert them for you. Name Alias fields are most useful in reverse zones for doing partial subnet delegation, as covered in the Partial reverse delegation section below.

Editing a master zone

You can use Webmin to edit many of the settings that apply to an entire master zone, such as the expiry and retry times, and the clients that are allowed to query it. These settings effectively apply to all records in the zone, although some (such as the TTL) can be overridden on a per-record basis.

Webmin uses the term zone parameters to refer to all information stored in the domain’s SOA record, including the primary nameserver, administrator email address and retry and expiry times. All of these are set when the zone is created, but you can edit them at any time by following these steps :

1. On the module’s main page, click on the icon for the zone that you want to edit.
2. Click on the Zone Parameters icon, which will bring up a form for editing the parameters.
3. The Master server field only needs to be edited if the Internet hostname of the DNS server has changed. Enter a fully-qualified hostname, with a dot at the end.
4. To change the address of the person responsible for the zone, edit the Email address field. Any @ symbols that it contains will be automatically converted to dots for use in the SOA record, as BIND requires.
5. The Refresh time, Transfer retry time, Expiry time and Default time-to-live fields all have the same meanings as explained in the section on Creating a new master zone. If records in your zone are going to be changing frequently in future, you may want to reduce some of these times. However, any changes, may not be detected by secondary servers and DNS clients until the old refresh or expiry time has elapsed, even if the new times are much lower. This is because they will wait for the old times to elapse before checking with the master server again to discovered the new ones.
6. Click the Save button at the bottom of the page when you are done, and then the Apply Changes button back on the module’s main page. The serial number in the SOA record will be automatically incremented when the form is saved, so that secondaries now that the zone has changed.

The is another set of options that you can edit for a master zone, stored in the named.conf file in the zone’s section. These control which servers and clients are allowed to query records in the zone, do zone transfers and update records over the network. The most useful of these options specifies a list of slave DNS servers for the zone that should be notified when a change occurs, so that they can perform immediate zone transfers and thus remain synchronized.

To edit these master zone options, the process to follow is :

1. On the module’s main page, click on the icon for the zone that you want to edit. This will take you to the form shown in Figure
2. -4.
3. Click on the Edit Zone Options icon, which will bring up a form showing the existing settings.
4. The Check names? field determines the level of checking that BIND performs on records in this zone when it reads the records file. The available options are :
   • Warn If an invalid record is found, an error will be written to the system log file but processing of other records continues normally.
   • Fail Invalid records cause the entire zone to be rejected, but other zones will still be processed normally.
   • Ignore No checking is done at all.
   • Default The global default from the Zone Defaults page is used. If it is not set, then the default complied into BIND will be used instead, which is to fail when invalid records are encounterd.
5. To have secondary servers notified when records in the zone change, set the Notify slaves of changes? field to Yes. BIND works out which slaves will be notified by looking at the Name Server records for the zone, and the list of IP addresses in the Also notify slaves field. If your zone has an secondary servers, then you should definitely turn this option on.
6. To allow some systems to update records in the zone dynamically, fill in the Allow updates from field with a list of IP addresses, IP networks (like 192.168.1.0/24) and BIND ACL names. Only those hosts that match will be able to modify records using commands like nsupdate, and if the list is left empty updates will not be allowed at all. You should be careful allowing the dynamic update of zones in which Webmin is also being used to edit records, as it is very likely that updates made dynamically will be overwritten by changes made in this module, or vice-versa.
7. By default, all DNS clients and servers will be able to lookup records in the zone. This may not be what you want for a zone that is used only on an internal network, as it may give away sensitive information to potential attackers. To restrict queries, fill in the Allow queries from field with a list of IP addresses, IP networks and BIND ACL names. If the field is left empty, the field with the same name on the global Zone Defaults page determines which clients are allowed.
8. To restrict the clients and servers that are allowed to perform zone transfers of all the records in this domain, fill in the Allow transfers from field. Often you will only want to allow secondary servers to perform transfers, especially if your zone is very large or contains records that you want to hide from attackers. Enter a list of IP addresses, IP networks and ACL names into the field to limit transfers to only matching clients. If it is left empty, the Allow transfers from field on the Zone Defaults page applies instead.
9. To specify additional slave servers to be notified when the zone changes, fill in the Also notify slaves field with a list of IP addresses. BIND normally works out with addresses of all secondary servers for the zone from its Name Server records, but this may not always be complete.
10. When you are done, click the Save button at the bottom of the page to update the BIND configuration file with your changes. You will need to use the Apply Changes button on the module’s main page to make them active.

If a master zone is no longer needed, you can use this Webmin module to totally delete it along with all the records that it contains. To do this, the steps to follow are :

1. On the module’s main page, click on the icon for the zone that you want to edit.
2. Click on the Delete Zone button at the bottom of the page.
3. When deleting a forward zone, the field Delete reverse records in other zones? controls whether matching Reverse Address records in hosted reverse zones for all of the Address records in this one should be removed as well. This is generally safe to set to Yes, as only records with the exact same IP address and hostname will be deleted.
4. Similarly, when deleting a reverse zone the field Delete forward records in other zones? determines whether matching forward records should be deleted too.
5. Once you have made your selection and are sure you want to go ahead with the deletion, click the Delete button. The zone’s entry in the named.conf file will be removed, and its records file deleted.

You can convert a master zone to a slave zone of the same name without needing to delete and re-create it. This can be useful if the new server is taking over as the master for some domain, or if the master and secondary servers are switching roles. The section on *Editing a slave zone* explains how to carry out the reverse action of converting a slave zone to a master, which may be useful in this situation.

To convert a zone, the steps to follow are :

1. On the module’s main page, click on the icon for the zone that you want to edit, then on the Edit Zone Options icon.
2. When you click on the Convert to slave zone button, zone’s entry in named.conf will be immediately updated to convert it to a slave zone. The browser will then return to the module’s main page.
3. Normally, every slave zone has a list of master server IP addresses that it can use to perform zone transfers from. In the case of converted zones, this list will be initially empty unless the Default master server(s) for slave zones module configuration option is set. Follow the instructions in the Edit a slave zone section to set the master servers addresses correctly.
4. To activate the change, click on the Apply Changes button the module’s main page.

Creating a new slave zone

A slave or secondary zone is one for which your DNS server gets the list of records from a master server for the zone. Generally, slave servers are used to reduce the load on the primary server, or act as a backup in case it goes down. For important zones (such as a company’s Internet domain), you should always have at least one slave server so that your website is still accessible and email can still be delivered even if the primary goes down.

The secondary DNS server for a domain should not usually be located on the same network as the master, so that the failure of that network cannot take them both down. Many ISPs and hosting companies will host secondary zones for their customer’s domains for free, on their own DNS servers. If your ISP provides this service and you want to set up a secondary server for an Internet domain, you should take advantage of it. If so, most of this section can be skipped. However, if you want to add a slave server for an internal domain or have a large company network with many connections to the Internet, then the instructions below explain how to set it up :

1. On the main page of the BIND DNS Server module, click on the Create a new slave zone link above or below the list of existing zones. This will bring up the form shown below, for entering the details of the new domain.
2. For a forward zone like example.com, set the Zone type field to Forward and enter the zone name into the Domain name / Network field. For a reverse zone that maps IP addresses to hostnames for a network, choose the Reverse option and enter the network address (like 192.168.1) into the Domain name / Network text field.
3. The Records file field determines if BIND keeps a cache of the records in this zone in a file, and if so where that file is located. If the option None is chosen, records that the DNS server transfers from the master will be kept in memory only, and lost when the server is re-started. This should only be chosen if there is a good network connect between the master and slave servers, as it will increase the number of zone transfers that your server must perform. If you choose Automatic, Webmin will generate a filename in the zone files directory specified in the named.conf file (usually /var/named). Whenever your server does a zone transfer, all records will be written to this file in the standard format. If the final option is selected, you can enter the full path to a file in which records should be stored into the field next to. This can be useful if you want to separate the records files for master and slave zones.
4. In the Master servers field, enter the IP addresses of the master DNS server and any other secondary servers for the zone. BIND will try these servers in order when doing a zone transfer, so the master should be first on the list. You must enter at least one address, so that your server knows where to get records from.
5. Click the Create button to have the new slave zone added to your server’s configuration. Your browser will be re-directed to a page for editing options for the zone.
6. Return to the module’s main page, and click the Apply Changes button on the main page to make the addition active.
7. On the master server, add a new Name Server (NS) record for the zone with the IP address of the secondary server. This can be easily done in Webmin by following the instructions in the Adding and editing records section.
8. Configure the master DNS server to notify this slave of any changes to records in the zone. The steps in the section on Editing a master zone explain how.
9. If this is an Internet domain, notify the registrar for the parent zone of the new secondary server. Most provide online forms for editing the list of nameservers for a domain, to which you can add the secondary’s IP. This is necessary so that other hosts on the Internet know to use the slave server is the master is down.

The slave zone creation form

Another type of zone that is closely related to the slave zone is the stub. They are like slave zones, but only contain Name Server records that have been transferred from a master server, instead of all the records. Stub zones are rarely used, but can be useful for ensuring that the Name Server records in a zone for its sub-domains are the same as those use in the sub-domain itself. The steps for creating one are almost identical to those above, but in step 1 you must use the Create a new stub zone link on the main page instead.

Editing a slave zone

After a slave zone has been created, it is still possible to edit several options that apply to it. Naturally there is no way to add or edit the actual records within the zone, but you can still change the list of master servers, the records file and the clients that allowed to query it. To change these setting, the steps to follow are :

1. On the module’s main page, click on the icon for the slave zone that you want to edit. Your browser will display the form shown in the screenshot below.
2. Scroll down to the Zone Options form at the bottom of the page.
3. To edit the list of other master and slave servers for this zone, change the IP addresses in the *Master servers *field. If a new secondary server has been added, it should be added to this list on all other secondaries so that they can do zone transfers from it. If the IP address of the master has changed, the list must be updated with the new address.
4. To change the amount of time that the server will wait before giving up on a zone transfer, de-select Default for the Maximum transfer time field and enter a number of minutes into the text box next to it.
5. If the Records file field is set to None, records transferred from the master server for this zone will be kept in memory only. However if a filename is entered, records will be written to that file instead in the standard format. This is the best option, as it minimizes zone transfers and allows you to view the records on the secondary server, as explained below.
6. To have this DNS server notify others when the zone changes, change the Notify slaves of changes? field to Yes. This is only really useful if there are other secondary servers that perform zone transfers from this one, and may not be able to receive update notifications from the master server. The DNS servers to notify are determined from the Name Server records for the zone, and the contents of the Also notify slaves field.
7. By default, all DNS clients and servers will be able to lookup records in the zone. To change this, fill in the Allow queries from field with a list of IP addresses, IP networks and BIND ACL names. If the field is left empty, the field with the same name on the global Zone Defaults page determines which clients are allowed.
8. To restrict the clients and servers that are allowed to perform zone transfers of all the records in this domain, fill in the Allow transfers from field with a list of IP addresses, IP networks and ACL names. If it is left empty, the Allow transfers from field on the Zone Defaults page applies instead.
9. The other fields on the form such as Check names? and Allow updates from? are not really used for slave zones, and so can be left unchanged.
10. When you are done making changes, click the Save button. As long as there were no syntax errors in your input, you will be returned to the module’s main page. Click the Apply Changes button there to make the modifications active. Note that this will not always force a re-transfer of the zone, even if the master servers have changed. For slave zones that use records files, BIND will only do a transfer when it the zone expires or the server receives notification of a change.

The slave zone editing form

When editing a slave zones that uses a records file, it is possible to browse the records in Webmin. At the top of the page that appears when you click on the slave zone’s icon is a table of record types, just like the one that appears on the master zone form. Each can be clicked on to list the names and values of records of that type in the zone, as known to the secondary server. Editing or adding to them is impossible of course, as any changes must be made on the master server which is the authoritative source of records for the domain.

To stop your system acting as a slave server for a zone, you will need to delete it from the BIND configuration. This is generally a safe procedure, as the all the records in the zone have been copied from a master server and can be easily replaced. However, you should update the Name Server records in the zone and notify the parent domain’s registrar that you system is no longer a secondary for the zone, so that other DNS servers do not waste time querying it.

To delete a slave zone, the steps to follow are :

1. On the module’s main page, click on the icon for the slave zone that you want to edit. This will take you to the form shown in the screenshot above.
2. Click on the Delete button in the bottom right-hand corner of the page, which will display a confirmation form.
3. Hit the Delete button if you are sure you want to delete the zone.
4. After your browser returns to the module’s main page, click on Apply Changes to make the deletion active.
5. On the master server, remove the Name Server (NS) record for this secondary server from the zone.
6. If this is an Internet domain, notify the parent zone registrar of the removal of this secondary server. Failure to do so could cause problems if other DNS servers attempt to query this one for records in the domain when it cannot provide answers.

The final thing that you can do to a slave zone is convert it to a master. This is only possible for zones that use a records file, so that Webmin can view and edit that file in future. If you do such a conversion, make sure that the original master server is changed to become a slave or stops hosting the zone altogether – the same domain cannot be served by two masters.

The steps to convert a zone are :

1. Click on its icon on the module’s main page.
2. Scroll down to the bottom of the slave zone page, and hit the Convert to master zone button. This will immediately update the named.conf file to change the zone’s type, but will not make any other changes.
3. To make the conversion active, click on the Apply Changes button on the module’s main page.
4. You can now edit records in the domain just as you would with any normal master zone, by following the instructions in the section on Adding and editing records.

Creating and editing a forward zone

A forward zone is one for which your DNS server simply forwards queries to another server on behalf of whoever is making the request. They can be useful if the zone is actually hosted by another server that cannot be reached by clients of this server. It is possible to set up BIND to forward all requests for any non-hosted zones to another server, as explained in the *Configuring forwarding and transfers* section below. A forward zone entry does the same thing, but for just a single domain.

To set one up, the steps to follow are :

1. On the module’s main page, click on the Create a new forward zone link above or below the list of existing domain icons. This will take you to the zone creation form.
2. Set the Zone type field to either Forward or Reverse, as when creating master and slave zones.
3. For a forward zone, enter its full name (without a dot at the end) into the Domain name / Network field. For a reverse zone, enter its network (like 192.168.1) into the field instead – Webmin will automatically convert it to in-addr.arpa format when the zone is added.
4. In the Master servers field, enter a list of IP addresses for the DNS servers that can be queried to lookup records in the zone. These must all be master, slave or forward hosts for the domain. If no addresses are entered at all, BIND will always perform normal lookups of records in the zone instead of forwarding requests to another server. This can be used to override the global forwarding settings on the Forwarding and Transfers page for a single zone.
5. Click the Create button to have the zone added to BIND’s configuration file. Your browser will be taken to a page for editing options in the new domain.
6. Return to the module’s main page, and hit the Apply Changes button to make it active.

After a forward zone has been created, you can delete it or edit the few settings that it has by following these steps :

1. Click on the icon for the zone on the module’s main page, which will bring your browser to a small form for editing its options.
2. To change the list of DNS servers that requests are forwarded to, edit the IP addresses in the Master servers field. If none are entered, requests for records in this domain will be looked up directly.
3. If the Try other servers? field is set to Yes, BIND will try a normal direct lookup for requests in this zone if it cannot contact any of the listed servers.
4. Click the Save button to store your changes, and then Apply Changes back on the main page to activate them. Or to delete the forward zone, click on Delete and then Delete again on the confirmation page.

Creating a root zone

As the introduction explains, a root zone is one that contains the information that your DNS server needs to contain the Internet root servers. Without one, it is impossible to resolve records in domains other than those hosted by your server. Fortunately, one will almost always exist already in your BIND configuration, created either by Webmin or included as part of the default setup.

You may need to create a root zone if one does not exist yet because you selected the internal non-internet use only option when setting up the module for the first time, but have now connected your system to the Internet. Adding a second root zone can also be useful when views have been configured, as explained in the Using BIND views section.

Webmin will only allow you to create a root zone if none exists yet, or if a view exists that does not contain one, because there is no point having two such zones. To add one, the steps to follow are :

1. On the module’s main page, click on the Create a new root zone icon.
2. Fill in the Store root servers in file field with a filename to use for the root zone file. If one already exists, then this field will already contain its path – otherwise, you should enter something like /var/named/db.cache.
3. The Get root servers from field controls where Webmin copies the root file from. The choices are : *Download from root FTP server *This is the best option, as it tells the module to make an FTP connection to rs.internic.net and download the latest version of the file. However, this may not work if your system cannot make perform FTP downloads due to a firewall. *Use Webmin’s older root server information *This option should be used if the first will not work. If selected, the module will use a copy of the root zone file that comes with Webmin, which will work but may not be up to date. *Existing root servers in file *If the file entered in step 2 already exists, then this option should be chosen. If you are adding a root zone to a view and one already exists in another view, it will be selected by default so that the file can be shared between both zones.
4. Click the Create button to add the zone and return to the module’s main page. Then hit Apply Changes to make it active.

Once a root zone has been added, an icon representing it will appear on the main page. You can delete it by clicking on the icon and hitting the Delete button – however, this may prevent the lookup of records in non-hosted Internet domains from working as explained above.

Editing zone defaults

If you add lots of zones that contain similar records, then it can be a lot of work to add them manually after creating each one. For example, in a web hosting company all of your domains might contain a www Address record for the IP address of your webserver, and an Mail Server record that directs mail to a central server. Fortunately, Webmin allows you to create a list of records that get added to all new domains, called a zone template.

A template consists of one or more records, each of which has a name, type and value. For Address records, the value can be option which indicates that it can be entered by the user at zone creation time. This is useful if one of the records (such as www) in the new domains does not have a fixed address, and you want to be able to easily set it when the zone is added. Templates can only be used when creating forward zones, as they do not make much sense for reverse zones.

It is also possible to edit the default expiry, refresh, TTL and retry times for new zones. Webmin’s initial defaults are reasonable, but may not be appropriate for your network. To change these defaults and set up template records, the steps to follow are :

1. On the module’s main page, click on the Zone Defaults icon. The form at the top of the page labeled Defaults for new master zones contains all the fields that need to be edited.
2. Edit the Refresh time, Transfer retry time, Expiry time and Default time-to-live fields if you want to change the defaults times for new zones. Existing master zones will not be effected by any changes you make here though.
3. If all your new domains are managed by the same person, enter his address into the Default email address field. This will save you from having to type it in on the master zone creation page every time.
4. In the Template records table, two blanks rows appear for entering new records. To add more than two, you will need to save this page and re-edit it. The records in existing rows can be edited by just changing their fields, or deleted by clearing out the record name. Under the Record name column you must enter the name of the record relative to the zone, such as www or ftp. To create a record for the zone itself (such as a Mail Server record for the domain), just enter a single dot. Under the Type column, select a type for the record from the list. See the Record types section for more information on what each is used for. As its name suggests, the field under the Value column is for entering a value for the new record. For the Address type, you can select From form in which case you will be able to enter an address when creating a new domain, which will be used by all template records that have this option selected. For Mail Server records, both the priority and server name must be entered separated by a space, such as 5 mail.example.com.. Values for records of all other types should be entered in the same format as is used when adding a record to a zone.
5. If you are familiar with the records file format used by BIND, you can create your own file of records to be included in new zones. If a filename is entered into the Additional template file field, its contents will be added to the zone file created by Webmin for new master domains.
6. When you are done adding template records, click the Save button at the bottom of the page. The changes will apply to any new master zones created from now on.

Now that you have created a template, you can choose whether or not to use it for each new master zone that you create. On the creation form (explained in the Creating a new master zone section) is a field labeled Use zone template?, which is set to Yes by default if there are any template records. Next to it is a field named IP address for template records, which used for entering the IP for records for which the From form option is selected. If you chose to use a template and if there are any records that do not have an IP address specified, then this field must be filled in.

The Zone Defaults page also contains several options that apply to all existing domains, but can all be set or overridden on a per-zone basis as explained in the Editing a master zone section. You can control which clients are allowed to query the server, and what kind of checking is done for the records of various domain types. Being able to limit the allowed client hosts is particularly useful, so that you can stop non-internal clients using your DNS server. However, you should make sure that master Internet zones hosted by your server are accessible to everyone, so that other DNS servers on the Internet can look them up.

To change these global options, the steps to follow are :

1. On the module’s main page, click on the Zone Defaults icon and scroll down to the *Default zone settings *section.
2. To control which hosts are allowed to query your DNS server, change the Allow queries from field to Listed and enter a list of IP addresses, IP networks (like 192.168.1.0/24) and ACL names into the text box below. Clients that do not match any entry on the list will be denied, unless they are requesting a record in a zone which has its own separate settings allowing them.
3. To control which hosts are allowed to perform zone transfers from your server, change the Allow transfers from field to Listed and fill in the text box below with a list of IP addresses, IP networks and ACL names. Only servers that are acting as secondaries for zones that this server hosts really need to be able to do transfers, so it is usually a good idea to enter just their IP addresses. If you are restricting queries, this field must be filled in so that hosts that cannot lookup records are not allowed to perform transfers either.
4. The fields Check names in master zones? and Check names in slave zones? control the checking of records in all zone files for master and slave zones respectively. The available options for each are : Warn *If an invalid record is found, an error will be written to the system log file but processing of other records continues normally. *Fail *Invalid records cause the entire zone to be rejected, but other zones will still be processed normally. *Ignore *No checking is done at all. *Default *The default checking level is used, which is *Fail.
5. To have BIND check responses that it receives from other DNS servers, set the Check names in responses? field to Warn or Fail. The default is simply to pass potentially erroneous responses on to clients.
6. The Notify slaves of changes? field determines whether BIND sends a notification to all slaves of master zones hosted by this server when they change. To turn this on, select Yes – otherwise, select No or Default. Enabling notification is a good idea, as it ensures that secondary servers are kept in sync with the master.
7. When done, click the Save button at the bottom of the page to update the BIND configuration file, and then the Apply Changes button on the module’s main page to make the changes active. The new settings will apply to all zones that do not explicitly override them on their own options pages.

Configuring forwarding and transfers

BIND can be configured to forward all requests for zones that it is not the master or slave for to another DNS server. When doing this, it acts like a DNS client itself, accepting requests from real clients and then sending them off to another server or servers for resolution instead of carrying out the normal process of contacting the root zone servers and finding the correct server for the domain. This can be useful if your DNS server is unable to contact the rest of the Internet, but can still communicate with a DNS server that does have full network access. For example, it may be on an internal network behind a firewall that only allows connections to a limited set of destinations.

To set up forwarding, the steps to follow are :

1. On the module’s main page, click on the Forwarding and Transfers icon.
2. In the form that appears, fill in the Servers to forward queries to field the IP addresses of DNS servers that requests should be sent to. BIND will try them in order until one returns a positive or negative a response. If the list is empty, the server will revert to the normal method of looking up records by contacting the root servers and so on.
3. If you want your server to attempt to resolve a client’s query directly when it cannot contact any of the forwarding servers, set the Lookup directly if no response from forwarder field to Yes. This is only useful if your server is actually capable of doing lookups.
4. Click the Save button at the bottom of the page, and then hit Apply Changes back on the main page to make the new setting active. Assuming the forwarding list was filled in, your server will now send all client queries to the listed servers.

The same form also contains fields for configuring BIND’s behavior when doing zone transfers. You can control how long it will wait for a transfer to complete, the protocol used for transfers and the number that can be active at the same time. To edit these settings, follow these steps :

1. On the module’s main page, click on the Forwarding and Transfers icon.
2. By default, BIND will wait 120 minutes (2 hours) for a zone transfer from a master to complete. To change this, enter a different number of minutes into the Maximum zone transfer time field. This can also be set or overridden on a per-slave zone basis.
3. BIND versions before 8.1 only support the transfer of a single zone at a time. Because this can be slow when transferring many zones from the same master server, the Zone transfer format field can be set to Many to use a new format that combines multiple domains into the same transfer. If One at a time or Default is chosen, then each zone will be transferred separately. This is the best choice unless you are sure that all slave servers are running BIND 8.1 or above.
4. By default, your nameserver will not carry out more than 2 concurrent zone transfers from the same master server. To increase this limit, change the Maximum concurrent zone transfers field to something higher. This can speed up the process of transferring a large number of domains, but at the expense of putting a higher load on the master server.
5. Click the Save button when you are done making changes, and then Apply Changes on the main page to activate them. The new settings will apply to all subsequent zone transfers.

Editing access control lists

An access control list (or ACL) is list of IP addresses, IP networks or other ACLs that are grouped together under a single name. The ACL name can then be used when specifying the list of clients allowed to query, update or perform zone transfers from a zone. This can make be used to reduce the amount of duplication in your BIND configuration, and to make it clearer. For example, the ACL corpnet might match the IP networks 192.168.1.0/24, 192.168.2.0/24 and 1.2.3.0/24, which are all part of your company’s network. When configuring who can query a zone, you could just enter corpnet instead of that list of network addresses.

To view and edit ACLs in Webmin, the steps to follow are :

1. On the module’s main page, click on the Access Control Lists icon. This will take you to a page listing existing ACLs and allowing the addition of one more. If you want to add more than one ACL, you will need to save the form and re-edit it to force the display of a new blank row.
2. To add a new ACL, find the blank row at the bottom of the table and enter a short name consisting of only letters and numbers in the ACL Name column. Then in the field under Matching addresses, networks and ACLs, enter a list of IP addresses, IP networks and other ACL names that this new ACL will contain. IP addresses must be entered in their standard format like 192.168.1.1, but hostnames are not allowed. IP networks must be entered in network/prefix format like 192.168.1.0/24 or 192.168.1/24. You can also precede any address, network or ACL name with a ! to negate it, so for example the entry !192.168.1.0/24 would match all hosts outside the_ 192.168.1 _network.
3. Existing entries in the list can be edited by changing their fields in the table, and ACLs can be deleted by clearing out the field containing their names.
4. When you are done adding and editing ACLs, click the Save button. To activate the changes, hit Apply Changes back on the main page. As soon as an ACL is created, it can be used in other query, transfer and update restrictions of other zones.

BIND has four built-in ACLs that can be used in all the same places that user-defined ACLs can. They are :

• any Matches any client address.
• none Matches nothing.
• localhost Matches the IP addresses of all network interfaces on your system. Even though it is called localhost, it doesn’t just match 127.0.0.1.
• localnets Matches all clients on all networks that your system is directly connected to. BIND works this out by looking at the IP addresses and netmasks of all network interfaces.

Setting up partial reverse delegation

Partial reverse zone delegation is method for transferring the management of a small set of reverse IP addresses to another DNS server. Normally, reverse zones cover an entire class C network containing 256 addresses. However, many organizations have networks much smaller than this, containing maybe 16 or 32 addresses. Normally, this would make it impossible for the organization to manage its own reverse address mappings, as the addresses come from a network that is owned by an ISP or hosting company.

Fortunately, there is a solution – the ISP can set up Name Alias (CNAME) records in the reverse zone for the parent network that point to Reverse Address records in a special zone on the organization’s DNS server. The parent zone must also contain a Name Server (NS) record for the special sub-zone that points to the customer’s server, so that other DNS clients know where to look when resolving the Name Alias records.

An example may make this clearer – imagine for example than an ISP had granted addresses in the range 192.168.1.100 to 192.168.1.110 to Example Corporation, which owns the example.com domain. The company already runs its own DNS server to host the example.com zone, but wants to control reverse address resolution for its IP range as well. The ISP would create Name Alias records in the 192.168.1 zone pointing to the special sub-zone 192.168.1.100-110, which will contain the actual Reverse Address records named like 192.168.1.100-100.101. The ISP also needs to create a Name Server record for 192.168.1.100-110 which tells other servers that Example Corporation’s DNS server should be used to find records under that zone.

Webmin handles reverse address delegation well, and automatically converts special network zones like 192.168.1.100-110 to and from the real zone names used by BIND such as 100-110.1.168.192.in-addr.arpa. The exact steps to follow on both the server that hosts the actual class C network zone and the server that a subset of it is being delegated to are :

1. Decide on the range of addresses that are being delegated, such as 192.168.1.100 to 192.168.1.110. Typically, the sub-zone name is based on the range of addresses being delegated, but this does not have to be the case as long as it is under the parent network domain.
2. On the server that hosts the class C network zone, add a Name Server record for 192.168.1.100-110 with the server set to the IP address or name of the sub-zone’s DNS server.
3. For each address in the range, add a Name Alias record to the reverse zone named like 101.1.168.192.in-addr.arpa. with the Real Name set like 101.100-110.1.168.192.in-addr.arpa. As you can see, the alias points to a record inside the zone for the sub-network.
4. When all of the Name Alias records have been created, everything that needs to be done on this server is finished and you can hit Apply Changes.
5. On the DNS server for the sub-network, create a new master zone for the reverse network 192.168.1.100-110. Webmin will automatically convert this to the correct in-addr.arpa format for you.
6. Add Reverse Address records to the new zone as normal for IP addresses like 192.168.1.100-110.101. Adding a record for the IP 192.168.1.101 will not work.
7. When you are done creating reverse records, click the Apply Changes button to make them active. You should now be able to look them up using a command like nslookup on the server for the parent network zone.

The instructions above can be used to delegate multiple ranges from a single class C network to several different DNS servers. There is no limit on the size of ranges, nor any requirement that they follow normal network block boundaries – however, for routing reasons most IP allocation is done in power-of-two sized blocks (like 4, 8, 16 and so on), which means that any sub-zone ranges will be the same size.

The only problem with reverse address delegation when using Webmin is that Reverse Address are not automatically created and updated when Address records are. This means that you will have to create all such records manually on the sub-zone server, as in the steps above.

One inconvenience in setting up partial reverse delegation is the number of similar Name Alias records that must be created on the parent network zone server. Fortunately, there is a simpler alternative – record generators. A generator is a special BIND configuration entry that creates multiple similar records using an incrementing counter. This module allows you to created and edit generators, by following these steps :

1. On the module’s main page, click on the icon for the reverse zone that you want to create records in. This will typically be a class C network domain that is going to have a range of addresses delegated to some other server.
2. Click on the Record Generators icon. This takes you to a page containing a table of existing generators, with a blank row for adding a new one.
3. In the empty row, select CNAME from the menu under the Type column.
4. Under the Range column, enter numbers for the start and end of the address range into the first two fields, such as 100 and 110. The third field is for entering the gap between each step, and should be left blank. If you were to enter 2, then the range would go 100, 102, 104 and so on.
5. In the Address pattern field, enter $ (a single dollar sign). When the records are created, the $ will be replaced with the number of each record, which will in turn resolve to an IP address in the range. You could also enter $.1.168.192.in-addr.arpa., which makes things more obvious but is longer to type.
6. In the Hostname pattern field, enter $.100-110. Similarly, the $ will be replace with the number of each record, which will resolve to something like 101.100-110. 1.168.192.in-addr.arpa..
7. If you like, enter a comment that describes what this generator is for into the Comment field.
8. Click the Save button, return to the module’s main page and click on Apply Changes.

A generator can replace the Name Alias records that the first set of instructions in this section tell you to create, so there is no need for them anymore. Note that the automatically generated replacements will not be visible or editable in the normal way, only through the Record Generators page.

Using BIND views

BIND version 9 introduced the concept of views, which are groups of zones that are visible only to certain DNS clients. Views can be used to hide internal zones from the Internet, to present the same zone in two different ways, or to stop non-local clients resolving non-hosted domains through your server. Every view has a unique name, and a list of matching IPs addresses and IP networks that determines which clients and servers it is visible to.

When it detects that you are running BIND 9, several additional features are available in the module. You can create views, move zones from one view to another, and choose which view zones are created in. On the main page, each current view is represented by an icon under Existing Client Views heading, and each zone icon has a label that indicates which view it is in.

If any views exist, then every zone must be in a view. Only if none are defined will Webmin allow the creation of zones outside views, as this is not supported by BIND. This includes the root zone, which must be available to a client for DNS requests for records in domains not hosted by this server to succeed. For this reason, it often makes sense to put the root zone in a view that is available to all clients.

To add a new view to your BIND configuration, the steps to follow are :

1. On the module’s main page, click on the Create a new view link in the Existing Client Views section. This will take you to a form for entering its details.
2. Enter a short alphanumeric name for the view (such as internal or everyone) into the View name field. Each view must have a unique name.
3. Leave the DNS records class field set to Default.
4. If this zones in this view are to be visible to everyone, set the Apply this view to clients field to All clients. Otherwise, choose Selected addresses, networks and ACLs and enter a list of IP addresses, IP networks and BIND ACL names into the text box below. Only clients that match one of the entries in this list will have access to the view.
5. Click the Create button at the bottom of the form. You will be returned to the main page, which will include an icon for your new view.
6. Move any existing zones that you want to be in this view into it. A zone can be moved by clicking on its icon, then on Edit Zone Options, and then selecting the new view from the menu next to the Move to view button before clicking it. If this is your first view, all existing zones must be moved into it (or another view) before the new configuration will be accepted by BIND.
7. When you are done moving zones, click the Apply Changes button on the main page.

Once a view has been created, you can change the list of addresses and networks that it matches by clicking on its icon on the main page and updating the Apply this view to clients field. Then hit the Save button followed by Apply Changes to make the new client list active.

A view can be deleted by clicking the Delete button on the same form. This will bring up a confirmation page that allows you to choose what should happen to the zones that it contains, if any. The available options are :

• Delete totally All zones in the view are deleted, along with their records files.
• Move out of views Zones in the view are moved out to the top level. This option should only be used when deleting the last view, for the reasons explained above.
• Move to view Zones are moved to a different existing view.

When one or more views have been defined on your system, you can choose which one to use when adding new zones. This is done using the Create in view field on the master, slave, forward and root zone creation forms, which allows you to select a view from its menu. Naturally, there is no option for creating a zone outside of any views as this is not allowed by BIND.

One common use of views is hiding internal zones from clients outside your internal network. This is a good way of hiding the structure of your network and the hosts on it from potential attackers. To set it up, the steps to follow are :

1. Create a new view called internal that matches clients on your internal LAN.
2. Create a second view called everyone that matches all clients.
3. Move any zones that are for internal use only into the internal view. Zones for Internet domains such as example.com must not be put in this view, as that would make them inaccessible to the rest of the world.
4. Move all other zones (including the root zone) to the everyone view.

Views can also be used to prevent clients outside your network looking up non-hosted domains on your server, as follows :

1. Create a new view called internal that matches clients on your internal LAN.
2. Create a second view called everyone that matches all clients.
3. Move the root zone to the internal view, which will prevent the server from looking up records for non-local clients that require contact with the root servers.
4. Move all other zones to the everyone view.

Module access control

Like others, the BIND DNS Server module allows you to control which of its features are available to a particular Webmin user or group. This can be useful for giving people the rights to manage only records in their own zones and nobody else’s. Even though this would normally require root access to the records files, with Webmin it can be granted to people without giving them level of power that a root login would allow.

Once you have created a user with access to the module as explained on WebminUsers, the steps to limit his access to only certain zones are :

1. Click on the BIND DNS Server next to the name of the user in the Webmin Users module. This will being up a page of access control options.
2. Change the Can edit module configuration? field to No, so that the user is not allowed to change the paths that the module uses to named.conf and other files.
3. For the Domains this user can edit *field, choose *Selected zones and select the ones that you want him to have access to from the list to its right. If you want him to be able to edit almost all zones, it may be better to choose All except selected and select only those that he should not be allowed to manage records in. If your DNS server uses views, you can use the Zones in view options to allow or deny access to all zones in a view as well.
4. Change the fields Can create master zones?, Can create slave/stub zones?, Can create forward zones? and Can edit global options? to No.
5. If you want Reverse Address records in zones that the user does not have access to to be updated by changes to Address records in zones that he does, set the Can update reverse addresses in any domain? field to Yes. This may not be a good idea from a security point of view though, as he would be able to change almost any existing Reverse Address record on your system. For that reason, I suggest that this field be set to No.
6. To stop the user creating more than one Address record with the same IP, set the Can multiple addresses have the same IP? *field to *No. Even though creating multiple records is harmless, you may want to set this to No to prevent the user allocating the same IP twice.
7. Leave the Read-only access mode? field set to No. If it is changed to Yes, the user will only be able to view zones and records using the module, and not change anything. This might be useful for creating a different kind of restricted user though – one who can see all settings, but not edit them.
8. Leave the Can apply changes? field set to Yes, so that he can use the Apply Changes button to make his additions and modifications active.
9. Unless you want the user to be able to edit his records file manually, change the Can edit records file? field to No. Most un-trusted users are not smart enough to perform manual editing.
10. The Can edit zone parameters? field determines if the user can see and use the Edit Zone Parameters icon for his domains. Setting this to Yes is quite safe, as the user can only harm his own zones by setting the parameters to silly values.
11. Similarly, the Can edit zone options? field determines if the Edit Zone Options icon is visible or not. You should set this to No, as it is possible for a user to create a syntax error in named.conf by improper use of the zone options form.
12. Unless you want the user to be able to delete his own domains, change the Can delete zones? field to No. Users should contact the master administrator instead if they can to delete zones.
13. The Can edit record generators? field can be left set to Yes, as it simply allows the creation of multiple records at once. However, some users may get confused by this feature so it might be a good idea to change the field to No.
14. The Can lookup WHOIS information? And Can search for free IP numbers? fields can also be left on Yes, as those features mere display information to the user.
15. Change the Can create and edit views? field to No, so that the user cannot manage BIND 9 views. If the user is allowed to create zones, you can use the Views this user can edit and add zones to field to limit those that he can create zones in.
16. Can create slave zones on remote servers? should be set to No, but this doesn’t really matter as the user is not going to be allowed to create master or slave zones anyway.
17. Finally, click the Save button to make the new restrictions for the user active.

DHCP Server Configuration

source: http://doxfer.com/Webmin/DHCPServer

This page explains what DHCP is and how to use Webmin to set up a DHCP server on your network so that other systems can obtain IP addresses automatically.

Introduction to the Dynamic Host Configuration Protocol

DHCP is a protocol that allows hosts to request and be assigned an IP address on a local area network. It is used to simplify the process of IP address assignment, as a single server can manage the addresses of multiple clients. It is also useful for systems such as laptops that are moved between multiple networks, as they do not need to be re-configured for each LAN that they connect to.

DHCP is usually used on Ethernet networks, although it can be used on any type of LAN that supports broadcast traffic such as 802.11 and token ring. It is not used for address assignment for dial-up connections or ADSL – the PPP protocol has its own method of assigning clients their IP addresses. Because broadcasts are not normally forwarded by routers, a DHCP server can only assign addresses to hosts on a single LAN – unless you have a router that is configured to forward DHCP packets.

A DHCP server can also supply other information to clients in addition to an IP address. The addresses of DNS servers and the network gateway can be sent, along with the DNS domain, NIS server, NIS domain, static routes and much more. DNS and routing information allows clients to fully integrate themselves into the network they are connected to without needing any manual configuration.

When a server assigns an IP to a client, it is given a lease on that address for a certain amount of time, during which no other client will be assigned the same address. When the lease expires the client must contact the server again. Typically it will be assigned the same IP address as before, and the lease will be extended for the same time period. If a client does not contact the server when its lease is up the server assumes that the client has been shut down, and marks the address as available for assignment to other hosts.

Most operating systems include support for configuring a network interface to use DHCP to get its IP address. Chapter 16 explains how to set it up for Linux systems, and it is relatively simple to configure Windows and MacOS? clients to use it as well. DHCP has become the standard protocol for address assignment on IP networks, replacing the older BOOTP protocol used by some Unix operating systems.

The ISC DHCP server

The most common DHCP server for Unix system is the ISC server, of which several versions have been released. The latest is version 3, but version 2 is still in common use. Release 1 uses a very different configuration file format to later versions, and is not seen much any more. The ISC DHCP server supports a wide range of options, and can be configured to behave differently for different clients, networks and address ranges.

The ISC server can be used to assign fixed addresses to hosts, or addresses from certain ranges. Every host is identified by its MAC addresses, which on an Ethernet LAN is the address of the host’s Ethernet card. A static IP address and other options can be associated with a particular hardware address, which allows you to fix the address that certain systems receive while using dynamic allocation for others.

The server’s configuration file contains four different types of entries, that contain options that effect different clients :

• Subnet A subnet is an entire IP network, such as 192.168.1.0. Entries of this type are used to dynamically allocate addresses within certain ranges to clients within the network.

• Shared network A shared network is a group of subnets that share the same physical network.

• Host A single client host, identified by its MAC address and assigned a fixed IP address.

• Group A group of hosts for which the same options can be set.

Entries in the server configuration are arranged in a hierarchy that determines what client options and other settings apply to a particular client. Options in higher-level entries are overridden by those lower in the hierarchy, which allows an administrator to avoid repeating configuration information while still being able to set individual options for specific hosts.

The ISC DHCP server’s primary configuration file is called dhcpd.conf, and can usually be found in the /etc directory. Other configuration files can be included by the primary file, but on most systems only dhcpd.conf is used. The only other file used by the server is dhcpd.leases, which contains all granted leases and is always kept up to date. Whenever the server is started, it re-reads this file to find out which leases are currently active. This means that there is no danger of lease information being lost if the server is stopped and re-started, which is necessary for it to re-read the primary configuration file.

Webmin’s DHCP Server module directly updates the configuration and lease files when you manage subnets, hosts, groups and leases. To activate the current configuration, it kills the server process and re-runs it, as there is no way to signal the server to re-read its configuration file.

The DHCP Server module

This module can be used to set your system up as a DHCP server so that clients on your LAN can be automatically assigned IP addresses, DNS servers and other information. If there is already a server on your network, setting up another one is a bad idea as they may interfere with each other. If you just want to configure your system to obtain its own IP address via DHCP, then there is no need to set up a server – instead, see the Adding a network interface section of NetworkConfiguration.

The DHCP Server module can be found in Webmin under the Servers category. Clicking on its icon will take you to the main page, which lists all existing subnet, shared network, host and group configurations. The screenshot below shows an example. However, if this is the first time that you have used the module and the server has not been configured manually, then the page will probably be almost empty.

At the bottom of the page are buttons for editing global settings, and for displaying current dynamic address leases. Below them is the Start Server or Apply Changes button, which either starts the server if it is not running, or re-starts it to force a reload of the configuration if it is. However, you cannot start the server until at least one valid subnet has been defined.

The DHCP server module

If the ISC DHCP server is not installed on your system, the main page will display an error message notifying you that the dhcpd program could not be found. All Linux distributions include a DHCP server package on their CD or website, which you will need to install before you can use the module. Make sure that the package you add is called dhcpd or dhcp-server, as there is often a separate package for the DHCP client programs.

The same error can also appear if the server is installed, but in a location other than the one that the module expects. This can happen if you have compiled and installed it yourself from the source code, rather than using your distribution’s standard package. If so, you will need to adjust some of the paths explained in the section called Configuring the DHCP Server module.

Because this module only supports the configuration of ISC DHCP server versions 2 and 3, the main page will also display an error message if it detects that version 1 of the server is installed. Unfortunately, this older release uses a totally different configuration file format and so is not supported by the module. Some operating systems (such as Solaris) include this older version by default, but it can be replaced by the latest one.

The ISC DHCP server is also available for several other Unix operating systems in addition to Linux. Because it works the same on all of those systems, the behaviour of this module is identical as well. The only differences are the default paths that it uses for the server configuration files and programs.

IMPORTANT – On some operating systems and Linux distributions, the DHCP server package includes a sample configuration file that defines several hosts and subnets. These are not going to be of much use for your network, and will probably prevent the server from working at all as they do not match its actual network interfaces. For this reason, it is best to simply delete them before setting up your own configuration.

Once a few entries have been added to the server configuration, the main page displays a table of icons networks under the heading Subnets and Shared Networks. Each icon represents either a subnet (shown with its network address under it), or a shared network (shown with its name). By default, subnets are listed first followed by shared networks, and both lists are in the order that they appear in the configuration file. If you have a complex DHCP configuration, you can change this by clicking on one of the following links next to Display nets and subnets by :

• Assignment The default sorting mode – subnets are shown before shared networks, and both are listed in the order that they appear in the configuration file.

• File structure Subnets are listed after the shared networks that they are part of, which are sorted by their order in the configuration file.

• Name/IP address Subnets are listed sorted by IP address, followed by shared networks sorted by name.

In the bottom part of the page is a table of icons with the heading Hosts and Host Groups. An icon is shown for each host or host group, with the name or number of members displayed beneath it. Because many servers have a large number of hosts, you can control the order that they are displayed in by clicking on one of the following links next to Display hosts and groups by :

• Assignment Hosts are listed before groups, and both are in the same order that they appear in the configuration file.

• File structure Hosts are listed after the groups that they are part of, which are sorted by their order in the configuration file.

• Name Hosts are listed sorted by name, followed by groups in the order that they appear in the configuration file.

• Hardware address Hosts are listed sorted by MAC addresses, followed by all groups.

• IP address Hosts are listed sorted by their fixed IP address, followed by all groups.

Changes to the sorting modes will be remembered by the module, so that they will be used every time you visit the main page from now on.

Adding and editing subnets

In the simplest DHCP server configuration, all you need is a single subnet entry to hand out IP addresses within some range to clients on a single LAN. The server allows you to do much more than that, but for many networks this is all that is needed (unless you want to assign fixed addresses to some hosts, or have multiple IP networks on the same LAN).

To add a new subnet entry, the steps to follow are :

1. On the module’s main page, click on the Add a new subnet link in the Subnets and Shared Networks section. This will take you to the page shown in the first image below.
2. In the Network address field, enter the address of your local LAN such as 192.168.1.0. This must be a network that your system is connected directly to.
3. In the Netmask field, enter the mask for the local LAN such as 255.255.255.0. The best way to find the correct network address and netmask is to use the Network Configuration module to look at the settings for your Ethernet interface.
4. The Address ranges section is actually a table for entering multiple ranges, but only one blank row is displayed at a time. In the first field, enter the starting address for the range of IPs that you want assigned to clients, such as 192.168.1.100, and in the second enter the ending address for the range, such as 192.168.1.150. Both addresses must be within the network, and the first must be lower than the second. To add more than one range, you will need to re-edit this subnet after saving so that a new blank row appears in the table. The server will always assign addresses from the start of the first range up to the end, then go on to the second and any subsequent ranges. Because each client must have a unique IP, make sure that your ranges are big enough to support all the client hosts that may be connected to the network at any one time.
5. If you want this subnet to be part of a shared network (explained in the Adding and editing shared networks section), select it from the Shared network menu. Otherwise, choose to have the subnet created outside of any shared nets.
6. To set the lease length for clients on this network, change the Default lease time from Default and enter a number of seconds into the field next to it. This will be the length of the lease for hosts that do not explicitly request one. You should also set the Maximum lease time field, so that clients cannot request a lease longer than the specified number of seconds. If not set, then there is no upper limit on lease length.
7. Unless the client systems on your LAN will be network booting from another server, the Boot filename and Boot file server fields can be left set to Default. Only diskless workstations need to do this.
8. The Server name field is for entering the network hostname of your DHCP server system. Usually this can be left set to Default, in which case the server will work it out automatically.
9. Click the Create button at the bottom of the page. An new entry for the subnet will be added to the server’s configuration, and you will be returned to the module’s main page.
10. Click on the new icon for the subnet, which will take you to an editing form that is almost identical to the creation page.
11. Click on the Edit Client Options button to go to a page listing information that will be sent to clients, as shown in Figure
12. -4. All of the fields have a Default radio button, which if selected typically indicates that no information related to that option will be sent to clients.
13. Fill in the Default routers field will the IP address of the default gateway on your network, such as 192.168.1.1. This will be used by clients that have their address assigned by DHCP to communicate with systems outside the network.
14. Fill in the Subnet mask field with the netmask for your network, such as 255.255.255.0.
15. Enter the broadcast address for your network into the Broadcast address field, such as 192.168.1.255.
16. Fill in the Domain name field with the DNS domain name such as example.com that clients should append to partial hostnames.
17. In the DNS servers field, enter a space-separated list of DNS server IP addresses that clients can use, such as _192.168.1.104
18. 2.3.4_.
19. If you are running NIS (covered on NISClientAndServer? ) and want clients to connect to an NIS server at boot time, fill in the NIS domain field with the name of your NIS domain, and the NIS servers field with the IP address of your NIS master or slave server. This is only useful if the client hosts are capable of getting their NIS settings from DHCP.
20. If you have Windows clients and are running a Samba or Windows server, fill in the NetBIOS name servers field with the IP address of a system that can do NetBIOS? name resolution for clients. Any Unix system running Samba will be able to perform this role.
21. Click the Save button at the bottom of the page to go back to the subnet form.
22. If this is your first subnet, you will need to make sure that the server is configured to use the right network interface for your system. Return to the module’s main page, and click on the Edit Network Interface button at the bottom of the page. Then select the interface for the new subnet from the Listen on interfaces list, and click Save. If you have multiple network interfaces and have created subnet configurations for each of them, then all the interfaces must be selected for the server to work properly.
23. If you are running version 3 of the ISC DHCP server (shown on the main page) and this is your first subnet, you may need to set the DDNS update style before the server can be started. Even if you are not using DDNS, some versions insist on an entry existing in the configuration file for it. Click on the Edit Client Options button on the main page and scroll down to the Dynamic DNS update style field. Select None and click Save to return to the module index.
24. Back on the main page and click on the Start Server or Apply Changes button. If something goes wrong, the error message generated by the DHCP server will be displayed. The most common problem is a mismatch between the network interface settings and the network address for the subnet. Another that often shows up is related to the ddns-update-style directive, which step 21 explains how to set.

The subnet creation form

The subnet client options page

Once your first subnet has been created and the server started, you can test it by configuring a client system to use DHCP. When the client boots up, it should contact the server and be assigned an address, DNS and routing information. You should also be able to see the client on the leases page, covered in the subsequent Viewing and managing leases section.

An existing subnet can be edited by clicking on its icon on the main page, changing fields and hitting the Save button. If you want to edit options for clients in the subnet, you will need to click on Edit Client Options as in the instructions above, make your changes and then click Save on that page. After any modifications, the Apply Changes button must be used to make them active.

A subnet can be deleted using the Delete button on its editing form. Any hosts, groups or address pools that it contains will be removed as well, so be careful. After deleting, use the Network Interfaces page to de-select the interface for the subnet – failure to do so will cause the DHCP server to display an error message when Apply Changes is clicked, which must be done to make the deletion active.

If the subnet contains any hosts or groups, a confirmation page will be displayed when Delete is clicked listing all the groups and hosts that will be deleted as well. Only when the Yes button is hit will be subnet (and all it contains) actually be removed.

Another way to create a subnet inside a shared network is to click on the Add a new subnet link on the shared network’s page. This will bring up the same subnet creation form shown in the screenshot above, but without the Shared network field. Instead, the shared net is shown at the top of the page under the title. The rest of the creation process is identical.

A subnet configuration entry must be created for each IP network that you want to allocate addresses on. Typically, there will be one for each LAN connected to your system via an Ethernet, Token Ring or 802.11 network card. If two IP networks are actually on the same LAN, then both their subnets must be inside a shared network, as explained in the Adding and editing shared networks section.

You must also make sure that every network interface that is connected to a network on which your DHCP server is assigning addresses is selected on the Network Interface page. If not, an error will be reported when the server is started or changes are applied. For most system administrators, this is not a big issue though as they have only a single LAN in their organization.

Viewing and deleting leases

Every time the DHCP server supplies a dynamic address to a client, it records information about the assignment in its lease file. Fixed addresses assigned to specific hosts (covered in the *Adding and editing fixed hosts*) section do not trigger the creation of a lease, as they are considered permanent. You can use this module to view all current leases or expired leases, and to delete those that exist. Removing a lease tells the server that its IP address is no longer in use, and can be assigned to some other client. This should only be done if the client really isn’t using the address any more though, for example if it crashed while holding a long lease.

To view and delete leases, the steps to follow are :

1. On the module’s main page, click on the List Active Leases button. This will display a table listing all currently active leases, with the IP address, client name and start time shown for each.
2. To show leases that have expired as well, click on the List all active and expired leases button at the bottom of the page.
3. To remove a lease, click on its IP address in the list. The DHCP server will be stopped and re-started automatically to make the deletion active.

It is also possible to view the leases to clients in just a single subnet by clicking on the List Leases button on the subnet editing form. This can be useful if you have several networks connected to your system with a large number of clients, and want to limit the size of the lease display.

Editing global client options

The Adding and editing subnets section explains how to set client options (such as DNS and gateway IP addresses) that are supplied to all clients in a subnet. However, if you have more than one network or many fixed hosts, it can be more convenient to set option that apply to all clients of the server. These options can still be overridden for individual subnets, hosts and groups if you wish.

To edit global client options, the steps to follow are :

1. Click on the Edit Client Options near the bottom of the module’s main page. This will take you to a form similar to the one shown in the screenshot above.
2. Change any of the fields as explained in steps 11 to 18 of the Adding and editing subnets section.
3. At the bottom of the form are fields for setting the default and maximum lease times for all clients, along with a few other options. These have the same meanings as similarly named fields on the subnet creation page.
4. Click the Save button to update the DHCP server configuration file and return to the module’s main page.
5. Hit the Apply Changes button to make your new settings active.

Client options specified for a subnet override those defined globally, and are in turn overridden by options for hosts within the subnet.

Adding and editing fixed hosts

If you want to fix the IP address that is assigned to a specific host, you will need to add a host entry to the DHCP server configuration. This also allows you to set client options that apply only to that host, such as the DNS server addresses or default router.

The server identifies hosts by their MAC (Medium Access Control) address, which on an Ethernet LAN is the Ethernet address of the client’s network card. Typically this address is fixed, but a few network cards allow it to be changed. On Linux systems, you can find the MAC address by running the command ifconfig eth0 as root and looking for a string of 6 bytes in hex separated by colons, like 00:D0:B7:1D:FB:A1. On Windows, the winipcfg program can provide the information although it is displayed with dashes instead of colons. Other operating systems have their own ways of finding the Ethernet address.

Once you know the MAC address of the host, it can be added to the DHCP server configuration as follows :

1. On the module’s main page, click on the Add a new host link in the Hosts and Host Groups section. This will bring up the host creation form shown in the image below.
2. Enter a name into the Host name field. This should match the hostname that the client is configured with, or its fully-qualified name on your network. However, this is not mandatory.
3. Select the type of network (such as Ethernet) that the host in on from the menu in the Hardware address field. In the text box next to it, enter the host’s MAC address as a series of 6 hex bytes separated by colons, like 00:D0:B7:1D:FB:A1.
4. Enter the IP address that should be always assigned to this client into the Fixed IP address field.
5. If you want this host to inherit client options from a subnet, select Subnet from the menu in the Host assigned to field. The list next to it will be filled in with the names of all existing subnets, allowing you to select the one that the host should be under. The fixed IP address must be within the subnet’s network though, and the client must be connected to its LAN. Hosts can also be created inside shared networks or host groups, by choosing Shared Network or Group from the menu and selecting the appropriate entry from the list to the right.
6. If this host needs to network boot from a server, enter the name of that server into the Boot file server field. You must also fill in the Boot filename field with the path to an appropriate boot file (downloadable via TFTP) on the server. Generally, network booting is used by simple clients like X terminals and diskless workstations. For it to work, you must set up a TFTP server which contains the correct boot files for the client, which is not covered in this chapter.
7. Click the Create button at the bottom of the form, and you will be returned to the module’s main page which will now include an icon for the new host.
8. To edit the client options that are assigned to this host, click on its icon to go to its editing page, then on Edit Client Options. This is not always necessary if the host is a member of a subnet that already has these options set, or if they have been defined globally as explained in Editing global client options.
9. Fill in the form as you would for a subnet, as explained in the Adding and editing subnets section.
10. Click the Save button to return to the host form.
11. Return to the main page, and hit the Apply Changes button. From how on, the host will be assigned the IP address and options that you have chosen. It will no longer appear on the lease list, as its IP assignment is permanent.

Creating a new host

Once a host has been created, you can change its fixed IP address, MAC address and other options by clicking on its icon on the module’s main page, which will take you to the host editing form. After making modifications, hit Save to update the server configuration and then Apply Changes to make them active. A host can also be deleted with the Delete button on the editing page. From then on, the client system will receive a dynamically allocated address from one of the ranges for its subnet, rather than a fixed addresses.

A host can also be created by clicking on the Add a new host link on the subnet, shared network or group editing page. If done this way, the Host assigned to field is no longer displayed on the creation form – instead, the parent that it will be added to is shown at the top of the page. All the other steps in the process of adding the host are the same though.

If you have a large number of hosts and want all of them to use the same client options, then they should be placed in a group or shared network. See the section on Adding and editing groups for more information on group management. The DHCP server configuration allows you to define several levels of groups, which allows for quite complex configurations. If you have more than one fixed address host on your network, they definitely should be both under a subnet or group to avoid duplicating settings.

Adding and editing shared networks

A shared network is a group of subnets that shared the same physical LAN. If you have multiple IP networks on the same physical network, then the DHCP server configuration entries for all of them must be placed inside a shared network. Failure to do so may cause the server to behave incorrectly or report an error message when started. On the other hand, you must not put subnets that do not share the same LAN in the same shared network either.

It is also possible for a shared network to contain a single subnet, although this does not really achieve anything. However, it may be useful for grouping configuration entries, as a shared network can contain hosts and groups as well, and have client options that apply to all its members.

To create a shared network, the steps to follow are :

1. On the module’s main page, click on the Add a new shared network link under Subnets and Shared Networks.
2. Enter a short name for the network into the Network name field, such as homelan. This is used only when displaying the shared network on the main page.
3. To set the lease lengths for all clients of subnets under this shared network, fill in the Default lease time and Maximum lease time fields. Their meanings are the same as on the subnet creation form, documented in the Adding and editing subnets section.
4. In the Subnets in this shared network field, select any existing subnets that you want to move into this shared network. All existing subnets including those in other shared networks will be listed. You must choose at least one subnet, as a shared network cannot be empty.
5. Click the Create button at the bottom of the page. Your new shared network will be added to the server’s configuration, and an icon for it will appear on the module’s main page.
6. If you want to set client options that will apply to all subnets in the shared network, client on its icon and then on Edit Client Options. Set any of the fields that you want, and then hit Save to return to the shared network form.
7. Click the Apply Changes button to make it active.

Once a shared network has been created, subnets can be created in or move to it using the Shared network field on the subnet form. The same field can also be used to move a subnet out of any shared networks, by selecting the option.

Once a shared network has been created, it can be renamed or edited by clicking on its icon, changing fields and hitting the Save button. Or is can be removed altogether with the Delete button. Trying to delete a shared network that contains subnets, hosts or groups will bring up a confirmation page asking if you really want to go ahead. If you click Yes, all the configuration entries that the shared network contains will be deleted as well. As usual, after making changes or deleting, you must click the Apply Changes button on the main page to activate the new settings.

Adding and editing groups

Unlike subnets, hosts and shared networks, group entries in the DHCP server configuration do not actually effect the server’s behaviour in any way. Instead, they are just used to define options that will apply to multiple hosts. Even though there are other ways that this can be achieved (such as putting the hosts under a subnet), using a group gives you extra flexibility.

Groups can be defined under subnets and shared networks, but not other groups. In order DHCP server versions, groups do not normally have names – instead, they are identified in Webmin by the number of hosts that they contain. Never versions do support group names, and they can be set using Webmin.

To create a new host group, the steps to follow are :

1. On the module’s main page, click on the Add a new host group link under Hosts and Host Groups to go to the group creation form.
2. Select any existing hosts that you want to be members of this group from the Hosts in this group list.
3. If you want this group to be under a subnet, choose Subnet from the menu in the Group assigned to field, and select the subnet in the list next to it. All hosts in the group must have fixed IP addresses that fall within the subnet’s network. Similarly, a group can be created inside a shared network by choosing Shared Network from the menu and selecting the network name from the list. In both cases, the group will inherit client options and other settings (like the lease length) from its parent subnet or shared net.
4. If hosts in the group need to network boot from a server, enter the name of that server into the Boot file server field. You must also fill in the Boot filename field with the path to an appropriate boot file (downloadable via TFTP) on the boot server.
5. Click the Create button. You will be returned to the module’s main page, while will now include an icon for the new group.
6. Click on the group icon to bring up its editing form, and then on Edit Client Options. This will take you to the page shown in way above for setting options that are sent to client hosts in this group.
7. Set any of the options such as the DNS or NIS servers by following steps 10 to 18 of the Adding and editing subnets section.
8. Click the Save button at the bottom of the page to save the options and return to the group form.
9. Go back to the module’s main page and hit Apply Changes to make your new group active.

Once a group has been created, new or existing hosts can be moved into it using the Host assigned to field on the host form. Any host added to a group will inherit client options and network boot settings from the group, unless overridden by settings for the host itself.

As usual, a group can be edited by clicking on its icon on the module’s main page, making changes and clicking Save. A group can also be removed with the Delete button on its editing page – however, if it contains any hosts you will be asked to confirm the deletion before it and the hosts are actually removed.

A group can also be created under a subnet or shared network by clicking on the Add a new host group link on the page reached by clicking on one of their icons. The group creation form that is displayed no longer has a Group assigned to field – instead, the name of the subnet or shared network that it will be added to is displayed at the top of the page. Apart from that difference, the instructions above can still be followed.

Module access control

As the WebminUsers page explains, the Webmin Users module can be used to limit what a user or group can do with a particular module. For this module, you can control exactly which hosts, groups, subnets and shared networks a user can edit. This can be useful for granting a sub-administrator the rights to set options for only a few hosts within your server configuration, while preventing him from changing subnets and other hosts.

Once a user has been given access to the module, to limit him to editing only certain hosts the steps to follow are :

1. In the Webmin Users module, click on DHCP Server next to the name of the user. This will bring up the module access control form.
2. Change the Can edit module configuration? field to No, so that he cannot edit the configuration file path and the commands that the module uses.
3. Leave Can apply changes? set to Yes, so that he can activate any changes that he makes.
4. Change Can edit global options? to No, so that he cannot change options that apply to all clients.
5. Can view leases? can be safely left set to Yes, but Can remove leases? should be set to No.
6. The Uniq host names?, Uniq subnet IP addresses? and Uniq shared-net names? fields should be changed to Yes to prevent the creation of clashing hosts, subnets and shared networks.
7. The Use security level field determines which configuration entries in the hierarchy the user is allowed access to. The available options and their meanings are : *Level 0 *The user will have access to all entries to which he has been granted. *Level 1 *The user will have access to granted entries, as long as he can access all their children as well. *Level 2 *The user will have access to granted entries, as long as he can access all parent and ancestor entries. *Level 3 *Like levels
8. and 3 combined. Generally, you should leave this option set to level 0 for simplicity’s sake.
9. Assuming you are limiting the user to only editing certain hosts, in the Access groups and Access shared nets field de-select all three options. This will stop the user viewing and editing any groups or shared networks. To stop the user creating hosts and subnets, de-select create in the Access hosts and Access subnets fields.
10. Change the Enable per-subnet ACLs? and Enable per-host ACLs? fields to Yes. This allows you to select exactly which hosts and subnets the user can access from the Per-object ACLs section below. If the first of these fields is set to No instead, the Access subnets checkboxes above determine if the user can view and edit all subnets. Similarly, if the Enable per-host ACLs? field is set to No then the Access hosts checkboxes control the viewing and editing of all hosts.
11. In the Per-object ACLs section, select read/write for any hosts and subnets that the user should be able to configure, and not allowed for the rest. Choosing read only will allow him to view the host or subnet without being able to change it.
12. Finally, click the Save button at the bottom of the page to make the new restrictions active.

Another common use of the DHCP Server module’s access control page is limiting a user to the viewing and cancelling of leases only. This can be done by setting the Can view leases? and *Can remove leases?* fields to Yes, and everything else to No. The user should also be denied access to all hosts, subnets and so on, or possibly given read-only permissions.

NFS File Sharing – Webmin

source: http://doxfer.com/Webmin/NFSExports

This page explains how to export files to other Unix systems by setting up an NFS server.

Introduction to file sharing with NFS

NFS is the most common protocol for sharing files between Unix systems over a network. NFS servers export directories from their local hard disks to NFS clients, which mount them so that they can be accessed like any other directory. Unlike other file sharing protocols such as Windows networking, Netware and AppleShare? , NFS was designed to support client systems that have multiple users. This means that a client never logs into a server, and that the server almost completely trusts the client to authenticate users. The down side is that NFS is not a good protocol for sharing files with client systems that are not fully trusted.

Instead of using usernames and passwords for authentication, NFS uses the IP address of the client. Only trusted clients are allowed to mount directories from the server, so that it is not vulnerable to unauthorized file access from any client on the network. Some additional security can be gained by restricting the access of particular Unix users on a client, or treating all requests from a client as a single user.

On Linux, the /etc/exports file contains a permanent list of directories exported by NFS and the clients they are exported to. Typically this file is read at boot time by the nfsd and mountd programs, which run in the background to service NFS requests. When you change or create exports using Webmin, the exports file is directly updated.

This chapter covers only the sharing of directories from a server using NFS. For details on how to mount an NFS exported directory on a client, see chapter 5. If you want to share files with Windows clients, you should read chapter 43 (which covers Sama) instead, as NFS support is not widely available for Windows.

The NFS Exports module

On Linux, NFS server configuration is done using the NFS Exports module which can be found under the Networking category. After entering the module, the main page will display a list of exported directories and the clients that are allowed to access them, as shown below :

The NFS Exports module

Most Linux distributions come with the programs required for NFS file sharing installed by default. However, if Webmin detects that they are missing from your system an error message will be displayed when you enter the module. If that happens, you will need to install the nfs-server or nfs package from your distribution CD or website.

Exporting a directory

Only directories on local filesystems can be exported via NFS, so it is not possible to re-export files that have been mounted from another NFS server. Neither is it possible to export directories from non-Unix filesystems such as vfat, ntfs or iso-9660. If an exported directory has mount points under it, files under those mount points will not be accessible by NFS clients. So if you exported the root directory / and has a separate filesystem mounted at /home , you would need to also export /home and clients would need to mount it in order to see the files under it.

The steps for exporting a directory are :

1. Click on the Add a new export link on the main page of the module. This will take you to a form for entering the details of the export, as shown below.
2. Enter the directory that you want to share in the Directory to export field.
3. Unless you want the export to be unavailable, make sure the Active? option is set to Yes.
4. The Export to option allows you to choose which clients will have access to the directory. The possible choices are :
   • Everyone Any system that can connect to yours over the network will be able to mount the directory. Be very careful with this choice, as it may allow anyone on the Internet to access your files.
   • Host(s) Only the single specified host or IP address will be allowed. You can also enter a wildcard hostname like *.foo.com for this option to allow all hosts from a domain. However, if you want to export a directory to several specific client hosts then the only solution is to create multiple exports of the same directory, each with a different hostname in this field.
   • WebNFS clients WebNFS? is a rarely used protocol for accessing NFS exports over the internet. Don’t use this option unless you know what you are doing, as it may allow anyone to access your files.
   • Netgroup A netgroup is a list of hosts that is defined on an NIS server. Unfortunately, your system must be an NIS client for this to be useful.
   • Network and Netmask All hosts on the specified network will be allowed to connect. To allow all hosts with IP addresses from 192.168.1.0 to 192.168.1.255, you would enter 192.168.1.0 for the network and 255.255.255.0 for the netmask.
5. If you want to prevent clients from modifying or creating files in the exported directory, set the Access mode option to Read only.
6. If exporting only to trusted systems, set the Trust remote users option to Everyone. However, if you want to ensure that clients only have the permissions of a single Unix user, set Trust remote users to Nobody and enter the user and his primary group into the Treat untrusted users as and Treat untrusted groups as fields respectively. This can be very useful if exporting to a client workstation that is used by single user.
7. Click the Create button to save the export. If you have made any mistakes in any of the fields, an explanatory error message will be displayed. Otherwise, the browser will return to the list of exports.
8. Click the Apply Changes button to make your new export active.

The new NFS export form

Allowed clients should now be able to mount the exported directory. If not, check your system’s error logs for messages from the NFS server processes that explain why the client is being rejected.

Editing or deleting an NFS exports

All the details of any existing NFS export can be edited at any time, by following these steps :

1. On the main page of the module, click on the client under the Exported to column that you want to edit. If a single directory is exported multiple times to different clients, each one must be edited individually.
2. On the export editing form (which is almost identical to the screenshot above) change any of the options, including the directory to share.
3. If you want to delete the export, click the Delete button at the bottom-right of the page. Otherwise, click Save to save your changes. Either way, your browser will return to the module’s main page.
4. Click the Apply Changes button to make the changes active.