Skip to content

README_EN.md

Latest commit

 

History

History
255 lines (183 loc) · 9.04 KB

README_EN.md

File metadata and controls

255 lines (183 loc) · 9.04 KB
Raw

SSL Certificate Auto-Deploy CLI

中文说明

An automated SSL certificate deployment tool for downloading certificates from anssl.cn and deploying them to your servers.

Features

  • 🚀 Automatically deploys certificates to Nginx, Apache, RustFS, 1Panel, and SafeLine WAF, then reloads local services
  • ✅ Built-in HTTP-01 validation service to automatically respond to ACME challenges
  • ☁️ Supports automatic deployment to Alibaba Cloud, Tencent Cloud, Qiniu Cloud, Huawei Cloud, Volcengine, JD Cloud, Baidu Cloud, DogeCloud, and LeCDN
  • 🔧 Daemon mode for long-running background execution
  • 🖥️ Multi-platform support: macOS, Linux, Windows (amd64/arm64)

Quick Start

1. Install

For Linux/macOS, use the install script. It installs the latest version from GitHub Releases by default:

curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/https-cert/deploy/main/scripts/install.sh | sh

To pin a version or customize paths:

curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/https-cert/deploy/main/scripts/install.sh | VERSION=v0.6.0 APP_DIR=/opt/anssl sh

By default, anssl is installed into /opt/anssl and linked as /usr/local/bin/anssl. To uninstall:

# Remove the binary and keep config
curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/https-cert/deploy/main/scripts/install.sh | sh -s -- --uninstall

# Remove the binary and config
curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/https-cert/deploy/main/scripts/install.sh | sh -s -- --uninstall --purge

2. Configure Nginx

Add an HTTP-01 reverse proxy rule (for certificate issuance):

# Add this inside the server block
location ~ ^/.well-known/acme-challenge/(.+)$ {
    proxy_pass http://localhost:19000/acme-challenge/$1;
    proxy_set_header Host $host;
}

Reload Nginx:

sudo nginx -t && sudo nginx -s reload

3. Run

# Start daemon
sudo anssl daemon -c /opt/anssl/config.yaml

# Check status
anssl status

# View logs
anssl log -f

HTTP-01 Validation Flow

  1. Request a free certificate on the website
  2. Backend pushes ACME challenge tokens to the CLI
  3. CLI caches and serves Let's Encrypt validation requests automatically
  4. Validation succeeds and certificate is issued
  5. Certificate is downloaded and deployed to configured services (Nginx/Apache/RustFS/1Panel/SafeLine WAF/FeiNiu OS)
  6. Nginx and Apache are reloaded automatically

Fully automated end-to-end, with no manual intervention.

Cloud Provider Capabilities

For resource-based deployments, the deploy client discovers resources in real time and reads the certificate state back after every update. A product is exposed in the console only after resource discovery, certificate update, and read-back verification are all implemented.

Cloud provider Provider name Supported capabilities
Alibaba Cloud aliyun Certificate upload, CDN, DCDN, ESA, OSS custom domains, CLB, ALB, NLB
Tencent Cloud cloudTencent Certificate upload, CDN, EdgeOne, COS custom domains, CLB
Qiniu Cloud qiniu Certificate upload, CDN, DCDN
Huawei Cloud huawei Certificate upload, CDN, DCDN, OBS custom domains, ELB
Volcengine volcengine Certificate upload, CDN, DCDN, TOS custom domains, CLB, ALB, NLB
JD Cloud jdcloud Certificate upload, CDN
Baidu Cloud baidu Certificate upload, CDN
DogeCloud dogecloud Certificate upload, CDN
LeCDN lecdn CDN

JD Cloud, Baidu Cloud, and DogeCloud do not currently expose DCDN. LeCDN exposes CDN only. Additional products will be enabled after the complete lifecycle is available.

Common Commands

# Daemon management
anssl daemon -c /opt/anssl/config.yaml  # Start daemon
anssl status                            # Check status
anssl stop                              # Stop
anssl restart -c /opt/anssl/config.yaml # Restart

# Logs
anssl log                               # View logs
anssl log -f                            # Follow logs

# Update
anssl check-update                      # Check updates
anssl update                            # Run update

Troubleshooting

HTTP-01 validation failed

# 1. Check Nginx config
sudo nginx -t
cat /etc/nginx/sites-enabled/default | grep acme-challenge

# 2. Check port usage
lsof -i :19000

# 3. Test validation service
curl http://localhost:19000/acme-challenge/test-token

# 4. Check logs
anssl log -f

Permission errors

# Option 1: Use sudo
sudo anssl daemon -c /opt/anssl/config.yaml

# Option 2: Use user-owned directories
# Update /opt/anssl/config.yaml: ssl.path: "$HOME/nginx/ssl"
anssl daemon -c /opt/anssl/config.yaml

Auto-start on boot (systemd)

sudo tee /etc/systemd/system/anssl.service > /dev/null <<EOF
[Unit]
Description=Certificate Deploy Service
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/anssl start -c /opt/anssl/config.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable anssl
sudo systemctl start anssl

RustFS and FeiNiu SSH deployment

RustFS uses ssl.rustFS.path as its certificate directory. With no SSH host configured, deployment runs on the deploy client's local machine. After the SSH host, port, username, and authentication fields are set, deployment runs on the remote RustFS host. FeiNiu OS continues to use the built-in deployment method on the client's device when ssl.feiNiu is absent, and switches to remote SSH deployment when it is configured.

SSH supports password and private-key authentication; no separate SCP setting is required. privateKeyPath must be an absolute path to a key on the deploy client's local filesystem. The private key contents are never written to config.yaml or sent to the backend. In private-key mode, password may be left empty or used as the sudo password for a non-root user.

ssl:
  rustFS:
    path: "/opt/rustfs/tls"
    host: "192.168.1.30"
    port: 22
    username: "admin"
    privateKeyPath: "/home/anssl/.ssh/id_ed25519"
    privateKeyPassphrase: ""
    password: "" # Optional sudo password

  feiNiu:
    host: "192.168.1.20"
    port: 22
    username: "admin"
    password: "your-ssh-password"

SafeLine WAF certificate deployment

Generate an API Token in SafeLine's General Settings, then configure the management URL and token on the deploy client. Connection testing only calls the read-only certificate list endpoint. During deployment, existing certificates are matched by the complete SAN domain set: every exact match is updated, while a new certificate is created when no exact match exists. Partial domain overlap is never used for replacement.

ssl:
  safeLine:
    url: "https://waf.example.com:9443"
    apiToken: "your-safeline-api-token"
    insecureSkipVerify: false

Keep insecureSkipVerify set to false by default. Enable it only when the SafeLine management endpoint uses a self-signed HTTPS certificate that you explicitly trust. The API Token remains on the deploy client and is never sent to the ANSSL backend.

FAQ

Q: Where can I get server.accessKey?
A: Log in to anssl.cn → Console → Developer → API Credentials.

Q: Which web servers and panels are supported?
A: Nginx, Apache, RustFS, 1Panel, SafeLine WAF, and FeiNiu OS. RustFS supports either a local directory or remote SSH deployment. FeiNiu uses the built-in method on the client's device by default and can also deploy remotely through ssl.feiNiu. Both SSH targets support password and private-key authentication.

Q: Can I deploy to multiple targets at the same time?
A: Yes. Configure the required targets in config.yaml (nginxPath, apachePath, rustFS, onePanel, safeLine, and optional remote feiNiu) and select the corresponding targets in the anssl.cn console.

Q: Where can I get the 1Panel API key?
A: 1Panel → Settings → Security → API Interface → Generate API Key.

Q: Where can I get the SafeLine API Token? A: SafeLine management console → General Settings → API Token. Store it only in ssl.safeLine.apiToken on the deploy client.

Q: Can certificates be deployed to both local services and cloud providers?
A: Yes. In the anssl.cn console, you can configure deployment to local CLI targets (Nginx/Apache/RustFS/1Panel/SafeLine WAF/FeiNiu OS) and/or any supported cloud provider. Each certificate can have multiple deployment targets.

Q: Is manual action required for HTTP-01 validation?
A: No. Once Nginx reverse proxy is configured, validation is fully automated.

Development

# Install dependencies
go mod download

# Run tests
go test -v ./...

# Build
go build -o anssl main.go

Links

License

MIT License