ngx_http_fastcgi_module

ngx_http_fastcgi_module 모듈을 사용하여 FastCGI 서버로 요청을 전달할 수 있습니다.

예제 구성

location / {
    fastcgi_pass  localhost:9000;
    fastcgi_index index.php;

    fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
    fastcgi_param QUERY_STRING    $query_string;
    fastcgi_param REQUEST_METHOD  $request_method;
    fastcgi_param CONTENT_TYPE    $content_type;
    fastcgi_param CONTENT_LENGTH  $content_length;
}

Directives

Syntax:  fastcgi_bind address [transparent] | off;
Default: —
Context: http, server, location
This directive appeared in version 0.8.22.

선택적 포트를 통해 지정된 로컬 IP 주소에서 FastCGI 서버로 나가는 연결을 설정합니다(1.11.2). 매개변수 값은 변수를 포함할 수 있습니다(1.3.12). 특수 값 off(1.3.12)는 이전 구성 수준에서 상속한 fastcgi_bind 명령의 효과를 상쇄하여, 시스템에서 로컬 IP 주소와 포트를 자동으로 할당하도록 합니다.

transparent 매개변수(1.11.0)를 사용하면 외부 IP 주소에서 FastCGI 서버로 나가는 연결을 허용할 수 있습니다. 예를 들어, 클라이언트의 실제 IP 주소를 사용할 수 있습니다.

fastcgi_bind $remote_addr transparent;

이 매개변수가 작동하려면 일반적으로 superuser 권한이 있는 nginx 작업자 프로세스를 실행해야 합니다. Linux에서는 필수가 아닙니다(1.13.8). transparent 매개변수를 지정한 경우, 작업자 프로세스가 마스터 프로세스에서 CAP_NET_RAW 기능을 상속하기 때문입니다. 또한, 커널 라우팅 테이블을 구성하여 FastCGI 서버의 네트워크 트래픽을 가로채야 합니다.

Syntax:  fastcgi_buffer_size size;
Default: fastcgi_buffer_size 4k|8k;
Context: http, server, location

FastCGI 서버에서 수신된 응답을 읽는 데 사용할 버퍼의 size를 설정합니다. 일반적으로 이 부분에는 작은 응답 헤더가 포함됩니다. 기본적으로 버퍼 크기는 메모리 페이지 1개와 같습니다. 플랫폼에 따라 4K 또는 8K가 됩니다. 하지만 크기는 더 줄일 수 있습니다.

Syntax:  fastcgi_buffering on | off;
Default: fastcgi_buffering on;
Context: http, server, location
This directive appeared in version 1.5.6.

FastCGI 서버에서 응답 버퍼링을 활성화하거나 비활성화합니다.

버퍼링을 활성화하면 nginx는 최대한 빠르게 FastCGI 서버에서 응답을 수신하고, fastcgi_buffer_size 및 fastcgi_buffers 명령에서 설정한 버퍼에 저장합니다. 응답 전체를 메모리에 저장할 수 없을 경우, 그중 일부를 디스크의 임시 파일에 저장할 수 있습니다. 임시 파일에 작성하는 작업은 fastcgi_max_temp_file_size 및 fastcgi_temp_file_write_size 명령으로 제어합니다.

버퍼링이 비활성화되면, 응답을 수신하는 즉시 클라이언트에 비동기식으로 전달하고 nginx는 FastCGI 서버에서 응답 전체를 읽으려고 시도하지 않습니다. nginx가 특정 시점에 서버에서 수신할 수 있는 데이터의 최대 용량은 fastcgi_buffer_size 명령으로 설정합니다.

또한, 버퍼링은 “X-Accel-Buffering” 응답 헤더 파일에서 “yes” 또는 “no”를 전달하여 활성화하거나 비활성화할 수 있습니다. 이 기능은 fastcgi_ignore_headers 명령을 사용하여 비활성화할 수 있습니다.

Syntax:  fastcgi_buffers number size;
Default: fastcgi_buffers 8 4k|8k;
Context: http, server, location

FastCGI 서버에서 하나의 연결에 대한 응답을 읽는 데 사용한 버퍼의 number와 size를 설정합니다. 기본적으로 버퍼 크기는 메모리 페이지 1개와 같습니다. 플랫폼에 따라 4K 또는 8K가 됩니다.

Syntax:  fastcgi_busy_buffers_size size;
Default: fastcgi_busy_buffers_size 8k|16k;
Context: http, server, location

FastCGI 서버에서 응답의 버퍼링이 활성화되면, 응답을 아직 완전히 읽지 않았을 때 클라이언트로 응답을 보내는 버퍼의 전체 size가 제한됩니다. 그동안 나머지 버퍼는 응답을 읽는 데 사용할 수 있고, 경우에 따라 임시 파일에 대한 응답의 버퍼링 부분을 담당할 수 있습니다. 기본적으로 size는 fastcgi_buffer_size 및 fastcgi_buffers 명령에서 설정한 두 버퍼의 크기로 제한됩니다.

Syntax:  fastcgi_cache zone | off;
Default: fastcgi_cache off;
Context: http, server, location

캐싱에 사용하는 공유된 메모리 영역을 정의합니다. 동일한 영역을 여러 곳에 사용할 수 있습니다. 매개변수 값은 변수를 포함할 수 있습니다(1.7.9). off 매개변수는 이전 구성 수준에서 상속한 캐싱을 비활성화합니다.

Syntax:  fastcgi_cache_background_update on | off;
Default: fastcgi_cache_background_update off;
Context: http, server, location
This directive appeared in version 1.11.10.

백그라운드 하위 요청을 시작하여 만료된 캐시 항목을 업데이트하고, 오래된 캐싱된 응답을 클라이언트로 반환합니다. 오래된 캐시된 응답을 업데이트할 때 이를 사용하도록 허용해야 합니다.

Syntax:  fastcgi_cache_bypass string ...;
Default: —
Context: http, server, location

응답을 캐시에서 수신하지 않는 조건을 정의합니다. 문자열 매개변수의 값 중 하나 이상이 비어 있지 않고 “0”이 아닐 경우, 응답을 캐시에서 수신하지 않습니다.

fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
fastcgi_cache_bypass $http_pragma    $http_authorization;

fastcgi_no_cache 명령과 함께 사용할 수 있습니다.

Syntax:  fastcgi_cache_key string;
Default: —
Context: http, server, location

캐싱을 위한 키를 정의합니다. 예를 들어 다음과 같습니다.

fastcgi_cache_key localhost:9000$request_uri;

Syntax:  fastcgi_cache_lock on | off;
Default: fastcgi_cache_lock off;
Context: http, server, location
This directive appeared in version 1.1.12.

이 설정을 활성화하면 FastCGI 서버에 요청을 전달하여 한 번에 하나의 요청만 fastcgi_cache_key 명령에 따라 식별된 새 캐시 요소를 채우게 됩니다. 동일한 캐시 요소의 다른 요청은 캐시에서 응답이 나타나기를 기다리거나, 이 요소에 대한 캐시 잠금이 해제되기를 기다립니다. 시간제한은 fastcgi_cache_lock_timeout 명령으로 설정합니다.

Syntax:  fastcgi_cache_lock_age time;
Default: fastcgi_cache_lock_age 5s;
Context: http, server, location
This directive appeared in version 1.7.8.

새로운 캐시 요소를 채우기 위해 FastCGI 서버로 전달된 마지막 요청이 일정 time 완료되지 않았을 경우, 요청을 하나 더 FastCGI 서버로 전달할 수 있습니다.

Syntax:  fastcgi_cache_lock_timeout time;
Default: fastcgi_cache_lock_timeout 5s;
Context: http, server, location
This directive appeared in version 1.1.12.

fastcgi_cache_lock에 대한 시간제한을 설정합니다. time이 만료되면 요청을 FastCGI 서버로 보냅니다. 단, 응답은 캐싱되지 않습니다.

1.7.8버전 이전에는 응답을 캐싱할 수 있었습니다.

Syntax:  fastcgi_cache_max_range_offset number;
Default: —
Context: http, server, location
This directive appeared in version 1.11.6.

바이트 범위 요청에 대해 오프셋(바이트 기준)을 설정합니다. 이 범위가 오프셋을 초과하면, 범위 요청을 FastCGI 서버로 전달하고 응답이 캐싱되지 않습니다.

Syntax:  fastcgi_cache_methods GET | HEAD | POST ...;
Default: fastcgi_cache_methods GET HEAD;
Context: http, server, location
This directive appeared in version 0.7.59.

클라이언트 요청 메서드가 이 명령에 나와 있으면 응답이 캐싱됩니다. “GET” 및 “HEAD” 메서드는 언제나 이 목록에 추가되지만, 명시적으로 지정하는 것이 좋습니다. fastcgi_no_cache 명령도 참조하세요.

Syntax:  fastcgi_cache_min_uses number;
Default: fastcgi_cache_min_uses 1;
Context: http, server, location

응답을 캐싱하기 전까지 요청의 number를 설정합니다.

Syntax:  fastcgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size 
         [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] 
         [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] 
         [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default: —
Context: http

캐시의 경로와 다른 매개변수를 설정합니다. 캐시 데이터는 파일에 저장됩니다. 캐시의 키와 파일 이름은 MD5 함수를 프록시된 URL에 적용한 결과입니다. levels 매개변수는 캐시의 계층 수준을 1~3까지 정의합니다. 각 수준은 1 또는 2 값을 받습니다. 예를 들어, 다음 구성에서

fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

캐시의 파일 이름은 다음과 같은 형식을 취합니다.

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

캐싱된 응답은 먼저 임시 파일에 작성된 다음, 파일 이름이 변경됩니다. 0.8.9버전에서부터 임시 파일과 캐시를 다른 파일 시스템에 넣을 수 있게 되었습니다. 그러나 이 경우, 간단하게 이름 변경 작업으로 처리하는 대신 파일을 두 개의 파일 시스템에 복사합니다. 따라서 어느 위치에서든 캐시와 임시 파일을 저장한 디렉터리는 동일한 파일 시스템에 넣어야 합니다. 임시 파일을 위한 디렉터리는 use_temp_path 매개변수를 기반으로 설정됩니다(1.7.10). 이 매개변수를 생략하거나 on 값으로 설정한 경우, 해당 위치에 대해 fastcgi_temp_path 명령으로 설정한 디렉터리를 사용합니다. 값이 off로 설정되면 임시 파일은 바로 캐시 디렉터리에 넣습니다.

또한, 모든 활성화된 키와 데이터에 대한 정보는 공유된 메모리 영역에 저장합니다. 이 영역의 name 및 size는 keys_zone 매개변수로 설정합니다. 1MB 영역은 약 8,000개의 키를 저장할 수 있습니다.

상업용 구독에서 공유된 메모리 영역은 확장된 캐시 정보도 저장하므로 동일한 숫자의 키에 대해서 영역 크기를 더 크게 설정해야 합니다. 예를 들어 1MB 영역은 약 4,000개의 키를 저장할 수 있습니다.

inactive 매개변수에서 지정한 시간 동안 캐싱된 데이터에 액세스가 없으면, 오래된 데이터든 새로운 데이터든 캐시에서 제거됩니다. 기본적으로 inactive는 10분으로 설정됩니다.

특수한 “cache manager” 프로세스는 max_size 매개변수에서 설정한 최대 캐시 크기를 모니터링하고, min_free(1.19.1) 매개변수가 캐시가 있는 파일 시스템에 대해 설정한 최소 여유 공간도 모니터링합니다. 이 용량을 초과하거나 여유 공간이 부족할 경우, 가장 오래전에 사용된 데이터를 제거합니다. 이 데이터는 manager_files, manager_threshold 및 manager_sleep 매개변수에서 구성한 이터레이션으로 제거됩니다(1.11.5). 1회 이터레이션에서는 manager_files보다 적은 수의 항목이 삭제됩니다(기본값: 100). 1회 이터레이션 시간은 manager_threshold 매개변수로 제한됩니다(기본값: 200ms). 이터레이션 사이에는 manager_sleep 매개변수로 구성한 일시 정지 시간(기본값: 50ms)이 포함됩니다.

시작되고 1분 후에 특수한 “cache loader” 프로세스가 활성화됩니다. 파일 시스템에 저장되었던 캐싱된 데이터에 대한 정보를 캐시 영역으로 로드합니다. 로딩도 이터레이션으로 실행됩니다. 1회 이터레이션에서는 loader_files보다 적은 수의 항목이 로드됩니다(기본값: 100). 또한, 1회 이터레이션 시간은 loader_threshold 매개변수로 제한됩니다(기본값: 200ms). 이터레이션 사이에는 loader_sleep 매개변수로 구성한 일시 정지 시간(기본값: 50ms)이 포함됩니다.

또한, 다음 매개변수는 상업용 구독에 제공됩니다.

purger=on|off

캐시 제거기가 와일드카드 키와 일치하는 캐시 항목을 디스크에서 제거합니다(1.7.12). 이 매개변수를 on(기본값: off)으로 설정하면 “cache purger” 프로세스가 활성화되고, 모든 캐시 항목에 대해 영구적으로 반복 수행하며 와일드카드 키와 일치하는 항목을 삭제합니다.

purger_files=number

1회 이터레이션에서 스캔할 항목 수를 설정합니다(1.7.12). 기본적으로 purger_files를 10으로 설정합니다.

purger_threshold=number

1회 이터레이션의 시간을 설정합니다(1.7.12). 기본적으로 purger_threshold는 50ms로 설정합니다.

purger_sleep=number

이터레이션 사이에 일시 정지 시간을 설정합니다(1.7.12). 기본적으로 purger_sleep을 50ms로 설정합니다.

1.7.3, 1.7.7, 1.11.10버전에서 캐시 헤더 형식이 변경되었습니다. 새로운 nginx 버전으로 업그레이드하면 이전에 캐싱된 응답은 유효하지 않은 것으로 간주됩니다.

Syntax:  fastcgi_cache_purge string ...;
Default: —
Context: http, server, location
This directive appeared in version 1.5.7.

요청을 캐시 퍼지 요청으로 간주하는 조건을 정의합니다. 문자열 매개변수의 값 중 하나 이상이 비어 있지 않고 “0”이 아닐 경우, 해당 캐시 키가 있는 캐시 항목을 제거합니다. 작업이 성공하면 204(No Content) 응답이 반환됩니다.

퍼지 요청의 캐시 키가 별표(“*”)로 끝나면 와일드카드 키와 일치하는 모든 캐시 항목을 캐시에서 제거합니다. 그러나 이들 항목은 활동이 없어서 삭제되거나 캐시 제거기가 처리하여(1.7.12) 삭제하거나, 클라이언트가 액세스를 시도할 때까지 디스크에 남아 있습니다.

예제 구성:

fastcgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        fastcgi_pass        backend;
        fastcgi_cache       cache_zone;
        fastcgi_cache_key   $uri;
        fastcgi_cache_purge $purge_method;
    }
}

이 기능은 상업용 구독에서 제공합니다.

Syntax:  fastcgi_cache_revalidate on | off;
Default: fastcgi_cache_revalidate off;
Context: http, server, location
This directive appeared in version 1.5.7.

“If-Modified-Since” 및 “If-None-Match” 헤더 필드로 조건부 요청을 사용하여 만료된 캐시 항목을 다시 평가하도록 합니다.

Syntax:  fastcgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | 
         http_403 | http_404 | http_429 | off ...;
Default: fastcgi_cache_use_stale off;
Context: http, server, location

FastCGI 서버와의 통신에 오류가 발생했을 때 어떤 경우에 오래된 캐싱된 응답을 사용할 수 있는지 결정합니다. 이 명령의 매개변수는 fastcgi_next_upstream 명령의 매개변수와 일치합니다.

error 매개변수는 요청을 처리할 FastCGI 서버를 선택하지 못할 경우 오래된 캐싱된 응답을 사용하도록 허용합니다.

또한, updating 매개변수는 오래된 캐싱된 응답이 현재 업데이트 중인 경우 사용을 허용합니다. 따라서 캐싱된 데이터를 업데이트할 때 FastCGI 서버에 대한 액세스 횟수를 최소화할 수 있습니다.

응답 시간이 경과된 이후에 일정 시간(초) 동안 응답 헤더에서 직접 오래된 캐싱된 응답을 사용할 수 있게 됩니다(1.11.10). 이는 명령 매개변수를 사용하는 것보다 우선순위가 낮습니다.

• “Cache-Control” 헤더 필드의 “stale-while-revalidate” 확장 프로그램은 오래된 캐싱된 응답이 현재 업데이트 중이라면 이를 사용하도록 허용합니다.
• “Cache-Control” 헤더 필드의 “stale-if-error” 확장 프로그램은 오류 발생 시 오래된 캐싱된 응답을 사용하도록 허용합니다.

새로운 캐시 요소를 채울 때 FastCGI 서버에 액세스하는 횟수를 최소화하려면 fastcgi_cache_lock 명령을 사용할 수 있습니다.

Syntax:  fastcgi_cache_valid [code ...] time;
Default: —
Context: http, server, location

각 응답 코드에 대한 캐싱 시간을 설정합니다. 예를 들어, 다음의 명령은

fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404      1m;

200 및 302 코드가 포함된 응답에 대한 캐싱은 10분으로, 404 코드가 포함된 응답에 대한 캐싱은 1분으로 설정합니다.

캐싱 time만 지정된 경우

fastcgi_cache_valid 5m;

200, 301 및 302 응답만 캐싱됩니다.

또한, any 매개변수로 모든 응답을 캐싱하도록 지정할 수 있습니다.

fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 301      1h;
fastcgi_cache_valid any      1m;

캐싱 매개변수는 응답 헤더에서 직접 설정할 수도 있습니다. 명령을 사용하여 캐싱 시간을 설정하는 것보다 우선순위가 높습니다.

• “X-Accel-Expires” 헤더 필드는 응답의 캐싱 시간(초)을 설정합니다. 0 값으로 설정하면 응답 캐싱이 비활성화됩니다. 값이 @ 접두사로 시작하는 경우, Epoch가 시작되고 경과한 절대 시간(초)을 설정하면 그 시간까지 응답을 캐싱할 수 있습니다.
• 헤더에 “X-Accel-Expires” 필드가 포함되지 않는 경우, 캐싱 매개변수를 “Expires” 또는 “Cache-Control” 헤더 필드에 설정할 수 있습니다.
• 헤더에 “Set-Cookie” 필드가 있을 경우, 해당 응답은 캐싱되지 않습니다.
• 헤더에 특수 값 “*”을 포함한 “Vary” 필드가 있을 경우, 해당 응답은 캐싱되지 않습니다(1.7.7). 헤더에 다른 값을 포함한 “Vary” 필드가 있을 경우, 해당 응답은 해당 요청 헤더 필드를 고려하여 캐싱됩니다(1.7.7).

하나 이상의 응답 헤더 필드를 처리하는 작업은 fastcgi_ignore_headers 명령을 사용하여 비활성화할 수 있습니다.

Syntax:  fastcgi_catch_stderr string;
Default: —
Context: http, server, location

FastCGI 서버에서 수신한 응답의 오류 스트림에서 검색할 문자열을 설정합니다. string을 발견한 경우, FastCGI 서버가 유효하지 않은 응답을 반환한 것으로 간주됩니다. 다음과 같이 nginx에서 애플리케이션 오류를 처리할 수 있습니다.

location /php/ {
    fastcgi_pass backend:9000;
    ...
    fastcgi_catch_stderr "PHP Fatal error";
    fastcgi_next_upstream error timeout invalid_header;
}

Syntax:  fastcgi_connect_timeout time;
Default: fastcgi_connect_timeout 60s;
Context: http, server, location

FastCGI 서버와의 연결을 설정하는 데 적용할 제한 시간을 정의합니다. 참고로 이 제한 시간은 일반적으로 75초를 넘지 않습니다.

Syntax:  fastcgi_force_ranges on | off;
Default: fastcgi_force_ranges off;
Context: http, server, location
This directive appeared in version 1.7.7.

이 응답의 “Accept-Ranges” 필드와 무관하게, FastCGI 서버의 캐싱된 응답과 캐싱되지 않은 응답에서 모두 바이트 범위를 지원합니다.

Syntax:  fastcgi_hide_header field;
Default: —
Context: http, server, location

기본적으로 nginx는 FastCGI 서버 응답에서 클라이언트로 “Status” 및”X-Accel-…” 헤더 필드를 전달하지 않습니다. fastcgi_hide_header 명령은 전달하지 않을 필드를 추가로 설정합니다. 반면, 필드 전달을 허용해야 하는 경우 fastcgi_pass_header 명령을 사용할 수 있습니다.

Syntax:  fastcgi_ignore_client_abort on | off;
Default: fastcgi_ignore_client_abort off;
Context: http, server, location

클라이언트가 응답을 기다리지 않고 연결을 종료하면 FastCGI 서버와의 연결을 종료해야 할지 결정합니다.

Syntax:  fastcgi_ignore_headers field ...;
Default: —
Context: http, server, location

FastCGI 서버에서 특정 응답 헤더 필드를 처리하는 작업을 비활성화합니다. 다음의 필드가 무시됩니다. “X-Accel-Redirect”, “X-Accel-Expires”, “X-Accel-Limit-Rate”(1.1.6), “X-Accel-Buffering”(1.1.6), “X-Accel-Charset”(1.1.6), “Expires”, “Cache-Control”, “Set-Cookie”(0.8.44) 및 “Vary”(1.7.7).

이 헤더 필드의 처리를 비활성화하지 않으면, 다음과 같은 효과가 발생합니다.

• “X-Accel-Expires”, “Expires”, “Cache-Control”, “Set-Cookie” 및 “Vary”가 응답 캐싱의 매개변수를 설정합니다.
• “X-Accel-Redirect”가 지정된 URI에 내부 리디렉션을 실행합니다.
• “X-Accel-Limit-Rate”가 응답을 클라이언트에 전송하는 속도 제한을 설정합니다.
• “X-Accel-Buffering”이 응답의 버퍼링을 활성화하거나 비활성화합니다.
• “X-Accel-Charset”가 응답의 적절한 문자 세트를 설정합니다.

Syntax:  fastcgi_index name;
Default: —
Context: http, server, location

슬래시로 끝나는 URI 뒤에 첨부할 파일 이름을 $fastcgi_script_name 변수 값으로 설정합니다. 예를 들어, 다음과 같은 설정을 사용할 경우

fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;

“/page.php” 요청에서는 SCRIPT_FILENAME 매개변수가 “/home/www/scripts/php/page.php”와 같고 “/” 요청에서는 “/home/www/scripts/php/index.php”와 같습니다.

Syntax:  fastcgi_intercept_errors on | off;
Default: fastcgi_intercept_errors off;
Context: http, server, location

300 이상의 코드가 포함된 FastCGI 서버 응답은 클라이언트로 전달하거나, 이를 해석하여 nginx로 리디렉션하고 error_page 명령을 통해 처리해야 합니다.

Syntax:  fastcgi_keep_conn on | off;
Default: fastcgi_keep_conn off;
Context: http, server, location
This directive appeared in version 1.1.4.

기본적으로 FastCGI 서버는 응답을 전송한 직후에 연결을 종료합니다. 그러나 이 명령을 on 값으로 저장하면, nginx가 FastCGI 서버에 연결을 열어두라는 명령을 보냅니다. 이는 특히 FastCGI 서버에 대한 keepalive 연결이 작동하는 데 필요합니다.

Syntax:  fastcgi_limit_rate rate;
Default: fastcgi_limit_rate 0;
Context: http, server, location
This directive appeared in version 1.7.7.

FastCGI 서버에서 응답을 읽는 속도를 제한합니다. rate는 1초당 바이트로 지정됩니다. 0 값은 속도 제한을 비활성화합니다. 제한은 요청별로 설정되므로, nginx가 FastCFI 서버에 대한 연결 2개를 동시에 열면 전체 속도는 지정된 제한의 두 배가 됩니다. 이 제한은 FastCGI 서버에서 응답 버퍼링이 활성화된 경우에만 적용됩니다.

Syntax:  fastcgi_max_temp_file_size size;
Default: fastcgi_max_temp_file_size 1024m;
Context: http, server, location

FastCGI 서버에서 응답 버퍼링이 활성화되었고 fastcgi_buffer_size 및 fastcgi_buffers 명령에서 설정한 버퍼보다 응답 전체가 클 경우, 응답 일부를 임시 파일에 저장할 수 있습니다. 이 명령은 임시 파일의 최대 size를 설정합니다. 한 번에 임시 파일에 작성하는 데이터 크기는 fastcgi_temp_file_write_size 명령에서 설정합니다.

0 값으로 설정하면 임시 파일에 대한 응답의 버퍼링이 비활성화됩니다.

이 제한은 캐싱되거나 디스크에 저장할 응답에는 적용되지 않습니다.

Syntax:  fastcgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | 
         http_404 | http_429 | non_idempotent | off ...;
Default: fastcgi_next_upstream error timeout;
Context: http, server, location

요청을 다음 서버로 전달해야 하는 경우를 지정합니다.

error

서버와 연결을 설정하거나 요청을 전달하거나 응답 헤더를 읽는 동안 오류가 발생했습니다.

timeout

서버와 연결을 설정하거나 요청을 전달하거나 응답 헤더를 읽는 동안 시간 초과가 발생했습니다.

invalid_header

서버가 비어 있거나 잘못된 응답을 반환했습니다.

http_500

서버가 500 코드로 응답을 반환했습니다.

http_503

서버가 503 코드로 응답을 반환했습니다.

http_403

서버가 403 코드로 응답을 반환했습니다.

http_404

서버가 404 코드로 응답을 반환했습니다.

http_429

서버가 코드 429(1.11.13)로 응답을 반환했습니다.

non_idempotent

일반적으로 non-idempotent 메서드가 포함된 요청(POST, LOCK, PATCH)은 업스트림 서버에 전송되었다면 다음 서버로 전달되지 않습니다(1.9.13). 이 옵션을 활성화하면 이 요청을 재시도하는 것을 명시적으로 허용합니다.

off

다음 서버로의 요청 전달을 비활성화하는 경우

단, 아직 클라이언트에 아무것도 전송하지 않은 상태여야 요청을 다음 서버로 전달할 수 있습니다. 즉, 응답을 전송하는 동안 오류가 발생하거나 시간이 초과되면 이를 수정할 수 없습니다.

또한, 이 명령은 서버 연결 시도 실패를 정의합니다. error, timeout 및 invalid_header는 언제나 통신 연결 실패로 간주됩니다. 이는 명령에서 지정되지 않은 경우에도 해당합니다. http_500, http_503, http_429는 명령에서 지정되지 않은 경우에만 통신 연결 실패로 간주됩니다. http_403 및 http_404는 통신 실패로 간주하지 않습니다.

다음 서버로 요청을 전달하는 것은 시도 횟수와 시간으로 제한할 수 있습니다.

Syntax:  fastcgi_next_upstream_timeout time;
Default: fastcgi_next_upstream_timeout 0;
Context: http, server, location
This directive appeared in version 1.7.5.

다음 서버로 요청을 전달할 수 있는 시간을 제한합니다 0 값은 이 제한을 비활성화합니다.

Syntax:  fastcgi_next_upstream_tries number;
Default: fastcgi_next_upstream_tries 0;
Context: http, server, location
This directive appeared in version 1.7.5.

다음 서버로 요청 전달을 시도할 수 있는 횟수를 제한합니다. 0 값은 이 제한을 비활성화합니다.

Syntax:  fastcgi_no_cache string ...;
Default: —
Context: http, server, location

응답을 캐시에 저장하지 않는 조건을 정의합니다. 문자열 매개변수의 값 중 하나 이상이 비어 있지 않고 “0”이 아닐 경우, 응답을 캐시에 저장하지 않습니다.

fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
fastcgi_no_cache $http_pragma    $http_authorization;

fastcgi_cache_bypass 명령과 함께 사용할 수 있습니다.

Syntax:  fastcgi_param parameter value [if_not_empty];
Default: —
Context: http, server, location

FastCGI 서버로 전달해야 하는 parameter를 설정합니다. value는 텍스트, 변수 및 그 두 가지의 조합을 포함할 수 있습니다. 이 명령은 현재 수준에서 정의된 fastcgi_param 명령이 없을 경우에만 이전 구성 수준에서 상속합니다.

다음의 예시는 PHP의 최소 요구 설정을 나타냅니다.

fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
fastcgi_param QUERY_STRING    $query_string;

SCRIPT_FILENAME 매개변수는 PHP에서 스크립트 이름을 확인하는 데 사용하고, QUERY_STRING 매개변수는 요청 매개변수를 전달하는 데 사용합니다.

POST 요청을 처리하는 스크립트의 경우, 다음의 세 가지 매개변수도 필요합니다.

fastcgi_param REQUEST_METHOD  $request_method;
fastcgi_param CONTENT_TYPE    $content_type;
fastcgi_param CONTENT_LENGTH  $content_length;

PHP를 –enable-force-cgi-redirect 구성 매개변수로 구축할 경우, REDIRECT_STATUS 매개변수도 “200” 값으로 전달해야 합니다.

fastcgi_param REDIRECT_STATUS 200;

명령을 if_not_empty(1.1.11)로 지정할 경우, 해당 매개변수는 그 값이 비어 있을 경우에만 서버로 전달됩니다.

fastcgi_param HTTPS           $https if_not_empty;

Syntax:  fastcgi_pass address;
Default: —
Context: location, if in location

FastCGI 서버의 주소를 설정합니다. 이 주소는 도메인 이름이나 IP 주소와 포트로 지정할 수 있습니다.

fastcgi_pass localhost:9000;

또는, UNIX 도메인 소켓 경로도 가능합니다.

fastcgi_pass unix:/tmp/fastcgi.socket;

도메인 이름이 여러 주소로 변환되는 경우, 모두 순환 방식으로 사용됩니다. 또한, 주소는 서버 그룹으로 지정할 수 있습니다.

매개변수 값은 변수를 포함할 수 있습니다. 이 경우, 주소를 도메인 이름으로 지정하면 설명된 서버 그룹에서 검색합니다. 이를 찾지 못할 경우 리졸버를 사용해서 확인합니다.

Syntax:  fastcgi_pass_header field;
Default: —
Context: http, server, location

다른 경우에는 비활성화된 헤더 필드를 FastCGI 서버에서 클라이언트로 전달하도록 허용합니다.

Syntax:  fastcgi_pass_request_body on | off;
Default: fastcgi_pass_request_body on;
Context: http, server, location

원본 요청 본문을 FastCGI 서버로 전달하는지 나타냅니다. fastcgi_pass_request_headers 명령도 참조하세요.

Syntax:  fastcgi_pass_request_headers on | off;
Default: fastcgi_pass_request_headers on;
Context: http, server, location

원본 요청의 헤더 필드를 FastCGI 서버로 전달하는지 나타냅니다. fastcgi_pass_request_body 명령도 참조하세요.

Syntax:  fastcgi_read_timeout time;
Default: fastcgi_read_timeout 60s;
Context: http, server, location

FastCGI 서버에서 응답을 읽는 시간제한을 정의합니다. 시간제한은 전체 응답 전송이 아니라 두 개의 연속적인 읽기 작업 사이에만 설정됩니다. FastCGI 서버가 이 시간 내에 아무것도 전송하지 않으면 연결이 종료됩니다.

Syntax:  fastcgi_request_buffering on | off;
Default: fastcgi_request_buffering on;
Context: http, server, location
This directive appeared in version 1.7.11.

클라이언트 요청 본문의 버퍼링을 활성화하거나 비활성화합니다.

버퍼링이 활성화되면 전체 요청 본문을 클라이언트에서 읽은 다음, 요청을 FastCGI 서버로 보냅니다.

버퍼링이 비활성화되면 요청 본문을 수신하는 즉시 FastCGI 서버로 전송합니다. 이 경우, nginx가 이미 요청 본문을 전송하기 시작했다면 요청을 다음 서버로 전달할 수 없습니다.

Syntax:  fastcgi_send_lowat size;
Default: fastcgi_send_lowat 0;
Context: http, server, location

명령을 0이 아닌 값으로 설정하면 nginx는 FastCGI 서버로 내보내는 연결에서 kqueue 메서드의 NOTE_LOWAT 플래그 또는 SO_SNDLOWAT 소켓 옵션을 사용하여 지정된 size를 기준으로 전송 작업 횟수를 최소화하려고 합니다.

이 명령은 Linux, Solaris, Windows에서는 무시됩니다.

Syntax:  fastcgi_send_timeout time;
Default: fastcgi_send_timeout 60s;
Context: http, server, location

FastCGI 서버로 요청을 전송하는 시간제한을 설정합니다. 시간제한은 전체 요청 전송이 아니라 두 개의 연속적인 쓰기 작업 사이에만 설정됩니다. FastCGI 서버가 이 시간 내에 아무것도 수신하지 않으면 연결이 종료됩니다.

Syntax:  fastcgi_socket_keepalive on | off;
Default: fastcgi_socket_keepalive off;
Context: http, server, location
This directive appeared in version 1.15.6.

FastCGI 서버로 내보내는 연결에 대해 “TCP keepalive” 동작을 구성합니다. 기본적으로 소켓에는 운영 체제 설정이 적용됩니다. 명령에서 “on” 값을 설정하면 해당 소켓에 대해 SO_KEEPALIVE 옵션이 활성화됩니다.

Syntax:  fastcgi_split_path_info regex;
Default: —
Context: location

$fastcgi_path_info 변수에 대한 값을 캡처하는 정규식을 정의합니다. 정규식은 두 개의 캡처가 있어야 합니다. 첫 번째는 $fastcgi_script_name 변수의 값이 되고, 두 번째는 $fastcgi_path_info 변수의 값이 됩니다. 예를 들어, 다음과 같은 설정을 사용할 경우

location ~ ^(.+\.php)(.*)$ {
    fastcgi_split_path_info       ^(.+\.php)(.*)$;
    fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;
    fastcgi_param PATH_INFO       $fastcgi_path_info;

“/show.php/article/0001” 요청에서 SCRIPT_FILENAME 매개변수가 “/path/to/php/show.php”와 같아지고, PATH_INFO 매개변수는 “/article/0001″과 같아집니다.

Syntax:  fastcgi_store on | off | string;
Default: fastcgi_store off;
Context: http, server, location

파일의 디스크 저장이 활성화됩니다. on 매개변수는 alias 또는 root 명령에 해당하는 경로로 파일을 저장합니다. off 매개변수는 파일 저장을 비활성화합니다. 또한, 파일 이름은 다음의 변수와 string을 사용하여 명시적으로 설정할 수 있습니다.

fastcgi_store /data/www$original_uri;

파일 수정 시간은 수신된 “Last-Modified” 응답 헤더 필드에 따라 설정됩니다. 응답은 먼저 임시 파일에 작성된 다음, 파일 이름이 변경됩니다. 0.8.9버전에서부터 임시 파일 및 영구 저장소를 다른 파일 시스템에 넣을 수 있게 되었습니다. 그러나 이 경우, 간단하게 이름 변경 작업으로 처리하는 대신 파일을 두 개의 파일 시스템에 복사합니다. 따라서 특정 위치에서 fastcgi_temp_path 명령에 따라 저장된 파일과 임시 파일을 저장한 디렉터리가 있을 경우, 이들을 동일한 파일 시스템에 넣어야 합니다.

이 명령은 변경할 수 없는 고정 파일의 로컬 사본을 생성하는 데 사용할 수 있습니다. 예를 들어, 다음과 같습니다.

location /images/ {
    root                 /data/www;
    error_page           404 = /fetch$uri;
}

location /fetch/ {
    internal;

    fastcgi_pass         backend:9000;
    ...

    fastcgi_store        on;
    fastcgi_store_access user:rw group:rw all:r;
    fastcgi_temp_path    /data/temp;

    alias                /data/www/;
}

Syntax:  fastcgi_store_access users:permissions ...;
Default: fastcgi_store_access user:rw;
Context: http, server, location

예를 들어, 다음과 같이 새로 생성된 파일과 디렉터리에 대한 액세스 권한을 설정합니다.

fastcgi_store_access user:rw group:rw all:r;

group 또는 all 액세스 권한을 지정할 경우, user 권한을 생략할 수 있습니다.

fastcgi_store_access group:rw all:r;

Syntax:  fastcgi_temp_file_write_size size;
Default: fastcgi_temp_file_write_size 8k|16k;
Context: http, server, location

FastCGI 서버에서 임시 파일로의 응답 버퍼링이 활성화되어 있을 경우, 임시 파일에 한 번에 작성한 데이터의 size를 제한합니다. 기본적으로 size는 fastcgi_buffer_size 및 fastcgi_buffers 명령에서 설정한 두 개의 버퍼로 제한됩니다. 임시 파일의 최대 크기는 fastcgi_max_temp_file_size 명령으로 설정합니다.

Syntax:  fastcgi_temp_path path [level1 [level2 [level3]]];
Default: fastcgi_temp_path fastcgi_temp;
Context: http, server, location

FastCGI 서버에서 수신한 데이터를 임시 파일에 저장하기 위한 디렉터리를 정의합니다. 지정된 디렉터리 아래에 최대 3개 수준의 하위 디렉터리 계층을 사용할 수 있습니다. 예를 들어, 다음 구성에서

fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2;

임시 파일은 다음과 같은 형식을 취할 수 있습니다.

/spool/nginx/fastcgi_temp/7/45/00000123457

fastcgi_cache_path 명령의 use_temp_path 매개변수도 참조하세요.

FastCGI 서버에 전달된 매개변수

HTTP 요청 헤더 필드는 FastCGI 서버에 매개변수로 전달됩니다. 일반적으로 FastCGI 서버로 실행되는 애플리케이션과 스크립트에서 이 매개변수가 환경 변수로 제공됩니다. 예를 들어 “User-Agent” 헤더 필드는 HTTP_USER_AGENT 매개변수로 전달됩니다. fastcgi_param 명령을 사용해서 HTTP 요청 헤더 필드 외에도 임의의 매개변수도 전달할 수 있습니다.

임베디드 변수

ngx_http_fastcgi_module 모듈은 fastcgi_param 명령을 사용하여 매개변수를 설정하는 데 사용할 수 있는 다음의 임베디드 변수를 지원합니다.

$fastcgi_script_name

요청 URI를 지원합니다. 또는, URI가 슬래시로 끝나면 fastcgi_index 명령을 첨부하여 구성한 인덱스 파일 이름을 포함한 요청 URI를 지원합니다. 이 변수는 PHP에서 스크립트 이름을 결정하는 SCRIPT_FILENAME 및 PATH_TRANSLATED 매개변수를 설정하는 데 사용할 수 있습니다. 예를 들어, 다음의 명령이 포함된 “/info/” 요청의 경우

fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;

SCRIPT_FILENAME 매개변수는 “/home/www/scripts/php/info/index.php”와 같습니다.

fastcgi_split_path_info 명령을 사용할 때 $fastcgi_script_name 변수는 이 명령으로 설정한 첫 캡처의 값과 같습니다.

$fastcgi_path_info

fastcgi_split_path_info 명령에서 설정한 두 번째 캡처의 값입니다. 이 변수는 PATH_INFO 매개변수를 설정하는 데 사용할 수 있습니다.