开源堡垒机Guacamole二次开发记录之一

简介

项目中需要用到堡垒机功能，调研了一大圈，发现了Apache Guacamole这个开源项目。

Apache Guacamole 是一个无客户端的远程桌面网关，它支持众多标准管理协议，例如 VNC(RFB)，RDP，SSH 等等。该项目是Apache基金会旗下的一个开源项目，也是一个较高标准，并具有广泛应用前景的项目。

当Guacamole被部署在服务器上后，用户通过浏览器即可访问已经开启 VNC(RFB)，RDP，SSH 等远程管理服务的主机，屏蔽用户使用环境差异，跨平台，另外由于Guacamole本身被设计为一种代理工作模型，方便对用户集中授权监控等管理，，也被众多堡垒机项目所集成，例如‘jumpserver’，‘next-terminal’。

Guacamole项目的主页如下：

Apache Guacamole™

Guacamole项目的架构如下图：

包括了guacd、guacamole、前端页面等几个模块。

其中，guacd是由C语言编写，接受并处理guacamole发送来的请求，然后翻译并转换这个请求，动态的调用遵循那些标准管理协议开发的开源客户端，例如FreeRDP，libssh2，LibVNC，代为连接Remote Desktops，最后回传数据给guacamole，guacamole回传数据给web browser。

guacamole是web工程，包含了java后端服务和angular前端页面， 通过servlet或websocket与前端界面交互，通过tcp与guacd交互。同时集成了用户管理、权限验证、数据管理等各种功能。这块的模块组成如下：

 我们项目中有很多自己的业务需求和界面需求，所以，Web这块决定不用开源自带的后端和界面，自己开发。基于guacamole-common和js库进行二次开发。

SpringBoot集成

POM：包含了guacamole-common、guacamole-common-js，以及servlet、websocket等。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-websocket</artifactId>
</dependency>

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>servlet-api</artifactId>
    <version>2.5</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>javax.websocket</groupId>
    <artifactId>javax.websocket-api</artifactId>
    <version>1.0</version>
    <scope>provided</scope>
</dependency>

<dependency>
    <groupId>org.apache.guacamole</groupId>
    <artifactId>guacamole-common</artifactId>
    <version>1.5.1</version>
</dependency>
<dependency>
    <groupId>org.apache.guacamole</groupId>
    <artifactId>guacamole-ext</artifactId>
    <version>1.5.1</version>
</dependency>

<dependency>
    <groupId>org.apache.guacamole</groupId>
    <artifactId>guacamole-common-js</artifactId>
    <version>1.5.1</version>
    <type>zip</type>
    <scope>runtime</scope>
</dependency>

可以通过servlet或websocket两种方式进行集成，推荐采用websocket方式，性能更好。

配置文件application.yml

server:
  port: 8080
  servlet:
    context-path: /

spring:
  servlet:
    multipart:
      enabled: false
      max-file-size: 1024MB
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/guac?useSSL=false&useUnicode=true&characterEncoding=UTF-8&serverTimezone=GMT%2b8
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver

mybatis-plus:
  mapper-locations: classpath:mapper/*.xml

guacamole:
  ip: 192.168.110.2
  port: 4822

WebSocket方式

从GuacamoleWebSocketTunnelEndpoint中继承类，重载createTunnel方法。

@ServerEndpoint(value = "/webSocket", subprotocols = "guacamole")
@Component
public class WebSocketTunnel extends GuacamoleWebSocketTunnelEndpoint {
    private String uuid;
    private static IDeviceLoginInfoService deviceLoginInfoService;
    private static String guacIp;
    private static Integer guacPort;
    private GuacamoleTunnel guacamoleTunnel;


    // websocket中，自动注入及绑定配置项必须用这种方式
    @Autowired
    public void setDeviceListenerService(IDeviceLoginInfoService deviceListenerService) {
        WebSocketTunnel.deviceLoginInfoService = deviceListenerService;
    }

    @Value("${guacamole.ip}")
    public void setGuacIp(String guacIp) {
        WebSocketTunnel.guacIp = guacIp;
    }

    @Value("${guacamole.port}")
    public void setGuacPort(Integer guacPort) {
        WebSocketTunnel.guacPort = guacPort;
    }

    @Override
    protected GuacamoleTunnel createTunnel(Session session, EndpointConfig endpointConfig) throws GuacamoleException {
        //从session中获取传入参数
        Map<String, List<String>> map = session.getRequestParameterMap();

        DeviceLoginInfoVo loginInfo = null;

        String did = map.get("did").get(0);
        tid = map.get("tid").get(0);
        tid = tid.toLowerCase();

        // 根据传入参数从数据库中查找连接信息
        loginInfo = deviceLoginInfoService.getDeviceLoginInfo(did, tid);
        if(loginInfo != null) {
            loginInfo.setPort(opsPort);
        }

        if(loginInfo != null) {
            //String wid = (map.get("width")==null) ? "1413" : map.get("width").get(0);
            //String hei = (map.get("height")==null) ? "925" : map.get("height").get(0);
            String wid = "1412";
            String hei = "924";

            GuacamoleConfiguration configuration = new GuacamoleConfiguration();

            configuration.setParameter("hostname", loginInfo.getIp());
            configuration.setParameter("port", loginInfo.getPort().toString());
            configuration.setParameter("username", loginInfo.getUser());
            configuration.setParameter("password", loginInfo.getPassword());

            if(tid.equals("ssh")) {
                configuration.setProtocol("ssh"); // 远程连接协议
                configuration.setParameter("width", wid);
                configuration.setParameter("height", hei);
                configuration.setParameter("color-scheme", "white-black");
                //configuration.setParameter("terminal-type", "xterm-256color");
                //configuration.setParameter("locale", "zh_CN.UTF-8");
                configuration.setParameter("font-name", "Courier New");
                configuration.setParameter("enable-sftp", "true");
            }
            else if(tid.equals("vnc")){
                configuration.setProtocol("vnc"); // 远程连接协议
                configuration.setParameter("width", wid);
                configuration.setParameter("height", hei);
            }
            else if(tid.equals("rdp")) {
                configuration.setProtocol("rdp"); // 远程连接协议
                configuration.setParameter("ignore-cert", "true");
                if(loginInfo.getDomain() !=null) {
                    configuration.setParameter("domain", loginInfo.getDomain());
                }

                configuration.setParameter("width", wid);
                configuration.setParameter("height", hei);
            }

            GuacamoleClientInformation information = new GuacamoleClientInformation();
            information.setOptimalScreenHeight(Integer.parseInt(hei));
            information.setOptimalScreenWidth(Integer.parseInt(wid));

            GuacamoleSocket socket = new ConfiguredGuacamoleSocket(
                    new InetGuacamoleSocket(guacIp, guacPort),
                    configuration, information
            );

            GuacamoleTunnel tunnel = new SimpleGuacamoleTunnel(socket);

            guacamoleTunnel = tunnel;
            return tunnel;
        }

        return null;
    }
}

Servlet方式

从GuacamoleHTTPTunnelServlet类继承，重载doConnect方法

@WebServlet(urlPatterns = "/tunnel")
public class HttpTunnelServlet extends GuacamoleHTTPTunnelServlet {
    @Resource
    IDeviceLoginInfoService deviceLoginInfoService;

    @Value("${guacamole.ip}")
    private String guacIp;
    @Value("${guacamole.port}")
    private Integer guacPort;

	@Override
	protected GuacamoleTunnel doConnect(HttpServletRequest request) throws GuacamoleException {
        //从HttpServletRequest获取请求参数
        String did = request.getParameter("did");
        String tid = request.getParameter("tid");
        tid = tid.toLowerCase();

        //根据参数从数据库中查找连接信息，主机ip、端口、用户名、密码等
        DeviceLoginInfoVo loginInfo = deviceLoginInfoService.getDeviceLoginInfo(did, tid);

        if(loginInfo != null) {
            GuacamoleConfiguration configuration = new GuacamoleConfiguration();

            configuration.setParameter("hostname", loginInfo.getIp());
            configuration.setParameter("port", loginInfo.getPort().toString());
            configuration.setParameter("username", loginInfo.getUser());
            configuration.setParameter("password", loginInfo.getPassword());
            if(tid.equals("ssh")) {
                configuration.setProtocol("ssh"); // 远程连接协议
            }
            else if(tid.equals("vnc")){
                configuration.setProtocol("vnc"); // 远程连接协议
            }
            else if(tid.equals("rdp")) {
                configuration.setProtocol("rdp"); // 远程连接协议
                configuration.setParameter("ignore-cert", "true");
                if(loginInfo.getDomain() != null) {
                    configuration.setParameter("domain", loginInfo.getDomain());
                }
                configuration.setParameter("width", "1024");
                configuration.setParameter("height", "768");
            }

            GuacamoleSocket socket = new ConfiguredGuacamoleSocket(
                    new InetGuacamoleSocket(guacIp, guacPort),
                    configuration
            );

            GuacamoleTunnel tunnel = new SimpleGuacamoleTunnel(socket);

            return tunnel;
        }

        return null;
	}
}

前端页面

我用的是最基本的html+js

<!DOCTYPE HTML>
<html>
<head>
    <meta charset="UTF-8">
    <link rel="stylesheet" type="text/css" href="guacamole.css"/>
    <title>guac</title>
    <style>

    </style>
</head>
<body>
<div id="mainapp">
    <!-- Display -->
    <div id="display"></div>
</div>

<!-- Guacamole JavaScript API -->
<script type="text/javascript" src="guacamole-common-js/all.js"></script>
<script type="text/javascript">
    function getUrlParam(name) {
        var reg = new RegExp("(^|&)" + name + "=([^&]*)(&|$)");
        var r = window.location.search.substr(1).match(reg);
        if(r != null) {
            return decodeURI(r[2]);
        }

        return null;
    }

    var user = getUrlParam('user');
    var devid = getUrlParam('did');
    var typeid= getUrlParam('tid');
    // var width = getUrlParam('width');
    // var height = getUrlParam('height');

    // Get display div from document
    var display = document.getElementById("display");

    var uuid;
    var tunnel = new Guacamole.ChainedTunnel(new Guacamole.WebSocketTunnel("webSocket"));
    var guac = new Guacamole.Client(tunnel);

    // Add client to display div
    display.appendChild(guac.getDisplay().getElement());

    tunnel.onuuid = function(id) {
        uuid = id;
    }

    // Connect
    guac.connect('did='+devid+'&tid='+typeid+'&user='+user);

    // Disconnect on close
    window.onunload = function() {
        guac.disconnect();
    }

    // Mouse
    var mouse = new Guacamole.Mouse(guac.getDisplay().getElement());

    mouse.onmousedown =
        mouse.onmousemove = function(mouseState) {
            guac.sendMouseState(mouseState);
        };

    mouse.onmouseup = function(mouseState) {
        vueapp.showfile = false;
        guac.sendMouseState(mouseState);
    };

    // Keyboard
    var keyboard = new Guacamole.Keyboard(document);

    keyboard.onkeydown = function (keysym) {
        guac.sendKeyEvent(1, keysym);
    };

    keyboard.onkeyup = function (keysym) {
        guac.sendKeyEvent(0, keysym);
    };

    function setWin() {
        let width = window.document.body.clientWidth;
        let height = window.document.body.clientHeight;
        guac.sendSize(1412, 924);
        scaleWin();
    }

    function handleMouseEvent(event) {
        // Do not attempt to handle mouse state changes if the client
        // or display are not yet available
        if(!guac || !guac.getDisplay())
            return;

        event.stopPropagation();
        event.preventDefault();
        // Send mouse state, show cursor if necessary
        guac.getDisplay().showCursor(true);
    };

    // Forward all mouse interaction over Guacamole connection
    mouse.onEach(['mousemove'], handleMouseEvent);
    // Hide software cursor when mouse leaves display
    mouse.on('mouseout', function hideCursor() {
        guac.getDisplay().showCursor(false);
        display.style.cursor = 'initial';
    });

    guac.getDisplay().getElement().addEventListener('mouseenter', function (e) {
        display.style.cursor = 'none';
    });
</script>
</body>
</html>

将页面放在Springboot项目的resource下的static下，启动程序，通过地址

http://ip:8080?did=1&tid=ssh访问，可以打开远程桌面。

可以看出guacamole-common和guacamole-common-js已经做了很好的封装，对于SSH、VNC、RDP这几种远程方式，可以很简单的实现。

接下来，SFTP的实现较为复杂，需要对SFTP上传下载的流程及guacamole封装的协议有较好的了解，才能实现。另外对于录屏及录屏的播放，因为我们的项目中需要把guac和java后端分开两台服务器部署，所以也要有点工作要做。这两部分内容见下一篇博文。