WebtoB Admin API
WebtoB는 관리 기능을 Rest API를 이용한 Admin API를 통해 제공합니다. /server/admin 설정에서 포트를 지정하여 해당 포트를 통해 API 통신을 수행합니다.
config에서 admin 설정은 다음과 같이 수행합니다. 아래와 같이 설정하면 이후 9090 포트에 대해 Admin API 통신이 가능합니다.
"server":{
"admin": {
"port": 9090
}
}
다음은 Admin API가 제공하는 API에 대한 설명입니다.
| API 이름 | 설명 |
|---|---|
환경 설정 내용을 조회합니다. |
|
config 파일을 다시 읽어 적용 가능한 설정을 동적으로 반영합니다. |
|
접속 웹 브라우저를 확인합니다. |
|
연결 정보를 조회합니다. |
|
서버 그룹 정보를 확인합니다. |
|
프로세스, 스레드 및 서비스 상태에 대한 통계를 조회합니다. |
|
서버 프로세스의 통계 정보를 초기화합니다. |
|
WebtoB를 종료합니다. |
|
HTTP 응답 캐시에 저장된 응답들의 정보를 출력합니다. |
|
HTTP 응답 캐시에 저장된 응답을 삭제합니다. |
WebtoB Admin API의 주요 특징을 다음과 같습니다.
-
모든 API는 POST 메소드로 통신합니다.
-
HTH별로 동작하는 API의 경우 HTH가 일정 시간동안 응답이 없다면 타임아웃 이후 "busy_hth"에 표시됩니다. 예를 들어 /cliinfo API에 대해 HTH-1, HTH-2가 타임아웃동안 응답하지 않는 경우 해당 정보가 다음과 같이 "busy_hth"에 표현됩니다.
{ "result": { "HTH-0": [ { ... } ] }, "busy_hth": [ "HTH-1", "HTH-2" ] } -
API가 올바르게 동작한 경우 HTTP 응답 코드 200을 반환하고, 그렇지 않은 경우에는 상황에 따라 적절한 응답 코드를 반환합니다.
공통적으로 발생하는 에러 응답 코드는 다음과 같습니다.
응답 코드 설명 400
HTTP 본문에 대한 JSON 스키마 검증에 실패
401
사용자 인증에 실패
403
대상 API에 대한 동작 권한이 없음
404
대상 API가 없음
405
올바르지 않은 메소드로 요청
500
API 동작 중 에러가 발생 (API별로 발생하는 상황과 메시지가 다름)
-
응답 코드가 200이 아닌 경우 공통적으로 다음과 같은 방식으로 구성됩니다.
{ "error_code": string, "error_message": string }예를 들어 응답 코드가 404인 경우는 다음과 같이 발생할 수 있습니다.
{ "error_code": "APIERR_COMMON_0003", "error_message": "No such API" }
환경 정보
/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 } }
동작 상태 정보
/cliinfo
현재 접속된 클라이언트(주로 웹 브라우저)의 환경 정보를 조회합니다. 현재 상태(status), 접속 IP 주소, 처리 건수(count)와 같은 정보를 확인할 수 있습니다.
-
사용법
{ "http_server": string, "virtual_host": string, "hth_number": integer }옵션 설명 없음
서버에 연결된 모든 클라이언트의 정보를 조회합니다.
http_server
지정한 HTTP 서버에 연결된 클라이언트의 정보를 조회합니다.
virtual_host
지정한 가상 호스트에 연결된 클라이언트의 정보를 조회합니다. 단, http_server가 설정된 경우에만 설정이 가능하며 해당 값은 http_server에 포함된 가상 호스트 이름이어야 합니다.
hth_number
지정한 HTH에 연결된 클라이언트의 정보를 조회합니다. 지정하지 않으면 모든 HTH가 조회됩니다.
-
예시
다음은 HTH 3번에서 vhost1 가상 호스트에 연결된 클라이언트 정보를 "/cliinfo" Admin API로 확인한 예시입니다.
[Request] { "http_server": "http1", "virtual_host": "vhost1", "hth_number": 3 } [Response] { "result": { "HTH-3": [ { "no": 1, "idle": 24, "local_ipaddr:port": "192.168.15.167:8080", "remote_ipaddr:port": "192.168.15.168:48006", "request_count": 0, "response_count": 0, "ssl": false, "status": "READY", "http_server": "http1", "virtual_host": "vhost1" }, { "no": 0, "idle": 24, "local_ipaddr:port": "192.168.15.167:8080", "remote_ipaddr:port": "192.168.15.168:48005", "request_count": 2, "response_count": 2, "ssl": false, "status": "READY", "http_server": "http1", "virtual_host": "vhost1" } ] } }다음은 출력 항목에 대한 설명입니다.
출력 항목 설명 no
WebtoB 내부적으로 관리하는 커넥션 번호입니다.
idle
해당 클라이언트가 어떠한 데이터도 주고받지 않고 있는 상태로 지속된 시간입니다.
local_ipaddr:port,
remote_ipaddr:port서버와 클라이언트의 IP 주소와 포트 번호입니다.
request_count
해당 클라이언트가 전송한 요청 수입니다.
response_count
해당 클라이언트로 전송한 응답 수입니다.
ssl
해당 클라이언트가 SSL로 연결되어 있는지 여부입니다.
status
서버 내부의 클라이언트 상태입니다.
-
CONNECTING: 연결 시도 중
-
CONNECTED: 연결됨
-
READY: 클라이언트로부터 요청을 받는 중
-
RUNNING: 클라이언트의 요청이 서버에서 처리 중
-
DISCONNECTING: 연결 종료 시도 중
-
DISCONNECTED: 연결 종료됨
http_server
해당 클라이언트가 접속한 HTTP 서버입니다.
virtual_host
해당 클라이언트가 마지막으로 접근한 가상 호스트입니다.
-
/connectioninfo
현재 접속된 클라이언트(주로 웹 브라우저) 및 서버의 환경 정보를 조회합니다. 이를 통해 현재 상태, 접속 IP 주소, 처리 건수와 같은 정보를 확인할 수 있습니다.
-
사용법
{ "hth_number": integer }옵션 설명 없음
WebtoB에 연결된 모든 클라이언트 및 서버의 정보를 조회합니다.
hth_number
지정한 HTH에 연결된 클라이언트의 및 서버 정보를 조회합니다. 지정하지 않으면 모든 HTH가 조회됩니다.
-
예시
다음은 HTH 3번에 연결된 클라이언트 및 서버 정보를 "/connectioninfo" Admin API로 확인한 예시입니다.
[Request] { "hth_number": 3 } [Response] { "result": { "HTH-3": [ { "acceptor": "WJP-0", "request_count": 1, "response_count": 1, "counterpart": "", "idle": 3, "local_ipaddr:port": "127.0.0.1:9999", "no": 0, "remote_ipaddr:port": "127.0.0.1:44866", "remote_type": "JSV", "ssl": false, "status": "READY", "virtual_host": "" }, { "acceptor": "http1", "request_count": 2, "response_count": 2, "counterpart": "", "idle": 2, "local_ipaddr:port": "192.168.15.167:8080", "no": 10, "remote_ipaddr:port": "192.168.15.168:64223", "remote_type": "CLIENT", "ssl": false, "status": "READY", "virtual_host": "" }, { "acceptor": "", "request_count": 1, "response_count": 1, "counterpart": "", "idle": 2, "local_ipaddr:port": "192.168.15.167:60504", "no": 11, "remote_ipaddr:port": "192.168.15.124:8080", "remote_type": "RPROXY", "ssl": false, "status": "READY", "virtual_host": "" } ] } }다음은 출력 항목에 대한 설명입니다.
출력 항목 설명 no
WebtoB 내부적으로 관리하는 커넥션 번호입니다.
idle
해당 연결에서 데이터를 주고받지 않은 상태로 지속된 시간입니다.
local_ipaddr:port,
remote_ipaddr:port서버와 클라이언트의 IP 주소와 포트 번호입니다.
request_count
해당 연결로 전송한 요청 수입니다.
response_count
해당 연결로 전송한 응답 수입니다.
ssl
해당 연결이 SSL로 연결되어 있는지 여부입니다.
status
서버 내부의 클라이언트 상태입니다.
-
CONNECTING: 연결 시도 중
-
CONNECTED: 연결됨
-
READY: 클라이언트로부터 요청을 받는 중
-
RUNNING: 클라이언트의 요청이 서버에서 처리 중
-
DISCONNECTING: 연결 종료 시도 중
-
DISCONNECTED: 연결 종료됨
acceptor
해당 연결이 접속한 서버입니다.
virtual_host
해당 연결이 마지막으로 접근한 가상 호스트입니다. (클라이언트만 적용)
counterpart
해당 연결과 맺어진 반대쪽 연결의 번호를 의미합니다. 현재 연결이 클라이언트인 경우 counterpart는 서버 연결을 의미하고, 그 반대의 경우도 있습니다. 대기 상태의 WJP connection의 경우 -1로 나타날 수 있습니다.
-
/svginfo
현재 동작 중인 각 서버 그룹의 정보를 조회합니다.
-
사용법
{ "jeus" : array(string), "rproxy" : array(string) }옵션 설명 없음
모든 서버 그룹에 대한 정보를 확인할 수 있습니다.
jeus
JEUS 서버 그룹 이름을 지정합니다. "*"을 포함하면 모든 서버 그룹에 대한 정보를 확인할 수 있습니다.
rproxy
역방향 프록시 그룹 이름을 지정합니다. "*"을 포함하면 모든 서버 그룹에 대한 정보를 확인할 수 있습니다.
-
예시
다음은 모든 JEUS 서버 그룹과 rproxy1이라는 이름의 역방향 프록시 그룹 정보를 "/svginfo" Admin API로 확인한 예시입니다.
[Request] { "jeus" : [*], "rproxy" : ["rproxy1"] } [Response] "result": [ { "HTH-0": { "jeus": [ { "aqcnt": 0, "count": 0, "cqcnt": 0, "qpcnt": 0, "reqs": 0, "rscnt": 0, "status": "NRDY", "svgname": "MyGroup2" }, { "aqcnt": 0, "count": 0, "cqcnt": 0, "qpcnt": 0, "reqs": 0, "rscnt": 0, "status": "NRDY", "svgname": "MyGroup1" } ], "rproxy": [ { "aqcnt": 0, "count": 0, "cqcnt": 0, "qpcnt": 0, "reqs": 0, "rscnt": 0, "status": "RDY", "svgname": "rproxy1" } ] } } ]다음은 출력 항목에 대한 설명입니다.
출력 항목 설명 aqcnt
현재까지 큐에 대기했던 요청 수(cqcnt의 cumulative 값)입니다.
count
요청 처리 수입니다.
cqcnt
현재 큐에서 대기 중인 요청 수입니다.
qpcnt
큐에 대기 중이던 요청이 timeout 또는 qp 명령 등으로 인해 큐에서 제거된 요청 수입니다.
reqs
해당 서버에 보내진 요청 수입니다.
rscnt
해당 서버의 비정상 종료로 인한 재시작 횟수입니다.
status
서버 내부의 클라이언트 상태입니다.
-
RDY: 서버가 요청을 처리할 수 있으며, WebtoB와 연결된 서버 프로세스들이 존재함
-
NRDY: 요청을 처리할 수 없으며, WebtoB와 연결된 서버 프로세스가 존재하지 않음
-
BLK: 서버가 관리자 명령에 따라 일시 정지된 상태이며, 이로 인해 요청을 처리할 수 없음
svgname
환경 설정의 서버 그룹 이름입니다.
-
/statinfo
실질적인 시스템 동작 상태를 나타내며, 동작 중인 서버 프로세스와 서비스에 대한 정보를 조회합니다.
서버별로 처리한 서비스 개수, 커넥션 개수 등과 같은 동적인 정보를 확인할 수 있습니다.
-
사용법
{ "hth_number" : integer, "target":{ "jeus": array(string), "rproxy" : array(string), "htmls": boolean } }옵션 설명 hth_number
통계를 확인할 HTH 번호를 지정합니다.
target/jeus
통계 정보를 출력할 JSV 서버를 지정합니다. "*"이 포함되면 모든 JSV 서버에 대한 정보가 츌력됩니다.
target/rproxy
각 서버 상태를 출력할 역방향 프록시 서버를 지정합니다. '*'이 포함되면 모든 역방향 프록시 서버에 대한 정보가 츌력됩니다.
target/htmls
HTMLS 통계 정보의 출력 여부를 지정합니다.
target에서 최소한 1개 이상의 항목은 지정해야 합니다.
-
예시
다음은 MyGroup1이라는 JEUS 서버, rproxy1이라는 이름의 역방향 프록시 그룹 내 서버, HTMLS 서버 정보를 "/statinfo" Admin API로 확인한 예시입니다.
[Request] { "hth_number" : 1, "target":{ "jeus": ["MyGroup1"], "rproxy" : ["rproxy1"], "htmls": true } } [Response] { "result": { "HTH-0": { "jeus": [ { "average_processed_time": 0.0, "connections": 50, "request_count": 0, "response_count": 0, "server": "amV1c19kb21haW4vc2VydmVyMQ==", "server_group": "MyGroup1", "sticky_routed_count": 0 } ], "rproxy": [ { "average_processed_time": 0.0, "connections": 0, "request_count": 0, "response_count": 0, "server": "192.168.15.167:8090", "server_group": "rproxy1", "sticky_routed_count": 0 }, { "average_processed_time": 0.0, "connections": 0, "request_count": 0, "response_count": 0, "server": "192.168.15.167:8088", "server_group": "rproxy1", "sticky_routed_count": 0 } ], "htmls": { "average_processed_time": 0.000309519, "queue_count": 0, "request_count": 5, "response_count": 5, "server": "HTMLS" } } } }다음은 출력 항목에 대한 설명입니다.
출력 항목 설명 average_processed_time
요청당 평균 처리 시간입니다. (단위: 초)
connections
해당 서버에 연결된 커넥션 개수입니다.
request_count
해당 프로세스로 보내진 요청 수입니다.
response_count
해당 프로세스가 처리한 요청 수입니다.
server
서버 그룹에 속한 서버 이름입니다.
-
jeus: jengineid
-
역방향 프록시: 대상 서버 주소
-
HTMLS: HTMLS (고정)
server_group
서버 그룹 이름입니다.
sticky_routed_count
클라이언트로부터 받은 스티키(Sticky) ID를 기준으로 해당 서버에 라우팅한 횟수입니다.
-
/restat
서버 프로세스의 통계 정보를 초기화합니다. 호출 시 관련된 서비스나 서버 프로세스의 정보가 초기화됩니다.
-
사용법
{ "hth_number" : integer, "target":{ "jeus": array(string), "rproxy" : array(string), "htmls": boolean } }옵션 설명 없음
모든 HTH에 대해 초기화합니다.
hth_number
초기화할 HTH 번호를 지정합니다. 설정하지 않으면 모든 HTH가 초기화됩니다.
target
초기화할 대상을 지정합니다. 최소 하나 이상의 대상을 설정해야 합니다.
target/jeus
초기화할 JEUS 서버를 지정합니다. '*'이 포함되면 모든 JEUS 서버가 초기화됩니다.
target/rproxy
초기화할 역방향 프록시 서버를 지정합니다. '*'이 포함되면 모든 역방향 프록시 서버가 초기화됩니다.
target/htmls
HTMLS 통계의 초기화 여부를 지정합니다.
-
예시
다음은 "MyGroup1"이라는 이름을 가진 JEUS 서버의 통계 정보를 초기화하는 예시입니다.
[Request] { "target": { "jeus": ["MyGroup1"] } } [Response] "HTH-0": { "jeus": [ "MyGroup1" ] }각 HTH별로 초기화에 성공한 대상의 이름을 반환합니다.
프로세스 종료
/shutdown
동작 중인 WebtoB를 종료합니다.
-
사용법
{ "timeout": integer }옵션 설명 "timeout"
graceful shutdown 과정의 타임아웃을 초 단위로 지정합니다. 지정된 시간이 지나도 WebtoB가 종료되지 않으면 강제 종료됩니다.
생략 시 /node/graceful_shutdown_timeout에 설정된 값이 적용됩니다. -
예시
다음은 30초 동안 graceful shutdown을 시도한 후 WebtoB가 종료되지 않으면 강제 종료하도록 "/shutdown" Admin API를 호출하는 예시입니다.
[Request] { "timeout": 30 } [Response] { "result": {} }응답은 WebtoB에서 명령을 수신한 직후 반환됩니다. 단, 응답을 받은 후에도 WebtoB 프로세스가 동작 중일 수 있습니다.
캐시 정보 관리
/cachelist
현재 WebtoB의 HTTP 응답 캐시에 저장된 응답 정보를 출력합니다.
-
사용법
{ "hth_number": integer }옵션 설명 없음
모든 캐시 정보를 조회합니다.
"hth_number"
캐시 정보를 조회할 HTH 번호를 지정합니다.
-
예시
다음은 HTH 0번에 대한 캐시 정보를 "/cachelist" Admin API로 확인한 예시입니다. 요청 경로 외의 부분은 서버 내부 디버그 용도로만 사용됩니다.
[Request] { "hth_number": 0 } [Response] "result": { "HTH-0": { "cache_map": [ { "expire_time": "2023-10-25 16:35:18", "key": "192.168.15.167:8080/index.html", "size": 4312 }, { "expire_time": "2023-10-25 16:34:52", "key": "192.168.15.167:8080/favicon.ico", "size": 4507 }, { "expire_time": "2023-10-25 16:34:52", "key": "192.168.15.167:8080/4.html", "size": 219 } ], "cache_map_size": 3, "memory_usage": 9038 } }다음은 출력 항목에 대한 설명입니다.
출력 항목 설명 cache_map
캐시에서 관리하는 키(URI)와 관련 정보들을 반환합니다.
cache_map/expire_time
해당 아이템이 만료되는 시각입니다.
cache_map/key
해당 아이템의 URI입니다.
cache_map/size
해당 캐시 아이템의 전체 크기입니다.
cache_map_size
캐시에서 관리 중인 캐시 아이템 건수입니다.
memory_usage
캐시 아이템 콘텐츠에 대해 실제 사용 중인 메모리 총량입니다. (단위: byte)
/cacherefresh
WebtoB의 HTTP 응답 캐시에 저장된 응답을 제거합니다.
-
사용법
{ "url": string, "ext": string }옵션 설명 없음
캐시를 비웁니다.
url
삭제할 캐시의 URL을 지정합니다.
ext
삭제할 캐시의 확장자를 지정합니다.
url과 ext는 둘 중 하나만 설정할 수 있습니다.
다음은 캐시에 저장된 "test.domain.com/test.html" 응답을 "/cacherefresh" Admin API로 제거하는 예시입니다.
[Request] { "url": "test.domain.com/test.html" } [Response] "result": { "HTH-0": { "removed_count": 1 } }다음은 출력 항목에 대한 설명입니다.
출력 항목 설명 removed_count
삭제한 캐시 아이템 개수입니다.