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