summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorDaniel Kahn Gillmor <dkg@fifthhorseman.net>2016-10-27 20:19:18 +0200
committerWerner Koch <wk@gnupg.org>2016-11-11 08:44:51 +0100
commit57e95f5413e21cfcb957af2346b292686a5647b7 (patch)
tree1ed7f3550d599207beb3e0785f4ed4bcfe5cfa1e /doc
parentagent: Clean up comments. (diff)
downloadgnupg2-57e95f5413e21cfcb957af2346b292686a5647b7.tar.xz
gnupg2-57e95f5413e21cfcb957af2346b292686a5647b7.zip
doc: Include config examples for socket-activated user services.
-- These configuration files and instructions enable clean and simple daemon supervision on machines that run systemd. Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net> - Removed the detailed ChangeLog entry because that is not needed for doc changes. - Added an entry to doc/examples/README. Signed-off-by: Werner Koch <wk@gnupg.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am9
-rw-r--r--doc/examples/README4
-rw-r--r--doc/examples/systemd-user/README66
-rw-r--r--doc/examples/systemd-user/dirmngr.service10
-rw-r--r--doc/examples/systemd-user/dirmngr.socket11
-rw-r--r--doc/examples/systemd-user/gpg-agent-browser.socket13
-rw-r--r--doc/examples/systemd-user/gpg-agent-extra.socket13
-rw-r--r--doc/examples/systemd-user/gpg-agent-ssh.socket13
-rw-r--r--doc/examples/systemd-user/gpg-agent.service10
-rw-r--r--doc/examples/systemd-user/gpg-agent.socket12
10 files changed, 159 insertions, 2 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 0791dbcf1..53cd639dd 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -21,7 +21,14 @@ AM_CPPFLAGS =
include $(top_srcdir)/am/cmacros.am
-examples = examples/README examples/scd-event examples/trustlist.txt \
+examples = examples/README examples/scd-event examples/trustlist.txt \
+ examples/systemd-user/README \
+ examples/systemd-user/dirmngr.service \
+ examples/systemd-user/dirmngr.socket \
+ examples/systemd-user/gpg-agent.service \
+ examples/systemd-user/gpg-agent.socket \
+ examples/systemd-user/gpg-agent-ssh.socket \
+ examples/systemd-user/gpg-agent-extra.socket \
examples/gpgconf.conf examples/pwpattern.list
helpfiles = help.txt help.be.txt help.ca.txt help.cs.txt \
diff --git a/doc/examples/README b/doc/examples/README
index 344482283..77ee80741 100644
--- a/doc/examples/README
+++ b/doc/examples/README
@@ -3,7 +3,9 @@ Files in this directory:
scd-event A handler script used with scdaemon
-trustlist.txt A list of trustworthy root certificates
+trustlist.txt A list of trustworthy root certificates
(Please check yourself whether you actually trust them)
gpgconf.conf A sample configuration file for gpgconf.
+
+systemd-user Sample files for a Linux-only init system.
diff --git a/doc/examples/systemd-user/README b/doc/examples/systemd-user/README
new file mode 100644
index 000000000..43122f568
--- /dev/null
+++ b/doc/examples/systemd-user/README
@@ -0,0 +1,66 @@
+Socket-activated dirmngr and gpg-agent with systemd
+===================================================
+
+When used on a GNU/Linux system supervised by systemd, you can ensure
+that the GnuPG daemons dirmngr and gpg-agent are launched
+automatically the first time they're needed, and shut down cleanly at
+session logout. This is done by enabling user services via
+socket-activation.
+
+System distributors
+-------------------
+
+The *.service and *.socket files (from this directory) should be
+placed in /usr/lib/systemd/user/ alongside other user-session services
+and sockets.
+
+To enable socket-activated dirmngr for all accounts on the system,
+use:
+
+ systemctl --user --global enable dirmngr.socket
+
+To enable socket-activated gpg-agent for all accounts on the system,
+use:
+
+ systemctl --user --global enable gpg-agent.socket
+
+Additionally, you can enable socket-activated gpg-agent ssh-agent
+emulation for all accounts on the system with:
+
+ systemctl --user --global enable gpg-agent-ssh.socket
+
+You can also enable restricted ("--extra-socket"-style) gpg-agent
+sockets for all accounts on the system with:
+
+ systemctl --user --global enable gpg-agent-extra.socket
+
+Individual users
+----------------
+
+A user on a system with systemd where this has not been installed
+system-wide can place these files in ~/.config/systemd/user/ to make
+them available.
+
+If a given service isn't installed system-wide, or if it's installed
+system-wide but not globally enabled, individual users will still need
+to enable them. For example, to enable socket-activated dirmngr for
+all future sessions:
+
+ systemctl --user enable dirmngr.socket
+
+To enable socket-activated gpg-agent with ssh support, do:
+
+ systemctl --user enable gpg-agent.socket gpg-agent-ssh.socket
+
+These changes won't take effect until your next login after you've
+fully logged out (be sure to terminate any running daemons before
+logging out).
+
+If you'd rather try a socket-activated GnuPG daemon in an
+already-running session without logging out (with or without enabling
+it for all future sessions), kill any existing daemon and start the
+user socket directly. For example, to set up socket-activated dirmgnr
+in the current session:
+
+ gpgconf --kill dirmngr
+ systemctl --user start dirmngr.socket
diff --git a/doc/examples/systemd-user/dirmngr.service b/doc/examples/systemd-user/dirmngr.service
new file mode 100644
index 000000000..c79dfc58a
--- /dev/null
+++ b/doc/examples/systemd-user/dirmngr.service
@@ -0,0 +1,10 @@
+[Unit]
+Description=GnuPG network certificate management daemon
+Documentation=man:dirmngr(8)
+Requires=dirmngr.socket
+After=dirmngr.socket
+## This is a socket-activated service:
+RefuseManualStart=true
+
+[Service]
+ExecStart=/usr/bin/dirmngr --supervised
diff --git a/doc/examples/systemd-user/dirmngr.socket b/doc/examples/systemd-user/dirmngr.socket
new file mode 100644
index 000000000..ebabf896a
--- /dev/null
+++ b/doc/examples/systemd-user/dirmngr.socket
@@ -0,0 +1,11 @@
+[Unit]
+Description=GnuPG network certificate management daemon
+Documentation=man:dirmngr(8)
+
+[Socket]
+ListenStream=%t/gnupg/S.dirmngr
+SocketMode=0600
+DirectoryMode=0700
+
+[Install]
+WantedBy=sockets.target
diff --git a/doc/examples/systemd-user/gpg-agent-browser.socket b/doc/examples/systemd-user/gpg-agent-browser.socket
new file mode 100644
index 000000000..bc8d344e1
--- /dev/null
+++ b/doc/examples/systemd-user/gpg-agent-browser.socket
@@ -0,0 +1,13 @@
+[Unit]
+Description=GnuPG cryptographic agent and passphrase cache (access for web browsers)
+Documentation=man:gpg-agent(1)
+
+[Socket]
+ListenStream=%t/gnupg/S.gpg-agent.browser
+FileDescriptorName=browser
+Service=gpg-agent.service
+SocketMode=0600
+DirectoryMode=0700
+
+[Install]
+WantedBy=sockets.target
diff --git a/doc/examples/systemd-user/gpg-agent-extra.socket b/doc/examples/systemd-user/gpg-agent-extra.socket
new file mode 100644
index 000000000..5b87d09df
--- /dev/null
+++ b/doc/examples/systemd-user/gpg-agent-extra.socket
@@ -0,0 +1,13 @@
+[Unit]
+Description=GnuPG cryptographic agent and passphrase cache (restricted)
+Documentation=man:gpg-agent(1)
+
+[Socket]
+ListenStream=%t/gnupg/S.gpg-agent.extra
+FileDescriptorName=extra
+Service=gpg-agent.service
+SocketMode=0600
+DirectoryMode=0700
+
+[Install]
+WantedBy=sockets.target
diff --git a/doc/examples/systemd-user/gpg-agent-ssh.socket b/doc/examples/systemd-user/gpg-agent-ssh.socket
new file mode 100644
index 000000000..798c1d967
--- /dev/null
+++ b/doc/examples/systemd-user/gpg-agent-ssh.socket
@@ -0,0 +1,13 @@
+[Unit]
+Description=GnuPG cryptographic agent (ssh-agent emulation)
+Documentation=man:gpg-agent(1) man:ssh-add(1) man:ssh-agent(1) man:ssh(1)
+
+[Socket]
+ListenStream=%t/gnupg/S.gpg-agent.ssh
+FileDescriptorName=ssh
+Service=gpg-agent.service
+SocketMode=0600
+DirectoryMode=0700
+
+[Install]
+WantedBy=sockets.target
diff --git a/doc/examples/systemd-user/gpg-agent.service b/doc/examples/systemd-user/gpg-agent.service
new file mode 100644
index 000000000..9ab922081
--- /dev/null
+++ b/doc/examples/systemd-user/gpg-agent.service
@@ -0,0 +1,10 @@
+[Unit]
+Description=GnuPG cryptographic agent and passphrase cache
+Documentation=man:gpg-agent(1)
+Requires=gpg-agent.socket
+After=gpg-agent.socket
+## This is a socket-activated service:
+RefuseManualStart=true
+
+[Service]
+ExecStart=/usr/bin/gpg-agent --supervised
diff --git a/doc/examples/systemd-user/gpg-agent.socket b/doc/examples/systemd-user/gpg-agent.socket
new file mode 100644
index 000000000..4257c2c80
--- /dev/null
+++ b/doc/examples/systemd-user/gpg-agent.socket
@@ -0,0 +1,12 @@
+[Unit]
+Description=GnuPG cryptographic agent and passphrase cache
+Documentation=man:gpg-agent(1)
+
+[Socket]
+ListenStream=%t/gnupg/S.gpg-agent
+FileDescriptorName=std
+SocketMode=0600
+DirectoryMode=0700
+
+[Install]
+WantedBy=sockets.target