Mercurial > hg > nginx-site

comparison xml/en/docs/install.xml @ 924:a2aea48ff155

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
New "installation" article. Old "installation" was renamed to "configure" and describes how to build nginx from sources.
author Ruslan Ermilov <ru@nginx.com>
date Fri, 31 May 2013 13:05:51 +0400
parents 65e75e59a714
children b93422ca9fe7
comparison
equal deleted inserted replaced
923:4f1e2120be5e 924:a2aea48ff155
6 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> 6 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd">
7 7
8 <article name="Installing nginx" 8 <article name="Installing nginx"
9 link="/en/docs/install.html" 9 link="/en/docs/install.html"
10 lang="en" 10 lang="en"
11 rev="3"> 11 rev="1"
12 toc="no">
12 13
13 <section> 14 <section>
14 15
15 <para> 16 <para>
16 The build is configured using the <command>configure</command> command. 17 nginx can be installed differently, depending on the operating system.
17 It defines various aspects of the system, including the methods nginx
18 is allowed to use for connection processing.
19 At the end it creates a <path>Makefile</path>.
20 The <command>configure</command> command supports the following parameters:
21 <list type="bullet">
22
23 <listitem>
24 <para>
25 <literal>--prefix=<value>path</value></literal>&mdash;defines
26 a directory that will keep server files.
27 This same directory will also be used for all relative paths set by
28 <command>configure</command> (except for paths to libraries sources)
29 and in the <path>nginx.conf</path> configuration file.
30 It is set to the <path>/usr/local/nginx</path> directory by default.
31 </para>
32 </listitem>
33
34 <listitem>
35 <para>
36 <literal>--sbin-path=<value>path</value></literal>&mdash;sets
37 the name of an nginx executable file.
38 This name is used only during installation.
39 By default the file is named
40 <path><value>prefix</value>/sbin/nginx</path>.
41 </para>
42 </listitem>
43
44 <listitem>
45 <para>
46 <literal>--conf-path=<value>path</value></literal>&mdash;sets
47 the name of an <path>nginx.conf</path> configuration file.
48 If needs be, nginx can always be started with a different configuration file,
49 by specifying it in the command-line parameter
50 <nobr><literal>-c <value>file</value></literal></nobr>.
51 By default the file is named
52 <path><value>prefix</value>/conf/nginx.conf</path>.
53 </para>
54 </listitem>
55
56 <listitem>
57 <para>
58 <literal>--pid-path=<value>path</value></literal>&mdash;sets
59 the name of an nginx.pid file that will store the process ID
60 of the main process.
61 After installation, the file name can always be changed in the
62 <path>nginx.conf</path> configuration file using the
63 <link doc="ngx_core_module.xml" id="pid"/> directive.
64 By default the file is named
65 <path><value>prefix</value>/logs/nginx.pid</path>.
66 </para>
67 </listitem>
68
69 <listitem>
70 <para>
71 <literal>--error-log-path=<value>path</value></literal>&mdash;sets
72 the name of the primary error, warnings, and diagnostic file.
73 After installation, the file name can always be changed in the
74 <path>nginx.conf</path> configuration file using the
75 <link doc="ngx_core_module.xml" id="error_log"/> directive.
76 By default the file is named
77 <path><value>prefix</value>/logs/error.log</path>.
78 </para>
79 </listitem>
80
81 <listitem>
82 <para>
83 <literal>--http-log-path=<value>path</value></literal>&mdash;sets
84 the name of the primary request log file of the HTTP server.
85 After installation, the file name can always be changed in the
86 <path>nginx.conf</path> configuration file using the
87 <link doc="http/ngx_http_log_module.xml" id="access_log"/> directive.
88 By default the file is named
89 <path><value>prefix</value>/logs/access.log</path>.
90 </para>
91 </listitem>
92
93 <listitem>
94 <para>
95 <literal>--user=<value>name</value></literal>&mdash;sets
96 the name of an unprivileged user whose credentials will be used
97 by worker processes.
98 After installation, the name can always be changed in the
99 <path>nginx.conf</path> configuration file using the
100 <link doc="ngx_core_module.xml" id="user"/> directive.
101 The default user name is nobody.
102 </para>
103 </listitem>
104
105 <listitem>
106 <para>
107 <literal>--group=<value>name</value></literal>&mdash;sets
108 the name of a group whose credentials will be used
109 by worker processes.
110 After installation, the name can always be changed in the
111 <path>nginx.conf</path> configuration file using the
112 <link doc="ngx_core_module.xml" id="user"/> directive.
113 By default, a group name is set to the name of an unprivileged user.
114 </para>
115 </listitem>
116
117 <listitem>
118 <para>
119 <literal>--with-select_module</literal><br/>
120 <literal>--without-select_module</literal>&mdash;enables or disables
121 building a module that allows the server to work with the
122 <c-func>select</c-func> method.
123 This module is built automatically if the platform does not appear
124 to support more appropriate methods such as kqueue, epoll, rtsig, or /dev/poll.
125 </para>
126 </listitem>
127
128 <listitem>
129 <para>
130 <literal>--with-poll_module</literal><br/>
131 <literal>--without-poll_module</literal>&mdash;enables or disables
132 building a module that allows the server to work with the
133 <c-func>poll</c-func> method.
134 This module is built automatically if the platform does not appear
135 to support more appropriate methods such as kqueue, epoll, rtsig, or /dev/poll.
136 </para>
137 </listitem>
138
139 <listitem>
140 <para>
141 <literal>--without-http_gzip_module</literal>&mdash;disables building a module
142 that <link doc="http/ngx_http_gzip_module.xml">compresses responses</link>
143 of an HTTP server.
144 The zlib library is required to build and run this module.
145 </para>
146 </listitem>
147
148 <listitem>
149 <para>
150 <literal>--without-http_rewrite_module</literal>&mdash;disables building a
151 module that allows an HTTP server to
152 <link doc="http/ngx_http_rewrite_module.xml">redirect requests and change URI
153 of requests</link>.
154 The PCRE library is required to build and run this module.
155 </para>
156 </listitem>
157
158 <listitem>
159 <para>
160 <literal>--without-http_proxy_module</literal>&mdash;disables building an
161 HTTP server <link doc="http/ngx_http_proxy_module.xml">proxying module</link>.
162 <!--
163 The MD5 library is required to build and run this module.
164 -->
165 </para>
166 </listitem>
167
168 <listitem>
169 <para>
170 <literal>--with-http_ssl_module</literal>&mdash;enables building a module
171 that adds the <link doc="http/ngx_http_ssl_module.xml">HTTPS protocol
172 support</link> to an HTTP server.
173 This module is not built by default.
174 The OpenSSL library is required to build and run this module.
175 </para>
176 </listitem>
177
178 <listitem>
179 <para>
180 <literal>--with-pcre=<value>path</value></literal>&mdash;sets
181 the path to the sources of the PCRE library.
182 The library distribution (version
183 4.4&mdash;8.32) needs to be downloaded from the
184 <link url="http://www.pcre.org">PCRE</link> site and extracted.
185 The rest is done by nginx’s ./configure and make.
186 The library is required for regular expressions support in the
187 <link doc="http/ngx_http_core_module.xml" id="location"/> directive
188 and for the
189 <link doc="http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
190 module.
191 </para>
192 </listitem>
193
194 <listitem>
195 <para>
196 <literal>--with-pcre-jit</literal>&mdash;builds the PCRE library with
197 “just-in-time compilation” support (1.1.12, the
198 <link doc="ngx_core_module.xml" id="pcre_jit"/> directive).
199 </para>
200 </listitem>
201
202 <listitem>
203 <para>
204 <literal>--with-zlib=<value>path</value></literal>&mdash;sets
205 the path to the sources of the zlib library.
206 The library distribution (version
207 1.1.3&mdash;1.2.7) needs to be downloaded from the
208 <link url="http://zlib.net">zlib</link> site and extracted.
209 The rest is done by nginx’s ./configure and make.
210 The library is required for the
211 <link doc="http/ngx_http_gzip_module.xml">ngx_http_gzip_module</link> module.
212 </para>
213 </listitem>
214
215 <listitem>
216 <para>
217 <literal>--with-cc-opt=<value>parameters</value></literal>&mdash;sets
218 additional parameters that will be added to the CFLAGS variable.
219 When using the system PCRE library under FreeBSD,
220 <literal>--with-cc-opt="-I /usr/local/include"</literal>
221 should be specified.
222 If the number of files supported by <c-func>select</c-func> needs to be
223 increased it can also be specified here such as this:
224 <literal>--with-cc-opt="-D FD_SETSIZE=2048"</literal>.
225 </para>
226 </listitem>
227
228 <listitem>
229 <para>
230 <literal>--with-ld-opt=<value>parameters</value></literal>&mdash;sets
231 additional parameters that will be used during linking.
232 When using the system PCRE library under FreeBSD,
233 <literal>--with-ld-opt="-L /usr/local/lib"</literal>
234 should be specified.
235 </para>
236 </listitem>
237
238 </list>
239
240 </para> 18 </para>
241 19
20 </section>
21
22
23 <section id="linux" name="Installation on Linux">
24
242 <para> 25 <para>
243 Example of parameters usage (all of this needs to be typed in one line): 26 For Linux, nginx <link doc="../linux_packages.xml">packages</link>
244 <programlisting> 27 from nginx.org can be used.
245 ./configure 28 </para>
246 --sbin-path=/usr/local/nginx/nginx 29
247 --conf-path=/usr/local/nginx/nginx.conf 30 </section>
248 --pid-path=/usr/local/nginx/nginx.pid 31
249 --with-http_ssl_module 32
250 --with-pcre=../pcre-4.4 33 <section id="freebsd" name="Installation on FreeBSD">
251 --with-zlib=../zlib-1.1.3 34
252 </programlisting> 35 <para>
36 On FreeBSD, nginx can be installed either from the <link
37 url="http://www.freebsd.org/doc/handbook/packages-using.html">packages</link>
38 or through the
39 <link url="http://www.freebsd.org/doc/handbook/ports-using.html">ports</link>
40 system.
41 The ports system provides greater flexibility, allowing selection among
42 a wide range of options.
43 The port will compile nginx with the specified options and install it.
44 </para>
45
46 </section>
47
48
49 <section id="source_install" name="Building from Sources">
50
51 <para>
52 If some special functionality is required, not available with packages and
53 ports, nginx can also be compiled from source files.
54 While more flexible, this approach may be complex for a beginner.
55 For more information, see <link doc="configure.xml"/>.
253 </para> 56 </para>
254 57
255 </section> 58 </section>
256 59
257 </article> 60 </article>