설치 및 파라미터 설정

Docker-compose 및 Podman-compose 환경에서 SysMaster DB 8.3를 설치하는 과정이다.

참고

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

이때 로드된 컨테이너 이미지 목록은 다음과 같다.

• sysmaster-db-client:{version}

• sysmaster-db-sdm:{version}

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

• sysmaster-db-collector:{version}

• sysmaster-db-analyzer:{version}

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

• sysmaster-db-schema-registry:{version}

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

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

참고

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

---

2. Docker / Podman 서비스 정의

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

서비스	설명
client	사용자가 브라우저를 통해 접속하게 될 웹 서버
sdm	수집 정보를 조회하고 클라이언트와 통신하는 API 서버
tibero-master	관제 데이터베이스에 대한 상태 확인과 Admin 기능을 수행하는 서버
collector	관제 데이터베이스로부터 데이터를 수집하는 서버
analyzer	수집한 정보를 가공해 분석 및 저장하는 서버
metadb	UI 관련 설정 정보를 저장하는 DB 서버
repodb	관제 데이터베이스 수집 데이터를 저장하는 DB 서버
zookeeper	Kafka Broker 서버의 상태 관리
broker	Kafka Broker 서버
schema-registry	Kafka 메시지 프로토콜 관리

---

3. 설치 파라미터 설정

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

참고

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

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

CLIENT_PORT=80
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=1
LOG_FILE_SIZE=100MB
LOG_TOTAL_SIZE=1000MB
LOG_LEVEL=info
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=
TBM_HEAP_SIZE_MAX=
TBM_HEAP_SIZE_MIN=
PERFORMANCE_LOGGING=
LIMIT_SQL_HASH_COUNT=
# NGINX_RESOLVER=127.0.0.11  

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

파라미터 이름	설명	초기값
CLIENT_PORT	UI 접속 URL의 포트 번호	80
ADMIN_USERNAME	Admin 계정의 사용자 이름	admin
ADMIN_PASSWORD	Admin 계정의 암호	admin
COLLECTOR_PORT	수집 모듈(TPM Agent)이 접속할 포트 번호 [참고] 관제 DB에서 접속할 수 있도록 SysMaster 서버에서 열려 있어야 함	8292
METADB_PORT	Meta DB의 접속 포트 번호	25432
METADB_USER	Meta DB의 슈퍼 사용자 이름	sysmaster
METADB_PASSWORD	Meta DB의 슈퍼 사용자 암호	sysmaster
METADB_PATH	Meta DB의 데이터 파일 경로	./meta
METADB_CONF_PATH	Meta DB의 설정 파일 경로	./meta.conf
REPODB_PORT	Repository DB의 접속 포트 번호	15432
REPODB_USER	Repository DB의 슈퍼 사용자 이름	sysmaster
REPODB_PASSWORD	Repository DB의 슈퍼 사용자 암호	sysmaster
REPODB_PATH	Repository DB의 데이터 파일 경로	./repo
REPODB_CONF_PATH	Repository DB의 설정 파일 경로	./repo.conf
RETENTION_DAY	수집 정보의 보관 주기	7
LOG_PATH	로그 생성 위치	./logs
LOG_RETENTION_DAY	로그 파일 보관 주기	1
LOG_FILE_SIZE	로그 파일 하나의 최대 크기	100MB
LOG_TOTAL_SIZE	모듈 별 최대 로그 저장 용량	1000MB
LOG_LEVEL	모듈 별 로그 레벨	info
CONTAINER_LOG_PATH	컨테이너 내부 로그 경로 설정	/sysmaster/logs
KAFKA_MESSAGE_MAX_BYTES	카프카 메시지 사이즈 설정, 1MB ~ 2GB 범위로 설정 가능	20971520 Byte
TIME_ZONE	SysMaster DB 서버 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 기본 이미지는 openjdk:17-alpine 이다.
SDM_HEAP_SIZE_MIN	SDM의 최소 힙 크기	현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64 이다. [참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.
ANALYZER_HEAP_SIZE_MAX	Analyzer의 최대 힙 크기	현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4 이다. [참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.
ANALYZER_HEAP_SIZE_MIN	Analyzer의 최소 힙 크기	현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64 이다. [참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.
COLLECTOR_HEAP_SIZE_MAX	Collector의 최대 힙 크기	현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4 이다. [참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.
COLLECTOR_HEAP_SIZE_MIN	Collector의 최소 힙 크기	현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64 이다. [참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.
TBM_HEAP_SIZE_MAX	TBM의 최대 힙 크기	현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/4 이다. [참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.
TBM_HEAP_SIZE_MIN	TBM의 최소 힙 크기	현재 컨테이너 전체 메모리(free 명령어의 total mem 참고)의 1/64 이다. [참고] 현재 docker 기본 이미지는 openjdk:17-alpine 이다.
PERFORMANCE_LOGGING	성능 관련 로그 작성 여부 [참고] 추가적인 CPU, Disk를 사용하는 것이기 때문에 Y로 설정 시 성능 저하가 발생할 수 있음.	N
LIMIT_SQL_HASH_COUNT	중복 수집 방지를 위해 메모리에 저장하는 SQL plan hash value + cost 조합의 최대 개수이며, 동시에 SQL text hash value 최대 개수	100만개 [참고] 총 약 <등록된 인스턴스 개수> * 300MB 메모리를 차지한다.
NGINX_RESOLVER	Podman 환경 전용 설정 NGINX에서 DNS 이름을 해석하기 위해, Sysmaster 내부 DNS 네트워크의 게이트웨이 주소를 지정. 이설정은 Podman 환경에서만 필요하며, Docker 환경 등 다른 런타임에서는 별도의 설정이 요구되지 않습니다.	podman network inspect script_sysmaster 로 확인 가능.

참고 1

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

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

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

v8.1.3 이상의 SysMaster DB 서비스 이용 시, 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의 메뉴에서 과거(SysMaster DB v8.1.2 이하에서 수집된) 데이터 조회가 불필요한 경우

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

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

참고 2

SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH, RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH 파라미터는 신규 설치 시에는 필요하지 않고, SysMaster DB 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에서 신규 스키마 적용 대상 테이블의 과거(SysMaster DB v8.2.1 이하에서 수집된) 데이터 조회가 불필요한 경우

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

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

• 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일 이내의 데이터에 대해서만 마이그레이션이 수행됨.

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

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

3.1 Podman 환경에서 DNS Resolver 설정

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

아래 예시에서 NGINX_RESOLVER=10.89.0.1로 설정 후 시스마스터를 부팅하는 과정을 보여준다.

[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

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

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은 정상 접속되는 것으로 확인할 수 있다.

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

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

아래 예시처럼 서비스에 extra_hosts를 추가한다.

tibero-master:
  image: sysmaster-db-tibero-master:8.3.4
  container_name: tibero-master
  hostname: tibero-master
  environment:
    <<: *common-env
    # (기타 환경변수 생략)
  networks:
    sysmaster:
      aliases:
        - tibero-master
  restart: on-failure
  # 이 부분 추가
  extra_hosts:
    - "host.docker.internal:host-gateway"

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

---

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

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

파라미터 이름	설명
pg_max_connections	Meta DB(또는 Repository DB)의 최대 커넥션 수
pg_owner_id	해당 DB 데이터 디렉토리 접근 권한 설정을 위한 Host OS의 사용자 ID(uid). 호스트 머신의 특정 유저에서 컨테이너 DB 디렉토리로 직접 접근하고 싶을 경우 해당 유저의 사용자 ID로 설정한다.
pg_group_id	해당 DB 데이터 디렉토리 접근 권한 설정을 위한 Host OS의 사용자 그룹 ID(gid). 호스트 머신의 특정 유저에서 컨테이너 DB 디렉토리로 직접 접근하고 싶을 경우 해당 유저의 그룹 ID로 설정한다.
log_timezone	Meta DB(또는 Repository DB)의 로그 시간 Time-Zone

참고

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

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