From 89f8c948d7b39314d7fc997643874adc6be92462 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Thu, 22 Aug 2019 00:30:11 +0200 Subject: Use /run for the listening socket of the webserver component. --- config/lacme.conf | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'config') diff --git a/config/lacme.conf b/config/lacme.conf index 39c8654..7c3833d 100644 --- a/config/lacme.conf +++ b/config/lacme.conf @@ -62,7 +62,7 @@ # Comma- or space-separated list of addresses to listen on, for instance # "0.0.0.0:80 [::]:80". # -#listen = /var/run/lacme-www.socket +#listen = /run/lacme-www.socket # Non-existent directory under which an external HTTP daemon is # configured to serve GET requests for challenge files under -- cgit v1.2.3 From f6913c09b9987ae8a6f65f5acfa7673278c701be Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 3 Aug 2020 22:15:14 +0200 Subject: Install lacme manpage to section 8. As it's a system command, see hier(7) for details. --- .gitignore | 3 +- Changelog | 3 +- Makefile | 6 +- config/lacme.conf | 8 +- lacme-accountd.1.md | 16 +- lacme.1.md | 413 ---------------------------------------------------- lacme.8.md | 413 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 433 insertions(+), 429 deletions(-) delete mode 100644 lacme.1.md create mode 100644 lacme.8.md (limited to 'config') diff --git a/.gitignore b/.gitignore index 813d896..21f822a 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ .*.sw[po] # generated man-pages -*.1 +/lacme.8 +/lacme-accountd.1 diff --git a/Changelog b/Changelog index 6aa31e8..a220c83 100644 --- a/Changelog +++ b/Changelog @@ -5,6 +5,7 @@ lacme (0.7) UNRELEASED; /var/run.) * Makefile: major refactoring, add install and uninstall targets, honor BUILD_DOCDIR and DESTDIR variables. + * Install lacme manual to section 8. -- Guilhem Moulin Thu, 22 Aug 2019 00:31:35 +0200 @@ -15,7 +16,7 @@ lacme (0.6) upstream; deactivation, see RFC 8555 sec. 7.3.6. - lacme, client: new dependency Date::Parse, don't parse RFC 3339 datetime strings from X.509 certs manually. - - lacme: assume that the iptables(1) binaries are under /usr/sbin not + - lacme: assume that the iptables(8) binaries are under /usr/sbin not /sbin. As of Buster this is the case, and the maintainer plans to drop compatibility symlinks once Bullseye is released. - Link to RFC 8555 instead of the diff --git a/Makefile b/Makefile index 6bfa739..06841ee 100644 --- a/Makefile +++ b/Makefile @@ -20,19 +20,21 @@ datarootdir ?= $(prefix)/share sysconfdir ?= $(prefix)/etc mandir ?= $(datarootdir)/man man1dir ?= $(mandir)/man1 +man8dir ?= $(mandir)/man8 install: all install -m0644 -vDt $(sysconfdir)/lacme config/*.conf snippets/*.conf install -vd $(sysconfdir)/lacme/lacme-certs.conf.d install -m0644 -vDt $(datarootdir)/lacme certs/lets-encrypt-x[1-4]-cross-signed.pem install -m0755 -vDt $(libexecdir)/lacme ./client ./webserver - install -m0644 -vDt $(man1dir) $(BUILD_DOCDIR)/lacme-accountd.1 $(BUILD_DOCDIR)/lacme.1 + install -m0644 -vDt $(man1dir) $(BUILD_DOCDIR)/lacme-accountd.1 + install -m0644 -vDt $(man8dir) $(BUILD_DOCDIR)/lacme.8 install -m0644 -vDt $(bindir) ./lacme-accountd install -m0644 -vDt $(sbindir) ./lacme uninstall: rm -vf -- $(bindir)/lacme-accountd $(sbindir)/lacme - rm -vf -- $(man1dir)/lacme-accountd.1 $(man1dir)/lacme.1 + rm -vf -- $(man1dir)/lacme-accountd.1 $(man8dir)/lacme.8 rm -rvf -- $(sysconfdir)/lacme $(datarootdir)/lacme $(libexecdir)/lacme clean: diff --git a/config/lacme.conf b/config/lacme.conf index 7c3833d..acafe81 100644 --- a/config/lacme.conf +++ b/config/lacme.conf @@ -8,11 +8,11 @@ # The value of "socket" specifies the path to the lacme-accountd(1) # UNIX-domain socket to connect to for signature requests from the ACME -# client. lacme(1) aborts if the socket is readable or writable by +# client. lacme(8) aborts if the socket is readable or writable by # other users, or if its parent directory is writable by other users. # Default: "$XDG_RUNTIME_DIR/S.lacme" if the XDG_RUNTIME_DIR environment # variable is set. -# This option is ignored when lacme-accountd(1) is spawned by lacme(1), +# This option is ignored when lacme-accountd(1) is spawned by lacme(8), # since the two processes communicate through a socket pair. See the # "accountd" section below for details. # @@ -88,14 +88,14 @@ # Whether to automatically install iptables(8) rules to open the # ADDRESS[:PORT] specified with listen. Theses rules are automatically -# removed once lacme(1) exits. +# removed once lacme(8) exits. # #iptables = No [accountd] # lacme-accound(1) section. Comment out this section (including its -# header) to make lacme(1) connect to an existing UNIX-domain socket +# header) to make lacme(8) connect to an existing UNIX-domain socket # bound by a running acme-accountd(1) process. # username to drop privileges to (setting both effective and real uid). diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 403c68c..215adf6 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -16,9 +16,9 @@ Synopsis Description =========== -`lacme-accountd` is the account key manager component of [`lacme`(1)], a +`lacme-accountd` is the account key manager component of [`lacme`(8)], a small [ACME] client written with process isolation and minimal -privileges in mind. No other [`lacme`(1)] component needs access to the +privileges in mind. No other [`lacme`(8)] component needs access to the account key; in fact the account key could as well be stored on another host or a smartcard. @@ -26,12 +26,12 @@ host or a smartcard. `--socket=`), which [ACME] clients can connect to in order to request data signatures. As a consequence, `lacme-accountd` needs to be up and running before -using [`lacme`(1)] to issue [ACME] commands. Also, the process does not +using [`lacme`(8)] to issue [ACME] commands. Also, the process does not automatically terminate after the last signature request: instead, one sends an `INT` or `TERM` [`signal`(7)] to bring the server down. Furthermore, one can use the UNIX-domain socket forwarding facility of -[OpenSSH] 6.7 and later to run `lacme-accountd` and [`lacme`(1)] on +[OpenSSH] 6.7 and later to run `lacme-accountd` and [`lacme`(8)] on different hosts. For instance one could store the account key on a machine that is not exposed to the internet. See the **[examples](#examples)** section below. @@ -119,13 +119,13 @@ Run `lacme-accountd` in a first terminal: ~$ lacme-accountd --privkey=file:/path/to/account.key --socket=$XDG_RUNTIME_DIR/S.lacme -Then, while `lacme-accountd` is running, execute locally [`lacme`(1)] in +Then, while `lacme-accountd` is running, execute locally [`lacme`(8)] in another terminal: ~$ sudo lacme --socket=$XDG_RUNTIME_DIR/S.lacme newOrder Alternatively, use [OpenSSH] 6.7 or later to forward the socket and -execute [`lacme`(1)] remotely: +execute [`lacme`(8)] remotely: ~$ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:$XDG_RUNTIME_DIR/S.lacme user@example.org \ sudo lacme --socket=/path/to/remote.sock newOrder @@ -133,10 +133,10 @@ execute [`lacme`(1)] remotely: See also ======== -[`lacme`(1)], [`ssh`(1)] +[`lacme`(8)], [`ssh`(1)] [ACME]: https://tools.ietf.org/html/rfc8555 -[`lacme`(1)]: lacme.1.html +[`lacme`(8)]: lacme.8.html [`signal`(7)]: http://linux.die.net/man/7/signal [`gpg`(1)]: https://www.gnupg.org/documentation/manpage.en.html [OpenSSH]: http://www.openssh.com/ diff --git a/lacme.1.md b/lacme.1.md deleted file mode 100644 index 5d86f40..0000000 --- a/lacme.1.md +++ /dev/null @@ -1,413 +0,0 @@ -% lacme(1) -% [Guilhem Moulin](mailto:guilhem@fripost.org) -% December 2015 - -Name -==== - -lacme - [ACME] client written with process isolation and minimal -privileges in mind - -Synopsis -======== - -`lacme` [`--config=FILENAME`] [`--socket=PATH`] [*OPTION* …] *COMMAND* [*ARGUMENT* …] - -Description -=========== - -`lacme` is a small [ACME] client written with process isolation and -minimal privileges in mind. It is divided into four components, each -with its own executable: - - 1. A [`lacme-accountd`(1)] process to manage the account key and issue - SHA-256 signatures needed for each [ACME] command. (This process - binds to a UNIX-domain socket to reply to signature requests from - the [ACME] client.) - One can use the UNIX-domain socket forwarding facility of OpenSSH - 6.7 and later to run [`lacme-accountd`(1)] and `lacme` on different - hosts. Alternatively, the [`lacme-accountd`(1)] process can be - spawned by the “master” `lacme` process below; in that case, the - two processes communicate through a socket pair. - - 2. A “master” `lacme` process, which runs as root and is the only - component with access to the private key material of the server - keys. It is used to fork the [ACME] client (and optionally the - [ACME] webserver) after dropping root privileges. - For certificate issuances (`newOrder` command), it also generates - Certificate Signing Requests, then verifies the validity of the - issued certificate, and optionally reloads or restarts services when - the *notify* option is set. - - 3. An actual [ACME] client (specified with the *command* option of the - [`[client]` section](#client-section) of the configuration file), - which builds [ACME] commands and dialogues with the remote [ACME] - server. - Since [ACME] commands need to be signed with the account key, the - “master” `lacme` process passes the [`lacme-accountd`(1)] - UNIX-domain socket to the [ACME] client: data signatures are - requested by writing the data to be signed to the socket. - - 4. For certificate issuances (`newOrder` command), an optional - webserver (specified with the *command* option of the [`[webserver]` - section](#webserver-section) of the configuration file), which is - spawned by the “master” `lacme`. (The only challenge type currently - supported by `lacme` is `http-01`, which requires a webserver to - answer challenges.) That webserver only processes `GET` and `HEAD` - requests under the `/.well-known/acme-challenge/` URI. - Moreover temporary [`iptables`(8)] rules can be automatically - installed to open the HTTP port. - -Commands -======== - -`lacme account` [`--tos-agreed`] [`--register`] [*CONTACT* …] - -: Register (if `--registered` is set) a [`lacme-accountd`(1)]-managed - account key. A list of *CONTACT* information (such as `maito:` - URIs) can be specified in order for the [ACME] server to contact the - client for issues related to this registration (such as - notifications about server-initiated revocations). `--tos-agreed` - indicates agreement with the [ACME] server's Terms of Service (and - might be required for registration). - - If the account key is already registered, update the contact info - with the given list of *CONTACT* information. - - Upon success, `lacme` prints the new or updated Account Object from - the [ACME] server. - -`lacme` [`--config-certs=`*FILE*] [`--min-days=`*INT*] `newOrder` [*SECTION* …] - -: Read the certificate configuration *FILE* (see the **[certificate - configuration file](#certificate-configuration-file)** section below - for the configuration options), and request new Certificate Issuance - for each of its sections (or the given list of *SECTION*s). - Command alias: `new-order`. - -`lacme` `revokeCert` *FILE* [*FILE* …] - -: Request that the given certificate(s) *FILE*(s) be revoked. For - this command, [`lacme-accountd`(1)] can be pointed to either the - account key or the server's private key. - Command alias: `revoke-cert`. - -Generic options -=============== - -`--config=`*filename* - -: Use *filename* as configuration file. See the **[configuration - file](#configuration-file)** section below for the configuration - options. - -`--socket=`*path* - -: Use *path* as the [`lacme-accountd`(1)] UNIX-domain socket to - connect to for signature requests from the [ACME] client. `lacme` - aborts if `path` is readable or writable by other users, or if its - parent directory is writable by other users. - This command-line option overrides the *socket* option of the - [`[client]` section](#client-section) of the configuration file. - Moreover this option is ignored when the configuration file has an - [`[accountd]` section](#accountd-section); in that case `lacme` - spawns [`lacme-accountd`(1)], and the two processes communicate - through a socket pair. - -`-h`, `--help` - -: Display a brief help and exit. - -`-q`, `--quiet` - -: Be quiet. - -`--debug` - -: Turn on debug mode. - -Configuration file -================== - -If `--config=` is not given, `lacme` uses the first existing -configuration file among *./lacme.conf*, -*$XDG_CONFIG_HOME/lacme/lacme.conf* (or *~/.config/lacme/lacme.conf* if -the `XDG_CONFIG_HOME` environment variable is not set), and -*/etc/lacme/lacme.conf*. -Valid options are: - -Default section ---------------- - -*config-certs* - -: For certificate issuances (`newOrder` command), specify the - space-separated list of certificate configuration files or - directories to use (see the **[certificate configuration - file](#certificate-configuration-file)** section below for the - configuration options). - - Paths not starting with `/` are relative to the directory name of - the **[configuration filename](#configuration-file)**. The list of - files and directories is processed in order, with the later items - taking precedence. Files in a directory are processed in - lexicographic order, only considering the ones with suffix `.conf`. - - Default: `lacme-certs.conf lacme-certs.conf.d/`. - -`[client]` section ------------------- - -This section is used for configuring the [ACME] client (which takes care -of [ACME] commands and dialogues with the remote [ACME] server). - -*socket* - -: See `--socket=`. - Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR` - environment variable is set. - -*user* - -: The username to drop privileges to (setting both effective and real - uid). Preserve root privileges if the value is empty (not - recommended). - Default: `nobody`. - -*group* - -: The groupname to drop privileges to (setting both effective and real - gid, and also setting the list of supplementary gids to that single - group). Preserve root privileges if the value is empty (not - recommended). - Default: `nogroup`. - -*command* - -: Path to the [ACME] client executable. - Default: `/usr/lib/lacme/client`. - -*server* - -: Root URI of the [ACME] server. - Default: `https://acme-v02.api.letsencrypt.org/directory`. - -*timeout* - -: Timeout in seconds after which the client stops polling the [ACME] - server and considers the request failed. - Default: `10`. - -*SSL_verify* - -: Whether to verify the server certificate chain. - Default: `Yes`. - -*SSL_version* - -: Specify the version of the SSL protocol used to transmit data. - -*SSL_cipher_list* - -: Specify the cipher list for the connection, see [`ciphers`(1ssl)] - for more information. - -`[webserver]` section ---------------------- - -This section is used to configure how [ACME] challenge responses are -served during certificate issuance. - -*listen* - -: Comma- or space-separated list of addresses to listen on. Valid - addresses are of the form `IPV4:PORT`, `[IPV6]:PORT` (where the - `:PORT` suffix is optional and defaults to the HTTP port 80), or an - absolute path of a UNIX-domain socket (created with mode `0666`). - Default: `/run/lacme-www.socket`. - - **Note**: The default value is only suitable when an external HTTP - daemon is publicly reachable and passes all ACME challenge requests - to the webserver component through the UNIX-domain socket - `/run/lacme-www.socket` (for instance using the provided - `/etc/lacme/apache2.conf` or `/etc/lacme/nginx.conf` configuration - snippets for each virtual host requiring authorization). If there - is no HTTP daemon bound to port 80 one needs to set *listen* to - `[::]` (or `0.0.0.0 [::]` when dual IPv4/IPv6 stack is disabled or - unavailable), and possibly also set *iptables* to `Yes`. - -*challenge-directory* - -: Specify a non-existent directory under which an external HTTP daemon - is configured to serve `GET` requests for challenge files under - `/.well-known/acme-challenge/` (for each virtual host requiring - authorization) as static files. - This option is required when *listen* is empty. - -*user* - -: The username to drop privileges to (setting both effective and real - uid). Preserve root privileges if the value is empty (not - recommended). - Default: `www-data`. - -*group* - -: The groupname to drop privileges to (setting both effective and real - gid, and also setting the list of supplementary gids to that single - group). Preserve root privileges if the value is empty (not - recommended). - Default: `www-data`. - -*command* - -: Path to the [ACME] webserver executable. A separate process is - spawned for each address to *listen* on. (In particular no - webserver process is forked when the *listen* option is empty.) - Default: `/usr/lib/lacme/webserver`. - -*iptables* - -: Whether to automatically install temporary [`iptables`(8)] rules to - open the `ADDRESS[:PORT]` specified with *listen*. The rules are - automatically removed once `lacme` exits. - Default: `No`. - -`[accountd]` section ---------------------- - -This section is used for configuring the [`lacme-accountd`(1)] process. -If the section (including its header) is absent or commented out, -`lacme` connects to an existing UNIX-domain socket bound by a running -[`lacme-accountd`(1)] process. - -*user* - -: The username to drop privileges to (setting both effective and real - uid). Preserve root privileges if the value is empty. - -*group* - -: The groupname to drop privileges to (setting both effective and real - gid, and also setting the list of supplementary gids to that single - group). Preserve root privileges if the value is empty. - -*command* - -: Path to the [`lacme-accountd`(1)] executable. - Default: `/usr/bin/lacme-accountd`. - -*config* - -: Path to the [`lacme-accountd`(1)] configuration file. - Default: `/etc/lacme/lacme-accountd.conf`. - -*privkey* - -: The (private) account key to use for signing requests. See - [`lacme-accountd`(1)] for details. - -*quiet* - -: Be quiet. Possible values: `Yes`/`No`. - -Certificate configuration file -============================== - -For certificate issuances (`newOrder` command), a separate file is used -to configure paths to the certificate and key, as well as the subject, -subjectAltName, etc. to generate Certificate Signing Requests. -Each section denotes a separate certificate issuance. -Valid options are: - -*certificate* - -: Where to store the issued certificate (in PEM format). - At least one of *certificate* or *certificate-chain* is required. - -*certificate-chain* - -: Where to store the issued certificate, concatenated with the content - of the file specified specified with the *CAfile* option (in PEM - format). - At least one of *certificate* or *certificate-chain* is required. - -*certificate-key* - -: Path the service's private key. This option is required. The - following command can be used to generate a new 4096-bits RSA key in - PEM format with mode 0600: - - openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/srv.key - -*min-days* - -: For an existing certificate, the minimum number of days before its - expiration date the section is considered for re-issuance. - A negative value forces reissuance, while the number `0` limits - reissuance to expired certificates. - Default: the value of the CLI option `--min-days`, or `21` if there - is no such option. - -*CAfile* - -: Path to the issuer's certificate. This is used for - *certificate-chain* and to verify the validity of each issued - certificate. - Specifying an empty value skip certificate validation. - Default: `/usr/share/lacme/lets-encrypt-x3-cross-signed.pem`. - -*hash* - -: Message digest algorithm to sign the Certificate Signing Request - with. - -*keyUsage* - -: Comma-separated list of Key Usages, see [`x509v3_config`(5ssl)]. - -*subject* - -: Subject field of the Certificate Signing Request, in the form - `/type0=value0/type1=value1/type2=…`. This option is required. - -*subjectAltName* - -: Comma-separated list of Subject Alternative Names, in the form - `type0:value1,type1:value1,type2:…` - The only `type` currently supported is `DNS`, to specify an - alternative domain name. - -*chown* - -: An optional `username[:groupname]` to chown the issued *certificate* - and *certificate-chain* to. - -*chmod* - -: An optional octal mode to chmod the issued *certificate* and - *certificate-chain* to. - -*notify* - -: Command to pass the the system's command shell (`/bin/sh -c`) - after successful installation of the *certificate* and/or - *certificate-chain*. - -Examples -======== - - ~$ sudo lacme account --register --tos-agreed mailto:noreply@example.com - ~$ sudo lacme newOrder - ~$ sudo lacme revokeCert /path/to/server/certificate.pem - -See also -======== - -[`lacme-accountd`(1)] - -[ACME]: https://tools.ietf.org/html/rfc8555 -[`lacme-accountd`(1)]: lacme-accountd.1.html -[`iptables`(8)]: http://linux.die.net/man/8/iptables -[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html -[`x509v3_config`(5ssl)]: https://www.openssl.org/docs/manmaster/apps/x509v3_config.html diff --git a/lacme.8.md b/lacme.8.md new file mode 100644 index 0000000..79fb300 --- /dev/null +++ b/lacme.8.md @@ -0,0 +1,413 @@ +% lacme(8) +% [Guilhem Moulin](mailto:guilhem@fripost.org) +% December 2015 + +Name +==== + +lacme - [ACME] client written with process isolation and minimal +privileges in mind + +Synopsis +======== + +`lacme` [`--config=FILENAME`] [`--socket=PATH`] [*OPTION* …] *COMMAND* [*ARGUMENT* …] + +Description +=========== + +`lacme` is a small [ACME] client written with process isolation and +minimal privileges in mind. It is divided into four components, each +with its own executable: + + 1. A [`lacme-accountd`(1)] process to manage the account key and issue + SHA-256 signatures needed for each [ACME] command. (This process + binds to a UNIX-domain socket to reply to signature requests from + the [ACME] client.) + One can use the UNIX-domain socket forwarding facility of OpenSSH + 6.7 and later to run [`lacme-accountd`(1)] and `lacme` on different + hosts. Alternatively, the [`lacme-accountd`(1)] process can be + spawned by the “master” `lacme` process below; in that case, the + two processes communicate through a socket pair. + + 2. A “master” `lacme` process, which runs as root and is the only + component with access to the private key material of the server + keys. It is used to fork the [ACME] client (and optionally the + [ACME] webserver) after dropping root privileges. + For certificate issuances (`newOrder` command), it also generates + Certificate Signing Requests, then verifies the validity of the + issued certificate, and optionally reloads or restarts services when + the *notify* option is set. + + 3. An actual [ACME] client (specified with the *command* option of the + [`[client]` section](#client-section) of the configuration file), + which builds [ACME] commands and dialogues with the remote [ACME] + server. + Since [ACME] commands need to be signed with the account key, the + “master” `lacme` process passes the [`lacme-accountd`(1)] + UNIX-domain socket to the [ACME] client: data signatures are + requested by writing the data to be signed to the socket. + + 4. For certificate issuances (`newOrder` command), an optional + webserver (specified with the *command* option of the [`[webserver]` + section](#webserver-section) of the configuration file), which is + spawned by the “master” `lacme`. (The only challenge type currently + supported by `lacme` is `http-01`, which requires a webserver to + answer challenges.) That webserver only processes `GET` and `HEAD` + requests under the `/.well-known/acme-challenge/` URI. + Moreover temporary [`iptables`(8)] rules can be automatically + installed to open the HTTP port. + +Commands +======== + +`lacme account` [`--tos-agreed`] [`--register`] [*CONTACT* …] + +: Register (if `--registered` is set) a [`lacme-accountd`(1)]-managed + account key. A list of *CONTACT* information (such as `maito:` + URIs) can be specified in order for the [ACME] server to contact the + client for issues related to this registration (such as + notifications about server-initiated revocations). `--tos-agreed` + indicates agreement with the [ACME] server's Terms of Service (and + might be required for registration). + + If the account key is already registered, update the contact info + with the given list of *CONTACT* information. + + Upon success, `lacme` prints the new or updated Account Object from + the [ACME] server. + +`lacme` [`--config-certs=`*FILE*] [`--min-days=`*INT*] `newOrder` [*SECTION* …] + +: Read the certificate configuration *FILE* (see the **[certificate + configuration file](#certificate-configuration-file)** section below + for the configuration options), and request new Certificate Issuance + for each of its sections (or the given list of *SECTION*s). + Command alias: `new-order`. + +`lacme` `revokeCert` *FILE* [*FILE* …] + +: Request that the given certificate(s) *FILE*(s) be revoked. For + this command, [`lacme-accountd`(1)] can be pointed to either the + account key or the server's private key. + Command alias: `revoke-cert`. + +Generic options +=============== + +`--config=`*filename* + +: Use *filename* as configuration file. See the **[configuration + file](#configuration-file)** section below for the configuration + options. + +`--socket=`*path* + +: Use *path* as the [`lacme-accountd`(1)] UNIX-domain socket to + connect to for signature requests from the [ACME] client. `lacme` + aborts if `path` is readable or writable by other users, or if its + parent directory is writable by other users. + This command-line option overrides the *socket* option of the + [`[client]` section](#client-section) of the configuration file. + Moreover this option is ignored when the configuration file has an + [`[accountd]` section](#accountd-section); in that case `lacme` + spawns [`lacme-accountd`(1)], and the two processes communicate + through a socket pair. + +`-h`, `--help` + +: Display a brief help and exit. + +`-q`, `--quiet` + +: Be quiet. + +`--debug` + +: Turn on debug mode. + +Configuration file +================== + +If `--config=` is not given, `lacme` uses the first existing +configuration file among *./lacme.conf*, +*$XDG_CONFIG_HOME/lacme/lacme.conf* (or *~/.config/lacme/lacme.conf* if +the `XDG_CONFIG_HOME` environment variable is not set), and +*/etc/lacme/lacme.conf*. +Valid options are: + +Default section +--------------- + +*config-certs* + +: For certificate issuances (`newOrder` command), specify the + space-separated list of certificate configuration files or + directories to use (see the **[certificate configuration + file](#certificate-configuration-file)** section below for the + configuration options). + + Paths not starting with `/` are relative to the directory name of + the **[configuration filename](#configuration-file)**. The list of + files and directories is processed in order, with the later items + taking precedence. Files in a directory are processed in + lexicographic order, only considering the ones with suffix `.conf`. + + Default: `lacme-certs.conf lacme-certs.conf.d/`. + +`[client]` section +------------------ + +This section is used for configuring the [ACME] client (which takes care +of [ACME] commands and dialogues with the remote [ACME] server). + +*socket* + +: See `--socket=`. + Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR` + environment variable is set. + +*user* + +: The username to drop privileges to (setting both effective and real + uid). Preserve root privileges if the value is empty (not + recommended). + Default: `nobody`. + +*group* + +: The groupname to drop privileges to (setting both effective and real + gid, and also setting the list of supplementary gids to that single + group). Preserve root privileges if the value is empty (not + recommended). + Default: `nogroup`. + +*command* + +: Path to the [ACME] client executable. + Default: `/usr/lib/lacme/client`. + +*server* + +: Root URI of the [ACME] server. + Default: `https://acme-v02.api.letsencrypt.org/directory`. + +*timeout* + +: Timeout in seconds after which the client stops polling the [ACME] + server and considers the request failed. + Default: `10`. + +*SSL_verify* + +: Whether to verify the server certificate chain. + Default: `Yes`. + +*SSL_version* + +: Specify the version of the SSL protocol used to transmit data. + +*SSL_cipher_list* + +: Specify the cipher list for the connection, see [`ciphers`(1ssl)] + for more information. + +`[webserver]` section +--------------------- + +This section is used to configure how [ACME] challenge responses are +served during certificate issuance. + +*listen* + +: Comma- or space-separated list of addresses to listen on. Valid + addresses are of the form `IPV4:PORT`, `[IPV6]:PORT` (where the + `:PORT` suffix is optional and defaults to the HTTP port 80), or an + absolute path of a UNIX-domain socket (created with mode `0666`). + Default: `/run/lacme-www.socket`. + + **Note**: The default value is only suitable when an external HTTP + daemon is publicly reachable and passes all ACME challenge requests + to the webserver component through the UNIX-domain socket + `/run/lacme-www.socket` (for instance using the provided + `/etc/lacme/apache2.conf` or `/etc/lacme/nginx.conf` configuration + snippets for each virtual host requiring authorization). If there + is no HTTP daemon bound to port 80 one needs to set *listen* to + `[::]` (or `0.0.0.0 [::]` when dual IPv4/IPv6 stack is disabled or + unavailable), and possibly also set *iptables* to `Yes`. + +*challenge-directory* + +: Specify a non-existent directory under which an external HTTP daemon + is configured to serve `GET` requests for challenge files under + `/.well-known/acme-challenge/` (for each virtual host requiring + authorization) as static files. + This option is required when *listen* is empty. + +*user* + +: The username to drop privileges to (setting both effective and real + uid). Preserve root privileges if the value is empty (not + recommended). + Default: `www-data`. + +*group* + +: The groupname to drop privileges to (setting both effective and real + gid, and also setting the list of supplementary gids to that single + group). Preserve root privileges if the value is empty (not + recommended). + Default: `www-data`. + +*command* + +: Path to the [ACME] webserver executable. A separate process is + spawned for each address to *listen* on. (In particular no + webserver process is forked when the *listen* option is empty.) + Default: `/usr/lib/lacme/webserver`. + +*iptables* + +: Whether to automatically install temporary [`iptables`(8)] rules to + open the `ADDRESS[:PORT]` specified with *listen*. The rules are + automatically removed once `lacme` exits. + Default: `No`. + +`[accountd]` section +--------------------- + +This section is used for configuring the [`lacme-accountd`(1)] process. +If the section (including its header) is absent or commented out, +`lacme` connects to an existing UNIX-domain socket bound by a running +[`lacme-accountd`(1)] process. + +*user* + +: The username to drop privileges to (setting both effective and real + uid). Preserve root privileges if the value is empty. + +*group* + +: The groupname to drop privileges to (setting both effective and real + gid, and also setting the list of supplementary gids to that single + group). Preserve root privileges if the value is empty. + +*command* + +: Path to the [`lacme-accountd`(1)] executable. + Default: `/usr/bin/lacme-accountd`. + +*config* + +: Path to the [`lacme-accountd`(1)] configuration file. + Default: `/etc/lacme/lacme-accountd.conf`. + +*privkey* + +: The (private) account key to use for signing requests. See + [`lacme-accountd`(1)] for details. + +*quiet* + +: Be quiet. Possible values: `Yes`/`No`. + +Certificate configuration file +============================== + +For certificate issuances (`newOrder` command), a separate file is used +to configure paths to the certificate and key, as well as the subject, +subjectAltName, etc. to generate Certificate Signing Requests. +Each section denotes a separate certificate issuance. +Valid options are: + +*certificate* + +: Where to store the issued certificate (in PEM format). + At least one of *certificate* or *certificate-chain* is required. + +*certificate-chain* + +: Where to store the issued certificate, concatenated with the content + of the file specified specified with the *CAfile* option (in PEM + format). + At least one of *certificate* or *certificate-chain* is required. + +*certificate-key* + +: Path the service's private key. This option is required. The + following command can be used to generate a new 4096-bits RSA key in + PEM format with mode 0600: + + openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/srv.key + +*min-days* + +: For an existing certificate, the minimum number of days before its + expiration date the section is considered for re-issuance. + A negative value forces reissuance, while the number `0` limits + reissuance to expired certificates. + Default: the value of the CLI option `--min-days`, or `21` if there + is no such option. + +*CAfile* + +: Path to the issuer's certificate. This is used for + *certificate-chain* and to verify the validity of each issued + certificate. + Specifying an empty value skip certificate validation. + Default: `/usr/share/lacme/lets-encrypt-x3-cross-signed.pem`. + +*hash* + +: Message digest algorithm to sign the Certificate Signing Request + with. + +*keyUsage* + +: Comma-separated list of Key Usages, see [`x509v3_config`(5ssl)]. + +*subject* + +: Subject field of the Certificate Signing Request, in the form + `/type0=value0/type1=value1/type2=…`. This option is required. + +*subjectAltName* + +: Comma-separated list of Subject Alternative Names, in the form + `type0:value1,type1:value1,type2:…` + The only `type` currently supported is `DNS`, to specify an + alternative domain name. + +*chown* + +: An optional `username[:groupname]` to chown the issued *certificate* + and *certificate-chain* to. + +*chmod* + +: An optional octal mode to chmod the issued *certificate* and + *certificate-chain* to. + +*notify* + +: Command to pass the the system's command shell (`/bin/sh -c`) + after successful installation of the *certificate* and/or + *certificate-chain*. + +Examples +======== + + ~$ sudo lacme account --register --tos-agreed mailto:noreply@example.com + ~$ sudo lacme newOrder + ~$ sudo lacme revokeCert /path/to/server/certificate.pem + +See also +======== + +[`lacme-accountd`(1)] + +[ACME]: https://tools.ietf.org/html/rfc8555 +[`lacme-accountd`(1)]: lacme-accountd.1.html +[`iptables`(8)]: http://linux.die.net/man/8/iptables +[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html +[`x509v3_config`(5ssl)]: https://www.openssl.org/docs/manmaster/apps/x509v3_config.html -- cgit v1.2.3 From 294bc39102e9263a268b58fe29e03c9983ccfeca Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 3 Aug 2020 22:29:37 +0200 Subject: Change default libexec dir from /usr/lib/lacme to /usr/libexec/lacme. --- Changelog | 1 + Makefile | 2 +- config/lacme.conf | 4 ++-- lacme | 4 ++-- lacme.8.md | 4 ++-- 5 files changed, 8 insertions(+), 7 deletions(-) (limited to 'config') diff --git a/Changelog b/Changelog index a220c83..45e7a99 100644 --- a/Changelog +++ b/Changelog @@ -6,6 +6,7 @@ lacme (0.7) UNRELEASED; * Makefile: major refactoring, add install and uninstall targets, honor BUILD_DOCDIR and DESTDIR variables. * Install lacme manual to section 8. + * Change default libexec dir from /usr/lib/lacme to /usr/libexec/lacme. -- Guilhem Moulin Thu, 22 Aug 2019 00:31:35 +0200 diff --git a/Makefile b/Makefile index 06841ee..467b834 100644 --- a/Makefile +++ b/Makefile @@ -15,7 +15,7 @@ prefix ?= $(DESTDIR) exec_prefix ?= $(prefix) bindir ?= $(exec_prefix)/bin sbindir ?= $(exec_prefix)/sbin -libexecdir ?= $(exec_prefix)/lib +libexecdir ?= $(exec_prefix)/libexec datarootdir ?= $(prefix)/share sysconfdir ?= $(prefix)/etc mandir ?= $(datarootdir)/man diff --git a/config/lacme.conf b/config/lacme.conf index acafe81..236d203 100644 --- a/config/lacme.conf +++ b/config/lacme.conf @@ -31,7 +31,7 @@ # Path to the ACME client executable. # -#command = /usr/lib/lacme/client +#command = /usr/libexec/lacme/client # URI of the ACME server's directory. NOTE: Use the staging server # for testing @@ -84,7 +84,7 @@ # Path to the ACME webserver executable. # -#command = /usr/lib/lacme/webserver +#command = /usr/libexec/lacme/webserver # Whether to automatically install iptables(8) rules to open the # ADDRESS[:PORT] specified with listen. Theses rules are automatically diff --git a/lacme b/lacme index 5ad28a8..73180f0 100755 --- a/lacme +++ b/lacme @@ -93,7 +93,7 @@ do { socket => (defined $ENV{XDG_RUNTIME_DIR} ? "$ENV{XDG_RUNTIME_DIR}/S.lacme" : undef), user => 'nobody', group => 'nogroup', - command => '/usr/lib/lacme/client', + command => '/usr/libexec/lacme/client', # the rest is for the ACME client map {$_ => undef} qw/server timeout SSL_verify SSL_version SSL_cipher_list/ }, @@ -102,7 +102,7 @@ do { 'challenge-directory' => undef, user => 'www-data', group => 'www-data', - command => '/usr/lib/lacme/webserver', + command => '/usr/libexec/lacme/webserver', iptables => 'No' }, diff --git a/lacme.8.md b/lacme.8.md index 79fb300..1d1aede 100644 --- a/lacme.8.md +++ b/lacme.8.md @@ -185,7 +185,7 @@ of [ACME] commands and dialogues with the remote [ACME] server). *command* : Path to the [ACME] client executable. - Default: `/usr/lib/lacme/client`. + Default: `/usr/libexec/lacme/client`. *server* @@ -264,7 +264,7 @@ served during certificate issuance. : Path to the [ACME] webserver executable. A separate process is spawned for each address to *listen* on. (In particular no webserver process is forked when the *listen* option is empty.) - Default: `/usr/lib/lacme/webserver`. + Default: `/usr/libexec/lacme/webserver`. *iptables* -- cgit v1.2.3 From da8b727f156d23553eecb90e8731d39c6027cb02 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Tue, 4 Aug 2020 00:00:58 +0200 Subject: Makefile: Use variables for target directories etc. --- .gitignore | 4 +--- Changelog | 4 +--- Makefile | 39 ++++++++++++++++++++++++++------------- config/lacme-certs.conf | 2 +- config/lacme.conf | 10 +++++----- lacme | 14 +++++++------- lacme-accountd | 2 +- lacme-accountd.1.md | 2 +- lacme.8.md | 18 +++++++++--------- snippets/apache2.conf | 2 +- snippets/nginx.conf | 2 +- 11 files changed, 54 insertions(+), 45 deletions(-) (limited to 'config') diff --git a/.gitignore b/.gitignore index 21f822a..f6e4380 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,4 @@ # vim swapfiles .*.sw[po] -# generated man-pages -/lacme.8 -/lacme-accountd.1 +/build/ diff --git a/Changelog b/Changelog index 95d17bf..2b1bbe2 100644 --- a/Changelog +++ b/Changelog @@ -1,13 +1,11 @@ lacme (0.7) UNRELEASED; - + Default listening socket for the webserver component is now - /run/lacme-www.socket. (It was previously under the legacy directory - /var/run.) + Adapt Apache2 snippet to Apache2 2.4. * Makefile: major refactoring, add install and uninstall targets, honor BUILD_DOCDIR and DESTDIR variables. * Install lacme manual to section 8. * Change default libexec dir from /usr/lib/lacme to /usr/libexec/lacme. + * Makefile: Use variables for target directories etc. -- Guilhem Moulin Thu, 22 Aug 2019 00:31:35 +0200 diff --git a/Makefile b/Makefile index 467b834..757a581 100644 --- a/Makefile +++ b/Makefile @@ -1,14 +1,14 @@ DESTDIR ?= /usr/local -BUILD_DOCDIR ?= . -MANUAL_FILES = $(addprefix $(BUILD_DOCDIR)/,$(patsubst ./%.md,%,$(wildcard ./*.[1-9].md))) +BUILDDIR ?= ./build +MANUAL_FILES = $(addprefix $(BUILDDIR)/,$(patsubst ./%.md,%,$(wildcard ./*.[1-9].md))) -all: manual +all: manual $(addprefix $(BUILDDIR)/,lacme lacme-accountd client webserver $(wildcard config/* snippets/*)) doc: manual manual: $(MANUAL_FILES) # upper case the headers and remove the links -$(MANUAL_FILES): $(BUILD_DOCDIR)/%: ./%.md +$(MANUAL_FILES): $(BUILDDIR)/%: $(BUILDDIR)/%.md pandoc -f markdown -t json -- "$<" | ./pandoc2man.jq | pandoc -s -f json -t man -o "$@" prefix ?= $(DESTDIR) @@ -17,27 +17,40 @@ bindir ?= $(exec_prefix)/bin sbindir ?= $(exec_prefix)/sbin libexecdir ?= $(exec_prefix)/libexec datarootdir ?= $(prefix)/share +datadir ?= $(datarootdir) sysconfdir ?= $(prefix)/etc +localstatedir =? $(prefix)/var +runstatedir ?= $(localstatedir)/run mandir ?= $(datarootdir)/man man1dir ?= $(mandir)/man1 man8dir ?= $(mandir)/man8 +$(BUILDDIR)/%: % + mkdir -pv -- $(dir $@) + cp --no-dereference --preserve=mode,links,xattr -vfT -- "$<" "$@" + sed -i "s#@@bindir@@#$(bindir)#g; \ + s#@@sbindir@@#$(sbindir)#g; \ + s#@@libexecdir@@#$(libexecdir)#g; \ + s#@@datadir@@#$(datadir)#g; \ + s#@@runstatedir@@#$(runstatedir)#g; \ + s#@@sysconfdir@@#$(sysconfdir)#g;" -- "$@" + install: all - install -m0644 -vDt $(sysconfdir)/lacme config/*.conf snippets/*.conf + install -m0644 -vDt $(sysconfdir)/lacme $(BUILDDIR)/config/*.conf $(BUILDDIR)/snippets/*.conf install -vd $(sysconfdir)/lacme/lacme-certs.conf.d - install -m0644 -vDt $(datarootdir)/lacme certs/lets-encrypt-x[1-4]-cross-signed.pem - install -m0755 -vDt $(libexecdir)/lacme ./client ./webserver - install -m0644 -vDt $(man1dir) $(BUILD_DOCDIR)/lacme-accountd.1 - install -m0644 -vDt $(man8dir) $(BUILD_DOCDIR)/lacme.8 - install -m0644 -vDt $(bindir) ./lacme-accountd - install -m0644 -vDt $(sbindir) ./lacme + install -m0644 -vDt $(datadir)/lacme certs/lets-encrypt-x[1-4]-cross-signed.pem + install -m0755 -vDt $(libexecdir)/lacme $(BUILDDIR)/client $(BUILDDIR)/webserver + install -m0644 -vDt $(man1dir) $(BUILDDIR)/lacme-accountd.1 + install -m0644 -vDt $(man8dir) $(BUILDDIR)/lacme.8 + install -m0644 -vDt $(bindir) $(BUILDDIR)/lacme-accountd + install -m0644 -vDt $(sbindir) $(BUILDDIR)/lacme uninstall: rm -vf -- $(bindir)/lacme-accountd $(sbindir)/lacme rm -vf -- $(man1dir)/lacme-accountd.1 $(man8dir)/lacme.8 - rm -rvf -- $(sysconfdir)/lacme $(datarootdir)/lacme $(libexecdir)/lacme + rm -rvf -- $(sysconfdir)/lacme $(datadir)/lacme $(libexecdir)/lacme clean: - rm -vf -- $(MANUAL_FILES) + rm -rvf -- $(BUILDDIR) .PHONY: all doc manual install uninstall clean diff --git a/config/lacme-certs.conf b/config/lacme-certs.conf index 97d588a..dd02f95 100644 --- a/config/lacme-certs.conf +++ b/config/lacme-certs.conf @@ -34,7 +34,7 @@ # and to verify the validity of each issued certificate. Specifying an # empty value skip certificate validation. # -#CAfile = /usr/share/lacme/lets-encrypt-x3-cross-signed.pem +#CAfile = @@datadir@@/lacme/lets-encrypt-x3-cross-signed.pem # Subject field of the Certificate Signing Request. This option is # required. diff --git a/config/lacme.conf b/config/lacme.conf index 236d203..cf7edfd 100644 --- a/config/lacme.conf +++ b/config/lacme.conf @@ -31,7 +31,7 @@ # Path to the ACME client executable. # -#command = /usr/libexec/lacme/client +#command = @@libexecdir@@/lacme/client # URI of the ACME server's directory. NOTE: Use the staging server # for testing @@ -62,7 +62,7 @@ # Comma- or space-separated list of addresses to listen on, for instance # "0.0.0.0:80 [::]:80". # -#listen = /run/lacme-www.socket +#listen = @@runstatedir@@/lacme-www.socket # Non-existent directory under which an external HTTP daemon is # configured to serve GET requests for challenge files under @@ -84,7 +84,7 @@ # Path to the ACME webserver executable. # -#command = /usr/libexec/lacme/webserver +#command = @@libexecdir@@/lacme/webserver # Whether to automatically install iptables(8) rules to open the # ADDRESS[:PORT] specified with listen. Theses rules are automatically @@ -111,11 +111,11 @@ # Path to the lacme-accountd(1) executable. # -#command = /usr/bin/lacme-accountd +#command = @@bindir@@/lacme-accountd # Path to the lacme-accountd(1) configuration file. # -#config = /etc/lacme/lacme-accountd.conf +#config = @@sysconfdir@@/lacme/lacme-accountd.conf # The (private) account key to use for signing requests. See # lacme-accountd(1) for details. diff --git a/lacme b/lacme index 73180f0..566545b 100755 --- a/lacme +++ b/lacme @@ -75,7 +75,7 @@ sub set_FD_CLOEXEC($$); my $CONFFILENAME = $OPTS{config} // first { -f $_ } ( "./$NAME.conf" , ($ENV{XDG_CONFIG_HOME} // "$ENV{HOME}/.config")."/lacme/$NAME.conf" - , "/etc/lacme/$NAME.conf" + , "@@sysconfdir@@/lacme/$NAME.conf" ); do { die "Error: Can't find configuration file\n" unless defined $CONFFILENAME; @@ -93,24 +93,24 @@ do { socket => (defined $ENV{XDG_RUNTIME_DIR} ? "$ENV{XDG_RUNTIME_DIR}/S.lacme" : undef), user => 'nobody', group => 'nogroup', - command => '/usr/libexec/lacme/client', + command => '@@libexecdir@@/lacme/client', # the rest is for the ACME client map {$_ => undef} qw/server timeout SSL_verify SSL_version SSL_cipher_list/ }, webserver => { - listen => '/run/lacme-www.socket', + listen => '@@runstatedir@@/lacme-www.socket', 'challenge-directory' => undef, user => 'www-data', group => 'www-data', - command => '/usr/libexec/lacme/webserver', + command => '@@libexecdir@@/lacme/webserver', iptables => 'No' }, accountd => { user => '', group => '', - command => '/usr/bin/lacme-accountd', - config => '/etc/lacme/lacme-accountd.conf', + command => '@@bindir@@/lacme-accountd', + config => '@@sysconfdir@@/lacme/lacme-accountd.conf', privkey => undef, quiet => 'Yes', } @@ -743,7 +743,7 @@ elsif ($COMMAND eq 'newOrder' or $COMMAND eq 'new-cert') { }; # verify certificate validity against the CA - $conf->{CAfile} //= '/usr/share/lacme/lets-encrypt-x3-cross-signed.pem'; + $conf->{CAfile} //= '@@datadir@@/lacme/lets-encrypt-x3-cross-signed.pem'; if ($conf->{CAfile} ne '' and spawn({in => $x509}, 'openssl', 'verify', '-CAfile', $conf->{CAfile}, qw/-purpose sslserver -x509_strict/)) { print STDERR "[$s] Error: Received invalid X.509 certificate from ACME server!\n"; diff --git a/lacme-accountd b/lacme-accountd index 822894b..89774c2 100755 --- a/lacme-accountd +++ b/lacme-accountd @@ -67,7 +67,7 @@ do { my $conffile = $OPTS{config} // first { -f $_ } ( "./$NAME.conf" , ($ENV{XDG_CONFIG_HOME} // "$ENV{HOME}/.config")."/lacme/$NAME.conf" - , "/etc/lacme/$NAME.conf" + , "@@sysconfdir@@/lacme/$NAME.conf" ); die "Error: Can't find configuration file\n" unless defined $conffile; print STDERR "Using configuration file: $conffile\n" if $OPTS{debug}; diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 215adf6..77cc8ed 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -85,7 +85,7 @@ If `--config=` is not given, `lacme-accountd` uses the first existing configuration file among *./lacme-accountd.conf*, *$XDG_CONFIG_HOME/lacme/lacme-accountd.conf* (or *~/.config/lacme/lacme-accountd.conf* if the `XDG_CONFIG_HOME` -environment variable is not set), and */etc/lacme/lacme-accountd.conf*. +environment variable is not set), and *@@sysconfdir@@/lacme/lacme-accountd.conf*. When given on the command line, the `--privkey=`, `--socket=` and `--quiet` options take precedence over their counterpart (without diff --git a/lacme.8.md b/lacme.8.md index 1d1aede..e250858 100644 --- a/lacme.8.md +++ b/lacme.8.md @@ -133,7 +133,7 @@ If `--config=` is not given, `lacme` uses the first existing configuration file among *./lacme.conf*, *$XDG_CONFIG_HOME/lacme/lacme.conf* (or *~/.config/lacme/lacme.conf* if the `XDG_CONFIG_HOME` environment variable is not set), and -*/etc/lacme/lacme.conf*. +*@@sysconfdir@@/lacme/lacme.conf*. Valid options are: Default section @@ -185,7 +185,7 @@ of [ACME] commands and dialogues with the remote [ACME] server). *command* : Path to the [ACME] client executable. - Default: `/usr/libexec/lacme/client`. + Default: `@@libexecdir@@/lacme/client`. *server* @@ -224,13 +224,13 @@ served during certificate issuance. addresses are of the form `IPV4:PORT`, `[IPV6]:PORT` (where the `:PORT` suffix is optional and defaults to the HTTP port 80), or an absolute path of a UNIX-domain socket (created with mode `0666`). - Default: `/run/lacme-www.socket`. + Default: `@@runstatedir@@/lacme-www.socket`. **Note**: The default value is only suitable when an external HTTP daemon is publicly reachable and passes all ACME challenge requests to the webserver component through the UNIX-domain socket - `/run/lacme-www.socket` (for instance using the provided - `/etc/lacme/apache2.conf` or `/etc/lacme/nginx.conf` configuration + `@@runstatedir@@/lacme-www.socket` (for instance using the provided + `@@sysconfdir@@/lacme/apache2.conf` or `@@sysconfdir@@/lacme/nginx.conf` configuration snippets for each virtual host requiring authorization). If there is no HTTP daemon bound to port 80 one needs to set *listen* to `[::]` (or `0.0.0.0 [::]` when dual IPv4/IPv6 stack is disabled or @@ -264,7 +264,7 @@ served during certificate issuance. : Path to the [ACME] webserver executable. A separate process is spawned for each address to *listen* on. (In particular no webserver process is forked when the *listen* option is empty.) - Default: `/usr/libexec/lacme/webserver`. + Default: `@@libexecdir@@/lacme/webserver`. *iptables* @@ -295,12 +295,12 @@ If the section (including its header) is absent or commented out, *command* : Path to the [`lacme-accountd`(1)] executable. - Default: `/usr/bin/lacme-accountd`. + Default: `@@bindir@@/lacme-accountd`. *config* : Path to the [`lacme-accountd`(1)] configuration file. - Default: `/etc/lacme/lacme-accountd.conf`. + Default: `@@sysconfdir@@/lacme/lacme-accountd.conf`. *privkey* @@ -355,7 +355,7 @@ Valid options are: *certificate-chain* and to verify the validity of each issued certificate. Specifying an empty value skip certificate validation. - Default: `/usr/share/lacme/lets-encrypt-x3-cross-signed.pem`. + Default: `@@datadir@@/lacme/lets-encrypt-x3-cross-signed.pem`. *hash* diff --git a/snippets/apache2.conf b/snippets/apache2.conf index c42a9fb..45d7c7f 100644 --- a/snippets/apache2.conf +++ b/snippets/apache2.conf @@ -5,7 +5,7 @@ # non-ssl one) of each virtual host requiring authorization. - ProxyPass unix:///run/lacme-www.socket|http://localhost/.well-known/acme-challenge/ + ProxyPass unix://@@runstatedir@@/lacme-www.socket|http://localhost/.well-known/acme-challenge/ Require all granted diff --git a/snippets/nginx.conf b/snippets/nginx.conf index 86592d2..6775489 100644 --- a/snippets/nginx.conf +++ b/snippets/nginx.conf @@ -6,7 +6,7 @@ location ^~ /.well-known/acme-challenge/ { # Pass ACME requests to lacme's webserver component - proxy_pass http://unix:/run/lacme-www.socket; + proxy_pass http://unix:@@runstatedir@@/lacme-www.socket; ## Alternatively, you can let nginx serve the requests by ## setting 'challenge-directory' to '/var/www/acme-challenge' in -- cgit v1.2.3 From e419eb68718085fa2e2505eb4b4aa08145f7dc1c Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 3 Aug 2020 22:57:32 +0200 Subject: Ignore [accountd] section from lacme.conf when the --socket option is defined. This allows remotely-controlled lacme processes being controlled without modifying an config files. See https://bugs.debian.org/955767 . --- Changelog | 3 +++ config/lacme.conf | 4 ++-- lacme | 2 +- lacme.8.md | 17 ++++++++--------- 4 files changed, 14 insertions(+), 12 deletions(-) (limited to 'config') diff --git a/Changelog b/Changelog index 2b1bbe2..1e54354 100644 --- a/Changelog +++ b/Changelog @@ -1,6 +1,9 @@ lacme (0.7) UNRELEASED; + Adapt Apache2 snippet to Apache2 2.4. + + Ignore [accountd] section from lacme.conf when the --socket option is + defined. This allows remotely-controlled lacme processes being + controlled without modifying an config files. * Makefile: major refactoring, add install and uninstall targets, honor BUILD_DOCDIR and DESTDIR variables. * Install lacme manual to section 8. diff --git a/config/lacme.conf b/config/lacme.conf index cf7edfd..9f4db72 100644 --- a/config/lacme.conf +++ b/config/lacme.conf @@ -95,8 +95,8 @@ [accountd] # lacme-accound(1) section. Comment out this section (including its -# header) to make lacme(8) connect to an existing UNIX-domain socket -# bound by a running acme-accountd(1) process. +# header), or use the --socket= CLI option, to make lacme(8) connect to +# an existing lacme-accountd(1) process via a UNIX-domain socket. # username to drop privileges to (setting both effective and real uid). # Preserve root privileges if the value is empty. diff --git a/lacme b/lacme index 566545b..8701047 100755 --- a/lacme +++ b/lacme @@ -87,7 +87,7 @@ do { my $h = Config::Tiny::->read_string($conf) or die Config::Tiny::->errstr()."\n"; my $defaults = delete $h->{_} // {}; - my $accountd = exists $h->{accountd} ? 1 : 0; + my $accountd = defined $OPTS{socket} ? 0 : exists $h->{accountd} ? 1 : 0; my %valid = ( client => { socket => (defined $ENV{XDG_RUNTIME_DIR} ? "$ENV{XDG_RUNTIME_DIR}/S.lacme" : undef), diff --git a/lacme.8.md b/lacme.8.md index e250858..8f8eb41 100644 --- a/lacme.8.md +++ b/lacme.8.md @@ -108,11 +108,9 @@ Generic options aborts if `path` is readable or writable by other users, or if its parent directory is writable by other users. This command-line option overrides the *socket* option of the - [`[client]` section](#client-section) of the configuration file. - Moreover this option is ignored when the configuration file has an - [`[accountd]` section](#accountd-section); in that case `lacme` - spawns [`lacme-accountd`(1)], and the two processes communicate - through a socket pair. + [`[client]` section](#client-section) of the configuration file; it + also causes the [`[accountd]` section](#accountd-section) to be + ignored. `-h`, `--help` @@ -276,10 +274,11 @@ served during certificate issuance. `[accountd]` section --------------------- -This section is used for configuring the [`lacme-accountd`(1)] process. -If the section (including its header) is absent or commented out, -`lacme` connects to an existing UNIX-domain socket bound by a running -[`lacme-accountd`(1)] process. +This section is used for configuring the [`lacme-accountd`(1)] child +process. If the section (including its header) is absent or commented +out, or if the CLI option `--socket` is specified, then `lacme` connects +to an existing [`lacme-accountd`(1)] process via the specified +UNIX-domain socket. *user* -- cgit v1.2.3