Mercurial > hg > nginx-site

comparison xml/it/docs/beginners_guide.xml @ 1018:19129672444e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added italian translation. Grazie a Angelo Papadia <angelo.papadia@gmail.com>!
author Vladimir Homutov <vl@nginx.com>
date Wed, 20 Nov 2013 14:36:40 +0400
parents
children 6303d4e343a8
comparison
equal deleted inserted replaced
1017:9f9a427a73eb 1018:19129672444e
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>&mdash;arresto rapido
68 </listitem>
69 <listitem>
70 <literal>quit</literal>&mdash;arresto controllato
71 </listitem>
72 <listitem>
73 <literal>reload</literal>&mdash;ricaricamento della configurazione
74 </listitem>
75 <listitem>
76 <literal>reopen</literal>&mdash;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>