1018
|
1 <!--
|
|
2 Copyright (C) Nginx, Inc.
|
|
3 -->
|
|
4
|
|
5 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd">
|
|
6
|
|
7 <article name="Guida per il principiante"
|
|
8 link="/it/docs/beginners_guide.html"
|
|
9 lang="it"
|
|
10 translator="Angelo Papadia"
|
|
11 rev="1">
|
|
12
|
|
13 <section>
|
|
14
|
|
15 <para>
|
|
16 La presente guida fornisce una introduzione a nginx e descrive alcune
|
|
17 semplici funzionalità per il quale può essere utilizzato.
|
|
18 Nel seguito si presuppone che nginx sia gia' stato installato;
|
|
19 in caso contrario fare riferimento alla pagina
|
|
20 <link doc="install.xml"/>.
|
|
21 La presente guida spiega come avviare, come fermare e come ricaricare
|
|
22 la configurazione di nginx, descrive brevemente la struttura del file
|
|
23 di configurazione, spiega come configurare nginx per servire contenuti statici,
|
|
24 come configurarlo per l'uso come proxy server,
|
|
25 e come configurarlo per l'uso con un'applicazione FastCGI.
|
|
26 </para>
|
|
27
|
|
28 <para>
|
|
29 nginx ha un processo master e numerosi processi worker:
|
|
30 lo scopo principale del processo master e' leggere e interpretare la configurazione,
|
|
31 e mantenere i processi worker attivi;
|
|
32 a loro volta, i processi worker si occupano di gestire effettivamente le richieste.
|
|
33 nginx utilizza un modello event-based e meccanismi dipendenti dal sistema operativo
|
|
34 per distribuire con efficienza le richieste fra i processi worker.
|
|
35 Il numero di processi worker e' definito nel file di configurazione,
|
|
36 e puo' sia essere fisso,
|
|
37 sia essere regolato automaticamente in base al numero di core CPU disponibili
|
|
38 (vedere <link doc="ngx_core_module.xml" id="worker_processes"/>).
|
|
39 </para>
|
|
40
|
|
41 <para>
|
|
42 La maniera in cui nginx e i suoi moduli lavorano e' determinata nel file di configurazione;
|
|
43 per default, tale file si chiama
|
|
44 <path>nginx.conf</path>
|
|
45 e si trova in una delle directory:
|
|
46 <path>/usr/local/nginx/conf</path> ,
|
|
47 <path>/etc/nginx</path> ,
|
|
48 <path>/usr/local/etc/nginx</path> .
|
|
49 </para>
|
|
50
|
|
51 </section>
|
|
52
|
|
53
|
|
54 <section id="control" name="Avvio, arresto e ricaricamento della configurazione">
|
|
55
|
|
56 <para>
|
|
57 Per far partire nginx, avviare il file eseguibile.
|
|
58 Una volta partito, nginx puo' essere controllato invocando l'eseguibile con il parametro
|
|
59 <literal>-s</literal> .
|
|
60 Usare la seguente sintassi:
|
|
61 <programlisting>
|
|
62 nginx -s <i>signal</i>
|
|
63 </programlisting>
|
|
64 Dove <i>signal</i> e' uno dei seguenti:
|
|
65 <list type="bullet">
|
|
66 <listitem>
|
|
67 <literal>stop</literal>—arresto rapido
|
|
68 </listitem>
|
|
69 <listitem>
|
|
70 <literal>quit</literal>—arresto controllato
|
|
71 </listitem>
|
|
72 <listitem>
|
|
73 <literal>reload</literal>—ricaricamento della configurazione
|
|
74 </listitem>
|
|
75 <listitem>
|
|
76 <literal>reopen</literal>—riapertura del file di log
|
|
77 </listitem>
|
|
78 </list>
|
|
79 Ad esempio, per fermare il processo nginx ma attendendo che finisca di servire
|
|
80 le richieste correnti, va eseguito il seguente comando:
|
|
81 <programlisting>
|
|
82 nginx -s quit
|
|
83 </programlisting>
|
|
84 <note>Questo comando dovrebbe essere eseguito dallo stesso utente che ha avviato nginx.</note>
|
|
85 </para>
|
|
86
|
|
87 <para>
|
|
88 Le modifiche al file di configurazione non saranno applicate sinche'
|
|
89 nginx non e' riavviato o non riceve il comando di ricaricamento della configurazione.
|
|
90 Per ricaricare la configurazione, eseguire:
|
|
91 <programlisting>
|
|
92 nginx -s reload
|
|
93 </programlisting>
|
|
94 </para>
|
|
95
|
|
96 <para>
|
|
97 Quando il processo master riceve il segnale di ricaricamento della configurazione,
|
|
98 verifica la validita' sintattica e tenta di applicare la configurazione riportata nel relativo file.
|
|
99 Se ha successo, il processo master avvia nuovi processi worker e invia messaggi di chiusura a quelli vecchi,
|
|
100 che smettono di accettare nuove connessioni ma continuano a servire le richieste correnti sinche' non sono
|
|
101 state del tutto completate, dopo di che terminano.
|
|
102 Se la nuova configurazione non risulta corretta, oppure se non e' possibile applicarla,
|
|
103 il processo master continua a lavorare con la configurazione precedente.
|
|
104 </para>
|
|
105
|
|
106 <para>
|
|
107 E' anche possibile inviare un segnale ai processi nginx tramite i normali comandi Unix,
|
|
108 quale ad esempio <command>kill</command>, che invia un segnale al processo individuato tramite il relativo ID;
|
|
109 per default, l'ID del processo master di nginx e' scritto nel file <path>nginx.pid</path>
|
|
110 nella directory
|
|
111 <path>/usr/local/nginx/logs</path> oppure
|
|
112 <path>/var/run</path> .
|
|
113 Ad esempio, se l'ID del processo master e' 1628, per inviare il segnale QUIT,
|
|
114 che causa l'arresto controllato, bisogna eseguire il comando:
|
|
115 <programlisting>
|
|
116 kill -s QUIT 1628
|
|
117 </programlisting>
|
|
118 Per ottenere la lista di tutti in processi nginx, e' possibile usare vari comandi,
|
|
119 fra cui ad esempio <command>ps</command>
|
|
120 nella maniera seguente:
|
|
121 <programlisting>
|
|
122 ps -ax | grep nginx
|
|
123 </programlisting>
|
|
124 Per ulteriori informazioni su come inviare segnali a ngnix, fare riferimento a
|
|
125 <link doc="control.xml"/>.
|
|
126 </para>
|
|
127
|
|
128 </section>
|
|
129
|
|
130
|
|
131 <section id="conf_structure" name="Struttura del file di configurazione">
|
|
132
|
|
133 <para>
|
|
134 nginx e' costituito da moduli che sono controllati da direttiva specificate
|
|
135 nel file di configurazione.
|
|
136 Le direttive possono essere semplici o a blocco.
|
|
137 Una direttiva semplice e' caratterizzata dal nome seguito da parametri separati da spazi,
|
|
138 e termina con punto e virgola (<literal>;</literal>).
|
|
139 Una direttiva a blocco ha la stessa struttura di una direttiva semplice,
|
|
140 ma, invece che con punto e virgola, termina con un insieme di istruzioni aggiuntive racchiuse
|
|
141 fra parentesi graffe ( <literal>{</literal> e <literal>}</literal> ).
|
|
142 Una direttiva che puo' avere altre direttive all'interno delle parentesi graffe e' chiamata
|
|
143 contesto (ad esempio:
|
|
144 <link doc="ngx_core_module.xml" id="events"/>,
|
|
145 <link doc="http/ngx_http_core_module.xml" id="http"/>,
|
|
146 <link doc="http/ngx_http_core_module.xml" id="server"/>,
|
|
147 e
|
|
148 <link doc="http/ngx_http_core_module.xml" id="location"/>).
|
|
149 Le direttive del file di configurazione che non sono all'interno di alcun
|
|
150 contesto sono considerate facenti parte del contesto
|
|
151 <link doc="ngx_core_module.xml">main</link>.
|
|
152 </para>
|
|
153
|
|
154 <para>
|
|
155 Le direttive <literal>events</literal> e <literal>http</literal>
|
|
156 appartengono al contesto <literal>main</literal>, la direttiva <literal>server</literal>
|
|
157 al contesto <literal>http</literal>,
|
|
158 la direttiva <literal>location</literal> al contesto <literal>server</literal>.
|
|
159 </para>
|
|
160
|
|
161 <para>
|
|
162 Tutto cio' che in una riga segue il simbolo <literal>#</literal> e' considerato un commento.
|
|
163 </para>
|
|
164
|
|
165 </section>
|
|
166
|
|
167
|
|
168 <section id="static" name="Servizio di contenuti statici">
|
|
169
|
|
170 <para>
|
|
171 Un compito importante di un web server e' costituito dal servizio
|
|
172 di file, quali immagini o pagine HTML statiche.
|
|
173 Di seguito si implementa un esempio in cui, a seconda della richiesta,
|
|
174 i file sono serviti prendendoli da varie directory locali: <path>/data/www</path>
|
|
175 (che puo' contenere file HTML) e <path>/data/images</path>
|
|
176 (che contiene immagini).
|
|
177 Per tale implementazione e' necessaria la modifica del file di configurazione,
|
|
178 con l'aggiunta,
|
|
179 all'interno di un blocco <link doc="http/ngx_http_core_module.xml" id="http"/>,
|
|
180 di un blocco <link doc="http/ngx_http_core_module.xml" id="server"/>
|
|
181 a sua volta contenente due blocchi <link doc="http/ngx_http_core_module.xml" id="location"/>.
|
|
182 </para>
|
|
183
|
|
184 <para>
|
|
185 Anzitutto, creare le directory <path>/data/www</path> e <path>/data/images</path>,
|
|
186 e aggiungere nella prima un file <path>index.html</path> contenente un testo qualsiasi,
|
|
187 nella seconda una immagine a caso.
|
|
188 </para>
|
|
189
|
|
190 <para>
|
|
191 Quindi, aprire il file di configurazione;
|
|
192 si puo' notare che contiene gia' diversi esempi di blocchi <literal>server</literal>,
|
|
193 per la maggior parte inattivati da commenti;
|
|
194 inattivare con commenti tutto il blocco <literal>http</literal>, e scriverne uno nuovo:
|
|
195 <programlisting>
|
|
196 http {
|
|
197 server {
|
|
198 }
|
|
199 }
|
|
200 </programlisting>
|
|
201 In generale, il file di configurazione puo' includere numerosi blocchi <literal>server</literal>,
|
|
202 <link doc="http/request_processing.xml">distinti</link> in base alla porta su cui
|
|
203 sono in <link doc="http/ngx_http_core_module.xml" id="listen">ascolto</link> e al
|
|
204 <link doc="http/server_names.xml">nome del server</link>.
|
|
205 Una volta che nginx ha deciso quale <literal>server</literal> deve processare una data richiesta,
|
|
206 confronta l'URI presente nell'header della stessa con i parametri delle direttive
|
|
207 <literal>location</literal> definite all'interno del blocco <literal>server</literal>.
|
|
208 </para>
|
|
209
|
|
210 <para>
|
|
211 Aggiungere il seguente blocco <literal>location</literal>
|
|
212 al blocco <literal>server</literal>:
|
|
213 <programlisting>
|
|
214 location / {
|
|
215 root /data/www;
|
|
216 }
|
|
217 </programlisting>
|
|
218 Questo blocco <literal>location</literal> fa riferimento al prefisso “<literal>/</literal>”,
|
|
219 da confrontare con l'URI della richiesta:
|
|
220 se la richiesta corrisponde, l'URI viene aggiunto al path specificato dalla
|
|
221 direttiva <link doc="http/ngx_http_core_module.xml" id="root"/>,
|
|
222 in questo caso cioe' a <path>/data/www</path> ,
|
|
223 per definire sul file system locale il path al file richiesto.
|
|
224 Se i blocchi <literal>location</literal> che corrispondono sono piu' di uno,
|
|
225 nginx seleziona quello con il prefisso piu' lungo;
|
|
226 il blocco <literal>location</literal> dell'esempio riguarda il prefisso
|
|
227 piu' breve in assoluto, di lunghezza uno, quindi e' effettivamente usato
|
|
228 solo se tutti gli altri blocchi <literal>location</literal> non corrispondono.
|
|
229 </para>
|
|
230
|
|
231 <para>
|
|
232 Tornando all'esempio, aggiungere un secondo blocco <literal>location</literal>:
|
|
233 <programlisting>
|
|
234 location /images/ {
|
|
235 root /data;
|
|
236 }
|
|
237 </programlisting>
|
|
238 In questo caso ci sara' corrispondenza con
|
|
239 le richieste che iniziano con <literal>/images/</literal>
|
|
240 (anche <literal>location /</literal> corrisponde alla richiesta,
|
|
241 ma ha un prefisso piu' breve e quindi priorita' inferiore).
|
|
242 La configurazione risultante del blocco <literal>server</literal> risulta quindi:
|
|
243 <programlisting>
|
|
244 server {
|
|
245 location / {
|
|
246 root /data/www;
|
|
247 }
|
|
248
|
|
249 location /images/ {
|
|
250 root /data;
|
|
251 }
|
|
252 }
|
|
253 </programlisting>
|
|
254 Tale configurazione e' effettivamente funzionante,
|
|
255 con il server in ascolto sulla porta standard 80 e accessibile
|
|
256 sulla macchina locale a <literal>http://localhost/</literal> .
|
|
257 In risposta alle richieste di URI che iniziano con <literal>/images/</literal> ,
|
|
258 il server inviera' file presi dalla directory <path>/data/images</path> ;
|
|
259 ad esempio, in risposta ad una richiesta
|
|
260 <literal>http://localhost/images/example.png</literal>
|
|
261 nginx inviera' il file <path>/data/images/example.png</path> .
|
|
262 Se tale file non esiste, nginx inviera' una risposta che indica
|
|
263 l'errore 404.
|
|
264 Richieste di URI che non iniziano con <literal>/images/</literal>
|
|
265 saranno mappate sulla directory <path>/data/www</path> ;
|
|
266 ad esempio, in risposta ad una richiesta
|
|
267 <literal>http://localhost/some/example.html</literal>
|
|
268 nginx inviera' il file <path>/data/www/some/example.html</path> .
|
|
269 </para>
|
|
270
|
|
271 <para>
|
|
272 Per applicare la nuova configurazione, avviare nginx se e' spento;
|
|
273 se e' gia' attivo, inviare il segnale <literal>reload</literal> al processo master,
|
|
274 eseguendo:
|
|
275 <programlisting>
|
|
276 nginx -s reload
|
|
277 </programlisting>
|
|
278 </para>
|
|
279
|
|
280 <para>
|
|
281 <note>
|
|
282 Nel caso in cui qualcosa non vada come atteso, e' possibile cercare
|
|
283 di capire cosa e' successo verificandolo nei file <path>access.log</path> e
|
|
284 <path>error.log</path>, presenti nella directory <path>/usr/local/nginx/logs</path> o
|
|
285 <path>/var/log/nginx</path> .
|
|
286 </note>
|
|
287 </para>
|
|
288
|
|
289 </section>
|
|
290
|
|
291
|
|
292 <section id="proxy" name="Configurare un semplice proxy server">
|
|
293
|
|
294 <para>
|
|
295 Uno degli usi piu' frequenti di nginx prevede la configurazione come proxy server,
|
|
296 vale a dire un server che riceve le richieste dai client, le passa ai server remoti,
|
|
297 riceve da essi le risposte, e le reinvia ai client.
|
|
298 </para>
|
|
299
|
|
300 <para>
|
|
301 Di seguito si configura un semplice proxy server, il quale serve le richieste
|
|
302 di immagini con file da una directory locale, e invia invece tutte le altre
|
|
303 richieste a un ulteriore server web.
|
|
304 Nell'esempio, entrambi i server saranno definiti su una singola istanza di nginx..
|
|
305 </para>
|
|
306
|
|
307 <para>
|
|
308 Per iniziare, definire il server web aggiuntivo inserendo nel file di configurazione di
|
|
309 nginx un ulteriore blocco <literal>server</literal> con il contenuto seguente:
|
|
310 <programlisting>
|
|
311 server {
|
|
312 listen 8080;
|
|
313 root /data/up1;
|
|
314
|
|
315 location / {
|
|
316 }
|
|
317 }
|
|
318 </programlisting>
|
|
319 Si tratta di un semplice server in ascolto sulla porta 8080
|
|
320 (in precedenza la direttiva <literal>listen</literal> non e' stata specificata
|
|
321 in quanto e' stata usata la porta standard 80), che mappa tutte le
|
|
322 richieste sulla directory <path>/data/up1</path> del file system locale.
|
|
323 Creare tale directory, e inserire in essa un file <path>index.html</path> .
|
|
324 Notare che la direttiva <literal>root</literal> e' posta nel
|
|
325 contesto <literal>server</literal> ; tale direttiva <literal>root</literal> e' usata
|
|
326 quando il blocco <literal>location</literal> scelto per servire una richiesta
|
|
327 non include una direttiva <literal>root</literal> propria.
|
|
328 </para>
|
|
329
|
|
330 <para>
|
|
331 Procedere usando la configurazione del server della sezione precedente e
|
|
332 modificandola per farne un proxy server.
|
|
333 Nel primo blocco <literal>location</literal>, inserire la direttiva
|
|
334 <link doc="http/ngx_http_proxy_module.xml" id="proxy_pass"/>
|
|
335 specificando come parametro il protocollo, il nome e la porta del server
|
|
336 web aggiuntivo (in questo caso <literal>http://localhost:8080</literal> ):
|
|
337 <programlisting>
|
|
338 server {
|
|
339 location / {
|
|
340 proxy_pass http://localhost:8080;
|
|
341 }
|
|
342
|
|
343 location /images/ {
|
|
344 root /data;
|
|
345 }
|
|
346 }
|
|
347 </programlisting>
|
|
348 </para>
|
|
349
|
|
350 <para>
|
|
351 A questo punto modificare il secondo blocco <literal>location</literal>, che al momento
|
|
352 mappa le richieste con il prefisso <literal>/images/</literal> sui file nella directory
|
|
353 <path>/data/images</path> , per fare in modo che risponda alle richieste con le
|
|
354 tipiche estensioni file delle immagini.
|
|
355 Il blocco <literal>location</literal> sara' il seguente:
|
|
356 <programlisting>
|
|
357 location ~ \.(gif|jpg|png)$ {
|
|
358 root /data/images;
|
|
359 }
|
|
360 </programlisting>
|
|
361 Il parametro e' una espressione regolare che corrisponde a tutti gli URI
|
|
362 che terminano con <path>.gif</path>, <path>.jpg</path>, o <path>.png</path>
|
|
363 (in ngnix le espressioni regolari normalmente iniziano con <literal>~</literal> ).
|
|
364 La richiesta corrispondente sara' mappata sulla directory <path>/data/images</path> .
|
|
365 </para>
|
|
366
|
|
367 <para>
|
|
368 Per decidere quale blocco <literal>location</literal> debba servire una richiesta,
|
|
369 nginx per prima cosa verifica le direttive
|
|
370 <link doc="http/ngx_http_core_module.xml" id="location"/>
|
|
371 che riportano la specifica di un prefisso, registrando quella con il piu' lungo
|
|
372 prefisso che corrisponde, quindi verifica quelle con una espressione regolare;
|
|
373 se c'e' corrispondenza con una espressione regolare, nginx sceglie tale
|
|
374 <literal>location</literal>, altrimenti sceglie quella registrata in precedenza.
|
|
375 </para>
|
|
376
|
|
377 <para>
|
|
378 Alla fine la configurazione risultante di un proxy server e' la seguente:
|
|
379 <programlisting>
|
|
380 server {
|
|
381 location / {
|
|
382 proxy_pass http://localhost:8080/;
|
|
383 }
|
|
384
|
|
385 location ~ \.(gif|jpg|png)$ {
|
|
386 root /data/images;
|
|
387 }
|
|
388 }
|
|
389 </programlisting>
|
|
390 Tale server selezionera' le richieste che terminano in <path>.gif</path>,
|
|
391 <path>.jpg</path> o <path>.png</path> e le mappera' sulla directory
|
|
392 <path>/data/images</path> (aggiungendo l'URI al parametro della direttiva
|
|
393 <literal>root</literal>), mentre invece passera' tutte le altre richieste al web
|
|
394 server configurato in precedenza.
|
|
395 </para>
|
|
396
|
|
397 <para>
|
|
398 Per applicare la nuova configurazione, inviare il segnale <literal>reload</literal>
|
|
399 ad nginx, come descritto nella sezione precedente.
|
|
400 </para>
|
|
401
|
|
402 <para>
|
|
403 Ci sono molte <link doc="http/ngx_http_proxy_module.xml">more</link>
|
|
404 direttive che possono essere usate nella configurazione di un proxy.
|
|
405 </para>
|
|
406
|
|
407 </section>
|
|
408
|
|
409
|
|
410 <section id="fastcgi" name="Configurare il proxying FastCGI">
|
|
411
|
|
412 <para>
|
|
413 nginx puo' essere usato per dirigere le richieste ad uno o piu' server
|
|
414 FastCGI che eseguono applicazioni scritte con vari framework e linguaggi di
|
|
415 programmazione, ad esempio PHP.
|
|
416 </para>
|
|
417
|
|
418 <para>
|
|
419 La configurazione piu' semplice di nginx che consente di lavorare con un server
|
|
420 FastCGI, richiede l'uso della direttiva
|
|
421 <link doc="http/ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>
|
|
422 al posto della direttiva <literal>proxy_pass</literal>,
|
|
423 e della direttiva <link doc="http/ngx_http_fastcgi_module.xml" id="fastcgi_param"/>
|
|
424 per impostare i parametri passati al server FastCGI.
|
|
425 Nel seguito si suppone che il server FastCGI sia accessibile a <literal>localhost:9000</literal> .
|
|
426 Prendendo la configurazione di un proxy nella sezione precedente come base,
|
|
427 sostituire la direttiva <literal>proxy_pass</literal> con la direttiva <literal>fastcgi_pass</literal>
|
|
428 e cambiare il relativo parametro in <literal>localhost:9000</literal> .
|
|
429 Nel caso del PHP, il parametro <literal>SCRIPT_FILENAME</literal> e' usato per determinare
|
|
430 il nome dello script, ed il parametro <literal>QUERY_STRING</literal> e' usato per
|
|
431 passare i parametri della richiesta.
|
|
432 La configurazione risulta quindi:
|
|
433 <programlisting>
|
|
434 server {
|
|
435 location / {
|
|
436 fastcgi_pass localhost:9000;
|
|
437 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
|
|
438 fastcgi_param QUERY_STRING $query_string;
|
|
439 }
|
|
440
|
|
441 location ~ \.(gif|jpg|png)$ {
|
|
442 root /data/images;
|
|
443 }
|
|
444 }
|
|
445 </programlisting>
|
|
446 Tale configurazione realizza un server che inoltra tutte le richieste
|
|
447 (a parte quelle per immagini statiche) tramite il protocollo FastCGI
|
|
448 ad un server esterno che opera su
|
|
449 <literal>localhost:9000</literal> .
|
|
450 </para>
|
|
451
|
|
452 </section>
|
|
453
|
|
454 </article>
|