howto/cumin.md

@@ -76,7 +76,7 @@ order to verify if the tunnel port is open so, install it with:
 
 To get the automatic tunnel, we'll create a systemd unit that can bring the
 tunnel up for us. Create the file
-`~/.config/systemd/user/puppetdb-tunnel.service`, making sure to create the
+`~/.config/systemd/user/puppetdb-tunnel@.service`, making sure to create the
 missing directories in the path:
 
 ```systemd
@@ -85,66 +85,68 @@ Description=Setup port forward to puppetdb
 After=network.target
 
 [Service]
-ExecStart=/usr/bin/ssh -nNT -o ExitOnForwardFailure=yes -o BatchMode=yes -L 8080:localhost:8080 puppetdb-01.torproject.org
-Environment=SSH_AUTH_SOCK=/run/user/1003/gnupg/S.gpg-agent.ssh
+ExecStart=-/usr/bin/ssh -W localhost:8080 puppetdb-01.torproject.org
+StandardInput=socket
+StandardError=journal
+Environment=SSH_AUTH_SOCK=/run/user/1000/gnupg/S.gpg-agent.ssh
 ```
 
 In the file above, change the path given to `SSH_AUTH_SOCK` so that it matches
 your user ID. This environment variable is necessary for the ssh command to be
 able to request the key from your yubi key.
 
+And you'll need the following for socket activation, in
+`~/.config/systemd/user/puppetdb-tunnel.socket`:
+
+```systemd
+[Unit]
+Description=Socket activation for PuppetDB tunnel
+After=network.target
+
+[Socket]
+ListenStream=127.0.0.1:8080
+Accept=yes
+
+[Install]
+WantedBy=graphical-session.target
+```
+
 With this in place, make sure that systemd has loaded this unit file:
 
-    systemd --user daemon-reload
-
-Note: if you already have a line `LocalForward 8080 127.0.0.1:8080` under a
-block for host puppetdb-01.torproject.org in your ssh configuration, you can
-safely drop the `-L` argument in the ssh command in the systemd unit above.
-
-The last missing piece is to create something that'll intercept `cumin` commands
-and check whether your tunnel to puppetdb is currently listening and if not,
-start the tunnel before handing your arguments to the actual `cumin` command.
-
-Somewhere in your `~/.bashrc`, add the following:
-
-    # All output for starting the tunnel is on stderr so it can be filtered out if
-    # needed.
-    function cumin () {
-      if ! nc -z localhost 8080 2>/dev/null; then
-        echo -n "NOTE: starting tunnel with puppetdb, watch out for your token being sollicited: " >&2
-        systemctl --user start puppetdb-tunnel.service
-        for i in {0..60}; do
-          if nc -z localhost 8080 2>/dev/null; then
-            # Clear line from the pesky wait dots
-            echo "" >&2
-            break
-          else
-            if [[ $i -eq 60 ]]; then
-              echo "x" >&2
-              echo "error: tunnel not started correctly, bailing out" >&2
-              return 1
-            fi
-            echo -n "." >&2
-            sleep 1
-          fi
-        done
-      elif ! curl -s http://localhost:8080/pdb/meta/v1/version | jq .version >/dev/null 2>&1; then
-        echo "ERR: localhost:8080 is listening but it does not seem to be used by puppetdb." >&2
-        return 1
-      fi
-      # Now hand off the arguments to actually run cumin
-      /usr/bin/cumin --config=~/.config/cumin/config.yaml "$@"
-    }
-
-With this set, now when you call `cumin [...]`, an ssh tunnel will be brought
-up if needed, which could require you to confirm the ssh connection on your
-token so keep an eye out for that.
-
-The tunnel will keep running in the background so subsequent calls to cumin
-will just go through immediately. If you ever want to tear down the ssh tunnel,
-you can do so with this:
-
-    systemctl --user stop puppetdb-tunnel.service
+    systemctl --user daemon-reload
+    systemctl --user enable --now puppetdb-tunnel.socket
+
+Note: if you already have a line like `LocalForward 8080
+127.0.0.1:8080` under a block for host `puppetdb-01.torproject.org` in
+your ssh configuration, it will cause problem as `ssh` will try to
+bind to the same socket as systemd. That configuration should be
+removed.
+
+The above can be tested by hand without creating any systemd
+configuration with:
+
+    systemd-socket-activate -a --inetd  -E SSH_AUTH_SOCK=/run/user/1000/gnupg/S.gpg-agent.ssh -l 127.0.0.1:8080 \
+        ssh -o BatchMode=yes -W localhost:8080 puppetdb-01.torproject.org
+
+The tunnel will be shutdown as soon as it's done, and fired up as
+needed. You *will* need to tap your YubiKey, as normal, to get it to
+work of course.
+
+This is different from a `-N` "daemon" configuration where the daemon
+stays around for a long-lived connection. This is the only way we've
+found to make it work with socket activation. The alternative to that
+is to use a "normal" service that is *not* socket activated and start
+it by hand:
+
+```systemd
+[Unit]
+Description=Setup port forward to puppetdb
+After=network.target
+
+[Service]
+ExecStart=/usr/bin/ssh -nNT -o ExitOnForwardFailure=yes -o BatchMode=yes -L 8080:localhost:8080 puppetdb-01.torproject.org
+Environment=SSH_AUTH_SOCK=/run/user/1003/gnupg/S.gpg-agent.ssh
+```
 
 ### Virtualenv / pip