3.2 Zenoh 라우터(zenohd) 및 핵심 CLI 도구 설치

3.2 Zenoh 라우터(zenohd) 및 핵심 CLI 도구 설치

Zenoh 네트워크 생태계에 진입하기 위한 최우선 관문은 **Zenoh 라우터(zenohd)**와 상호작용 체계를 테스트하기 위한 **핵심 CLI 도구(zenoh-cli)**를 확보하는 것이다.

이 도구들은 단순히 코딩된 애플리케이션을 보조하는 조연이 아니라, 4장에서 다루게 될 거대한 분산 라우팅 트리(Tree)와 메쉬(Mesh) 토폴로지를 직접 엮어내는 주연 역할을 담당한다. Zenoh 코어 팀은 개발 및 인프라 운영자가 각자의 환경에서 가장 통제력 높은 방식을 선택할 수 있도록 다채로운 배포 파이프라인(패키지 매니저, 바이너리 릴리즈, 소스 빌드, 컨테이너 등)을 공식적으로 제공하고 있다.

1. 설치할 핵심 컴포넌트의 이해

이 장에서 설치하게 될 두 가지 핵심 바이너리의 역할은 다음과 같다.

  1. zenohd (Zenoh Router Daemon):
    소규모 에지 노드부터 거대 클라우드 데이터센터까지 데이터 흐름을 중계(Relay)하고 인네트워크 캐시(In-Network Cache)를 제어하는 백그라운드 프로세스이다. zenohd는 단일 실행 파일 형태로 배포되며, OS 내부에 무거운 종속 라이브러리를 요구하지 않는 극단적인 경량성(Zero-dependency)을 자랑한다.
  2. zenoh-cli (혹은 z_pub, z_sub, z_get 등 분리된 유틸리티):
    명령줄(CLI) 환경에서 직접 패킷을 밀어 넣고(Publish) 빼내며(Subscribe/Query) 네트워크 망의 정상 작동 여부를 진단하는 디버깅 특화 바이너리 집합이다. zenohd가 세워둔 고속도로 위를 시험 주행하는 테스트 차량과 같다.

2. 배포판 선택을 위한 체크리스트

각자의 시스템 스펙과 운영 목적(DevOps)에 따라 아래 절들의 설치 시나리오를 전략적으로 취사선택해야 한다.

  • 서버/에지 물리 장비에 영구적으로 백업망을 구성하고 싶다:
    \rightarrow 3.2.1절의 리눅스(Linux) 환경 설치 및 systemd 서비스 등록 체계를 따른다. 백그라운드 무중단 운영의 정석이다.
  • 사무용 PC에서 코딩과 로컬 디버깅을 당장 시작하고 싶다:
    \rightarrow 3.2.2절(Windows) 또는 3.2.3절(macOS)의 방법을 따른다.
  • 호스트 OS를 더럽히지 않고 격리된 컨테이너 환경에서 테스트하고 싶다:
    \rightarrow 3.2.4절의 Docker/Kubernetes 기반 배포 가이드를 참조한다.
  • 실험적인 최신 기능(Nightly)이나 플러그인 모듈을 직접 커스터마이징해야만 한다:
    \rightarrow 3.2.5절의 Rust cargo 컴파일러를 이용한 소스 코드 직접 빌드 방식을 택해야 한다.

다음 하위 절들에서는 운영체제별 공식 설치 파이프라인을 따라 실제로 바이너리를 로컬 장비에 내려받고 구동을 검증하는 절차를 상세히 밟아 나간다.

3. 리눅스(Linux) 환경에서의 설치 및 시스템 데몬(systemd) 등록

로봇의 두뇌인 SBC(Single Board Computer)나 클라우드 가상 머신(VM)처럼 24시간 무중단 보장 환경을 구성해야 하는 서버용 리눅스(Ubuntu/Debian)에서는, APT 패키지 매니저를 통한 스크립트 기반 설치 및 systemd 데몬 등록이 필수적이다.

3.1 APT 리포지토리를 통한 공식 패키지 설치 (Debian/Ubuntu 계열)

Eclipse Zenoh 팀은 개발자들이 최신 릴리스 패키지를 쉽게 추적하고 업데이트할 수 있도록 공식 데비안(Debian) 리포지토리를 제공한다.

터미널을 열고 다음 명령어를 순차적으로 실행하여 GPG 키를 등록하고 패키지를 설치하라.

## 1. 필수 패키지 설치 및 Zenoh 공식 GPG 키 다운로드
sudo apt update
sudo apt install -y curl apt-transport-https
curl -L https://download.eclipse.org/zenoh/debian-repo/zenoh.gpg | sudo apt-key add -

## 2. Zenoh APT 저장소 추가
echo "deb [arch=amd64,arm64] https://download.eclipse.org/zenoh/debian-repo/ /" | sudo tee /etc/apt/sources.list.d/zenoh.list

## 3. 패키지 목록 업데이트 및 zenohd, zenoh-cli 설치
sudo apt update
sudo apt install -y zenohd zenoh-cli

설치가 정상적으로 끝났다면, 버전을 확인하여 바이너리가 PATH에 제대로 등록되었는지 점검하라.

zenohd --version

3.2 미리 컴파일된 바이너리 아카이브(Binary Archive) 수동 다운로드 및 설치

만약 apt 사용이 불가능한 격리망(Air-gapped) 환경이거나 RHEL/CentOS 계열 리눅스라면, GitHub Releases 페이지에서 직접 압축 파일을 받아 압축을 푸는 원시적인 방식이 가장 확실하다.

## 최신 릴리스 버전 번호를 명시하여 x86_64 리눅스 바이너리를 다운로드 (버전은 예시)
wget https://github.com/eclipse-zenoh/zenoh/releases/download/1.0.0/zenoh-1.0.0-x86_64-unknown-linux-musl.zip

## 압축 해제 후 전역 경로로 바이너리 이동
unzip zenoh-1.0.0-x86_64-unknown-linux-musl.zip
sudo mv zenohd /usr/local/bin/
sudo mv z_pub /usr/local/bin/    # 이전 버전의 경우 zenoh-cli 대신 개별 바이너리 제공
sudo mv z_sub /usr/local/bin/

3.3 시스템 데몬(systemd) 서비스 등록 및 백그라운드 구동

통신 라우터 프로세스가 사용자의 로그아웃과 무관하게 하드웨어 부팅 즉시 백그라운드에서 살아나도록 systemd 데몬으로 교체하라. APT를 통해 설치했다면 자동으로 서비스 빈 껍데기가 생성되어 있지만, 수동으로 구성하는 표준 템플릿은 다음과 같다.

루트 권한으로 /etc/systemd/system/zenohd.service 파일을 생성하고 아래 내용을 입력하라.

[Unit]
Description=Eclipse Zenoh Router Daemon
After=network.target

[Service]
## 라우터 설정 파일이 존재할 경우 지정 (4장에서 상세히 다룸)
## ExecStart=/usr/local/bin/zenohd -c /etc/zenoh/zenoh.json5
ExecStart=/usr/local/bin/zenohd
Restart=on-failure
RestartSec=2
User=root

[Install]
WantedBy=multi-user.target

작성이 끝났으면 데몬을 리로드하고 서비스를 기동한다.

## systemd 설정 새로고침 및 서비스 부팅 시 자동 시작 등록
sudo systemctl daemon-reload
sudo systemctl enable zenohd

## 지금 즉시 라우터 서비스 시작
sudo systemctl start zenohd

## 서비스 정상 구동 및 로그 검사
sudo systemctl status zenohd

이제 이 리눅스 서버 장비는 당신의 홈 네트워크 혹은 사내 전산망에서 언제든지 트래픽을 처리해 줄 든든한 Zenoh 라우팅 피어(Peer) 노드로 거듭났다.

4. 윈도우(Windows) 환경에서의 설치 및 환경 변수 구성

데스크톱 환경에서의 애플리케이션 개발자이거나, 게임 엔진(Unreal, Unity) 연동, 혹은 산업용 Windows 머신에서 데이터를 뽑아내야 하는 상황이라면 Windows OS 상에 Zenoh를 이식해야 한다. Windows 환경에서는 무거운 인스톨러 프로그램(.exe, .msi) 포맷 대신, 깔끔하게 컴파일된 독립 실행형(Standalone) 바이너리 압축 파일을 직접 다운로드하여 환경 변수에 수동으로 연결하는 방식을 주로 취한다.

4.1 릴리스 아카이브(Archive) 다운로드

Eclipse Zenoh의 공식 GitHub 저장소(Repository) 릴리스(Releases) 탭으로 이동하라. 버전 번호(예: 1.0.0 이상)에 맞춰 Windows x86_64 아키텍처용으로 빌드된 압축 파일 포맷(.zip)을 찾는다. 파일명은 대략 zenoh-<버전 번호>-x86_64-pc-windows-msvc.zip 형태를 띨 것이다.

해당 아카이브를 다운로드한 후, 사용자가 선호하는 로컬 디스크의 특정 폴더(예: C:\tools\zenoh 또는 기타 유틸리티 전용 디렉터리)를 생성하고 그 안에 압축을 해제하라.

폴더 내부에는 zenohd.exe를 비롯하여 패킷 확인을 위한 CLI 유틸리티(zenoh-cli.exe 혹은 분리된 형태의 z_pub.exe, z_sub.exe 등)가 존재해야 한다.

4.2 Windows 시스템 환경 변수(Enviroment Variables) Path 등록

다운로드한 바이너리 파일들을 언제 어느 터미널 경로에서든 zenohd라는 짧은 단어 단 세 음절로 즉답하여 실행시키려면, 방금 생성한 바이너리의 물리적 디렉터리 주소를 Windows OS의 환경 변수 Path에 집어넣어 주어야 한다.

  1. 키보드의 Windows Key를 누르고 “환경 변수 편집” (Edit the system environment variables)을 검색하여 클릭한다.
  2. 하단에 있는 환경 변수(Environment Variables) 버튼을 클릭한다.
  3. 상단 패널의 ‘사용자 변수’ 혹은 하단 패널의 ‘시스템 변수(System variables)’ 영역 모음 중 Path 변수 항목을 마우스로 더블 클릭한다.
  4. 패널 우측 상단에 위치한 새로 만들기(New) 버튼을 누르고, 앞서 zenohd.exe 바이너리를 압축 해제해 둔 절대 경로 폴더(예: C:\tools\zenoh)를 키보드로 타이핑하여 추가한다.
  5. 모든 대화상자에서 확인(OK) 버튼을 눌러 적용을 저장하고 시스템 패널을 완전히 닫는다.

4.3 터미널(Command Prompt / PowerShell)을 통한 설치 무결성 구동 테스트

Path 등록이 끝났다면 운영체제가 변경 사항을 실시간으로 감지할 수 있도록, 현재 열려있는 모든 Windows 터미널(CMD 또는 PowerShell) 창을 닫고 새로운 창을 하나 띄워라.

새로 연 터미널의 커맨드 라인 어디에서든 프롬프트 창에 다음 명령어를 입력하라.

zenohd --version

명령어 실행과 동시에 zenohd 1.0.0 ... 과 같은 식의 라이브러리 엔진 빌드 버전 출력 문구가 터미널 화면에 정상적으로 튀어나온다면, Windows 개발 환경에서의 코어 인프라스트럭처 세팅이 완벽하게 끝난 것이다.

이제 이 Windows 랩탑은 zenohd 명령어를 한 번 치는 것만으로도 언제든 거대한 글로벌 브로드캐스트 분산 네트워크 토폴로지의 중심축 라우터 역할을 자처할 막강한 권한을 손에 쥐게 되었다.

5. macOS 환경에서의 Homebrew 기반 설치

현대 소프트웨어 엔지니어들의 가장 친숙한 로컬 개발 장비인 macOS(Apple Silicon 및 Intel) 환경에서는, 복잡한 압축 해제나 PATH 경로 삽입 과정을 모두 자동화해 주는 Homebrew 패키지 매니저를 통한 설치가 가장 권장된다.

5.1 Eclipse Zenoh 비공식/공식 Homebrew 탭(Tap) 연동

Zenoh는 아직 Homebrew의 기본 중앙 저장소(Core)에 병합되지 않은 버전이 존재할 수 있으므로, Eclipse 재단이나 커뮤니티가 제공하는 전용 탭(Tap)을 먼저 시스템에 추가하는 것이 안전하다. (최근 릴리스에서는 Brew 코어에 편입되어 바로 설치가 가능할 수도 있다.)

터미널을 열고 다음 명령어를 실행하여 탭을 추가하고 패키지를 설치하라.

## 확장 패키지 저장소(Tap) 추가
brew tap eclipse-zenoh/zenoh

## zenohd 라우터 및 zenoh-cli 도구 설치
brew install zenoh

명령어가 종료되면 zenohd 바이너리가 /opt/homebrew/bin/ (Apple Silicon 기준) 또는 /usr/local/bin/ (Intel Mac 기준) 디렉터리에 자동으로 심볼릭 링크(Symbolic Link)되며, 시스템 환경 변수 설정 절차가 완전히 생략된다.

5.2 구동 테스트 및 macOS 보안 경고(Gatekeeper) 대응

설치가 끝났다면 바로 터미널에서 버전을 검증해 본다.

zenohd --version

주의사항 (Gatekeeper 차단):
만약 Homebrew가 아닌 GitHub 저장소에서 Mac용 .zip 바이너리를 직접 수동으로 다운로드 받아 실행했다면, macOS의 악성코드 방어 체계인 Gatekeeper가 “확인되지 않은 개발자의 앱” 이라며 강제로 실행을 차단(Kill)할 것이다.

이때는 당황하지 말고, 시스템 설정(System Settings) -> 개인정보 보호 및 보안(Privacy & Security) 탭의 하단으로 스크롤하여, “zenohd이(가) 차단되었습니다” 라는 문구 옆의 [확인 없이 허용(Allow Anyway)] 버튼을 클릭해야만 정상적인 구동이 가능하다. (Homebrew를 통한 설치 시에는 이 서명 우회 과정이 대부분 자동으로 처리된다.)

5.3 백그라운드 서비스(Launchd) 구동

리눅스의 systemd처럼 Mac을 부팅할 때마다 Zenoh 라우터가 아무도 모르게 뒤에서 돌게 만들고 싶다면, Homebrew Services 기능을 이용해 macOS의 고유 시스템 데몬인 launchd에 zenohd를 등록할 수 있다.

## macOS 백그라운드 서비스로 zenoh 등록 및 즉시 실행
brew services start zenoh

## 현재 백그라운드에서 돌고 있는 서비스 목록 확인
brew services list

## 더 이상 데몬이 필요 없을 때 중지 및 서비스 내리기
brew services stop zenoh

이렇게 구성된 Mac 랩탑은, 로컬 디버깅 과정에서 zenohd 터미널 창을 실수로 닫아버려서 전체 피어(Peer) 네트워크가 붕괴되는 개발자의 흔한 실수를 원천적으로 차단해 준다.

6. Docker를 활용한 컨테이너 기반 zenohd 실행

클라우드 데이터센터(AWS, GCP 메인 백본 서버)에 라우터를 띄우거나, 쿠버네티스(Kubernetes) 팟(Pod) 형태로 인프라를 스케일 아웃(Scale-out) 시키고자 할 때는 더 이상 물리적인 .exe나 APT 패키지를 고민하지 않는다. 모든 것을 감싸버리는 가상화 컨테이너, Docker 환경에서의 zenohd 실행이 표준이 된다.

Eclipse Zenoh 프로젝트는 Docker Hub 및 알파인(Alpine) 기반의 초경량 공식 이미지를 주기적으로 퍼블리시하고 있다.

6.1 Eclipse 공식 Docker 이미지 가져오기 및 단일 실행

로컬 호스트 OS에 아무것도 설치할 필요 없이, Docker 데몬만 돌아가고 있다면 아래 명령어 한 줄로 즉각적인 라우팅 네트워크가 구동된다.

## Docker Hub에서 공식 eclipse/zenoh 이미지 풀링 및 컨테이너 실행
docker run --init -p 7447:7447/tcp -p 7447:7447/udp eclipse/zenoh
  1. --init 플래그: 컨테이너 특성상 라우터 프로세스가 PID 1을 점유할 때 발생하는 좀비 프로세스(Zombie Process) 및 시스템 종료 시그널(SIGTERM) 멈춤 현상을 방지하기 위해 반드시 삽입해야 하는 안전장치다.
  2. -p 7447:7447 매핑: 3.1.3절 방화벽 규칙에서 다루었듯, 컨테이너 내부의 포트와 외부 현실 호스트의 TCP/UDP 7447 포트를 구멍 뚫어 엮어주는 필수 옵션이다.

6.2 로컬 디스커버리(Scouting)를 위한 호스트 네트워크 모드

위 명령어의 단점은, 도커 내부의 가상 브릿지망에 갇혀 있기 때문에 동일 IP 대역(Subnet)에 물리적으로 존재하는 라즈베리파이나 랩탑들이 뿜어내는 ’UDP 멀티캐스트 탐색(Scout) 패킷’을 도커가 듣지 못한다는 것이다.

가십 방식(Gossip)이 아닌, 켜자마자 서로를 찾는 마법(Scouting)을 컨테이너에서도 구사하게 하려면 라우팅 공간 차단을 해제하는 --net=host 구동 방식이 권장된다.

## 호스트 OS의 네트워크 인터페이스를 100% 공유 (macOS의 Docker Desktop 에선 지원되지 않음에 주의!)
docker run --init --net=host eclipse/zenoh

6.3 볼륨 마운트(Volume Mount)를 통한 설정 파일(Config) 주입

순정 상태의 도커 이미지는 인메모리 위에서만 돌아갈 뿐, 라우팅 토폴로지 구조나 스토리지 백엔드(RocksDB 등) 설정이 전무하다. 따라서 호스트 PC에 작성해 둔 사용자 정의 라우터 설정 파일(zenoh.json5 - 4.3절 참조)을 도커가 켜질 때 밀어 넣어주는(Mount) 테크닉이 구사되어야 한다.

## 내 PC의 /opt/zenoh_config/ 디렉터리를 컨테이너 안으로 덮어씌움
docker run --init --net=host \
  -v /opt/zenoh_config:/etc/zenoh \
  eclipse/zenoh -c /etc/zenoh/my_config.json5

이 방식을 터득한다면, 컨테이너 이미지를 매번 새로 구울 필요 없이 텍스트 설정 파일 조작만으로 전 세계 백본 라우터를 마음대로 주무를 수 있는 DevOps의 신세계가 열리게 될 것이다.

7. 소스코드를 통한 직접 컴파일 및 커스텀 빌드 방법

대부분의 엔지니어는 앞서 다룬 사전 컴파일된 바이너리로 충분하다. 그러나 인프라의 최정점에 서야 하는 아키텍트, 혹은 최신 버전(Nightly Build)의 버그 픽스가 급박하거나 자신만의 커스텀 C++ 스토리지 백엔드를 라우터 엔진(Plugin) 깊숙이 엮어 넣고 싶은 해커라면, Zenoh(제노) 코어 소스코드 깃 레이크(Git Lake) 바닥부터 퍼 올려 직접 빌드(Compile)하는 인고의 과정을 거쳐야 한다.

이 과정은 전적으로 Zenoh의 모국어인 Rust 생태계 툴체인 위에서 이루어진다.

7.1 Rust 빌드 툴체인 준비 및 소스코드 복제

먼저 운영체제에 Rust 공식 컴파일러 세트인 rustup과 패키지 빌더 cargo가 완전히 설치되어 있어야 한다. (Rust 환경 구축의 기초는 3.3.1절에서 연이어 상세히 다룬다.)

터미널을 열고 Eclipse Foundation의 Zenoh 코어 저장소(Repository) 전체를 로컬 장비로 내려받는다.

## 최신 개발 소스트리 복제(Clone)
git clone https://github.com/eclipse-zenoh/zenoh.git
cd zenoh

## 혹은 특정 안정화된 릴리스 태그로 브랜치 체크아웃
git checkout tags/1.0.0 -b stable-1.0.0

7.2 Cargo를 이용한 릴리스(Release) 타겟 최적화 빌드

Zenoh 코드는 수백 개의 크레이트(Crate, 러스트의 패키지 단위)로 잘게 쪼개져 있는 거대한 워크스페이스 구조다. 루트 디렉터리에서 zenohd(라우터)와 zenoh-cli 유틸리티를 최고 수준의 컴파일러 최적화 옵션이 적용된 상태로 빌드한다.

## --release 플래그: 실행 속도 최적화를 위해 매우 중요함 (초보자들이 흔히 빼먹는 옵션)
cargo build --release --bin zenohd
cargo build --release --bin zenoh-cli

컴파일이 끝나면 보통 커피 한 잔을 비우고도 남을 시간이 소요될 수 있다(Rust 컴파일러의 악명 높은 엄격함 때문이다). 완료된 바이너리 전리품들은 ./target/release/ 디렉터리 내부에 고스란히 담겨있게 되며, 이를 전역 PATH 경로로 복사해 사용하면 된다.

7.3 플러그인(Plugins) 피처(Feature) 선택적 빌드 통합

직접 빌드의 가장 거대한 메리트는 **“원하는 모듈(Feature)만 살리고 죽여서 바이너리 용량을 조절하는 권한”**에 있다.

예를 들어, REST API 플러그인 기능과 InfluxDB 데이터베이스 연동 기능이 내장된 극한의 풀옵션 zenohd 라우터를 만들어내고 싶다면, Cargo 빌드 명령어 인자에 쉼표(,)로 구분되는 피처 플래그 세트를 강제로 주입해야 한다.

## 기본 옵션에 REST 플러그인 등 특정 피처를 활성화하여 라우터 엔진 빌드
cargo build --release --bin zenohd --features "plugins, rest, influxdb"

반대로 극단적으로 메모리가 부족한 최말단 라우터를 위해 불필요한 관제 스레드와 로그 수집 시스템을 모두 컴파일 단계에서 도려내 버리는 것도 가능하다. 이렇게 탄생한 당신만의 커스텀 zenohd는 1MB 안팎의 살인적으로 가벼운 몸집으로 로봇 제어 보드의 여백을 채워줄 궁극의 데이터 버스로 활약하게 될 것이다.