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. --- Changelog | 8 ++++++++ config/lacme.conf | 2 +- lacme | 2 +- lacme.md | 4 ++-- snippets/apache2.conf | 2 +- snippets/nginx.conf | 2 +- 6 files changed, 14 insertions(+), 6 deletions(-) diff --git a/Changelog b/Changelog index c7cc0b3..2010c52 100644 --- a/Changelog +++ b/Changelog @@ -1,3 +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.) + + -- Guilhem Moulin Thu, 22 Aug 2019 00:31:35 +0200 + lacme (0.6) upstream; + client: poll order URL instead of each authz URL successively. 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 diff --git a/lacme b/lacme index d5e8933..5ad28a8 100755 --- a/lacme +++ b/lacme @@ -98,7 +98,7 @@ do { map {$_ => undef} qw/server timeout SSL_verify SSL_version SSL_cipher_list/ }, webserver => { - listen => '/var/run/lacme-www.socket', + listen => '/run/lacme-www.socket', 'challenge-directory' => undef, user => 'www-data', group => 'www-data', diff --git a/lacme.md b/lacme.md index ca9a6a9..5d86f40 100644 --- a/lacme.md +++ b/lacme.md @@ -224,12 +224,12 @@ 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: `/var/run/lacme-www.socket`. + 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 - `/var/run/lacme-www.socket` (for instance using the provided + `/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 diff --git a/snippets/apache2.conf b/snippets/apache2.conf index 20bf2ad..e1d56a9 100644 --- a/snippets/apache2.conf +++ b/snippets/apache2.conf @@ -5,7 +5,7 @@ # non-ssl one) of each virtual host requiring authorization. - ProxyPass unix:///var/run/lacme-www.socket|http://localhost/.well-known/acme-challenge/ + ProxyPass unix:///run/lacme-www.socket|http://localhost/.well-known/acme-challenge/ Order allow,deny Allow from all diff --git a/snippets/nginx.conf b/snippets/nginx.conf index 981bdc3..86592d2 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:/var/run/lacme-www.socket; + proxy_pass http://unix:/run/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 0cf8517bea1e939d7054e682cde24767e7ed6e04 Mon Sep 17 00:00:00 2001 From: Benjamin Tietz Date: Wed, 28 Nov 2018 20:20:54 +0100 Subject: factor out jq-script from Makefile the script is just a plain copy, but now accessible without make --- Makefile | 25 +------------------------ fixman.jq | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 24 deletions(-) create mode 100755 fixman.jq diff --git a/Makefile b/Makefile index 5d421bf..0aa3046 100644 --- a/Makefile +++ b/Makefile @@ -5,30 +5,7 @@ all: ${MANPAGES} # upper case the headers and remove the links %.1: %.md @pandoc -f markdown -t json "$<" | \ - jq " \ - def fixheaders: \ - if .t == \"Header\" then \ - .c[2][] |= (if .t == \"Str\" then .c |= ascii_upcase else . end)\ - else \ - . \ - end; \ - def fixlinks: \ - if type == \"object\" then \ - if .t == \"Link\" then \ - if .c[2][0][0:7] == \"mailto:\" then . else .c[1][] end \ - else \ - map_values(fixlinks) \ - end \ - else if type == \"array\" then \ - map(fixlinks) \ - else \ - . \ - end \ - end; \ - { \"pandoc-api-version\" \ - , meta \ - , blocks: .blocks | map(fixheaders) | map(fixlinks) \ - }" | \ + jq -f fixman.jq | \ pandoc -s -f json -t man+smart -o "$@" install: ${MANPAGES} diff --git a/fixman.jq b/fixman.jq new file mode 100755 index 0000000..3524420 --- /dev/null +++ b/fixman.jq @@ -0,0 +1,26 @@ +#!/usr/bin/jq -f +def fixheaders: + if .t == "Header" then + .c[2][] |= (if .t == "Str" then .c |= ascii_upcase else . end) + else + . + end; + +def fixlinks: + if type == "object" then + if .t == "Link" then + if .c[2][0][0:7] == "mailto:" then . else .c[1][] end + else + map_values(fixlinks) + end + else if type == "array" then + map(fixlinks) + else + . + end + end; + +{ "pandoc-api-version" +, meta +, blocks: .blocks | map(fixheaders) | map(fixlinks) +} -- cgit v1.2.3 From 615f98315ce17751a703d4933ae690befdae82e1 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 3 Aug 2020 21:58:25 +0200 Subject: Makefile: Major refactoring, add install and uninstall targets. Honor BUILD_DOCDIR and DESTDIR variables. --- Changelog | 8 +- Makefile | 59 +++++--- fixman.jq | 26 ---- lacme-accountd.1.md | 143 ++++++++++++++++++ lacme-accountd.md | 143 ------------------ lacme.1.md | 413 ++++++++++++++++++++++++++++++++++++++++++++++++++++ lacme.md | 413 ---------------------------------------------------- pandoc2man.jq | 28 ++++ 8 files changed, 624 insertions(+), 609 deletions(-) delete mode 100755 fixman.jq create mode 100644 lacme-accountd.1.md delete mode 100644 lacme-accountd.md create mode 100644 lacme.1.md delete mode 100644 lacme.md create mode 100755 pandoc2man.jq diff --git a/Changelog b/Changelog index 2010c52..6aa31e8 100644 --- a/Changelog +++ b/Changelog @@ -1,8 +1,10 @@ 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.) + + Default listening socket for the webserver component is now + /run/lacme-www.socket. (It was previously under the legacy directory + /var/run.) + * Makefile: major refactoring, add install and uninstall targets, honor + BUILD_DOCDIR and DESTDIR variables. -- Guilhem Moulin Thu, 22 Aug 2019 00:31:35 +0200 diff --git a/Makefile b/Makefile index 0aa3046..6bfa739 100644 --- a/Makefile +++ b/Makefile @@ -1,30 +1,41 @@ -MANPAGES = lacme-accountd.1 lacme.1 +DESTDIR ?= /usr/local +BUILD_DOCDIR ?= . +MANUAL_FILES = $(addprefix $(BUILD_DOCDIR)/,$(patsubst ./%.md,%,$(wildcard ./*.[1-9].md))) -all: ${MANPAGES} +all: manual +doc: manual + +manual: $(MANUAL_FILES) # upper case the headers and remove the links -%.1: %.md - @pandoc -f markdown -t json "$<" | \ - jq -f fixman.jq | \ - pandoc -s -f json -t man+smart -o "$@" - -install: ${MANPAGES} - install -d $(DESTDIR)/etc/lacme - install -d $(DESTDIR)/etc/lacme/lacme-certs.conf.d - install -m0644 -t $(DESTDIR)/etc/lacme config/*.conf - install -m0644 -t $(DESTDIR)/etc/lacme snippets/*.conf - install -d $(DESTDIR)/usr/share/lacme - install -m0644 -t $(DESTDIR)/usr/share/lacme certs/lets-encrypt-x[1-4]-cross-signed.pem - install -d $(DESTDIR)/usr/lib/lacme - install -m0755 -t $(DESTDIR)/usr/lib/lacme client webserver - install -d $(DESTDIR)/usr/share/man/man1 - install -m0644 -t $(DESTDIR)/usr/share/man/man1 lacme-accountd.1 lacme.1 - install -d $(DESTDIR)/usr/bin - install -m0644 -t $(DESTDIR)/usr/bin lacme-accountd - install -d $(DESTDIR)/usr/sbin - install -m0644 -t $(DESTDIR)/usr/bin lacme +$(MANUAL_FILES): $(BUILD_DOCDIR)/%: ./%.md + pandoc -f markdown -t json -- "$<" | ./pandoc2man.jq | pandoc -s -f json -t man -o "$@" + +prefix ?= $(DESTDIR) +exec_prefix ?= $(prefix) +bindir ?= $(exec_prefix)/bin +sbindir ?= $(exec_prefix)/sbin +libexecdir ?= $(exec_prefix)/lib +datarootdir ?= $(prefix)/share +sysconfdir ?= $(prefix)/etc +mandir ?= $(datarootdir)/man +man1dir ?= $(mandir)/man1 + +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 $(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 -rvf -- $(sysconfdir)/lacme $(datarootdir)/lacme $(libexecdir)/lacme clean: - rm -vf ${MANPAGES} + rm -vf -- $(MANUAL_FILES) -.PHONY: all install clean +.PHONY: all doc manual install uninstall clean diff --git a/fixman.jq b/fixman.jq deleted file mode 100755 index 3524420..0000000 --- a/fixman.jq +++ /dev/null @@ -1,26 +0,0 @@ -#!/usr/bin/jq -f -def fixheaders: - if .t == "Header" then - .c[2][] |= (if .t == "Str" then .c |= ascii_upcase else . end) - else - . - end; - -def fixlinks: - if type == "object" then - if .t == "Link" then - if .c[2][0][0:7] == "mailto:" then . else .c[1][] end - else - map_values(fixlinks) - end - else if type == "array" then - map(fixlinks) - else - . - end - end; - -{ "pandoc-api-version" -, meta -, blocks: .blocks | map(fixheaders) | map(fixlinks) -} diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md new file mode 100644 index 0000000..403c68c --- /dev/null +++ b/lacme-accountd.1.md @@ -0,0 +1,143 @@ +% lacme-accountd(1) +% [Guilhem Moulin](mailto:guilhem@fripost.org) +% March 2016 + +Name +==== + +lacme-accountd - [ACME] client written with process isolation and +minimal privileges in mind (account key manager) + +Synopsis +======== + +`lacme-accountd` [`--config=FILENAME`] [`--privkey=ARG`] [`--socket=PATH`] [`--quiet`] + +Description +=========== + +`lacme-accountd` is the account key manager component of [`lacme`(1)], a +small [ACME] client written with process isolation and minimal +privileges in mind. No other [`lacme`(1)] component needs access to the +account key; in fact the account key could as well be stored on another +host or a smartcard. + +`lacme-accountd` binds to a UNIX-domain socket (specified with +`--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 +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 +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. + +Options +======= + +`--config=`*filename* + +: Use *filename* as configuration file. See the **[configuration + file](#configuration-file)** section below for the configuration + options. + +`--privkey=`*arg* + +: Specify the (private) account key to use for signing requests. + Currently supported *arg*uments are: + + * `file:`*FILE*, to specify an encrypted private key (in PEM + format); and + * `gpg:`*FILE*, to specify a [`gpg`(1)]-encrypted private key (in + PEM format). + + 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/account.key + +`--socket=`*path* + +: Use *path* as the UNIX-domain socket to bind against for signature + requests from the [ACME] client. `lacme-accountd` aborts if *path* + exists or if its parent directory is writable by other users. + +`-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-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*. + +When given on the command line, the `--privkey=`, `--socket=` and +`--quiet` options take precedence over their counterpart (without +leading `--`) in the configuration file. Valid options are: + +*privkey* + +: See `--privkey=`. This option is required when `--privkey=` is not + specified on the command line. + +*gpg* + +: For a [`gpg`(1)]-encrypted private account key, specify the binary + [`gpg`(1)] to use, as well as some default options. + Default: `gpg --quiet`. + +*socket* + +: See `--socket=`. + Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR` + environment variable is set. + +*quiet* + +: Be quiet. Possible values: `Yes`/`No`. + +Examples +======== + +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 +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: + + ~$ 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 + +See also +======== + +[`lacme`(1)], [`ssh`(1)] + +[ACME]: https://tools.ietf.org/html/rfc8555 +[`lacme`(1)]: lacme.1.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/ +[`ssh`(1)]: http://man.openbsd.org/ssh diff --git a/lacme-accountd.md b/lacme-accountd.md deleted file mode 100644 index 403c68c..0000000 --- a/lacme-accountd.md +++ /dev/null @@ -1,143 +0,0 @@ -% lacme-accountd(1) -% [Guilhem Moulin](mailto:guilhem@fripost.org) -% March 2016 - -Name -==== - -lacme-accountd - [ACME] client written with process isolation and -minimal privileges in mind (account key manager) - -Synopsis -======== - -`lacme-accountd` [`--config=FILENAME`] [`--privkey=ARG`] [`--socket=PATH`] [`--quiet`] - -Description -=========== - -`lacme-accountd` is the account key manager component of [`lacme`(1)], a -small [ACME] client written with process isolation and minimal -privileges in mind. No other [`lacme`(1)] component needs access to the -account key; in fact the account key could as well be stored on another -host or a smartcard. - -`lacme-accountd` binds to a UNIX-domain socket (specified with -`--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 -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 -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. - -Options -======= - -`--config=`*filename* - -: Use *filename* as configuration file. See the **[configuration - file](#configuration-file)** section below for the configuration - options. - -`--privkey=`*arg* - -: Specify the (private) account key to use for signing requests. - Currently supported *arg*uments are: - - * `file:`*FILE*, to specify an encrypted private key (in PEM - format); and - * `gpg:`*FILE*, to specify a [`gpg`(1)]-encrypted private key (in - PEM format). - - 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/account.key - -`--socket=`*path* - -: Use *path* as the UNIX-domain socket to bind against for signature - requests from the [ACME] client. `lacme-accountd` aborts if *path* - exists or if its parent directory is writable by other users. - -`-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-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*. - -When given on the command line, the `--privkey=`, `--socket=` and -`--quiet` options take precedence over their counterpart (without -leading `--`) in the configuration file. Valid options are: - -*privkey* - -: See `--privkey=`. This option is required when `--privkey=` is not - specified on the command line. - -*gpg* - -: For a [`gpg`(1)]-encrypted private account key, specify the binary - [`gpg`(1)] to use, as well as some default options. - Default: `gpg --quiet`. - -*socket* - -: See `--socket=`. - Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR` - environment variable is set. - -*quiet* - -: Be quiet. Possible values: `Yes`/`No`. - -Examples -======== - -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 -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: - - ~$ 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 - -See also -======== - -[`lacme`(1)], [`ssh`(1)] - -[ACME]: https://tools.ietf.org/html/rfc8555 -[`lacme`(1)]: lacme.1.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/ -[`ssh`(1)]: http://man.openbsd.org/ssh diff --git a/lacme.1.md b/lacme.1.md new file mode 100644 index 0000000..5d86f40 --- /dev/null +++ b/lacme.1.md @@ -0,0 +1,413 @@ +% 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.md b/lacme.md deleted file mode 100644 index 5d86f40..0000000 --- a/lacme.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/pandoc2man.jq b/pandoc2man.jq new file mode 100755 index 0000000..69802a5 --- /dev/null +++ b/pandoc2man.jq @@ -0,0 +1,28 @@ +#!/usr/bin/jq -f + +def fixheaders: + if .t == "Header" then + .c[2][] |= (if .t == "Str" then .c |= ascii_upcase else . end) + else + . + end; + +def fixlinks: + if type == "object" then + if .t == "Link" then + if .c[2][0][0:7] == "mailto:" then . else .c[1][] end + else + map_values(fixlinks) + end + else if type == "array" then + map(fixlinks) + else + . + end + end; + +{ + "pandoc-api-version" + , meta + , blocks: .blocks | map(fixheaders | fixlinks) +} -- 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 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(-) 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 d9946b9ab478026defed364485d970b4041e1a2a Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 3 Aug 2020 22:39:29 +0200 Subject: Adapt Apache2 snippet to Apache2 2.4. --- Changelog | 1 + snippets/apache2.conf | 3 +-- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Changelog b/Changelog index 45e7a99..95d17bf 100644 --- a/Changelog +++ b/Changelog @@ -3,6 +3,7 @@ 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. diff --git a/snippets/apache2.conf b/snippets/apache2.conf index e1d56a9..c42a9fb 100644 --- a/snippets/apache2.conf +++ b/snippets/apache2.conf @@ -6,7 +6,6 @@ ProxyPass unix:///run/lacme-www.socket|http://localhost/.well-known/acme-challenge/ - Order allow,deny - Allow from all + Require all granted -- 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(-) 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(-) 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 From 89c94e697545c3333277194dfa862daede14a5e8 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Tue, 4 Aug 2020 01:27:09 +0200 Subject: Upgrade links to secure HTTP. --- COPYING | 8 ++++---- client | 2 +- lacme | 2 +- lacme-accountd | 2 +- lacme-accountd.1.md | 6 +++--- lacme.8.md | 2 +- webserver | 2 +- 7 files changed, 12 insertions(+), 12 deletions(-) diff --git a/COPYING b/COPYING index 94a9ed0..e600086 100644 --- a/COPYING +++ b/COPYING @@ -1,7 +1,7 @@ GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 - Copyright (C) 2007 Free Software Foundation, Inc. + Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @@ -645,7 +645,7 @@ the "copyright" line and a pointer to where the full notice is found. GNU General Public License for more details. You should have received a copy of the GNU General Public License - along with this program. If not, see . + along with this program. If not, see . Also add information on how to contact you by electronic and paper mail. @@ -664,11 +664,11 @@ might be different; for a GUI interface, you would use an "about box". You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see -. +. The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read -. +. diff --git a/client b/client index 2eebbf0..b59c013 100755 --- a/client +++ b/client @@ -15,7 +15,7 @@ # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License -# along with this program. If not, see . +# along with this program. If not, see . #---------------------------------------------------------------------- use v5.14.2; diff --git a/lacme b/lacme index 8701047..1ca4a38 100755 --- a/lacme +++ b/lacme @@ -15,7 +15,7 @@ # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License -# along with this program. If not, see . +# along with this program. If not, see . #---------------------------------------------------------------------- use v5.14.2; diff --git a/lacme-accountd b/lacme-accountd index 89774c2..af64168 100755 --- a/lacme-accountd +++ b/lacme-accountd @@ -16,7 +16,7 @@ # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License -# along with this program. If not, see . +# along with this program. If not, see . #---------------------------------------------------------------------- use v5.14.2; diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 77cc8ed..6cf9ea8 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -137,7 +137,7 @@ See also [ACME]: https://tools.ietf.org/html/rfc8555 [`lacme`(8)]: lacme.8.html -[`signal`(7)]: http://linux.die.net/man/7/signal +[`signal`(7)]: https://linux.die.net/man/7/signal [`gpg`(1)]: https://www.gnupg.org/documentation/manpage.en.html -[OpenSSH]: http://www.openssh.com/ -[`ssh`(1)]: http://man.openbsd.org/ssh +[OpenSSH]: https://www.openssh.com/ +[`ssh`(1)]: https://man.openbsd.org/ssh diff --git a/lacme.8.md b/lacme.8.md index 8f8eb41..90fd3cf 100644 --- a/lacme.8.md +++ b/lacme.8.md @@ -407,6 +407,6 @@ See also [ACME]: https://tools.ietf.org/html/rfc8555 [`lacme-accountd`(1)]: lacme-accountd.1.html -[`iptables`(8)]: http://linux.die.net/man/8/iptables +[`iptables`(8)]: https://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/webserver b/webserver index 584f0bb..c16737f 100755 --- a/webserver +++ b/webserver @@ -16,7 +16,7 @@ # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License -# along with this program. If not, see . +# along with this program. If not, see . #---------------------------------------------------------------------- use v5.14.2; -- cgit v1.2.3 From 49c14fb9faf9aedf1f6c22bff9526ba980d0f23b Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Tue, 4 Aug 2020 01:40:25 +0200 Subject: New release 0.6.1 --- Changelog | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Changelog b/Changelog index 1e54354..b71cce7 100644 --- a/Changelog +++ b/Changelog @@ -1,4 +1,4 @@ -lacme (0.7) UNRELEASED; +lacme (0.6.1) upstream; + Adapt Apache2 snippet to Apache2 2.4. + Ignore [accountd] section from lacme.conf when the --socket option is @@ -10,7 +10,7 @@ lacme (0.7) UNRELEASED; * 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 + -- Guilhem Moulin Tue, 04 Aug 2020 01:39:47 +0200 lacme (0.6) upstream; -- cgit v1.2.3