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=3&rev2=4 - 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. + Some Virtual hosts troubleshooting information/tips based on the common questions about them in #httpd = TroubleShooting Virtual Hosts = - The page will concentrate on Name Based 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 page will concentrate on Name Based virtual hosts mainly because it is what most people use and it is the one many people seem to have problems with. Version specifc information is marked as such. == The Basics == Virtual Hosts are much simpler than most people seem to think but in some cases are made more complicated by some unusual 'default' virtual host setups installed by some of the major distributions. @@ -14, +14 @@ * http://httpd.apache.org/docs/current/vhosts/examples.html * ExampleVhosts - 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 [[#apachectl|below]] for further information. + Secondly, and this cannot be stressed enough, use `apachectl -S` or `httpd -S` whenever any changes are made to the configuration. It outputs various lines of information that are vital to the troubleshooting of virtual host configurations. See [[#apachectl|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 actually reached your web server. + Thirdly, althought there are a couple of exceptions, if an access log is defined 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 return code. An error log entry will also normally be written on a 5xx return code, however when using 3rd party modules, CGIs or launguages such as php it is possible for these to be hijacked and nothing will be in the log. If you cannot find the access/error log entry then you are either looking in the wrong log or the request didn't actually reach the web server. == 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. + * (httpd prior to v2.3.11) You ''must'' have a [[http://httpd.apache.org/docs/current/mod/core.html#namevirtualhost|NamedVirtualHost]] directive for each IP+port combination in use, it should be IP:port or *:port and should come before any of the actual virtual hosts. {{{ NameVirtualhost *:80 }}} - * 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. Unless you know exactly what you are doing, do not mix IP:port and *:port as the results may be unpredictable. + * Each [[http://httpd.apache.org/docs/current/vhosts/|<VirtualHost>]] directive should have an IP:port inside it, in httpd prior to v2.3.11 this should match the [[http://httpd.apache.org/docs/current/mod/core.html#namevirtualhost|NamedVirtualHost]] directive. Unless you know exactly what you are doing, do not mix IP:port and *:port as the results may be unpredictable. {{{ <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 another virtual host with the same server name (or server alias) 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 another virtual host is defined with the same server name (or server alias) then whichever virtual host comes first in the configuration will be the only one that works with that name. {{{ ServerName foo.com }}} @@ -42, +42 @@ == 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. - 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]] directive (Remember Server``Name can contain an optional schema and port). Anything that does not match a Server``Name or Server``Alias in your configuration will be served by the default virtual host. + 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]] directive (Remember Server``Name can contain an optional schema and port). Anything that does not match a Server``Name or Server``Alias in the configuration will be served by the default virtual host. - ''Note:'' It is actually the contents of the `Host` header that is actually used by httpd here rather than the host component of the URL, though these would normally be the same. + ''Note:'' It is the contents of the `Host` header that is actually used by httpd here rather than the host component of the URL, though these would normally be the same. == Virtual Host Example == Here is a very simple two virtual host example that we will use to highlight the output of `apachectl -S`. {{{ - # NameVirtualhost is needed in httpd 2.2 only + # NameVirtualhost is needed in httpd prior to v2.3.11 NameVirtualHost 192.168.0.1:80 # Any request to foo.com, or indeed anything other than bar.com that resolves @@ -72, +72 @@ == Problem Solving Tips == - 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. + The [[http://httpd.apache.org/docs/current/mod/core.html#errorlog|ErrorLog]] is always the first place to look when any problems arise, but there are things that can be done 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 that a particular request is actually being served by the virtual host you think it should be. An alternative for determining the virtual host a request is served by is to add `%v` to the relevant [[http://httpd.apache.org/docs/current/mod/mod_log_config.html#logformat|LogFormat]]. + * Give each virtual host its own access and error log. This is a simple way to separate out the requests to each virtual host and in particular verify that a request is actually being served by the virtual host you think it should be. An alternative to this is to add `%v` to the relevant [[http://httpd.apache.org/docs/current/mod/mod_log_config.html#logformat|LogFormat]]. + * In conjunction with the access/error logs, make a request that is guaranteed to generate a 404 Not Found error. You can then search the access and error logs for the entries relating to this request. + - * 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 a web server 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 usable as `GET`). It is worth familiarising yourself with these tools and their options, but here are some examples by way of an introduction. + * Use a command line tool to access a specific virtual host. This is particularly useful when there are redirects in place and you wish to make sure they are working correctly. Commonly used tools for the troubleshooting of a web server from the command line are [[http://curl.haxx.se|curl]] and [[http://www.gnu.org/software/wget/|wget]]. If the perl LWP module is installed then lwp-request may also be used (often usable as `GET`). It is worth learning these tools and their options, but here are some examples by way of an introduction. {{{ # Get the headers from foo.com. Output in the file headers.txt @@ -95, +97 @@ }}} <<Anchor(apachectl)>> - * ''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, with line numbers added for clarity, with a line by line explanation of each. The output was generate using a simple httpd install with the example virtual host configuration above. + * ''Every'' time a modification is made to httpd's configuration you should be running `apachectl -S` to test it before the web server is restarted. Below are two examples of the output from this command for httpd v2.2.x and 2.4.x with line numbers added for clarity. A line by line explanation of each follows. The output was generated using a basic httpd install with the example virtual host configuration above. {{{ # Example output from httpd 2.2 @@ -130, +132 @@ 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. httpd 2.4 automatically works out the need for a name based virtual host (a warning is output 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. @@ -145, +147 @@ 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. + In the ouput, if there are any duplicate server names or aliases (other than the default one and the namevhost immediately after it) then there are virtual hosts with duplicate names and only the first one in the list will work. - With httpd 2.2, if 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: + With httpd prior to v2.3.11, if you do not have a Name``Virtual``Host directive you will not see the line ending in `is a NameVirtualHost` and depending on the exact configuration you may see something similar to one of the following warnings: {{{ - # If your virtual hosts are defined with IP:port + # If the 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 + # If the 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
