Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc

Please improve it in any way that you see fit, and remove this notice {{Cleanup}} from the article. For tips on cleaning and formatting see Cleanup process

Apache2 Series


  • Installing Apache 2


Addons & Tunnels





Getting Started

Apache2 will now work on most systems with no problems, if it doesn't work for you, the section on Common Problems might be helpful. For additional information about setting up your computer to service multiple domains see HOWTO Setup mysql virtual hosting.

Start by emerging apache2: add "apache2" to your USE flags in make.conf and

emerge -av apache

Then add the following to the bottom of /etc/apache2/httpd.conf

Note this may already be contained in /etc/apache2/vhosts.d/00_default_vhost.conf with newer apache2 installs, and hence setting this is not required - unless you' like to adjust.

ServerName <name>
Listen <port> 

Where <name> is the name of the host and <port> is the port you want Apache to listen on. If Apache is hosted locally, you can usually use localhost for name. Port will usually be 80 for webserving. You should now have a basic, functional Apache server.

Apache 2.2.8 allows you to set the included modules using APACHE2_MODULES and the used mpm using APACHE2_MPMS in your make.conf. If you do not specify those variables the following default is used:

nano -w /etc/make.conf
APACHE2_MODULES="actions alias
       auth_basic authn_alias authn_anon authn_dbm authn_default authn_file authz_dbm authz_default authz_groupfile
       authz_host authz_owner authz_user autoindex cache dav dav_fs dav_lock deflate dir disk_cache env expires
       ext_filter file_cache filter headers include info log_config logio mem_cache mime mime_magic negotiation
       rewrite setenvif speling status unique_id userdir usertrack vhost_alias proxy"
# default disabled modules:
#       -asis -auth_digest -authn_dbd -cern_meta -charset_lite -dbd -dumpio -ident -imagemap -log_forensic
#       -proxy -proxy_ajp -proxy_balancer -proxy_connect -proxy_ftp -proxy_http -version"
# default disabled mpms:
# -event -itk -peruser -prefork -worker"

Starting Apache

To start Apache2 run:

/etc/init.d/apache2 start

If you'd like to have have Apache2 start on boot run:

rc-update add apache2 default

See the init scripts section of the manual for more information.

You should now have a working apache installation. Point your browser at http://localhost/ and you should see a welcome page.

Apache's simplest functionality is just serving plain old files. The basic pattern is: replace http://hostname/ with the directory (document root) that contains the website. The default configuration tells Apache that the website is located in /var/www/localhost/htdocs/. This can be changed in /etc/apache2/vhosts.d/00_default_vhost.conf Here's a couple examples:

Actually, you'll find that /var/www/localhost/htdocs/index.html contains the HTML of the welcome page you saw earlier at http://localhost/. Notice that Apache served htdocs/index.html when you asked for htdocs/ . This is because of the way HTTP is designed. Apache can't send entire directories, but it needs to show something. A listing (index) of the directory seems sensible. Apache allows you to specify a filename to use as the index, or it can generate its own directory listing. It's obviously become very common for the 'index' to just be a default page; it doesn't have to actually list the contents of the directory.


Apache is extremely versatile. It can serve files using HTTP and it can serve them using FTP. It can send a file on the hard drive, or the output of a PHP script. To achieve this, Apache uses modules. Other applications would call them plugins. Whatever they're called, they usually add functionality and can be installed and uninstalled independently; you don't have to uninstall, or even recompile, Apache to uninstall a module.

Apache modules are typically named mod_something. Some come bundled with Apache, others need to be installed separately. Portage contains many Apache modules. The process usually goes something like:

emerge mod_perl
nano /etc/conf.d/apache2

Some guides for specific modules can be found in the Apache Index in this wiki. You might also want to read the documentation for modules that come with Apache.


The httpd.conf, (/etc/apache2/httpd.conf,) that comes with Gentoo demonstrates quite a bit. However, it probably does both more and less than you need it to. Apache configuration files have a consistent syntax.

Any line that starts with # is ignored

# Apache doesn't care what I put here, 
# It's handy for leaving comments

Most lines start with a directive and are followed by one or more arguments.

SomeDirective one or more arguments

Directive can then be wrapped in sections to control when they apply

  # Will only apply when the section matches

Sections can be nested to add further constraints. Here's part of an httpd.conf file:

# If mod_alias is loaded
<IfModule mod_alias.c>
    # Alias is a directive and it only applies if mod_alias is loaded
    Alias /icons/ "/usr/share/httpd/icons/"
    # If the file is in the directory
    <Directory "/usr/share/httpd/icons">
        # Options will only apply if:
        #   mod_alias is loaded AND
        #   the file is in the directory
        Options Indexes MultiViews

You can read more about configuration files and sections in the official Apache manual. It's a handy reference.

Common Problems

[warn] _default_ VirtualHost overlap on port 80, the first has precedence

This problem pops up when updating from previous versions to Apache/2.2.4 (June 2007). Here is how to fix it. First make sure the default vhost is enabled :

Code: /etc/conf.d/apache2


Secondly comment out the next line

Code: /etc/apache2/httpd.conf
 #NameVirtualHost *  

As last update ALL VirtualHost tags in /etc/apache2/vhosts.d/00_default_vhost.conf :

 Change <VirtualHost *:80> to <VirtualHost YOUR_IP:80>

Replace YOUR_IP with your ip.

All done restart apache and all will run normal again. Don't you love updating ?

Update: Instead of the above, typically, what you want is to use the ServerName directive. See HOWTO_Setup_mysql_virtual_hosting#Apache.2FPHP for an example.

Another Update: If you don't put much money on the apache config files (/etc/apache2/*), simply rename the folder and re-emerge apache. Apache should work now. Idea taken from this thread. In the same thread it is also stated that removing xx_mod_ssl.default-vhost.conf should work. It might be interesting to try that first.

(98)Address already in use: make_sock: could not bind to address no listening sockets available, shutting down

Remove Listen 80 from your /etc/apache2/httpd.conf

SSI Not Working

When configuring for SSI (Server Side Includes), an error may occur:

mod_include: Options +Includes (or IncludesNoExec) wasn't set, INCLUDES filter removed

The problem is that setting Options +Includes in either .htaccess or httpd.conf is overwritten by the additional configuration file as defined at the end of httpd.conf.

Include /etc/apache2/vhosts.d/*.conf

You need to edit this additional configuration file such that

AllowOverride None

Is replaced by

AllowOverride Options

Could Not Open Error Log

While starting Apache, it prints:

Error while starting apache: (2)No such file or directory: apache2: could not open error log file /usr/lib/apache2/logs/error_log.

/usr/lib/apache2/logs should be a symlink pointing to /var/log/apache2 . Check it using:

ls -la /usr/lib/apache2/logs

(note the lack of a slash on the end). If /var/log/apache2 is missing, create it and make sure you give apache ownership:

mkdir /var/log/apache2
chown apache:apache /var/log/apache2

If the symlink /usr/lib/apache2/logs is missing, you can create it:

ln -s /var/log/apache2 /usr/lib/apache2/logs

You don't need to set permissions on the symlink.

Check the Logs

See /var/log/apache2/error_log for errors, especially towards the end of the file. You may find tail useful because it displays only the last few lines of a file:

tail /var/log/apache2/error_log

If you wish to keep an eye on the log the -f option for tail may be useful:

 tail -f /var/log/apache2/error_log

Here's one error you might see:

Error: [alert] (EAI 2)Name or service not known: mod_unique_id: unable to find IPv4 address of ""

With the base installation "mod_unique_id" is turned on, this can cause problems, notably the server not starting. Simply comment out this module in /etc/apache2/httpd.conf and the problem will be solved.

This error occurs when /etc/hosts does not contain an entry for HOSTNAME (in /etc/conf.d/hostname). Add one and it will go away.

(Your config file might be /etc/apache2/conf/apache2.conf)

Forbidden User Directories

If the server is returning "403 Forbidden" while accessing http://server/~username/ Make sure Apache (usually user apache and group apache) has read access to username's home directory and public_html (or equivalent). You can grant everyone read access using:

chmod 755 ~username/ ~username/public_html/

Not Enough Entropy

If Apache2

  • accepts connections
  • does not respond to clients
  • creates exactly one process
  • is not stopped by
/etc/init.d/apache2 stop

Check to see how much entropy is available using:

cat /proc/sys/kernel/random/entropy_avail

If little entropy (less than 100) is available, Apache2 is probably waiting for more so it can generate the secret for digest authentication (mod_auth_digest). To generate more entropy, just do something else for a little while. Grepping the kernel or emerging a package usually works well.

The video-entropyd and audio-entropyd supply /dev/random with entropy gathered from your video and audio devices, respectively. If you have a hardware random number generator (RNG), you can emerge rng-tools and run rngd.

If there's still a shortage of entropy, you can enable the urandom USE flag and re-emerge APR and Apache2. This makes APR use /dev/urandom, which falls back to a pseudorandom number generator when there isn't enough entropy. The program gets a number immediately, but it is cryptographically weaker. This is okay for some things (e.g. solitaire), but completely unacceptable for others (like PGP key generation).

Hardened Gentoo

If you use gentoo hardened profile be careful when you update your system. You can find apache2: Syntax error on line 60 of /etc/apache2/httpd.conf: Cannot load /usr/lib/apache2/modules/ into server: /usr/lib/apache2/modules/ failed to map segment from shared object: Cannot allocate memory

This error can be removed with paxctl -PemRXs /usr/sbin/apache2 command.

Confusing config files

If you start the Apache2 server with the startup script /etc/init.d/apache2 check to see if the line

local myconf="/etc/apache2/httpd.conf"

from /etc/init.d/apache2 points to your configuration script. If it points to apache.conf and you use httpd.conf, make the necessary adjustments.

See Also

Configure LAMP (Linux, Apache, MySQL, and Python/PHP/Perl) - A popular web server combination

Last modified: Sun, 21 Sep 2008 11:48:00 +0000 Hits: 123,584