Installing the apache web server on a Gentoo server is as simple as using “emerge”.
The workhorse of the Internet
Ah, the apache web server. Used to host more web sites than any other web server out there, apache's popularity stems from its flexibility and stable performance. It also doesn't hurt that there's a lot of documentation for it that's just a web search away.
In this article series we'll cover how to install apache and how to dive into its configuration to tailor the web server to your needs. We'll also throw in some instructions for installing PHP, given its widespread use on web servers these days.
Note that we'll usually refer to the apache web server as just apache, even though technically apache puts out other projects too. Honestly, we do it for the same reason most of the Internet does it: It's easier to just say “apache”.
We start at the beginning.
Checking iptables
The first step is really a precautionary one before installing the web server. We'll want to make sure that once the web server is running browsers will actually be able to reach it.
You may be running a firewall on your server, and it might be blocking traffic to the standard web server ports, port 80 (for regular connections) and port 443 (for secure connections). We'll talk about how to check iptables, since it's the firewall method used most often (and because it's what we use in our server setup articles), but the same general principle will apply to any other firewall solution.
Check the current firewall rules, to start off:
sudo /sbin/iptables -L
You'll want to look those rules over to make sure ports 80 and 443 are open for business. If it turns out you don't have a firewall running no changes are necessary. If you're using the default rules from our slice setup articles, you should already find ports 80 and 443 are open. Otherwise you'll want to apply rules to open those ports.
Rules like these should suffice for even the strictest iptables configuration:
-I INPUT -p tcp --dport 80 -m state --state NEW,ESTABLISHED -j ACCEPT -I OUTPUT -p tcp --sport 80 -m state --state ESTABLISHED -j ACCEPT -I INPUT -p tcp --dport 443 -m state --state NEW,ESTABLISHED -j ACCEPT -I OUTPUT -p tcp --sport 443 -m state --state ESTABLISHED -j ACCEPT
Apache Install
Installing a basic apache web server is straightforward:
sudo emerge --sync sudo emerge apache
That should install apache along with a couple other packages to support some commonly-used options (like SSL support).
rc-update
Now that we have apache installed and working properly, we need to make sure it's set to start automatically if the slice is rebooted.
sudo /sbin/rc-update add apache2 default
ServerName
If you start apache now you might see this warning:
apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.0.1 for ServerName
The warning comes from apache2 because that's the name of the apache process when it's running (and thus what you'd look for in a ps list or top).
We'll take a closer look at apache configuration later in this article series, but for now let's attend to that complaint.
First, let's create a “custom” directory in apache's configuration directory:
sudo mkdir /etc/apache2/custom
Now create a config file to store your server name:
sudo nano /etc/apache2/custom/servername.conf
Put the following line into that file:
ServerName demo
Change “demo” to the name of your slice or another handy identifier. Don't use the domain names of any of your sites for this value. We'll want to use those when we set up virtual hosts later in this series.
When you're done save servername.conf.
Finally, edit the main apache config file:
sudo nano /etc/apache2/httpd.conf
Scroll down toward the end of that file. Right before the “Supplemental configuration” section (the block that ends with “Include /etc/apache2/modules.d/*.conf”) add this line:
Include /etc/apache2/custom/*.conf
We'll talk about why we did all that work when we talk about apache's config layout in a later article. For now, save that change to httpd.conf.
Graceful restart
Now that you've explicitly told apache what your server name should be, let's gracefully restart Apache:
sudo /usr/sbin/apache2ctl graceful
You shouldn't see the warning this time. If you do, you may want to double-check your change to the servername.conf file.
Using apache2ctl
We used apache2ctl to restart apache just now. That command can be used to start or stop apache in a manner similar to using the init script /etc/init.d/apache2. If you just run apache2ctl by itself you get a list of the arguments you can send it, along the lines of:
Normal Options:
start stop restart pause zap
Default init.d options.
Additional Options:
configdump configtest fullstatus graceful gracefulstop modules reload virtualhosts
The start, stop, and restart commands are pretty self-explanatory, and often they're all you will need. But let's take a moment to briefly explain some other arguments.
Graceful
graceful gracefulstop
The graceful argument to apache2ctl asks apache to restart, but to do it in a way that won't interfere with existing connections. The gracefulstop argument is similar to stop, but apache will let existing connections finish their business before cutting them off. The common thread there is that while the core of the web server is restarted or stopped, processes are left in place to continue handling old connections using the old configuration.
So on paper, graceful looks pretty good. When it works, you can restart the web server without actually cutting any users off or interrupting their sessions. In practice, graceful doesn't always execute perfectly. Some modules don't work well with graceful restarts, and sometimes you can end up with several hung connections that won't go away. There are also some configuration changes that only take effect after a full restart.
If you want to use graceful to restart apache after most configuration changes, just be aware of the possibility that it won't always work like you'd want it to. Make a test connection to the web server immediately after a graceful restart to make sure it accepts new connections using the new configuration. If graceful restarts don't consistently work, you may be better off just using a regular restart command instead (it may not be graceful, but it's more reliable).
Should you run the apache init script with the reload argument, behind the scenes it runs apache2ctl graceful to handle the configuration reload.
Configtest
configtest
The configtest argument to apache2ctl doesn't interfere with a running web server. It simply asks apache to skim its configuration files to check for syntax errors. It's good to use this one after any change.
The configtest won't guarantee that a configuration change will actually work, mind you, but it does let you catch the more obvious configuration problems like a missing bracket or misspelled keyword.
Status
status fullstatus
The status command can present you with a snapshot of what the web server is doing at a given moment, but it usually takes some preparation to get it to work. Since the output is a bit more complex than just whether or not the web server is running, you may not want to go to the effort.
To get a response from the status or fullstatus commands, you would need to enable mod_status on the web server, configure it, and have a text-based web browser like lynx or links installed on your slice. If you just try to run apache2ctl status, apache will let you know what needs to be done.
Apache logs
By default, the apache logs are stored in the directory:
/var/log/apache2/
You will need to use sudo to look around in that directory since it's restricted to root access. The two main log files you'll find in there are “accesslog” and “errorlog”.
The access_log will store all access attempts apache receives. This can be useful for traffic analysis, but it's also handy for troubleshooting if you need to figure out if a connection attempt got through to the web server (or if it's been blocked by something like iptables).
The error_log stores the errors apache reports. This can include both errors reported by the binary or by modules (like PHP complaining about not finding an SQL library) and errors the web server has sent to users (like a “file not found” error).
Test the server
If you navigate to your server's IP address in a web browser:
http://123.45.67.890
You should see a default page telling you apache is working. Hooray for working!
If not then, well, it doesn't work. If you didn't see the “It works!” page and your browser took a minute to tell you it couldn't get to it (like a “Server unavailable” error), then iptables may be blocking access to port 80.
If your browser gives you an error response right away, like a “connection refused” error, then apache may not be running. Try starting it up to be sure:
sudo /usr/sbin/apache2ctl start
If that doesn't work, and you didn't get a useful explanation from apache2ctl, check the error log in apache's log directory. Common problems include a mistake in the /etc/apache2/httpd.conf file, or another web server already running and keeping apache from attaching itself to port 80.
USE flag
Now that you have apache working you probably want to make sure other programs on your server will work with it if they're able to. To do that we use Gentoo's USE flags.
The USE flags help customize the build options portage uses when it compiles installed software. It's a central part of Gentoo, so knowing something about it can help if you're going to keep using that distribution. You can read more about USE flags and how they're used in the Gentoo documentation.
For the moment we just need to know that the USE flag for apache is apache2. Edit the file:
/etc/make.conf
Go down to the line that starts with USE=, and add apache2 to the end of the list. For example, after making the change you might have a USE definition that looks like this:
USE="-gnome -kde -alsa -cups -qt3 -qt4 apache2"
The - in front of some of those options tells portage not to enable those USE flags even if they would normally be enabled for a software package by default.
If you know another installed package needs to be rebuilt to add apache support just “emerge” that package again with the apache2 USE flag set.
A full list of official USE flags can be found in the online index of USE flags, or can be found locally in this file:
/usr/portage/profiles/use.desc
You can search it later if you want to check for flags pertaining to a particular software package (like MySQL or PHP).
Summary
You should now have a functioning, but very basic, apache installation running on your server. There's more work to be done to properly configure apache and get your site on there, but you've completed the first step.
- Author: Jered @ SliceHost