Dear Wiki user, You have subscribed to a wiki page or wiki category on "Httpd Wiki" for change notification.
The "TroubleshootingVhosts" page has been changed by SeanTimmins: http://wiki.apache.org/httpd/TroubleshootingVhosts?action=diff&rev1=1&rev2=2 + This page is not linked anywhere yet. I was going to have it linked to my personal home page until I was informed they were not suitable for the wiki. I'll join the documentation project mailing list and the wiki changes list and then update/delete this page as necessary. + = TroubleShooting Virtual Hosts = - The page will concentrate on Named Base virtual hosts mainly because it is what most people use and it is the one most people seem to have problems with. Some things are 2.2 only and are marked as such. + The page will concentrate on Named Base virtual hosts mainly because it is what most people use and it is the one many people seem to have problems with. Some things are httpd 2.2 or 2.4 only and are marked as such. == The Basics == - Virtual Hosts are much simpler than most people seem to think. This is not helped by some unusual 'default' virtual hosts setups distributed by some of the major distributions. + Virtual Hosts are much simpler than most people seem to think. Thing are made more complicated by some unusual 'default' virtual host setups installed by some of the major distributions. - First of all '''read the documentation'''! + First things first, '''read the documentation'''! + * http://httpd.apache.org/docs/current/vhosts/ * http://httpd.apache.org/docs/current/vhosts/examples.html * ExampleVhosts - Secondly, and I can't stree this enough, '''USE''' "apachectl -S", "httpd -S" or "apache2ctl -S" whenever you make any change to your configuration. It outputs various lines of information that are vital to troubleshooting virtual host configuration. + Secondly, and I can't stress this enough, use `apachectl -S` or `httpd -S` whenever you make any change to your configuration. It outputs various lines of information that are vital to the troubleshooting of virtual host configuration. See below for further information. + Thirdly, althought there are a couple of exceptions, if you have defined an access log then httpd will ''always'' log something to it when it serves a request and an entry will always be logged in the error log on a 4xx or 5xx return code. If you cannot find the access/error log entry then you are either looking in the wrong log or the request never hit your web server. - == The Requirements == - * (2.2 only) You '''must''' have a [[http://httpd.apache.org/docs/current/mod/core.html#namevirtualhost|NamedVirtualHost]] directive for each IP+port combination you wish to use, it should be IP:port or *:port + == Virtual Host Requirements == + * (httpd 2.2 only) You ''must'' have a [[http://httpd.apache.org/docs/current/mod/core.html#namevirtualhost|NamedVirtualHost]] directive for each IP+port combination you wish to use, it should be IP:port or *:port and should come before any of your actual virtual hosts. {{{ NameVirtualhost *:80 }}} - * Each [[http://httpd.apache.org/docs/current/vhosts/|<VirtualHost>]] directive should have and IP:port inside it, in httpd 2.2 this should match your [[http://httpd.apache.org/docs/current/mod/core.html#namevirtualhost|NamedVirtualHost]] directive + * Each [[http://httpd.apache.org/docs/current/vhosts/|<VirtualHost>]] directive should have an IP:port inside it, in httpd 2.2 this should match your [[http://httpd.apache.org/docs/current/mod/core.html#namevirtualhost|NamedVirtualHost]] directive - {{{ <VirtualHost *:80> }}} - * Each virtual host '''must''' have its own unique [[http://httpd.apache.org/docs/current/mod/core.html#servername|ServerName]]. It is this that must match the host component of the URL that the user types into their browser. If you define a second virtual host with the same server name then whichever virtual host comes first in the configuration will be the only one that works with that name. + * Each virtual host ''must'' have its own unique [[http://httpd.apache.org/docs/current/mod/core.html#servername|ServerName]]. It is this that must match the host component of the URL that the user types into their browser. If you define a second virtual host with the same server name then whichever virtual host comes first in the configuration will be the only one that works with that name. - {{{ ServerName foo.com }}} - * Each virtual host should also have its own distinct [[http://httpd.apache.org/docs/current/mod/core.html#documentroot|DocumentRoot]]. Although it is possible and in a few cases needed to share document roots, it is normally better to use a single virtual hosts with server aliases. + * Each virtual host should also have its own distinct [[http://httpd.apache.org/docs/current/mod/core.html#documentroot|DocumentRoot]]. Although it is possible, and in a few cases needed, to share the document root, if this is required it is normally better to use a single virtual host with server aliases. {{{ DocumentRoot /var/www/foo }}} == The First Virtual Host == - With named base virtual hosts, the first one apache finds in the configuration files is special. This is the one that requests will be passed to if apache has no way to determine which specific virtual host to use. It is the '''default''' virtual host. + With named base virtual hosts, the first one apache finds in the configuration files is special. This is the one that requests will be passed to, if apache has no way to determine which specific virtual host to use. It is the ''default'' virtual host. - If the user types `http://my.domain.com/my/url/path` then it is the string `my.domain.com` that is matched against the host component of the [[http://httpd.apache.org/docs/current/mod/core.html#servername|ServerName]] or any [[http://httpd.apache.org/docs/current/mod/core.html#serveralias|ServerAlias]] (Remember Server``Name can contain an optional schema and port) + In general, if the user types `http://my.domain.com/my/url/path` into their browser, then it is the string `my.domain.com` that is matched against the host component of the [[http://httpd.apache.org/docs/current/mod/core.html#servername|ServerName]] or any [[http://httpd.apache.org/docs/current/mod/core.html#serveralias|ServerAlias]] (Remember Server``Name can contain an optional schema and port). + Anything that does not match a ServerName or ServerAlias in one of your virtual hosts will be served by the default. + - ''Advanced Note:'' It is actually the contents of the `Host` header that is used rather than the host component of the URL. Though these would normally be the same. + ''Note:'' It is actually the contents of the `Host` header that is used rather than the host component of the URL, though these would normally be the same. == Virtual Host Example == + + Here is a very simple 2 virtual hosts example that we will use to highlight the output of `apachectl -S`. {{{ + # NameVirtualhost is needed in httpd 2.2 only NameVirtualHost 192.168.0.1:80 - # any request to foo.com, or indeen anything other than bar.com that resolves + # Any request to foo.com, or indeed anything other than bar.com that resolves - # to 192.160.0.1 will hit this first virtual host + # to 192.168.0.1 will hit this first virtual host <VirtualHost 192.168.0.1:80> ServerName foo.com ServerAlias www.foo.com @@ -64, +71 @@ DocumentRoot /var/www/bar </Virtualhost> }}} + == Problem Solving Tips == - - == Troubleshooting == The [[http://httpd.apache.org/docs/current/mod/core.html#errorlog|ErrorLog]] is always the first place to look when you get any problems, but there are things you can do to make troubleshooting virtual hosts easier. - * Give each virtual host its own access and error log. this will enable you to easily separate out requests to each virtual host and in particular verify a particular request is actually hitting the virtual host you think it is. An alternative for determining the virtual host a request hits is to add `%v` to the [[http://httpd.apache.org/docs/current/mod/mod_log_config.html#logformat|LogFormat]] + * Give each virtual host its own access and error log. This will enable you to easily separate out requests to each virtual host and in particular verify a particular request is actually hitting the virtual host you think it should be. An alternative for determining the virtual host a request hits is to add `%v` to the relevant [[http://httpd.apache.org/docs/current/mod/mod_log_config.html#logformat|LogFormat]]. - === Log Files === + * Use a command line tool to access your virtual host. This is particularly useful when you have redirects in place and wish to make sure they are working correctly. Commonly used tools for the troubleshooting of httpd from the command line are [[http://curl.haxx.se|curl]] and [[http://www.gnu.org/software/wget/|wget]]. If you have the perl LWP module installed you can use lwp-request (often linked as GET). It is worth familiarising yourself with these tools and their options. + {{{ + # Get the headers from foo.com + # Output in the file headers.txt + curl -s -D headers.txt -o /dev/null http://foo.com/ + GET -uUsSed http://foo.com/ > headers.txt + + # Using just the host header instead of the fqdn + # Output in the file headers.txt + curl -H "Host: foo.com" -s -D headers.txt -o /dev/null http://192.168.0.1/ + wget --header="Host: foo.com" -nv --save-headers=on -O headers.txt http://192.168.0.1/ + GET -H "Host: foo.com" -uUsSed http://192.168.0.1/ > headers.txt + + # Get headers and content to terminal + curl -s -i http://foo.com/ + wget -nv --save-headers=on -O - http://foo.com/ + GET -uUsSe http://foo.com/ + }}} + + * ''Every'' time you modify your configuration you should be running `apachectl -S` to test it before you restart your web server. Below are two examples of the output from this command for httpd 2.2 and 2.4 when using the example virtual host configuration above, with a line by line explanation after each. + {{{ + # Example output from httpd 2.2 + 1: VirtualHost configuration: + 2: 192.168.0.1:8080 is a NameVirtualHost + 3: default server foo.com (/etc/httpd/conf.d/vhosts.conf:11) + 4: port 80 namevhost foo.com (/etc/httpd/conf.d/vhosts.conf:11) + 5: port 80 namevhost bar.com (/etc/httpd/conf.d/vhosts.conf:18) + }}} + + 1. The first line of output, unless there are warnings/errors. + + 1. If there is no Name``Virtual``Host directive this line will not be present. + + 1. The 'default' virtual host is the one with server name 'foo.com'. It was defined in the file /etc/httpd/conf.d/vhosts.conf and started on line 9. + + 1. A second entry refering to the default virtual host. It runs on port 80 and it's server name is foo.com. The file and start line are repeated. + + 1. We have another name based virtual host running on port 80 with server name bar.com. It was defined in the file /etc/httpd/conf.d/vhosts.conf and started on line 18. + + {{{ + # Example output from httpd 2.4 + 1: VirtualHost configuration: + 2: 192.168.0.1:80 is a NameVirtualHost + 3: default server foo.com (/etc/httpd/conf.d/vhosts.conf:2) + 4: port 80 namevhost foo.com (/etc/httpd/conf.d/vhosts.conf:2) + 5: alias www.foo.com + 6: port 80 namevhost bar.com (/etc/httpd/conf.d/vhosts.conf:9) + 7: alias www.bar.com + 8: <After this are several lines of output relating to the global configuration> + }}} + + 1. The first line of output, unless there are warnings/errors. + + 1. httpd 2.4 automatically works out you need a name based virtual host (you will get a warning if the directive is present). + + 1. The 'default' virtual host is the one with server name 'foo.com'. It was defined in the file /etc/httpd/conf.d/vhosts.conf and started on line 2. + + 1. A second entry refering to the default virtual host. It runs on port 80 and it's server name is foo.com. The file and start line are repeated. + + 1. The name virtual host foo.com has an alias www.foo.com (this output is new in httpd 2.4). + + 1. We have another name based virtual host running on port 80 with server name bar.com. It was defined in the file /etc/httpd/conf.d/vhosts.conf and started on line 9. + + 1. The name virtual host bar.com has an alias www.bar.com. + + 1. After the virtual hosts information, the output contains lines useful for debugging the global configuration. + + <<BR>> + In the ouput, if you see any duplicate server names or aliases (other than the default one and the namevhost immediately after it) then you have virtual hosts with duplicate names and only the first one in the list will work. + + If with httpd 2.2 you do not have a Name``Virtual``Host directive you will not see the line ending in `is a NameVirtualHost` and depending on your exact configuration you may see something similar to one of the following warnings: + + {{{ + # If your virtual hosts are defined with IP:port + [Fri Jan 11 22:27:30 2013] [warn] VirtualHost 192.168.0.1:80 overlaps with VirtualHost 192.168.0.1:80, the first has precedence, perhaps you need a NameVirtualHost directive + # If your virtual hosts are defined with *:port + [Fri Jan 11 22:28:04 2013] [warn] _default_ VirtualHost overlap on port 80, the first has precedence + }}} + --------------------------------------------------------------------- To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org For additional commands, e-mail: docs-h...@httpd.apache.org
