WebtoB 프로세스 구조

WebtoB는 안정적인 서비스를 위해 프로세스가 비정상적으로 종료되면 자동으로 재기동합니다. 이때 기본적으로 Manager 프로세스와 Engine 프로세스를 함께 기동합니다.

figure webtob boot process

프로세스 종류

다음은 WebtoB의 프로세스 종류에 대한 설명입니다.

프로세스 이름 설명

Manager

비정상 종료된 Engine 프로세스를 재기동합니다.

Engine

HTTP 요청을 처리합니다.

WebtoB Manager와 WebtoB Engine의 설정은 반드시 일치해야 합니다.

두 프로세스의 설정이 일치하지 않는 경우, 기본적으로 Engine 설정으로 동기화하지만, Manager 설정으로 동기화할 경우에는 Engine을 종료 후 재기동합니다.

Manager 프로세스

Manager 프로세스는 HTTP 요청을 처리하는 웹 서버 프로세스(Engine)를 관리하는 역할을 합니다. Engine 프로세스를 모니터링하다가 비정상 종료될 경우 자동으로 재기동하며, 이미 기동 중인 Engine이 있을 때는 해당 Engine을 관리합니다.

다음과 같은 경우에는 Engine을 재기동하지 않습니다.

  • "/shutdown" API를 통해서 정상 종료한 Engine

  • 비정상 종료된 엔진 혹은 /restartengine API로 재기동한 엔진이 이미 사용 중인 포트로 재기동되어 재기동에 실패한 경우

위와 같은 경우에 Engine을 재기동하기 위해서는 Manager를 종료한 후 재기동하면 다시 Engine 재기동을 시도합니다. 중복된 포트 사용으로 재기동에 실패한 경우에는 포트를 변경 후 Manager를 재기동합니다.

Manager는 하나만 기동할 수 있습니다. WebtoB의 기본 기동 방식은 Manager와 Engine을 함께 기동하지만, 필요 시 다음 명령으로 Manager만 단독 기동할 수 있습니다.

> webtob -a start-manager

또한 REST API 방식의 Admin API를 제공합니다. Manager 포트는 NODE 절에서 설정하며 주요 API는 다음과 같습니다.

API 이름 설명

/config

환경 설정 내용을 조회합니다.

/shutdownmanager

WebtoB Manager를 종료합니다.

/restartengine

WebtoB Engine을 재기동합니다.

환경 설정 조회 (/config)

현재 동작 중인 시스템의 환경 정보를 조회합니다. 이 과정에서는 환경 설정 파일에서 지정한 값뿐만 아니라 기본적으로 적용되는 값까지 확인할 수 있습니다.

  • 사용법

    {
    "path": string
}
    옵션 설명

    path

    환경 설정 파일의 JSON 경로를 지정합니다. 이때 경로는 항상 /로 시작해야 합니다.
    경로를 생략하거나 /로 설정하면 현재 설정된 모든 환경 설정을 가져옵니다.

  • 예시

    다음은 NODE 절 환경 설정을 "/config" Admin API로 확인한 예시입니다. NODE 절의 설정 항목에 대한 자세한 설명은 NODE 절 설정 항목을 참고합니다.

    [Request]
{
    "path": "/node"
}

[Response]
{
    "result": {
        "cache_entry": 128,
        "cache_key": "HOST_URI",
        "cache_max_file_size": 8192,
        "connection_pool_size": 8192,
        "graceful_shutdown_timeout": 5,
        "hth_count": 1,
        "hth_schedule": "RR",
        "limit_request_body_size": 0,
        "limit_request_header_field_count": 100,
        "limit_request_header_field_size": 8190,
        "limit_request_line_size": 8190,
        "listen_backlog": 4096,
        "max_cache_memory_size": 100,
        "name": "webtob-server",
        "system_filters": [],
        "worker_threads": 1
    }
}

WebtoB Manager 종료 (/shutdownmanager)

동작 중인 WebtoB Manager를 종료합니다.

  • 사용법

    {
   "timeout": integer
}
    옵션 설명

    timeout

    graceful shutdown 과정의 타임아웃을 초 단위로 지정합니다. 지정된 시간이 지나도 WebtoB Manager가 종료되지 않으면 강제 종료됩니다.
    생략 시 /node/graceful_shutdown_timeout에 설정된 값이 적용됩니다.

  • 예시

    다음은 30초 동안 graceful shutdown을 시도한 후 WebtoB Manager가 종료되지 않으면 강제 종료하도록 "/shutdownmanager" Admin API를 호출하는 예시입니다.

    [Request]
{
   "timeout": 30
}

[Response]
{
   "result": {}
}

    응답은 WebtoB에서 명령을 수신한 직후 반환됩니다. 단, 응답을 받은 후에도 WebtoB Manager 프로세스가 동작 중일 수 있으며, WebtoB Manager를 종료하더라도 Engine은 종료되지 않습니다.

WebtoB Engine 재기동 (/restartengine)

동작 중인 WebtoB Engine을 강제로 재기동합니다. 재기동 과정에서 장애 분석용 core 파일을 생성합니다.

  • 사용법

    {
    "engine_index": integer,
    "make_core_file": boolean
}
    옵션 설명

    engine_index

    재기동할 Engine의 인덱스를 설정합니다. 설정하지 않으면 모든 Engine을 재기동합니다.

    make_core_file

    Engine을 재기동하기 전에 core 파일을 생성할지 여부를 설정합니다. (기본값: false)

    graceful_shutdown

    Engine 재기동 시 종료 방식을 설정합니다.

    • true: 처리 중인 요청을 모두 완료한 후 안전하게 종료(Graceful Shutdown)합니다. (기본값)

    • false: 요청 처리 여부와 상관없이 즉시 강제 종료합니다.

    graceful_shutdown_timeout

    Graceful Shutdown 방식을 선택한 경우, 종료 전 최대 대기 시간을 초 단위로 지정합니다. 지정된 시간이 지나도 WebtoB Engine이 종료되지 않으면 강제 종료합니다. (기본값: 60)

  • 예시

    다음은 Engine-1의 Graceful Shutdown을 시도하고 10초 동안 종료가 되지 않을 경우 강제 종료하고 재기동하는 예시입니다. 자동으로 "/restartengine" Admin API가 호출됩니다.

    [Request]
{
   "engine_index": 1,
   "graceful_shutdown_timeout": 10
}

[Response]
{
   "result": {}
}

Engine 프로세스

Engine 프로세스는 실제로 HTTP 요청을 처리하는 역할을 합니다. 각 프로세스는 인덱스를 가지며, 인덱스 번호는 0부터 시작합니다. 실행할 프로세스의 개수는 /node/engine_count에서 설정할 수 있습니다.

WebtoB가 기동 중인 상태에서도 engine_count 값을 변경한 후 WebtoB를 재기동하면 Engine 프로세스의 개수를 조정할 수 있습니다. 이와 관련된 내용은 Engine 수의 동적 변경을 참고합니다.

WebtoB의 기본 기동 방식은 Manager와 Engine을 함께 기동하지만, 필요 시 다음 명령으로 Engine만 단독 기동할 수 있습니다.

> webtob -a start-engine

또한 REST API 방식의 Admin API를 제공합니다. 자세한 내용은 WebtoB Admin API를 참고합니다.

로그 파일 이름에 %fullname% 또는 %pid%를 지정하면 각 프로세스별로 개별 로그 파일이 생성됩니다. 만약 %name%만 지정할 경우 Manager와 Engine 단위로만 로그 파일이 생성됩니다.

프로세스 권한 및 특권 포트

특권 포트 사용과 루트 권한 실행

웹 서버에서 일반적으로 HTTP는 80 포트, HTTPS는 443 포트를 사용합니다. 이 포트는 운영체제에서 특권 포트(1~1023에 해당하는 포트)로 분류되며, 루트(root) 권한을 가진 프로세스만 사용할 수 있습니다.

따라서 WebtoB가 해당 포트를 사용하려면 실행 시 루트 권한이 필요하고, 환경 변수도 루트 권한으로 설정해야 합니다.

figure process execution privileges and privileged ports

루트 권한으로 WebtoB를 실행할 경우 리눅스 보안 정책에 따라 기존에 설정된 환경 변수(라이브러리 경로 등)는 무시됩니다.

따라서 WebtoB 라이브러리를 정상적으로 불러오기 위해서는 해당 경로를 시스템 공유 라이브러리 설정(ld.so.conf)에 직접 등록해야 합니다.

다음은 특권 포트 사용을 위해 라이브러리 경로를 시스템에 등록하고, 루트 권한으로 WebtoB를 기동하는 예시입니다.

# WEBTOB_HOME 설정
> export WEBTOB_HOME=/home/webtob

# WebtoB 라이브러리 경로를 시스템 설정에 등록
> echo "${WEBTOB_HOME}/lib" | sudo tee /etc/ld.so.conf.d/webtob6.conf

# 변경된 라이브러리 설정 적용 (캐시 갱신)
> sudo ldconfig

# 루트 권한으로 WebtoB 실행 (환경변수 유지를 위해 -E 옵션 사용)
> sudo -E ./webtob

루트 권한 실행 시 문제점

WebtoB 바이너리를 루트 권한으로 실행하면 Manager 프로세스와 Engine 프로세스가 모두 루트 권한으로 기동됩니다. 그러나 Engine 프로세스는 외부 HTTP 요청을 직접 처리하므로, 루트 권한을 유지한 상태로 운영할 경우 보안 위험이 증가합니다.

다음은 WebtoB 바이너리를 루트 권한으로 기동했을 때 프로세스의 권한을 확인한 결과입니다.

> ps -eo pid,user,comm | grep WebtoB
 396052 root   WebtoB Manager
 396053 root   WebtoB Engine-0
 396054 root   WebtoB Engine-1
 396055 root   WebtoB Engine-2

Engine 권한 분리

WebtoB는 /node/user 설정을 사용하여 Engine 프로세스를 일반 사용자 권한으로 실행하도록 설정할 수 있습니다. 이때 지정할 수 있는 권한은 WebtoB 바이너리를 실행한 권한보다 낮아야 합니다.

/node/user 설정 예시
"node": {
    "user": "webtob"
}

루트 권한으로 WebtoB를 기동한 후 /node/user에 일반 사용자를 지정하면 다음과 같이 동작합니다.

  • Manager 프로세스는 루트 권한 유지

  • Engine 프로세스는 /node/user에 지정한 사용자 권한으로 실행

이 구조는 Manager가 특권 포트(1~1023)를 열고, Engine은 낮은 권한으로 운영되어 보안성을 높이는 데 유용합니다.

다음은 /node/user를 'webtob’로 설정한 상태에서 WebtoB 바이너리를 루트 권한으로 기동했을 때 프로세스의 권한을 확인한 결과입니다.

> ps -eo pid,user,comm | grep WebtoB
 396052 root    WebtoB Manager
 396053 webtob  WebtoB Engine-0
 396054 webtob  WebtoB Engine-1
 396055 webtob  WebtoB Engine-2

특권 포트(1~1023 포트) 사용을 위해 루트 권한을 사용하면서 user 설정을 통해서 Engine 프로세스의 실행 권한을 낮춘 경우에는 block listen 기능을 사용하지 않도록 합니다. (/destination/jeus/enable_block_listen=false로 설정)

block listen 기능을 사용할 경우, 서버가 서비스 불능 상태에서 복구되었을 때 Engine이 포트를 열게 되기 때문에 Engine도 루트 권한을 가져야 합니다.

Engine 수의 동적 변경

WebtoB가 기동되어 있는 상태에서도 Engine 수를 변경하여 Engine을 확장(Scale-out) 또는 축소(Scale-in)할 수 있습니다.

Engine 수의 동적 변경을 반영하기 위해서는 운영 중인 WebtoB 설정 파일에서 engine_count 값을 변경한 후 Engine 기동 명령을 수행합니다.

engine_count 외에 다른 설정도 변경한 경우 기동이 취소됩니다.

다음은 engine_count를 1에서 3으로 확장한 예시입니다. 변경된 설정은 즉시 적용되지만, 추가된 Engine은 수동으로 기동해야 합니다.

$ webtob
(...상단 로그 생략...)

WebtoB Engine-0 is already running. Comparing config....

(...중략...)

Starting Engine-1(93740) at Thu Jan 15 16:51:42 2026
Starting Engine-2(93741) at Thu Jan 15 16:51:42 2026
WebtoB Manager(93738) starts managing WebtoB Engine-1(93740)
WebtoB Manager(93738) starts managing WebtoB Engine-2(93741)

engine_count를 축소한 경우에는 실행 중인 Engine을 종료해야 하므로 사용자의 확인 절차를 거칩니다. 다음은 engine_count를 3에서 1로 축소한 예시입니다.

$ webtob
(...상단 로그 생략...)

WebtoB Engine-0 is already running. Comparing config....

WebtoB Engine-1 is already running. Comparing config....

WebtoB Engine-2 is already running. Comparing config....
Config Engine count is not match
Do you want to terminate WebtoB Engines that exceed the configured engine_count? (Y/N): y
WebtoB Engine is terminated normally. Stop managing WebtoB Engine-1(93740)
WebtoB Engine(93740) is stopped.
WebtoB Engine is terminated normally. Stop managing WebtoB Engine-2(93741)
WebtoB Engine(93741) is stopped.

(...중략...)

인덱스 값이 작은 Engine부터 순서대로 종료됩니다.

사용자가 Engine 종료를 거부(N)할 경우, 현재 운영 상태를 그대로 유지하며 설정 변경 작업을 취소합니다.

$ webtob
(...상단 로그 생략...)

WebtoB Engine-0 is already running. Comparing config....

WebtoB Engine-1 is already running. Comparing config....

WebtoB Engine-2 is already running. Comparing config....
Config Engine count is not match
Do you want to terminate WebtoB Engines that exceed the configured engine_count? (Y/N): n
Booting of WebtoB will be canceled

분리 기동 시 설정 동기화

분리 기동은 WebtoB Manager와 WebtoB Engine이 모두 기동되지 않고 어느 하나만 독립적으로 실행 중일 때 나머지 프로세스를 추가로 기동하는 경우입니다. 이때 실행 중인 프로세스의 설정과 새로 기동하는 프로세스의 설정이 다를 경우, 어느 쪽이 기준이 되느냐에 따라 동작 방식이 다릅니다.

figure separate startup flowchart

Manager가 기동된 상태에서 Engine을 추가 기동하는 경우

Manager가 먼저 실행 중인 상태에서 Engine을 Manager와 다른 설정으로 기동할 경우, Engine의 설정이 우선시됩니다. Manager는 기동하는 Engine의 설정이 자신의 설정과 다를 경우, Engine의 설정을 가져와 자신의 설정을 변경한 후 기동된 Engine을 관리합니다.

다음은 예시 화면입니다.

$ webtob
(...상단 로그 생략...)

Starting Engine-0(93739) at Thu Jan 15 16:51:42 2026
Success to load config files from WebtoB Engine.
+++ Configuration initialized successfully +++
WebtoB Manager(93738) starts managing WebtoB Engine-0(93739)

Manager와 기동되는 Engine의 설정이 동일한 경우, Manager는 즉시 Engine 관리를 시작합니다.

Engine이 기동된 상태에서 Manager를 추가 기동하는 경우

Engine이 실행 중인 상태에서 Manager를 기동할 때 설정 불일치가 감지되면, 다음 중 하나를 선택할 수 있습니다.

  • 현재 실행 중인 Engine 설정을 그대로 유지

  • Manager의 설정으로 Engine을 재기동

Engine 설정을 유지하는 경우(설정값: N)

다음은 Engine의 설정을 유지하는 경우의 예시입니다. Manager는 Engine의 설정을 가져와 사용합니다.

$ webtob
(...상단 로그 생략...)

WebtoB Engine-0 is already running. Comparing config....
Different values at: /node/hth_count
Manager: 3
WebtoB0: 1
Mismatch between loaded config and alive Engine-0 config.
Do you want to restart WebtoB Engine? (Y/N): n

Manager will start using Engine configuration instead of the file configuration.
Success to load config files from WebtoB Engine.
+++ Configuration initialized successfully +++

(...중략...)

WebtoB Manager(93738) starts managing WebtoB Engine-0(93739)

Manager 설정으로 Engine을 재기동하는 경우(설정값:Y)

다음은 기동되어 있는 Engine을 Manager의 설정으로 재기동하는 경우의 예시입니다. Engine을 모두 종료한 후 Manager와 동일한 설정으로 Engine을 재기동합니다.

$ webtob
(...상단 로그 생략...)

WebtoB Engine-0 is already running. Comparing config....
Different values at: /node/hth_count
Manager: 3
WebtoB0: 1
Mismatch between loaded config and alive Engine-0 config.
Do you want to restart WebtoB Engine? (Y/N): y

(...중략...)

WebtoB Engine(93739) is stopped.
Starting Engine-0(93740) at Thu Jan 15 16:51:42 2026
WebtoB Manager(93738) starts managing WebtoB Engine-0(93740)

Engine과 기동되는 Manager의 설정이 동일한 경우, Manager는 즉시 Engine 관리를 시작합니다.