지브라 프린터 웹 연동 (Tomcat 설정, SSL 인증서, ZPL 변환)
회사에서 RFID 기반 자산 관리 시스템을 만들어야 했을 때, 저는 솔직히 “이게 꼭 필요한가?” 하는 생각부터 들었습니다. 그런데 막상 지브라(Zebra) 프린터와 Tomcat 서버를 연동하는 작업에 뛰어들고 나서, 고가 장비보다 오히려 SSL 인증서 하나가 더 큰 복병이라는 걸 알게 됐습니다. 그 삽질의 기록을 그대로 풀어보겠습니다.
Tomcat 설정, 처음엔 뭐가 문제인지도 몰랐습니다
이 프로젝트를 처음 받았을 때 저는 PHP 개발자였습니다. 갑자기 Tomcat으로 구동되는 스프링(Spring) 프로젝트를 만지게 됐으니, 환경 세팅부터가 낯선 싸움이었습니다. Tomcat이란 자바(Java) 기반 웹 애플리케이션을 구동하기 위한 오픈소스 서블릿 컨테이너(Servlet Container)입니다. 쉽게 말해 PHP에서 Apache가 하는 역할을 자바 환경에서 담당하는 서버라고 보면 됩니다.
Eclipse에서 Tomcat을 연동하는 순서는 다음과 같습니다. 저도 이 순서를 몇 번씩 반복하면서 겨우 손에 익혔습니다.
- Eclipse 메뉴에서 Window → Preferences → Server → Runtime Environments로 이동한다.
- Add 버튼을 클릭하고, Apache Tomcat v7.0을 선택한 뒤 Next를 누른다.
- Browse로 Tomcat 설치 경로를 지정하고, JRE 버전이 1.7 이상인지 반드시 확인한다.
- 생성된 Server 프로젝트에 .p12 인증서 파일을 복사하고, server.xml에 Connector 설정을 추가한다.
- Servers 탭에서 Tomcat을 더블클릭해 Modules 탭으로 이동, Add External Web Module로 WeblinkServlet 폴더를 경로로 지정하고 Path에 /zebra를 입력한다.
- ZebraWebServicesDeveloperDemo 프로젝트를 우클릭 후 Run As → Run on Server로 실행한다.
이 과정을 처음 따라갈 때 제가 계속 걸렸던 부분은 JRE 설정이었습니다. JRE(Java Runtime Environment)란 자바 프로그램이 실행되는 데 필요한 런타임 환경을 뜻하는데, 버전이 맞지 않거나 인증서가 신뢰 목록에 등록되지 않으면 서버 자체가 뜨질 않습니다. 처음엔 에러 메시지만 보고 Tomcat 설정 문제인 줄 알았는데, 알고 보면 전부 JRE 인증서 문제였습니다. 이게 예상 밖이었습니다.
Tomcat 공식 문서는 Apache Tomcat 7.0 공식 문서에서 확인할 수 있습니다. 설치 방법부터 서블릿 설정까지 꽤 상세하게 나와 있으니, 환경 세팅 전에 한 번은 읽어두는 게 낫습니다.
SSL 인증서, 이게 진짜 고비였습니다
Tomcat 세팅보다 훨씬 오래 걸린 건 SSL 인증서 연동이었습니다. 지브라 WebLink 방식으로 프린터가 서버에 접속하려면, 서버가 HTTPS로 열려 있어야 하고 프린터가 그 인증서를 신뢰해야 합니다. 여기서 사용하는 게 ZebraCAChain.cer이라는 인증서 파일입니다. ZebraCAChain.cer이란 지브라 기기가 서버를 신뢰할 수 있는지 검증하는 루트 CA(Certificate Authority, 인증 기관) 체인 파일입니다.
문제는 이 인증서를 JRE의 신뢰 저장소(Truststore)에 등록하는 과정이었습니다. Truststore란 JVM이 신뢰하는 인증서 목록을 보관하는 저장소를 말합니다. 이걸 빠뜨리면 서버는 멀쩡히 뜨는데 프린터가 연결을 거부합니다. 제가 직접 이 삽질을 며칠 동안 했습니다. 로그를 보면 SSL handshake failure라고만 나오는데, 그 원인이 Truststore 문제인지, Connector 설정 문제인지 처음엔 전혀 구분이 안 됐습니다.
추가로 .p12 파일도 이해해야 했습니다. .p12(PKCS#12)란 개인 키와 인증서를 하나의 파일에 묶어놓은 포맷으로, 서버가 자신의 신원을 증명할 때 씁니다. 이 파일을 Eclipse의 Server 프로젝트 폴더에 복사하고, server.xml의 Connector 항목에 keystoreFile, keystorePass 속성으로 연결해야 비로소 HTTPS가 정상 작동합니다. 인증서 발급과 등록이 완료되고 나서 프린터가 서버에 붙었을 때, 솔직히 그 순간의 쾌감은 꽤 컸습니다.
SSL/TLS 인증서 구조나 체인 개념에 대해서는 OpenSSL 공식 문서를 참고하면 개념 잡는 데 도움이 됩니다. 특히 CA 체인이 왜 필요한지 이해하면 이후 트러블슈팅이 훨씬 빨라집니다.
ZPL 변환, 지브라만의 언어를 배워야 했습니다
프린터 연결이 됐다고 끝이 아니었습니다. RFID 라벨을 실제로 출력하려면 ZPL(Zebra Programming Language)이라는 언어를 써야 합니다. ZPL이란 지브라 프린터 전용 명령어 언어로, 텍스트·바코드·그래픽의 위치와 크기를 코드로 정의해 프린터에 전달하는 방식입니다. 일반 프린터에 HTML을 보내는 것과 완전히 다른 개념입니다.
저는 이때까지 바코드 라벨 하나면 빅솔론(BIXOLON) 같은 일반 라벨 프린터로도 충분하다고 생각했었습니다. 그런데 RFID 라벨은 단순 인쇄가 아니라 태그(Tag) 안의 칩에 데이터를 쓰는(Encoding) 작업까지 포함됩니다. RFID 인코딩(Encoding)이란 라벨에 내장된 IC 칩에 자산 고유 번호를 전자적으로 기록하는 과정입니다. 이 인코딩 명령어까지 ZPL 안에 포함시켜야 하기 때문에, 일반 HTML이나 이미지를 ZPL로 변환하는 컨버터 작업이 별도로 필요했습니다.
변환 과정에서 제가 쓴 방식은 기존에 디자인된 라벨 레이아웃을 ZPL 명령어로 바꾸는 것이었습니다. ^XA로 시작해서 ^XZ로 끝나는 ZPL 구조, ^FO로 위치를 잡고 ^FD로 데이터를 넣는 방식을 하나씩 파악해야 했습니다. 처음에는 ZPL 레퍼런스 문서를 옆에 열어두고, 명령어 하나하나를 확인하면서 작업했던 기억이 납니다. 이 부분은 솔직히 PHP 개발자인 제 입장에서 가장 낯설고 오래 걸린 구간이었습니다.
그리고 프린터 자체 설정도 필요했습니다. 프린터의 SGD(Set-Get-Do) 명령어를 통해 weblink.ip.conn1.location 값을 서버의 FQDN(Fully Qualified Domain Name) 기반 HTTPS 주소로 지정해줘야 합니다. FQDN이란 네트워크에서 기기를 유일하게 식별할 수 있는 완전한 도메인 주소를 뜻합니다. 예를 들어 그냥 devserver가 아니라 devserver.company.internal 같은 형태입니다. 이 값을 설정하고 프린터를 재시작하면, 프린터가 서버에 접속을 시도하고 https://localhost/ZebraWebServicesDeveloperDemo/ 페이지에 연결된 프린터 목록이 뜨기 시작합니다. 그 화면을 처음 봤을 때 저도 모르게 자리에서 일어났던 기억이 납니다.
자주 묻는 질문
Q. 지브라 프린터 WebLink 연동 시 SSL 인증서 오류가 계속 나는 이유가 뭔가요?
A. 가장 많은 원인은 ZebraCAChain.cer 파일이 JRE의 Truststore에 등록되지 않은 경우입니다. keytool 명령어로 해당 인증서를 JRE cacerts 파일에 import한 뒤 Tomcat을 재시작해보시기 바랍니다. server.xml의 Connector에 keystoreFile 경로와 비밀번호가 정확히 입력됐는지도 함께 확인하시면 대부분 해결됩니다.
Q. ZPL 코드를 직접 작성하지 않고 변환할 수 있는 방법이 있나요?
A. 지브라에서 제공하는 ZebraDesigner나 Labelary 같은 온라인 ZPL 미리보기 도구를 활용하면 초반 학습 비용을 줄일 수 있습니다. 다만 RFID 인코딩 명령어가 포함된 ZPL은 결국 직접 작성해야 하는 부분이 생기기 때문에, ZPL 레퍼런스 문서는 한 번 정독해두시는 편이 낫습니다.
Q. Tomcat 7.0을 Eclipse에서 연동할 때 JRE 버전은 어떤 걸 써야 하나요?
A. 최소 JRE 1.7 이상이 필요합니다. 다만 현재 시점에서는 JDK 11 또는 17 LTS 버전을 쓰는 환경이 많으니, 프로젝트의 스프링 버전과 호환되는 JDK를 먼저 확인하고 맞추는 것이 좋습니다. Eclipse의 Preferences에서 설정한 JRE와 Tomcat이 바라보는 JRE가 일치하지 않으면 서버가 뜨지 않는 경우도 있으니 주의하시기 바랍니다.
Q. RFID 라벨 프린터 도입이 소규모 기업에도 실제로 필요한가요?
A. 저도 같은 생각이었습니다. 장비 수가 많지 않은 환경이라면 700만 원대 고가 프린터와 개발 공수를 투입하는 것보다 수작업 관리가 효율적일 수 있습니다. RFID 자산 관리는 수백 개 이상의 자산을 주기적으로 일괄 스캔해야 하는 환경, 또는 자산 위치 추적까지 필요한 경우에 투자 가치가 올라간다고 봅니다.
Q. 프린터가 서버에 연결됐는지 확인하는 방법이 있나요?
A. Tomcat 서버를 실행한 상태에서 https://localhost/ZebraWebServicesDeveloperDemo/ 주소로 접속하면 현재 서버에 연결된 프린터 목록이 표시됩니다. 프린터에서 SGD의 weblink.ip.conn1.location 값을 정확히 입력하고 재시작했는데도 목록에 나타나지 않는다면, 방화벽 또는 DNS 설정에서 FQDN이 제대로 해석되는지 먼저 점검해보시기 바랍니다.
이 작업을 마무리하고 나서 든 솔직한 생각은, 기술 자체보다 “이게 지금 이 규모에 맞는 선택이었나”라는 의문이었습니다. 개발자 한 명이 PHP 환경에서 Java 생태계로 건너와 SSL 인증서, ZPL 변환, Tomcat 설정을 처음부터 익혀야 했던 시간과 비용은 결코 작지 않았습니다. 그래도 RFID 라벨이 처음으로 인코딩되어 출력되던 순간의 뿌듯함은 확실히 있었고, 리더기 연동 개발은 다음 글에서 이어서 다루겠습니다.
—
참고: 나