install/unix/apache2.xml
e51792efe0f103ec8724ad199524d7543610c978
...
...
@@ -1,359 +1,366 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<sect1 xml:id="install.unix.apache2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
-
<title>Apache 2.x on Unix systems</title>
5
-
<para>
6
-
This section contains notes and hints specific to Apache 2.x installs
7
-
of PHP on Unix systems.
8
-
</para>
3
+
<sect1 xml:id="install.unix.apache2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
+
<title>Apache 2.x on Unix systems</title>
9
5

10
-
&warn.apache2.compat;
6
+
<para>
7
+
This section contains notes and hints specific to Apache 2.x installs
8
+
of PHP on Unix systems.
9
+
</para>
11
10
12
-
<para>
13
-
The <link xlink:href="&url.apache2.docs;">Apache Documentation</link>
14
-
is the most authoritative source of information on the Apache 2.x server.
15
-
More information about installation options for Apache may be found
16
-
there.
17
-
</para>
11
+
&warn.apache2.compat;
18
12
19
-
<para>
20
-
The most recent version of Apache HTTP Server may be obtained from
21
-
<link xlink:href="&url.apache;">Apache download site</link>,
22
-
and a fitting PHP version from the above mentioned places.
23
-
This quick guide covers only the basics to get started with Apache 2.x
24
-
and PHP. For more information read the
25
-
<link xlink:href="&url.apache2.docs;">Apache Documentation</link>.
26
-
The version numbers have been omitted here, to ensure the
27
-
instructions are not incorrect. In the examples below, 'NN' should be
28
-
replaced with the specific version of Apache being used.
29
-
</para>
13
+
<para>
14
+
The <link xlink:href="&url.apache2.docs;">Apache Documentation</link>
15
+
is the most authoritative source of information on the Apache 2.x server.
16
+
More information about installation options for Apache may be found
17
+
there.
18
+
</para>
30
19

31
-
<para>
32
-
There are currently two versions of Apache 2.x - there's 2.0 and 2.2.
33
-
While there are various reasons for choosing each, 2.2 is the current
34
-
latest version, and the one that is recommended, if that option is
35
-
available to you. However, the instructions here will work for either
36
-
2.0 or 2.2.
37
-
</para>
20
+
<para>
21
+
The most recent version of Apache HTTP Server may be obtained from
22
+
<link xlink:href="&url.apache;">Apache download site</link>,
23
+
and a fitting PHP version from the above mentioned places.
24
+
This quick guide covers only the basics to get started with Apache 2.x
25
+
and PHP. For more information read the
26
+
<link xlink:href="&url.apache2.docs;">Apache Documentation</link>.
27
+
The version numbers have been omitted here, to ensure the
28
+
instructions are not incorrect. In the examples below, 'NN' should be
29
+
replaced with the specific version of Apache being used.
30
+
</para>
31
+

32
+
<para>
33
+
There are currently two versions of Apache 2.x - there's 2.4 and 2.2.
34
+
While there are various reasons for choosing each, 2.4 is the current
35
+
latest version, and the one that is recommended, if that option is
36
+
available to you. However, the instructions here will work for either
37
+
2.4 or 2.2. Note that Apache httpd 2.2 is officially End Of Life,
38
+
and no new development or patches are being issued for it.
39
+
</para>
38
40

39
-
<orderedlist>
40
-
<listitem>
41
-
<para>Obtain the Apache HTTP server from the location listed above,
42
-
and unpack it:</para>
41
+
<orderedlist>
42
+
<listitem>
43
+
<para>
44
+
Obtain the Apache HTTP server from the location listed above,
45
+
and unpack it:
46
+
</para>
43
47

44
-
<informalexample>
45
-
<screen>
48
+
<informalexample>
49
+
<screen>
46
50
<![CDATA[
47
-
gzip -d httpd-2_x_NN.tar.gz
48
-
tar -xf httpd-2_x_NN.tar
51
+
tar -xzf httpd-2.x.NN.tar.gz
49
52
]]>
50
-
</screen>
51
-
</informalexample>
52
-
</listitem>
53
+
</screen>
54
+
</informalexample>
55
+
</listitem>
53
56

54
-
<listitem>
55
-
<para>Likewise, obtain and unpack the PHP source:</para>
57
+
<listitem>
58
+
<para>
59
+
Likewise, obtain and unpack the PHP source:
60
+
</para>
56
61

57
-
<informalexample>
58
-
<screen>
62
+
<informalexample>
63
+
<screen>
59
64
<![CDATA[
60
-
gunzip php-NN.tar.gz
61
-
tar -xf php-NN.tar
65
+
tar -xzf php-NN.tar.gz
62
66
]]>
63
-
</screen>
64
-
</informalexample>
65
-
</listitem>
67
+
</screen>
68
+
</informalexample>
69
+
</listitem>
66
70
67
-
<listitem>
68
-
<para>
69
-
Build and install Apache. Consult the Apache install documentation for
70
-
more details on building Apache.
71
-
</para>
71
+
<listitem>
72
+
<para>
73
+
Build and install Apache. Consult the Apache install documentation for
74
+
more details on building Apache.
75
+
</para>
72
76

73
-
<informalexample>
74
-
<screen>
77
+
<informalexample>
78
+
<screen>
75
79
<![CDATA[
76
80
cd httpd-2_x_NN
77
81
./configure --enable-so
78
82
make
79
83
make install
80
84
]]>
81
-
</screen>
82
-
</informalexample>
83
-
</listitem>
85
+
</screen>
86
+
</informalexample>
87
+
</listitem>
84
88

85
-
<listitem>
86
-
<para>
89
+
<listitem>
90
+
<para>
87
91
Now you have Apache 2.x.NN available under /usr/local/apache2,
88
92
configured with loadable module support and the standard MPM prefork.
89
93
To test the installation use your normal procedure for starting
90
94
the Apache server, e.g.:
91
95

92
96
<informalexample>
93
-
<screen>
97
+
<screen>
94
98
<![CDATA[
95
99
/usr/local/apache2/bin/apachectl start
96
100
]]>
97
-
</screen>
101
+
</screen>
98
102
</informalexample>
99
103

100
104
and stop the server to go on with the configuration for PHP:
101
105

102
106
<informalexample>
103
-
<screen>
107
+
<screen>
104
108
<![CDATA[
105
109
/usr/local/apache2/bin/apachectl stop
106
110
]]>
107
-
</screen>
111
+
</screen>
108
112
</informalexample>
109
-
</para>
110
-
</listitem>
111
-

112
-
<listitem>
113
-

114
-
<para>
115
-
Now, configure and build PHP. This is where you customize PHP
116
-
with various options, like which extensions will be enabled. Run
117
-
./configure --help for a list of available options. In our example
118
-
we'll do a simple configure with Apache 2 and MySQL support.
119
-
</para>
120
-

121
-
<para>
122
-
If you built Apache from source, as described above, the below example will
123
-
match your path for apxs, but if you installed Apache some other way, you'll
124
-
need to adjust the path to apxs accordingly. Note that some distros may rename
125
-
apxs to apxs2.
126
-
</para>
127
-
<informalexample>
128
-
<screen>
113
+
</para>
114
+
</listitem>
115
+

116
+
<listitem>
117
+
<para>
118
+
Now, configure and build PHP. This is where you customize PHP
119
+
with various options, like which extensions will be enabled. Run
120
+
<command>./configure --help</command> for a list of available options. In our example
121
+
we'll do a simple configure with Apache 2 and MySQL support.
122
+
</para>
123
+

124
+
<para>
125
+
If you built Apache from source, as described above, the below example will
126
+
match your path for <command>apxs</command>, but if you installed Apache some other way, you'll
127
+
need to adjust the path to <command>apxs</command> accordingly. Note that some distros may rename
128
+
<command>apxs</command> to <command>apxs2</command>.
129
+
</para>
130
+

131
+
<informalexample>
132
+
<screen>
129
133
<![CDATA[
130
134
cd ../php-NN
131
-
./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql
135
+
./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-pdo-mysql
132
136
make
133
137
make install
134
138
]]>
135
-
</screen>
136
-
</informalexample>
139
+
</screen>
140
+
</informalexample>
137
141

138
-
<para>
142
+
<para>
139
143
If you decide to change your configure options after installation,
140
-
you'll need to re-run the configure, make, and make install steps.
141
-
You only need to
142
-
restart apache for the new module to take effect. A recompile of
143
-
Apache is not needed.
144
-
</para>
145
-
146
-
<para>
147
-
Note that unless told otherwise, 'make install' will also install PEAR,
148
-
various PHP tools such as phpize, install the PHP CLI, and more.
149
-
</para>
144
+
you'll need to re-run the <command>configure</command>, <command>make</command>,
145
+
and <command>make install</command> steps.
146
+
You only need to restart apache for the new module to take effect.
147
+
A recompile of Apache is not needed.
148
+
</para>
150
149
151
-
</listitem>
150
+
<para>
151
+
Note that unless told otherwise, <command>make install</command> will also install
152
+
<link xlink:href="&url.php.pear;">PEAR</link>,
153
+
various PHP tools such as <link linkend="install.pecl.phpize">phpize</link>,
154
+
install the PHP CLI, and more.
155
+
</para>
156
+
</listitem>
152
157

153
158
<listitem>
154
-
<para>
155
-
Setup your php.ini
156
-
</para>
159
+
<para>
160
+
Setup your <filename>php.ini</filename>.
161
+
</para>
157
162
158
-
<informalexample>
159
-
<screen>
163
+
<informalexample>
164
+
<screen>
160
165
<![CDATA[
161
166
cp php.ini-development /usr/local/lib/php.ini
162
167
]]>
163
-
</screen>
164
-
</informalexample>
168
+
</screen>
169
+
</informalexample>
165
170

166
-
<para>
167
-
You may edit your .ini file to set PHP options. If you prefer having
168
-
php.ini in another location, use --with-config-file-path=/some/path in
169
-
step 5.
170
-
</para>
171
+
<para>
172
+
You may edit your <literal>.ini</literal> file to set PHP options. If you prefer having
173
+
<filename>php.ini</filename> in another location,
174
+
use <literal>--with-config-file-path=/some/path</literal> in step 5.
175
+
</para>
171
176
172
-
<para>
173
-
If you instead choose php.ini-production, be certain to read the list
177
+
<para>
178
+
If you instead choose <filename>php.ini-production</filename>, be certain to read the list
174
179
of changes within, as they affect how PHP behaves.
175
-
</para>
176
-

177
-
</listitem>
178
-

179
-
<listitem>
180
+
</para>
181
+
</listitem>
180
182

181
-
<para>
182
-
Edit your httpd.conf to load the PHP module. The path on the right hand
183
-
side of the LoadModule statement must point to the path of the PHP
184
-
module on your system. The make install from above may have already
183
+
<listitem>
184
+
<para>
185
+
Edit your <filename>httpd.conf</filename> to load the PHP module. The path on the right hand
186
+
side of the <literal>LoadModule</literal> statement must point to the path of the PHP
187
+
module on your system. The <command>make install</command> from above may have already
185
188
added this for you, but be sure to check.
186
-
</para>
189
+
</para>
187
190

188
-
<informalexample>
189
-
<para>
190
-
For PHP 7:
191
-
</para>
192
-
<programlisting role="apache-conf">
193
-
<![CDATA[
194
-
LoadModule php7_module modules/libphp7.so
195
-
]]>
196
-
</programlisting>
197
-
</informalexample>
198
-

199
-
<informalexample>
200
-
<para>
201
-
For PHP 5:
202
-
</para>
203
-
<programlisting role="apache-conf">
191
+
<informalexample>
192
+
<para>
193
+
For PHP 8:
194
+
</para>
195
+

196
+
<programlisting role="apache-conf">
204
197
<![CDATA[
205
-
LoadModule php5_module modules/libphp5.so
198
+
LoadModule php_module modules/libphp.so
206
199
]]>
207
-
</programlisting>
208
-
</informalexample>
200
+
</programlisting>
201
+
</informalexample>
209
202

210
-
</listitem>
203
+
<informalexample>
204
+
<para>
205
+
For PHP 7:
206
+
</para>
211
207

212
-
<listitem>
208
+
<programlisting role="apache-conf">
209
+
<![CDATA[
210
+
LoadModule php7_module modules/libphp7.so
211
+
]]>
212
+
</programlisting>
213
+
</informalexample>
214
+
</listitem>
213
215

214
-
<para>
215
-
Tell Apache to parse certain extensions as PHP. For example, let's have
216
-
Apache parse .php files as PHP. Instead of only using the Apache AddType
216
+
<listitem>
217
+
<para>
218
+
Tell Apache to parse certain extensions as PHP. For example, let's have
219
+
Apache parse <literal>.php</literal> files as PHP. Instead of only using the Apache <literal>AddType</literal>
217
220
directive, we want to avoid potentially dangerous uploads and created
218
-
files such as exploit.php.jpg from being executed as PHP. Using this
221
+
files such as <filename>exploit.php.jpg</filename> from being executed as PHP. Using this
219
222
example, you could have any extension(s) parse as PHP by simply adding
220
-
them. We'll add .php to demonstrate.
221
-
</para>
222
-

223
+
them. We'll add <literal>.php</literal> to demonstrate.
224
+
</para>
223
225

224
-
<informalexample>
225
-
<programlisting role="apache-conf">
226
+
<informalexample>
227
+
<programlisting role="apache-conf">
226
228
<![CDATA[
227
229
<FilesMatch \.php$>
228
230
SetHandler application/x-httpd-php
229
231
</FilesMatch>
230
232
]]>
231
-
</programlisting>
232
-
</informalexample>
233
+
</programlisting>
234
+
</informalexample>
233
235

234
-
<para>
235
-
Or, if we wanted to allow .php, .php2, .php3, .php4, .php5, .php6, and
236
-
.phtml files to be executed as PHP, but nothing else, we'd use this:
237
-
</para>
236
+
<para>
237
+
Or, if we wanted to allow <literal>.php</literal>, <literal>.php2</literal>,
238
+
<literal>.php3</literal>, <literal>.php4</literal>, <literal>.php5</literal>,
239
+
<literal>.php6</literal>, and <literal>.phtml</literal> files to be
240
+
executed as PHP, but nothing else, we'd use this:
241
+
</para>
238
242

239
-
<informalexample>
240
-
<programlisting role="apache-conf">
243
+
<informalexample>
244
+
<programlisting role="apache-conf">
241
245
<![CDATA[
242
246
<FilesMatch "\.ph(p[2-6]?|tml)$">
243
247
SetHandler application/x-httpd-php
244
248
</FilesMatch>
245
249
]]>
246
-
</programlisting>
247
-
</informalexample>
250
+
</programlisting>
251
+
</informalexample>
248
252

249
-
<para>
250
-
And to allow .phps files to be handled by the php source filter, and
253
+
<para>
254
+
And to allow <literal>.phps</literal> files to be handled by the php source filter, and
251
255
displayed as syntax-highlighted source code, use this:
252
-
</para>
256
+
</para>
253
257

254
-
<informalexample>
255
-
<programlisting role="apache-conf">
258
+
<informalexample>
259
+
<programlisting role="apache-conf">
256
260
<![CDATA[
257
261
<FilesMatch "\.phps$">
258
262
SetHandler application/x-httpd-php-source
259
263
</FilesMatch>
260
264
]]>
261
-
</programlisting>
262
-
</informalexample>
265
+
</programlisting>
266
+
</informalexample>
263
267

264
-
<para>
265
-
mod_rewrite may be used To allow any arbitrary .php file to be displayed
268
+
<para>
269
+
<literal>mod_rewrite</literal> may be used to allow any arbitrary <literal>.php</literal> file to be displayed
266
270
as syntax-highlighted source code, without having to rename or copy it
267
-
to a .phps file:
271
+
to a <literal>.phps</literal> file:
268
272
</para>
269
273

270
-
<informalexample>
271
-
<programlisting role="apache-conf">
274
+
<informalexample>
275
+
<programlisting role="apache-conf">
272
276
<![CDATA[
273
277
RewriteEngine On
274
278
RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]
275
279
]]>
276
-
</programlisting>
277
-
</informalexample>
280
+
</programlisting>
281
+
</informalexample>
278
282

279
-
<para>
283
+
<para>
280
284
The php source filter should not be enabled on production systems, where
281
285
it may expose confidential or otherwise sensitive information embedded in
282
286
source code.
283
-
</para>
284
-

285
-
</listitem>
287
+
</para>
288
+
</listitem>
286
289

287
-
<listitem>
290
+
<listitem>
288
291
<para>
289
-
Use your normal procedure for starting the Apache server, e.g.:
292
+
Use your normal procedure for starting the Apache server, e.g.:
290
293
</para>
291
294
292
295
<informalexample>
293
-
<screen>
296
+
<screen>
294
297
<![CDATA[
295
298
/usr/local/apache2/bin/apachectl start
296
299
]]>
297
-
</screen>
298
-
</informalexample>
300
+
</screen>
301
+
</informalexample>
299
302

300
-
<para>OR</para>
303
+
<para>OR</para>
301
304

302
305
<informalexample>
303
-
<screen>
306
+
<screen>
304
307
<![CDATA[
305
308
service httpd restart
306
309
]]>
307
-
</screen>
308
-
</informalexample>
310
+
</screen>
311
+
</informalexample>
312
+
</listitem>
313
+
</orderedlist>
309
314

310
-
</listitem>
311
-
</orderedlist>
315
+
<para>
316
+
Following the steps above you will have a running Apache2 web server with
317
+
support for PHP as a <literal>SAPI</literal> module. Of course, there are
318
+
many more configuration options available for Apache and PHP. For more
319
+
information type <command>./configure --help</command> in the corresponding
320
+
source tree.
321
+
</para>
312
322

313
-
<para>
314
-
Following the steps above you will have a running Apache2 web server with
315
-
support for PHP as a <literal>SAPI</literal> module. Of course there are
316
-
many more configuration options available Apache and PHP. For more
317
-
information type <command>./configure --help</command> in the corresponding
318
-
source tree.
319
-
</para>
320
-
<para>
321
-
Apache may be built multithreaded by selecting the
322
-
<filename>worker</filename> MPM, rather than the standard
323
-
<filename>prefork</filename> MPM, when Apache is built. This is done by
324
-
adding the following option to the argument passed to ./configure, in
325
-
step 3 above:
326
-
</para>
327
-
<informalexample>
328
-
<screen>
323
+
<para>
324
+
Apache may be built multithreaded by selecting the
325
+
<filename>worker</filename> MPM, rather than the standard
326
+
<filename>prefork</filename> MPM, when Apache is built. This is done by
327
+
adding the following option to the argument passed to <command>./configure</command>, in
328
+
step 3 above:
329
+
</para>
330
+

331
+
<informalexample>
332
+
<screen>
329
333
<![CDATA[
330
334
--with-mpm=worker
331
335
]]>
332
-
</screen>
333
-
</informalexample>
334
-
<para>
335
-
This should not be undertaken without being aware of the consequences of
336
-
this decision, and having at least a fair understanding of
337
-
the implications. The Apache documentation
338
-
regarding <link xlink:href="&url.apache2.mpm;">MPM-Modules</link>
339
-
discusses MPMs in a great deal more detail.
340
-
</para>
341
-
<note>
342
-
<para>
343
-
The <link linkend="faq.installation.apache.multiviews">Apache MultiViews
344
-
FAQ</link> discusses using multiviews with PHP.
345
-
</para>
346
-
</note>
347
-
<note>
348
-
<para>
349
-
To build a multithreaded version of Apache, the target system must support threads.
350
-
In this case, PHP should also be built with experimental
351
-
Zend Thread Safety (ZTS). Under this configuration, not all extensions will be available.
352
-
The recommended setup is to build Apache with the default
353
-
<filename>prefork</filename> MPM-Module.
354
-
</para>
355
-
</note>
356
-
</sect1>
336
+
</screen>
337
+
</informalexample>
338
+

339
+
<para>
340
+
This should not be undertaken without being aware of the consequences of
341
+
this decision, and having at least a fair understanding of
342
+
the implications. The Apache documentation
343
+
regarding <link xlink:href="&url.apache2.mpm;">MPM-Modules</link>
344
+
discusses MPMs in a great deal more detail.
345
+
</para>
346
+

347
+
<note>
348
+
<para>
349
+
The <link linkend="faq.installation.apache.multiviews">Apache MultiViews
350
+
FAQ</link> discusses using multiviews with PHP.
351
+
</para>
352
+
</note>
353
+

354
+
<note>
355
+
<para>
356
+
To build a multithreaded version of Apache, the target system must support threads.
357
+
In this case, PHP should also be built with
358
+
Zend Thread Safety (ZTS). Under this configuration, not all extensions will be available.
359
+
The recommended setup is to build Apache with the default
360
+
<filename>prefork</filename> MPM-Module.
361
+
</para>
362
+
</note>
363
+
</sect1>
357
364

358
365
<!-- Keep this comment at the end of the file
359
366
Local variables:
360
367



Translation status