<h2 id="host">Access control by host <a title="Permanent link" href="#host" class="permalink">¶</a></h2>
<p>
If you wish to restrict access to portions of your site based on the
- host address of your visitors, this is most easily done using
+ host address of your visitors, use
<code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code>.
</p>
<p>The usage of these directives is:</p>
-
<pre class="prettyprint lang-config">Require host <var>address</var>
+
<div class="example"><pre class="prettyprint lang-config">Require host <var>address</var>
Require ip <var>ip.address</var>
- </pre>
-
+</pre>
+</div>
<p>In the first form, <var>address</var> is a fully qualified
domain name (or a partial domain name); you may provide multiple
partial IP address, a network/netmask pair, or a network/nnn CIDR
specification. Either IPv4 or IPv6 addresses may be used.</p>
+<div class="example"><h3>Examples of IP address formats</h3><pre class="prettyprint lang-config"># Full IP address
+Require ip 10.2.3.4
+# Partial IP address (matches any host in the 172.20.0.0/16 range)
+Require ip 172.20
+# Network/netmask pair
+Require ip 192.168.1.0/255.255.255.0
+# Network/CIDR specification
+Require ip 192.168.1.0/24
+# IPv6 address
+Require ip 2001:db8::a00:20ff:fea7:ccea
+# IPv6 with CIDR
+Require ip 2001:db8:1::/48</pre>
+</div>
+
<p>See <a href="../mod/mod_authz_host.html#requiredirectives">the
mod_authz_host documentation</a> for further examples of this
syntax.</p>
<p>You can insert <code>not</code> to negate a particular requirement.
- Note, that since a <code>not</code> is a negation of a value, it cannot
+ Since a <code>not</code> is a negation of a value, it cannot
be used by itself to allow or deny a request, as <em>not true</em>
does not constitute <em>false</em>. Thus, to deny a visit using a negation,
the block must have one element that evaluates as true or false.
board, and you want to keep them out, you could do the
following:</p>
-
<pre class="prettyprint lang-config"><RequireAll>
- Require all granted
- Require not ip 10.252.46.165
+
<div class="example"><pre class="prettyprint lang-config"><RequireAll>
+Require all granted
+Require not ip 10.252.46.165
</RequireAll></pre>
-
+</div>
<p>Visitors coming from that address (<code>10.252.46.165</code>)
will not be able to see the content covered by this directive. If,
instead, you have a machine name, rather than an IP address, you
can use that.</p>
-
<pre class="prettyprint lang-config">Require not host <var>host.example.com</var>
- </pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Require not host <var>host.example.com</var>
+</pre>
+</div>
<p>And, if you'd like to block access from an entire domain,
- you can specify just part of an address or domain name:</p>
+ you can specify part of an address or domain name:</p>
-
<pre class="prettyprint lang-config">Require not ip 192.168.205
-Require not host phishers.example.com moreidiots.example
+
<div class="example"><pre class="prettyprint lang-config">Require not ip 192.168.205
+Require not host phishers.example.com badguys.example
Require not host gov</pre>
-
+</div>
<p>Use of the <code class="directive"><a href="../mod/mod_authz_core.html#requireall">RequireAll</a></code>, <code class="directive"><a href="../mod/mod_authz_core.html#requireany">RequireAny</a></code>, and <code class="directive"><a href="../mod/mod_authz_core.html#requirenone">RequireNone</a></code> directives may be
used to enforce more complex sets of requirements.</p>
based on user-agent (the browser type) you might do the
following:</p>
-
<pre class="prettyprint lang-config"><If "%{HTTP_USER_AGENT} == 'BadBot'">
- Require all denied
+
<div class="example"><pre class="prettyprint lang-config"><If "%{HTTP_USER_AGENT} == 'BadBot'">
+Require all denied
</If></pre>
-
+</div>
<p>Using the <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
<code>expr</code> syntax, this could also be written as:</p>
-
<pre class="prettyprint lang-config">Require expr %{HTTP_USER_AGENT} != 'BadBot'</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Require expr %{HTTP_USER_AGENT} != 'BadBot'</pre>
+</div>
<div class="note"><h3>Warning:</h3>
<p>Access control by <code>User-Agent</code> is an unreliable technique,
<p>For example, if you wish to block access to a resource between 8pm
and 7am, you can do this using <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
-
<pre class="prettyprint lang-config">RewriteEngine On
+
<div class="example"><pre class="prettyprint lang-config">RewriteEngine On
RewriteCond "%{TIME_HOUR}" ">=20" [OR]
RewriteCond "%{TIME_HOUR}" "<07"
RewriteRule "^/fridge" "-" [F]</pre>
-
+</div>
<p>This will return a 403 Forbidden response for any request after 8pm
or before 7am. This technique can be used for any criteria that you wish
<a href="../es/howto/access.html" hreflang="es" rel="alternate" title="Español"> es </a> |
<a href="../fr/howto/access.html" title="Français"> fr </a></p>
</div>
+<div class="outofdate">Cette traduction peut être périmée. Vérifiez la version
+ anglaise pour les changements récents.</div>
<p>Le contrôle d'accès fait référence à tout concept de contrôle
d'accès à une ressource quelconque. Il est distinct du processus d'<a href="auth.html">authentification et d'autorisation</a>.</p>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.es.xsl"?>
-<!-- English Revision: 1745189:1933720 (outdated) -->
+<!-- English Revision: 1745189:1935507 (outdated) -->
<!-- Updated by Luis Gil de Bernabé Pfeiffer lgilbernabe[AT]apache.org -->
<!-- Reviewed by Sergio Ramos -->
<!--
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- English Revision: 1933720 -->
+<!-- English Revision: 1933720:1935507 (outdated) -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
<variants>
<variant>en</variant>
<variant outdated="yes">es</variant>
- <variant>fr</variant>
+ <variant outdated="yes">fr</variant>
</variants>
</metafile>
an <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> directive like the
following:</p>
-
<pre class="prettyprint lang-config">AllowOverride AuthConfig</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">AllowOverride AuthConfig</pre>
+</div>
<p>Or, if you are just going to put the directives directly in
your main server configuration file, you will of course need to
placed in <code>httpd.conf</code> inside a <Directory
"/usr/local/apache/htdocs/secret"> section.</p>
-
<pre class="prettyprint lang-config">AuthType Basic
+
<div class="example"><pre class="prettyprint lang-config">AuthType Basic
AuthName "Restricted Files"
# (Following line optional)
AuthBasicProvider file
AuthUserFile "/usr/local/apache/passwd/passwords"
Require user rbowen</pre>
-
+</div>
<p>Let's examine each of those directives individually. The <code class="directive"><a href="../mod/mod_authn_core.html#authtype">AuthType</a></code> directive selects
the method that is used to authenticate the user. The most
<p>Now, you need to modify your <code>.htaccess</code> file to
look like the following:</p>
-
<pre class="prettyprint lang-config">AuthType Basic
+
<div class="example"><pre class="prettyprint lang-config">AuthType Basic
AuthName "By Invitation Only"
# Optional line:
AuthBasicProvider file
AuthUserFile "/usr/local/apache/passwd/passwords"
AuthGroupFile "/usr/local/apache/passwd/groups"
Require group GroupName</pre>
-
+</div>
<p>Now, anyone that is listed in the group <code>GroupName</code>,
and has an entry in the <code>password</code> file, will be let in, if
specific. Rather than creating a group file, you can just use
the following directive:</p>
-
<pre class="prettyprint lang-config">Require valid-user</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Require valid-user</pre>
+</div>
<p>Using that rather than the <code>Require user rbowen</code>
line will allow anyone in that is listed in the password file,
<p>To select a dbm file rather than a text file, for example:</p>
-
<pre class="prettyprint lang-config"><Directory "/www/docs/private">
- AuthName "Private"
- AuthType Basic
- AuthBasicProvider dbm
- AuthDBMUserFile "/www/passwords/passwd.dbm"
- Require valid-user
+
<div class="example"><pre class="prettyprint lang-config"><Directory "/www/docs/private">
+AuthName "Private"
+AuthType Basic
+AuthBasicProvider dbm
+AuthDBMUserFile "/www/passwords/passwd.dbm"
+Require valid-user
</Directory></pre>
-
+</div>
<p>Other options are available. Consult the
<code class="module"><a href="../mod/mod_authn_dbm.html">mod_authn_dbm</a></code> documentation for more details.</p>
scheme that meets your needs. In the following example, both the
file and LDAP based authentication providers are being used.</p>
-
<pre class="prettyprint lang-config"><Directory "/www/docs/private">
- AuthName "Private"
- AuthType Basic
- AuthBasicProvider file ldap
- AuthUserFile "/usr/local/apache/passwd/passwords"
- AuthLDAPURL ldap://ldaphost/o=yourorg
- Require valid-user
+
<div class="example"><pre class="prettyprint lang-config"><Directory "/www/docs/private">
+AuthName "Private"
+AuthType Basic
+AuthBasicProvider file ldap
+AuthUserFile "/usr/local/apache/passwd/passwords"
+AuthLDAPURL ldap://ldaphost/o=yourorg
+Require valid-user
</Directory></pre>
-
+</div>
<p>In this example the file provider will attempt to authenticate
the user first. If it is unable to authenticate the user, the LDAP
authorization methods can also be used. In this example both file group
authorization as well as LDAP group authorization is being used.</p>
-
<pre class="prettyprint lang-config"><Directory "/www/docs/private">
- AuthName "Private"
- AuthType Basic
- AuthBasicProvider file
- AuthUserFile "/usr/local/apache/passwd/passwords"
- AuthLDAPURL ldap://ldaphost/o=yourorg
- AuthGroupFile "/usr/local/apache/passwd/groups"
- Require group GroupName
- Require ldap-group cn=mygroup,o=yourorg
+
<div class="example"><pre class="prettyprint lang-config"><Directory "/www/docs/private">
+AuthName "Private"
+AuthType Basic
+AuthBasicProvider file
+AuthUserFile "/usr/local/apache/passwd/passwords"
+AuthLDAPURL ldap://ldaphost/o=yourorg
+AuthGroupFile "/usr/local/apache/passwd/groups"
+Require group GroupName
+Require ldap-group cn=mygroup,o=yourorg
</Directory></pre>
-
+</div>
<p>To take authorization a little further, authorization container
directives such as
<h3 id="reqaccessctrl">Using authorization providers for access control</h3>
<p>Authentication by username and password is only part of the
- story. Frequently you want to let people in based on something
- other than who they are. Something such as where they are
- coming from.</p>
-
- <p>The authorization providers <code>all</code>,
- <code>env</code>, <code>host</code> and <code>ip</code> let you
- allow or deny access based on other host based criteria such as
- host name or ip address of the machine requesting a
- document.</p>
-
- <p>The usage of these providers is specified through the
- <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive.
- This directive registers the authorization providers
- that will be called during the authorization stage of the request
- processing. For example:</p>
-
- <pre class="prettyprint lang-config">Require ip <var>address</var>
- </pre>
-
-
- <p>where <var>address</var> is an IP address (or a partial IP
- address) or:</p>
-
- <pre class="prettyprint lang-config">Require host <var>domain_name</var>
- </pre>
-
-
- <p>where <var>domain_name</var> is a fully qualified domain name
- (or a partial domain name); you may provide multiple addresses or
- domain names, if desired.</p>
-
- <p>For example, if you have someone spamming your message
- board, and you want to keep them out, you could do the
- following:</p>
-
- <pre class="prettyprint lang-config"><RequireAll>
- Require all granted
- Require not ip 10.252.46.165
-</RequireAll></pre>
-
-
- <p>Visitors coming from that address will not be able to see
- the content covered by this directive. If, instead, you have a
- machine name, rather than an IP address, you can use that.</p>
-
- <pre class="prettyprint lang-config"><RequireAll>
- Require all granted
- Require not host host.example.com
-</RequireAll></pre>
-
-
- <p>And, if you'd like to block access from an entire domain,
- you can specify just part of an address or domain name:</p>
-
- <pre class="prettyprint lang-config"><RequireAll>
- Require all granted
- Require not ip 192.168.205
- Require not host phishers.example.com moreidiots.example
- Require not host ke
-</RequireAll></pre>
-
-
- <p>Using <code class="directive"><a href="../mod/mod_authz_core.html#requireall"><RequireAll></a></code>
- with multiple <code class="directive"><a href="../mod/mod_authz_core.html#require"><Require></a></code> directives, each negated with <code>not</code>,
- will only allow access, if all of negated conditions are true. In other words,
- access will be blocked, if any of the negated conditions fails.</p>
+ story. You can also allow or deny access based on other
+ criteria, such as the client's IP address or hostname, using
+ the authorization providers <code>all</code>, <code>env</code>,
+ <code>host</code>, and <code>ip</code> with the
+ <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
+ directive.</p>
+ <p>For full details and examples, see the
+ <a href="access.html">Access Control</a> howto.</p>
<h3 id="filesystem">Access Control backwards compatibility</h3>
<h2 id="socache">Authentication Caching <a title="Permanent link" href="#socache" class="permalink">¶</a></h2>
<p>There may be times when authentication puts an unacceptable load
on a provider or on your network. This is most likely to affect users
- of <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code> (or third-party/custom providers).
- To deal with this, HTTPD 2.3/2.4 introduces a new caching provider
- <code class="module"><a href="../mod/mod_authn_socache.html">mod_authn_socache</a></code> to cache credentials and reduce
+ of <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code> (or third-party/custom providers). The
+ <code class="module"><a href="../mod/mod_authn_socache.html">mod_authn_socache</a></code> module caches credentials and reduces
the load on the origin provider(s).</p>
<p>This may offer a substantial performance boost to some users.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<a href="../ko/howto/auth.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
<a href="../tr/howto/auth.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
</div>
+<div class="outofdate">Cette traduction peut être périmée. Vérifiez la version
+ anglaise pour les changements récents.</div>
<p>L'authentification est un processus qui vous permet de vérifier
qu'une personne est bien celle qu'elle prétend être. L'autorisation
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.es.xsl"?>
-<!-- English Revision: 1766314:1933687 (outdated) -->
+<!-- English Revision: 1766314:1935509 (outdated) -->
<!-- Translated by: Luis Gil de Bernabé Pfeiffer lgilbernabe [AT] apache.org-->
<!-- Reviewed by: Sergio Ramos -->
<!--
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1933687 -->
+<!-- English Revision: 1933687:1935509 (outdated) -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviwed by : Vincent Deffontaines -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 479777:1933687 (outdated) -->
+<!-- English Revision: 479777:1935509 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version='1.0' encoding='EUC-KR' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ko.xsl"?>
-<!-- English Revision: 105989:1933687 (outdated) -->
+<!-- English Revision: 105989:1935509 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<variants>
<variant>en</variant>
<variant outdated="yes">es</variant>
- <variant>fr</variant>
+ <variant outdated="yes">fr</variant>
<variant outdated="yes">ja</variant>
<variant outdated="yes">ko</variant>
<variant outdated="yes">tr</variant>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 1070891:1933687 (outdated) -->
+<!-- English Revision: 1070891:1935509 (outdated) -->
<!-- =====================================================
Translated by: Umut Samuk <umut belgeler.org>
Reviewed by: Nilgün Belma Bugüner <nilgun belgeler.org>
<h2 id="configuring">Configuring httpd to permit CGI <a title="Permanent link" href="#configuring" class="permalink">¶</a></h2>
- <p>In order to get your CGI programs to work properly, you'll
- need to have httpd configured to permit CGI execution. There
- are several ways to do this.</p>
-
- <div class="warning">Note: If httpd has been built with shared module
- support you need to ensure that the module is loaded; in your
+ <p>Your httpd configuration must permit CGI execution before
+ CGI programs will work. Several ways to do this are described
+ below.</p>
+
+ <p>CGI support is provided by two modules:
+ <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code> and <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>.
+ <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code> uses a dedicated external daemon to manage
+ CGI processes and is required when httpd runs a threaded MPM (such as
+ <code class="module"><a href="../mod/event.html">event</a></code> or <code class="module"><a href="../mod/worker.html">worker</a></code>).
+ <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> runs CGI programs directly from within the
+ server process and is used with non-threaded MPMs like
+ <code class="module"><a href="../mod/prefork.html">prefork</a></code>, or on Windows. From a configuration
+ standpoint they are interchangeable — the directives are the same.
+ See the <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> and <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code>
+ reference pages for implementation details.</p>
+
+ <div class="warning">If httpd has been built with shared module
+ support, you need to ensure that the appropriate module is loaded. In your
<code>httpd.conf</code> you need to make sure the
<code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code>
- directive has not been commented out. A correctly configured directive
- may look like this:
-
- <pre class="prettyprint lang-config">LoadModule cgid_module modules/mod_cgid.so</pre>
-
+ directive has not been commented out. For a threaded MPM:
+<div class="example"><pre class="prettyprint lang-config">LoadModule cgid_module modules/mod_cgid.so</pre>
+</div>
- On Windows, or using a non-threaded MPM like prefork, A correctly
- configured directive may look like this:
+ For Windows, or a non-threaded MPM like prefork:
- <pre class="prettyprint lang-config">LoadModule cgi_module modules/mod_cgi.so</pre>
+<div class="example"><pre class="prettyprint lang-config">LoadModule cgi_module modules/mod_cgi.so</pre>
+</div>
</div>
<p>The <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
directive looks like:</p>
-
<pre class="prettyprint lang-config">ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"</pre>
+</div>
<p>The example shown is from your default <code>httpd.conf</code>
configuration file, if you installed httpd in the default
treated as a CGI program.</p>
<p>For example, if the URL
- <code>http://www.example.com/cgi-bin/test.pl</code>
+ <code>http://www.example.com/cgi-bin/test.py</code>
is requested, httpd will attempt to execute the file
- <code>/usr/local/apache2/cgi-bin/test.pl</code>
- and return the output. Of course, the file will have to
- exist, and be executable, and return output in a particular
- way, or httpd will return an error message.</p>
+ <code>/usr/local/apache2/cgi-bin/test.py</code>
+ and return the output. The file must exist, be executable,
+ and produce output in the expected format; otherwise httpd
+ returns an error.</p>
<h3 id="nonscriptalias">CGI outside of ScriptAlias directories</h3>
the main <code>cgi-bin</code> directory, they will need to be able to
run CGI programs elsewhere.</p>
- <p>There are two steps to allowing CGI execution in an arbitrary
- directory. First, the <code>cgi-script</code> handler must be
+ <p>Allowing CGI execution in an arbitrary directory requires
+ two steps. First, the <code>cgi-script</code> handler must be
activated using the <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> or <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> directive. Second,
<code>ExecCGI</code> must be specified in the <code class="directive"><a href="../mod/core.html#options">Options</a></code> directive.</p>
file, to specify that CGI execution was permitted in a particular
directory:</p>
-
<pre class="prettyprint lang-config"><Directory "/usr/local/apache2/htdocs/somedir">
- Options +ExecCGI
+
<div class="example"><pre class="prettyprint lang-config"><Directory "/usr/local/apache2/htdocs/somedir">
+Options +ExecCGI
</Directory></pre>
-
+</div>
<p>The above directive tells httpd to permit the execution
of CGI files. You will also need to tell the server what
files are CGI files. The following <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> directive tells the server to treat all
- files with the <code>cgi</code> or <code>pl</code> extension as CGI
+ files with the <code>cgi</code> or <code>py</code> extension as CGI
programs:</p>
- <pre class="prettyprint lang-config">AddHandler cgi-script .cgi .pl</pre>
-
+<div class="example"><pre class="prettyprint lang-config">AddHandler cgi-script .cgi .py</pre>
+</div>
<h3 id="htaccess">.htaccess files</h3>
<code>.cgi</code> in users' directories, you can use the
following configuration.</p>
-
<pre class="prettyprint lang-config"><Directory "/home/*/public_html">
- Options +ExecCGI
- AddHandler cgi-script .cgi
+
<div class="example"><pre class="prettyprint lang-config"><Directory "/home/*/public_html">
+Options +ExecCGI
+AddHandler cgi-script .cgi
</Directory></pre>
+</div>
-
- <p>If you wish designate a <code>cgi-bin</code> subdirectory of
+ <p>To designate a <code>cgi-bin</code> subdirectory of
a user's directory where everything will be treated as a CGI
program, you can use the following.</p>
-
<pre class="prettyprint lang-config"><Directory "/home/*/public_html/cgi-bin">
- Options ExecCGI
- SetHandler cgi-script
+
<div class="example"><pre class="prettyprint lang-config"><Directory "/home/*/public_html/cgi-bin">
+Options ExecCGI
+SetHandler cgi-script
</Directory></pre>
-
+</div>
<h2 id="writing">Writing a CGI program <a title="Permanent link" href="#writing" class="permalink">¶</a></h2>
- <p>There are two main differences between ``regular''
- programming, and CGI programming.</p>
+ <p>CGI programming differs from regular programming in two
+ ways.</p>
<p>First, all output from your CGI program must be preceded by
a <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> header. This is HTTP header that tells the client
<p>Secondly, your output needs to be in HTML, or some other
format that a browser will be able to display. Most of the
time, this will be HTML, but occasionally you might write a CGI
- program that outputs a gif image, or other non-HTML
+ program that outputs a GIF image, or other non-HTML
content.</p>
<p>Apart from those two things, writing a CGI program will look
<p>The following is an example CGI program that prints one
line to your browser. Type in the following, save it to a
- file called <code>first.pl</code>, and put it in your
+ file called <code>first.py</code>, and put it in your
<code>cgi-bin</code> directory.</p>
- <pre class="prettyprint lang-perl">#!/usr/bin/perl
-print "Content-type: text/html\n\n";
-print "Hello, World.";</pre>
-
+<div class="example"><pre class="prettyprint lang-python">#!/usr/bin/env python3
+print("Content-type: text/html\n")
+print("Hello, World.")</pre>
+</div>
- <p>Even if you are not familiar with Perl, you should be able
- to see what is happening here. The first line tells httpd
- (or whatever shell you happen to be running under) that this
- program can be executed by feeding the file to the
- interpreter found at the location <code>/usr/bin/perl</code>.
- The second line prints the content-type declaration we
- talked about, followed by two carriage-return newline pairs.
- This puts a blank line after the header, to indicate the end
- of the HTTP headers, and the beginning of the body. The third
- line prints the string "Hello, World.". And that's the end
- of it.</p>
+ <p>The first line tells the operating system which interpreter
+ to use. The first <code>print</code> call outputs the
+ content-type header followed by a blank line (the
+ <code>\n</code> in the string plus the newline that
+ <code>print()</code> adds), which marks the end of HTTP
+ headers. The second <code>print</code> call outputs the body.
+ That is all a CGI program needs to produce a response.</p>
<p>If you open your favorite browser and tell it to get the
address</p>
<div class="example"><p><code>
- http://www.example.com/cgi-bin/first.pl
+ http://www.example.com/cgi-bin/first.py
</code></p></div>
<p>or wherever you put your file, you will see the one line
<code>Hello, World.</code> appear in your browser window.
It's not very exciting, but once you get that working, you'll
- have a good chance of getting just about anything working.</p>
+ have a good chance of getting about anything working.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="troubleshoot">But it's still not working! <a title="Permanent link" href="#troubleshoot" class="permalink">¶</a></h2>
- <p>There are four basic things that you may see in your browser
- when you try to access your CGI program from the web:</p>
+ <p>Four basic things may appear in your browser when you try to
+ access your CGI program from the web:</p>
<dl>
<dt>The output of your CGI program</dt>
a file sufficient permissions to be executed by <code>nobody</code>
is to give everyone execute permission on the file:</p>
- <div class="example"><p><code>
- chmod a+x first.pl
- </code></p></div>
+<div class="example"><pre class="prettyprint lang-bash">chmod a+x first.py</pre>
+</div>
<p>Also, if your program reads from, or writes to, any other
files, those files will need to have the correct permissions
program.</p>
<p>A common manifestation of this is the path to the script
- interpreter (often <code>perl</code>) indicated in the first
+ interpreter (often <code>python3</code>) indicated in the first
line of your CGI program, which will look something like:</p>
- <pre class="prettyprint lang-perl">#!/usr/bin/perl</pre>
-
+<div class="example"><pre class="prettyprint lang-python">#!/usr/bin/env python3</pre>
+</div>
<p>Make sure that this is in fact the path to the
interpreter.</p>
<div class="example"><p><code>
cd /usr/local/apache2/cgi-bin<br>
- ./first.pl
+ ./first.py
</code></p></div>
- <p>(Do not call the <code>perl</code> interpreter. The shell
+ <p>(Do not call the <code>python3</code> interpreter directly. The shell
and httpd should find the interpreter using the <a href="#pathinformation">path information</a> on the first line of
the script.)</p>
suexec will be activated.</p>
<p>Unless you fully understand suexec, you should not be using it.
- To disable suexec,
simply remove (or rename) the <code class="program"><a href="../programs/suexec.html">suexec</a></code>
+ To disable suexec, remove (or rename) the <code class="program"><a href="../programs/suexec.html">suexec</a></code>
binary pointed to by <code>SUEXEC_BIN</code> and then restart the
server. If, after reading about <a href="../suexec.html">suexec</a>,
you still wish to use it, then run <code>suexec -V</code> to find
<p>During the CGI transaction, the server and the browser
also set environment variables, so that they can communicate
with one another. These are things like the browser type
- (Chrome, Firefox, Lynx), the server type (Apache httpd, Nginx, IIS),
+ (Chrome, Firefox, Lynx), the server type (httpd, Nginx, IIS),
the name of the CGI program that is being run, and so on.</p>
<p>These variables are available to the CGI programmer, and
complete list of required variables is at
Common Gateway Interface RFC (<a href="https://www.rfc-editor.org/rfc/rfc3875">RFC 3875</a>).</p>
- <p>This simple Perl CGI program will display all of the
+ <p>This simple Python CGI program will display all of the
environment variables that are being passed around. Two
similar programs are included in the
<code>cgi-bin</code>
<a href="../env.html">add your own environment variables</a>
to the basic ones provided by default.</p>
- <pre class="prettyprint lang-perl">#!/usr/bin/perl
-use strict;
-use warnings;
-
-print "Content-type: text/html\n\n";
-foreach my $key (keys %ENV) {
- print "$key --> $ENV{$key}<br>";
-}</pre>
+<div class="example"><pre class="prettyprint lang-python">#!/usr/bin/env python3
+import os
+print("Content-type: text/html\n")
+for key, value in os.environ.items():
+print(f"{key} --> {value}<br>")</pre>
+</div>
<h3 id="stdin">STDIN and STDOUT</h3>
<code>METHOD</code> attribute in the <code>FORM</code> tag.</p>
<p>Your program is then responsible for splitting that string
- up into useful information. Fortunately, there are libraries
- and modules available to help you process this data, as well
- as handle other of the aspects of your CGI program.</p>
+ up into useful information. Fortunately, libraries
+ and modules are available to help you process this data, as well
+ as handle other aspects of your CGI program.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
code library, or module, to do most of the grunt work for you.
This leads to fewer errors, and faster development.</p>
- <p>If you're writing CGI programs in Perl, modules are
- available on <a href="http://www.cpan.org/">CPAN</a>. The most
- popular module for this purpose is <code>CGI.pm</code>. You might
- also consider <code>CGI::Lite</code>, which implements a minimal
- set of functionality, which is all you need in most programs.</p>
+ <p>If you're writing CGI programs in Python, the standard
+ library's <code>cgi</code> module (deprecated in Python 3.11,
+ removed in 3.13) handled form parsing. For current Python
+ versions, use the <code>urllib.parse</code> module to parse
+ query strings and form data. For more complex applications,
+ consider a lightweight WSGI framework, though that moves
+ beyond the scope of traditional CGI.</p>
- <p>If you're writing CGI programs in C, there are a variety of
- options. One of these is the <code>CGIC</code> library, from
- <a href="https://web.mit.edu/wwwdev/www/cgic.html">https://web.mit.edu/wwwdev/www/cgic.html</a>.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="moreinfo">For more information <a title="Permanent link" href="#moreinfo" class="permalink">¶</a></h2>
program was in, and, if possible, the offending code. This will
make finding your problem much simpler.</p>
- <p>Note that questions about CGI problems should <strong>never</strong>
+ <div class="note">Questions about CGI problems should <strong>never</strong>
be posted to the httpd bug database unless you are sure you
- have found a problem in the httpd source code.</p>
+ have found a problem in the httpd source code.</div>
</div></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/howto/cgi.html" title="English"> en </a> |
<a href="../ja/howto/cgi.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
<a href="../ko/howto/cgi.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
</div>
+<div class="outofdate">Cette traduction peut être périmée. Vérifiez la version
+ anglaise pour les changements récents.</div>
</div>
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif"> <a href="#intro">Introduction</a></li>
<li><img alt="" src="../images/down.gif"> <a href="#configuring">Configurer httpd pour autoriser CGI</a></li>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.es.xsl"?>
-<!-- English Revision: 1773244:1933506 (outdated) -->
+<!-- English Revision: 1773244:1935512 (outdated) -->
<!-- Spanish translation : Daniel Ferradal -->
<!-- Reviewed by Luis Gil de Bernabé Pfeiffer lgilbernabe[AT]apache.org -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1933506 -->
+<!-- English Revision: 1933506:1935512 (outdated) -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 545841:1933506 (outdated) -->
+<!-- English Revision: 545841:1935512 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version='1.0' encoding='EUC-KR' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ko.xsl"?>
-<!-- English Revision: 105989:1933506 (outdated) -->
+<!-- English Revision: 105989:1935512 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<variants>
<variant>en</variant>
<variant outdated="yes">es</variant>
- <variant>fr</variant>
+ <variant outdated="yes">fr</variant>
<variant outdated="yes">ja</variant>
<variant outdated="yes">ko</variant>
</variants>
if you would rather call the file <code>.config</code> then you
can put the following in your server configuration file:</p>
-
<pre class="prettyprint lang-config">AccessFileName ".config"</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">AccessFileName ".config"</pre>
+</div>
</div>
<p>Directives in <code>.htaccess</code> files use the same syntax as
<code>.htaccess</code> file, while <code class="directive"><a href="../mod/core.html#allowoverridelist">AllowOverrideList</a></code> names individual
directives to permit (see <a href="#when">below</a>). If a directive
is permitted, the documentation for that directive will contain an Override section,
- specifying what value must be in <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> in order for that
+ specifying what value must be in <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> for that
directive to be permitted.</p>
<div class="note">The default value of <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> is <code>None</code>.
directive, you will find that it is permitted in <code>.htaccess</code>
files. (See the Context line in the directive summary.) The <a href="../mod/directive-dict.html#Context">Override</a> line reads
<code>FileInfo</code>. Thus, you must have at least
- <code>AllowOverride FileInfo</code> in order for this directive to be
+ <code>AllowOverride FileInfo</code> for this directive to be
honored in <code>.htaccess</code> files.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<code>.htaccess</code> file is loaded every time a document is
requested.</p>
- <p>Further note that httpd must look for <code>.htaccess</code> files
- in all higher-level directories, in order to have a full complement of
- directives
that it must apply. (See section on <a href="#how">how
+ <p>Additionally, httpd must look for <code>.htaccess</code> files
+ in all higher-level directories to assemble the full set of applicable
+ directives. (See section on <a href="#how">how
directives are applied</a>.) Thus, if a file is requested out of a
directory <code>/www/htdocs/example</code>, httpd must look for the
following files:</p>
-
<pre class="prettyprint lang-config">/.htaccess
+
<div class="example"><pre class="prettyprint lang-config">/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/example/.htaccess</pre>
-
+</div>
<p>And so, for each file access out of that directory, there are 4
additional file-system accesses, even if none of those files are
- present. (Note that this would only be the case if
+ present. (This would only be the case if
<code>.htaccess</code> files were enabled for <code>/</code>, which
is not usually the case.)</p>
<p><strong>Security:</strong> You are permitting
users to modify server configuration, which may result in changes over
which you have no control. Carefully consider whether you want to give
- your users this privilege. Note also that giving users less
+ your users this privilege. Giving users less
privileges than they need will lead to additional technical support
requests. Make sure you clearly tell your users what level of
privileges you have given them. Specifying exactly what you have set
<code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> to, and pointing them
- to the relevant documentation, will save yourself a lot of confusion
+ to the relevant documentation, prevents confusion
later.</p>
<p>If you need to grant <code>.htaccess</code> access but want to
lets you name individual directives that are permitted, providing
finer-grained control than <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> alone:</p>
-
<pre class="prettyprint lang-config"># Allow only specific directives, not entire categories
+
<div class="example"><pre class="prettyprint lang-config"># Allow only specific directives, not entire categories
AllowOverride None
AllowOverrideList Redirect RedirectMatch RewriteEngine RewriteRule RewriteCond</pre>
-
+</div>
<p>With this configuration, any directive not explicitly listed will
cause a server error if encountered in a <code>.htaccess</code> file.
This is a useful middle ground between full override access and no
override access.</p>
- <p>Note that it is completely equivalent to put a <code>.htaccess</code>
- file in a directory <code>/www/htdocs/example</code> containing a
- directive, and to put that same directive in a Directory section
- <code><Directory "/www/htdocs/example"></code> in your main server
+ <p>Placing a directive in a <code>.htaccess</code>
+ file in a directory <code>/www/htdocs/example</code> is completely equivalent to placing that same directive in a
+ <code><Directory "/www/htdocs/example"></code> section in your main server
configuration:</p>
<p><code>.htaccess</code> file in <code>/www/htdocs/example</code>:</p>
<div class="example"><h3>Contents of .htaccess file in
- <code>/www/htdocs/example</code></h3><pre class="prettyprint lang-config">AddType text/example ".exm"</pre>
-</div>
+ <code>/www/htdocs/example</code></h3><div class="example"><pre class="prettyprint lang-config">AddType text/example ".exm"</pre>
+</div></div>
<div class="example"><h3>Section from your <code>httpd.conf</code>
- file</h3><pre class="prettyprint lang-config"><Directory "/www/htdocs/example">
- AddType text/example ".exm"
+ file</h3><div class="example"><pre class="prettyprint lang-config"><Directory "/www/htdocs/example">
+AddType text/example ".exm"
</Directory></pre>
-</div>
+</div></div>
<p>The use of <code>.htaccess</code> files can be disabled completely
by setting the <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code>
directive to <code>none</code>:</p>
-
<pre class="prettyprint lang-config">AllowOverride None</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">AllowOverride None</pre>
+</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="how">How directives are applied <a title="Permanent link" href="#how" class="permalink">¶</a></h2>
<p>The configuration directives found in a <code>.htaccess</code> file
are applied to the directory in which the <code>.htaccess</code> file
- is found, and to all subdirectories thereof. However, it is important
- to also remember that there may have been <code>.htaccess</code> files
+ is found, and to all subdirectories thereof. Remember that there may have been <code>.htaccess</code> files
in directories higher up. Directives are applied in the order that they
are found. Therefore, a <code>.htaccess</code> file in a particular
directory may override directives found in <code>.htaccess</code> files
<p>In the directory <code>/www/htdocs/example1</code> we have a
<code>.htaccess</code> file containing the following:</p>
-
<pre class="prettyprint lang-config">Options +ExecCGI</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Options +ExecCGI</pre>
+</div>
- <p>(Note: you must have "<code>AllowOverride Options</code>" in effect
+ <div class="note">You must have "<code>AllowOverride Options</code>" in effect
to permit the use of the "<code class="directive"><a href="../mod/core.html#options">Options</a></code>" directive in
- <code>.htaccess</code> files.)</p>
+ <code>.htaccess</code> files.</div>
<p>In the directory <code>/www/htdocs/example1/example2</code> we have
a <code>.htaccess</code> file containing:</p>
-
<pre class="prettyprint lang-config">Options Includes</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Options Includes</pre>
+</div>
<p>Because of this second <code>.htaccess</code> file, in the directory
<code>/www/htdocs/example1/example2</code>, CGI execution is not
prevent script execution while allowing anything else to be set in
<code>.htaccess</code> you can use:</p>
-
<pre class="prettyprint lang-config"><Directory "/www/htdocs">
- AllowOverride All
+
<div class="example"><pre class="prettyprint lang-config"><Directory "/www/htdocs">
+AllowOverride All
</Directory>
<Location "/">
- Options +IncludesNoExec -ExecCGI
+Options +IncludesNoExec -ExecCGI
</Location></pre>
-
+</div>
<div class="note">This example assumes that your <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> is <code>/www/htdocs</code>.</div>
<p><code>.htaccess</code> file contents:</p>
-
<pre class="prettyprint lang-config">AuthType Basic
+
<div class="example"><pre class="prettyprint lang-config">AuthType Basic
AuthName "Password Required"
AuthUserFile "/www/passwords/password.file"
AuthGroupFile "/www/passwords/group.file"
Require group admins</pre>
+</div>
-
- <p>Note that <code>AllowOverride AuthConfig</code> must be in effect
- for these directives to have any effect.</p>
+ <div class="note"><code>AllowOverride AuthConfig</code> must be in effect
+ for these directives to have any effect.</div>
<p>Please see the <a href="auth.html">authentication tutorial</a> for a
more complete discussion of authentication and authorization.</p>
configuration directives, placed in a <code>.htaccess</code> file in
the desired directory:</p>
-
<pre class="prettyprint lang-config">Options +Includes
+
<div class="example"><pre class="prettyprint lang-config">Options +Includes
AddType text/html "shtml"
AddHandler server-parsed shtml</pre>
+</div>
-
- <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
+ <div class="note"><code>AllowOverride Options</code> and <code>AllowOverride
FileInfo</code> must both be in effect for these directives to have any
- effect.</p>
+ effect.</div>
<p>Please see the <a href="ssi.html">SSI tutorial</a> for a more
complete discussion of server-side includes.</p>
the current directory, rather than being the original requested URI.
Consider the following examples:</p>
-<pre class="prettyprint lang-config"># In httpd.conf
+<div class="example"><pre class="prettyprint lang-config"># In httpd.conf
RewriteRule "^/images/(.+)\.jpg" "/images/$1.png"
# In .htaccess in root dir
# In .htaccess in images/
RewriteRule "^(.+)\.jpg" "$1.png"</pre>
-
+</div>
<p>In a <code>.htaccess</code> in your document directory, the leading
slash is removed from the value supplied to <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>, and in the
it. Thus, your regular expression needs to omit that portion as
well.</p>
-<p>Also note that in <code>.htaccess</code> context, regular expressions are
+<p>In <code>.htaccess</code> context, regular expressions are
recompiled on every request, whereas in the main server configuration they
are compiled once and cached.</p>
execution of CGI programs in a particular directory. This may be
implemented with the following configuration:</p>
-
<pre class="prettyprint lang-config">Options +ExecCGI
+
<div class="example"><pre class="prettyprint lang-config">Options +ExecCGI
AddHandler cgi-script "cgi" "py"</pre>
-
+</div>
<p>Alternately, if you wish to have all files in the given directory be
considered to be CGI programs, this may be done with the following
configuration:</p>
-
<pre class="prettyprint lang-config">Options +ExecCGI
+
<div class="example"><pre class="prettyprint lang-config">Options +ExecCGI
SetHandler cgi-script</pre>
+</div>
-
- <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
+ <div class="note"><code>AllowOverride Options</code> and <code>AllowOverride
FileInfo</code> must both be in effect for these directives to have any
- effect.</p>
+ effect.</div>
<p>Please see the <a href="cgi.html">CGI tutorial</a> for a more
complete discussion of CGI programming and configuration.</p>
nonsense word in your <code>.htaccess</code> file and reload the
page:</p>
-
<pre class="prettyprint lang-config">TestMe</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">TestMe</pre>
+</div>
<p>If a server error (HTTP 500) is
not generated, then you almost certainly have <code>AllowOverride
that the directive used in your <code>.htaccess</code> file is not
permitted.</p>
- <pre class="prettyprint lang-config">[Tue May 06 09:12:31.528374 2025] [core:alert] [pid 12345] [client 192.168.1.50:54321] /var/www/html/.htaccess: DirectoryIndex not allowed here</pre>
-
+<div class="example"><pre class="prettyprint lang-sh">[Thu Jun 18 09:12:31.528374 2026] [core:alert] [pid 12345] [client 192.168.1.50:54321] /var/www/html/.htaccess: DirectoryIndex not allowed here</pre>
+</div>
<p>This will indicate either that you've used a directive that is
- never permitted in <code>.htaccess</code> files, or that you simply
- don't have <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> set to
+ never permitted in <code>.htaccess</code> files, or that you don't have <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> set to
a level sufficient for the directive you've used. Consult the
documentation for that particular directive to determine which is
the case.</p>
<p>Alternately, it may tell you that you had a syntax error in your
usage of the directive itself.</p>
- <pre class="prettyprint lang-config">[Tue May 06 09:14:02.946218 2025] [core:alert] [pid 12345] [client 192.168.1.50:54321] /var/www/html/.htaccess: RewriteCond: bad flag delimiters</pre>
-
+<div class="example"><pre class="prettyprint lang-sh">[Thu Jun 18 09:14:02.946218 2026] [core:alert] [pid 12345] [client 192.168.1.50:54321] /var/www/html/.htaccess: RewriteCond: bad flag delimiters</pre>
+</div>
<p>In this case, the error message should be specific to the
particular syntax error that you have committed.</p>
<a href="../ko/howto/htaccess.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
<a href="../pt-br/howto/htaccess.html" hreflang="pt-br" rel="alternate" title="Português (Brasil)"> pt-br </a></p>
</div>
+<div class="outofdate">Cette traduction peut être périmée. Vérifiez la version
+ anglaise pour les changements récents.</div>
<p>Les fichiers <code>.htaccess</code> fournissent une méthode pour
modifier la configuration du serveur au niveau de chaque répertoire, sans
<a href="../ko/howto/htaccess.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
<a href="../pt-br/howto/htaccess.html" title="Português (Brasil)"> pt-br </a></p>
</div>
+<div class="outofdate">Esta tradução pode estar desatualizada.
+ Verifique a versão em inglês para alterações recentes.</div>
<p>Arquivos <code>.htaccess</code> oferecem um meio de fazer alterações
nas configurações por diretório, sem modificar diretamente os arquivos
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.es.xsl"?>
-<!-- English Revision: 1741842:1934247 (outdated) -->
+<!-- English Revision: 1741842:1935518 (outdated) -->
<!-- Spanish translation : Daniel Ferradal -->
<!-- Reviewed by Luis Joaquin Gil de Bernabé Pfeiffer -->
<!--
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1934247 -->
+<!-- English Revision: 1934247:1935518 (outdated) -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 574882:1934247 (outdated) -->
+<!-- English Revision: 574882:1935518 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version='1.0' encoding='EUC-KR' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ko.xsl"?>
-<!-- English Revision: 151408:1934247 (outdated) -->
+<!-- English Revision: 151408:1935518 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<variants>
<variant>en</variant>
<variant outdated="yes">es</variant>
- <variant>fr</variant>
+ <variant outdated="yes">fr</variant>
<variant outdated="yes">ja</variant>
<variant outdated="yes">ko</variant>
- <variant>pt-br</variant>
+ <variant outdated="yes">pt-br</variant>
</variants>
</metafile>
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.pt-br.xsl"?>
-<!-- English Revision: 1934247 -->
+<!-- English Revision: 1934247:1935518 (outdated) -->
<!-- Portuguese(BR) translation: leonardolara --><!-- Reviewed by: leonardolara -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<p>This is the howto guide for the HTTP/2 implementation in Apache httpd. This
feature is <em>production-ready</em> and you may expect interfaces and directives to
- remain consistent releases.
+ remain consistent across releases.
</p>
</div>
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif"> <a href="#protocol">The HTTP/2 protocol</a></li>
<p>HTTP/2 is the evolution of the world's most successful application layer protocol, HTTP.
It focuses on making more efficient use of network resources. It does not change the fundamentals
- of HTTP, the semantics. There are still request and responses and headers and all that. So, if
+ of HTTP, the semantics. There are still requests and responses and headers and all that. So, if
you already know HTTP/1, you know 95% about HTTP/2 as well.</p>
- <p>There has been a lot written about HTTP/2 and how it works. The most normative is, of course,
- its <a href="https://www.rfc-editor.org/rfc/rfc7540">RFC 7540</a>
- (also available in more readable formatting, YMMV (<a href="https://www.rfc-editor.org/rfc/rfc7540">RFC 7540</a>)).
- So, there you'll find the nuts and bolts.</p>
- <p>But, as RFC do, it's not really a good thing to read first. It's better to first understand
- <em>what</em> a thing wants to do and then read the RFC about <em>how</em> it is done. A much
- better document to start with is <a href="https://daniel.haxx.se/http2/">http2 explained</a>
- by Daniel Stenberg, the author of <a href="https://curl.haxx.se">curl</a>. It is available in
- an ever growing list of languages, too!</p>
- <p>Too Long, Didn't read: there are some new terms and gotchas that need to be kept in mind while reading this document:</p>
+
+ <p>The protocol is defined in <a href="https://www.rfc-editor.org/rfc/rfc9113">RFC 9113</a> (which obsoletes the original
+ <a href="https://www.rfc-editor.org/rfc/rfc7540">RFC 7540</a>). For a more approachable introduction, see
+ <a href="https://daniel.haxx.se/http2/">http2 explained</a> by Daniel Stenberg,
+ the author of <a href="https://curl.haxx.se">curl</a>. It covers the motivation
+ and design of HTTP/2 without requiring you to parse RFC notation first.</p>
+
+ <p>In short: there are some new terms and gotchas that need to be kept in
+ mind while reading this document:</p>
+
<ul>
- <li>HTTP/2 is a <strong>binary protocol</strong>, as opposed to HTTP 1.1 that is plain text. The latter is meant to be human readable (for example sniffing network traffic) meanwhile the former is not. More info in the official FAQ <a href="https://http2.github.io/faq/#why-is-http2-binary">question</a>.</li>
+ <li>HTTP/2 is a <strong>binary protocol</strong>, as opposed to HTTP 1.1
+ that is plain text. The latter is meant to be human readable (for example
+ sniffing network traffic) while the former is not. More info in the official
+ FAQ <a href="https://http2.github.io/faq/#why-is-http2-binary">question</a>.</li>
<li><strong>h2</strong> is HTTP/2 over TLS (protocol negotiation via ALPN).</li>
- <li><strong>h2c</strong> is HTTP/2 over TCP.</li>
- <li>A <strong>frame</strong> is the smallest unit of communication within an HTTP/2 connection, consisting of a header and a variable-length sequence of octets structured according to the frame type. More info in the official documentation <a href="https://www.rfc-editor.org/rfc/rfc7540">RFC 7540</a>.</li>
- <li>A <strong>stream</strong> is a bidirectional flow of frames within the HTTP/2 connection. The correspondent concept in HTTP 1.1 is a request/response message exchange. More info in the official documentation <a href="https://www.rfc-editor.org/rfc/rfc7540">RFC 7540</a>.</li>
- <li>HTTP/2 is able to run <strong>multiple streams</strong> of data over the same TCP connection, avoiding the classic HTTP 1.1 head of blocking slow request and avoiding to re-instantiate TCP connections for each request/response (KeepAlive patched the problem in HTTP 1.1 but did not fully solve it).</li>
+ <li><strong>h2c</strong> is HTTP/2 over cleartext TCP (without TLS). Note that
+ h2c has been removed from the current specification but httpd still supports it.</li>
+ <li>A <strong>frame</strong> is the smallest unit of communication within
+ an HTTP/2 connection, consisting of a header and a variable-length sequence
+ of octets structured according to the frame type. More info in the official
+ documentation <a href="https://www.rfc-editor.org/rfc/rfc9113">RFC 9113</a>.</li>
+ <li>A <strong>stream</strong> is a bidirectional flow of frames within the
+ HTTP/2 connection. The corresponding concept in HTTP 1.1 is a request/response
+ message exchange. More info in the official documentation
+ <a href="https://www.rfc-editor.org/rfc/rfc9113">RFC 9113</a>.</li>
+ <li>HTTP/2 is able to run <strong>multiple streams</strong> of data over
+ the same TCP connection, avoiding the classic HTTP 1.1 head-of-line blocking
+ of slow requests and avoiding the need to re-instantiate TCP connections
+ for each request/response (KeepAlive patched the problem in HTTP 1.1 but
+ did not fully solve it).</li>
</ul>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<p>The HTTP/2 protocol is implemented by its own httpd module, aptly named
<code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code>. It implements the complete set
- of features described by RFC 7540 and supports HTTP/2 over cleartext (http:), as
+ of features described by RFC 9113 and supports HTTP/2 over cleartext (http:), as
well as secure (https:) connections. The cleartext variant is named '<code>h2c</code>',
the secure one '<code>h2</code>'. For <code>h2c</code> it allows the <em>direct</em>
mode and the <code>Upgrade:</code> via an initial HTTP/1 request.</p>
- <p>One feature of HTTP/2 that offers new capabilities for web developers is
- <a href="#push">Server Push</a>. See that section on how your web application
- can make use of it.</p>
+ <p>One feature of HTTP/2 that formerly offered new capabilities for web developers is
+ <a href="#push">Server Push</a>, though it is now deprecated. See the
+ <a href="#earlyhints">Early Hints</a> section for the recommended alternative.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="building">Build httpd with HTTP/2 support <a title="Permanent link" href="#building" class="permalink">¶</a></h2>
<p><code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> uses the library of <a href="https://nghttp2.org">nghttp2</a>
- as its implementation base. In order to build <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> you need at least version 1.2.1 of
+ as its implementation base. Building <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> requires at least version 1.2.1 of
<code>libnghttp2</code> installed on your system.</p>
<p>When you <code>./configure</code> your Apache httpd source tree, you need to give it
'<code>--enable-http2</code>' as additional argument to trigger the build of the module.
Should your <code>libnghttp2</code> reside in an unusual place (whatever that is on your
operating system), you may announce its location with '<code>--with-nghttp2=<path></code>'
to <code>configure</code>.</p>
- <p>While that should do the trick for most, they are people who might prefer a statically
+ <p>While that should do the trick for most, there are people who might prefer a statically
linked <code>nghttp2</code> in this module. For those, the option <code>--enable-nghttp2-staticlib-deps</code>
- exists. It works quite similar to how one statically links openssl to <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>.</p>
+ exists. It works quite similar
ly to how one statically links openssl to <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>.</p>
<p>Speaking of SSL, you need to be aware that most browsers will speak HTTP/2 only on <code>https:</code>
- URLs, so you need a server with SSL support. But not only that, you will need a SSL library
+ URLs, so you need a server with SSL support. But not only that, you will need an SSL library
that supports the <code>ALPN</code> extension. If OpenSSL is the library you use, you need
at least version 1.0.2.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<p>When you have a <code>httpd</code> built with <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> you need some
- basic configuration for it becoming active. The first thing, as with every Apache module,
+ basic configuration for it becoming active. The first thing, as with every httpd module,
is that you need to load it:</p>
-
<pre class="prettyprint lang-config">LoadModule http2_module modules/mod_http2.so</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">LoadModule http2_module modules/mod_http2.so</pre>
+</div>
<p>The second directive you need to add to your server configuration is</p>
-
<pre class="prettyprint lang-config">Protocols h2 http/1.1</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Protocols h2 http/1.1</pre>
+</div>
<p>This allows h2, the secure variant, to be the preferred protocol on your server
- connections. When you want to enable all HTTP/2 variants, you simply write:</p>
-
<pre class="prettyprint lang-config">Protocols h2 h2c http/1.1</pre>
-
- <p>Depending on where you put this directive, it affects all connections or just
- the ones to a certain virtual host. You can nest it, as in:</p>
-
<pre class="prettyprint lang-config">Protocols http/1.1
+ connections. When you want to enable all HTTP/2 variants, write:</p>
+
<div class="example"><pre class="prettyprint lang-config">Protocols h2 h2c http/1.1</pre>
+</div>
+ <p>Depending on where you put this directive, it affects all connections or only
+ those to a specific virtual host. You can nest it, as in:</p>
+
<div class="example"><pre class="prettyprint lang-config">Protocols http/1.1
<VirtualHost ...>
- ServerName test.example.org
- Protocols h2 http/1.1
+ServerName test.example.org
+Protocols h2 http/1.1
</VirtualHost></pre>
-
+</div>
<p>This allows only HTTP/1 on connections, except SSL connections to <code>test.example.org</code>
which offer HTTP/2.</p>
<div class="note"><h3>Choose a strong SSLCipherSuite</h3>
<p>The <code class="directive"><a href="../mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code> needs to be configured with
a strong TLS cipher suite. The current version of <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> does not enforce any cipher but most
- clients do so. Pointing a browser to a <code>h2</code> enabled server with a inappropriate
- cipher suite will force it to simply refuse and fall back to HTTP 1.1. This is a common mistake
- that is done while configuring httpd for HTTP/2 the first time, so please keep it in mind to avoid
+ clients do so. Pointing a browser to a <code>h2</code> enabled server with an inappropriate
+ cipher suite causes it to refuse and fall back to HTTP 1.1. This is a common mistake
+ made while configuring httpd for HTTP/2 the first time, so please keep it in mind to avoid
long debugging sessions! If you want to be sure about the cipher suite to choose please avoid
- the ones listed in the HTTP/2 TLS reject list (<a href="https://www.rfc-editor.org/rfc/rfc7540">RFC 7540</a>).</p>
+ the ones listed in the HTTP/2 TLS reject list (<a href="https://www.rfc-editor.org/rfc/rfc9113#section-9.2.2">RFC 9113</a>).</p>
</div>
<p>The order of protocols mentioned is also relevant. By default, the first one is the
most preferred protocol. When a client offers multiple choices, the one most to the
left is selected. In</p>
-
<pre class="prettyprint lang-config">Protocols http/1.1 h2</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Protocols http/1.1 h2</pre>
+</div>
<p>the most preferred protocol is HTTP/1 and it will always be selected unless a
client <em>only</em> supports h2. Since we want to talk HTTP/2 to clients that
support it, the better order is</p>
-
<pre class="prettyprint lang-config">Protocols h2 h2c http/1.1</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Protocols h2 h2c http/1.1</pre>
+</div>
<p>There is one more thing to ordering: the client has its own preferences, too. If
you want, you can configure your server to select the protocol most preferred by
the client:</p>
-
<pre class="prettyprint lang-config">ProtocolsHonorOrder Off</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">ProtocolsHonorOrder Off</pre>
+</div>
<p>makes the order <em>you</em> wrote the Protocols irrelevant and only the client's
ordering will decide.</p>
<p>A last thing: the protocols you configure are not checked for correctness
<p>HTTP/2 is supported in all multi-processing modules that come with httpd. However, if
you use the <code class="module"><a href="../mod/prefork.html">prefork</a></code> mpm, there will be severe restrictions.</p>
- <p>In <code class="module"><a href="../mod/prefork.html">prefork</a></code>, <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> will only process one request at at time
+ <p>In <code class="module"><a href="../mod/prefork.html">prefork</a></code>, <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> will only process one request at a time
per connection. But clients, such as browsers, will send many requests at the same time.
If one of these takes long to process (or is a long polling one), the other requests will
stall.</p>
<div class="section">
<h2 id="clients">Clients <a title="Permanent link" href="#clients" class="permalink">¶</a></h2>
- <p>Almost all modern browsers support HTTP/2, but only over SSL connections: Firefox (v43),
- Chrome (v45), Safari (since v9), iOS Safari (v9), Opera (v35), Chrome for Android (v49)
- and Internet Explorer (v11 on Windows10) (<a href="http://caniuse.com/#search=http2">source</a>).</p>
+ <p>All modern browsers support HTTP/2 over TLS connections
+ (<a href="https://caniuse.com/http2">source</a>). Support has been universal across
+ major browsers since approximately 2015.</p>
<p>Other clients, as well as servers, are listed
<a href="https://github.com/http2/http2-spec/wiki/Implementations">on the Implementations wiki</a>,
among them implementations for c, c++, common lisp, dart, erlang, haskell, java, nodejs, php,
<p>The first tool to mention is of course <a href="https://curl.haxx.se">curl</a>. Please make sure that
your version supports HTTP/2 checking its <code>Features</code>:</p>
- <pre class="prettyprint lang-config"> $ curl -V
- curl 7.45.0 (x86_64-apple-darwin15.0.0) libcurl/7.45.0 OpenSSL/1.0.2d zlib/1.2.8 nghttp2/1.3.4
- Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 [...]
- Features: IPv6 Largefile NTLM NTLM_WB SSL libz TLS-SRP <strong>HTTP2</strong>
- </pre>
-
- <div class="note"><h3>Mac OS homebrew notes</h3>
- brew install curl --with-openssl --with-nghttp2
+<div class="example"><pre class="prettyprint lang-sh">$ curl -V
+curl 8.20.0 (x86_64-pc-linux-gnu) libcurl/8.20.0 OpenSSL/3.5.7 zlib/1.3.1 nghttp2/1.69.0
+Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 [...]
+Features: IPv6 Largefile NTLM NTLM_WB SSL libz TLS-SRP <strong>HTTP2</strong>
+</pre>
+</div>
+ <div class="note"><h3>macOS Homebrew notes</h3>
+ <p>Homebrew's <code>curl</code> includes HTTP/2 support by default. Install with
+ <code>brew install curl</code> and follow the displayed caveats to put it ahead
+ of the system curl in your PATH.</p>
</div>
<p>And for really deep inspection <a href="https://wiki.wireshark.org/HTTP2">wireshark</a>.</p>
<p>The <a href="https://nghttp2.org">nghttp2</a> package also includes clients, such as:</p>
</ul>
<p>Chrome offers detailed HTTP/2 logs on its connections via the
<a href="chrome://net-internals/#http2">special net-internals page</a>. There is also an
- interesting extension for <a href="https://chrome.google.com/webstore/detail/http2-and-spdy-indicator/mpbpobfflnpcgagjijhmgnchggcjblin?hl=en">Chrome</a>
- and <a href="https://addons.mozilla.org/en-us/firefox/addon/spdy-indicator/">Firefox</a>
- to visualize when your browser is using HTTP/2.</p>
+ interesting extension for <a href="https://chromewebstore.google.com/detail/http-indicator/hgcomhbcacfkpffiphlmnlhpppcjgmbl">Chrome</a>
+ and <a href="https://addons.mozilla.org/en-US/firefox/addon/http2-indicator/">Firefox</a>
+ to indicate when your browser is using HTTP/2.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="push">Server Push <a title="Permanent link" href="#push" class="permalink">¶</a></h2>
+ <div class="warning"><h3>Deprecation Notice</h3>
+ <p>Server Push is deprecated in <a href="https://www.rfc-editor.org/rfc/rfc9113#section-8.4">RFC 9113</a>. Major browsers
+ (Chrome 106+, Edge 106+) have removed support for it. While <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code>
+ still implements push, new deployments should use <a href="#earlyhints">103 Early Hints</a>
+ instead as a more reliable way to inform clients about needed resources.</p>
+ </div>
<p>The HTTP/2 protocol allows the server to PUSH responses to a client it never
asked for. The tone of the conversation is: "here is a request that you
never sent and the response to it will arrive soon..."</p>
<p>To summarize: there is no one good strategy on how to make best use of this
feature of HTTP/2 and everyone is still experimenting. So, how do you experiment
with it in Apache httpd?</p>
- <p><code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> inspect response header for <code>Link</code> headers
+ <p><code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> inspects response headers for <code>Link</code> headers
in a certain format:</p>
-
<pre class="prettyprint lang-config">Link </xxx.css>;rel=preload, </xxx.js>; rel=preload</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Link </xxx.css>;rel=preload, </xxx.js>; rel=preload</pre>
+</div>
<p>If the connection supports PUSH, these two resources will be sent to the
client. As a web developer, you may set these headers either directly in
your application response or you configure the server via</p>
-
<pre class="prettyprint lang-config"><Location /xxx.html>
- Header add Link "</xxx.css>;rel=preload"
- Header add Link "</xxx.js>;rel=preload"
+
<div class="example"><pre class="prettyprint lang-config"><Location /xxx.html>
+Header add Link "</xxx.css>;rel=preload"
+Header add Link "</xxx.js>;rel=preload"
</Location></pre>
-
+</div>
<p>If you want to use <code>preload</code> links without triggering a PUSH, you
can use the <code>nopush</code> parameter, as in</p>
-
<pre class="prettyprint lang-config">Link </xxx.css>;rel=preload;nopush</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">Link </xxx.css>;rel=preload;nopush</pre>
+</div>
<p>or you may disable PUSHes for your server entirely with the directive</p>
-
<pre class="prettyprint lang-config">H2Push Off</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">H2Push Off</pre>
+</div>
<p>And there is more:</p>
<p>The module will keep a diary of what has been PUSHed for each connection
(hashes of URLs, basically) and will not PUSH the same resource twice. When
the connection closes, this information is discarded.</p>
<p>There are people thinking about how a client can tell a server what it
- already has, so PUSHes for those things can be avoided, but this is all
- highly experimental right now.</p>
- <p>An
other experimental draft that has been implemented in <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code>
+ already has, so PUSHes for those things can be avoided, but no standard
+ emerged before push was deprecated.</p>
+ <p>An
experimental draft that was implemented in <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code>
is the <a href="https://datatracker.ietf.org/doc/html/draft-ruellan-http-accept-push-policy-00">
Accept-Push-Policy Header Field</a> where a client can, for each request, define
- what kind of PUSHes it accepts.</p>
+ what kind of PUSHes it accepts. This draft expired and was never adopted.</p>
<p>
PUSH might not always trigger the request/response/performance that one expects or
hopes for. There are various studies on this topic to be found on the web that explain
benefits and weaknesses and how different features of client and network influence
- the outcome. For example: just because the server PUSHes a resource does not mean
+ the outcome. For example: the fact that the server PUSHes a resource does not mean
a browser will actually use the data.</p>
<p>The major thing that influences the response being PUSHed is the request that was
simulated. The request URL for a PUSH is given by the application, but where do the
request headers come from? For example, will the PUSH request a <code>accept-language</code>
header and if yes with what value?</p>
- <p>Apache will look at the original request (the one that triggered the PUSH) and copy the
+ <p>httpd will look at the original request (the one that triggered the PUSH) and copy the
following headers over to PUSH requests: <code>user-agent</code>, <code>accept</code>,
<code>accept-encoding</code>, <code>accept-language</code>, <code>cache-control</code>.</p>
<p>All other headers are ignored. Cookies will also not be copied over. PUSHing resources
that require a cookie to be present will not work. This can be a matter of debate. But
- unless this is more clearly discussed with browser, let's err on the side of caution and
- not expose cookie where they might ordinarily not be visible.</p>
+ unless this is more clearly discussed with browsers, let's err on the side of caution and
+ not expose cookies where they might ordinarily not be visible.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="earlyhints">Early Hints <a title="Permanent link" href="#earlyhints" class="permalink">¶</a></h2>
<p>An alternative to PUSHing resources is to send <code>Link</code> headers to the
client before the response is even ready. This uses the HTTP feature called "Early Hints" and
is described in <a href="https://www.rfc-editor.org/rfc/rfc8297">RFC 8297</a>.</p>
- <p>In order to use this, you need to explicitly enable it on the server via</p>
-
<pre class="prettyprint lang-config">H2EarlyHints on</pre>
-
+ <p>To use this, you need to explicitly enable it on the server via</p>
+
<div class="example"><pre class="prettyprint lang-config">H2EarlyHints on</pre>
+</div>
<p>(It is not enabled by default since some older browser tripped on such responses.)</p>
<p>If this feature is on, you can use the directive <code class="directive"><a href="../mod/mod_http2.html#h2pushresource">H2PushResource</a></code> to
trigger early hints and resource PUSHes:</p>
-
<pre class="prettyprint lang-config"><Location /xxx.html>
- H2PushResource /xxx.css
- H2PushResource /xxx.js
+
<div class="example"><pre class="prettyprint lang-config"><Location /xxx.html>
+H2PushResource /xxx.css
+H2PushResource /xxx.js
</Location></pre>
-
+</div>
<p>This will send out a <code>"103 Early Hints"</code> response to a client as soon
- as the server <em>starts</em> processing the request. This may be much early than
+ as the server <em>starts</em> processing the request. This may be much earlier than
the time the first response headers have been determined, depending on your web
application.</p>
<p>If <code class="directive"><a href="../mod/mod_http2.html#h2push">H2Push</a></code> is enabled, this will also start the PUSH right after the
- 103 response. If <code class="directive"><a href="../mod/mod_http2.html#h2push">H2Push</a></code> is disabled however, the 103 response will be send
+ 103 response. If <code class="directive"><a href="../mod/mod_http2.html#h2push">H2Push</a></code> is disabled however, the 103 response will be sent
nevertheless to the client.</p>
</div></div>
<div class="bottomlang">
<a href="../es/howto/http2.html" hreflang="es" rel="alternate" title="Español"> es </a> |
<a href="../fr/howto/http2.html" title="Français"> fr </a></p>
</div>
+<div class="outofdate">Cette traduction peut être périmée. Vérifiez la version
+ anglaise pour les changements récents.</div>
<p>Ce document est le guide de l'utilisateur de l'implémentation de HTTP/2
dans Apache httpd. Cette fonctionnalité en est au stade
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.es.xsl"?>
-<!-- English Revision: 1834263:1933860 (outdated) -->
+<!-- English Revision: 1834263:1935505 (outdated) -->
<!-- Spanish translation : Daniel Ferradal -->
<!-- Reviewed & updated by Luis Gil de Bernabé Pfeiffer lgilbernabe[AT]apache.org -->
<!--
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1933860 -->
+<!-- English Revision: 1933860:1935505 (outdated) -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
<variants>
<variant>en</variant>
<variant outdated="yes">es</variant>
- <variant>fr</variant>
+ <variant outdated="yes">fr</variant>
</variants>
</metafile>
to a URL <code>http://example.com/~username/</code> will get content
out of the home directory of the user "<code>username</code>", out of
the subdirectory specified by the <code class="directive"><a href="../mod/mod_userdir.html#userdir">UserDir</a></code> directive.</p>
-<p>Note that, by default, access to these directories is <strong>not</strong>
+<p>By default, access to these directories is <strong>not</strong>
enabled. You can enable access when using <code class="directive"><a href="../mod/mod_userdir.html#userdir">UserDir</a></code> by uncommenting the line:</p>
-
<pre class="prettyprint lang-config">#Include conf/extra/httpd-userdir.conf</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">#Include conf/extra/httpd-userdir.conf</pre>
+</div>
<p>in the default config file <code>conf/httpd.conf</code>, and adapting the <code>httpd-userdir.conf</code>
file as necessary, or by including the appropriate directives in a
<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> block
within the main config file.</p>
+
+ <div class="note">Third-party distributions of httpd (from your OS vendor or
+ package manager) often place the <code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code>
+ configuration in a separate file, and may enable it by default.
+ Check your distribution's documentation for specifics. The examples
+ in this document assume a default source build of httpd.</div>
</div>
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif"> <a href="#related">Per-user web directories</a></li>
<li><img alt="" src="../images/down.gif"> <a href="#userdir">Setting the file path with UserDir</a></li>
assumed to be a directory path relative to the home directory of the
specified user. Given this configuration:</p>
-
<pre class="prettyprint lang-config">UserDir public_html</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">UserDir public_html</pre>
+</div>
<p>the URL <code>http://example.com/~rbowen/file.html</code> will be
translated to the file path
constructed using that path, plus the username specified. Given this
configuration:</p>
-
<pre class="prettyprint lang-config">UserDir /var/html</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">UserDir /var/html</pre>
+</div>
<p>the URL <code>http://example.com/~rbowen/file.html</code> will be
translated to the file path <code>/var/html/rbowen/file.html</code></p>
in which the asterisk is replaced with the username. Given this
configuration:</p>
-
<pre class="prettyprint lang-config">UserDir /var/www/*/docs</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">UserDir /var/www/*/docs</pre>
+</div>
<p>the URL <code>http://example.com/~rbowen/file.html</code> will be
translated to the file path
<p>Multiple directories or directory paths can also be set.</p>
-
<pre class="prettyprint lang-config">UserDir public_html /var/html</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">UserDir public_html /var/html</pre>
+</div>
- <p>For the URL <code>http://example.com/~rbowen/file.html</code>,
- Apache will search for <code>~rbowen</code>. If it isn't found,
- Apache will search for <code>rbowen</code> in <code>/var/html</code>. If
- found, the above URL will then be translated to the file path
- <code>/var/html/rbowen/file.html</code></p>
+ <p>The arguments are considered in the order they appear.
+ For the URL <code>http://example.com/~rbowen/file.html</code>,
+ httpd will search for <code>~rbowen</code>. If it isn't found,
+ httpd will then search for <code>rbowen</code> in <code>/var/html</code>.
+ The file will be served from whichever location is found first.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<p>The <code class="directive"><a href="../mod/mod_userdir.html#userdir">UserDir</a></code> directive can be
used to redirect user directory requests to external URLs.</p>
-
<pre class="prettyprint lang-config">UserDir http://example.org/users/*/</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">UserDir http://example.org/users/*/</pre>
+</div>
<p>The above example will redirect a request for
<code>http://example.com/~bob/abc.html</code> to
<p>Using the syntax shown in the UserDir documentation, you can restrict
what users are permitted to use this functionality:</p>
-
<pre class="prettyprint lang-config">UserDir disabled root jro fish</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">UserDir disabled root jro fish</pre>
+</div>
<p>The configuration above will enable the feature for all users
except for those listed in the <code>disabled</code> statement.
You can, likewise, disable the feature for all but a few users by
using a configuration like the following:</p>
-
<pre class="prettyprint lang-config">UserDir disabled
+
<div class="example"><pre class="prettyprint lang-config">UserDir disabled
UserDir enabled rbowen krietz</pre>
-
+</div>
<p>See <code class="directive"><a href="../mod/mod_userdir.html#userdir">UserDir</a></code>
documentation for additional examples.</p>
<h2 id="cgi">Enabling a cgi directory for each user <a title="Permanent link" href="#cgi" class="permalink">¶</a></h2>
- <p>In order to give each user their own cgi-bin directory, you can use
+ <p>To give each user their own cgi-bin directory, you can use
a <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>
directive to make a particular subdirectory of a user's home directory
cgi-enabled.</p>
-
<pre class="prettyprint lang-config"><Directory "/home/*/public_html/cgi-bin/">
- Options ExecCGI
- SetHandler cgi-script
+
<div class="example"><pre class="prettyprint lang-config"><Directory "/home/*/public_html/cgi-bin/">
+Options ExecCGI
+SetHandler cgi-script
</Directory></pre>
-
+</div>
<p>Then, presuming that <code>UserDir</code> is set to
<code>public_html</code>, a cgi program <code>example.cgi</code>
<h2 id="htaccess">Allowing users to alter configuration <a title="Permanent link" href="#htaccess" class="permalink">¶</a></h2>
- <p>If you want to allows users to modify the server configuration in
+ <p>If you want to allow users to modify the server configuration in
their web space, they will need to use <code>.htaccess</code> files to
make these changes. Ensure that you have set <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> to a
value sufficient for the directives that you want to permit the users
<a href="../ko/howto/public_html.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
<a href="../tr/howto/public_html.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
</div>
+<div class="outofdate">Esta traducción podría estar
+ obsoleta. Consulte la versión en inglés de la
+ documentación para comprobar si se han producido cambios
+ recientemente.</div>
<p>En sistemas con múltiples usuarios, cada usuario puede tener un website
en su directorio home usando la directiva <code class="directive"><a href="../mod/mod_userdir.html#userdir">UserDir</a></code>. Los visitantes de una URL
<a href="../ko/howto/public_html.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
<a href="../tr/howto/public_html.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
</div>
+<div class="outofdate">Cette traduction peut être périmée. Vérifiez la version
+ anglaise pour les changements récents.</div>
<p>Sur les systèmes multi-utilisateurs, on peut permettre à chaque
utilisateur d'avoir un site web dans son répertoire home à l'aide de la
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.es.xsl"?>
-<!-- English Revision: 1745711 -->
+<!-- English Revision: 1745711:1935516 (outdated) -->
<!-- Spanish translation : Daniel Ferradal -->
<!-- Reviewed by: Luis Gil de Bernabé Pfeiffer -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1745711 -->
+<!-- English Revision: 1745711:1935516 (outdated) -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 1591191:1745711 (outdated) -->
+<!-- English Revision: 1591191:1935516 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version='1.0' encoding='EUC-KR' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ko.xsl"?>
-<!-- English Revision: 151408:1745711 (outdated) -->
+<!-- English Revision: 151408:1935516 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<variants>
<variant>en</variant>
- <variant>es</variant>
- <variant>fr</variant>
+ <variant outdated="yes">es</variant>
+ <variant outdated="yes">fr</variant>
<variant outdated="yes">ja</variant>
<variant outdated="yes">ko</variant>
<variant outdated="yes">tr</variant>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 1174747:1745711 (outdated) -->
+<!-- English Revision: 1174747:1935516 (outdated) -->
<!-- =====================================================
Translated by: Nilgün Belma Bugüner <nilgun belgeler.org>
Reviewed by: Orhan Berent <berent belgeler.org>
<a href="../fr/howto/reverse_proxy.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
</div>
- <p>In addition to being a "basic" web server, and providing static and
- dynamic content to end-users, Apache httpd (as well as most other web
- servers) can also act as a reverse proxy server, also-known-as a
- "gateway" server.</p>
-
- <p>In such scenarios, httpd itself does not generate or host the data,
- but rather the content is obtained by one or several backend servers,
- which normally have no direct connection to the external network. As
- httpd receives a request from a client, the request itself is <em>proxied</em>
- to one of these backend servers, which then handles the request, generates
- the content and then sends this content back to httpd, which then
- generates the actual HTTP response back to the client.</p>
-
- <p>There are numerous reasons for such an implementation, but generally
- the typical rationales are due to security, high-availability, load-balancing
- and centralized authentication/authorization. It is critical in these
- implementations that the layout, design and architecture of the backend
- infrastructure (those servers which actually handle the requests) are
- insulated and protected from the outside; as far as the client is concerned,
- the reverse proxy server <em>is</em> the sole source of all content.</p>
+ <p>Besides serving static and dynamic content directly, Apache httpd
+ can act as a reverse proxy server (sometimes called a gateway).</p>
+
+ <p>In this mode, httpd does not generate the content itself. Instead,
+ it forwards each client request to one or more backend servers that
+ have no direct connection to the external network. The backend
+ processes the request and returns the content to httpd, which then
+ delivers the HTTP response to the client.</p>
+
+ <p>Common reasons include security, high availability, load balancing,
+ and centralized authentication. The backend infrastructure should be isolated from the external
+ network; as far as the client is concerned, the reverse proxy
+ <em>is</em> the sole source of all content.</p>
<p>A typical implementation is below:</p>
<p class="centered"><img src="../images/reverse-proxy-arch.png" alt="reverse-proxy-arch"></p>
to a single backend:
</p>
-
<pre class="prettyprint lang-config">ProxyPass "/" "http://www.example.com/"</pre>
-
+
<div class="example"><pre class="prettyprint lang-config">ProxyPass "/" "http://www.example.com/"</pre>
+</div>
<p>
- To ensure that and <code>Location:</code> headers generated from
+ To ensure that <code>Location:</code> headers generated from
the backend are modified to point to the reverse proxy, instead of
back to itself, the <code class="directive"><a href="../mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a></code>
directive is most often required:
</p>
-
<pre class="prettyprint lang-config">ProxyPass "/" "http://www.example.com/"
+
<div class="example"><pre class="prettyprint lang-config">ProxyPass "/" "http://www.example.com/"
ProxyPassReverse "/" "http://www.example.com/"</pre>
-
+</div>
<p>Only specific URIs can be proxied, as shown in this example:</p>
-
<pre class="prettyprint lang-config">ProxyPass "/images" "http://www.example.com/"
+
<div class="example"><pre class="prettyprint lang-config">ProxyPass "/images" "http://www.example.com/"
ProxyPassReverse "/images" "http://www.example.com/"</pre>
-
+</div>
<p>In the above, any requests which start with the <code>/images</code>
- path with be proxied to the specified backend, otherwise it will be handled
+ path will be proxied to the specified backend, otherwise it will be handled
locally.
</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<p>
- As useful as the above is, it still has the deficiencies that should
- the (single) backend node go down, or become heavily loaded, that proxying
- those requests provides no real advantage. What is needed is the ability
- to define a set or group of backend servers which can handle such
- requests and for the reverse proxy to load balance and failover among
- them. This group is sometimes called a <em>cluster</em> but Apache httpd's
- term is a <em>balancer</em>. One defines a balancer by leveraging the
+ The single-backend setup above has an obvious weakness: if that
+ node goes down or becomes overloaded, the proxied content is unavailable.
+ What you need is a group of backend servers that the reverse proxy can
+ load-balance and failover among. This group is sometimes called a <em>cluster</em>; Apache httpd's
+ term is a <em>balancer</em>. You define a balancer using the
<code class="directive"><a href="../mod/mod_proxy.html#proxy"><Proxy></a></code> and
- <code class="directive"><a href="../mod/mod_proxy.html#balancermember">BalancerMember</a></code> directives as
- shown:
+ <code class="directive"><a href="../mod/mod_proxy.html#balancermember">BalancerMember</a></code> directives:
</p>
-
<pre class="prettyprint lang-config"><Proxy balancer://myset>
- BalancerMember http://www2.example.com:8080
- BalancerMember http://www3.example.com:8080
- ProxySet lbmethod=bytraffic
+
<div class="example"><pre class="prettyprint lang-config"><Proxy balancer://myset>
+BalancerMember http://www2.example.com:8080
+BalancerMember http://www3.example.com:8080
+ProxySet lbmethod=bytraffic
</Proxy>
ProxyPass "/images/" "balancer://myset/"
ProxyPassReverse "/images/" "balancer://myset/"</pre>
-
+</div>
<p>
The <code>balancer://</code> scheme is what tells httpd that we are creating
<p>
- You can adjust numerous configuration details of the <em>balancers</em>
- and the <em>workers</em> via the various parameters defined in
- <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>. For example,
- assuming we would want <code>http://www3.example.com:8080</code> to
- handle 3x the traffic with a timeout of 1 second, we would adjust the
- configuration as follows:
+ You can tune <em>balancers</em> and <em>workers</em> through
+ parameters on <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>.
+ For example, to have <code>http://www3.example.com:8080</code>
+ handle 3× the traffic with a 1-second timeout:
</p>
-
<pre class="prettyprint lang-config"><Proxy balancer://myset>
- BalancerMember http://www2.example.com:8080
- BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
- ProxySet lbmethod=bytraffic
+
<div class="example"><pre class="prettyprint lang-config"><Proxy balancer://myset>
+BalancerMember http://www2.example.com:8080
+BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
+ProxySet lbmethod=bytraffic
</Proxy>
ProxyPass "/images" "balancer://myset/"
ProxyPassReverse "/images" "balancer://myset/"</pre>
-
+</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<p>
- You can also fine-tune various failover scenarios, detailing which workers
- and even which balancers should be accessed in such cases. For example, the
- below setup implements three failover cases:
+ You can fine-tune failover scenarios, specifying which workers and
+ balancers handle traffic when others fail. The setup below
+ implements three failover cases:
</p>
<ol>
<li>
</li>
</ol>
<p>
- Thus, it is possible to have one or more hot spares and hot standbys for
- each load balancer set.
+ You can have one or more hot spares and hot standbys for each
+ load balancer set.
</p>
-
<pre class="prettyprint lang-config"><Proxy balancer://myset>
- BalancerMember http://www2.example.com:8080
- BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
- BalancerMember http://spare1.example.com:8080 status=+R
- BalancerMember http://spare2.example.com:8080 status=+R
- BalancerMember http://hstandby.example.com:8080 status=+H
- BalancerMember http://bkup1.example.com:8080 lbset=1
- BalancerMember http://bkup2.example.com:8080 lbset=1
- ProxySet lbmethod=byrequests
+
<div class="example"><pre class="prettyprint lang-config"><Proxy balancer://myset>
+BalancerMember http://www2.example.com:8080
+BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
+BalancerMember http://spare1.example.com:8080 status=+R
+BalancerMember http://spare2.example.com:8080 status=+R
+BalancerMember http://hstandby.example.com:8080 status=+H
+BalancerMember http://bkup1.example.com:8080 lbset=1
+BalancerMember http://bkup2.example.com:8080 lbset=1
+ProxySet lbmethod=byrequests
</Proxy>
ProxyPass "/images/" "balancer://myset/"
ProxyPassReverse "/images/" "balancer://myset/"</pre>
-
+</div>
<p>
- For failover, hot spares are used as replacements for unusable workers in
- the same load balancer set. A worker is considered unusable if it is
- draining, stopped, or otherwise in an error/failed state. Hot standbys are
- used if all workers and spares in the load balancer set are
- unavailable. Load balancer sets (with their respective hot spares and
- standbys) are always tried in order from lowest to highest.
+ Hot spares replace unusable workers (draining, stopped, or in an
+ error state) within the same load balancer set. Hot standbys
+ activate only when all workers and spares in a set are unavailable.
+ Sets are tried in order from lowest to highest.
</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<p>
- One of the most unique and useful features of Apache httpd's reverse proxy is
- the embedded <em>balancer-manager</em> application. Similar to
- <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>, <em>balancer-manager</em> displays
- the current working configuration and status of the enabled
- balancers and workers currently in use. However, not only does it
- display these parameters, it also allows for dynamic, runtime, on-the-fly
- reconfiguration of almost all of them, including adding new <em>BalancerMembers</em>
- (workers) to an existing balancer. To enable these capability, the following
- needs to be added to your configuration:
+ Apache httpd includes an embedded <em>balancer-manager</em>
+ application. Like <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>, it displays the
+ current configuration and status of your balancers and workers.
+ It also lets you reconfigure them at runtime—including adding
+ new <em>BalancerMembers</em> to an existing balancer. To enable
+ it, add the following to your configuration:
</p>
-
<pre class="prettyprint lang-config"><Location "/balancer-manager">
- SetHandler balancer-manager
- Require host localhost
+
<div class="example"><pre class="prettyprint lang-config"><Location "/balancer-manager">
+SetHandler balancer-manager
+Require host localhost
</Location></pre>
-
+</div>
<div class="warning"><h3>Warning</h3>
<p>Do not enable the <em>balancer-manager</em> until you have <a href="../mod/mod_proxy.html#access">secured your server</a>. In
</div>
<p>
- When the reverse proxy server is accessed at that url
- (eg: <code>http://rproxy.example.com/balancer-manager/</code>, you will see a
- page similar to the below:
+ When you access that URL
+ (e.g. <code>http://rproxy.example.com/balancer-manager/</code>), you
+ will see a page like this:
</p>
<p class="centered"><img src="../images/bal-man.png" alt="balancer-manager page"></p>
<p>
- This form allows the devops admin to adjust various parameters, take
- workers offline, change load balancing methods and add new works. For
- example, clicking on the balancer itself, you will get the following page:
+ From here you can adjust parameters, take workers offline, change
+ load balancing methods, and add new workers. Clicking on the
+ balancer itself shows:
</p>
<p class="centered"><img src="../images/bal-man-b.png" alt="balancer-manager page"></p>
<p class="centered"><img src="../images/bal-man-w.png" alt="balancer-manager page"></p>
<p>
- To have these changes persist restarts of the reverse proxy, ensure that
- <code class="directive"><a href="../mod/mod_proxy.html#balancerpersist">BalancerPersist</a></code> is enabled.
+ To persist these changes across restarts, enable
+ <code class="directive"><a href="../mod/mod_proxy.html#balancerpersist">BalancerPersist</a></code>.
</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<p>
- Before httpd proxies a request to a worker, it can <em>"test"</em> if that worker
- is available via setting the <code>ping</code> parameter for that worker using
- <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>. Oftentimes it is
- more useful to check the health of the workers <em>out of band</em>, in a
- dynamic fashion. This is achieved in Apache httpd by the
- <code class="module"><a href="../mod/mod_proxy_hcheck.html">mod_proxy_hcheck</a></code> module.
+ Before proxying a request, httpd can test whether a worker is
+ available using the <code>ping</code> parameter in
+ <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>. Often it is
+ more useful to check worker health <em>out of band</em>.
+ <code class="module"><a href="../mod/mod_proxy_hcheck.html">mod_proxy_hcheck</a></code> provides this capability.
</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<a href="../es/howto/reverse_proxy.html" hreflang="es" rel="alternate" title="Español"> es </a> |
<a href="../fr/howto/reverse_proxy.html" title="Français"> fr </a></p>
</div>
+<div class="outofdate">Cette traduction peut être périmée. Vérifiez la version
+ anglaise pour les changements récents.</div>
<p>En plus de ses fonctions de serveur web "basique", à savoir fournir du
contenu statique et dynamique à l'utilisateur, Apache httpd (comme la
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.es.xsl"?>
-<!-- English Revision: 1784674:1874148 (outdated) -->
+<!-- English Revision: 1784674:1935520 (outdated) -->
<!-- Spanish translation : Daniel Ferradal -->
<!-- Reviewed by Luis Gil de Bernabé Pfeiffer -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1874148 -->
+<!-- English Revision: 1874148:1935520 (outdated) -->
<!-- French translation : Lucien GENTIS -->
<!--
<variants>
<variant>en</variant>
<variant outdated="yes">es</variant>
- <variant>fr</variant>
+ <variant outdated="yes">fr</variant>
</variants>
</metafile>
<a href="../ko/howto/ssi.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
</div>
-<p>Server-side includes provide a means to add dynamic content to
-existing HTML documents.</p>
+<p>Server Side Includes (SSI) provide a way to add dynamic content to
+existing HTML documents without requiring a full application framework.
+They are particularly useful for inserting common elements — headers,
+footers, navigation, timestamps — into otherwise static pages.</p>
</div>
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif"> <a href="#related">Introduction</a></li>
<li><img alt="" src="../images/down.gif"> <a href="#what">What are SSI?</a></li>
<li><img alt="" src="../images/down.gif"> <a href="#configuring">Configuring your server to permit SSI</a></li>
<li><img alt="" src="../images/down.gif"> <a href="#basic">Basic SSI directives</a></li>
<li><img alt="" src="../images/down.gif"> <a href="#additionalexamples">Additional examples</a></li>
-<li><img alt="" src="../images/down.gif"> <a href="#config">What else can I config?</a></li>
+<li><img alt="" src="../images/down.gif"> <a href="#config">Other config options</a></li>
<li><img alt="" src="../images/down.gif"> <a href="#exec">Executing commands</a></li>
<li><img alt="" src="../images/down.gif"> <a href="#advanced">Advanced SSI techniques</a></li>
<li><img alt="" src="../images/down.gif"> <a href="#conclusion">Conclusion</a></li>
<h2 id="related">Introduction <a title="Permanent link" href="#related" class="permalink">¶</a></h2>
<table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="../mod/mod_include.html">mod_include</a></code></li><li><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code></li><li><code class="module"><a href="../mod/mod_expires.html">mod_expires</a></code></li></ul></td><td><ul><li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li><li><code class="directive"><a href="../mod/mod_include.html#xbithack">XBitHack</a></code></li><li><code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code></li><li><code class="directive"><a href="../mod/core.html#setoutputfilter">SetOutputFilter</a></code></li><li><code class="directive"><a href="../mod/mod_setenvif.html#browsermatchnocase">BrowserMatchNoCase</a></code></li></ul></td></tr></table>
- <p>This article deals with Server Side Includes, usually called
- simply SSI. In this article, I'll talk about configuring your
- server to permit SSI, and introduce some basic SSI techniques
- for adding dynamic content to your existing HTML pages.</p>
+ <p>SSI lets you drop simple directives into your HTML files that
+ the server evaluates before sending the page to the client. This
+ is a lightweight way to keep shared content (like a site-wide
+ footer or a "last modified" timestamp) in one place, without
+ needing a template engine or application server.</p>
- <p>In the latter part of the article, we'll talk about some of
- the somewhat more advanced things that can be done with SSI,
- such as conditional statements in your SSI directives.</p>
+ <p>This document covers configuring httpd to permit SSI, basic
+ SSI directives for common tasks, and some more advanced
+ techniques including variables and conditional expressions.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="what">What are SSI? <a title="Permanent link" href="#what" class="permalink">¶</a></h2>
- <p>SSI (Server Side Includes) are directives that are placed in
- HTML pages, and evaluated on the server while the pages are
- being served. They let you add dynamically generated content to
- an existing HTML page, without having to serve the entire page
- via a CGI program, or other dynamic technology.</p>
+ <p>SSI directives are HTML comments with a specific syntax that
+ <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> recognizes and evaluates before the
+ page is sent to the client. They look like this:</p>
- <p>For example, you might place a directive into an existing HTML
- page, such as:</p>
-
- <div class="example"><p><code>
- <!--#echo var="DATE_LOCAL" -->
- </code></p></div>
+<div class="example"><pre class="prettyprint lang-html"><!--#echo var="DATE_LOCAL" --></pre>
+</div>
- <p>And, when the page is served, this fragment will be evaluated and replaced with its value:</p>
+ <p>When the page is served, this fragment is replaced with its
+ value:</p>
<div class="example"><p><code>
- Tuesday, 15-Jan-2013 19:28:54 EST
+ Thursday, 18-Jun-2026 14:22:07 EDT
</code></p></div>
- <p>The decision of when to use SSI, and when to have your page
- entirely generated by some program, is usually a matter of how
- much of the page is static, and how much needs to be
- recalculated every time the page is served. SSI is a great way
- to add small pieces of information, such as the current time - shown
- above. But if a majority of your page is being generated at the time
- that it is served, you need to look for some other solution.</p>
+ <p>Because the directives are embedded in HTML comments, if SSI
+ is not enabled, browsers ignore them (though they remain
+ visible in the page source).</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="configuring">Configuring your server to permit SSI <a title="Permanent link" href="#configuring" class="permalink">¶</a></h2>
- <p>To permit SSI on your server, you must have the following
- directive either in your <code>httpd.conf</code> file, or in a
- <code>.htaccess</code> file:</p>
-<pre class="prettyprint lang-config">Options +Includes</pre>
+ <p>To enable SSI processing, add the following directive to your
+ <code>httpd.conf</code> file or to a <code>.htaccess</code>
+ file:</p>
+
+<div class="example"><pre class="prettyprint lang-config">Options +Includes</pre>
+</div>
+
+ <p>This tells httpd to parse files for SSI directives. Since most
+ configurations contain multiple <code class="directive"><a href="../mod/core.html#options">Options</a></code> directives that can override each other, apply
+ this to the specific directory where you want SSI enabled.</p>
+ <p>You also need to tell httpd which files to parse. There are
+ two common approaches.</p>
- <p>This tells Apache that you want to permit files to be parsed
- for SSI directives. Note that most configurations contain
- multiple <code class="directive"><a href="../mod/core.html#options">Options</a></code> directives
- that can override each other. You will probably need to apply the
- <code>Options</code> to the specific directory where you want SSI
- enabled in order to assure that it gets evaluated last.</p>
+ <p>The first is to designate a file extension (typically
+ <code>.shtml</code>) for SSI-enabled pages:</p>
- <p>Not just any file is parsed for SSI directives. You have to
- tell Apache which files should be parsed. There are two ways to
- do this. You can tell Apache to parse any file with a
- particular file extension, such as <code>.shtml</code>, with
- the following directives:</p>
-<pre class="prettyprint lang-config">AddType text/html .shtml
+<div class="example"><pre class="prettyprint lang-config">AddType text/html .shtml
AddOutputFilter INCLUDES .shtml</pre>
+</div>
+ <p>The disadvantage here is that adding SSI to an existing page
+ requires renaming the file (and updating all links to it) to use
+ the <code>.shtml</code> extension.</p>
- <p>One disadvantage to this approach is that if you wanted to
- add SSI directives to an existing page, you would have to
- change the name of that page, and all links to that page, in
- order to give it a <code>.shtml</code> extension, so that those
- directives would be executed.</p>
+ <p>The second approach uses the <code class="directive"><a href="../mod/mod_include.html#xbithack">XBitHack</a></code> directive:</p>
- <p>The other method is to use the <code class="directive"><a href="../mod/mod_include.html#xbithack">XBitHack</a></code> directive:</p>
-<pre class="prettyprint lang-config">XBitHack on</pre>
+<div class="example"><pre class="prettyprint lang-config">XBitHack on</pre>
+</div>
+ <p><code class="directive"><a href="../mod/mod_include.html#xbithack">XBitHack</a></code> tells
+ httpd to parse any file that has its execute bit set. To enable
+ SSI on an existing page, make the file executable:</p>
- <p><code class="directive"><a href="../mod/mod_include.html#xbithack">XBitHack</a></code>
- tells Apache to parse files for SSI
- directives if they have the execute bit set. So, to add SSI
- directives to an existing page, rather than having to change
- the file name, you would just need to make the file executable
- using <code>chmod</code>.</p>
-<div class="example"><p><code>
- chmod +x pagename.html
-</code></p></div>
+<div class="example"><pre class="prettyprint lang-bash">chmod +x pagename.html</pre>
+</div>
+
+ <div class="warning"><p>
+ Avoid configuring httpd to parse <em>all</em> <code>.html</code>
+ files for SSI directives. This forces the server to read through
+ every HTML file it serves, even those without any SSI content,
+ which adds unnecessary overhead.
+ </p></div>
- <p>A brief comment about what not to do. You'll occasionally
- see people recommending that you just tell Apache to parse all
- <code>.html</code> files for SSI, so that you don't have to
- mess with <code>.shtml</code> file names. These folks have
- perhaps not heard about <code class="directive"><a href="../mod/mod_include.html#xbithack">XBitHack</a></code>. The thing to
- keep in mind is that, by doing this, you're requiring that
- Apache read through every single file that it sends out to
- clients, even if they don't contain any SSI directives. This
- can slow things down quite a bit, and is not a good idea.</p>
-
- <p>Of course, on Windows, there is no such thing as an execute
- bit to set, so that limits your options a little.</p>
-
- <p>In its default configuration, Apache does not send the last
- modified date or content length HTTP headers on SSI pages,
- because these values are difficult to calculate for dynamic
- content. This can prevent your document from being cached, and
- result in slower perceived client performance. There are two
- ways to solve this:</p>
+ <p>On Windows, there is no execute bit, so the
+ <code class="directive"><a href="../mod/mod_include.html#xbithack">XBitHack</a></code> approach is
+ not available. Use the file-extension method instead.</p>
+
+ <p>By default, httpd does not send the last-modified date or
+ content-length headers on SSI pages, since these values are
+ difficult to calculate for dynamic content. This can prevent
+ caching and result in slower perceived performance. Two
+ approaches can help:</p>
<ol>
- <li>Use the <code>XBitHack Full</code> configuration. This
- tells Apache to determine the last modified date by looking
- only at the date of the originally requested file, ignoring
- the modification date of any included files.</li>
-
- <li>Use the directives provided by
- <code class="module"><a href="../mod/mod_expires.html">mod_expires</a></code> to set an explicit expiration
- time on your files, thereby letting browsers and proxies
- know that it is acceptable to cache them.</li>
+ <li>Use <code>XBitHack Full</code>, which tells httpd to
+ determine the last-modified date from the originally requested
+ file, ignoring the modification dates of included files.</li>
+
+ <li>Use <code class="module"><a href="../mod/mod_expires.html">mod_expires</a></code> to set an explicit
+ expiration time, letting browsers and proxies know the content
+ is safe to cache.</li>
</ol>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="basic">Basic SSI directives <a title="Permanent link" href="#basic" class="permalink">¶</a></h2>
- <p>SSI directives have the following syntax:</p>
-<div class="example"><p><code>
- <!--#function attribute=value attribute=value ... -->
-</code></p></div>
-
- <p>It is formatted like an HTML comment, so if you don't have
- SSI correctly enabled, the browser will ignore it, but it will
- still be visible in the HTML source. If you have SSI correctly
- configured, the directive will be replaced with its
- results.</p>
+ <p>SSI directives use the following syntax:</p>
+<div class="example"><pre class="prettyprint lang-html"><!--#function attribute=value attribute=value ... --></pre>
+</div>
- <p>The function can be one of a number of things, and we'll talk
- some more about most of these in the next installment of this
- series. For now, here are some examples of what you can do with
- SSI</p>
+ <p>If SSI is correctly configured, the directive is replaced with
+ its output. If not, it remains as an HTML comment — invisible to
+ the end user but present in the source.</p>
<h3 id="todaysdate">Today's date</h3>
-<div class="example"><p><code>
- <!--#echo var="DATE_LOCAL" -->
-</code></p></div>
+<div class="example"><pre class="prettyprint lang-html"><!--#echo var="DATE_LOCAL" --></pre>
+</div>
- <p>The <code>echo</code> function just spits out the value of a
- variable. There are a number of standard variables, which
- include the whole set of environment variables that are
- available to CGI programs. Also, you can define your own
- variables with the <code>set</code> function.</p>
+ <p>The <code>echo</code> function outputs the value of a variable.
+ Standard variables include the full set of environment variables
+ available to CGI programs, plus variables you define with
+ <code>set</code>.</p>
- <p>If you don't like the format in which the date gets printed,
- you can use the <code>config</code> function, with a
- <code>timefmt</code> attribute, to modify that formatting.</p>
+ <p>To customize the date format, use the <code>config</code>
+ function with the <code>timefmt</code> attribute:</p>
-<div class="example"><p><code>
- <!--#config timefmt="%A %B %d, %Y" --><br>
- Today is <!--#echo var="DATE_LOCAL" -->
-</code></p></div>
+<div class="example"><pre class="prettyprint lang-html"><!--#config timefmt="%A %B %d, %Y" --><br>
+Today is <!--#echo var="DATE_LOCAL" --></pre>
+</div>
<h3 id="lastmodified">Modification date of the file</h3>
-<div class="example"><p><code>
- This document last modified <!--#flastmod file="index.html" -->
-</code></p></div>
+<div class="example"><pre class="prettyprint lang-html">This document last modified <!--#flastmod file="index.html" --></pre>
+</div>
- <p>This function is also subject to <code>timefmt</code> format
- configurations.</p>
+ <p>This function is also subject to <code>timefmt</code>
+ configuration.</p>
<h3 id="cgi">Including the results of a CGI program</h3>
- <p>This is one of the more common uses of SSI - to output the
- results of a CGI program, such as everybody's favorite, a ``hit
- counter.''</p>
+ <p>SSI can include the output of a CGI program directly in the
+ page:</p>
-<div class="example"><p><code>
- <!--#include virtual="/cgi-bin/counter.pl" -->
-</code></p></div>
+<div class="example"><pre class="prettyprint lang-html"><!--#include virtual="/cgi-bin/counter.pl" --></pre>
+</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<h2 id="additionalexamples">Additional examples <a title="Permanent link" href="#additionalexamples" class="permalink">¶</a></h2>
- <p>Following are some specific examples of things you can do in
- your HTML documents with SSI.</p>
+ <p>The following are practical examples of common SSI use
+ cases.</p>
-<h3 id="docmodified">When was this document
-modified?</h3>
+<h3 id="docmodified">When was this document modified?</h3>
- <p>Earlier, we mentioned that you could use SSI to inform the
- user when the document was most recently modified. However, the
- actual method for doing that was left somewhat in question. The
- following code, placed in your HTML document, will put such a
- time stamp on your page. Of course, you will have to have SSI
- correctly enabled, as discussed above.</p>
-<div class="example"><p><code>
- <!--#config timefmt="%A %B %d, %Y" --><br>
- This file last modified <!--#flastmod file="ssi.shtml" -->
-</code></p></div>
+ <p>A common use of SSI is to display a "last modified" timestamp
+ on each page. The following code uses the
+ <code>LAST_MODIFIED</code> variable so you can paste the same
+ snippet into any file without changing the filename:</p>
- <p>Of course, you will need to replace the
- <code>ssi.shtml</code> with the actual name of the file that
- you're referring to. This can be inconvenient if you're just
- looking for a generic piece of code that you can paste into any
- file, so you probably want to use the
- <code>LAST_MODIFIED</code> variable instead:</p>
-<div class="example"><p><code>
- <!--#config timefmt="%D" --><br>
- This file last modified <!--#echo var="LAST_MODIFIED" -->
-</code></p></div>
+<div class="example"><pre class="prettyprint lang-html"><!--#config timefmt="%D" --><br>
+This file last modified <!--#echo var="LAST_MODIFIED" --></pre>
+</div>
- <p>For more details on the <code>timefmt</code> format, go to
- your favorite search site and look for <code>strftime</code>. The
- syntax is the same.</p>
+ <p>For details on <code>timefmt</code> format strings, see the
+ documentation for <code>strftime</code> in your system's C
+ library reference.</p>
<h3 id="standard-footer">Including a standard footer</h3>
- <p>If you are managing any site that is more than a few pages,
- you may find that making changes to all those pages can be a
- real pain, particularly if you are trying to maintain some kind
- of standard look across all those pages.</p>
-
- <p>Using an include file for a header and/or a footer can
- reduce the burden of these updates. You just have to make one
- footer file, and then include it into each page with the
- <code>include</code> SSI command. The <code>include</code>
- function can determine what file to include with either the
- <code>file</code> attribute, or the <code>virtual</code>
- attribute. The <code>file</code> attribute is a file path,
- <em>relative to the current directory</em>. That means that it
- cannot be an absolute file path (starting with /), nor can it
- contain ../ as part of that path. The <code>virtual</code>
- attribute is probably more useful, and should specify a URL
- relative to the document being served. It can start with a /,
- but must be on the same server as the file being served.</p>
-<div class="example"><p><code>
- <!--#include virtual="/footer.html" -->
-</code></p></div>
+ <p>On a site with more than a few pages, maintaining a
+ consistent header or footer across all pages can be tedious.
+ SSI solves this by letting you keep shared content in a single
+ file and include it everywhere:</p>
+
+<div class="example"><pre class="prettyprint lang-html"><!--#include virtual="/footer.html" --></pre>
+</div>
- <p>I'll frequently combine the last two things, putting a
- <code>LAST_MODIFIED</code> directive inside a footer file to be
- included. SSI directives can be contained in the included file,
- and includes can be nested - that is, the included file can
- include another file, and so on.</p>
+ <p>The <code>include</code> function accepts two attributes:
+ <code>file</code> specifies a path relative to the current
+ directory (it cannot be an absolute path or contain
+ <code>../</code>), while <code>virtual</code> specifies a URL
+ relative to the document being served (it can start with
+ <code>/</code> but must be on the same server).</p>
+
+ <p>SSI directives inside included files are evaluated normally,
+ and includes can be nested. This means you can put a
+ <code>LAST_MODIFIED</code> timestamp in your footer file, and
+ it will be evaluated in the context of each page that includes
+ it.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
-<h2 id="config">
What else can I config? <a title="Permanent link" href="#config" class="permalink">¶</a></h2>
+<h2 id="config">
Other config options <a title="Permanent link" href="#config" class="permalink">¶</a></h2>
- <p>In addition to being able to <code>config</code> the time
- format, you can also <code>config</code> two other things.</p>
+ <p>In addition to <code>timefmt</code>, the <code>config</code>
+ function supports two other attributes.</p>
- <p>Usually, when something goes wrong with your SSI directive,
- you get the message</p>
+ <p>The <code>errmsg</code> attribute changes the error message
+ displayed when an SSI directive fails. The default is:</p>
<div class="example"><p><code>
- [an error occurred while processing this directive]
+[an error occurred while processing this directive]
</code></p></div>
- <p>If you want to change that message to something else, you
- can do so with the <code>errmsg</code> attribute to the
- <code>config</code> function:</p>
-<div class="example"><p><code>
- <!--#config errmsg="[It appears that you don't know how to use SSI]" -->
-</code></p></div>
-
- <p>Hopefully, end users will never see this message, because
- you will have resolved all the problems with your SSI
- directives before your site goes live. (Right?)</p>
+ <p>You can replace it with something more appropriate for your
+ site:</p>
+<div class="example"><pre class="prettyprint lang-html"><!--#config errmsg="[Content unavailable]" --></pre>
+</div>
- <p>And you can <code>config</code> the format in which file
- sizes are returned with the <code>sizefmt</code> attribute. You
- can specify <code>bytes</code> for a full count in bytes, or
- <code>abbrev</code> for an abbreviated number in Kb or Mb, as
- appropriate.</p>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
+ <p>The <code>sizefmt</code> attribute controls how file sizes
+ are formatted: <code>bytes</code> for a full byte count, or
+ <code>abbrev</code> for an abbreviated form in KB or MB.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="exec">Executing commands <a title="Permanent link" href="#exec" class="permalink">¶</a></h2>
- <p>Here's something else that you can do with the <code>exec</code>
- function. You can actually have SSI execute a command using the
- shell (<code>/bin/sh</code>, to be precise - or the DOS shell,
- if you're on Win32). The following, for example, will give you
- a directory listing.</p>
-<div class="example"><p><code>
- <pre><br>
- <!--#exec cmd="ls" --><br>
- </pre>
-</code></p></div>
+ <p>The <code>exec</code> function can run a shell command and
+ include its output in the page. On Unix-like systems, the
+ command is executed via <code>/bin/sh</code>; on Windows, via
+ the command shell.</p>
- <p>or, on Windows</p>
-<div class="example"><p><code>
- <pre><br>
- <!--#exec cmd="dir" --><br>
- </pre>
-</code></p></div>
+<div class="example"><pre class="prettyprint lang-html"><pre>
+<!--#exec cmd="ls" -->
+</pre></pre>
+</div>
- <p>You might notice some strange formatting with this directive
- on Windows, because the output from <code>dir</code> contains
- the string ``<<code>dir</code>>'' in it, which confuses
- browsers.</p>
-
- <p>Note that this feature is exceedingly dangerous, as it will
- execute whatever code happens to be embedded in the
- <code>exec</code> tag. If you have any situation where users
- can edit content on your web pages, such as with a
- ``guestbook'', for example, make sure that you have this
- feature disabled. You can allow SSI, but not the
- <code>exec</code> feature, with the <code>IncludesNOEXEC</code>
- argument to the <code>Options</code> directive.</p>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
+ <div class="warning"><p>
+ The <code>exec</code> feature is a significant security risk. It
+ executes arbitrary commands with the permissions of the web
+ server process. If users can edit content on your site, ensure
+ this feature is disabled by using <code>IncludesNOEXEC</code>
+ instead of <code>Includes</code> in the <code class="directive"><a href="../mod/core.html#options">Options</a></code> directive.
+ </p></div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="advanced">Advanced SSI techniques <a title="Permanent link" href="#advanced" class="permalink">¶</a></h2>
- <p>In addition to spitting out content, Apache SSI gives you
- the option of setting variables, and using those variables in
- comparisons and conditionals.</p>
+ <p>Beyond simple content inclusion, SSI supports variables and
+ conditional expressions, making it possible to generate
+ different content based on the request context.</p>
<h3 id="variables">Setting variables</h3>
- <p>Using the <code>set</code> directive, you can set variables
- for later use. We'll need this later in the discussion, so
- we'll talk about it here. The syntax of this is as follows:</p>
-<div class="example"><p><code>
- <!--#set var="name" value="Rich" -->
-</code></p></div>
+ <p>The <code>set</code> directive defines variables for use later
+ in the page:</p>
+
+<div class="example"><pre class="prettyprint lang-html"><!--#set var="name" value="Rich" --></pre>
+</div>
- <p>In addition to merely setting values literally like that, you
- can use any other variable, including <a href="../env.html">environment variables</a> or the variables
- discussed above (like <code>LAST_MODIFIED</code>, for example) to
- give values to your variables. You will specify that something is
- a variable, rather than a literal string, by using the dollar sign
- ($) before the name of the variable.</p>
+ <p>Variables can reference other variables (including
+ <a href="../env.html">environment variables</a>) using the dollar
+ sign (<code>$</code>) prefix:</p>
- <div class="example"><p><code> <!--#set var="modified" value="$LAST_MODIFIED" -->
- </code></p></div>
+<div class="example"><pre class="prettyprint lang-html"><!--#set var="modified" value="$LAST_MODIFIED" --></pre>
+</div>
- <p>To put a literal dollar sign into the value of your
- variable, you need to escape the dollar sign with a
- backslash.</p>
-<div class="example"><p><code>
- <!--#set var="cost" value="\$100" -->
-</code></p></div>
+ <p>To include a literal dollar sign, escape it with a
+ backslash:</p>
- <p>Finally, if you want to put a variable in the midst of a
- longer string, and there's a chance that the name of the
- variable will run up against some other characters, and thus be
- confused with those characters, you can place the name of the
- variable in braces, to remove this confusion. (It's hard to
- come up with a really good example of this, but hopefully
- you'll get the point.)</p>
-<div class="example"><p><code>
- <!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
-</code></p></div>
+<div class="example"><pre class="prettyprint lang-html"><!--#set var="cost" value="\$100" --></pre>
+</div>
+
+ <p>When a variable name might be ambiguous within a longer
+ string, use braces to delimit it:</p>
+
+<div class="example"><pre class="prettyprint lang-html"><!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --></pre>
+</div>
<h3 id="conditional">Conditional expressions</h3>
- <p>Now that we have variables, and are able to set and compare
- their values, we can use them to express conditionals. This
- lets SSI be a tiny programming language of sorts.
- <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> provides an <code>if</code>,
- <code>elif</code>, <code>else</code>, <code>endif</code>
- structure for building conditional statements. This allows you
- to effectively generate multiple logical pages out of one
- actual page.</p>
+ <p><code class="module"><a href="../mod/mod_include.html">mod_include</a></code> provides <code>if</code>,
+ <code>elif</code>, <code>else</code>, and <code>endif</code>
+ constructs for building conditional logic. This lets you
+ generate different output from a single physical page.</p>
- <p>The structure of this conditional construct is:</p>
-<div class="example"><p><code>
- <!--#if expr="test_condition" --><br>
- <!--#elif expr="test_condition" --><br>
- <!--#else --><br>
- <!--#endif -->
-</code></p></div>
+ <p>The structure is:</p>
- <p>A <em>test_condition</em> can be any sort of logical
- comparison - either comparing values to one another, or testing
- the ``truth'' of a particular value. (A given string is true if
- it is nonempty.) For a full list of the comparison operators
- available to you, see the <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
- documentation.</p>
+<div class="example"><pre class="prettyprint lang-html"><!--#if expr="test_condition" --><br>
+<!--#elif expr="test_condition" --><br>
+<!--#else --><br>
+<!--#endif --></pre>
+</div>
- <p>For example, if you wish to customize the text on your web page
- based on the time of day, you could use the following recipe, placed
- in the HTML page:</p>
+ <p>A <em>test_condition</em> can compare values or test whether a
+ variable is non-empty. See the <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
+ documentation for the full list of comparison operators.</p>
- <div class="example"><p><code>
- Good
- <!--#if expr="%{TIME_HOUR} <12" --><br>
- morning!<br>
- <!--#else --><br>
- afternoon!<br>
- <!--#endif --><br>
- </code></p></div>
+ <p>For example, to display different greetings based on the time
+ of day:</p>
+
+<div class="example"><pre class="prettyprint lang-html">Good
+<!--#if expr="%{TIME_HOUR} <12" --><br>
+morning!<br>
+<!--#else --><br>
+afternoon!<br>
+<!--#endif --><br>
+</pre>
+</div>
- <p>Any other variable (either ones that you define, or normal
- environment variables) can be used in conditional statements.
-
See <a href="../expr.html">Expressions in Apache HTTP Server</a> for
- more information on the expression evaluation engine.</p>
+ <p>Any variable — user-defined or from the environment — can be
+ used in conditional expressions. See
+ <a href="../expr.html">Expressions in Apache HTTP Server</a> for
+ full details on the expression evaluation engine.</p>
- <p>With Apache's ability to set environment variables with the
- <code>SetEnvIf</code> directives, and other related directives,
- this functionality can let you do a wide variety of dynamic content
- on the server side without resorting a full web application.</p>
+ <p>Combined with httpd's ability to set environment variables
+ using <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> and
+ related directives, conditional SSI can handle a wide variety of
+ dynamic content scenarios without a full application
+ framework.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div>
<div class="section">
<h2 id="conclusion">Conclusion <a title="Permanent link" href="#conclusion" class="permalink">¶</a></h2>
- <p>SSI is certainly not a replacement for CGI, or other
- technologies used for generating dynamic web pages. But it is a
- great way to add small amounts of dynamic content to pages,
- without doing a lot of extra work.</p>
+ <p>For sites that are mostly static but need a few dynamic
+ touches, SSI avoids the overhead of setting up a full
+ application stack. It requires only <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
+ and a few lines of configuration to get started.</p>
</div></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/howto/ssi.html" title="English"> en </a> |
<a href="../ja/howto/ssi.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
<a href="../ko/howto/ssi.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
</div>
+<div class="outofdate">Esta traducción podría estar
+ obsoleta. Consulte la versión en inglés de la
+ documentación para comprobar si se han producido cambios
+ recientemente.</div>
<p>Los Server Side Includes (Inclusiones en la parte Servidor) facilitan un método para añadir contenido dinámico a documentos HTML existentes.</p>
</div>
<a href="../ja/howto/ssi.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
<a href="../ko/howto/ssi.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
</div>
+<div class="outofdate">Cette traduction peut être périmée. Vérifiez la version
+ anglaise pour les changements récents.</div>
<p>Les SSI permettent d'ajouter du contenu dynamique à des documents
HTML préexistants.</p>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.es.xsl"?>
-<!-- English revision: 1786682 -->
+<!-- English Revision: 1786682:1935522 (outdated) -->
<!-- Spanish Translation: Daniel Ferradal <dferradal@apache.org> -->
<!--
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1786682 -->
+<!-- English Revision: 1786682:1935522 (outdated) -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 659902:1786682 (outdated) -->
+<!-- English Revision: 659902:1935522 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version='1.0' encoding='EUC-KR' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ko.xsl"?>
-<!-- English Revision: 659902:1786682 (outdated) -->
+<!-- English Revision: 659902:1935522 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<variants>
<variant>en</variant>
- <variant>es</variant>
- <variant>fr</variant>
+ <variant outdated="yes">es</variant>
+ <variant outdated="yes">fr</variant>
<variant outdated="yes">ja</variant>
<variant outdated="yes">ko</variant>
</variants>
projects / thirdparty / apache / httpd.git / commitdiff
