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. --- lacme-accountd.1.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 lacme-accountd.1.md (limited to 'lacme-accountd.1.md') 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 -- 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. --- lacme-accountd.1.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'lacme-accountd.1.md') 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/ -- 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. --- lacme-accountd.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lacme-accountd.1.md') 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 -- 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. --- lacme-accountd.1.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'lacme-accountd.1.md') 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 -- cgit v1.2.3