6. 고급 환경 설정

6.1. 로그 작업

서버로 전송된 요청의 로그를 기록하려면, 다음 환경 변수를 설정해야 합니다:

다음 변수들을 사용하면 로그 작업을 좀 더 사용자 지정할 수 있습니다:

6.2. 환경 변수

환경 변수 를 설정해서 QGIS 서버의 일부 환경을 설정할 수 있습니다.

HTTP 서버 및 사용자가 QGIS 서버를 어떻게 실행하느냐에 따라, 이런 변수들을 여러 방법으로 정의할 수 있습니다. 아파치 HTTP 서버 에서 그 방법들을 자세히 설명하고 있습니다.

명칭

설명

기본값

서비스

QGIS_OPTIONS_PATH

설정 파일이 있는 디렉터리를 가리키는 경로를 지정합니다. QGIS 응용 프로그램의 --optionspath 옵션과 동일하게 작동합니다. <QGIS_OPTIONS_PATH>/QGIS/QGIS3.ini 에 있는 설정 파일을 찾을 것입니다.

‘’

모두

QGIS_PLUGINPATH

사용자가 서버 용 파이썬 플러그인을 사용하고 있는 경우 유용합니다. 이 환경 변수는 파이썬 플러그인을 검색할 폴더를 설정합니다.

‘’

모두

QGIS_PROJECT_FILE

일반적으로 (MAP 을 보유한) 쿼리 문자열 내에서 파라미터로 전송되는 .qgs 또는 .qgz 프로젝트 파일을 (예를 들어 mod_rewrite 아파치 모듈을 사용해서) 환경 변수로 설정할 수도 있습니다.

PostgreSQL에 저장된 프로젝트를, 예를 들어 postgresql://localhost:5432?sslmode=disable&dbname=mydb&schema=myschema&project=myproject 와 같이 지정해야 할 수도 있다는 사실을 기억하십시오.

‘’

모두

QGIS_SERVER_ALLOWED_EXTRA_SQL_TOKENS

피처 필터의 요소로 허용된 추가 SQL 토큰을 표현하는 문자열의 쉼표 구분 목록

‘’

WMS

QGIS_SERVER_API_RESOURCES_DIRECTORY

(OAPIF/WFS3 같은) OGC API의 모든 정적 리소스(HTML 템플릿, CSS, JS 등등) 용 기본 디렉터리

패키지에 따라 다름

OAPIF/WFS3

QGIS_SERVER_API_WFS3_MAX_LIMIT

OAPIF/WFS3 피처 요청에서 limit 의 최대값

10000

OAPIF/WFS3

QGIS_SERVER_CACHE_DIRECTORY

파일 시스템 상에 네트워크 캐시 디렉터리를 지정합니다.

cache 가 프로파일 디렉터리에 있음

모두

QGIS_SERVER_CACHE_SIZE

네트워크 캐시의 용량을 MB 단위로 설정합니다.

50 MB

모두

QGIS_SERVER_DISABLE_GETPRINT

조판 불러오기를 비활성화시켜 프로젝트를 읽어오는 시간을 단축하기 위한 프로젝트 수준 옵션입니다.

이 옵션을 활성화하면 QGIS WMS GetPrint 요청이 비활성화됩니다. 이 QGIS 프로젝트 플래그가 조판을 불러오지 않도록 설정하십시오.

false

WMS

QGIS_SERVER_FORCE_READONLY_LAYERS

QGIS 서버가 모든 레이어를 읽기 전용 모드로 열도록 강제합니다.

false

모두

QGIS_SERVER_IGNORE_BAD_LAYERS

“불량(bad)” 레이어란 불러올 수 없는 레이어입니다. 프로젝트가 불량 레이어를 담고 있는 경우 해당 프로젝트를 사용할 수 없다고 인식하는 것이 QGIS 서버의 기본 습성입니다.

이 환경 변수를 1 또는 true 로 설정하면 이런 기본 습성을 무시할 수 있습니다. 이렇게 설정하면 “불량” 레이어를 그냥 무시해버리고, 프로젝트를 유효하고 사용 가능한 것으로 인식할 것입니다.

false

모두

QGIS_SERVER_LANDING_PAGE_PREFIX

랜딩 페이지 기반 URL의 경로 구성요소의 접두어입니다.

“”

모두

QGIS_SERVER_LANDING_PAGE_PROJECTS_DIRECTORIES

연결 페이지(landing page) 서비스가 .qgs 및 .qgz 프로젝트를 찾기 위해 사용하는 디렉터리들입니다.

“”

모두

QGIS_SERVER_LANDING_PAGE_PROJECTS_PG_CONNECTIONS

연결 페이지(landing page) 서비스가 프로젝트를 찾기 위해 사용하는 PostgreSQL 연결 문자열입니다.

“”

모두

QGIS_SERVER_LOG_FILE

경로 및 파일명을 지정합니다. 서버가 파일을 작성하기 위한 적절한 권한을 가지고 있는지 확인하십시오. 서버에 요청을 보내기만 하면 파일을 자동적으로 생성할 것입니다. 파일이 생성되지 않을 경우, 권한을 확인해보십시오.

경고

QGIS_SERVER_LOG_FILE 환경 변수는 QGIS 3.4 버전부터 사용하지 않게 되었으므로, 대신 QGIS_SERVER_LOG_STDERR를 사용하십시오. 파일 로그 작업 지원은 QGIS 4.0 버전에서 제거될 것입니다.

‘’

모두

QGIS_SERVER_LOG_LEVEL

원하는 로그 수준을 지정합니다. 다음 수준 가운데 하나를 선택할 수 있습니다:

  • 0 또는 INFO: 모든 요청을 로그에 기록합니다.

  • 1 또는 WARNING

  • 2 또는 CRITICAL: 치명적인 오류만 로그에 기록합니다. 제품 목적으로 적합합니다.

0

모두

QGIS_SERVER_LOG_PROFILE

로그에 상세 프로파일 정보를 추가합니다. QGIS_SERVER_LOG_LEVEL=0 인 경우에만 효과가 있습니다.

false

모두

QGIS_SERVER_LOG_STDERR

‘stderr’ 로의 로그 작업을 활성화합니다. QGIS_SERVER_LOG_FILE 을 설정한 경우 이 환경 변수는 아무 영향도 주지 못 합니다.

  • 0 또는 false (대소문자 구분 안 함)

  • 1 또는 true (대소문자 구분 안 함)

false

모두

QGIS_SERVER_MAX_THREADS

병렬 렌더링을 활성화한 경우 사용할 스레드의 개수를 지정합니다. 값이 -1 인 경우 프로세서 코어의 개수를 사용합니다.

-1

모두

QGIS_SERVER_OVERRIDE_SYSTEM_LOCALE

QGIS 서버가 사용할 LOCALE을 설정합니다. 기본값은 비어 있습니다(무시하지 않습니다).

예시: de_CH.utf8

‘’

모두

QGIS_SERVER_PARALLEL_RENDERING

WMS GetMap 요청에 대해 병렬 렌더링을 활성화합니다. 기본적으로 비활성화(false) 상태입니다. 다음 값을 사용할 수 있습니다:

  • 0 또는 false (대소문자 구분 안 함)

  • 1 또는 true (대소문자 구분 안 함)

false

WMS

QGIS_SERVER_PROJECT_CACHE_CHECK_INTERVAL

캐시 무효화에 대한 주기적 전략 간격을 제어합니다.

모두

QGIS_SERVER_PROJECT_CACHE_STRATEGY

프로젝트 캐시를 무효화하기 위한 방법을 정의합니다. 다음과 같은 전략 가운데 하나를 사용할 수 있습니다:

  • filesystem: 파일 시스템 감시자(watcher) 전략을 사용합니다.

  • periodic: 프로젝트 환경 설정의 변경 사항을 점검하기 위해 프로젝트의 마지막으로 수정된 값을 사용합니다. NFS 같은 일반적이지 않은 파일 시스템 상에서 또는 프로젝트 파일이 PostgreSQL 같은 데이터베이스 시스템에 저장되어 있는 경우 편리합니다.

  • off: 내부 캐시 무효화를 완전히 비활성화합니다.

filesystem

모두

QGIS_SERVER_SERVICE_URL

프로젝트에 서비스 URL이 존재하지 않는 경우 이 옵션을 통해 서비스 URL을 설정합니다.

서비스 URL은 다음에서 정의됩니다(우선 순위대로):

  • 서비스 별 프로젝트에서 정의된 값

  • QGIS_SERVER_<service>_SERVICE_URL 환경 변수

  • QGIS_SERVER_SERVICE_URL 환경 변수

  • X-Qgis-<service>-Service-Url 헤더

  • X-Qgis-Service-Url 헤더

  • Forwarded 헤더로부터 작성

  • X-Forwarded-Host 및 X-Forwarded-Proto 헤더로부터 작성

  • Host 헤더와 서버 프로토콜로부터 작성

  • 서버 이름과 서버 프로토콜로부터 작성

마지막 네 가지의 경우, 쿼리 문자열에 제공되는 MAP 파라미터 및 수신되는 경로 요청을 기반으로 서비스 URL을 산출합니다.

‘’

모두

QGIS_SERVER_SHOW_GROUP_SEPARATOR

숫자 값에 대해 (예를 들어 GetFeatureInfo 응답에서) 그룹 구분자(예: 천 단위 구분자)를 사용해야 할지 여부를 정의합니다. 기본값은 0 입니다.

  • 0 또는 false (대소문자 구분 안 함)

  • 1 또는 true (대소문자 구분 안 함)

false

WMS

QGIS_SERVER_TRUST_LAYER_METADATA

PostgreSQL/PostGIS 레이어 기본 키(primary key)의 유일성 점검을 비활성화하고 프로젝트 메타데이터에 정의된 벡터 레이어 영역을 사용해서 프로젝트를 읽어오는 시간을 단축하기 위한 프로젝트 수준 옵션입니다.

이 변수를 1 또는 true 로 설정하면 레이어 메타데이터를 신뢰하도록 강제할 수 있습니다. 그러면 벡터 레이어의 영역을 프로젝트에 정의된 영역으로 받아들이고, 데이터소스에 정의된 PostgreSQL/PostGIS 레이어의 기본 키를 점검하지 않은 채 유일하다고 간주할 것입니다.

프로젝트를 사용하는 도중 레이어 영역이 고정되지 않는 상황에서는 이 변수를 사용해서는 안 됩니다.

false

모두

QGIS_SERVER_WCS_SERVICE_URL

프로젝트에 서비스 URL이 존재하지 않는 경우 이 옵션을 통해 서비스 URL을 설정합니다. 더 자세한 정보는 QGIS_SERVER_SERVICE_URL 을 참조하세요.

‘’

WCS

QGIS_SERVER_WFS_SERVICE_URL

프로젝트에 서비스 URL이 존재하지 않는 경우 이 옵션을 통해 서비스 URL을 설정합니다. 더 자세한 정보는 QGIS_SERVER_SERVICE_URL 을 참조하세요.

‘’

WFS

QGIS_SERVER_WMS_MAX_HEIGHT / QGIS_SERVER_WMS_MAX_WIDTH

WMS 요청에 대한 최대 높이/너비입니다. 이 값과 프로젝트 값 사이에 가장 보수적인 값을 사용합니다. 값이 -1 인 경우, 설정된 최대값이 없다는 뜻입니다.

-1

WMS

QGIS_SERVER_WMS_SERVICE_URL

프로젝트에 서비스 URL이 존재하지 않는 경우 이 옵션을 통해 서비스 URL을 설정합니다. 더 자세한 정보는 QGIS_SERVER_SERVICE_URL 을 참조하세요.

‘’

WMS

QGIS_SERVER_WMTS_SERVICE_URL

프로젝트에 서비스 URL이 존재하지 않는 경우 이 옵션을 통해 서비스 URL을 설정합니다. 더 자세한 정보는 QGIS_SERVER_SERVICE_URL 을 참조하세요.

‘’

WMTS

QUERY_STRING

일반적으로 웹 서버가 전송하는 쿼리 문자열을 정의합니다. 이 환경 변수는 명령 줄 인터페이스에서 QGIS 서버 파일을 검증하는 데 유용합니다.

예를 들어 다음은 pg_service.conf 파일에 정의된 PostgreSQL 연결도 필요로 하는 프로젝트에 명령 줄 인터페이스에서 GetCapabilities 요청을 검증하는 예입니다:

PGSERVICEFILE=/etc/pg_service.conf \
QUERY_STRING="MAP=/home/projects/world.qgs&SERVICE=WMS&REQUEST=GetCapabilities" \
/usr/lib/cgi-bin/qgis_mapserv.fcgi

이 요청에 대한 결과는 GetCapabilities 응답의 내용이거나, 또는 무언가 오류가 발생한 경우 오류 메시지여야 합니다.

‘’

모두

6.3. 설정 요약

QGIS 서버 실행 시, 환경 설정할 수 있는 모든 파라미터의 요약을 환경 변수 덕분에 볼 수 있습니다. 게다가, 현재 사용되는 값과 그 기원까지 표시됩니다.

예를 들어 ‘spawn-fcgi’ 의 경우:

export QGIS_OPTIONS_PATH=/home/user/.local/share/QGIS/QGIS3/profiles/default/
export QGIS_SERVER_LOG_STDERR=1
export QGIS_SERVER_LOG_LEVEL=2
spawn-fcgi -f /usr/lib/cgi-bin/qgis_mapserv.fcgi -s /tmp/qgisserver.sock -U www-data -G www-data -n

 QGIS Server Settings:

   - QGIS_OPTIONS_PATH / '' (Override the default path for user configuration): '/home/user/.local/share/QGIS/QGIS3/profiles/default/' (read from ENVIRONMENT_VARIABLE)

   - QGIS_SERVER_PARALLEL_RENDERING / '/qgis/parallel_rendering' (Activate/Deactivate parallel rendering for WMS getMap request): 'true' (read from INI_FILE)

   - QGIS_SERVER_MAX_THREADS / '/qgis/max_threads' (Number of threads to use when parallel rendering is activated): '4' (read from INI_FILE)

   - QGIS_SERVER_LOG_LEVEL / '' (Log level): '2' (read from ENVIRONMENT_VARIABLE)

   - QGIS_SERVER_LOG_STDERR / '' (Activate/Deactivate logging to stderr): '1' (read from ENVIRONMENT_VARIABLE)

   - QGIS_PROJECT_FILE / '' (QGIS project file): '' (read from DEFAULT_VALUE)

   - MAX_CACHE_LAYERS / '' (Specify the maximum number of cached layers): '100' (read from DEFAULT_VALUE)

   - QGIS_SERVER_CACHE_DIRECTORY / '/cache/directory' (Specify the cache directory): '/root/.local/share/QGIS/QGIS3/profiles/default/cache' (read from DEFAULT_VALUE)

   - QGIS_SERVER_CACHE_SIZE / '/cache/size' (Specify the cache size): '52428800' (read from INI_FILE)

 Ini file used to initialize settings: /home/user/.local/share/QGIS/QGIS3/profiles/default/QGIS/QGIS3.ini

이 특정한 경우에서, (환경 변수를 통해 정의한) QGIS_OPTIONS_PATH 디렉터리에서 찾은 .ini 파일로부터 QGIS_SERVER_MAX_THREADS 및 QGIS_SERVER_PARALLEL_RENDERING 값을 읽어왔다는 사실을 알 수 있습니다. .ini 파일의 대응 항목들은 /qgis/max_threads 및 /qgis/parallel_rendering 이며 그 값은 각각 true 와 스레드 4 개입니다.

6.4. 서비스 파일에 연결

Apache가 PostgreSQL 서비스 파일(PostgreSQL 서비스 연결 파일 참조)을 인지하도록 하려면, 사용자의 *.conf 파일을 다음과 같이 추가해야 합니다:

SetEnv PGSERVICEFILE /home/web/.pg_service.conf

<Directory "/home/web/apps2/bin/">
  AllowOverride None
.....

6.5. 사용자 리눅스 서버에 글꼴 추가

사용자의 QGIS 프로젝트가 가리키는 글꼴이 다른 시스템 상에는 기본적으로 존재하지 않을 수도 있다는 사실을 기억하고 있어야 합니다. 즉 프로젝트를 공유하는 경우, (대상 컴퓨터에 해당 글꼴이 없다면) 다른 컴퓨터에서는 다르게 보일 수도 있다는 뜻입니다.

이런 일이 일어나지 않도록 보장하려면, 대상 컴퓨터에 빠진 글꼴을 설치하기만 하면 됩니다. 데스크탑 시스템인 경우 보통 이 작업은 어렵지 않습니다. (글꼴 파일을 더블클릭하면 됩니다.)

리눅스의 경우, 데스크탑 환경이 설치되지 않았다면 (또는 사용자가 명령 줄 인터페이스를 선호한다면) 다음 명령어를 실행하면 됩니다:

  • 데비안 기반 시스템인 경우:

    sudo su
mkdir -p /usr/local/share/fonts/truetype/myfonts && cd /usr/local/share/fonts/truetype/myfonts

# copy the fonts from their location
cp /fonts_location/* .

chown root *
cd .. && fc-cache -f -v

  • 페도라 기반 시스템인 경우:

    sudo su
mkdir /usr/share/fonts/myfonts && cd /usr/share/fonts/myfonts

# copy the fonts from their location
cp /fonts_location/* .

chown root *
cd .. && fc-cache -f -v