🥑 Guacamole란?

Apache Guacamole는 원격 데스크톱 게이트웨이입니다. Guacamole의 특징은 브라우저 기반의 인터페이스를 제공하는 점입니다. 이를 통해 어떤 환경에서든 구속되지 않고 원격 데스크탑에 접속할 수 있게하는 것이 목적입니다.

The principle reason to use Guacamole is constant, world-wide, unfettered access to your computers - guacamole.apache.org, "Why use Guacamole?"

예를 들어 집에 Guacamole 서버를 켜두었을 때, Guacamole가 집에 있는 데스크탑에 대신 원격 접속하고, 사용자와 데스크탑의 사이에서 통신을 중계합니다.

사용자가 guacamole 서버의 ip로 접속하면 아래와 같은 웹 페이지 인터페이스가 표시됩니다. 사용자는 이 인터페이스를 통해 원하는 데스크톱에 원격 접속할 수 있습니다. 덕분에 어떤 환경에서든 별도의 원격 클라이언트 프로그램을 설치할 필요 없이 즉시 접속할 수 있습니다.

Guacamole가 게이트웨이라고 했었죠? 사용자와 Guacamole 서버는 http 통신을 사용하기 때문에 간혹 RDP(3899)나 VNC(5900), SSH(22) 포트가 막혀 있는 경우 유용하게 사용할 수 있습니다.

⚙️ 작동 원리

Apache Guacamole는 Tomcat 상에서 동작하여 웹 페이지 인터페이스를 제공하는 guacamole 서블릿 컨테이너와 원격 장치에 연결하여 실질적인 입출력을 수행하는 guacd 데몬으로 이루어져 있습니다.

👨‍🍳 설치하기

설치 방법으로는 Docker 방식과 Native 방식이 있습니다. Docker 방식은 편리하긴 하지만 오버헤드가 있기 때문에 Native 방식으로 진행하겠습니다.

저는 아래의 환경에서 설치를 진행했습니다.

환경: Raspberry Pi 4 Model B, Ubuntu 22.04.3 LTS
버전: Tomcat9, Guacamole 1.5.3, OpenJdk 11.0.21

1. Java 설치

$ sudo apt-get install openjdk-11-jdk

Java 버전이 너무 높으면 패키지 명의 변경으로 인한 충돌이 발생할 수 있으니 주의하셔야 합니다. 여기서는 11 버전으로 설치하겠습니다.

2. Guacamole Server 설치

2.1. 라이브러리 설치

Guacamole 서버를 빌드하기 위해 필요한 라이브러리를 설치해줍니다. 공식 설치 가이드의 의존성 단락에서 required dependencies와 optional dependencies를 안내하고 있으니 참고해보시면 좋을 것 같습니다.

$ sudo apt install build-essential libcairo2-dev libjpeg-turbo8-dev \
    libpng-dev libtool-bin libossp-uuid-dev libvncserver-dev \
    freerdp2-dev libssh2-1-dev libtelnet-dev libwebsockets-dev \
    libpulse-dev libvorbis-dev libwebp-dev libssl-dev \
    libpango1.0-dev libswscale-dev libavcodec-dev libavutil-dev \
    libavformat-dev

2.2 Guacamole 소스코드 다운로드

다음으로 Guacamole의 소스코드를 다운받아주고 압축을 해제합니다.

$ wget https://downloads.apache.org/guacamole/1.5.3/source/guacamole-server-1.5.3.tar.gz
$ tar -xvf guacamole-server-1.5.3.tar.gz
$ cd guacamole-server-1.5.3

2.3 Guacamole 소스코드 빌드

다운받은 소스코드를 빌드합니다.

$ sudo ./configure --with-init-dir=/etc/init.d --enable-allow-freerdp-snapshots
$ sudo make
$ sudo make install

2.4 리로딩

업데이트된 라이브러리와 데몬을 로드합니다.

$ sudo ldconfig
$ sudo systemctl daemon-reload

2.5 guacd 실행

guacd를 실행합니다.

$ sudo systemctl start guacd
$ sudo systemctl status guacd

2.6 guacd 데몬 등록하기

guacd가 자동으로 실행되도록 설정합니다.

$ sudo systemctl enable guacd

3. Guacamole 웹 애플케이션 설정

3.1 Tomcat 설치

$ sudo apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user

3.2 Guacamole Client 다운로드

$ wget https://downloads.apache.org/guacamole/1.5.3/binary/guacamole-1.5.3.war
$ sudo mv guacamole-1.5.3.war /var/lib/tomcat9/webapps/guacamole.war

3.3 tomcat, guacd 재시작

$ sudo systemctl restart tomcat9 guacd

4. 인증용 DB 설정

4.1 maria DB 설치

아래 명령어를 통해 maria DB를 설치합니다.

$ sudo apt install mariadb-server
$ sudo mysql_secure_installation

참고로 대문자, 숫자, 특수문자가 각 1자 이상 포함된 8자리 이상의 비밀번호로 지정해주자.

4.2 Mysql Connector 설치

$ wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.26.tar.gz
$ tar -xf mysql-connector-java-8.0.26.tar.gz
$ sudo mkdir -p /etc/guacamole/lib
$ sudo cp mysql-connector-java-8.0.26/mysql-connector-java-8.0.26.jar /etc/guacamole/lib/

4.3 JDBC Auth plugin 설치

$ wget https://downloads.apache.org/guacamole/1.5.3/binary/guacamole-auth-jdbc-1.5.3.tar.gz
$ tar -xf guacamole-auth-jdbc-1.5.3.tar.gz
$ sudo mkdir /etc/guacamole/extensions
$ sudo mv guacamole-auth-jdbc-1.5.3/mysql/guacamole-auth-jdbc-mysql-1.5.3.jar /etc/guacamole/extensions/

4.4 guacamole 계정 생성

아래에서 자신의 패스워드 부분은 수정해 실행하시면 됩니다.

$ mysql -u root -p

mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY '자신의 패스워드';
mysql> CREATE DATABASE guacamole_db;
mysql> CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY '자신의 패스워드';
mysql> GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
mysql> FLUSH PRIVILEGES;
mysql> quit

4.5 scheme 파일 설정

$ cd guacamole-auth-jdbc-1.5.3/mysql/schema
$ cat *.sql | mysql -u root -p guacamole_db

4.6 DB 접속 정보 설정

$ sudo vim /etc/guacamole/guacamole.properties

아래의 내용을 넣어주시면 됩니다.

# MySQL properties
mysql-hostname: 127.0.0.1
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: [자신의 패스워드]

4.7 서비스 재실행

$ sudo systemctl restart tomcat9 guacd mysql

4.8 서비스 동작 로그 확인

Tomcat 서버 로그를 확인해 오류는 없는지, 있다면 어떤 부분에서 발생하는지 확인해봅시다.

$ tail -f /var/lib/tomcat9/logs/catalina.out

🐣 계정 설정

브라우저로 접속하면 다음과 같은 페이지를 확인할 수 있습니다. 초기 아이디, 비밀번호는 guacadmin로 동일합니다.

기본 계정은 취약하기 때문에 새로운 관리자 계정을 생성해야 합니다. (1) 우측 상단의 계정을 눌러 (2) '세팅'을 선택합니다.

(1) 사용자 탭을 선택하고 (2) 새 사용자 버튼을 클릭합니다.

사용자 이름과 비밀번호를 입력하고 모든 권한을 준 뒤 저장합니다. 마지막으로, 새롭게 생성한 관리자 계정으로 로그인한 뒤 기본 관리자 계정(guacadmin)을 삭제해주면 Guacamole를 사용할 모든 준비가 끝납니다.

🔒 HTTPS 설정

원격 데스크탑의 화면과 키보드 등의 정보가 송수신되기 때문에 외부에서 접속할 때는 반드시 HTTPS 설정을 해주셔야 합니다. 이 내용까지 다루면 글이 너무 길어지니 후속 글에서 다루겠습니다.

📜 References

• linode.com, "Installing Apache Guacamole on Ubuntu and Debian"
• guacamole.apache.org, "Apache Guacamole Manual"