모든 페이지
1 / 3

Loading...

Loading...

Loading...

Docker-compose / Podman-compose 환경

설치 및 파라미터 설정
기동 / 로그 확인 / 종료 / 초기화

구성

SysMasterDB 8.4 Docker-compose / Podman-compose 구성도

설치 및 파라미터 설정

Docker-compose 및 Podman-compose 환경에서 SysMasterDB 8.4를 설치하는 과정이다.

참고

Podman-compose는 Docker-compose 스타일의 yml 파일을 지원하기 때문에 동일한 yml 파일로 docker / podman 환경에서 모두 구동할 수 있다.

1. Docker / Podman 이미지 로드

설치 파일이 준비된 디렉터리에서 아래의 명령을 수행하여 Docker / Podman 이미지를 로드한다.

  • Docker:

    docker load -i sysmaster-db-{version}.tar
  • Podman:

    podman load -i sysmaster-db-{version}.tar

이때 로드된 컨테이너 이미지 목록은 다음과 같다. {version}은 이미지 태그(예: TIBERO-8.4.0)이다.

  • sysmaster-db-client:{version}

  • sysmaster-db-sdm:{version}

  • sysmaster-db-dbmanager:{version}

  • sysmaster-db-collector:{version}

  • sysmaster-db-analyzer:{version}

  • sysmaster-db-tiberoopensql-postgres:{version}

  • sysmaster-db-chatbot:{version}

  • sysmaster-db-kafka-loggable:{version}

  • sysmaster-db-zookeeper-loggable:{version}

  • sysmaster-db-client-tibero:{version}

  • sysmaster-db-alpine-linux:{version}


설치 디렉터리에서 docker-compose.yml 파일을 열어 Docker-compose / Podman-compose 환경에 생성하는 11개의 서비스에 대해 정의한다. 각 서비스에 대한 설명은 다음과 같다.

서비스
설명

설치 디렉터리에서 .env 파일을 열어 SysMasterDB 8.4의 설치에 필요한 파라미터 값을 설정한다.

이때 각 파라미터들은 개행으로 구분하며, 파라미터 이름과 값 사이에는 공백 없이 등호를 하나 입력한다.

해당 과정에서 설정하는 파라미터에 대한 설명은 다음과 같다.

파라미터 이름
설명
초기값

Rootless podman 환경에서는 NGINX_RESOLVER 패러미터 설정이 별도로 필요하다. 이는 SysMasterDB 기동 후 개별 컨테이너가 재기동 되는 상황에서의 재연결을 위해 필요하며 sysmaster 네트워크의 gateway ip 주소를 사용한다. 해당 값은 환경 / podman 기동마다 달라질 수 있다.

아래 예시에서 NGINX_RESOLVER=10.89.0.1로 설정 후 SysMasterDB를 부팅하는 과정을 보여준다. 네트워크 이름은 '<설치 디렉터리 이름>_sysmaster'이며, 예시는 설치 디렉터리가 script인 경우이다.

Podman bridge 네트워크 환경에서 SysMasterDB 컨테이너가 동일 호스트에 설치된 관제 DB에 호스트 IP(예: 192.168.141.12) 로 접속을 시도할 경우, 컨테이너 → 호스트 방향의 Hairpin NAT(DNAT loopback) 가 기본적으로 보장되지 않아 Connection Refused가 발생할 수 있다.

이는 동일 서버 내 구성이라도 컨테이너와 호스트가 서로 다른 네트워크 네임스페이스에 존재하기 때문에 발생하는 Podman bridge 구조적 제약이다.

예시로, 컨테이너에 접속하여 telnet 192.168.141.12 40010을 수행하면 Connection refused로 실패하고, Host Gateway 경로 적용 후 telnet host.docker.internal 40010은 정상 접속되는 것으로 확인할 수 있다.

해결을 위해 podman-compose.yml에 Host Gateway 매핑을 추가하고, 관제 DB 접속 주소를 호스트 IP → host.docker.internal 로 변경한다.

아래 예시처럼 dbmanager와 collector 서비스에 각각 extra_hosts를 추가한다. 두 서비스 모두 관제 DB에 직접 접속한다.

그리고 아래처럼 관제 DB IP를 host.docker.internal 로 설정하면 동일 호스트에 설치된 관제 DB를 등록할 수 있다.

client-gateway 서비스는 CLIENT_PORT에서 HTTPS로만 서비스한다. 따라서 브라우저 접속 URL은 https://{SysMasterDB 서버 IP 또는 호스트명}:{CLIENT_PORT} 형식이다.

인증서는 .env의 HTTPS_CERT_PATH에 지정한 호스트 디렉터리(비워 두면 ./https-cert)에서 읽는다. 이 디렉터리가 비어 있으면 최초 기동 시 이미지에 내장된 자체 서명 인증서가 자동으로 복사된다. 이 경우 브라우저에 인증서 경고가 표시되는 것이 정상이며, 경고를 확인하고 진행하면 로그인 화면이 열린다.

사이트 인증서를 사용하려면 기동 전에 아래 파일명으로 해당 디렉터리에 배치한다. 디렉터리에 파일이 하나라도 있으면 내장 인증서를 복사하지 않으므로 두 파일을 모두 넣어야 한다.

  • sysmaster-db-server.crt: 서버 인증서(PEM 형식)

  • sysmaster-db-server.key: 개인 키(PEM 형식)

운영 중에 인증서를 교체한 경우에는 client-gateway 컨테이너를 재기동해야 새 인증서가 적용된다.

Podman 환경에서는 podman compose restart client-gateway를 수행한다.


설치 디렉터리에서 meta.conf, repo.conf 파일을 통해 Meta DB 및 Repository DB 파라미터 값을 확인할 수 있다. 해당 conf 파일은 기본적으로 제공되는 설정값을 사용하되, 다음에서 설명하는 파라미터는 필요 시 구동 환경에 맞게 사용자가 직접 설정해준다.

파라미터 이름
설명

dbmanager

관제 데이터베이스에 대한 상태 확인과 Admin 기능을 수행하는 서버

collector

관제 데이터베이스로부터 데이터를 수집하는 서버

analyzer

수집한 정보를 가공해 분석 및 저장하는 서버

metadb

UI 관련 설정 정보를 저장하는 DB 서버

repodb

관제 데이터베이스 수집 데이터를 저장하는 DB 서버

zookeeper

Kafka Broker 서버의 상태 관리

broker

Kafka Broker 서버

chatbot

AI Chatbot의 질문을 처리하는 서버

ADMIN_USERNAME

Admin 계정의 사용자 이름

admin

ADMIN_PASSWORD

Admin 계정의 암호

admin

COLLECTOR_PORT

수집 모듈(TPM Agent)이 접속할 포트 번호

[참고] 관제 DB에서 접속할 수 있도록 SysMasterDB 서버에서 열려 있어야 함

8292

METADB_PORT

Meta DB의 접속 포트 번호

25432

METADB_USER

SysMasterDB가 Meta DB에 접속할 때 사용하는 사용자 이름. meta.conf의 pg_users에 있는 name과 같아야 한다

sysmaster

METADB_PASSWORD

SysMasterDB가 Meta DB에 접속할 때 사용하는 사용자 암호. meta.conf의 pg_users에 있는 pass와 같아야 한다

sysmaster

METADB_PATH

Meta DB의 데이터 파일 경로

./meta

METADB_CONF_PATH

Meta DB의 설정 파일 경로

./meta.conf

REPODB_PORT

Repository DB의 접속 포트 번호

15432

REPODB_USER

SysMasterDB가 Repository DB에 접속할 때 사용하는 사용자 이름. repo.conf의 pg_users에 있는 name과 같아야 한다

sysmaster

REPODB_PASSWORD

SysMasterDB가 Repository DB에 접속할 때 사용하는 사용자 암호. repo.conf의 pg_users에 있는 pass와 같아야 한다

sysmaster

REPODB_PATH

Repository DB의 데이터 파일 경로

./repo

REPODB_CONF_PATH

Repository DB의 설정 파일 경로

./repo.conf

RETENTION_DAY

수집 정보의 보관 주기

7

LOG_PATH

로그 생성 위치

./logs

LOG_RETENTION_DAY

로그 파일 보관 주기

30

LOG_FILE_SIZE

로그 파일 하나의 최대 크기

20MB

LOG_TOTAL_SIZE

모듈 별 최대 로그 저장 용량

1GB

LOG_LEVEL

모듈 별 로그 레벨

info

REPORT_PATH

TPR 리포트·ASH 리포트 파일이 저장되는 호스트 경로

./reports

CONTAINER_LOG_PATH

컨테이너 내부 로그 경로 설정

/sysmaster/logs

KAFKA_MESSAGE_MAX_BYTES

카프카 메시지 사이즈 설정, 1MB ~ 2GB 범위로 설정 가능

20971520 Byte

TIME_ZONE

SysMasterDB 서버 Time-Zone 설정

Asia/Seoul

SQL_FLUSH_THRESHOLD

SQL 관련 하나의 메시지가 담을 수 있는 정보 개수 제한. SQL Plan의 경우 해당 값의 10배로 제한한다.

관제 DB 당 100개

SQL_RS_FETCH_SIZE

한 번에 관제 DB로부터 조회하는 SQL 관련 정보 row 개수

관제 DB 당 1000개

SKIP_DB_USER_COUNT_MIGRATION_PATCH

(기설치 환경 패치 시,) 기수집 데이터 기반 Repository DB의 DB_USER_COUNT 테이블 데이터 생성 패치 생략 여부. 필요 시 아래 [참고 1]을 확인하고 설정.

true (주석 처리를 통한 미적용)

SKIP_DAILY_SEGMENT_MIGRATION_PATCH

(기설치 환경 패치 시,) 기수집 데이터 기반 Repository DB의 DAILY_SEGMENT 테이블 데이터 생성 패치 생략 여부. 필요 시 아래 [참고 1]을 확인하고 설정.

true (주석 처리를 통한 미적용)

SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH

(기설치 환경 패치 시,) v8.3.0 신규 스키마 적용 테이블 대상 v8.2.1 이하 기수집 데이터 마이그레이션 생략 여부. 필요 시 아래 [참고 2]를 확인하고 설정.

true (주석 처리를 통한 미적용)

RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH

(기설치 환경 패치 시,) v8.3.0에서 신규 스키마가 적용된 테이블에 대한 v8.2.1 이하 기수집 데이터 중 마이그레이션 대상 데이터 범위(일 단위 기간). 필요 시 아래 [참고 2]를 확인하고 설정.

7 (주석 처리를 통한 미적용)

SDM_HEAP_SIZE_MAX

SDM의 최대 힙 크기

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4이다.

[참고] 현재 docker 기본 이미지는 eclipse-temurin:17-jdk-alpine이다.

SDM_HEAP_SIZE_MIN

SDM의 최소 힙 크기

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64이다.

[참고] 현재 docker 기본 이미지는 eclipse-temurin:17-jdk-alpine이다.

ANALYZER_HEAP_SIZE_MAX

Analyzer의 최대 힙 크기

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4이다.

[참고] 현재 docker 기본 이미지는 eclipse-temurin:17-jdk-alpine이다.

ANALYZER_HEAP_SIZE_MIN

Analyzer의 최소 힙 크기

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64이다.

[참고] 현재 docker 기본 이미지는 eclipse-temurin:17-jdk-alpine이다.

COLLECTOR_HEAP_SIZE_MAX

Collector의 최대 힙 크기

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4이다.

[참고] 현재 docker 기본 이미지는 eclipse-temurin:17-jdk-alpine이다.

COLLECTOR_HEAP_SIZE_MIN

Collector의 최소 힙 크기

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64이다.

[참고] 현재 docker 기본 이미지는 eclipse-temurin:17-jdk-alpine이다.

COLLECTOR_AGENT_HEARTBEAT_TIMEOUT_MS

TPM Agent로부터 메시지를 받지 못해도 연결을 유지하는 허용 시간(ms). Agent의 최대 수집 주기보다 넉넉하게 설정한다.

300000

DBMANAGER_HEAP_SIZE_MAX

DBManager의 최대 힙 크기

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4이다.

[참고] 현재 docker 기본 이미지는 eclipse-temurin:17-jdk-alpine이다.

DBMANAGER_HEAP_SIZE_MIN

DBManager의 최소 힙 크기

현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64이다.

[참고] 현재 docker 기본 이미지는 eclipse-temurin:17-jdk-alpine이다.

PERFORMANCE_LOGGING

성능 관련 로그 작성 여부(.env에 기본 포함되지 않으며, 필요 시 추가한다) [참고] 추가적인 CPU, Disk를 사용하는 것이기 때문에 Y로 설정 시 성능 저하가 발생할 수 있음.

N

LIMIT_SQL_HASH_COUNT

중복 수집 방지를 위해 메모리에 저장하는 SQL plan hash value + cost 조합의 최대 개수이며, 동시에 SQL text hash value 최대 개수

100만개 [참고] 총 약 <등록된 인스턴스 개수> * 300MB 메모리를 차지한다.

SQL_BACKFILL_BATCH_SIZE

인스턴스 등록 전에 수행된 SQL을 백필 수집할 때 분당 수집하는 SQL 수. 값을 늘리면 백필이 빨리 끝나 캐시아웃으로 인한 누락이 줄지만 관제 DB 부하가 커진다. 0 이하로 설정하면 백필하지 않는다.

1000

NGINX_RESOLVER

client-gateway(NGINX)가 컨테이너 이름을 해석할 때 사용하는 DNS 주소. Docker 환경에서는 기본값(Docker 내장 DNS)을 그대로 사용한다. Rootless Podman 환경에서는 sysmaster 네트워크의 게이트웨이 주소로 바꿔야 하며, 아래 3.1을 참고한다.

127.0.0.11

HTTPS_CERT_PATH

client-gateway가 사용할 HTTPS 인증서 디렉터리(호스트 경로). 비워 두면 ./https-cert를 사용한다. 자세한 내용은 아래 3.3을 참고한다.

(빈값 = ./https-cert)

CHATBOT_SCHEMA_CACHE_TTL_SECONDS

(선택) chatbot 모듈이 Meta DB·Repository DB의 스키마 정보를 캐시하는 시간(초). .env에 기본 포함되지 않으며, 필요 시 추가한다.

86400

ACCOUNT_INACTIVE_LOCK_DAYS

장기 미사용 계정 잠금 마지막으로 사용한 뒤 이 기간(일)이 지나면 로그인, 토큰 재발급, 역할 변경을 막는다. 0 이하면 기능을 끈다.

0

ACCOUNT_REFRESH_TOKEN_EXPIRE_DAYS

Refresh Token 유효기간 0 이하면 따로 정하지 않은 것으로 본다. 이때 유효기간은 장기 미사용 잠금이 켜져 있으면 잠금 기간과 상한이 같다.

0

ACCOUNT_PASSWORD_HISTORY_COUNT

이전 비밀번호 재사용 금지 비밀번호를 바꿀 때 직전 N개와 같은 값으로는 바꿀 수 없다. 1~24로 설정 가능하다.

1

ACCOUNT_PASSWORD_CHANGE_DAYS

비밀번호 주기적 변경 안내 마지막으로 비밀번호를 바꾼 뒤(값이 없으면 계정을 만든 뒤) 이 기간이 지나면 로그인 응답으로 변경을 안내한다. 0 이하면 기능을 끈다.

0

SESSION_MAX_CONCURRENT_SESSIONS

계정당 동시 세션 수

  • 0이면 제한하지 않는다(기본).

  • 1 이상이면, 이 수를 넘는 로그인이 성공할 때 가장 먼저 로그인한 세션부터 끊는다.

0

SESSION_IDLE_TIMEOUT_MINUTES

유휴 세션 자동 로그오프(분) 0 이하면 기능을 끈다.

30

IP_RESTRICTION_TARGET

허용IP 외 접속차단서비스

  • NONE: 비활성화.

  • ADMIN: super admin과, 어느 그룹에서든 ADMIN 이상 역할이 있는 사용자에게만 적용한다.

  • ALL: 모든 사용자에게 적용한다.

NONE

IP_RESTRICTION_SUPER_ADMIN_IP

super admin의 허용 IP super admin의 허용 IP는 이 값으로만 정한다. IP_RESTRICTION_TARGET이 ADMIN 또는 ALL이라면 반드시 지정해야 한다.

빈값

IP_RESTRICTION_TRUSTED_PROXIES

프록시 대역

사내 PC 대역(10.0.0.0/8, 192.168.0.0/16 등)은 넣으면 안 된다. 그 대역의 PC가 헤더를 위조해 IP 제한을 피할 수 있다.

127.0.0.0/8, 172.16.0.0/12, 10.88.0.0/15

ACCESS_LOG_RETENTION_DAY

이벤트 로그 보관 기간(일) ACCESS_LOG ( 로그인/ 로그아웃 로그) 보관 기간을 설정한다.

0 이하면 기록, 보관, 삭제 정책이 모두 멈춘다. 이미 쌓인 데이터는 그대로 둔다.

365

log_timezone

Meta DB(또는 Repository DB)의 로그 시간 Time-Zone

client-gateway

사용자가 브라우저를 통해 접속하게 될 웹 진입점(리버스 프록시). HTTPS로 서비스하며 UI와 API 요청을 내부 서비스로 전달한다

client-tibero

UI 정적 자원(화면)을 제공하는 웹 서버

sdm

CLIENT_PORT=443
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin
COLLECTOR_PORT=8292
METADB_PORT=25432
METADB_USER=sysmaster
METADB_PASSWORD=sysmaster
METADB_PATH=./meta
METADB_CONF_PATH=./meta.conf
REPODB_PORT=15432
REPODB_USER=sysmaster
REPODB_PASSWORD=sysmaster
REPODB_PATH=./repo
REPODB_CONF_PATH=./repo.conf
RETENTION_DAY=7
LOG_PATH=./logs
LOG_RETENTION_DAY=30
LOG_FILE_SIZE=20MB
LOG_TOTAL_SIZE=1GB
LOG_LEVEL=info
REPORT_PATH=./reports
CONTAINER_LOG_PATH=/sysmaster/logs
KAFKA_MESSAGE_MAX_BYTES=20971520
TIME_ZONE=Asia/Seoul
SQL_FLUSH_THRESHOLD=100
SQL_RS_FETCH_SIZE=1000
# SKIP_DB_USER_COUNT_MIGRATION_PATCH=true
# SKIP_DAILY_SEGMENT_MIGRATION_PATCH=true
# SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH=true
# RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH=7
SDM_HEAP_SIZE_MAX=
SDM_HEAP_SIZE_MIN=
ANALYZER_HEAP_SIZE_MAX=
ANALYZER_HEAP_SIZE_MIN=
COLLECTOR_HEAP_SIZE_MAX=
COLLECTOR_HEAP_SIZE_MIN=
COLLECTOR_AGENT_HEARTBEAT_TIMEOUT_MS=300000
DBMANAGER_HEAP_SIZE_MAX=
DBMANAGER_HEAP_SIZE_MIN=
LIMIT_SQL_HASH_COUNT=1000000
SQL_BACKFILL_BATCH_SIZE=1000
NGINX_RESOLVER=127.0.0.11
HTTPS_CERT_PATH=
ACCOUNT_INACTIVE_LOCK_DAYS=
ACCOUNT_REFRESH_TOKEN_EXPIRE_DAYS=
ACCOUNT_PASSWORD_HISTORY_COUNT=
ACCOUNT_PASSWORD_CHANGE_DAYS=
SESSION_MAX_CONCURRENT_SESSIONS=
SESSION_IDLE_TIMEOUT_MINUTES=
IP_RESTRICTION_TARGET=
IP_RESTRICTION_SUPER_ADMIN_IP=
IP_RESTRICTION_TRUSTED_PROXIES=
ACCESS_LOG_RETENTION_DAY=

CLIENT_PORT

UI 접속 URL의 포트 번호(HTTPS)

443

[tibero@smdb-podman ~]$ podman compose up --no-start
[tibero@smdb-podman ~]$ podman network inspect script_sysmaster

[
     {
          "name": "script_sysmaster",
          "id": "e014d8811e9b51f417d578358ab41e2624a465d9026c7916f9ba7e4ce382f699",
          "driver": "bridge",
          "network_interface": "cni-podman1",
          "created": "2025-08-04T22:55:11.345378476-04:00",
          "subnets": [
               {
                    "subnet": "10.89.0.0/24",
                    "gateway": "10.89.0.1"  /// -> 이 주소를 사용.
               }
          ],
          "ipv6_enabled": false,
          "internal": false,
          "dns_enabled": true,
          "labels": {
               "com.docker.compose.project": "script",
               "io.podman.compose.project": "script"
          },
          "ipam_options": {
               "driver": "host-local"
          }
     }
]

/// .env 파일에 패러미터 설정하기
[tibero@smdb-podman ~]$ podman compose up -d
dbmanager:
  image: sysmaster-db-dbmanager:TIBERO-8.4.0
  container_name: dbmanager
  hostname: dbmanager
  environment:
    <<: *common-env
    # (기타 환경변수 생략)
  networks:
    sysmaster:
      aliases:
        - dbmanager
    edge: {}
  restart: always
  # 이 부분 추가
  extra_hosts:
    - "host.docker.internal:host-gateway"
docker compose restart client-gateway

pg_max_connections

Meta DB(또는 Repository DB)의 최대 커넥션 수

pg_owner_id

해당 DB 데이터 디렉토리 접근 권한 설정을 위한 Host OS의 사용자 ID(uid). 호스트 머신의 특정 유저에서 컨테이너 DB 디렉토리로 직접 접근하고 싶을 경우 해당 유저의 사용자 ID로 설정한다.

pg_group_id

참고

docker images | grep sysmaster 명령어를 통해 컨테이너 이미지 목록을 확인할 수 있다.

sysmaster-db-alpine-linux는 Kubernetes 환경에서 로그 확인·디버그용으로 쓰는 유틸리티 이미지로, Docker-compose / Podman-compose 환경에서는 기동되지 않는다.

2. Docker / Podman 서비스 정의

3. 설치 파라미터 설정

참고

.env 파일이 없다면 vim .env 명령어를 이용해 생성한다.

참고 1

SKIP_DB_USER_COUNT_MIGRATION_PATCH, SKIP_DAILY_SEGMENT_MIGRATION_PATCH 파라미터는 신규 설치 시에는 필요하지 않고, SysMasterDB v8.1.2 이하 기설치 환경에서 버전 업데이트를 수행하는 경우에만 적용이 필요하다.

각 파라미터를 별도로 설정하지 않으면, 버전 업데이트 시 해당 패치가 자동으로 수행되면서 기수집 데이터를 기반으로 DB_USER_COUNT, DAILY_SEGMENT 데이터를 생성한다.

이때, 기수집 데이터양에 따라 패치 수행에 장시간 소요될 수 있으므로, 해당 파라미터를 통해 사용자가 선택적으로 해당 패치 수행 여부를 설정할 수 있다.

v8.1.3 이상의 SysMasterDB 서비스 이용 시, DB_USER_COUNT, DAILY_SEGMENT 데이터는 각각 다음 메뉴에서 사용된다.

1. DB_USER_COUNT 데이터 - Analysis > All Session Flow 메뉴

2. DAILY_SEGMENT 데이터 - Analysis > Segment Usage 메뉴

따라서 해당 패치를 생략하도록 설정(각 파라미터를 true로 설정하고 주석 제거)하는 경우, 위 1, 2의 메뉴에서 과거(해당 업데이트 이전에 수집된) 데이터가 조회되지 않는다. 그러므로 기본적으로는 해당 파라미터를 별도로 설정하지 않는 것을 권장한다.

반면 다음과 같은 경우, 사용자는 해당 파라미터를 true로 설정(주석 제거)하여 앞서 설명한 패치를 생략할 수 있다.

  1. 위 1, 2의 메뉴에서 과거(SysMasterDB v8.1.2 이하에서 수집된) 데이터 조회가 불필요한 경우

  2. (SysMasterDB 서버 자원 제한 등의 이유로) 해당 데이터 생성 패치 진행 시 장시간 SysMasterDB 사용이 불가능해지는 상황이 우려되고, 이를 방지해야만 하는 경우

사용자는 필요에 따라, 해당 두 파라미터 중 원하는 파라미터만 선택적으로 설정하는 것도 가능하다.

참고 2

SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH, RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH 파라미터는 신규 설치 시에는 필요하지 않고, SysMasterDB v8.2.1 이하 기설치 환경에서 버전 업데이트를 수행하는 경우에만 적용이 필요하다.

각 파라미터를 별도로 설정하지 않으면, v8.3.0에서 신규 스키마가 적용된 테이블을 대상으로 v8.2.1 이하 버전에서의 기수집 데이터를 마이그레이션하는 패치가 자동으로 수행된다.

v8.3.0에서 신규 스키마가 적용된 테이블 목록은 다음과 같다.

  • SQL

  • SQL_TEXT

  • SQL_PLAN

  • DB_SESSION

  • SESSION_TEMP

  • SESSION_UNDO

  • LOCK

  • SQL_TRACE

위 테이블에 대한 마이그레이션 과정은 기수집 데이터양에 따라 장시간 소요될 수 있다.

사용자는 필요에 따라, 다음과 같이 별도 파라미터 설정을 통해 사용자가 선택적으로 해당 패치 수행 여부를 설정할 수 있다.

  • SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH

    • v8.3.0에서 신규 스키마가 적용된 테이블에 대해 v8.2.1 이하 기수집 데이터를 마이그레이션하는 패치 수행 여부를 설정

    • SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH 파라미터를 true로 설정(주석 제거) 시, 패치 대상 테이블 전체에 대한 마이그레이션이 수행되지 않음.

SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH 설정을 통해 마이그레이션을 수행하지 않은 경우, v8.2.1 이하에서 수집된 데이터가 삭제되므로 더 이상 조회되지 않는다.

그러므로 기본적으로는 해당 파라미터를 별도로 설정하지 않는 것을 권장한다.

반면 다음과 같은 경우, 사용자는 해당 마이그레이션 생략을 고려할 수 있다.

  1. v8.3.0에서 신규 스키마 적용 대상 테이블의 과거(SysMasterDB v8.2.1 이하에서 수집된) 데이터 조회가 불필요한 경우

  2. (SysMasterDB 서버 자원 제한 등의 이유로) 해당 데이터 생성 패치 진행 시 장시간 SysMasterDB 사용이 불가능해지는 상황이 우려되고, 이를 방지해야만 하는 경우

이때, 사용자는 아래 파라미터 설정을 통해 (마이그레이션 패치를 수행하되,) 패치 수행 대상 데이터 범위(일 단위 기간)를 별도로 설정할 수도 있다.

  • RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH

    • v8.3.0에서 신규 스키마가 적용된 테이블에 대한 v8.2.1 이하 기수집 데이터 중 마이그레이션 대상 데이터 범위(일 단위 기간) 설정

      • 예를 들어, RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH 파라미터를 7로 설정(주석 제거)하는 경우, v8.2.1 이하에서 수집된 데이터 중 최근 7일 이내의 데이터에 대해서만 마이그레이션이 수행됨.

상기 설명을 참고하여, 사용자는 운영 환경에 맞는 적절한 파라미터 설정을 선택, 적용할 수 있다.

3.1 Podman 환경에서 DNS Resolver 설정

3.2 Podman 환경에서 SysMasterDB 서버와 동일 호스트에 설치된 관제 DB 등록

설정 방법 (YML 예시 + 관제 DB 접속 주소 변경)

3.3 HTTPS 인증서 설정

4. Meta DB 및 Repository DB 파라미터 설정

참고

Meta DB 및 Repository DB 파라미터 변경이 필요한 경우, 관련 파라미터 설정은 OpenSQL 사용 가이드를 참조할 수 있다. 그러나 관련 파라미터 설정을 임의 수정하는 경우, SysMasterDB 서버의 정상 동작이 보장되지 않는다. 따라서 위 표에 명시된 파라미터 외 다른 파라미터는, 기본 제공 설정값을 그대로 사용하는 것을 권장한다.

특히 Podman-compose 환경에서의 설치 시, pg_owner_id와 pg_group_id 값을 직접 설정(변경)하는 경우 정상 동작하지 않을 수 있다. Podman의 컨테이너는 Rootless모드로 동작하고, 컨테이너 내부의 root (owner_id = 0, group_id = 0)가 호스트 머신의 유저에 대응된다. 하지만 OpenSQL이 root 권한 상태에서의 설치 및 기동을 허용하고 있지 않기 때문에 기본 설정값을 사용하는 것을 권장한다.

또한 Podman-compose 환경에서는 Host OS에서 조회되는 meta, repo 디렉터리의 소유자가 pg_owner_id, pg_group_id에 설정한 UID/GID에 대응하는 사용자명으로 표시되지 않을 수 있다.

이는 Podman rootless 환경의 user namespace 매핑 방식에 따른 정상 동작이다. Podman rootless 환경에서는 컨테이너 내부의 UID/GID가 Host OS의 UID/GID와 1:1로 동일한 사용자를 의미하지 않을 수 있다.

예를 들어 Host OS의 sysmaster 사용자가 uid=1008이고 pg_owner_id를 1008로 설정하더라도, 컨테이너 내부의 uid=1008은 Host OS에서 sysmaster가 아닌 subordinate UID로 매핑될 수 있다. 따라서 Host OS에서 meta, repo 디렉터리를 ls -al 명령으로 조회할 경우 소유자가 sysmaster가 아닌 숫자 UID/GID로 표시될 수 있다.

이는 권한 변경 실패나 제품 오류가 아니며, 컨테이너 내부에서는 매핑된 UID/GID 기준으로 정상 접근된다.

Host OS에서 숫자 UID/GID로 표시되는 데이터 디렉터리를 chown 등으로 임의 변경하지 않는 것을 권장한다. 임의로 소유자를 변경할 경우, 컨테이너 내부의 UID/GID 매핑과 파일 권한이 불일치하여 Meta DB 또는 Repository DB가 정상 기동하지 않을 수 있다.

수집 정보를 조회하고 클라이언트와 통신하는 API 서버

해당 DB 데이터 디렉토리 접근 권한 설정을 위한 Host OS의 사용자 그룹 ID(gid). 호스트 머신의 특정 유저에서 컨테이너 DB 디렉토리로 직접 접근하고 싶을 경우 해당 유저의 그룹 ID로 설정한다.

SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH 파라미터를 true로 설정(주석 제거)한 경우, 본 파라미터 설정은 무시됨.

기동 / 로그 확인 / 종료 / 초기화

Docker-compose 및 Podman-compose 환경에서 SysMasterDB 8.4를 기동, 로그 확인, 종료, 초기화하는 방법이다.

1. 기동

1.1. SysMasterDB 환경 변수 설정

export SYSMASTERDB_HOME={SysMasterDB_Home_Path}
인자
설명

{SysMasterDB_Home_Path}

docker-compose.yml 파일이 위치한 디렉터리 경로

1.2. SYSMASTERDB_HOME을 PATH에 추가

export PATH=$PATH:$SYSMASTERDB_HOME

1.3. 라이선스 파일 세팅

지정된 경로 하위에 발급받은 라이선스 파일을 배치한다. 라이선스 파일명과 경로는 아래와 같다. 파일명이 이 형식과 다르면 라이선스로 인식하지 않는다.

  • 라이선스 파일명

    • sysmaster-db-license.xml

    • sysmaster-db-license-{이름}.xml (예: sysmaster-db-license-30cores.xml)

  • 라이선스 경로

    • $SYSMASTERDB_HOME/license

$SYSMASTERDB_HOME 경로 하위에 license 디렉토리가 존재하지 않는 경우, 해당 디렉토리를 직접 생성해준 후 라이선스 파일(sysmaster-db-license.xml)을 넣어주면 된다.

Real 라이선스는 여러 파일을 함께 둘 수 있으며, 이때 관제할 수 있는 코어 수는 각 파일의 코어 수를 합한 값이다. Subscription·Demo·Trial 라이선스는 한 파일만 둘 수 있고, 타입이 다른 라이선스 파일을 함께 두면 라이선스가 적용되지 않는다.

--podman 옵션을 주면 podman-compose.yml 파일로 기동한다(파일이 없으면 docker-compose.yml을 사용한다). podman compose와 podman-compose 중 사용 가능한 명령을 자동으로 선택한다.

부팅이 완료되면 브라우저에서 https://{SysMasterDB 서버 IP 또는 호스트명}:{CLIENT_PORT} 로 접속한다. CLIENT_PORT의 기본값은 443이므로 기본 설정에서는 포트를 생략하고 접속할 수 있다. 자체 서명 인증서를 사용하는 경우 브라우저에 인증서 경고가 표시되며, 경고를 확인하고 진행하면 로그인 화면이 열린다. 사이트 인증서 적용 방법은 의 3.3을 참고한다.

부팅이 완료된 이후에 로그인과 프로그램 사용이 가능하다. 부팅 완료는 SDM 로그에서 아래와 같은 로그를 통해 확인할 수 있다.

이 로그가 출력된 뒤에도 dbmanager와 collector가 SDM에 처음 연결될 때까지는 브라우저 접속 화면이 열리지 않는다. 접속되지 않으면 잠시 기다린 뒤 다시 접속한다.


.env 파일의 로그 관련 파라미터 설정을 통해 로그가 저장될 경로를 지정할 수 있다. default 로그 경로는 ./logs이므로 docker-compose.yml 파일이 있는 디렉터리에 logs 폴더가 자동으로 생성되며, 여기서 로그 파일을 확인할 수 있다.


SysMasterDB 8.4 기동을 위한 환경 변수 및 PATH가 설정된 상태에서 아래의 명령을 수행하면 모든 서비스가 제거되고, SysMasterDB 8.4가 종료된다. 이때 SysMasterDB 8.4를 종료해도 METADB_PATH와 REPODB_PATH에 생성된 파일은 유지되므로, SysMasterDB 8.4를 다시 기동하면 종료 전과 동일하게 사용할 수 있다. Podman 환경에서는 sysmaster-db down --podman을 수행한다.


METADB_PATH와 REPODB_PATH 디렉터리를 삭제한 후 SysMasterDB 8.4를 다시 기동하면 최초 설치 상태와 동일하게 동작한다. 단, 이전에 저장한 데이터는 사용할 수 없다.

sysmaster-db up
sysmaster-db up --podman
Started SdmApplication in ... seconds (process running for ...)
sysmaster-db down
설치 및 파라미터 설정

참고

라이선스(기간 만료 등의 이유로) 파일 교체가 필요한 경우, 해당 경로 내 기존 라이선스 파일을 신규 라이선스 파일로 바꿔준 후 아래 명령을 수행하면 재기동 없이 갱신된다. 응답의 expirationDate가 새 라이선스의 만료일이면 갱신이 완료된 것이다. SysMasterDB 서비스를 재기동해도 새 라이선스가 적용된다.

docker compose exec sdm refresh-license

Podman 환경: podman compose exec sdm refresh-license

1.4. 실행

1.4.1. Docker-compose 환경

1.4.2. Podman-compose 환경

주의

--podman 옵션을 생략하면 기본값인 Docker 환경(docker compose)으로 기동한다. Podman 환경에서는 기동(sysmaster-db up --podman)과 종료(sysmaster-db down --podman) 모두 --podman 옵션을 붙여 실행한다.

1.5. 부팅 완료 확인 및 접속

2. 로그 확인

참고

client-gateway는 접속 로그(access.log)와 오류 로그(error.log)를 로그 경로 아래 client-gateway 디렉터리에 남긴다. client-tibero는 로그를 파일로 남기지 않으므로 docker compose logs client-tibero 명령으로 확인한다.

Podman 환경: podman compose logs client-tibero

3. 종료

4. 초기화