b442af56a5e2104663b84fb345c070ce185d4ab3slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. You may obtain a copy of the License at
acc36ab93565d2880447d535da6ca6e5feac7a70nd Unless required by applicable law or agreed to in writing, software
acc36ab93565d2880447d535da6ca6e5feac7a70nd distributed under the License is distributed on an "AS IS" BASIS,
acc36ab93565d2880447d535da6ca6e5feac7a70nd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
acc36ab93565d2880447d535da6ca6e5feac7a70nd See the License for the specific language governing permissions and
acc36ab93565d2880447d535da6ca6e5feac7a70nd limitations under the License.
654d8eb036bedc99e90e11910ee02d3421417697rbowen <p>Configuring Apache HTTP Server to listen on specific addresses and ports.</p>
b442af56a5e2104663b84fb345c070ce185d4ab3slive <seealso><a href="vhosts/">Virtual Hosts</a></seealso>
b442af56a5e2104663b84fb345c070ce185d4ab3slive <seealso><a href="dns-caveats.html">DNS Issues</a></seealso>
b442af56a5e2104663b84fb345c070ce185d4ab3slive <modulelist>
b442af56a5e2104663b84fb345c070ce185d4ab3slive </modulelist>
b442af56a5e2104663b84fb345c070ce185d4ab3slive <directivelist>
09ad82b467d18345648fe3fa155a5914984980dfnd <directive module="core" type="section">VirtualHost</directive>
b442af56a5e2104663b84fb345c070ce185d4ab3slive </directivelist>
c0c6c6e1fc6d75274623ec07b635725c5ffaaa20rbowen <p>When httpd starts, it binds to some port and address on
b442af56a5e2104663b84fb345c070ce185d4ab3slive the local machine and waits for incoming requests. By default,
a166215fba9f76030a979c81f95becff52f5aeefrbowen it listens to all addresses on the machine. However, it may need to
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim be told to listen on specific ports, or only on selected
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim addresses, or a combination of both. This is often combined with the
f50095bc3874806a9cc5e7d283dd9051ef8a0df8nd <a href="vhosts/">Virtual Host</a> feature, which determines how
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <code>httpd</code> responds to different IP addresses, hostnames and
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive <p>The <directive module="mpm_common">Listen</directive>
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive directive tells the server to accept
59c15ce2922cf16717326159168f26f628345a82rbowen incoming requests only on the specified port(s) or
b442af56a5e2104663b84fb345c070ce185d4ab3slive address-and-port combinations. If only a port number is
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive specified in the <directive module="mpm_common">Listen</directive>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim directive, the server listens to the given port on all interfaces.
59c15ce2922cf16717326159168f26f628345a82rbowen If an IP address is given as well as a port, the server will listen
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim on the given port and interface. Multiple <directive
efcdf6bd09d3edaacd4db8e3b6af0678a1201d52kess module="mpm_common">Listen</directive> directives may be used to
b442af56a5e2104663b84fb345c070ce185d4ab3slive specify a number of addresses and ports to listen on. The
b442af56a5e2104663b84fb345c070ce185d4ab3slive server will respond to requests from any of the listed
b442af56a5e2104663b84fb345c070ce185d4ab3slive addresses and ports.</p>
b442af56a5e2104663b84fb345c070ce185d4ab3slive <p>For example, to make the server accept connections on both
844a895a7e909808ee5b1bd431de3832c407eab4noirin port 80 and port 8000, on all interfaces, use:</p>
b47bddbe88fb1489893591d69d4ccab9b873af68humbedooh </highlight>
d4c13075c38c47d33dbab174e69f0dae9ecb4b28nd </example>
844a895a7e909808ee5b1bd431de3832c407eab4noirin <p>To make the server accept connections on port 80 for one interface,
d40245991835767528e0dcd234f176aef45bc038erikabele and port 8000 on another, use</p>
b47bddbe88fb1489893591d69d4ccab9b873af68humbedoohListen 192.0.2.1:80
b47bddbe88fb1489893591d69d4ccab9b873af68humbedoohListen 192.0.2.5:8000
b47bddbe88fb1489893591d69d4ccab9b873af68humbedooh </highlight>
d4c13075c38c47d33dbab174e69f0dae9ecb4b28nd </example>
844a895a7e909808ee5b1bd431de3832c407eab4noirin <p>IPv6 addresses must be enclosed in square brackets, as in the
b442af56a5e2104663b84fb345c070ce185d4ab3slive following example:</p>
cf02129aebf73dd0bdf369b172eb481ff76ac5f6colm Listen [2001:db8::a00:20ff:fea7:ccea]:80
b47bddbe88fb1489893591d69d4ccab9b873af68humbedooh </highlight>
d4c13075c38c47d33dbab174e69f0dae9ecb4b28nd </example>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim module="mpm_common">Listen</directive> directives will result in a
a166215fba9f76030a979c81f95becff52f5aeefrbowen fatal error which will prevent the server from starting up.</p>
d4c13075c38c47d33dbab174e69f0dae9ecb4b28nd (48)Address already in use: make_sock: could not bind to address [::]:80
2104559c61c6056b2f4ef117748af1871b467e81rbowen href="http://wiki.apache.org/httpd/CouldNotBindToAddress">the
2104559c61c6056b2f4ef117748af1871b467e81rbowen discussion in the wiki</a> for further troubleshooting tips.</p>
1d9308ed0075062953a246d16bcda888a1be1adeslive <p>A growing number of platforms implement IPv6, and
1d9308ed0075062953a246d16bcda888a1be1adeslive <glossary>APR</glossary> supports IPv6 on most of these platforms,
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim allowing httpd to allocate IPv6 sockets, and to handle requests sent
844a895a7e909808ee5b1bd431de3832c407eab4noirin over IPv6.</p>
c0c6c6e1fc6d75274623ec07b635725c5ffaaa20rbowen <p>One complicating factor for httpd administrators is whether or
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim not an IPv6 socket can handle both IPv4 connections and IPv6
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim connections. Handling IPv4 connections with an IPv6 socket uses
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim IPv4-mapped IPv6 addresses, which are allowed by default on most
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim platforms, but are disallowed by default on FreeBSD, NetBSD, and
844a895a7e909808ee5b1bd431de3832c407eab4noirin OpenBSD, in order to match the system-wide policy on those
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim platforms. On systems where it is disallowed by default, a
a1ef40892ffa2b44fc249423c5b6c42a74a84c68nd special <program>configure</program> parameter can change this behavior
c0c6c6e1fc6d75274623ec07b635725c5ffaaa20rbowen for httpd.</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>On the other hand, on some platforms, such as Linux and Tru64, the
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <strong>only</strong> way to handle both IPv6 and IPv4 is to use
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim mapped addresses. If you want <code>httpd</code> to handle IPv4 and IPv6 connections
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim with a minimum of sockets, which requires using IPv4-mapped IPv6
a1ef40892ffa2b44fc249423c5b6c42a74a84c68nd addresses, specify the <code>--enable-v4-mapped</code> <program>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p><code>--enable-v4-mapped</code> is the default on all platforms except
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim FreeBSD, NetBSD, and OpenBSD, so this is probably how your httpd was
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>If you want httpd to handle IPv4 connections only, regardless of
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim what your platform and APR will support, specify an IPv4 address on all
efcdf6bd09d3edaacd4db8e3b6af0678a1201d52kess <directive module="mpm_common">Listen</directive> directives, as in the
efcdf6bd09d3edaacd4db8e3b6af0678a1201d52kess following examples:</p>
b47bddbe88fb1489893591d69d4ccab9b873af68humbedoohListen 0.0.0.0:80
b47bddbe88fb1489893591d69d4ccab9b873af68humbedoohListen 192.0.2.1:80
b47bddbe88fb1489893591d69d4ccab9b873af68humbedooh </highlight>
d4c13075c38c47d33dbab174e69f0dae9ecb4b28nd </example>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>If your platform supports it and you want httpd to handle IPv4 and
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim IPv6 connections on separate sockets (i.e., to disable IPv4-mapped
a1ef40892ffa2b44fc249423c5b6c42a74a84c68nd addresses), specify the <code>--disable-v4-mapped</code> <program>
a1ef40892ffa2b44fc249423c5b6c42a74a84c68nd configure</program> option. <code>--disable-v4-mapped</code> is the
a1ef40892ffa2b44fc249423c5b6c42a74a84c68nd default on FreeBSD, NetBSD, and OpenBSD.</p>
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier <p>The optional second <var>protocol</var> argument of
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim is not required for most
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim configurations. If not specified, <code>https</code> is the default for
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim port 443 and <code>http</code> the default for all other ports. The
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier protocol is used to determine which module should handle a request, and
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim to apply protocol specific optimizations with the
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier <directive module="core">AcceptFilter</directive> directive.</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>You only need to set the protocol if you are running on non-standard
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier ports. For example, running an <code>https</code> site on port 8443:</p>
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier Listen 192.170.2.1:8443 https
b47bddbe88fb1489893591d69d4ccab9b873af68humbedooh </highlight>
d4c13075c38c47d33dbab174e69f0dae9ecb4b28nd </example>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim module="mpm_common">Listen</directive> directive does not implement
844a895a7e909808ee5b1bd431de3832c407eab4noirin Virtual Hosts - it only tells the
844a895a7e909808ee5b1bd431de3832c407eab4noirin main server what addresses and ports to listen on. If no
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive <directive module="core" type="section">VirtualHost</directive>
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive directives are used, the server will behave
844a895a7e909808ee5b1bd431de3832c407eab4noirin in the same way for all accepted requests. However,
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive <directive module="core" type="section">VirtualHost</directive>
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive can be used to specify a different behavior
844a895a7e909808ee5b1bd431de3832c407eab4noirin for one or more of the addresses or ports. To implement a
b442af56a5e2104663b84fb345c070ce185d4ab3slive VirtualHost, the server must first be told to listen to the
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive address and port to be used. Then a
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive <directive module="core" type="section">VirtualHost</directive> section
844a895a7e909808ee5b1bd431de3832c407eab4noirin should be created for the specified address and port to set the
b442af56a5e2104663b84fb345c070ce185d4ab3slive behavior of this virtual host. Note that if the
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive <directive module="core" type="section">VirtualHost</directive>
9530629c5ba74f47ba0bad2cd4f432c9c5cd4ff4slive is set for an address and port that the
b442af56a5e2104663b84fb345c070ce185d4ab3slive server is not listening to, it cannot be accessed.</p>
b442af56a5e2104663b84fb345c070ce185d4ab3slive</manualpage>