paulgit/3x-ui-certs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Automatically provision and install a Tailscale TLS certificate for the 3x-ui web panel.
5 commits 1 branch 0 tags 43 KiB
  • Shell 100%
Find a file
Exact
Paul Git 20d991a146
 Add project guidelines and rename script to 3x-ui-certs 
- Rename `x-ui-certs.sh` to `3x-ui-certs` (removing .sh extension)
- Add `AGENTS.md` with comprehensive bash/shell development guidelines
- Create symlink `CLAUDE.md` → `AGENTS.md` for AI agent reference
- Add `.gitignore` with editor, OS, and AI agent state exclusions
- Update all references in documentation and script header
- Bump version to 2.0.0
2026-05-03 18:45:46 +08:00
.gitignore Add project guidelines and rename script to 3x-ui-certs 2026-05-03 18:45:46 +08:00
3x-ui-certs Add project guidelines and rename script to 3x-ui-certs 2026-05-03 18:45:46 +08:00
AGENTS.md Add project guidelines and rename script to 3x-ui-certs 2026-05-03 18:45:46 +08:00
CLAUDE.md Add project guidelines and rename script to 3x-ui-certs 2026-05-03 18:45:46 +08:00
LICENSE Add x-ui-certs script, README, and license. Initial release 2026-04-03 00:34:44 +08:00
README.md Add project guidelines and rename script to 3x-ui-certs 2026-05-03 18:45:46 +08:00

README.md

3x-ui-certs

Automatically provision and install a Tailscale TLS certificate for the 3x-ui web panel.

Background

The x-ui web panel is a popular management interface for Xray/V2Ray proxy servers. When deployed on a server that uses Tailscale for networking, TLS certificates can be provisioned automatically through Tailscale's built-in ACME integration. This script automates that certificate provisioning and installation workflow.

What the script does

3x-ui-certs automatically provisions and installs a Tailscale TLS certificate for the x-ui web panel. It:

  1. Determines the machine's Tailscale FQDN (e.g., myhost.tail12345.ts.net).
  2. Checks whether the current certificate is missing or nearing expiry.
  3. If renewal is needed, requests a new TLS certificate from Tailscale.
  4. Installs the certificate and private key to /etc/ssl/tailscale/<hostname>/.
  5. If x-ui is installed, restarts the x-ui service to apply the new certificate. If x-ui is not found, this step is skipped and a notice is printed.

If the certificate is still valid beyond the renewal threshold, the script exits silently without making changes.

Usage

sudo ./3x-ui-certs [OPTIONS]

Options

Option Description
-h, --help Show help message and exit.
--version Show version information and exit.
-t DAYS, --threshold DAYS Days before certificate expiry at which to trigger renewal. Default: 30.
--cronmode Suppress all output unless an error occurs. On error, messages are sent to stdout (suitable for cron email capture).

Exit codes

  • 0 — Success (certificate renewed, or still valid).
  • 1 — An error occurred.

Examples

Basic usage:

sudo ./3x-ui-certs

Renew only if certificate expires within 14 days:

sudo ./3x-ui-certs --threshold 14

Silent cron operation:

sudo ./3x-ui-certs --cronmode

Crontab entry — daily at 3 AM, renew if within 7 days of expiry:

0 3 * * * /usr/local/bin/3x-ui-certs --cronmode --threshold 7

Prerequisites

  • Root privileges (run with sudo or as root).
  • tailscale — installed and connected to a tailnet.
  • jq — command-line JSON processor.
  • openssl — for certificate expiry checking.
  • x-ui (optional) — the web panel being managed. If installed, the service is restarted after a certificate renewal. If not installed, certificates are still provisioned and installed; only the service restart is skipped.

Installation

One-line install to /usr/local/bin/:

sudo curl -fsSL https://code.paulg.it/paulgit/3x-ui-certs/raw/branch/main/3x-ui-certs -o /usr/local/bin/3x-ui-certs && sudo chmod +x /usr/local/bin/3x-ui-certs

Or manually:

  1. Copy 3x-ui-certs to a suitable location (e.g., /usr/local/bin/).
  2. Make it executable: chmod +x 3x-ui-certs.
  3. Optionally, set up a cron job or systemd timer for automated renewal.

License

This project is licensed under the WTFPL — Do What The Fuck You Want To Public License.

Authors

Written by Paul Git and Claude AI.