Packager guide

This page is for distro / package maintainers who ship acme.sh as a system package (deb, rpm, port, etc.), typically with the files under a package-managed directory like /usr/share/acme.sh.

The problem

By default acme.sh manages itself:

• acme.sh --install copies the script and the hook folders (dnsapi, deploy, notify) into $LE_WORKING_DIR (default ~/.acme.sh), so users end up running a frozen copy that your package upgrades can never update.
• acme.sh --upgrade, acme.sh --install-online and the cron AUTO_UPGRADE=1 path download the latest master from GitHub and install it over $LE_WORKING_DIR. If your package points LE_WORKING_DIR at the packaged files, this overwrites package-managed files.
• acme.sh --uninstall removes $LE_WORKING_DIR/acme.sh, which again may be a package-managed file.

ACME_PACKAGED

Since v3.1.5, set the ACME_PACKAGED environment variable to any non-empty value to tell acme.sh that it is managed by a system package manager:

• --install does not copy the script, the completion file or the hook folders into $LE_WORKING_DIR. It still creates the working/config dirs, writes account.conf, installs the cron job and the shell alias -- both pointing to the packaged script itself.
• --upgrade, --install-online and the cron AUTO_UPGRADE path refuse with an error telling the user to upgrade via the package manager.
• --uninstall removes the cron job and the alias, but does not delete the script files.

The easiest way to set it is a wrapper installed as /usr/bin/acme.sh:

#!/bin/sh
export ACME_PACKAGED=1
exec /usr/share/acme.sh/acme.sh "$@"

Notes

• Do not point LE_WORKING_DIR at the packaged directory. Leave it at the default (~/.acme.sh per user, or let users pick --home): it holds the per-user state (account.conf, account keys, certs). The hooks are looked up next to the running script automatically, no copy in $LE_WORKING_DIR is needed.
• Users can still use --config-home to separate config/certs from $LE_WORKING_DIR as usual.
• There is intentionally no path auto-detection ("am I under /usr?"): a git clone under /usr/local or a custom --home under /usr are legitimate self-managed installs. ACME_PACKAGED is an explicit opt-in by the packager.

See https://github.com/acmesh-official/acme.sh/issues/7135 for background.