{"id":15978960,"url":"https://github.com/phrozenbyte/acme","last_synced_at":"2025-03-16T14:42:50.097Z","repository":{"id":152899958,"uuid":"412828201","full_name":"PhrozenByte/acme","owner":"PhrozenByte","description":"Issue and renew Let's Encrypt TLS certificates using acme-tiny.","archived":false,"fork":false,"pushed_at":"2024-08-05T22:37:11.000Z","size":75,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-23T02:11:53.272Z","etag":null,"topics":["acme","lets-encrypt","letsencrypt","ssl-certificates"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PhrozenByte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-02T15:01:03.000Z","updated_at":"2024-08-05T22:37:14.000Z","dependencies_parsed_at":"2024-08-06T01:01:19.923Z","dependency_job_id":null,"html_url":"https://github.com/PhrozenByte/acme","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhrozenByte%2Facme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhrozenByte%2Facme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhrozenByte%2Facme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhrozenByte%2Facme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhrozenByte","download_url":"https://codeload.github.com/PhrozenByte/acme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243885888,"owners_count":20363644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acme","lets-encrypt","letsencrypt","ssl-certificates"],"created_at":"2024-10-07T23:40:28.704Z","updated_at":"2025-03-16T14:42:50.067Z","avatar_url":"https://github.com/PhrozenByte.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"ACME Issue \u0026 Renew\n==================\n\n[`acme-issue`](./src/acme-issue), [`acme-renew`](./src/acme-renew) and [`acme-check`](./src/acme-check) (formerly known as `letsencrypt-issue` and `letsencrypt-renew`) are a collection of small management scripts for [acme-tiny](https://github.com/diafygi/acme-tiny) to issue TLS certificates with [Let's Encrypt](https://letsencrypt.org/).\n\nThe scripts use a very simple directory structure below `/var/local/acme` to manage your certs and to allow a fail-safe auto renewal of certs. All certs and associated files life below `/var/local/acme/archive` inside domain-specific sub-folders. When issuing a new or renewing an existing cert, `acme-issue` will create a directory with the current date and time (e.g. `/var/local/acme/archive/example.com/2021-10-01T04:49:34Z`) and put the necessary files there, namely\n\n* `cert.pem`: The cert signed by the Certificate Authority (CA; Let's Encrypt by default).\n* `chain.pem`: Any intermediate certs used by the CA to sign the cert, empty otherwise.\n* `fullchain.pem`: The composition of `cert.pem` and `chain.pem`.\n* `key.pem`: The private key used. The script will create a new private key for every signing request.\n* `csr.pem`: The CSR (Certificate Signing Request) used to issue the cert.\n\nIn the course of signing a cert, acme-tiny will communicate with your CA using the [ACME protocol](https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment). It uses `HTTP-01` challenges to verify that you're actually authorized to issue certs for the requested domains. To do so it creates challenge files that your webserver must publish below `http://example.com/.well-known/acme-challenge/`. These files are created in `/var/local/acme/challenges`. Make sure that your webserver publishes all files within this directory at the mentioned URL.\n\n`acme-issue` will always check whether it actually succeeded and the files contain valid certs. If `acme-issue` fails, it simply leaves the files there and bails. If it succeeds, it will copy `cert.pem`, `chain.pem`, `fullchain.pem` and `key.pem` to a matching sub-folder below `/var/local/acme/live` for your services to use. Point your software to the files in this directory (e.g. `/var/local/acme/live/example.com/cert.pem`) and you're ready to go!\n\nWhen renewing certs using `acme-renew`, remember to also restart your services, so that they actually pick up the new cert. It's usually best to let services deal with restarting themselves, e.g. using an inotify-based certs watchdog. It's recommended to renew all certificates once a month (e.g. using a cronjob).\n\nAdditionally you can use `acme-check` to check validity of managed certificates (e.g. whether a certificate was revoked). If a certificate is deemed invalid by `acme-check`, you should renew it (`acme-check` allows you to do that automatically). You should check certificate validity regularly (e.g. daily using a cronjob).\n\nBefore signing certs you must create a ACME account private key. The scripts' config is stored below `/etc/acme`. Simply create a `account.key` there by executing `openssl genrsa 4096 \u003e /etc/acme/account.key`. If you're there you can also take a look at the scripts' [`/etc/acme/config.env`](./conf/config.env). It is highly recommended to leave contact information with your CA (variable `ACME_ACCOUNT_CONTACT`) there. This is even mandatory for some CAs. acme-tiny can sign certs with any ACME-capable CA, it just defaults to Let's Encrypt. If you want to switch to another CA, simply change the `ACME_DIRECTORY_URL` variable in `config.env`. You can also change the associated group of private key files there (variable `TLS_KEY_GROUP`).\n\nMade with :heart: by [Daniel Rudolf](https://www.daniel-rudolf.de). ACME Issue \u0026 Renew is free and open source software, released under the terms of the [MIT license](./LICENSE).\n\nUsage\n-----\n\nUse `acme-issue` to issue a new cert for a domain and optional domain aliases, or renew a single existing cert:\n\n```\nUsage:\n  acme-issue [--force] DOMAIN_NAME [DOMAIN_ALIAS...]\n  acme-issue --renew DOMAIN_NAME\n\nOptions:\n  -r, --renew      renew an existing certificate\n  -f, --force      issue a new certificate even though there is another\n                   certificate for this DOMAIN_NAME\n      --no-verify  don't verify the certificate after issuance\n\nHelp options:\n  -h, --help     display this help and exit\n      --version  output version information and exit\n\nEnvironment:\n  ACME_ACCOUNT_KEY_FILE  path to your ACME account private key\n  ACME_ACCOUNT_CONTACT   contact details for your account\n  ACME_DIRECTORY_URL     ACME directory URL of the CA to use\n  TLS_KEY_GROUP          associated group for TLS key files\n```\n\nUse `acme-renew` to renew a single, multiple, or all known certs:\n\n```\nUsage:\n  acme-renew [--verbose|--quiet] [--retry...] [--clean] --all\n  acme-renew [--verbose|--quiet] [--retry...] DOMAIN_NAME...\n\nOptions:\n  -a, --all        renew all certificates\n  -c, --clean      remove dangling challenges on success; requires --all\n  -r, --retry      retry if renewal fails; can be passed multiple times\n      --no-verify  don't verify the certificate after renewal\n  -v, --verbose    explain what is being done\n  -q, --quiet      suppress status information\n\nHelp options:\n  -h, --help     display this help and exit\n      --version  output version information and exit\n\nEnvironment:\n  ACME_ACCOUNT_KEY_FILE  path to your ACME account private key\n  ACME_ACCOUNT_CONTACT   contact details for your account\n  ACME_DIRECTORY_URL     ACME directory URL of the CA to use\n  TLS_KEY_GROUP          associated group for TLS key files\n```\n\nUse `acme-check` to check validity of a single, multiple, or all known certs:\n\n```\nUsage:\n  acme-check [--verbose|--quiet] --all\n  acme-check [--verbose|--quiet] DOMAIN_NAME...\n\nOptions:\n  -a, --all          check all certificates\n  -r, --renew        renew certificates that are deemed invalid\n      --retry-renew  retry if renewal fails; can be passed multiple times\n  -v, --verbose      explain what is being done\n  -q, --quiet        suppress status information\n\nHelp options:\n  -h, --help     display this help and exit\n      --version  output version information and exit\n\nEnvironment:\n  FP_REVOCATION_LIST     path to a list of revoked certificate fingerprints\n  ACME_ACCOUNT_KEY_FILE  path to your ACME account private key\n  ACME_ACCOUNT_CONTACT   contact details for your account\n  ACME_DIRECTORY_URL     ACME directory URL of the CA to use\n  TLS_KEY_GROUP          associated group for TLS key files\n```\n\nSetup\n-----\n\n`acme-issue`, `acme-renew` and `acme-check` all require [OpenSSL](https://www.openssl.org/) and [acme-tiny](https://github.com/diafygi/acme-tiny).\n\nThe scripts were written to work with [GNU Bash](https://www.gnu.org/software/bash/) (any more or less recent version), but *SHOULD* work with other advanced shells, too. If you want to make `acme-issue`, `acme-renew` and `acme-check` compatible with your favorite shell, please go ahead and let me know, I very much appreciate it!\n\nBelow you'll find all steps required to set up `acme-issue`, `acme-renew` and `acme-check`. However, you **MUST** read, understand and edit these commands to fit your setup. **DO NOT EXECUTE THEM AS-IS!**\n\n```sh\n# download and install latest version of acme-tiny\n# all credit goes to these awesome people!\nwget -O /usr/local/bin/acme-tiny https://raw.githubusercontent.com/diafygi/acme-tiny/master/acme_tiny.py\nchmod +x /usr/local/bin/acme-tiny\n\n# add acme user\nadduser --system --home /var/local/acme --no-create-home --disabled-login --disabled-password --group acme\nusermod -aG www-data acme\n\n# create acme base and config dir\nmkdir /var/local/acme/{,live,archive} /etc/acme\nchown acme:acme /var/local/acme/{live,archive}\n\n# create acme-challenge directory\nmkdir -p /var/www/html/.well-known/acme-challenge\nchown acme:www-data /var/www/html/.well-known/acme-challenge\nln -s /var/www/html/.well-known/acme-challenge/ /var/local/acme/challenges\n\n# configure Apache to serve acme-challenge directory\ncat \u003e /etc/apache2/conf-available/acme-challenge.conf \u003c\u003cEOF\nAlias /.well-known/acme-challenge/ /var/www/html/.well-known/acme-challenge/\n\u003cDirectory \"/var/www/html/.well-known/acme-challenge/\"\u003e\n    Options None\n    AllowOverride None\n\n    ForceType text/plain\n    RedirectMatch 404 \"^(?!/\\.well-known/acme-challenge/[\\w-]{43}$)\"\n\u003c/Directory\u003e\nEOF\na2enconf acme-challenge\nsystemctl reload apache2.service\n\n# create config file and set 'ACME_ACCOUNT_CONTACT'\ncp ./conf/config.env /etc/acme/config.env\nchown acme:acme /etc/acme/config.env\nsed -i '/^#ACME_ACCOUNT_CONTACT=\"\"$/a ACME_ACCOUNT_CONTACT=\"certs@example.com\"' /etc/acme/config.env\n\n# create Let's Encrypt account key\n( umask 027 \u0026\u0026 openssl genrsa 4096 \u003e /etc/acme/account.key )\nchmod 640 /etc/acme/account.key\nchown acme:acme /etc/acme/account.key\n\n# install scripts\ncp ./src/acme-issue /usr/local/bin/acme-issue\ncp ./src/acme-renew /usr/local/bin/acme-renew\ncp ./src/acme-check /usr/local/bin/acme-check\nchmod +x /usr/local/bin/acme-{issue,renew,check}\n\n# OPTIONAL: install daily `acme-check` and monthly `acme-renew` cronjobs\n# check out the instructions in ./examples/cron/\n\n# OPTIONAL: install and setup certs watchdog script\n# check out the instructions and example script in ./examples/certs-watchdog/\n```\n\nUpgrade\n-------\n\nIf you're currently running `letsencrypt-issue` v1.6 or older, you might ask yourself how to upgrade to `acme-issue` v1.8 or later. Simply check the steps below, but as with the install instructions, you **MUST** read, understand and edit these commands to fit your setup. To upgrade later versions of `acme-issue` just replace the `acme-issue`, `acme-renew` and `acme-check` script files with their respective new version.\n\n```sh\n# create new base and config dir\nmkdir /var/local/acme /etc/acme\n\n# create config file\ncp ./conf/config.env /etc/acme/config.env\nchown acme:acme /etc/acme/config.env\n\n# RECOMMENDED: set 'ACME_ACCOUNT_CONTACT' config variable\nsed -i '/^#ACME_ACCOUNT_CONTACT=\"\"$/a ACME_ACCOUNT_CONTACT=\"certs@example.com\"' /etc/acme/config.env\n\n# OPTIONAL: set 'TLS_KEY_GROUP' config variable\nsed -i '/^#TLS_KEY_GROUP=\"\"$/a TLS_KEY_GROUP=\"ssl-cert\"' /etc/acme/config.env\n\n# move account.key\nmv /etc/ssl/acme/account.key /etc/acme/account.key\n\n# move live certs one after another (don't just copy/move the existing dir)\nmkdir /var/local/acme/live\nchown acme:acme /var/local/acme/live\n\nfor DOMAIN_PATH in /etc/ssl/acme/live/*; do\n    DOMAIN=\"$(basename \"$DOMAIN_PATH\")\"\n    mkdir /var/local/acme/live/\"$DOMAIN\"\n    chown acme:acme /var/local/acme/live/\"$DOMAIN\"\n\n    cp -p -t /var/local/acme/live/\"$DOMAIN\"/ \\\n        \"$DOMAIN_PATH\"/{key,cert,chain,fullchain}.pem\ndone\n\n# move cert archive and challenges\nmv -t /var/local/acme/ /etc/ssl/acme/{archive,challenges}\n\n# install scripts\ncp ./src/acme-issue /usr/local/bin/acme-issue\ncp ./src/acme-renew /usr/local/bin/acme-renew\ncp ./src/acme-check /usr/local/bin/acme-check\nchmod +x /usr/local/bin/acme-{issue,renew,check}\n\n# create symlinks for old scripts\nrm -f /usr/local/bin/letsencrypt-{issue,renew}\nln -s /usr/local/bin/acme-issue /usr/local/bin/letsencrypt-issue\nln -s /usr/local/bin/acme-renew /usr/local/bin/letsencrypt-renew\n\n# delete old dir\nrm -rf /etc/ssl/acme\n\n# remove old renewable cronjob\nrm /etc/cron.monthly/letsencrypt\n\n# OPTIONAL: install daily `acme-check` and monthly `acme-renew` cronjobs\n# check out the instructions in ./examples/cron/\n\n# OPTIONAL: install and setup certs watchdog script\n# check out the instructions and example script in ./examples/certs-watchdog/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphrozenbyte%2Facme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphrozenbyte%2Facme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphrozenbyte%2Facme/lists"}