Applying changes to configuration files

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

구성 파일에 변경 사항 적용하기

Windows에서는 securityadmin.sh 대신 securityadmin.bat을 사용하세요. 자세한 내용은 Windows 사용법을 참조하세요. {: .note}

Security 플러그인은 사용자, 역할, 권한, 백엔드 설정을 포함한 구성을 OpenSearch 클러스터의 시스템 인덱스에 저장해요. 이 설정들을 인덱스에 저장하면 클러스터를 재시작하지 않고도 설정을 변경할 수 있고, 개별 노드마다 구성 파일을 수정할 필요도 없어져요. 이 작업은 securityadmin.sh 스크립트를 실행해서 수행해요.

스크립트의 첫 번째 작업은 .opendistro_security 인덱스를 초기화하는 거예요. 이때 /config/opensearch-security에 있는 구성 파일을 사용해 초기 구성을 인덱스에 로드해요. .opendistro_security 인덱스가 초기화되고 나면 OpenSearch Dashboards나 REST API를 사용해 사용자, 역할, 권한을 관리할 수 있어요.

스크립트는 /plugins/opensearch-security/tools/securityadmin.sh에서 찾을 수 있어요. 이는 securityadmin.sh 스크립트가 있는 위치를 나타내는 상대 경로예요. 절대 경로는 OpenSearch를 설치한 디렉터리에 따라 달라져요. 예를 들어 Docker로 OpenSearch를 설치했다면 경로는 다음과 비슷하게 될 거예요: /usr/share/opensearch/plugins/opensearch-security/tools/securityadmin.sh.

securityadmin.sh 스크립트를 사용하려면 OpenSearch 클러스터에서 SSL/TLS HTTP가 활성화되어 있어야 해요. 진행하기 전에 opensearch.yml 파일에서 plugins.security.ssl.http.enabled: true로 설정하세요. 클러스터가 HTTP 레이어에서 SSL/TLS를 사용하지 않지만 securityadmin.sh가 필요하다면, ingest 노드 같은 단일 노드에서 SSL/TLS를 활성화한 다음 그 노드에서 securityadmin.sh를 실행하세요. 이 설정은 REST 레이어 TLS 설정을 한 노드에만 구성해서 활성화할 수 있어요. opensearch.yml 파일을 변경한 후에는 해당 노드에서 OpenSearch를 재시작해야 해요. {: .note}

주의 사항

config/opensearch-security의 구성 파일을 변경해도 OpenSearch는 이 변경 사항을 자동으로 적용하지 않아요. 대신 securityadmin.sh를 실행해서 업데이트된 파일을 인덱스에 로드해야 해요. securityadmin.sh 파일은 <OPENSEARCH_HOME>/plugins/opensearch-security/tools/securityadmin.[sh|bat]에서 찾을 수 있어요.

securityadmin.sh를 실행하면 .opendistro_security 인덱스의 한 부분 이상을 덮어써요. 기존 리소스를 잃어버리지 않으려면 각별히 주의해서 실행하세요. 다음 예시를 살펴보세요:

.opendistro_security 인덱스를 초기화해요.
REST API로 열 명의 사용자를 만들어요.
<OPENSEARCH_HOME>/config/opensearch-security/ 디렉터리에 있는 internal_users.yml을 사용해 새 예약 사용자를 만들기로 해요.
새 예약 사용자를 인덱스에 로드하려고 securityadmin.sh를 다시 실행해요.
REST API로 만들었던 열 명의 사용자를 모두 잃게 돼요.

이런 상황을 피하려면 변경을 가하기 전과 스크립트를 다시 실행하기 전에 현재 구성을 백업하세요:

./securityadmin.sh -backup my-backup-directory \
  -icl \
  -nhnv \
  -cacert ../../../config/root-ca.pem \
  -cert ../../../config/kirk.pem \
  -key ../../../config/kirk-key.pem

OpenSearch가 보안 구성의 히스토리를 유지하도록 설정하면, 의도하지 않은 변경이 있은 후에 이전 버전을 복원할 수도 있어요. 자세한 내용은 보안 구성 버전 API를 참조하세요.

-cd 대신 -f 인자를 사용하면 YAML 파일이 들어 있는 디렉터리 전체 대신 단일 YAML 파일을 인덱스에 로드할 수 있어요. 예를 들어 새 역할을 열 개 만들었다면, 역할을 잃지 않고 internal_users.yml을 안전하게 인덱스에 로드할 수 있어요. 덮어써지는 건 내부 사용자뿐이거든요.

./securityadmin.sh -f ../../../config/opensearch-security/internal_users.yml \
  -t internalusers \
  -icl \
  -nhnv \
  -cacert ../../../config/root-ca.pem \
  -cert ../../../config/kirk.pem \
  -key ../../../config/kirk-key.pem

보안 구성을 적용하기 전에 모든 환경 변수를 치환하려면 -rev 파라미터를 사용하세요.

./securityadmin.sh -cd ../../../config/opensearch-security/ \
 -rev \
 -cacert ../../../root-ca.pem \
 -cert ../../../kirk.pem \
 -key ../../../kirk.key.pem

다음 예시는 config.yml 파일에 있는 환경 변수를 보여줘요:

password: ${env.LDAP_PASSWORD}

어드민 인증서 구성하기

securityadmin.sh를 사용하려면 모든 어드민 인증서의 고유 이름(DN)을 opensearch.yml에 추가해야 해요. 예를 들어 데모 인증서를 사용한다면, opensearch.yml에 kirk 인증서를 위한 다음 줄들이 포함되어 있을 수 있어요:

plugins.security.authcz.admin_dn:
  - CN=kirk,OU=client,O=client,L=test,C=DE

노드 인증서를 어드민 인증서로 사용할 수는 없어요. 둘은 반드시 분리되어 있어야 해요. 또한 DN의 각 부분 사이에 공백을 넣지 마세요. {: .warning }

기본 사용법

securityadmin.sh 도구는 OpenSearch 클러스터의 HTTP 포트(기본 포트는 9200)에 접근할 수 있는 어떤 머신에서든 실행할 수 있어요. SSH로 노드에 접속하지 않고도 Security 플러그인 구성을 변경할 수 있어요.

각 노드에도 plugins/opensearch-security/tools/securityadmin.sh 위치에 이 도구가 포함되어 있어요. 스크립트를 실행하기 전에 실행 가능한 상태로 만들어야 할 수도 있어요:

chmod +x plugins/opensearch-security/tools/securityadmin.sh

사용 가능한 모든 명령줄 옵션을 출력하려면 인자 없이 스크립트를 실행하세요:

./plugins/opensearch-security/tools/securityadmin.sh

PEM 파일과 함께 `securityadmin` 사용하기

초기 구성(모든 YAML 파일)을 로드하려면 다음 명령어를 사용할 수 있어요:

./securityadmin.sh -cd ../../../config/opensearch-security/ -icl -nhnv \
  -cacert ../../../config/root-ca.pem \
  -cert ../../../config/kirk.pem \
  -key ../../../config/kirk-key.pem

-cd 옵션은 Security 플러그인 구성 파일이 있는 위치를 지정해요.
-icl(--ignore-clustername) 옵션은 클러스터 이름과 상관없이 구성을 업로드하라고 Security 플러그인에 알려줘요. 대신 -cn(--clustername) 옵션으로 클러스터 이름을 지정할 수도 있어요.
데모 인증서는 자체 서명되어 있기 때문에, 이 명령어는 -nhnv(--disable-host-name-verification) 옵션으로 호스트 이름 검증을 비활성화해요.
-cacert, -cert, -key 옵션은 루트 CA 인증서, 어드민 인증서, 어드민 인증서의 프라이빗 키 위치를 정의해요. 프라이빗 키에 비밀번호가 있다면 -keypass 옵션으로 지정하세요.

다음 표는 PEM 옵션을 보여줘요.

이름	설명
`-cert`	어드민 인증서와 중간 인증서(있다면)가 포함된 PEM 파일의 위치예요. 절대 경로나 상대 경로를 사용할 수 있어요. 상대 경로는 `securityadmin.sh`의 실행 디렉터리를 기준으로 확인돼요.
`-key`	어드민 인증서의 프라이빗 키가 포함된 PEM 파일의 위치예요. 절대 경로나 상대 경로를 사용할 수 있어요. 상대 경로는 `securityadmin.sh`의 실행 디렉터리를 기준으로 확인돼요. 키는 PKCS#8 형식이어야 해요.
`-keypass`	어드민 인증서 프라이빗 키의 비밀번호예요(있는 경우).
`-cacert`	루트 인증서가 포함된 PEM 파일의 위치예요. 절대 경로나 상대 경로를 사용할 수 있어요. 상대 경로는 `securityadmin.sh`의 실행 디렉터리를 기준으로 확인돼요.

키스토어 및 트러스트스토어 파일과 함께 `securityadmin` 사용하기

JKS 형식의 키스토어 파일은 다음 예시 설정에서 볼 수 있듯이 securityadmin.sh와 호환돼요:

./securityadmin.sh -cd ../../../config/opensearch-security -icl -nhnv
  -ts <path/to/truststore> -tspass <truststore password>
  -ks <path/to/keystore> -kspass <keystore password>

키스토어와 트러스트스토어 설정을 제어하려면 다음 옵션을 사용하세요.

이름	설명
`-ks`	어드민 인증서와 중간 인증서(있다면)가 포함된 키스토어의 위치예요. 절대 경로나 상대 경로를 사용할 수 있어요. 상대 경로는 `securityadmin.sh` 실행 디렉터리를 기준으로 확인돼요.
`-kspass`	키스토어 비밀번호예요.
`-kst`	키스토어 유형이에요. JKS 또는 PKCS#12/PFX예요. 지정하지 않으면 Security 플러그인이 파일 확장자를 기반으로 유형을 판단하려고 해요.
`-ksalias`	어드민 인증서의 별칭이에요(있는 경우).
`-ts`	루트 인증서가 포함된 트러스트스토어의 위치예요. 절대 경로나 상대 경로를 사용할 수 있어요. 상대 경로는 `securityadmin.sh` 실행 디렉터리를 기준으로 확인돼요.
`-tspass`	트러스트스토어 비밀번호예요.
`-tst`	트러스트스토어 유형이에요. JKS 또는 PKCS#12/PFX예요. 지정하지 않으면 Security 플러그인이 파일 확장자를 기반으로 유형을 판단하려고 해요.
`-tsalias`	루트 인증서의 별칭이에요(있는 경우).

admin 인증서에 서명하는 인증 기관(CA)은 전송(transport)이나 HTTP 인증서에 서명하는 데 사용한 CA와 달라도 돼요. 다만 인증서를 검증하려면 해당 CA를 트러스트스토어에 추가해야 해요. 자세한 내용은 노드 및 클라이언트 인증서 생성을 참조하세요. {: .note}

예시 명령어

PEM 인증서를 사용해 config/opensearch-security/의 모든 YAML 파일을 적용해요:

/usr/share/opensearch/plugins/opensearch-security/tools/securityadmin.sh \
  -cacert /etc/opensearch/root-ca.pem \
  -cert /etc/opensearch/kirk.pem \
  -key /etc/opensearch/kirk-key.pem \
  -cd /usr/share/opensearch/config/opensearch-security/

PEM 인증서를 사용해 단일 YAML 파일(config.yml)을 적용해요:

./securityadmin.sh \
  -f ../../../config/opensearch-security/config.yml \
  -icl -nhnv -cert /etc/opensearch/kirk.pem \
  -cacert /etc/opensearch/root-ca.pem \
  -key /etc/opensearch/kirk-key.pem \
  -t config

키스토어와 트러스트스토어 파일을 사용해 config/opensearch-security/의 모든 YAML 파일을 적용해요:

./securityadmin.sh \
  -cd /usr/share/opensearch/config/opensearch-security/ \
  -ks /path/to/keystore.jks \
  -kspass changeit \
  -ts /path/to/truststore.jks \
  -tspass changeit
  -nhnv
  -icl

OpenSearch 설정

포트 9200에서 리스닝하고 클러스터 이름으로 opensearch를 사용하는 기본 OpenSearch 설치를 실행 중이라면 다음 설정을 아예 생략할 수 있어요. 그렇지 않다면 다음 스위치를 사용해 OpenSearch 설정을 지정하세요.

이름	설명
`-h`	OpenSearch 호스트 이름이에요. 기본값은 `localhost`예요.
`-p`	OpenSearch 포트예요. 기본값은 9200이에요.
`-cn`	클러스터 이름이에요. 기본값은 `opensearch`예요.
`-icl`	클러스터 이름을 무시해요.
`-sniff`	클러스터 노드를 스니핑해요. 스니핑은 OpenSearch `_cluster/state` API를 사용해 사용 가능한 노드를 탐지해요.
`-arc,--accept-red-cluster`	클러스터 상태가 red여도 `securityadmin.sh`를 실행해요. 기본값은 `false`라서 red 클러스터에서는 스크립트가 실행되지 않아요.

인증서 검증 설정

인증서 검증을 제어하려면 다음 옵션을 사용하세요.

이름	설명
`-nhnv`	호스트 이름을 검증하지 않아요. 기본값은 `false`예요.
`-nrhn`	호스트 이름을 조회하지 않아요. `-nhnv`가 설정되지 않은 경우에만 관련이 있어요.

구성 파일 설정

다음 스위치는 Security 플러그인에 푸시할 구성 파일을 정의해요. 단일 파일을 푸시하거나 하나 이상의 구성 파일이 들어 있는 디렉터리를 지정할 수 있어요.

이름	설명
`-cd`	여러 Security 플러그인 구성 파일이 들어 있는 디렉터리예요.
`-f`	단일 구성 파일이에요. `-cd`와 함께 사용할 수 없어요.
`-t`	파일 유형이에요.
`-rl`	현재 구성을 다시 로드하고 내부 캐시를 플러시해요.

디렉터리에 있는 모든 구성 파일을 업로드하려면 이렇게 하세요:

./securityadmin.sh -cd ../../../config/opensearch-security -ts ... -tspass ... -ks ... -kspass ...

단일 구성 파일을 푸시하려면 이렇게 하세요:

./securityadmin.sh -f ../../../config/opensearch-security/internal_users.yml -t internalusers  \
    -ts ... -tspass ... -ks ... -kspass ...

파일 유형은 다음 중 하나여야 해요:

config
roles
rolesmapping
internalusers
actiongroups

암호 스위트 설정

암호 스위트 설정을 변경할 일은 없을 거예요. 필요하다면 다음 옵션을 사용하세요.

이름	설명
`-ec`	활성화할 TLS 암호 스위트의 쉼표로 구분된 목록이에요.
`-ep`	활성화할 TLS 프로토콜의 쉼표로 구분된 목록이에요.

백업, 복원, 마이그레이션

다음 명령어로 클러스터에서 현재 구성 파일을 모두 다운로드할 수 있어요:

./securityadmin.sh -backup my-backup-directory -ts ... -tspass ... -ks ... -kspass ...

이 명령어는 클러스터의 현재 Security 플러그인 구성을 지정한 디렉터리의 개별 파일로 덤프해요. 그런 다음 이 파일들을 백업으로 사용하거나 다른 클러스터에 구성을 로드할 때 사용할 수 있어요. 이 명령어는 개념 증명(PoC)을 프로덕션으로 옮길 때나 추가 예약 또는 숨김 리소스를 더해야 할 때 유용해요:

./securityadmin.sh \
  -backup my-backup-directory \
  -icl \
  -nhnv \
  -cacert ../../../config/root-ca.pem \
  -cert ../../../config/kirk.pem \
  -key ../../../config/kirk-key.pem

덤프한 파일을 다른 클러스터에 업로드하려면:

./securityadmin.sh -h production.example.com -p 9301 -cd /etc/backup/ -ts ... -tspass ... -ks ... -kspass ...

구성 YAML 파일을 Open Distro for Elasticsearch 0.x.x 형식에서 OpenSearch 1.x.x 형식으로 마이그레이션하려면:

./securityadmin.sh -migrate ../../../config/opensearch-security -ts ... -tspass ... -ks ... -kspass ...

이름	설명
`-backup`	실행 중인 클러스터에서 현재 Security 플러그인 구성을 가져와서 작업 디렉터리에 덤프해요.
`-migrate`	구성 YAML 파일을 Open Distro for Elasticsearch 0.x.x에서 OpenSearch 1.x.x로 마이그레이션해요.

기타 옵션

이름	설명
`-dci`	Security 플러그인 구성 인덱스를 삭제하고 종료해요. Security 플러그인 인덱스가 손상되어 클러스터 상태가 red가 된 경우에 유용해요.
`-dg,--diagnose`	진단 트레이스를 파일에 기록해요. 스크립트가 생성된 파일의 위치를 출력해요.
`-esa`	샤드 할당을 활성화하고 종료해요. 전체 클러스터 재시작을 수행하는 동안 샤드 할당을 비활성화했고 Security 플러그인 인덱스를 다시 만들어야 하는 경우에 유용해요.
`-w`	사용된 어드민 인증서에 대한 정보를 표시해요.
`-rl`	기본적으로 Security 플러그인은 인증된 사용자와 그들의 역할, 권한을 한 시간 동안 캐시해요. 이 옵션은 클러스터에 저장된 현재 Security 플러그인 구성을 다시 로드해서 캐시된 사용자, 역할, 권한을 무효화해요.
`-i`	Security 플러그인 인덱스 이름이에요. 기본값은 `.opendistro_security`예요.
`-er`	`opensearch_security` 인덱스의 복제본 수 또는 자동 확장 표현식을 명시적으로 설정해요.
`-era`	복제본 자동 확장을 활성화해요.
`-dra`	복제본 자동 확장을 비활성화해요.
`-us`	복제본 설정을 업데이트해요.

Windows 사용법

Windows에서는 securityadmin.sh에 해당하는 것으로, \path\to\opensearch-{{site.opensearch_version}}\plugins\opensearch-security\tools\ 디렉터리에 있는 securityadmin.bat 스크립트를 사용해요.

앞선 섹션의 예제 명령어를 실행할 때는 command prompt나 Powershell을 사용하세요. 작업 표시줄의 Start 옆에 있는 검색 상자에 cmd를 입력하면 명령 프롬프트가 열리고, powershell을 입력하면 Powershell이 열려요.

예를 들어 사용 가능한 모든 명령줄 옵션을 출력하려면 인수 없이 스크립트를 실행하세요:

.\plugins\opensearch-security\tools\securityadmin.bat

여러 줄로 된 명령어를 입력할 때는 캐럿(^) 문자를 사용해 명령줄에서 다음 문자를 이스케이프해요.

예를 들어 초기 설정(모든 YAML 파일)을 로드하려면 다음 명령어를 사용하세요:

.\securityadmin.bat -cd ..\..\..\config\opensearch-security\ -icl -nhnv ^
  -cacert ..\..\..\config\root-ca.pem ^
  -cert ..\..\..\config\kirk.pem ^
  -key ..\..\..\config\kirk-key.pem

문제 해결

securityadmin.sh 설정에서 흔히 발생하는 문제의 해결 방법은 Troubleshooting securityadmin.sh를 참고하세요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/security/configuration/security-admin/