Apache Guacamole 은 세 조각으로 나뉜다. 브라우저가 붙는 웹 애플리케이션(Tomcat), 실제 RDP · VNC · SSH 를 말하는 guacd, 그리고 사용자와 연결 정의를 담은 인증 백엔드(보통 MySQL/MariaDB 또는 PostgreSQL)다.
[브라우저] → [guacamole (Tomcat)] → [guacd:4822] → [RDP / VNC / SSH 대상]
↓
[MySQL / PostgreSQL]
증상이 로그인 실패인지 연결 실패인지에 따라 봐야 할 조각이 다르다. 로그가 그것을 바로 알려 준다.
설정 파일은 GUACAMOLE_HOME(기본 /etc/guacamole) 아래에 둔다. 형식은 키: 값 이고, 키는 점이 아니라 하이픈으로 구분한다.
guacd-hostname: guacd
guacd-port: 4822
mysql-hostname: mariadb
mysql-port: 3306
mysql-database: guacamole
mysql-username: guacamole
mysql-password: ${GUACAMOLE_DB_PASSWORD}
자주 틀리는 곳이 두 군데다. 첫째, guacamole.auth-provider 같은 키는 현행 버전에 없다. 인증 방식은 GUACAMOLE_HOME/extensions/ 에 넣은 확장 JAR 로 결정되므로 설정 파일에 적을 필요가 없고, 적으면 무시된다. 둘째, 컨테이너 환경에서 guacd-hostname: localhost 는 거의 항상 틀렸다 — guacd 는 다른 컨테이너이므로 서비스 이름이나 실제 호스트를 적는다.
docker exec -it guacamole cat /etc/guacamole/guacamole.properties
docker exec -it guacamole ls -al /etc/guacamole/extensions
WARN o.a.g.event.EventLoggingListener - Authentication attempt from [...]
for user "guacadmin" failed: Invalid login (rejected by "mysql")
인증 확장까지는 정상적으로 도달했고 계정이 거부된 것이다.
계정과 비밀번호가 맞는데도 거부된다면 확장이 여러 개 들어 있는 경우를 먼저 의심한다. extensions/ 에 JDBC 확장과 함께 LDAP · 헤더 · TOTP 확장 JAR 이 섞여 있으면 인증 순서가 꼬여 의도한 백엔드에 닿기 전에 거부된다. 쓰지 않는 확장 JAR 을 모두 치우고 하나만 남긴 뒤 재시작한다.
초기 계정으로 들어가지 못하면 스키마가 적재되지 않았을 수 있다. guacamole_user 테이블에 guacadmin 이 있는지 직접 본다.
SELECT entity_id, password_date FROM guacamole_user;
로그에 Loading class com.mysql.jdbc.Driver is deprecated 경고가 보이는 것은 무해하다. 인증 실패의 원인이 아니다.
ERROR o.a.g.w.GuacamoleWebSocketTunnelEndpoint - Creation of WebSocket tunnel to guacd failed:
java.net.ConnectException: Connection refused
로그인은 성공했고 실제 세션을 열지 못한 것이다. 웹 애플리케이션이 guacd 에 TCP 로 붙지 못한다는 뜻이므로 네 가지를 본다.
guacd-hostname 이 실제 도달 가능한 이름인지 확인한다. Docker Compose 라면 서비스 이름, Kubernetes 라면 Service 이름이다.
guacd 가 4822 를 듣고 있는지 확인한다. 기동 로그에 다음이 있어야 한다.
guacd[7]: INFO: Listening on host 0.0.0.0, port 4822
컨테이너가 같은 네트워크에 있는지 본다.
docker exec -it guacamole sh -c 'getent hosts guacd; nc -z -v guacd 4822'
guacd 를 -b 127.0.0.1 로 띄웠다면 다른 컨테이너에서 붙지 못한다. -b 0.0.0.0 이어야 한다.
연결 정의마다 WOL 을 켤 수 있다. 연결 편집 화면의 Wake-on-LAN 항목에 대상의 MAC 주소, 브로드캐스트 주소, 그리고 부팅을 기다릴 시간(초)을 넣는다.
동작 조건이 까다로운 편이다. guacd 가 도는 호스트가 대상과 같은 브로드캐스트 도메인에 있어야 매직 패킷이 닿는다. 라우터를 넘어가야 하면 브로드캐스트 주소를 해당 서브넷의 브로드캐스트 주소로 지정하고 경로 상의 장비가 directed broadcast 를 허용해야 하는데, 대부분의 장비는 기본적으로 막는다. 대상 쪽에서는 BIOS/UEFI 의 WOL 항목과 OS 의 네트워크 어댑터 설정이 모두 켜져 있어야 한다.
리눅스 대상이라면 다음으로 확인한다.
ethtool eth0 | grep -i wake
sudo ethtool -s eth0 wol g
Wake-on: g 면 매직 패킷으로 깨어난다. 재부팅하면 설정이 풀리는 배포판이 있으므로 영구 적용은 NetworkManager 나 systemd 유닛으로 잡는다.