ghostunnel/ghostunnel

Ghostunnel Docker镜像文档

镜像概述和主要用途

Ghostunnel是一个轻量级TLS代理工具，支持双向认证，用于保护非TLS后端应用。它提供客户端和服务器两种运行模式，可替代stunnel，实现安全的网络通信代理。

• 服务器模式：运行在后端服务前端，接收TLS加密连接并代理至不安全的后端（TCP端口或UNIX域套接字）
• 客户端模式：监听不安全连接（TCP或UNIX域套接字）并代理至TLS加密服务

支持平台：Linux（x86-64推荐）、Darwin（macOS）、FreeBSD、OpenBSD、NetBSD及Windows（功能受限）。

核心功能和特性

访问控制

• 强制双向认证，要求所有连接提供有效客户端证书
• 支持基于客户端证书主题（或主题备用名称）的访问控制，适用于无原生访问控制的服务

证书热交换

• 运行时无需中断现有连接即可重载证书
• 支持信号触发（SIGUSR1）或定时自动重载，适配短期证书场景
• 支持SO_REUSEPORT的平台可实现最小停机时间的重启

监控与指标

• 内置状态监控功能，可收集连接数、新建连接速率、连接生命周期、超时等指标
• 支持导出至Graphite等监控系统，便于运维分析

安全性设计

• 默认启用TLS 1.2+及安全密码套件
• 支持PKCS#11接口，可配合硬件安全模块（HSM）保护私钥
• 提供安全默认配置，防止意外误配置

使用场景和适用范围

保护非TLS后端服务

• 为无TLS能力的遗留应用提供TLS终结能力
• 避免直接修改后端服务代码实现加密通信

客户端TLS代理

• 允许不支持TLS的客户端通过代理访问TLS加密服务
• 集中管理客户端证书和TLS配置

细粒度访问控制

• 为无原生权限控制的服务添加基于证书的访问策略
• 与SPIFFE X.509 SVID兼容，支持云原生环境身份验证

证书自动化场景

• 配合短期证书管理系统（如Vault）实现证书自动轮换
• 满足合规要求下的证书快速更新需求

详细使用方法和配置说明

基础命令格式

bash
# 查看帮助
ghostunnel --help
ghostunnel server --help
ghostunnel client --help

证书准备

需准备以下证书文件（可通过certstrap或OpenSSL生成）：

• CA证书（cacert.pem）
• 服务器证书/密钥（PKCS#12 keystore或PEM格式）
• 客户端证书/密钥（PKCS#12 keystore或PEM格式）

服务器模式

功能说明

监听TLS连接，解密后转发至后端服务。

基本参数

使用示例

1. 启动后端服务（如netcat）：

   bash
   nc -l localhost 8080
   

2. 启动Ghostunnel服务器模式：

   bash
   ghostunnel server \
     --listen localhost:8443 \
     --target localhost:8080 \
     --keystore server-keystore.p12 \
     --cacert cacert.pem \
     --allow-cn client \
     --status localhost:8081 \
     --timed-reload 300s
   

3. 客户端连接测试：

   bash
   openssl s_client \
     -connect localhost:8443 \
     -cert client-combined.pem \
     -key client-combined.pem \
     -CAfile cacert.pem
   

客户端模式

功能说明

监听不安全连接，加密后转发至TLS服务。

基本参数

使用示例

1. 启动TLS后端服务：

   bash
   openssl s_server \
     -accept 8443 \
     -cert server-combined.pem \
     -key server-combined.pem \
     -CAfile cacert.pem
   

2. 启动Ghostunnel客户端模式：

   bash
   ghostunnel client \
     --listen localhost:8080 \
     --target localhost:8443 \
     --keystore client-keystore.p12 \
     --cacert cacert.pem \
     --status localhost:8081
   

3. 测试连接：

   bash
   nc -v localhost 8080
   

全隧道模式（客户端+服务器）

功能说明

组合客户端和服务器模式，实现端到端加密隧道。

部署步骤

1. 启动最终后端服务：

   bash
   nc -l localhost 8001
   

2. 启动服务器端Ghostunnel：

   bash
   ghostunnel server \
     --listen localhost:8002 \
     --target localhost:8001 \
     --keystore server-combined.pem \
     --cacert cacert.pem \
     --allow-cn client
   

3. 启动客户端Ghostunnel：

   bash
   ghostunnel client \
     --listen localhost:8003 \
     --target localhost:8002 \
     --keystore client-keystore.p12 \
     --cacert cacert.pem
   

4. 测试端到端连接：

   bash
   nc -v localhost 8003
   

Docker部署方案

镜像信息

• 镜像名称：ghostunnel/ghostunnel
• 官方仓库：https://hub.docker.com/r/ghostunnel/ghostunnel

服务器模式部署示例

bash
docker run -d \
  --name ghostunnel-server \
  -p 8443:8443 \
  -p 8081:8081 \
  -v $(pwd)/test-keys:/etc/ghostunnel/keys \
  docker.xuanyuan.run/ghostunnel/ghostunnel \
  server \
    --listen 0.0.0.0:8443 \
    --target backend-service:8080 \
    --keystore /etc/ghostunnel/keys/server-keystore.p12 \
    --cacert /etc/ghostunnel/keys/cacert.pem \
    --allow-cn client \
    --status 0.0.0.0:8081 \
    --timed-reload 300s

客户端模式部署示例

bash
docker run -d \
  --name ghostunnel-client \
  -p 8080:8080 \
  -v $(pwd)/test-keys:/etc/ghostunnel/keys \
  docker.xuanyuan.run/ghostunnel/ghostunnel \
  client \
    --listen 0.0.0.0:8080 \
    --target tls-service.example.com:443 \
    --keystore /etc/ghostunnel/keys/client-keystore.p12 \
    --cacert /etc/ghostunnel/keys/cacert.pem \
    --server-cn tls-service.example.com

Docker Compose示例

yaml
version: '3'
services:
  ghostunnel-server:
    image: docker.xuanyuan.run/ghostunnel/ghostunnel
    ports:
      - "8443:8443"
      - "8081:8081"
    volumes:
      - ./test-keys:/etc/ghostunnel/keys
    command: >
      server
      --listen 0.0.0.0:8443
      --target backend:8080
      --keystore /etc/ghostunnel/keys/server-keystore.p12
      --cacert /etc/ghostunnel/keys/cacert.pem
      --allow-cn client
      --status 0.0.0.0:8081
      --timed-reload 300s
    depends_on:
      - backend

  backend:
    image: docker.xuanyuan.run/alpine
    command: nc -l -p 8080

  ghostunnel-client:
    image: docker.xuanyuan.run/ghostunnel/ghostunnel
    ports:
      - "8080:8080"
    volumes:
      - ./test-keys:/etc/ghostunnel/keys
    command: >
      client
      --listen 0.0.0.0:8080
      --target ghostunnel-server:8443
      --keystore /etc/ghostunnel/keys/client-keystore.p12
      --cacert /etc/ghostunnel/keys/cacert.pem

高级特性说明

证书热交换

• 信号触发：发送SIGUSR1信号至进程触发证书重载

  bash
  kill -USR1 <ghostunnel-pid>
  

• 定时重载：通过--timed-reload <interval>设置自动重载间隔（如--timed-reload 5m）
• 无缝重启：支持SO_REUSEPORT的平台可实现新实例先启动再关闭旧实例，避免连接中断

监控与指标

• 状态端口：通过--status <host:port>启用指标端点，支持以下路径：
  • /metrics：Prometheus格式指标
  • /health：健康检查端点
  • /debug/pprof：性能分析接口（需--enable-pprof）
• 指标类型：连接数、连接速率、握手耗时、连接生命周期、错误统计等

访问控制策略

支持多种证书验证规则（逻辑OR关系，满足其一即可）：

• --allow-all：允许所有有效证书
• --allow-cn <cn>：验证客户端证书CN
• --allow-ou <ou>：验证客户端证书OU
• --allow-dns <dns>：验证客户端证书DNS SAN
• --allow-uri <uri>：验证客户端证书URI SAN（支持SPIFFE SVID）

日志选项

通过--quiet参数抑制特定类型日志：

• --quiet=conns：抑制连接建立/关闭日志
• --quiet=conn-errs：抑制连接错误日志（握手后）
• --quiet=handshake-errs：抑制握手错误日志（适用于K8s健康检查场景）
• --quiet=all：抑制所有日志

PKCS#11/HSM支持

通过PKCS#11接口使用硬件安全模块保护私钥，需指定PKCS#11模块路径和槽信息：

bash
ghostunnel server \
  --listen :8443 \
  --target :8080 \
  --pkcs11-module /usr/lib/pkcs11.so \
  --pkcs11-token-label "MyToken" \
  --pkcs11-pin "1234" \
  --cacert cacert.pem \
  --allow-cn client

SPIFFE Workload API集成

支持从SPIFFE Workload API获取动态证书和CA：

bash
ghostunnel server \
  --listen :8443 \
  --target :8080 \
  --spiffe-svid-path /run/spire/sockets/agent.sock \
  --spiffe-allow-uri spiffe://example.org/service \
  --cacert /run/spire/bundle/bundle.pem