실행 매개변수(Run parameters)

cloudflared tunnel run 명령의 구성 플래그 목록이에요. 원격 관리 터널에서는 이 플래그들을 터널 서비스에 추가해요. 로컬 관리 터널을 사용한다면 구성 파일에 키/값 쌍으로 추가해요.

출처: 문서

본문

터널 서비스에 실행 매개변수 추가하기

원격 관리 터널은 운영 체제에서 서비스로 실행돼요. 터널 서비스 파일에 실행 매개변수를 추가하려면:

Linux에서 Cloudflare Tunnel은 systemctl을 사용해 시스템 서비스로 설치돼요. 기본적으로 서비스 이름은 cloudflared.service예요. Linux에서 터널을 구성하려면:

1. cloudflared.service를 열어요.

   sudo systemctl edit --full cloudflared.service
   

2. cloudflared tunnel run 명령을 원하는 구성 플래그로 수정해요. 예를 들어,

   [Unit]
   Description=Cloudflare Tunnel
   After=network.target
   
   [Service]
   TimeoutStartSec=0
   Type=notify
   ExecStart=/usr/local/bin/cloudflared tunnel --loglevel info --logfile /var/log/cloudflared/cloudflared.log run --token <TOKEN VALUE>
   Restart=on-failure
   RestartSec=5s
   
   [Install]
   WantedBy=multi-user.target
   

3. cloudflared.service를 재시작해요:

   sudo systemctl restart cloudflared
   

4. 새 구성을 확인하려면 서비스 상태를 점검해요:

   sudo systemctl status cloudflared
   

   ● cloudflared.service - cloudflared
     Loaded: loaded (/etc/systemd/system/cloudflared.service; enabled; preset: enabled)
     Active: active (running) since Wed 2024-10-09 20:02:59 UTC; 2s ago
   Main PID: 2157 (cloudflared)
      Tasks: 8 (limit: 1136)
     Memory: 16.3M
        CPU: 136ms
     CGroup: /system.slice/cloudflared.service
             └─2157 /usr/bin/cloudflared tunnel --loglevel info --logfile /var/log/cloudflared/cloudflared.log run --token eyJhIjoi...
   

macOS에서 Cloudflare Tunnel은 launchctl을 사용해 launch agent로 설치돼요. 기본적으로 에이전트 이름은 com.cloudflare.cloudflared예요. macOS에서 터널을 구성하려면:

1. cloudflared 서비스를 중지해요.

   sudo launchctl stop com.cloudflare.cloudflared
   

2. 구성 파일을 언로드해요.

   sudo launchctl unload /Library/LaunchDaemons/com.cloudflare.cloudflared.plist
   

3. 텍스트 편집기에서 /Library/LaunchDaemons/com.cloudflare.cloudflared.plist를 열어요.

4. ProgramArguments 키를 원하는 구성 플래그로 수정해요. 예를 들어,

   <plist version="1.0">
       <dict>
           <key>Label</key>
           <string>com.cloudflare.cloudflared</string>
           <key>ProgramArguments</key>
           <array>
               <string>/opt/homebrew/bin/cloudflared</string>
               <string>tunnel</string>
               <string>--logfile</string>
               <string><PATH></string>
               <string>--loglevel</string>
               <string>debug</string>
               <string>run</string>
               <string>--token</string>
               <string><TOKEN VALUE> </string>
           </array>
   

5. 업데이트된 구성 파일을 로드해요.

   sudo launchctl load /Library/LaunchDaemons/com.cloudflare.cloudflared.plist
   

6. cloudflared 서비스를 시작해요.

   sudo launchctl start com.cloudflare.cloudflared
   

Windows에서 Cloudflare Tunnel은 레지스트리 편집기를 사용해 시스템 서비스로 설치돼요. 기본적으로 서비스 이름은 cloudflared예요. Windows에서 터널을 구성하려면:

1. 레지스트리 편집기를 열어요.

2. HKEY_LOCAL_MACHINE > SYSTEM > CurrentControlSet > Services > cloudflared로 이동해요.

3. ImagePath를 더블 클릭해요.

4. Value data를 원하는 구성 플래그로 수정해요. 예를 들어,

   C:\Program Files (x86)\cloudflared\.\cloudflared.exe tunnel --loglevel info --logfile <PATH> run --token <TOKEN VALUE>
   

매개변수(Parameters)

autoupdate-freq

Syntax	Default
cloudflared tunnel --autoupdate-freq <FREQ> run <UUID or NAME>	24h

cloudflared 업데이트의 빈도를 구성해요.

cloudflared가 독립 실행형 바이너리로 설치되고 서비스로 실행될 때 내장 자동 업데이트가 활성화돼요. Windows에서는, 패키지 매니저 설치는, 또는 cloudflared가 터미널에서 대화형으로 실행될 때는 사용할 수 없어요. 업데이트가 있으면 cloudflared는 새 버전을 사용하도록 재시작해요. 업데이터는 이전 프로세스를 종료하기 전에 대체 프로세스가 Cloudflare에 연결되기를 기다리지 않아요. 활성 연결이 중단될 수 있어요. 업데이트 시점을 제어하려면 no-autoupdate를 사용해요.

config

참고

로컬 관리 터널 전용.

Syntax	Default
cloudflared tunnel --config <PATH> run <UUID or NAME>	~/.cloudflared/config.yml

YAML 형식의 구성 파일 경로를 지정해요.

dns-resolver-addrs

참고

cloudflared 버전 2025.7.0 이상 필요.

Syntax	Environment Variable
cloudflared tunnel run --dns-resolver-addrs <IP:PORT> <UUID or NAME>	TUNNEL_DNS_RESOLVER_ADDRS

호스트 머신의 기본 해석기 대신 cloudflared가 사용할 사용자 지정 DNS 해석기 주소를 지정해요. 각 주소는 ip:port 형식이어야 해요 — 포트 없이 IP 주소만 제공하면 cloudflared가 시작에 실패해요. 플래그를 반복해 여러 해석기를 지정할 수 있어요. 예를 들어,

cloudflared tunnel run --dns-resolver-addrs 1.1.1.1:53 --dns-resolver-addrs 1.0.0.1:53 <UUID or NAME>

여러 해석기를 지정하면 cloudflared는 각 DNS 요청에 대해 하나를 무작위로 선택해요. 최대 10개의 해석기 주소가 허용돼요.

edge-bind-address

Syntax	Environment Variable
cloudflared tunnel --edge-bind-address <IP> run <UUID or NAME>	TUNNEL_EDGE_BIND_ADDRESS

cloudflared와 Cloudflare 글로벌 네트워크 사이의 연결을 설정하는 데 사용되는 발신(outgoing) IP 주소를 지정해요.

기본적으로 cloudflared는 운영 체제가 어떤 IP 주소를 사용할지 결정하게 해요. 이 옵션은 네트워크 인터페이스가 여러 개 있고 특정 인터페이스를 선호하고 싶을 때 유용해요.

edge-bind-address의 IP 버전은 edge-ip-version(제공된 경우)을 덮어써요. 예를 들어 IPv6 소스 주소를 입력하면 cloudflared는 항상 IPv6 목적지에 연결해요.

edge-ip-version

Syntax	Default	Environment Variable
cloudflared tunnel --edge-ip-version <VERSION> run <UUID or NAME>	4	TUNNEL_EDGE_IP_VERSION

cloudflared와 Cloudflare 글로벌 네트워크 사이의 연결을 설정하는 데 사용되는 IP 주소 버전(IPv4 또는 IPv6)을 지정해요. 사용 가능한 값은 auto, 4, 6이에요.

auto 값은 호스트 운영 체제가 어떤 IP 버전을 선택할지 결정하게 해요. 지역 조회의 DNS 해석에서 반환된 첫 번째 IP 버전이 기본 집합으로 사용돼요. IPv6와 IPv4 이중 네트워크 설정에서는 cloudflared가 IP 버전을 연결 실패 시나리오에서 폴백에 사용되는 두 개의 주소 집합으로 분리해요.

grace-period

Syntax	Default	Environment Variable
cloudflared tunnel --grace-period <PERIOD> run <UUID or NAME>	30s	TUNNEL_GRACE_PERIOD

cloudflared가 SIGINT/SIGTERM을 받으면 새 요청 수락을 중지하고, 진행 중인 요청이 종료되기를 기다린 뒤 종료해요. 진행 중인 요청 대기는 이 유예 기간(grace period) 후 또는 두 번째 SIGTERM/SIGINT를 받으면 타임아웃돼요.

log-directory

Syntax	Environment Variable
cloudflared tunnel --log-directory <PATH> run <UUID or NAME>	TUNNEL_LOGDIRECTORY

지정된 디렉터리의 cloudflared.log라는 파일에 로그를 써요. 파일이 1 MB에 도달하면 cloudflared가 로테이션하고 최대 5개의 백업 파일을 유지해요. 로테이션은 파일 크기를 기준으로 하며 나이 기준 보존은 없어요.

일상적인 영구 로깅에는 log-directory를 사용해요. logfile도 지정하면 logfile이 우선해요.

logfile

Syntax	Environment Variable
cloudflared tunnel --logfile <PATH> run <UUID or NAME>	TUNNEL_LOGFILE

애플리케이션 로그를 이 파일에 저장해요. cloudflared는 이 파일을 로테이션하지 않아요. 짧은 트러블슈팅 세션에서 또는 다른 도구가 로그 로테이션을 관리할 때 logfile을 사용해요. log-directory도 지정하면 logfile이 우선해요. Cloudflare 지원팀에 연락할 때 필요한 정보에 대한 자세한 내용은 이 가이드를 참고해요.

loglevel

Syntax	Default	Environment Variable
cloudflared tunnel --loglevel <VALUE> run <UUID or NAME>	info	TUNNEL_LOGLEVEL

로컬 cloudflared 인스턴스의 로깅 상세 수준을 지정해요. 사용 가능한 값은 debug, info(기본), warn, error, fatal이에요. debug 수준에서 cloudflared는 요청 URL, 메서드, 프로토콜, 콘텐츠 길이와 모든 요청 및 응답 헤더를 로그로 기록하고 표시해요. 다만 이는 로그에 민감한 정보를 노출할 수 있다는 점에 유의해요.

metrics

Syntax	Default	Environment Variable
cloudflared tunnel --metrics <IP:PORT> run <UUID or NAME>	Refer to Tunnel metrics	TUNNEL_METRICS

지정된 IP 주소와 포트에 Prometheus 엔드포인트를 노출하고, 이를 통해 사용량 메트릭을 쿼리할 수 있어요.

no-autoupdate

참고

이 매개변수는 cloudflared가 Windows에서 실행되거나, 패키지 매니저로 설치되었거나, 터미널에서 대화형으로 실행될 때는 적용되지 않아요. 이러한 환경에서는 자동 업데이트를 사용할 수 없어요.

cloudflared가 패키지 매니저로 설치되었는지 확인하려면 ls -la /usr/local/etc/cloudflared/를 실행하고 출력에서 .installedFromPackageManager를 찾아봐요.

Syntax	Environment Variable
cloudflared tunnel --no-autoupdate run <UUID or NAME>	NO_AUTOUPDATE

자동 cloudflared 업데이트를 비활성화해요. 자동 업데이트 간격을 바꾸려면 autoupdate-freq를 참고해요. 수동 업데이트 방법과 다운타임을 최소화하는 옵션은 Update cloudflared를 참고해요.

output

참고

cloudflared 버전 2025.6.1 이상 필요.

Syntax	Default	Environment variables
cloudflared tunnel --output <FORMAT> run <UUID or NAME>	default	TUNNEL_LOG_OUTPUT TUNNEL_MANAGEMENT_OUTPUT

콘솔 로그 형식을 지정해요. 사용 가능한 값은 default와 json이에요.

json 값은 각 로그 줄을 JSON 객체로 포맷해요. 이 형식은 JSON을 소비하는 Kubernetes 배포와 로그 수집 시스템에 유용해요.

origincert

참고

로컬 관리 터널 전용.

Syntax	Default	Environment Variable
cloudflared tunnel --origincert <PATH> run <UUID or NAME>	~/.cloudflared/cert.pem	TUNNEL_ORIGIN_CERT

여러분의 존 중 하나에 대한 계정 인증서를 지정해 클라이언트가 해당 존의 오리진으로 역할할 수 있게 인가해요. cloudflared tunnel login 명령을 사용하거나 https://dash.cloudflare.com/argotunnel을 방문해 인증서를 얻을 수 있어요.

pidfile

Syntax	Environment Variable
cloudflared tunnel --pidfile <PATH> run <UUID or NAME>	TUNNEL_PIDFILE

첫 번째 성공적인 연결 후 애플리케이션의 프로세스 식별자(PID)를 이 파일에 써요. 주로 스크립팅과 서비스 통합에 유용해요.

post-quantum

Syntax	Environment Variable
cloudflared tunnel run --post-quantum <UUID or NAME>	TUNNEL_POST_QUANTUM

기본적으로 quic을 통한 Cloudflare Tunnel 연결은 포스트퀀텀 암호화(PQC)로 암호화되지만 연결 문제가 있으면 비-PQ로 폴백해요. --post-quantum 플래그가 제공되면 quic 연결은 PQ 키 합의만 사용할 수 있고 비-PQ로의 폴백은 없어요.

http2 프로토콜을 사용할 때는 포스트퀀텀 키 합의가 지원되지 않아요.

protocol

Syntax	Default	Environment Variable
cloudflared tunnel --protocol <VALUE> run <UUID or NAME>	auto	TUNNEL_TRANSPORT_PROTOCOL

cloudflared와 Cloudflare 글로벌 네트워크 사이의 연결을 설정하는 데 사용되는 프로토콜을 지정해요. 사용 가능한 값은 auto, http2, quic이에요.

auto 값은 quic 프로토콜을 자동으로 구성해요. cloudflared가 UDP 연결을 설정할 수 없으면 http2 프로토콜을 사용하도록 폴백해요.

region

Syntax	Environment Variable
cloudflared tunnel --region <VALUE> run <UUID or NAME>	TUNNEL_REGION

연결이 설정될 지역을 선택할 수 있게 해요. 현재 사용 가능한 유일한 값은 us로, 모든 연결을 미국 데이터 센터로 라우팅해요. 생략하거나 비워 두면 글로벌 지역에 연결해요.

지역이 us로 설정되면 cloudflared는 미국 전용의 서로 다른 호스트 이름과 IP를 사용해요. 자세한 내용은 Tunnel with firewall을 참고해요.

참고

FedRAMP High ↗︎ 환경에서는 터널 토큰이 FedRAMP 데이터 센터로의 라우팅을 자동으로 결정해요 — --region 플래그가 필요 없어요. 방화벽이 허용해야 하는 FedRAMP 전용 엔드포인트는 Tunnel with firewall을 참고해요.

retries

Syntax	Default	Environment Variable
cloudflared tunnel --retries <VALUE> run <UUID or NAME>	5	TUNNEL_RETRIES

연결/프로토콜 오류에 대한 최대 재시도 횟수를 지정해요. 재시도는 지수 백오프(기본적으로 1, 2, 4, 8, 16초에서 재시도)를 사용하므로 이 값을 크게 늘리는 것은 권장하지 않아요.

tag

Syntax	Environment Variable
cloudflared tunnel --tag <KEY=VAL> run <UUID or NAME>	TUNNEL_TAG

이 터널을 식별하는 데 사용되는 사용자 지정 태그를 지정해요. 명령에 추가 --tag <KEY=VAL> 플래그를 추가해 여러 태그를 지정할 수 있어요. 구성 파일에 여러 태그를 입력한다면 쉼표로 구분해요: tag: {KEY1=VALUE1, KEY2=VALUE2}.

token

참고

원격 관리 터널 전용.

Syntax	Environment Variable
cloudflared tunnel run --token <TUNNEL_TOKEN>	TUNNEL_TOKEN

cloudflared 인스턴스를 특정 터널과 연결해요. 터널의 토큰은 터널을 처음 만들 때 대시보드에 표시돼요. API로 토큰을 검색할 수도 있어요.

token-file

참고

원격 관리 터널 전용. 2025.4.0 이상 필요.

Syntax	Environment Variable
cloudflared tunnel run --token-file <PATH>	TUNNEL_TOKEN_FILE

토큰이 들어 있는 파일을 사용해 cloudflared 인스턴스를 특정 터널과 연결해요.

더 알아보기 (Learn more)

실행 매개변수는 cloudflared tunnel run의 동작을 제어해요. 로컬 관리 터널은 구성 파일에, 원격 관리 터널은 각 OS의 서비스 설정에 플래그를 추가해요. 오리진 연결 방식은 origin-parameters 문서에서 다뤄요.