하늘구름™

Grafana CPU 정보 모니터링(ft. InfluxDB)

천풍훈 — Wed, 27 May 2026 13:26:09 +0900

들어가며.

오늘은 CPU 온도 정보를 함께 확인 및 저장하고 모니터링 툴(Grafana)에 추가하여 시각적으로 확인할 수 있도록 해보려고 한다.

해당 내용은 기존 InfluxDB 및 Grafana를 설치 이후 작업으로 필요시 아래 이전 설치정보를 참고해서 보도록 하자.

이전 모니터링 적용 정보는 아래 링크를 통해 확인해 보자.

InfluxDB + Grafana를 이용한 Proxmox 모니터링 적용

CPU정보를 확인하여 모니터링하는 것은 다음 네 가지 핵심 구성 요소로 이루어져 있다.

	역할	설치 위치
lm-sensors	시스템의 하드웨어 센서 정보를 읽어오는 도구	Linux OS
Telegraf	센서 정보를 파싱하여 InfluxDB로 전송	Linux OS
InfluxDB	수집된 시계열 데이터를 저장하는 백엔드	별도의 서버 (또는 같은 서버)
Grafana	InfluxDB에 저장된 데이터를 보기 좋게 시각화하는 대시보드 도구	별도의 서버 (또는 같은 서버)

데이터 흐름도

이 아키텍처는 데이터의 수집 > 전송 > 저장 > 시각화의 4단계 순서로 진행됩니다

단계	구성 요소	주요 동작	사용 기술/언어	데이터 형태
1. 수집	lm-sensors	센서 정보 읽기	sensors command, Shell Script	Plain Text > JSON/CSV
2. 전송	Telegraf	데이터 수집 및 전달	InfluxDB Protocol	Structured Data
3. 저장	InfluxDB (Time-Series DB)	시간순 데이터 저장	Time-Series Data	Structured Data
4. 시각화	Grafana (대시보드)	데이터 조회 및 표현	Flux/InfluxQL	Visual Chart Data

이제 하나하나 설치하며 진행해 보도록 하자.

1단계: lm-sensors 설치 및 데이터 확인

첫 번째 단계는 시스템이 센서 정보를 인식하고, lm-sensors가 정상적으로 작동하는지 확인하는 단계이다.

1.1. lm-sensors 설치

사용하는 Linux 배포판에 맞춰 간단하게 패키지를 설치 가능하다.

sudo apt update
sudo apt install lm-sensors

sudo yum install lm_sensors
# 또는
sudo dnf install lm_sensors

1.2.(선택사항) 센서 감지 및 설정

시스템에 연결된 센서를 검색하고 모듈을 로드한다.

실제로 각자의 시스템별로 이 부분은 모두 다른 형태로 나타나기 때문에 필요에 따라 CPU정보를 가져올 수 있도록 설정해야 한다.

sudo sensors-detect

[Tip] 이 명령어는 모듈을 확인하기 위하여 여러 질문을 나오는데. 특별한 이유가 없다면, 대부분의 질문에 YES를 입력하여 모듈을 활성화하는 것이 좋다.

sensors-detect 명령어를 통한 정보확인

1.3. 데이터 확인

설정이 완료되었다면, sensors 명령어를 통해 현재 센서 값을 확인한다. 이 출력정보 InfluxDB로 전송하여 저장해 보도록 하자.

sensors

CPU온도 정보 확인

2단계: Telegraf 설정 및 데이터 수집 (Docker Compose)

Telegraf는 시스템 명령어의 출력을 읽어와 InfluxDB 형식에 맞춰 전송하는 역할을 한다. 여기서는 자세한 사용법은 기술하지 않을 예정이니 필요한 경우 자세한 사용법을 찾아보도록 하자. [링크]

참고로 기존 Docker를 활용하여 InfluxDB + Grafana를 세팅하였기 때문에 해당 Compose파일에 Telegraf를 추가해서 사용해 보도록 하려고 한다.

2.1 Telegraf.conf 파일 생성

기존에 Telegraf를 사용하는 경우에는 관련 내용만 별도로 추가해서 사용하면 된다.

참고로 사용하는 파일 없는 경우 아래 명령어를 통해 기본 Telegraf.conf 파일도 생성이 가능하다.

Docker를 통한 신규 파일 생성

docker run --rm telegraf:latest telegraf config > ./telegraf.conf

그럼 InfluxData에서 제공하고 있는 sensors plugin 항목을 사용하여 데이터를 저장해 보도록 하자.

2.1.1 Inputs.sensors Plugin (센서 데이터 수집) 설정 [링크]

Plugin으로 lm-sensors를 통한 데이터를 기본적으로 제공해 주고 있기 때문에 [[inputs.sensors]] 를 추가해 주자.

필요에 따라 remove_numbers (Default : true) 설정만 수정해 주면 되는데 주석에 나와 있듯이 각각의 코어 항목에 일련번호를 넣을지 설정하는 것이다.

# Monitor sensors, requires lm-sensors package
[[inputs.sensors]]
  ## Remove numbers from field names.
  ## If true, a field name like 'temp1_input' will be changed to 'temp_input'.
  # remove_numbers = true

  ## Timeout is the maximum amount of time that the sensors command can run.
  # timeout = "5s"

2.1.2 Output Plugin (InfluxDB 전송) 설정 [링크]

Telegraf가 데이터를 InfluxDB로 전송하도록 본인의 정보를 설정한다.

[[outputs.influxdb_v2]]
  urls = ["http://influxdb:8086"] # influxdb server url
  token = "<Change Here!!>" #API Token Info
  organization = "<Change Here!!>" #Organinzation Info
  bucket = "<Change Here!!>" #Bucket Info

2.1.3 최종 telegraf.conf 파일

사설이 길었지만 결국 최종적으로 아래와 같은 telegraf.conf 파일을 생성하고, 각각 필요에 따라 수정해서 사용하면 된다.

# Configuration for telegraf agent
[agent]
  interval = "10s"
  round_interval = true
  metric_batch_size = 1000
  metric_buffer_limit = 10000
  collection_jitter = "0s"
  flush_interval = "10s"
  flush_jitter = "0s"
  precision = ""
  hostname = ""
  omit_hostname = false

[[outputs.influxdb_v2]]
  urls = ["http://influxdb:8086"] # influxdb server url
  token = "<Change Here!!>" #API Token Info
  organization = "<Change Here!!>" #Organinzation Info
  bucket = "<Change Here!!>" #Bucket Info

[[inputs.sensors]]
  ## Remove numbers from field names.
  ## If true, a field name like 'temp1_input' will be changed to 'temp_input'.
  # remove_numbers = true

  ## Timeout is the maximum amount of time that the sensors command can run.
  # timeout = "5s"

추가로 아래는 InfluxDB의 WEB UI를 통해 Telegraf.conf 파일을 간단히 생성할 수 있는데 이렇게 생성한 Telegraf 설정파일을 다운로드도 하고 API를 통한 호출도 가능하니 이 부분은 필요한 사람만 보면 될 듯하다.

InfluxDB WEB Telegraf.conf 생성방법

1. LoadData > Telegraf > CREATE CONFIGURATION

2. Sensors정보를 저장할 Bucket 선택 > LM Sensors Plugin 선택 > CONTINUE CONFIGURING

Sensors Telegraf.conf 파일생성

3. 생성할 Telegraf 이름 및 설명으로 본인이 확인하기 편하게 작성하면 된다.

참고로 [agent], [outputs] 정보는 기본적으로 작성되니 화면에 나와있는 [inputs] 정보에 대해서만 수정하면 된다.

4.Telegraf를 생성하게 되면 API Token 정보를 통해 원격으로 설정내용으로 호출이 가능하다.

여기서는 API를 사용할 것이 아니기 때문에 참고용으로만 확인하고 넘어 가자.

Sensors Telegraf.conf 파일생성

5. Telegraf 화면에서 방금 작성한 항목을 선택할 경우 DOWNLOAD CONFIG 버튼으로 설정파일을 다운로드 가능

Telegraf.conf 설정파일 다운로드

2.2 Telegraf Docker-Compose 생성 및 실행

이제 생성한 telegraf.conf 파일을 기반으로 Docker-compose를 생성하여 실행해 보도록 하자.

기존 Influxdb + Grafana 설치를 위한 Compose.yaml 파일에 추가

#Influxdb + grafana + telegraf compose.yaml
services:
  grafana:
    image: grafana/grafana
    container_name: grafana
    restart: always
    ports:
      - 3000:3000
    volumes:
      - grafana-data:/var/lib/grafana
  influxdb:
    image: influxdb:latest
    container_name: influxdb
    restart: always
    ports:
      - 8086:8086
    volumes:
      - influxdb2-data:/var/lib/influxdb2
      - influxdb2-config:/etc/influxdb2
  telegraf:
    image: telegraf:latest
    container_name: telegraf
    restart: always
    volumes:
      - ./telegraf.conf:/etc/telegraf/telegraf.conf:ro # 본인의 telegraf.conf파일 연결
      - /var/run/docker.sock:/var/run/docker.sock:ro
volumes:
  grafana-data:
  influxdb2-data:
  influxdb2-config:

Docker Compose 적용 및 실행

docker compose up -d telegraf

Telegraf Docker compose 적용

2.3. Telegraf를 통한 데이터 수집 확인

2.3.1 telegraf.conf 설정파일을 통한 수집 확인

기본적으로 Docker 가 실행되면 자동으로 미리 연결해 놓은 telegraf.conf 파일을 기준으로 자동으로 실행이 되는데

아래 명령어를 통해 정상적으로 수집이 되고 있는지 확인해 보자. 설정파일이 정상적이라면 문제없이 실행되었을 것이다.

--test 옵션은 정상적으로 수집되는 데이터를 확인하는 용도

docker exec -t telegraf telegraf --test

Telegraf 를 통한 CPU정보 수집확인

2.3.2 API를 통한 데이터 확인 ( 참고용으로 필요한 경우 사용 )

Telegraf를 생성했다면 Setup Instructions 항목에서 기본적인 정보 및 호출방법을 확인해 볼 수 있다.

기존 API Token정보가 있다면 `Telegraf Read` 권한을 부여해 사용해도 되고 팝업창에서 새로 생성해서 사용해도 된다.

(✅생성된 모든 API Token은 API TOKENS에서 확인 가능하다.)

Telegraf 설정 확인 및 API 실행

그럼 순서대로 실행해 보도록 하는데 우리는 Docker에 설치했으니 Docker로 진입해서 API호출을 실행해 보자.

Telegraf Docker 진입

docker exec -it telegraf /bin/bash

Token 정보 export ( Token을 별도로 관리하는 게 아니라면 Influxdb Web의 Telegraf 설정파일에 직접 지정해도 됨 )

export INFLUX_TOKEN=<본인 API Token정보입력>

API를 통한 telegraf 실행

telegraf --config http://192.168.0.145:8086/api/v2/telegrafs/10cc8c63fe987000 --test

이처럼 API를 통해서도 아래처럼 간단하게 확인가능하다.

API를 통한 Telegraf 수집 확인

2.3.3 Influxdb WEB UI에서 수집 데이터 확인

WebUI > Data Explorer 항목에서 본인의 정보에 맞춰 확인해 보면 정상적으로 데이터가 수집되고 있는 것을 확인할 수 있다.

InfluxDB WebUI 수집데이터 확인

3단계: Grafana 설정 및 대시보드 구성 (시각화)

이제 InfluxDB에 쌓인 데이터를 Grafana로 가져와 기존 생성했던 Proxmox 대시보드에 CPU 정보를 표시해 보도록 하자.

3.1 CPU정보 패널 추가

추가할 Dashboard > Edit > 표시할 패널 선택하여 Add Panel 선택

Dashboard 에 패널 추가

Configure visualization 선택 후 > All visualizations > Gauge 선택( ※해당항목은 본인이 원하는 스타일을 선택하면 됨 )

CPU정보에 대한 상세 패널 선택

3.2 데이터 확인 및 패널 상세설정

3.2.1 CPU정보 데이터 확인

Flux 문법을 이용한 Query를 호출하여 데이터가 정상적으로 호출되는지 확인
해당 조건은 각자의 조건에 맞게 수정해서 사용하면 된다.

from(bucket: "${Bucket}")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "sensors")
  |> filter(fn: (r) => r._field == "temp_input")
  |> filter(fn: (r) => r.feature == "package_id_0")

해당 Query를 호출하여 데이터가 정상적 조회가 되면 아래 화면과 같이 표현되는 것을 확인할 수 있다.

Influxdb CPU정보 데이터 확인

3.2.2 (선택사항) 패널 상세설정

위처럼 데이터 시각화 되었다면 끝이긴 하지만 가시성 있도록 패널에 몇 가지만 추가로 수정해 보도록 하자.

대메뉴	하위메뉴
Panel options	Title : 화면에 표시되는 타이틀 지정
Standard options	Unit : Temperature > Celsius(℃) Min : 0 Max : 100
Thresholds	Add threshold : 60%, 70%, 80% 90% 추가 Thresholds mode : percentage

간단하게 위처럼만 수정을 해준다면 아래와 같은 화면을 볼 수 있는데 필요에 따라 원하는 데로 우측 옵션을 조절해 사용하면 된다.

이후 저장을 통해 화면에 적용이 된 것을 확인할 수 있다.

CPU정보 패널 상세정보 설정

3.3 (선택사항) 모든 CPU 코어별 정보 확인

동일한 방식으로 나머지 CPU코어에 대한 정보도 표현해 보도록 하자.

Add Panel을 통해 Time serises 차트를 생성한다.

Time serise 챠트 생성

3.3.1 CPU Core정보 데이터 확인

Package를 제외한 나머지 core 정보만 가져오도록 한다.

from(bucket: "${Bucket}")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "sensors")
  |> filter(fn: (r) => r._field == "temp_input")
  |> filter(fn: (r) => r.feature != "package_id_0")

3.3.2 (선택사항) 패널 상세설정

이번에도 기존 CPU정보와 동일하게 가시성 있도록 패널에 몇 가지만 추가로 수정해 보도록 하자.

대메뉴	하위메뉴
Panel options	Title : 화면에 표시되는 타이틀 지정
Tooltip	Tooltop mode : All
Graph Styles	Fill opacity : 60 Gradient mode : Opacity
Standard options	Unit : Temperature > Celsius(℃) Min : 0 Max : 100
Thresholds	Add threshold : 60%, 70%, 80% 90% 추가 Thresholds mode : percentage

해당 패널 역시 필요에 따라 원하는 데로 우측 옵션을 조절해 사용하면 된다.

CPU Core Time Serises 정보 패널 설정

마치며...

이로서 길고 길었던 모든 적용이 완료되면 아래와 같이 CPU 온도 정보 및 각각 CPU Core정보를 한눈에 파악할 수 있다.

사실 전체적으로 보면 크게 어렵지 않게 적용할 수 있으며 추가하고 싶은 다른 데이터가 있다면 같은 형태로 추가해 주면 된다.

ps. 추가로 해당 정보를 통해 Grafana에서 제공해 주는 Alerting 기능을 사용한다면 CPU사용량 온도 Disk용량등 특정 수치값 이상인경우 메시지를 보내주는 기능도 구현가능하다. 해당 항목은 추후 별도로 작성하도록 하겠다

CPU 온도 정보가 추가된 모니터링 화면

InfluxDB + Grafana를 이용한 Proxmox 모니터링 적용

천풍훈 — Tue, 4 Nov 2025 15:43:57 +0900

들어가며..

보통 클라우드를 통해 서버를 이용할 경우 본인이 선택한 서버의 스펙에 따라 가격이 책정되는데 사양이 올라갈수록 가격이 올라가는 만큼 적정 수준의 스펙을 선택하여 사용하는 것이 바람직하다.

또한 요즘 MiniPC가 많이 보급됨에 따라서 가성비 저전력 MiniPC에 서버를 구축하는 경우도 종종 있는데 해당 경우에도 서버 정보를 한눈에 본다면 좀 더 효율적으로 관리할 수 있지 않을까 한다.

결론적으로 서버의 정보를 모니터링하여 서버의 가동률 및 실사용률 등을 파악해 좀 더 효율적인 관리를 해 볼 수 있도록 해보자.

사전적으로 필요한 정보는 아래 링크를 통해 확인해 보자.

Proxmox VE 리눅스 컨테이너(LXC) 생성

Docker 스크립트로 설치하기(ft.portainer)

1. Proxmox 모니터링

1.1 항목별 Summary Dashboard

Proxmox Web UI에도 기본적으로 Summary 항목의 Dashboard 통해서 각각 서버의 기본정보 및 항목별로 모니터링할 수 있는 화면이 존재한다.

Proxmox Datacenter > Summary
Datacenter > Cluster > Summary
Cluster > VM or CT > Summary

위와 같이 Proxmox 로컬 서버 및 클러스터, 클러스터 하위의 VM, CT 등 각 항목별로 Summary가 존재하며 해당 항목을 통해 기본적인 정보의 모니터링이 가능하며 이를 통해 서버의 정보 확인이 가능하다.

Promox 항목별 Dashboard Summary

해당 정보로도 파악은 가능하지만 좀 더 직관적이고 시각적으로 한눈에 파악하기 좋도록 모니터링 툴을 적용해 보도록 할 텐데,

Proxmox에서는 서버의 정보를 파악하여 확인할 수 있도록 Metric Server를 제공하고 있다.

1.2 Metric Server

1.2.1 Metric Server란?

Metric Server란 간단하게 서버의 CPU 및 메모리 사용량 같은 리소스 메트릭정보를 수집하여 제공하는 서비스를 말한다.

보통은 쿠버네티스(Kubernetes) 시스템에서 각 클러스트의 메트릭정보를 수집하여 제공하는 모니터링 오픈소스 서비스로서 많이 사용되며, 추가적으로 Prometheus, Elastic Stack, DataDog 등과 같은 애플리케이션도 존재한다.

오늘은 이게 주제가 아니니 필요한 경우 별도로 확인해 보도록 하자.

1.2.2 Metric Server 설정

해당 Metric Server 설정은 InfuxDB설치 이후 가능함으로 미리 확인만 하고 넘어가자.

Dtacenter > Metric Server > Add > InfluxDB

Proxmox Metric Server 추가

Proxmox에서 제공하는 Metric Server는 Graphite, InfluxDB 두 가지 선택지가 존재하는데 이 두 가지 모두 Metric Server로부터 정보를 전달받아 저장할 시계열 DB를 세팅하는 것이다.

보편적으로 많이 사용되는 InfluxDB를 설치하여 적용해 보도록 하자.

2. InfluxDB

대표적인 시계열 데이터베이스(TSDB)로서 간단하게 설명하자면, 시계열 데이터(Time series data - 시간의 흐름에 따라 발생하는 데이터)를 저장하도록 고안된 데이터베이스이다.

InfluxDB 버전
참고로 여기서는 InfluxDB OSS v2 버전을 사용하였다.
굳이 해당내용을 설명한 이유는 두 가지 버전의 핵심 개념 및 용어가 크게 변경되어 다르기 때문이다.

InfluxDB v1, v2버전 차이

구분 InfluxDB 1.x [링크] InfluxDB 2.x [링크]

아키텍처 단일 컴포넌트 아키텍처 마이크로서비스 아키텍처

핵심 개념/용어 Database, Retention Policy (DB/RP), User, Continuous Query Organization, Bucket, Token, Task (DB/RP 조합이 Bucket으로 변경됨)

인증 및 보안 사용자 이름/비밀번호 기반 인증 토큰(Token) 기반의 인증 및 권한 부여 시스템 도입

쿼리 언어 InfluxQL (SQL과 유사함) Flux(기본), InfluxQL 지원

데이터 모델 데이터 베이스, 태그(Tag)와 필드(Field)로 구분 태그와 필드 개념은 유지, 버킷(Bucket)에 저장

사용 편의성 CLI를 사용하여 관리 통합된 웹 UI 제공 (데이터 탐색, 시각화, 대시보드, 설정 등)

2.1 InfluxDB설치

설치는 Docker Compose를 통해서 간단하게 설치가 가능하다.

(선택사항) influxdb 폴더 생성

mkdir -p /services/influxdb && cd /services

compose.yaml 파일 생성 (Influx OSS v2 Docker-compose InstallGuide [링크])

공식 사이트에서는 설치 편의나 보안 이유로 secrets를 사용하는 방법으로 설정되어 있다.

설치 이후 해당 정보는 설정 가능하니 필요에 따라 설치하면 된다.

여기서는 간단하게 최소 설정만으로 설치를 진행해 보도록 하자.

# compose.yaml
services:
  influxdb2:
    image: influxdb:2
    ports:
      - 8086:8086
    volumes:
      - influxdb2-data:/var/lib/influxdb2
      - influxdb2-config:/etc/influxdb2
volumes:
  influxdb2-data:
  influxdb2-config:

Docker Compose를 통한 설치

docker compose up -d

Influxdb docker compose실행

2.2 InfluxDB 설정

2.2.1 Web UI접속

Influxdb를 설치하였으면 이제 Web관리 페이지에 접속해 보자

http://<본인의 서버 IP>:8086 정보로 접속하여 확인가능하다.

Influxdb Web 관리 콘솔 접속

2.2.1 Influxdb 관리계정 생성

최초 접속 시 아래처럼 초기 관리자 정보를 세팅하는 화면이 나오게 된다.

위에서 생성한 compose.yaml 작성 시 environment 부분을 미리 입력한 경우 해당 화면은 스킵되게 된다.

참고만 하고 넘어가도록 하자.

#compose.yaml 작성시 초기설정값 지정
....
environment:
      DOCKER_INFLUXDB_INIT_MODE: setup
      DOCKER_INFLUXDB_INIT_USERNAME_FILE: /run/secrets/influxdb2-admin-username
      DOCKER_INFLUXDB_INIT_PASSWORD_FILE: /run/secrets/influxdb2-admin-password
      DOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE: /run/secrets/influxdb2-admin-token
      DOCKER_INFLUXDB_INIT_ORG: <Initial Organization 항목> 
      DOCKER_INFLUXDB_INIT_BUCKET: <Initial Bucket 항목> 
....

계정생성 시 본인의 admin 계정에 대한 Token 정보를 확인할 수 있다. 해당 Token은 별도로 저장해 놓고 사용하도록 하면 된다.

하단에 버튼 3개 중 필요에 따라 누르면 계정생성은 마무리된다. 참고로 3가지는 메뉴이동이니 크게 신경 쓰지 않아도 된다.

Influxdb 관리계정 생성

API Token 정보 확인방법
가끔 생성한 Token정보를 기록해 놓지 않고 잊어버리는 경우기 존재하기에 influx cli를 통해 확인하는 방법을 알아보도록 한다.
1. 서버접속 후 docker로 실행 중인 influxdb container에 접속
docker exec -it influxdb /bin/bash
2. 서버접속 후 influx 명령어를 통해 config 정보 생성
- config는 Influxdb 인증정보를 세팅하기 위하여 실행 (해당과정을 하지 않을 경우 403 에러 발생)
#Default CLI Guide
influx config create \
  -n CONFIG_NAME \
  -u http://localhost:8086 \
  -p USERNAME:PASSWORD \
  -o ORG
아래처럼 본인의 ID/PW정보를 세팅하여 config를 생성해 주면 해당 계정으로 활성화된다.
참고로 -a 옵션은 해당 Config를 생성하면서 활성화해 주는 항목이며 패스워드에 특수문자 가존재하는 경우 '' 로 감싸주도록 하면 된다.
influx config create -a -n confName -u http://localhost:8086 -p admin:'12345678'
3. influx auth list 명령어를 통한 Token 정보 확인
influx auth list
Infulx CLI Token 정보확인

3. Proxmox와 Influxdb 연동

3.1 Influxdb Bucket 생성 및 API Token 발급

최초 계정생성 시 만들었던 Bucket 및 API Token정보가 존재하긴 하지만 권한설정이나 모니터링만을 위한 별도의 Bucket 및 API Token을 생성해 보도록 하자.

3.1.1 Bucket생성

Influx WEB > Load Data > Buckets > CREATE BUCKET

Influxdb Bucket 생성

3.1.2 API Token 생성

Custom API Token생성을 클릭하여 위에서 생성한 Bucket에 Read/Write 권한을 부여한다.

해당 API를 통해서 생성된 Bucket에 Proxmox 정보를 저장하도록 하는 것이다.

API를 생성하면 별도의 API Token이 생성되는데 해당 Token정보를 저장해 놓도록 한다.

Influx WEB > Load Data > API Tokens > GENERATE API TOKEN

Custom API Token 생성

3.2 Proxmox Metric Server 설정 및 데이터 확인

3.2.1 Proxmox Metric Server 설정

이제 InfluxDB에 새로 생성한 Bucket을 Proxmox의 Metric Server로 연결해 보도록 하자.

Server : 본인 Influxdb 서버 IP
Port : 8086 (변경한 경우 본인 포트 입력)
Protocol : HTTP
Organization : Influxdb Organization 명
Bucket : 생성한 Bucket명
Token : 생성한 API Token정보 입력

Dtacenter > Metric Server > Add > InfluxDB

Proxmox Metric Server 설정

연결이 정상적으로 완료되면 아래와 같이 등록된 것을 확인할 수 있다.

Metric Server InfluxDB 등록 완료

3.2.2 InfluxDB 데이터 확인

정상적으로 연동이 되었다면 일정주기로 InfluxDB Bucket에 자동 저 정 된다.

InfluxDB의 Data Explorer항목을 통해 Bucket에 저장되는 정보를 확인할 수 있다.

proxmox-monitor에 저장된 데이터 확인

4. Grafana

시계열 데이터 베이스와 연동하여 데이터를 시각화하여 보여주기 위한 애플리케이션으로 데이터를 통합하여 시스템 상태를 실시간 모니터링 할 수 있게 도와주며 다양한 대시보드를 제공하여 사용자가 원하는 유연한 형태의 화면 구성이 가능하다.

4.1 Grafana 설치

Grafana 역시 Docker를 통해 간단하게 설치해 보자.

Compose.yaml 수정 - 기존 InfluxDB 파일에 추가해 보자

compose.yaml에 grafana를 추가하고 기존 생성된 볼륨을 연결하여 사용할 수 있도록 external: true 옵션을 추가해 준다.

#Influxdb + grafana compose.yaml
services:
  grafana:
    image: grafana/grafana
    container_name: grafana
    restart: always
    ports:
      - 3000:3000
    volumes:
      - grafana-data:/var/lib/grafana
  influxdb:
    image: influxdb:latest
    container_name: influxdb
    restart: always
    ports:
      - 8086:8086
    volumes:
      - influxdb2-data:/var/lib/influxdb2
      - influxdb2-config:/etc/influxdb2
volumes:
  grafana-data:
  	external : true
  influxdb2-data:
 	external : true	
  influxdb2-config:
  	external : true

Docker Compose를 통한 설치

docker compose up -d

Influx & Grafana Compose 파일 실행

4.2 Grafana 설정

4.2.1 Grafana Web UI 접속

Grafana 역시 Web UI에 접속해 보자.

http://<본인의 서버 IP>:3000 정보로 접속하여 확인가능하다.

초기 아이디 / 패스워드 : admin / admin

Grafana WEB UI 접속

4.2.2 InfluxDB Data 연동

이제 InfluxDB에 적재된 데이터를 가져와 Grafana와 연동해 보도록 하자.

Grafana Home > Connections > Data Sources > InfluxDB

Query language : Flux 선택 (Influxdb 2.x 버전 SQL)
HTTP > URL : 본인의 influxDB Web 접속 URL (ex. http://192.168.0.119:8086)
InfluxDB Details : InfluxDB정보 입력
- Organization : 본인의 Organization 정보 입력
- Token : 생성한 Bucket API Token정보 입력
- Default Bucket : 생성한 Bucket정보 입력

Grafana + InfluxDB Data 연동

정상적으로 입력이 된 경우 Save & test 버튼 클릭 시 다음과 같이 정상적으로 연동된 것을 확인할 수 있다.

InfluxDB 연동 완료

생성된 influxdb Data Source에서 대시보드생성(Build a dashboard) 및 데이터확인(explorer)이 가능하다.

좌측메뉴에 대한 링크정보이니 참고만 하고 이제 그럼 데이터를 시각적으로 보여줄 대시보드를 생성하러 가보자.

4.2.2 Grafana Dashboard 생성

실제로 생성에 가면 한 땀 한 땀 생성을 해야 하지만 이미 다른 유능하신 분들이 만들어 놓은 대시보드들이 존재함으로 이미 만들어진 대시보드를 가져와 보도록 하자.

Grafana Dashboards : https://grafana.com/grafana/dashboards/?search=Proxmox&dataSource=influxdb

Proxmox에서 Influxdb를 사용하는 대시보드들을 확인할 수 있다.

대시보드에 들어가면 우측에 Copy ID to clipboard 버튼을 클릭하여 해당 대시보드 ID를 복사한다

참고로 Grfana 회원가입은 따로 하지 않아도 된다.

주의사항 - 대시보드 Influx2.x 버전 지원여부 확인
각 대시보드는 결국 Influxdb에 조회를 해서 데이터를 보여줘야 하는데 버전별로 문법이 차이가 있기 때문에 Influxdb 2.x버전 문법인 Flux 지원여부를 확인해야 함.
따로 확인방법이 있는 건 아니지만 제목에서 [Flux]라고 정의된 대시보드들은 대부분 Influxdb 2.x버전의 문법을 사용하는 것이기 때문에 해당 대시보드는 지원된다고 보면 된다.

Grafana Dashboards 확인

이제 다시 Grafana 사이트로 돌아와서 선택한 대시보드를 적용해 보자.

Home > Dashboards > Create dashboard

대시 보드를 가져올 것이기 때문에 Import a dashboard를 선택한다.
복사한 대시보드 ID를 입력 후 Load 버튼을 클릭한다.
정상적으로 로드된 경우 자신의 Influxdb를 선택하고 Import를 한다.

Grafana Dashboard 적용

4.2.3 Grafana Dashboard 확인

대시보드가 정상적으로 연동되었다면 다음과 같이 대시보드가 표시되는 것을 확인할 수 있다.

Grafana 대시보드 연동 확인

5. 마치며

이로서 길고 길었던 InfluxDB + Grafana를 연동한 Proxmox 모니터링 페이지가 완성되었다.

본인이 필요한 정보가 있다면 Infulxdb에 데이터를 입력하고 Grafana에서는 해당 대시보드에 추가해서 보여줄 수도 있으며 Alerting을 이용하여 특정 Rule을 생성하여 해당 Rule에 해당하는 경우 Push 알람서비스까지 제공하고 있다.

늘 그렇듯 이제 시작이다. 이제 한 발짝 내디딘 것일 뿐...ㅎ

NPM Plus 수동 설치하기(feat. Proxmox)

천풍훈 — Mon, 13 Oct 2025 17:02:35 +0900

들어가며..

여기서는 NPM Plus를 수동으로 설치하며 함께 사용가능한 추가기능 설치도 진행해 보려고 한다.

참고로 NPM Plus에 대한 설치 방법에 대해서만 작성예정임으로 기본적인 NPM Plus에 대한 정보 및 설치 시 필요한 항목에 대해서는 따로 정리해 놓은 글을 참조해 보도록 하자.

사전적으로 필요한 정보는 아래 링크를 통해 확인해 보자.

NPM Plus 설치하기(ft.Proxmox VE Helper-Scripts)

Proxmox VE 리눅스 컨테이너(LXC) 생성

Docker 스크립트로 설치하기(ft.portainer)

1. NPM Plus 설치

사실 NPM Plus에 대한 설치는 Github를 통해 배포되는 compose.yaml 파일을 통해 간단하게 설치 가능하기에 수동 설치라고 할만한 요소가 없을 수도 있다.

하지만 Docker compose를 통해 설치를 진행할 때 필요에 따라 설정을 변경하여 기능을 추가할 수 있으니 한번 진행해 보도록 하자

NPM Plus의 공식 사이트(Github) 정보는 아래에서 확인가능하다.

NPM Plus Github 링크 : https://github.com/ZoeyVid/NPMplus
NPM Plus Compose.yaml : compose.yaml

1.1 NPM Plus Quick Setup [링크]

아래 작성한 순서대로 진행해 보자.

(선택사항) Npmplus 폴더 생성 - 관리의 용의성을 위한 단계로 필요에 따라 진행하도록 하자.

mkdir -p /services/npmplus && cd /services/npmplus

comopose.yaml 파일 다운로드

curl -fsSL https://raw.githubusercontent.com/ZoeyVid/NPMplus/refs/heads/develop/compose.yaml -o docker-compose.yaml

NPM Plus Compose파일 다운로드

docker-compose.yaml 정보 수정

다운로드한 docker-compose.yaml에서 volumes, TZ, ACME_EMAIL 정보를 자신의 정보에 맞게 수정한다.

vi docker-compose.yaml

docker-compose.yaml 파일 수정

입력항목	필수여부	입력값	설명
volumes	필수	./data:/data	Docker와 연결할 Volume 디렉토리 지정 (각자의 설정에 맞도록 지정)
TZ	필수	Asia/Seoul	시간대 설정 (필수): "TZ identifier"에서 값 중 하나로 설정
ACME_EMAIL	선택사항	본인의 이메일	ACME(자동 인증서 관리 환경)에 사용될 이메일 주소: 현재 선택 사항이지만, 미래에 필요할 수 있으므로 입력 권장. Let's Encrypt에는 선택 사항이지만 ZeroSSL 및 Google Public CA에는 필수

Docker Compose를 통한 설치

아래 명령어를 통해 설치를 진행하면 NPM Plus를 손쉽게 설치할 수 있다.

설치가 완료되면 서비스도 정상적으로 실행되며 volumes에 연결한 data 폴더도 확인 가능하다.

docker compose up -d

Docker compose 를 통한 npm plus 설치

1.2 NPM Plus 사이트 접속 및 확인

관리자 사이트의 접속정보는 해당 Docker Container의 로그에 기록되어 있다.

Docker Container 정보 확인

docker ps -a

Docker Container ID 확인

컨테이너 로그를 통한 접속정보 확인

docker logs <컨테이너ID> | grep password

접속 정보 확인

위에서 확인 가능하듯 admin@example.org와 password를 통해 관리자 UI에 로그인 가능하다.

관리자 사이트 접속

https://<본인서버 IP>:81으로 접속하여 위에서 확인한 접속정보를 통해 로그인 가능하다.

NPM Plus 관리자 UI 접속

이처럼 기본적으로 설치가 완료된다면 Helper Script를 통한 NPM Plus설치와 동일하게 설치를 진행하게 된 것이다.

위에서 이야기하였듯 사실 NPM Plus 수동설치라고 하는 것은 Helper Script를 통해설치 하는 것에서 단지 Proxmox LXC컨테이너를 생성하고 Docker를 설치한 후 Compose.yaml파일을 수정/실행하는 작업을 수동으로 하고 있는 것뿐이다.

그럼 설치가 완료되었으니 이제 NPM Plus에 추가된 기능을 함께 적용해 보자.

2. 추가기능 설치 및 적용

추가기능이라고 하여 별도로 설치가 되는 것은 아니고 다운로드한 docker-compose.yaml에 주석처리된 부분을 하나씩 풀어가며 적용이 가능함으로 이 부분을 기억하고 가자.

그리고 각각의 모든 기능에 대해 논하진 않고 기본적으로 설치에 관하여만 작성하였으니 디테일한 설정 부분은 별도로 확인해서 적용하도록 하면 된다.

추가기능 부분은 Helper Script를 통해 NPM Plus를 설치한 경우에도 동일하게 적용가능하다.

Helper Script 설치 시 Compose File 위치 : /opt/comopose.yaml

2.1 Goaccess 적용

실시간 웹 로그 분석 프로그램으로 NPM Plus에 내장되어 있어 환경 변수(environemnt)를 수정하여 적용하는 것만으로 사용가능하다.

docker-compose.yaml 환경변수 수정

기존 docker-compose.yaml 파일에서 아래 3가지 항목만 주석을 풀어주면 된다.

- "LOGROTATE=true"
- "LOGROTATIONS=7"
- "GOA=true"

기존 주석을 모두 제거하고 아래와 같이 반영하여도 된다.

services:
  npmplus:
    container_name: npmplus
    image: docker.io/zoeyvid/npmplus:latest
    restart: always
    network_mode: host
    volumes:
      - "./data:/data"
    environment:
      - "TZ=Asia/Seoul"
      - "ACME_EMAIL=<본인의 이메일>"
      - "LOGROTATE=true"
      - "LOGROTATIONS=7"
      - "GOA=true"

docker-compose.yaml 재적용

docker compose down && docker compose up -d

docker-compose.yaml 재적용

Goaccess 페이지 확인

https://<본인서버 IP>:91으로 접속하면 아래와 같이 오픈소스를 통한 실시간으로 정보 확인이 가능하다.

NPM Plus에 기본적으로 적용이 되어있기 때문에 이렇게 환경변수 수정으로만 간단하게 확인이 가능하다.

상세한 설명 및 환경변수를 통해 포트나 추가적인 설정이 가능하긴 하지만 여기서는 패스하도록 한다.

Goaccess 적용 및 관리 화면

2.2 geoipupdate 설치

MaxMind의 GeoIP를 이용하여 접속 IP주소에 대한 정보파악용으로 Goaccess와 연동되어 GEO Location 페이지에서 접속정보를 파악할 수 있다.

2.2.1 MaxMind 회원가입

MaxMind는 별도로 회원가입을 진행해야 하며 Geolite2는 무료로 사용 가능하다.

MaxMind 회원가입 : https://www.maxmind.com/en/geolite2/signup

회원가입 후 Generate new license key를 통해 NPM plus에서 사용할 license정보를 추가하여 사용하면 된다.

참고로 License key정보는 발급당시 다운로드하여 놓거나 별도로 메모를 해두어야 한다.

발급 후에는 확인이 어려우니 별도 저장해놓지 않은 경우 삭제 후 새로 생성해야 한다.

Maxmind npmplus geoipupdate용 License 발급

2.2.2 geoipupdate 항목 적용

발급완료 시 geoipupdate 항목의 ACCOUNT_ID 및 LICENSE_KEY 항목에 본인 정보를 입력한다.

volumes 항목은 npm plus의 volumes 항목의 data/goaccess/geoip 항목을 연결해 주면 된다.

docker-compose.yaml 수정

# This can be used with GOA=true, to keep the geopip database updated, you need to change the envs to make it work
  geoipupdate:
    container_name: npmplus-geoipupdate
    image: ghcr.io/maxmind/geoipupdate:latest
    restart: always
    network_mode: bridge
    environment:
      - "TZ=Asia/Seoul"
      - "GEOIPUPDATE_EDITION_IDS=GeoLite2-Country GeoLite2-City GeoLite2-ASN"
      - "GEOIPUPDATE_ACCOUNT_ID=<your-account-id>" # needs to be changed
      - "GEOIPUPDATE_LICENSE_KEY=<your-license-key>" # needs to be changed
      - "GEOIPUPDATE_FREQUENCY=24"
    volumes:
      - "./data/goaccess/geoip:/usr/share/GeoIP"

docker-compose.yaml 재적용

docker compose down && docker compose up -d

npmplus geoipudate적용

위에서 보듯이 npmplus-geoipupdate가 실행되고 geoip폴더에 GeoLite2 항목들도 정상적으로 다운되어 적용된 것을 확인할 수 있다.

잠시 후 웹페이지에 접속해 보면 아래와 같이 GEO Location항목이 추가되고 접속정보를 확인할 수 있다.

Goaccess GEO Location 페이지 확인

2.3 crowdsec 설치

오픈소스 및 커뮤니티 기반의 실시간 침입방지 시스템으로 해당 항목도 주석을 풀어 간단한 정보 입력을 통해 적용가능하다.

volumes항목에 본인의 경로를 입력하도록 하며 마지막 openappsec부분은 openappsec설치 이후 진행하도록 한다.

docker-compose.yaml 수정

# This can be used to enable crowdsec, see README for a guide
  crowdsec:
    container_name: crowdsec
    image: docker.io/crowdsecurity/crowdsec:latest
    restart: always
    network_mode: bridge
    ports:
      - "127.0.0.1:7422:7422"
      - "127.0.0.1:8080:8080"
    environment:
      - "TZ=Asia/Seoul"
      - "COLLECTIONS=ZoeyVid/npmplus"
    volumes:
      - "./data/crowdsec/conf:/etc/crowdsec"
      - "./data/crowdsec/data:/var/lib/crowdsec/data"
      - "./data/nginx:/opt/npmplus/nginx:ro"
#      - "/opt/openappsec/logs:/opt/openappsec/logs:ro" # only uncomment if you also use the openappsec-agent container

docker-compose.yaml 재적용

docker compose down && docker compose up -d

NPM Plus crowdsec 적용

위와 같이 정상적으로 재적용되며 실행되는 것을 확인할 수 있다.

2.3.1 Crowdsec 설정

설정은 Github에서도 확인가능하다. : [링크]

Crowdsec npmplus 설정파일 생성

본인의 경로를 확인하여 해당 파일을 생성한다.

vi ./data/crowdsec/conf/acquis.d/npmplus.yaml

filenames:
  - ./data/npmplus/nginx/*.log
labels:
  type: npmplus
---
filenames:
  - ./data/npmplus/nginx/*.log
labels:
  type: modsecurity
---
listen_addr: 0.0.0.0:7422
appsec_config: crowdsecurity/appsec-default
name: appsec
source: appsec
labels:
  type: appsec
# if you use openappsec you can enable this
#---
#source: file
#filenames:
# - /opt/openappsec/logs/cp-nano-http-transaction-handler.log*
#labels:
#  type: openappsec

Crowdsec bouncer API key 생성

docker exec -it crowdsec cscli bouncers add nginx-bouncer

Crowdsec bouncer API key 생성

Crowdsec Configuration 파일 수정

해당 파일의 ENABLED 값을 true로 API_KEY 항목을 위에서 생성한 Key값으로 입력한다.

vi ./data/crowdsec/crowdsec.conf

crowdsec.conf 파일 수정

Docker Compose 재시작 및 확인

재시작 후 로그에 crowdsec 정보가 정상적으로 출력된다면 적용이 완료된 것이다.

docker compose restart

docker compose logs --tail 10 -f crowdsec

Crowdsec 실행 확인

아래 명령어를 통해 바운서 호출여부도 확인 가능하다.

docker exec -it crowdsec cscli metrics show bouncers

Crowdsec bouncers 확인

2.3.2 Crowdsec 차단 확인

정상적으로 동작하는지 확인을 위해 간단하게 본인 컴퓨터 IP를 차단하여 테스트해 보도록 하자

Crowdsec에서 호출되는 본인 아이피확인

접속 IP 차단

docker exec -it crowdsec cscli decisions add -i 192.168.0.40

본인 PC IP 차단

Crowdsec IP차단 확인

위와 같이 간단하게 차단 확인이 가능하다. 나머지는 개별적으로 확인해 보도록 하자.

Crowdsec cscli 명령어 확인 : https://docs.crowdsec.net/docs/next/cscli

2.4 openappsec-agent 설치

마지막으로 머신러닝 기반의 웹 애플리케이션 API 위협 보호 솔루션인 Openappsec도 설치해 보도록 하자.

Open-appsec NPM Plus 설치 가이드 : https://docs.openappsec.io/integrations/npmplus

2.4.1 openappsec 회원가입 및 프로파일 생성

아래 순서대로 진행해 보자.

Open-appsec 회원가입 : https://my.openappsec.io/
머신러닝 모델 다운로드

회원가입 후 오른쪽 상단의 본인 프로필 이미지를 클릭하여 Download advanced ML Model을 선택하여 다운로드한다.

Open-appsec 머신러닝 ML 모델 다운로드

Docker Profile생성 [링크]

1. 상단 Enforce항목을 선택하여 Profile생성 메뉴로 이동

2. 새로운 Docker Profile을 생성

3. Profile 설정 (순서는 상관없지만 편의상 화살표 방향으로 표시함)

Name : 본인이 구분하기 편한 이름입력
Sub Type : NGINX Proxy Manager + open-appsec 선택
Authentication 항목의 Token 항목 복사(추후 docker-compose.yaml 에 적용)
Management 항목 선택

4. 상단 Enforce항목을 선택 PUBLISH & ENFORCE POLICY 버튼을 통해 적용 완료

( 참고로 기존 정보 변경 후에도 Enforce 항목을 클릭하여 Publish를 진행해 줘야지만 정상적으로 반영이 완료된다.)

2.4.2 openappsec-agent 설정 적용

회원가입이 완료 이후 docker-compose.yaml에 openappsec-agent항목을 아래 순서대로 설정한다.

openappsec 폴더 생성

cd /services/npmplus && \
mkdir openappsec && \
mkdir ./openappsec/conf && \
mkdir ./openappsec/data && \
mkdir ./openappsec/logs && \
mkdir ./openappsec/localconf

다운로드한 머신러닝 모델파일 업로드

Proxmox의 호스트에 업로드하여 컨테이너로 복사하는 방식으로 사용한다.

컨테이너로 파일을 전송하는 방법은 각자의 상황에 맞도록 하면 될 것 같다.

#pct push <컨테이너ID> <Proxmox 경로> <컨테이너 경로>
pct push 100 /root/open-appsec-advanced-model.tgz /services/npmplus/openappsec/open-appsec-advanced-model.tgz

docker-compose.yaml 수정

#environment 주석 제거
- "NGINX_LOAD_OPENAPPSEC_ATTACHMENT_MODULE=true"

 #crowdsec volumes에 openappsec logs폴더 연결
 - "./openappsec/logs:/opt/openappsec/logs:ro"

# This can be used to run openappsec, you also need to set NGINX_LOAD_OPENAPPSEC_ATTACHMENT_MODULE to true and set ipc for NPMplus
  openappsec-agent:
    container_name: openappsec-agent
    image: ghcr.io/openappsec/agent:latest
    restart: always
    ipc: shareable
    volumes:
      - "./openappsec/conf:/etc/cp/conf"
      - "./openappsec/data:/etc/cp/data"
      - "./openappsec/logs:/var/log/nano_agent"
      - "./openappsec/localconf:/ext/appsec"
      - "./openappsec/open-appsec-advanced-model.tgz:/advanced-model/open-appsec-advanced-model.tgz"
    environment:
      - "TZ=Asia/Seoul"
      - "autoPolicyLoad=true"
      - "registered_server=NPMplus"
      - "user_email=<본인의 이메일>"
      - "AGENT_TOKEN=<appsec-token>"
    command: /cp-nano-agent

docker-compose.yaml 재적용

docker compose down && docker compose up -d

docker-compose.yaml 재적용

정상적으로 완료가 되었다면 위와 같이 모든 컨테이너가 정상적으로 실행될 것이다.

2.4.3 openappsec-agent 연결 확인

my.openappsec.io 홈페이지의 Agents항목을 보면 정상적으로 연결이 완료된 것을 확인할 수 있으며, Monotoring항목에서 관련 정보를 확인할 수 있다.

openappsec-agent 연결 확인 및 모니터링

3. NPM Plus 최종확인

아래는 최종적으로 적용한 docker-compose.yaml파일이다.

openappsec에는 별도의 sync, db 등 추가 컨테이너가 존재하는데 해당 항목은 각자의 필요에 따라 원하는 기능을 추가하여 사용하면 될 것 같다.

모든 것을 한 번에 다 적용할 필요 없이 본인에게 필요한 항목만 개별적으로 적용하면 된다.

docker-compose.yaml

services:
  npmplus:
    container_name: npmplus
    image: docker.io/zoeyvid/npmplus:latest
    restart: always
    network_mode: host
    volumes:
      - "./data:/data"
    environment:
      - "TZ=Asia/Seoul"
      - "ACME_EMAIL=<본인의 E-Mail>"
      - "LOGROTATE=true"
      - "LOGROTATIONS=7"
      - "GOA=true"
      - "NGINX_LOAD_OPENAPPSEC_ATTACHMENT_MODULE=true"
  geoipupdate:
    container_name: npmplus-geoipupdate
    image: ghcr.io/maxmind/geoipupdate:latest
    restart: always
    network_mode: bridge
    environment:
      - "TZ=Asia/Seoul"
      - "GEOIPUPDATE_EDITION_IDS=GeoLite2-Country GeoLite2-City GeoLite2-ASN"
      - "GEOIPUPDATE_ACCOUNT_ID=<maxmind-account-id>"
      - "GEOIPUPDATE_LICENSE_KEY=<maxmind-license-key>"
      - "GEOIPUPDATE_FREQUENCY=24"
    volumes:
      - "./data/goaccess/geoip:/usr/share/GeoIP"
  crowdsec:
    container_name: crowdsec
    image: docker.io/crowdsecurity/crowdsec:latest
    restart: always
    network_mode: bridge
    ports:
      - "127.0.0.1:7422:7422"
      - "127.0.0.1:8080:8080"
    environment:
      - "TZ=Asia/Seoul"
      - "COLLECTIONS=ZoeyVid/npmplus"
    volumes:
      - "./data/crowdsec/conf:/etc/crowdsec"
      - "./data/crowdsec/data:/var/lib/crowdsec/data"
      - "./data/nginx:/opt/npmplus/nginx:ro"
      - "./openappsec/logs:/opt/openappsec/logs:ro"
  openappsec-agent:
    container_name: openappsec-agent
    image: ghcr.io/openappsec/agent:latest
    restart: always
    ipc: shareable
    volumes:
      - "shm-volume:/dev/shm/check-point"
      - "./openappsec/conf:/etc/cp/conf"
      - "./openappsec/data:/etc/cp/data"
      - "./openappsec/logs:/var/log/nano_agent"
      - "./openappsec/localconf:/ext/appsec"
      - "./openappsec/open-appsec-advanced-model.tgz:/advanced-model/open-appsec-advanced-model.tgz"
    environment:
      - "TZ=Asia/Seoul"
      - "autoPolicyLoad=true"
      - "registered_server=NPMplus"
      - "user_email=<본인의 E-Mail>"
      - "AGENT_TOKEN=<Openappsec-access-token>"
    command: /cp-nano-agent

마치며..

이로써 길고 길었던 NPM Plus 수동 설치 및 추가기능에 대해 모두 적용해 보았다.

추가기능에 대해서 특별히 어렵지 않게 적용이 가능한 것 같지만 사실 이건 단순히 설치 및 기본 설정에만 해당하는 것이라 여기서 확장되는 부분은 개인의 노력이 필요할 듯하다.

참 쉽고도 멀다....ㅎ

Docker Compose 버전(v1, v2)

천풍훈 — Mon, 8 Sep 2025 15:57:22 +0900

들어가며.

우리는 Docker를 사용하면서 Docker Compose를 활용해 간단하게 여러 가지 서비스를 편리하게 관리 및 설치하여 사용해 왔다.

오늘은 Docker를 설치하고 그저 막연하게 사용하던 Docker Compose에 대해서 알아보기 위해서 정리해 보려고 한다.

참고로 여기서는 Docker Compose에 대한 사용법 등에 대한 설명을 하려는 것은 아니니 해당 내용에 대한 설명은 추후에 따로 정리해 보도록 하고.

그럼 Docker Compose에 대해 간단하게 알아보자

테스트 환경
- ubuntu22.04
- Docker version 28.4.0
참고로 Docker 설치는 Docker 스크립트로 설치하기(ft.portainer)를 참고하면 됨

1. Docker Compose란?

Docker Compose란? Docker의 개별 컨테이너를 하나의 서비스로 정의하여 각각의 컨테이너를 묶음으로 편리하게 관리할 수 있도록 작업환경을 제공하는 Docker의 관리도구이다.

Docker Compose를 이용하면 여러 컨테이너의 의존성, 네트워크, 볼륨 등을 함께 정의하여 관리할 수 있다.

이 때문에 관리해야 할 컨테이너수가 많거나 정의해야 할 옵션이 많다면 Docker compose를 이용하여 사용하는 것이 바람직하다.

그럼 간단하게 Compose 파일 생성하고 실행을 진행해 보자.

1.1 Compose 파일 생성

Docker compose는 yaml이라는 별도의 파일을 생성하여 관리한다.

간단하게 샘플로 Wordpress와 Mysql을설치하는 Compose yaml 파일을 작성해 보자.

mkdir -p /services/wordpress && cd /services/wordpress/
nano docker-compose.yaml

version: "3.9"

services:
  db:
    image: mysql:latest
    volumes:
      - ./db_data:/var/lib/mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: wordpress
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
  
  wordpress:
    depends_on: 
      - db
    image: wordpress:latest
    volumes:
      - ./app_data:/var/www/html
    ports:
      - "8000:80"
    restart: always
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress

1.2 Compose 파일 실행

docker-compose up -d

docker-compse 미설치 에러

정상적으로 짠!! 하고 실행될 줄 알았지만 우분투를 기준으로 위 명령어를 실행하면 docker-compose 명령어가 실행되지 않는다.

이때 우리는 docker-compose를 설치할 방법을 찾아보게 되는데....

1.3 docker-compose vs docker compose

docker-compose up
#or
docekr compose up

위에서 설명하였듯이 docker-compose를 설치하기 위해서 찾다 보니 docker compose, docker-compose처럼 실행 명령어가 제각각이다.

혹시 오타인가?? 아무거나 써도 될까?? 의문이 생긴다.

이 글을 쓴 목적이 여기에 있는데 인터넷에도 정보가 혼재되어 있으며 애매하게 사용했던 두 명령어의 차이에 대해 알아보도록 하자.

Docker Compose 명령어는 버전에 따라 차이가 있기 때문에 버전에 대해 먼저 알아보자.

2. Docker Compose 버전

모든 애플리케이션에는 서비스마다 각각의 버전이 존재하고 버전이 올라감에 따라 버그 수정 및 기능 향상 등 각 버전별 특징이 존재하기 마련이다.

Docker Compose 역시 V1버전과 V2버전이 존재하는데 결론먼저 이야기 하면 사실상 V1버전은 버그 수정 및 보안 문제에 대한 지원이 종료(EOL)되었기 때문에 Docker Compose는 V2버전을 사용해야 한다.

Docker Compose V1 지원종료(Docker compose V1 End of Life)

Docker roadmap에 올라온 이슈

Compose V2 정식 출시 발표

2.1 Docker Compose 버전별 특징

Compose의 두 가지 버전의 차이에 대해서는 정리하면 아래와 같다.

Compose V1 vs Compose V2

버전	Compose V1	Compose V2
명령어(Command)	docker-compose	docker compose (V2버전도 권장하진 않지만 docker-compose 명령어 사용이 가능하도록 Standalone 방식을 제공한다. )
작성언어(Language)	Python	Go
설치방법(Installaion)	Docker Engine과 별도로 설치되는 독립형(Standalone) Python 기반의 Binary 설치	Docker Desktop에 포함되며 Docker Engine에 플러그인(Plug-in) 형태로 설치된다
빌드(Build)	순차적 이미지 빌드	BulidKit을 사용하여 병렬로 이미지 빌드(빌드속도 개선)
컨테이너 생성(naming)	언더바('_')를 사용 (e.g. app_name_1) DNS와 호환되지 않는다.	하이픈('-')을 사용 (e.g. app-name-1) DNS와 호환된다.
Compose(yaml) 파일 특징	파일형식에 따라 최상위 version 항목 필요 (ex. version: 3.8)	version 항목 불필요 및 무시됨
Github 주소	별도의 브렌치로 관리 https://github.com/docker/compose/tree/v1	Main Github 사용 https://github.com/docker/compose
지원여부	2023.6월 지원종료(EOL)	개발 및 업데이트 진행

2.2 버전별 차이점

위 특징 부분에서 다 정리해 놓아서 특별히 차이점을 이야기할 필요가 있을까 하지만 가장 중요한 특징 몇 가지만 정리해 보자.

설치방법(Installaion)

실제로 내부에서 처리되는 Python이나 Go 부분과 처리 속도 등은 우리가 잘 느끼지 못하는 영역이지만 독립적인(Standalone) 설치형에서 플러그인 (Plug-in) 형태로 변경되면서 최근에는 Docker를 설치하게 되면 기본적으로 플러그인 형태로 자동으로 설치되기 때문에 별도로 설치하지 않아도 사용가능하다.

명령어(Command)

개인적인 생각으로는 우리가 가장 헷갈려하는 부분이기도 하며 가장 큰 변화가 아닐까 한다.

지금도 많이 사용하고 있는 docker-compose 명령어가 docker compose로 변경되었는데 아직도 여러 곳에서 이를 혼용하여 사용하고 있다.

docker compose로 명령어는 단순히 사용하는 입장에서 바뀐 것뿐만 아니라 가장 큰 차이는 기존 docker-compose를 설치 및 사용하기 위하여 Python의 pip를 사용해야 하는 등 Python 의존성에서 자유로워졌으며, Docker 내부의 네이티브와 통합되어 다양하게 사용가능하며 전반적인 성능도 향상되었다.

앞으로는 필요에 따라 V1버전을 꼭 써야 하는 경우가 아니라면 docker compose명령어로 사용하는 것이 좋을 것 같다.

Compose file(Yaml) 작성

Compose 파일 작성 시 기존 Legacy(V1) 버전에서는 Version항목(eg version '2.x', version '3.x')을 최상위 요소에 사용하여 해당 Compose의 릴리즈 정보에 기초하여 파일 포맷을 지정하였다.

- Compose file format versions 1 with Compose 1.0.0 in 2014
- Compose file format versions 2.x with Compose 1.6.0 in 2016
- Compose file format versions 3.x with Compose 1.10.0 in 2017

이 버전 정보에 따라 Compose파일 작성 시 사용가능한 매개변수가 다르기 때문에 버전이 달라지는 경우 Compose파일을 새로 수정해야 하는 상황이 발생하기도 하였다.

최신 Compose가 V2 버전으로 올라가면서 해당 버전 정보 필드 여부와 상관없이 최신 스키마를 사용하여 파일을 검증하도록 수정되었다.

이전 버전(2.x, 3.x)과의 호환성을 위하여 version 필드속성은 정보제공용으로 사용되며, 더 이상은 사용하지 않는다는 경고메시지가 출력됨에 따라 삭제하는 것을 권장한다.

3. Docker Compose 설치

최근엔 Docker Compose가 Docker 내에 plug-in 형태로 설치가 되지만 아직까지 예전의 설치 방법으로 설치도 진행되며 이 때문에 생기는 문제점 및 설치방 법들 역시 혼재되어 있어 정리를 해보자.

3.1. 플러그인 설치 [링크]

위에서 이야기하였듯 최신 Docker을 설치하게 되면 Compose는 Docker 내에 plugin 형태로 설치되게 된다.

혹시나 docker-compose-plugin이 설치되어 있지 않은 경우에만 별도로 설치하면 된다.

우분투(Ubuntu) 기준으로 아래와 같이 간단하게 설치가능하다. So Simple~

Docker Compose Plugin 설치

apt-get update
apt-get install docker-compose-plugin

Docker Compose 설치 확인

apt list docker*

Docker Compose Plugin설치 확인

3.2 (권장 안 함) Standalone 방식 설치 [링크]

혼재되어 있다는 게 아직도 해당 Standalone 방식으로 설치하는 경우가 많기 때문이며, 해당방법으로 설치하는 경우 때문에 docker-compose명령어도 계속 사용되고 있다.

설치파일 다운로드 및 설치

# 버전지정설치
curl -L "https://github.com/docker/compose/releases/download/v2.39.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 최신버전설치
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

참고로 버전정보(v2.39.4)는 각자 상황에 맞게 변경 가능하다.

* 버전정보 확인(https://github.com/docker/compose/releases)

바이너리 파일에 실행권한 적용

chmod +x /usr/local/bin/docker-compose

심볼릭 링크 설정 - Path 등록이 안 된 경우 어디서든 실행가능하도록

ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Path 설정 오류

docker-compose 설치확인

실제 docker-compose가 독립적(standalone)으로 설치되어 실행되지만 내부적으로는 docker compose와 동일한 명령어를 사용하는 것을 확인할 수 있다.

docker-compose 설치 확인

3.3 [지원종료] docker-compose(v1) 설치

해당 방법은 사용을 하지 않아야 한다는 차원에서 작성함‼️

Ubuntu 기준로 docker-compose를 처음 실행 할 당시 설치가 되어있지 않다면 하단에 친절하게 'apt install docker-compose'를 실행해 보라는 항목이 표시되기 때문에 고민하지 않고 해당 명령어로 설치를 실행하는 경우가 존재한다.

그럼 해당 명령어롤 통해 docker-compose를 설치해 보도록 하자.

docker-compse 미설치 에러

apt를 통한 docker-compose 설치

해당 명령어롤 통해 docker-compose를 설치해 보면 apt를 통해 간단한 게 설치가 마무리된다.

apt install docker-compose -y

docker-compose 설치확인

아래 버전 정보를 보게 되면 기존 Legacy(v1) 버전이 설치되는 것을 확인할 수 있습니다.

이렇게 되면 우리가 막연하게 사용하는 docker-compose는 v1버전으로 동작하는 것임으로 Python에러 등 우리가 생각지 못했던 갖가지 문제에 직면하게 될 것이다.

docker-compose version확인

마치며..

사실 사용하면서 매번 버전정보나 업데이트 정보를 확인해 가며 사용한다는 게 쉽지는 않다.

하지만 Docker Compose처럼 신경 쓰지 않고 편하게 사용하면서 매번 사용할 때마다 오류가 나면 그때그때 마다 해결해 사용하는 정도로 사용해 왔었다면 이런 궁금증을 한 번쯤 확인하고 넘어가는 것도 이후에 좀 더 편하게 사용할 수 있는 방법이 아닐까 생각한다.

Docker 스크립트로 설치하기(ft.portainer)

천풍훈 — Mon, 1 Sep 2025 17:22:27 +0900

1. Docker란?

Docker는 이제 너무나 많은 곳에서 사용하기에 설명이 필요할까 생각한다.

또 구체적으로 설명하자면 주제에서 벗어나기 때문에 간단하게만 확인하고 넘어가자.

그리고 이를 관리하기 위한 여러 툴들이 존재하는데 오늘은 portainer라는 관리툴 설치까지 함께 진행해 보자.

1.1 하이퍼 바이저(Hypervisor)

호스트 컴퓨터에서 다수의 운영 체제(operating system)를 동시에 실행하기 위한 논리적 플랫폼(platform)을 말한다. 가상화 머신 모니터 또는 가상화 머신 매니저(영어: virtual machine monitor 또는 virtual machine manager, 줄여서 VMM)라고도 부른다. (출처. 위키피디아)

하이퍼 바이저 에는 Type1, Type2, Type3 형태가 존재하게 되는데 Docker는 Type3 형태의 Container형 하이퍼바이저에 속한다.

Type3 - 'Container'형 하이퍼바이저

호스트 OS위에 컨테이너관리 소프트웨어를 설치하여, 논리적으로 컨테이너를 나누어 사용

장점 : 컨테이너 가상화는 오버헤드가 적어 가볍고 빠른 장점이 있음
종류 : Docker, LXC, LXD, CRI-O, Kata, Haconiwa

컨테이너 형태의 가상화 (출처 : tutorialspoint.com)

2. Docker 설치

2.1 Docker 설치 환경

위에서 보았듯 운영체제 위에서 컨테이너 형태로 실행되기 때문에 운영체제에 상관없이 설치 및 운영이 가능한 이점이 있다.

아래는 Docker 공식 사이트에서 제공하는 설치 지원 플랫폼정보이다. [링크]

또한 각 시스템 별로 설치방법을 제공하니 각 플랫폼 항목을 선택해 공식 설치 방법을 확인할 수 있다.

플랫폼	x86_64 / amd64	arm64 / aarch64	arm(32비트)	ppc64le	s390x
센트OS	✅	✅		✅
데비안	✅	✅	✅	✅
페도라	✅	✅		✅
라즈베리파이 OS(32비트)			✅
RHEL	✅	✅			✅
슬레스					✅
우분투	✅	✅	✅	✅	✅
바이너리	✅	✅	✅

2.2 Docker 설치 편의 스크립트 제공

사실 이 글을 작성한 목적은 여기에 있다.

각 OS 및 플랫폼 별로 설치방법이 약간씩 차이가 있는데 공식 설치방법을 보면서 설치하면 되긴 하지만 사실 약간 번거로운 부분이 존재하는데 Docker에서는 편의 스크립트를 제공해 간단하게 명령어 입력만으로 설치를 제공한다.

Docker Installation Srcipt : https://get.docker.com/
Docker sciprt Github : GitHub - docker/docker-install: Docker installation script

그럼 이제 해당 스크립트를 통해 설치를 진행해 보자.

2.3 스크립트를 통한 Docker 설치

사실 설치는 스크립트 실행만으로 간단하게 진행 가능하지만 필요한 패키지들이 존재함으로 아래 항목을 순차적으로 진행해 보자.

참고로 아래 Docker 설치는 Ubuntu 기준으로 설치를 진행함.
패키지 업데이트등 항목 및 필수 패키지 설치는 운영체제 별로 상이함. (RPM-based : yum 사용)

• 패키지 업데이트

apt update && apt upgrade -y

• 필수 패키지 설치

apt install curl -y

• 스크립트를 통해 Docker 설치

curl -fsSL get.docker.com -o get-docker.sh && sh ./get-docker.sh
or
curl -fsSL https://get.docker.com/ | sudo sh

Docker 설치 스크립트 실행

이 단계가 문제없이 정상적으로 완료되었다면 서버에 Docker가 정상적으로 설치된 것이다.

아래 단계를 통해 정상적으로 설치되었는지 확인해 보자.

2.4 Docker 설치 확인

• Docker 설치 확인

service docker status

Docker 서비스 상태 확인

• Docker 자동 실행 (부팅 시 자동으로 실행되지 않을 경우)

systemctl enable docker

Docker 서비스 자동실행

이로서 간단하게 스크립트를 통해 Docker를 설치 및 확인하였다.

보통 처음 시작한다면 CLI를 통해 명령어를 익혀야 구조나 사용 중 문제가 생겼을 때 해결할 때도 도움이 되긴 하지만 그것 또한 개인의 선택의 문제로 남겨두고 이제는 Docker를 Webui를 통해 사용할 수 있도록 하는 관리툴인 Portainer에 대해 알아보자.

3. Portainer 란?

CLI 버전의 Docker를 GUI를 통해 관리하기 위한 툴로서 Docker 이미지, 컨테이너, 볼륨 및 로그와 이벤트 확인 등 모든 작업을 Web UI를 통해 관리 및 설정할 수 있다.

사실 Windows에 설치하는 Docker Desktop기능을 Linux에서도 사용하게 해주는 관리 플랫폼이라고 볼 수 있다.

이외에도 Komodo, Dockge, Arcane이 존재하니 필요에 따라 설치해 보자.

3.1 Portainer 설치

Portainer는 상업용 BE(Business Edition) 버전과 개인용 CE(Community Edition)이 존재하는데 개인용 CE버전을 설치해 보자.

아래 링크를 통해 공식 페이지의 설치 방법도 확인 가능하다.

Install Portainer CE with Docker on Linux | Portainer Documentation

docs.portainer.io

• 데이터베이스 저장용 Docker 볼륨 생성

docker volume create portainer_data

Portainer Database Docker volume 생성

• Portainer Server 컨테이너 설치

각자의 설정에 따라 8000 / 9443 포트는 변경가능

docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts

Portainer Server Container 생성

• Docker Portainer 컨테이너 설치확인

docker ps

Portainer 설치 확인

Docker를 통해 설치하면 이처럼 간단하게 서비스 설치가 가능하다.

이제 간단하게 설치된 Portainer에 대해 확인해 보자.

3.2 Portainer 접속

포트의 변경이 없다면 https://본인의 서버 IP:9443으로 Portainer 관리 페이지에 접속 가능하다.

서버 접속 시 'Your Portainer instance timed out for security purposes' 메시지가 출력되는 경우 Portainer 서버 재기동을 통해 해결가능하다. [링크]
docker stop portainer
docker start portainer

Portainer 관리 페이지 접속

새로운 관리 계정입력을 생성할 수 있으며 기존 백업되었던 정보가 있다면 백업데이터를 복구하여 접속할 수도 있다.

3.3 Portainer WebUI 확인

간단하게 Get Started 클릭하여 접속해 보면 현재 서버의 Docker 정보를 확인할 수 있다.

자세한 사용법에 대해서는 별도로 다루지 않겠지만 WebUI인 만큼 간단한 건 항목을 눌러가며 확인해 볼 수 있을 것 같다.

Portainer WebUI 확인

NPM Plus 설치하기(ft.Proxmox VE Helper-Scripts)

천풍훈 — Wed, 30 Jul 2025 16:28:43 +0900

들어가며..

이전에 NPM(Nginx Proxy Manager)에 관하여 이야기한 적 있는데 이번에 이야기할 NPM Plus는 기본적으로 NPM에 대한 사전지식이 있다는 전제하에 작성하였기 때문에 해당 NPM에 대한 기본적인 정보를 알고 싶다면 기존 작성된 항목을 확인하고 오는 것이 이 글의 내용을 이해하는데 도움이 된다.

여기서는 NPM Plus의 설치에 대한 내용만 작성할 예정이다.

NPM의 기본적인 설명 및 자세한 사용방법에 대해서 알고 싶다면 아래 링크를 통해 확인해 보면 된다.

Proxmox에 NPM(Nginx Proxy Manager) 설치 및 SSL적용

하지만 NPM이 설치되고 NPM Plus가 설치돼야 하는 것이 아닌 각각의 서비스인 만큼 설치가 목적이라고 한다면 아래의 내용에 따라 설치하여 사용해도 된다.

그럼 이제 NPM Plus에 대해 알아보자.

1. NPM Plus란?

NPM Plus는 공식 NPM의 Github 프로젝트를 포크(fork) 해서 만든 서드파티 프로젝트라고 보면 될 것 같다.

그렇기 때문에 별도의 공식 홈페이지는 없고 Github나 기타 커뮤니티를 통해 전파되어 사용되고 있다.

NPM Plus Github 링크 : https://github.com/ZoeyVid/NPMplus

공식 NPM의 서드파티 프로젝트

최근엔 Proxmox 사용자를 위한 Proxmox VE Helper-Scripts 페이지에 NPMplus가 추가되어 설치하여 사용하기에 좀 더 수월해졌다 해당 부분도 아래에서 같이 이야기해 보자.

1.1 NPM Plus 사용 목적

우선적으로 고민해야 할 문제 이긴 한데 왜? NPM Plus를 설치하려는지 목적이 명확하게 구분되어야 할 것 같다

단지 Plus가 붙어서 좋아 보인다는 이유만으로 설치를 하기보다는 그 목적에 맞게 설치되는 게 맞는 것 같다.

NPM Plus인 만큼 공식적인 NPM의 기능 이외에 추가적인 기능들이 존재하긴 하지만 문제가 발생할 가능성 역시 존재함으로 본인이 필요로 하는 기능이 있다면 설치해 보도록 하며 기본적인 기능은 NPM만으로도 충분히 사용가능하다.

한 번쯤은 생각해 보자는 측면에서의 이야기이다.

1.2 NPM Plus 추가 기능

NPM Plus의 추가기능은 Github README 항목에 친절하게 설명되어 있다.

굉장히 많은 새로운 기능이 존재하는데 대표적인 것만 간단하게 정리하면 아래와 같다.

⁉️ 참고로 HTTP/3(Quic), modeSecurity 및 Goaccess는 기본적으로 포함되어 있지만 나머지 기능들은 사용하려면 추가로 설치해 사용해야 한다.

알파인 리눅스 기반 더 작은 도커 이미지
- 경량화하여 좀 더 빠르고 가벼운 이미지 구현
- 단점으로는 지원되는 아키텍처가 한정되어 있음(x86_64/amd64, aarch64/arm64)
HTTP/3(QUIC) 프로토콜 지원
- 최신 HTTP 3.0 기술로 UDP기반 QUIC 프로토콜을 사용하여 빠른 연결설정
- HOL 블로킹 문제점을 해결하여 전송속도가 향상된다.
CrowdSec IPS 지원
- 오픈소스 및 커뮤니티 기반의 실시간 침입방지 시스템
- 실시간 로그를 분석하여 악의적인 IP주소 탐지 및 차단하는 침입방지 시스템(IPS)
modSecurity 지원
- Apache, Nginx, IIS 등에서 다양한 플랫폼에서 사용되는 오픈소스 웹 애플리케이션 방화벽(WAF)
- HTTP 요청 및 응답을 필터링하여 웹 애플리케이션을 SQL Injection, XSS 등 다양한 웹 공격으로부터 보호하고, 침입을 탐지 및 차단
Open-appsec 지원
- 머신러닝 기반의 사전 예방적 웹 애플리케이션 및 API 위협 보호
- OWASP Top10 취약점 및 제로데이 공격으로부터 애플리케이션 보호
Goaccess 포함
- 오픈소스, 실시간 로깅 분석 및 웹 로그 분석 웹 서버입니다
- 콘솔 인터페이스를 통해 실시간으로 웹 서버 로그를 분석하고 시각화합니다.
geoipupdate 기능 지원
- MaxMind의 GeoIP를 이용한 특정 IP주소에 대한정보를 파악할 수 있다.
- Goaccess와 연동되어 GEO Location 페이지에서 서버 접속정보를 파악할 수 있다.

NPM Plus에 추가된 새로운 기능을 살펴보자면 보안측면에 있어 중점적으로 많은 기능들이 추가된 것 같다는 느낌이 든다.

이외에도 많은 기능들이 있으니 직접 한 번은 확인해 보는 것이 좋다.

그럼 이제 실제로 NPM Plus를 설치해 보자.

2. NPM Plus 설치

최근 Proxmox VE Helper-Scripts에 NPM Plus가 추가되어 NPM설치 때와 마찬가지로 우선 간단하게 설치 가능한 Script 통한 설치를 먼저 진행해 보자.

2.1 Proxmox VE Helper-Scripts를 통한 NPM Plus설치

2.1.1 사이트 접속 및 확인

Proxmox VE Helper-Scripts

The official website for the Proxmox VE Helper-Scripts (Community) Repository. Featuring over 300+ scripts to help you manage your Proxmox VE environment.

community-scripts.github.io

해당 링크를 통해 VE Helper-Scripts 사이트의 NPM Plus 항목을 확인할 수 있다.

추가로 빨간색으로 표시한 항목들은 로그인, 설치스크립트 및 추후 Docker Compose관련해서 필요하니 눈으로 한번 보고 넘어가자.

Proxmox VE Helper-Scripts의 NPMplus 화면

2.1.2 Script를 통한 NPMPlus 설치

본인의 Proxmox Shell에 접속하여 위 Helper-Scripts 사이트에서 확인한 아래 함수를 통해 설치를 진행할 수 있다.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/npmplus.sh)"

접속정보 : Proxmox Web > Datacenter > [본인노드] > Shell

Proxmox Shell에서 스크립트 실행

설치 시 기본 설정을 변경할 수도 있으며 해당 설정값은 설치 이후에도 변경 가능하니 Defalut Settings으로 진행해 보자.

이후 다음과 같이 설치가 진행 중 입력을 해야 하는 부분이 나오는데 입력정보를 확인해서 각자의 상황에 맞게 입력하면 된다.

VE Helper Script를 통한 NPM설치 진행

입력요청	필수여부	입력값	설명
Enter your TZ Identifier (e.g., Europe/Berlin)	필수	Asia/Seoul	시간대 설정 (필수): "TZ identifier"에서 값 중 하나로 설정
Enter your ACME Email	선택사항	본인의 이메일	ACME(자동 인증서 관리 환경)에 사용될 이메일 주소: 현재 선택 사항이지만, 미래에 필요할 수 있으므로 입력 권장. Let's Encrypt에는 선택 사항이지만 ZeroSSL 및 Google Public CA에는 필수

설치가 완료되게 되면 NPM때와 마찬가지로 LXC 컨테이너 서버가 생성 실행되며 서버 URL을 통해 관리콘솔에 접속하여 확인할 수 있다.

NPM plus 설치완료 및 Web UI접속

2.1.3 WEB 관리콘솔 로그인

기존 NPM의 경우 최초 관리 콘솔 접속 시 정보가 공통이었던 반면 NPM plus는 별도의 긴 문자열로 이루어져 있기 때문에 스크립트를 통해 설치할 경우 최초 암호자체를 따로 제공해주고 있다.

위 설치 전 VE Helper-Scripts사이트 접속 시 설명된 Application credentials 항목을 통해 접속 정보를 확인가능하다.

자신의 npmplus 설치 서버에 접속하여 아래 명령어를 통해 접속정보를 확인해 보자.

cat /opt/.npm_pwd

접속정보 : Proxmox Web > Datacenter > [본인노드] > [npmplus 컨테이너] > Console

NPM Plus관리콘솔 로그인 정보확인

다음과 같이 해당정보를 통해 로그인을 진행하게 되면 기존 NPM과 동일하게 사용자정보를 업데이트하는 화면이 나오며 해당 항목을 통해 정보업데이트 하여 사용가능하다.

Web관리콘솔 로그인 및 사용자 정보 수정

2.1.4 신규 추가기능확인

그럼 두 가지 버전의 차이점에 대해서 기존 NPM과 비교해서 확인해 보자.

참고로 다크모드 지원 역시 NPM Plus의 특징이라고 볼 수 있다.

아래에서 보는 것과 같이 Proxy Host등록 시 ModSecurity 및 CoreRuleSet 추가되는 등 옵션 항목이 변경된 것을 확인할 수 있다.

Default 영역 비교 (NPM(좌측) vs NPM Plus(우측))

SSL 탭 부분도 확인해 보면 Brotli 압축지원 및 HTTP/3-Quic 옵션이 추가되었다.

SSL 영역 비교 (NPM(좌측) vs NPM Plus(우측))

위에서 보듯이 이제 간단하게 관리 UI를 통해 추가된 기능 옵션을 활성화할 수 있다.

2.2 수동으로 NPM Plus 설치하기

역시나 글이 길어지는 관계로 수동으로 NPM Plus를 설치하는 방법은 별도로 작성예정이다. [ 작성 중.... ]

Location Confige File : /opt/compose.yaml
참고로 위에 언급한 Proxmox VE Helper-Scripts 사이트의 Location Config File에 보면 /opt/compose.yaml 항목이 존재하는데 해당 compose.yaml 파일은 수동설치 시 사용하는 파일로서 해당파일을 통해 NPM Plus가 설치가 되는 것이다.
여기서 알 수 있듯이 해당 Helper 설치스크립트는 기존 확인한 Github의 내용을 토대로 하여 작성된 것을 확인할 수 있다.

그래서 해당 compose.yaml 파일은 확인만 하고 넘어가고 자세한 사용법은 수동설치 부분에서 따로 확인해 보자.

마치며.

사실 먼가 장황하게 설명했지만 NPM plus 설치도 스크립트를 사용하면 1~2분 정도면 간단하게 끝나기 때문에 특별한 게 없다.

시간이 지나고 사용하는 입장에서만 보면 누군가의 수고로 인해 사용은 점점 더 간단하고 쉬워지는 것 같다....

NPM을 이용한 Proxmox 내부 네트워크 설정

천풍훈 — Thu, 24 Jul 2025 14:07:04 +0900

들어가며..

이전에 Proxmox에 사설네트워크 구성을 이야기한 적이 있는데 이번에는 내부 네트워크를 조금 더 효율적으로 관리하기 위한 리버스프록시 서버 NPM(Nginx Proxy Manager)을 이용하여 관리하는 방법을 확인해 보자.

해당 항목은 단지 NPM의 사용설명서 같은 부분이라 딱히 어려울 것이 없이 간단하게 확인만 해보면 된다.

필요에 따라 해당 설정을 하려면 우선적으로 Proxmox에 사설네트워크 구성 및 NPM( Nginx Proxy Manager ) 설치가 선행되어야 하기 때문에 이 부분은 아래 링크를 통해 확인해 보자.

Proxmox 사설네트워크 확인 및 사설망 구성

Proxmox에 NPM(Nginx Proxy Manager) 설치 및 SSL적용

1. 기존 네트워크 구성 및 문제점

NPM을 적용하기 이전이라면 아래와 같이 내부네트워크가 구성되어 있을 것이다.

해당설정은 외부에서 호출 시 Proxmox 서버의 네트워크를 거처 내부의 가상 사설네트워크(vmbr1)까지 연결되게 되는데 이때 각각의 서비스에 접근하기 위해서는 각각의 서버로 포트포워딩을 설정해줘야 한다.

NPM적용 전 내부네트워크 구성

여기서 바로 서비스가 추가될 때마다 포트포워딩 설정을 해야 하며 동일한 포트를 사용하는 서비스에 대해서도 포트를 변경해서 사용하여야 하는 상황이 발생하게 되는 문제가 존재한다.

그럼 이제 이 문제를 효율적으로 관리하기 위한 NPM을 이용해 구성해 보도록 하자.

2. NPM(Nginx Proxy Manager)을 이용한 내부네트워크 구성

우선 NPM(Nginx Proxy Manager) 사용 시 이점에 대해 간단하게만 설명하자면 아래와 같다.

WEB UI를 이용하여 네트워크 관리가 용이함
도메인을 연결하여 간편하게 접근 및 사용가능
도메인에 SSL을 적용하여 안전한 연결 구현 가능
외부연결 시 포트는 http(80), https(443) 포트만 포트포워딩 하여 내부에서 사용하는 모든 포트를 포워딩하지 않아도 됨

2.1 NPM 서버로 포트포워딩 설정

NPM은 기본적으로 Http(80), Https(443) 포트를 전달받기 때문에 해당 포트에 대해서 포트포워딩 설정을 진행해줘야 한다.

가상 사설네트워크 하단에 아래의 포트 포워딩 설정을 추가한다.

네트워크 설정 확인

nano /etc/network/interfaces

포트 포워딩 설정 추가

‼️81번 포트에 대해서는 최초 접근에 필요하며 설정이 완료되면 80, 443 포트만 전달하여 사용가능함

# Port Fowading (http, https -> Nginx Proxy Manager)
post-up   iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 443 -j DNAT --to 10.1.1.2:443
post-down iptables -t nat -D PREROUTING -i vmbr0 -p tcp --dport 443 -j DNAT --to 10.1.1.2:443
post-up   iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 80 -j DNAT --to 10.1.1.2:80
post-down iptables -t nat -D PREROUTING -i vmbr0 -p tcp --dport 80 -j DNAT --to 10.1.1.2:80

# 웹 관리화면 최초접근시 필요(81)
#post-up   iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 81 -j DNAT --to 10.1.1.2:81
#post-down iptables -t nat -D PREROUTING -i vmbr0 -p tcp --dport 81 -j DNAT --to 10.1.1.2:81

네트워크 서비스 재시작

systemctl restart networking

2.2 웹 관리 페이지 접속 및 연결 설정

Nginx Proxy Manger에 도메인 연결 및 SSL관련한 설정이 완료되었다는 가정하에 설명함.

포트포워딩 설정이 끝난 경우 본인의 [Proxmox 서버 IP]:81 포트를 통해 NPM 웹 관리 페이지에 접근할 수 있다.

NPM Web Proxy Host 연결 설정

NPM Web UI > Hosts > Proxy Hosts > Add Proxy Host를 통해 등록

Details 탭
- Domain Names : 사용할 서브도메인 정보 입력
- Forward Hostname / IP : NPM이 설치된 서버 내부 사설 IP 정보 입력
- Forwrad Port : 81 (Web 관리 콘솔 접속 포트)
SSL 탭
- 본인의 SSL 인증서 선택

NPM Web UI접속 Host 설정정보 등록

정상적으로 설정이 완료되었다면 아래와 같이 등록이 완료된 화면을 볼 수 있다.

이제 해당 도메인을 입력하거나 빨간색 부분을 클릭해 보면 도메인을 통해 정상적으로 접속되는 것을 확인할 수 있다.

‼️참고로 해당 도메인으로 접속 설정이 완료되면 프록시 서버에서 내부 서버 및 포트로 이동이 되기 때문에 1.1 NPM 서버로 포트포워딩 설정에서 지정하였던 81번 포트포워딩 설정은 삭제해 줘도 된다.

NPM Web Proxy Host 연결 설정

2.3 서비스 추가에 따른 Proxy Hosts 추가

이제 실제적인 구성은 끝났다.

각자 서비스가 추가됨에 따라 Proxy Hosts에 NPM웹 관리 콘솔을 추가한 것과 같이 추가해 주기만 하면 되는데,

별도의 포트 오픈이나 추가 서버 설정 없이도 간단하게 Proxy Hosts를 등록해 사용하기만 하면 되는 것이다.

3. NPM을 이용한 네트워크 구성 확인

NPM을 이용하여 사설네트워크 설정을 마무리하면 이용하면 최종적으로 다음과 같은 결과를 얻을 수 있는데

기존 사설네트워크 설정보다 한층 업그레이드된 느낌이 든다.

NPM을 이용한 최종 Proxmox 사설 네트워크 구성도

3.1 Proxmox Web 관리콘솔 Proxy Hosts등록‼️

추가로 내부 사설 네트워크(vmbr1)와 연결된 Proxmox 서버의 가상네트워크(vmbr0)에서 호출되는 Proxmox 웹 관리콘솔(8006)에 대해서도 NPM을 통해 접속되도록 설정해 보자.

위에서 설명한 것과 같이 간단하게 Proxy Host를 등록해 보자.

Proxmox Web 관리콘솔 Proxy Hosts등록

이 처럼 등록되기는 했지만 '도메인으로 너무 여러 번 리디렉션 되었습니다.' 문구가 표시되며 실제 연결이 되지 않는다.

이유는 SSL호출 시 NPM서버의 사설 네트워크망(vmbr1)과 다른 가상네트워크(vmbr0)로 호출이 되기 때문에 문제가 발생한다.

NPM 도메인 접속오류

이 부분은 NPM의 proxy_ssl_verify 기능을 사용하지 않는 것으로 간단하게 해결 가능하다.

다시 설정화면으로 들어가서 Advanced 탭 > Custom Nginx Configuration 부분에 아래 항목을 추가해준다.

proxy_ssl_verify off;

NPM의 proxy_ssl_verify 기능 Off

이제 잠시 후 다시 접속을 해보면 짠!! 이제 Proxmox 역시 도메인을 통해 접속이 완료되었다.

NPM을 이용한 Proxmox UI접속

Proxmox Web UI Console(Shell) 접속 오류
NPM을 이용하여 호출된 Proxmox 웹 관리 페이지에서 Web Console(Shell) 접속 시 'undefined'가 뜨면서 오류가 나는 경우가 있는데 이 부분은 Proxy Hosts 설정의 'Websockets Support'를 활성화해서 연결해 주면 된다.

Websockets Support 활성화

3.2 최종 구성도

모든 작업이 완료되면 아래와 같이 깔끔하게 NPM을 이용하여 모든 구성이 가능해진다.

NPM을 이용한 최종 네트워크 구성

마치며.

추가적으로 보안이 더 필요하다면 공유기랑 NPM서버 사이에 오픈소스 웹 방화벽(OPNsense, pfSense 등)을 구축한다면 기본적인 서버구성은 마무리되지 않을까 한다.

Proxmox 네트워크 확인 및 사설망 구성

천풍훈 — Tue, 15 Jul 2025 17:24:23 +0900

들어가며..

굳이 네트워크 설정을 해야 할까?라는 단순한 질문에 사실 설정 하지 않아도 Proxmox 사용하는데 지장은 없다고 답할 수 있다.
그런데 굳지 하지 않아도 되는 네트워크 설정을 하는 이유는 이왕 설치 한이상 좀 더 효율적으로 사용하기 위함이랄까??
너무 단순하게 이야기했지만 이 부분은 필요한 사람만 필요에 따라 설정을 해 사용하면 된다는 이야기이다.
그럼 필요한 사람들만의 효율적인 Proxmox사용을 위해 사설 네트워크 설정을 진행해 보자!~

Private IP(사설 IP)란?
보통 집에서 인터넷을 이용할 경우 대부분 통신사 공유기 또는 별도의 공유기를 통해서 연결되어 있을 것이다.
해당 공유기를 통해서 외부와 Public IP(공인 IP)를 통해 인터넷 연결을 하고 집내부의 기기들은 Private IP(사설 IP)를 할당받아 사용하게 되는데 이때 우리가 보는 192 또는 172로 시작하는 IP들이 이에 해당한다.

이렇게 사설 IP를 이용하는 이유는 사용하는 IT기기들이 늘어남에 따라 공유기를 통해 굳이 공인 IP를 사용해야 하지 않아도 되는 장비나 기기들에 대해 중복으로 사용가능한 IP를 효율적으로 제공하기 위함이다.

보통은 공유기에서 자동으로 할당해 주는 방식(DHCP)으로 사용하여 할당되지 않은 새로운 IP로 자동으로 생성해 주기 때문에 신경 쓰지 않아도 되지만 이렇게 생성된 사설 IP는 내부에서만 사용되는 IP이고 외부에서 접속이 되지 않기 때문에 필요에 따라 외부에서 접속 가능하도록 포트포워드등 라우팅 설정을 해주어야 한다.

1. Proxmox의 기본 네트워크 구성

여느 OS처럼 Proxmox를 설치하면 본인의 물리적 네트워크 카드(NIC)에 의해서 초기설정한 IP대역으로 연결이 된다.
이때의 IP가 위에서 설명한 사설 IP가 할당되며 해당 IP를 통해서 해당 Proxmox의 서비스에 접속하게 된다.
그래서 Proxmox 실행 시 설정한 사설 IP:8006 포트를 통해 WebUI에도 접근하여 사용가능하다.
참고로 앞서 설명했듯이 해당 사설 IP로는 내부에서만 접속되며 외부에서 접속하려면 공유기 설정에서 8006 포트를 포트포워딩 해줘야 한다.

사설IP가 할당된 Proxmox 기본 네트워크

1.1 네트워크 정보확인

아래 명령어를 통해 현재 설정된 Proxmox의 네트워크 정보를 확인해 볼 수 있다.

nano /etc/network/interfaces

auto lo
iface lo inet loopback

# ens33은 NIC에 대한 정보이다.
iface ens33 inet manual

# 가상 브릿지 [ vm(가상) + br(브릿지) + 일련번호 ]
# vmbr0(Linux Bridge)가 자동으로 생성되며 ens33으로부터 모든 포트를 전달받아 외부와 통신한다.
auto vmbr0
iface vmbr0 inet static
        address 192.168.0.70/24
        gateway 192.168.0.1
        bridge-ports ens33
        bridge-stp off
        bridge-fd 0

ens33 : NIC(물리적 네트워크 카드)에 대한 정보(각자마다 이름은 다를 수 있음)
vmbr0 : 가상 Linux Bridge로서 Proxmox 설치 시 자동으로 생성되며 ens33과 연결되어 외부와의 모든 통신이 이루어진다.

WebUI > [본인 Node] > System > Network를 통해서도 확인 가능하다.

Proxmox Web Network 확인

1.2 서비스 추가에 따른 네트워크 구성도

기본적인 네트워크 구성으로 서비스들을 추가할 경우 아래와 같이 구성될 것이다.

새로운 서비스가 추가
공유기로부터 새로운 사설 IP할당
외부접속을 위한 공유기의 포트포워딩 설정

기본 네트워크 설정에서의 서비스 구성도

1.3 기본 네트워크의 문제점

위에서 설명한 것처럼 공유기 사설 IP대역이 허락하는 한 포트포워딩등 설정을 통해서 서비스를 추가해 나가는 것에는 문제가 없다.
하지만 서비스가 많아지고 복잡해지며 또한 보안적인 측면에서도 위처럼 관리하는 것은 바람직하지 않을 것이다.
이 때문에 공유기 역시 Router로서 사설 IP를 사용하는 것이다.
각설하고 그럼 이제 Proxmox에도 사설망으로 네트워크를 구성해 보자~

2. Proxmox 사설 네트워크 설정

사설 네트워크는 사설 가상 브릿지 생성 > NAT설정 > 포트포워딩 설정 순으로 진행된다.
과정은 필요 없다 한다면 2.4 최종 네트워크 설정정보 부분만 확인해 보면 된다.

2.1 사설 가상브리지 생성

내부 사설망의 IP대역은 10.1.1.xxx대역을 사용하였는데 IP대역에 대해서는 아래 표를 참조하면 된다.

사설 IP대역
사설 IP라고 해서 아무것이나 사용하는 것은 아니며 미리 약속된 대역대가 존재함으로 확인해서 사용하면 된다.
사설 IP대역 (출처 : 위키피디아)

아래 명령어를 통해 네트워크 설정에 진입해 아래와 같이 사설 가상 브리지(vmbr1)를 추가해 보자.

네트워크 설정 확인

nano /etc/network/interfaces

사설 가상 브릿지 (vmbr1) 추가

# vmbr1 사설 가상 네트워크 구성
auto vmbr1
iface vmbr1 inet static
        address 10.1.1.1/24
        bridge-ports none
        bridge-stp off
        bridge-fd 0

네트워크 서비스 재시작

systemctl restart networking

이렇게 생성한 사설 가상 브리지(vmbr1)는 가상 브리지(vmbr0)와 다르게 bridge-ports가 none으로 설정되어 있기 때문에 NIC과 연결이 되어있지 않다 그래서 실제로 외부와 통신은 되지 않고 오직 vmbr0 과의 내부 네트워크 통신만 가능하다.

사설 가상 브리지 생성 및 외부연결 확인

아래에서 보듯이 실제로 컨테이너에 새로 생성한 사설 가상브릿지 네트워크(vmbr1) 연결 시 외부 연결은 되지 않지만 내부와의 연결은 가능한 것을 확인할 수 있다.

vmbr1 가상 브릿지 연결시 외부연결 확인

2.2 사설 가상브릿지 NAT 설정

vmbr0은 NIC와 연결되어 외부통신이 가능하고 vmbr1은 vmbr0과의 내부통신이 가능함으로 두 개의 가상 브릿지를 NAT로 연결하여 외부호출 시 vmbr0에서 vmbr1로 전달하게 함으로써 외부와의 통신연결을 하도록 하면 된다.

외부호출 ↔ vmbr0 ↔ vmbr1 호출과정

네트워크 설정 확인

nano /etc/network/interfaces

사설 가상브릿지 NAT 설정 추가

# NAT Setting
post-up echo 1 > /proc/sys/net/ipv4/ip_forward
post-up   iptables -t nat -A POSTROUTING -s '10.1.1.0/24' -o vmbr0 -j MASQUERADE
post-down iptables -t nat -D POSTROUTING -s '10.1.1.0/24' -o vmbr0 -j MASQUERADE

네트워크 서비스 재시작

systemctl restart networking

NAT 설정을 통한 외부통신 설정

위와 같이 사설 가상브릿지의 외부 통신 연결을 위한 NAT설정이 완료되면 가상 사설 네트워크(vmbr1)에서도 외부 통신이 가능해진다.

2.3 외부 접속을 위한 포트포워딩 설정

NAT설정이 끝나면 외부와의 통신은 되기는 하지만 이때도 내부에서 외부로의 통신은 가능한데 실제로 외부에서 내부의 서비스를 접속하려면 해당 서버로 포트를 연결해 줘야 한다.
이것은 공유기에서 사설 IP생성한 것과 동일한 이유로 내부의 사설 IP에 대해서는 외부에서 접근할 수 없기 때문에 외부에서 접속하려고 할 경우 포트포워딩을 통해 해당 포트를 vmbr1로 전달해 접속하려는 서버를 연결해야 한다.

가상 사설 네트워크(vmbr1)로 포트포워딩

네트워크 설정 확인

nano /etc/network/interfaces

포트 포워딩 설정 추가

- 아래 예시에서는 NPM(Nginx Proxy Manager)의 포트 포워딩을 설정하고 있다.
- http(80), https(443), webui(81) 포트에 대해서 사설네트워크(vmbr1)를 이용한 서버로 포트포워딩 해준다.

# Port Fowading (http, https, webui -> Nginx Proxy Manager)
post-up   iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 443 -j DNAT --to 10.1.1.2:443
post-down iptables -t nat -D PREROUTING -i vmbr0 -p tcp --dport 443 -j DNAT --to 10.1.1.2:443
post-up   iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 80 -j DNAT --to 10.1.1.2:80
post-down iptables -t nat -D PREROUTING -i vmbr0 -p tcp --dport 80 -j DNAT --to 10.1.1.2:80
post-up   iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 81 -j DNAT --to 10.1.1.2:81
post-down iptables -t nat -D PREROUTING -i vmbr0 -p tcp --dport 81 -j DNAT --to 10.1.1.2:81

네트워크 서비스 재시작

systemctl restart networking

2.4 최종 네트워크 설정 정보 확인

모든 사설네트워크 설정이 완료된 네트워크 설정파일은 아래와 같다.

auto lo
iface lo inet loopback

# ens33은 NIC에 대한 정보이다. (각자 다를수 있음)
iface ens33 inet manual

# 가상 브릿지 [ vm(가상) + br(브릿지) + 일련번호 ]
# vmbr0(Linux Bridge)가 자동으로 생성되며 ens33으로부터 모든 포트를 전달받아 외부와 통신한다.
auto vmbr0
iface vmbr0 inet static
        address 192.168.0.70/24
        gateway 192.168.0.1
        bridge-ports ens33
        bridge-stp off
        bridge-fd 0

# vmbr1 사설 가상 네트워크 구성
auto vmbr1
iface vmbr1 inet static
        address 10.1.1.1/24
        bridge-ports none
        bridge-stp off
        bridge-fd 0

        # NAT Setting
        post-up echo 1 > /proc/sys/net/ipv4/ip_forward
        post-up   iptables -t nat -A POSTROUTING -s '10.1.1.0/24' -o vmbr0 -j MASQUERADE
        post-down iptables -t nat -D POSTROUTING -s '10.1.1.0/24' -o vmbr0 -j MASQUERADE

        # Port Fowading (http, https -> Nginx Proxy Manager)
        post-up   iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 443 -j DNAT --to 10.1.1.2:443
        post-down iptables -t nat -D PREROUTING -i vmbr0 -p tcp --dport 443 -j DNAT --to 10.1.1.2:443
        post-up   iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 80 -j DNAT --to 10.1.1.2:80
        post-down iptables -t nat -D PREROUTING -i vmbr0 -p tcp --dport 80 -j DNAT --to 10.1.1.2:80
        post-up   iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 81 -j DNAT --to 10.1.1.2:81
        post-down iptables -t nat -D PREROUTING -i vmbr0 -p tcp --dport 81 -j DNAT --to 10.1.1.2:81

source /etc/network/interfaces.d/*

3. 외부 접속 확인

이제 모든 설정이 마무리되었으므로 외부에서 접속해 보자.

3.1 공유기 포트포워딩 설정

각자의 공유기에서 http(80), https(443), webui(81) 포트에 대해서 포트포워딩 설정을 진행하자.

공유기 포트포워딩 설정

3.2 NPM 관리 콘솔 접속 확인

위에서 모든 설정이 정상적으로 되었다면 Proxmox의 기본 네트워크 주소에 81 포트로 아래와 같이 외부에서 내부의 NPM서버 관리 웹 페이지로 접속이 되는 것을 확인할 수 있다.

NPM 웹 관리 콘솔접속

3.3 문제점

사실 여기도 여전히 문제점은 존재하는데 외부호출 과정에 대해 작업한 것을 포함해 요약해 보면 아래와 같다.

외부호출
공유기 포트포워딩 설정
Proxmox 네트워크(vmbr0) 호출 ↔ Proxmox 사설네트워크(vmbr1) NAT설정을 통한 통신
Proxmox 사설네트워크(vmbr1) 포트포워딩 설정을 통한 서버 연결
서버 호출 완료

관리적인 측면에서 Proxmox내부에 사설네트워크를 구축하긴 했지만 서비스가 추가될 경우 해당 서비스에서 사용할 포트에 대해서 공유기 및 내부 사설네트워크(vmbr1)에 모두 포트포워딩 설정을 진행해 줘야 하기 때문에 비효율 적인 것은 여전할 수 있다.
동일한 포트를 사용하는 서비스에 대해서도 사용할 수 없는 문제 역시 있기 때문에 포트를 변경해서 사용하여야 하는 상황이 발생할 문제 또한 존재한다.

이러한 문제를 해결하기 위하여 위에서 예제로 설명한 NPM(Nginx Proxy Manager)을 이용할 수 있는데 내용이 길어지는 관계로 아래 별도의 게시물을 통해 확인해 볼 수 있다.

NPM을 이용한 Proxmox 내부 네트워크 설정

들어가며..이전에 Proxmox에 사설네트워크 구성을 이야기한 적이 있는데 이번에는 내부 네트워크를 조금 더 효율적으로 관리하기 위한 리버스프록시 서버 NPM(Nginx Proxy Manager)을 이용하여 관리하는

lovelettee01.tistory.com

미리 보기로 NPM을 이용하여 사설네트워크 설정을 마무리하면 최종적으로 다음과 같은 결과를 얻을 수 있다.

최종 Proxmox 사설 네트워크 구성도

마치며.

사실 하나하나 풀어서 설명하다 보니 먼가 엄청 장황하게 설명해 복잡한 것 같지만 어쩌면 굉장히 간단한 작업이라고 할 수도 있다.
하지만 한번 설정해 두면 관리나 사용상 편리하게 사용할 수 있으니 한 번쯤은 구현해서 사용해 보도록 하자.

Nginx Prorxy Manager 차근차근 수동 설치하기(feat. Proxmox)

천풍훈 — Fri, 27 Jun 2025 13:55:26 +0900

들어가며

사실 NPM(Nginx Proxy Manager) 설치 방법은 이미 너무 다양하며 자동으로 간단하게 설치할 수 있는 스크립트 또한 존재하기 때문에 단순히 NPM만을 설치하려 한다면 굳이 수동으로 설치하지 않아도 된다.

스크립트를 이용한 자동설치는 아래 링크를 통해 간단하게 설치할 수 있는 방법으로 설치를 권장한다.

Proxmox에 NPM(Nginx Proxy Manager) 및 SSL적용

1. 사전준비NPM(Nginx Proxy Manager)을 설치하기에 앞서 도메인 준비 및 리버스 프록시 서버(Reverse Proxy Server)의 개념에 대해서만 알고 넘어가자.1.1 도메인(Domain) 준비HTTPS의 SSL연결을 사용하려면 기본

lovelettee01.tistory.com

하지만 Proxmox의 LXC컨테이너 또는 VM에 NPM 이외에 다른 서비스들도 함께 설치 및 관리하려 하는 경우 등 각자의 이유로 수동으로 설치를 해야 하는 경우가 존재하기 때문에 확인하여 설치를 진행해 보자.

1. LXC 컨테이너 생성

우선 Proxmox에 NPM을 설치할 LXC컨테이너를 생성해야 한다.

해당 생성방법은 간단하지만 설명해야 할 부분이 좀 있기에 기존 정리해 놓은 아래 링크로 대체하도록 함.

Proxmox VE 리눅스 컨테이너(LXC)생성

Proxmox VE에서는 LXC(Linux Container)와 KVM(Kernel-based Virtual Machine) 두 가지의 가상화 기술을 동시에 지원한다.오늘은 LXC에 대해 알아보고 Proxmox에서 설치 및 사용방법에 대해서도 알아보자.1. LXC(Linux Cont

lovelettee01.tistory.com

Ubuntu 22.04 컨테이너 생성완료

컨테이너 생성이 완료되면 다음과 같은 화면을 볼 수 있다.

최초 컨테이너 생성 이후에는 패키지 업데이트를 진행해 주는 것이 좋다.
apt update && apt upgrade -y

Ubuntu 22.04설치 완료

2. Docker 및 Docker-Compose 설치

실제로 NPM을 설치하려면 공식 사이트에서도 Docker-Compose를 이용하여 설치하는 것을 설명하고 있으므로 생성한 컨테이너에 Docker관련 항목들을 설치를 진행해 보자.

• 패키지 업데이트

apt update && apt upgrade -y

• 필수 패키지 설치

sudo apt install curl -y

• 스크립트를 통해 Docker 설치

curl -fsSL get.docker.com -o get-docker.sh && sh ./get-docker.sh
or
curl -fsSL https://get.docker.com/ | sudo sh

• Docker 설치 확인

service docker status

Docker 설치 및 확인

2. Nginx Proxy Manager 설치

2.1 설치 가이드 확인 및 설치

Nginx Proxy Manager의 공식 사이트에 접속해 Get Started를 클릭하거나 [가이드] 링크를 통해 확인 가능하다.

Nginx Proxy Manager Guide

Quick Setup으로 설치

가장 간단하게 설치할 수 있는 방법으로 차례대로 진행해 보면 된다.

관리의 용이성을 위해 설치하려는 폴더를 미리지정해 설치를 진행하도록 하자.(선택사항)
mkdir -p /services/npm && cd /services/npm

가이드에서 설명하는 데로 docker-compose 파일을 작성해서 설치를 진행해 보자.

nano docker-compose.yml

services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

docker compose up -d

Docker Compose를 이용한 NPM설치

정상적으로 설치가 되었다면 다음과 같이 Docker에 컨테이너가 정상적으로 동작하고 있을 것이다.

docker ps -a

docker ps 를 통한 컨테이너 확인

추가로 Quick Setup과 Full Setup의 차이는 별도의 Database를 사용하는지 여부이다.

Full Setup의 경우는 MySQL / MariaDB를 함께 연동하여 사용하도록 하는 구조로서 폭넓고 안정적인 서비스를 제공해야 하는 경우에 선택가능하며 일반적인 경우 Quick Setup으로 만도 충분히 사용가능하다.

참고로 Quick Setup의 경우는 sqlite를 Databse를 사용한다.

위에 지정한 Volume의 data폴더 (/services/npm/data)를 확인해 보면 database.sqlite 파일이 존재하는 것을 확인할 수 있다.

NPM Quick Setup > database.sqlite 사용

2.2 Web 관리 콘솔 접속

정상적으로 설치가 완료되었다면 자신의 IP를 확인하여 81번 포트로 접속을 해보면 Web 관리콘솔로 접속할 수 있다.

Username: admin@example.com
Password: changeme

NPM 로그인 및 Email, 패스워드 설정

로그인 이후에 초기에 본인이 추후 사용할 이메일 정보 및 패스워드를 지정하여 이후 로그인 시에는 본인이 지정한 이메일 및 패스워드를 통해 로그인하면 된다.

이후 설정이나 등록방법 또는 SSL연결 등은 맨 위에서도 링크로 제공한 NPM자동설치 및 SSL적용 관련포스트를 참고해 보면 된다.

마치며

해당 방법은 꼭 NPM만을 위한 것은 아니며 같은 방식으로 다른 서비스들도 계속 추가해 나갈 수 있다.

Docker를 이용해 계속해서 서비스를 추가할 수 있으며, 여기에 Komodo, Dockge, Portainer, Arcane 등 Docker Tool을 이용하여 서비스 관리 역시 UI를 통해 할 수 있으니 참고해 보면 된다.

참 끝이 없긴 없네...ㅎ;;

Proxmox에 NPM(Nginx Proxy Manager) 설치 및 SSL적용

천풍훈 — Mon, 2 Jun 2025 17:14:21 +0900

1. 사전준비

NPM(Nginx Proxy Manager)을 설치하기에 앞서 도메인 준비 및 리버스 프록시 서버(Reverse Proxy Server)의 개념에 대해서만 알고 넘어가자.

1.1 도메인(Domain) 준비

HTTPS의 SSL연결을 사용하려면 기본적으로 도메인을 필요로 한다.

본인의 도메인을 가지고 있는 경우가 아니라면 아래 링크를 통해 Duckdns라는 무료 도메인서비스를 이용하는 방법을 확인해 보자.

Duckdns 무료 도메인(DDNS) 연결

실제 도메인 연결은 국내외 수많은 호스팅 업체가 존재하며 도메인에 따라서 가격도 천차만별이다.물론 유료 호스팅을 사용하면 원하는 도메인을 설정할 수 있으며 당연히 안정성면에서도 뛰

lovelettee01.tistory.com

1.2 리버스 프록시서버(Reverse Proxy Server) 란?

리버스 프록시란? 간단하게 이야기하면 외부인터넷과 연결된 서버로서 모든 요청은 리버스 프록시 서버가 전달받으며 전달받은 정보를 기반으로 내부 네트워크(LAN)상에 존재하는 각각의 서버에 요청하고 응답받은 정보를 다시 클라이언트로 전달하는 중계서버 역할을 한다.

이러한 중계 역할에 NPM이 사용되며 우리가 원하는 기능을 해당 NPM을 통해 편하게 관리하게 되는 것이다.

자세한 프록시 서버의 개념에 대해서는 아래링크를 통해 알아보면 된다.

프록시 서버(Proxy Server) 개념 정리

1. 프록시 서버(Proxy Server)란?프록시(Proxy)는 '대리'라는 뜻 그대로 클라이언트(사용자)와 서버 사이에 존재하며 둘 사이의 통신의 요청과 응답을 대리하여 수행하는 역할로서 클라이언트와 서버

lovelettee01.tistory.com

2. NPM(Nginx Proxy Manager)이란?

NPM은 기본적으로 위에 이야기한 리버스 프록시 서버(Reverse Proxy Server)로서의 역할을 한다.

그럼 이것을 가지고 무엇을 할 수 있을까??

Nginx Proxy Manager

2.1 NPM 사용 목적 및 기능

Proxy Hosts : 서버로 들어온 요청을 특정 위치로 라우팅 한다
Redirection Hosts : 특정 도메인으로 접속된 요청을 다른 도메인으로 리다이렉션 시킨다.
Streams : Nginx의 새로운 기능인 Stream은 TCP/UDP 트래픽을 네트워크상의 다른 컴퓨터로 직접 전달해 준다.
404 Hosts : 페이지를 찾을 수 없을 때 연결페이지 설정한다.
SSL Certificates : Let`sEncrypt 기반 SSL 인증 설정을 관리한다.

위처럼 NPM을 사용하는 여러 가지 목적이 있겠지만 내가 현재 원하는 그림을 간단하게만 그려보면 아래와 같다.

각각의 도메인으로 호출을 하게 되면 해당서버로 접속을 할 수 있도록 하는 것이다.

이 보다 더 많은 기능들이 존재하지만 추후 알아보기로 하고 이제 설치부터 진행해 보자.

NPM을 이용한 서버 구상도

3. NPM 설치

사실 Nginx Proxy Manager에서 제공하는 공식 설치 방법(Setup Guide)이 있다. 하지만 Proxmox VE Helper-Scripts를 먼저 이야기하는 이유는 사용이 간단하기 때문에 추천하는 용도이긴 하다.

하지만 편한 만큼 실제 설치가 어떤 방식으로 진행되는지는 관심을 가지지 않는 경우 과정은 모르고 설치 시 문제가 발생할 경우 조치도 어렵기 때문에 혹여나 난 하나하나 설치해 보기를 원한다면 아래 링크를 통해 공식 설치 가이드를 통한 설치항목을 참고해 보는 것도 괜찮은 방법이다.

Nginx Prorxy Manager 차근차근 수동 설치하기(feat. Proxmox)

들어가며사실 NPM(Nginx Proxy Manager) 설치 방법은 이미 너무 다양하며 자동으로 간단하게 설치할 수 있는 스크립트 또한 존재하기 때문에 단순히 NPM만을 설치하려 한다면 굳이 수동으로 설치하

lovelettee01.tistory.com

3.1 Proxmox VE Helper-Scripts를 통한 설치

※ Proxmox VE Helper-Scripts란?(링크)

Proxmox의 사용자가 및 그에 따른 활용도가 늘어나는 만큼 각각의 설치항목을 간단하게 설치하여 사용하기 위하여 대단하신 분들이 만들어 공유하는 간편 설치(?) Github이 존재하는데 이곳에서 제공하는 명령어를 통해 간단하게 설치 가능하다.

해당 사이트는 직관적이라 따로 설명하지 않고 각자 필요에 따라 검색해서 설치하여 사용하면 된다.

3.1.1 사이트 접속 및 확인

VE Helper-Script 사이트에서 Nginx Proxy Manager를 검색해 보자.

접속 후 아래와 같이 기본적인 설명 및 설치방법 기타 설정 방법 등 정보를 확인할 수 있다.

Promox VE Helper-Scripts Nginx Proxy Manager

위 항목 중 빨간색으로 표시한 부분이 우리가 중요하게 확인해야 할 부분으로 설치 스크립트 및 설치 후 로그인 정보를 확인 가능하다.

그럼 설치를 시작해 보자!.

3.1.2 Script를 통한 NPM 설치

본인의 Proxmox Shell에 접속해서 아래 함수를 통해 설치를 진행해 보자.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/nginxproxymanager.sh)"

Proxmox Shell에서 Script 실행

실행 후 아래와 같이 LXC를 설치할지 묻는 화면이 나오고 이어서 설정 부분이 나온다 본인이 원하는 설정이 있다면 수정하면 되며 기본적으로 Default Settings를 선택해 설치하면 되며 필요시 추후 변경도 가능하니 Ok를 선택해 설치를 진행해 보자.

Promox VE Helper-Scripts 를 통한 NPM 설치

‼️Proxmox에서 제공하는 쉘이 아닌 외부 SSH를 이용하여 접속한 경우 설치 시 아래와 같은 메시지를 볼 수 있다.
Proxmox shell이 아닌 곳에서 설치할 경우 잠재적인 문제가 발생할 수 있다는 내용인데 혹시 모르니 Proxmox Shell을 이용하여 설치하는 것을 권장한다.
외부SSH를 이용한 설치시 확인 팝업

잠시 후 설치가 진행되고 설치 중간에 최신버전이 아닌 이전버전을 설치를 묻는 항목이 나오는데 각자 상황에 맞게 설치하면 된다.

최신 버전을 설치할 경우 'N'을 입력 후 진행하면 아래와 같이 설치가 완료된 항목이 나온다.

~ 이로서 설치가 끝이다 얼마나 간단하게 설치할 수 있는지는 별도로 이야기하지 않아도 될 것이다.

Script를 통한 NPM 설치 완료

설치가 완료되면 좌측에 101(nginxproxymanager) LXC컨테이너가 생성되며 자동실행 된다.

이후 하단의 접속 URL을 통해 접속하면 NPM관리 콘솔로 접근하지만 당장은 포트포워딩이나 각자의 상황에 따라 서버에 접속되지 않을 수 있다. 이 부분은 관리콘솔 접속 부분에서 별도로 설명하도록 한다.

4. WEB 관리 콘솔 접속

4.1 방화벽 오픈 및 포트 포워딩 설정

외부에서 NPM 관리 콘솔에 접속하기 위해서는 내부에 접근가능하도록 방화벽 및 포트 포워딩을 해줘야 한다.

아래는 ipTime을 기준으로 보면 접근 가능한 IP 및 포트를 오픈함으로써 외부에서도 접근가능하도록 지정한다.

각자의 네트워크 환경에 맞도록 구성해서 사용하도록 한다.

필수 오픈 포트

80 / 443 (웹 서비스 포트 오픈)

81 (웹 관리 콘솔 포트 오픈) - [설정 후 삭제] 해당 포트는 Proxy Host 등록 전 확인용도로만 사용

IPTime 포트 포워딩 규칙 추가

4.2 관리 콘솔 접속 및 로그인

관리 콘솔 접속 URL을 통해 다음과 같은 로그인 화면을 볼 수 있으며 3.1.1 사이트정보에서 이야기한 기본 로그인 정보를 통해 로그인 가능하다.

You can use the following credentials to login to the Nginx Proxy Manager ct.
Username: admin@example.com
Password: changeme

NPM 로그인 및 Email, 패스워드 설정

로그인 정보는 Web 관리콘솔 > Users 항목을 통해 추후 변경도 가능하고 필요에 따라 사용자를 추가해서 사용도 가능하다.

5. 도메인 접속 및 SSL적용

NPM을 설치하고 외부에서 접속되도록 하였다면 이제 도메인을 연결하고 SSL을 통한 보안 작업까지 마무리해 보자!~

해당 항목은 1. 사전준비 부분에서 설명한 Duckdns를 통한 도메인 연결이 되었다는 가정하에 진행하였다.

5.1 도메인을 통한 접속

도메인이 정상적으로 연결이 되었다면 다음과 같이 도메인을 통해 접속을 해보면 접속페이지가 출력되며 로그인도 정상적으로 진행된다.

다만 아직 SSL이 적용되어 있지 않기 때문에 ⚠️안전하지 않음이 표시되는 것을 확인할 수 있다.

Duckdns 무료 도메인을 통한 NPM접속

5.2 SSL 인증서 발급(with. Let`s Encrypt)

SSL은 NPM에서 제공하는 기능을 통해 무료 Let`s Encrypt 인증서를 발급받는다.

관리콘솔 > SSL Certificates > Add SSL Certificate

Let`s Encrypt SSL인증서 등록

Add Let`s Encrypt Certificate 항목의 [*] 표시가 된 필수 입력사항( Use a DNS Challenge 토글 버튼을 활성화한 정보 포함)

Domain Names	인증서를 발급받으려는 도메인정보를 입력 (탭[\tab] 을 눌러 복수개 입력가능)
Email Address for Let`s Encrypt	본인의 이메일 정보를 입력
DNS Provider	본인의 DNS Provider정보 선택
Credentials File Content	각 DNS 별로 본인인증용 Token정보등등 필요정보를 입력해준다.

여기서는 DNS Provider는 DuckDns를 선택하고 your-duckdns-token 부분에 본인의 Duckdns Token정보를 입력해 준다.

Save를 클릭하면 잠시 후 다음과 같이 인증서가 발급된 것을 확인할 수 있다.

참고로 무료 인증서인 만큼 3개월의 만료주기가 주어진다. 만료되기 전에 우측의 ⁝ 부분을 클릭하여 Renew Now항목을 통해 3개월 단위 갱신이 가능하다.

인증서 갱신 부분은 서버에 Crontab 등 자동갱신도 지정할 수 있다. 이 부분은 너무 길어지는 관계로 패스....

인증서 발급 완료 및 갱신

오류사항 발생 시 하단 더 보기 항목 확인

사실 인증서 발급단계에서의 에러는 너무 다양해서 다 확인할 수 없다.

필요에 따라 이 부분은 각자 확인을 해서 해결해야 할 부분으로 생각된다.

아래는 기본적인 버그에 해당하기 때문에 확인해서 실행해 보면 된다.

Duckdns Certbot 커멘드 에러 발생 시

nginxproxymanager lxc 컨테이너에서 Console에 접속 후 아래 명령어 입력
python3 -m pip install certbot_dns_duckdns
SSL 인증서 발급시 오류

참고 링크 : nginx proxy manager에서 ssl 생성 시 오류

5.3 도메인연결 및 SSL 인증서 적용

진짜 길고 험난했던 과정의 마지막을 달려가고 있다.

이제 도메인을 연결하고 이전에 생성한 SSL인증서를 적용해 보자.

관리콘솔 > Hosts > Proxy Hosts > Add Proxy Host

새로운 Proxy Host정보 생성 및 SSL 적용

위와 같이 새로운 Proxy Host 정보를 생성해 보자.

여기가 내가 하려고 했던 Reverse Proxy 서버로서의 역할을 지정하는 것이다.

npm.lovelettee.duckdns.org 도메인 접속 시 내부의 NPM 웹관리 콘솔(81번 포트)로 연결하는 설정이다.

보통은 Details 부분의 정보만 입력하면 Reverse Proxy로서의 역할을 하는 것이며 SSL탭설정은 SSL적용 시에만 진행해 주면 된다.

등록 완료 후 도메인 영역을 클릭하면 짠!!~

드디어 도메인 연결 및 SSL적용이 완료되었다.

이제 Reverse Proxy를 통해 연결되기 때문에 포트포워딩으로 활성화했던 81번 포트는 필요가 없어진다.
포트포워딩 설정에서 삭제해도 정상적으로 연결이 된다.
외부접속 포트인(80, 443)으로 NPM 접속 후 내부에서 다시 분배되는 것이다.

도메인에 SSL적용된 모습

6. 마치며

사실 Proxy Server를 설치한다는 것 자체가 네트워크(도메인, 방화벽, 포트포워딩등) 및 서버에 대한 여러 사전지식을 필요로 한다.

이것도 우선 적용한 것일 뿐 사실상 완벽하진 않다.

공유기에서 포트를 지정해 오픈해 주는 방식은 결국 한 포트에 한 가지 서비스만 연결될 뿐이다.

다음에는 Proxmox 서버를 통해 내부 사설네트워크(VPC)를 구성해 보자.

구분	InfluxDB 1.x [링크]	InfluxDB 2.x [링크]
아키텍처	단일 컴포넌트 아키텍처	마이크로서비스 아키텍처
핵심 개념/용어	Database, Retention Policy (DB/RP), User, Continuous Query	Organization, Bucket, Token, Task (DB/RP 조합이 Bucket으로 변경됨)
인증 및 보안	사용자 이름/비밀번호 기반 인증	토큰(Token) 기반의 인증 및 권한 부여 시스템 도입
쿼리 언어	InfluxQL (SQL과 유사함)	Flux(기본), InfluxQL 지원
데이터 모델	데이터 베이스, 태그(Tag)와 필드(Field)로 구분	태그와 필드 개념은 유지, 버킷(Bucket)에 저장
사용 편의성	CLI를 사용하여 관리	통합된 웹 UI 제공 (데이터 탐색, 시각화, 대시보드, 설정 등)