Merge pull request #81 from smlx/document-macos

Document macOS

.goreleaser.macos-latest.yml

@@ -1,6 +1,6 @@
 archives:
 - files:
-  - deploy/*
+  - deploy/launchd
   - LICENSE
   - README.md
 builds:

.goreleaser.ubuntu-latest.yml

@@ -1,6 +1,6 @@
 archives:
 - files:
-  - deploy/*
+  - deploy/systemd
   - LICENSE
   - README.md
 builds:

README.md

@@ -66,9 +66,7 @@ If you have tested another device with `piv-agent` successfully, please send a P
 
 ### Platform support
 
-Currently tested on Linux with `systemd`.
-
-If you have a Mac, I'd love to add support for `launchd` socket activation. See issue https://github.com/smlx/piv-agent/issues/12.
+Currently tested on Linux with `systemd` and macOS with `launchd`.
 
 ### Protocol / Encryption Algorithm support
 

deploy/launchd/com.github.smlx.piv-agent.plist

@@ -4,6 +4,10 @@
 <dict>
 	<key>Label</key>
 	<string>com.github.smlx.piv-agent</string>
+	<key>StandardErrorPath</key>
+	<string>/tmp/piv-agent.err</string>
+	<key>StandardOutPath</key>
+	<string>/tmp/piv-agent.out</string>
 	<key>ProgramArguments</key>
 	<array>
 		<string>/usr/local/bin/piv-agent</string>

docs/content/en/docs/faq.md

@@ -17,14 +17,28 @@ The `pkill` is required because `gpg` may be configured to automatically start `
 systemctl --user stop gpg-agent.socket gpg-agent.service piv-agent.socket piv-agent.service; pkill gpg-agent
 ```
 
-Start `piv-agent`:
+Start `piv-agent` sockets:
 
 ```
 systemctl --user start piv-agent.socket
 ```
 
-Or start `gpg-agent`:
+Or start `gpg-agent` socket:
 
 ```
 systemctl --user start gpg-agent.socket
 ```
+
+### macOS (launchd)
+
+Stop `piv-agent`:
+
+```
+launchctl disable gui/$UID/com.github.smlx.piv-agent
+```
+
+Start `piv-agent` sockets:
+
+```
+launchctl enable gui/$UID/com.github.smlx.piv-agent
+```

docs/content/en/docs/install.md

@@ -23,9 +23,10 @@ sudo apt install libpcsclite1
 
 ## Install piv-agent
 
+Download the latest [release](https://github.com/smlx/piv-agent/releases), and extract it to a temporary location.
+
 ### Linux
 
-Download the latest [release](https://github.com/smlx/piv-agent/releases), and extract it to a temporary location.
 Copy the `piv-agent` binary into your `$PATH`, and the `systemd` unit files to the correct location:
 
 ```
@@ -36,13 +37,58 @@ systemctl --user daemon-reload
 
 ### macOS
 
-Similarly to Linux, copy `piv-agent` to `/usr/local/bin/`, edit the `.plist` file with the correct home directory, and drop it in `~/Library/LaunchAgents`.
+`piv-agent` requires [Homebrew](https://brew.sh) in order to install dependencies.
+So install that first.
+
+Copy the `piv-agent` binary into your `$PATH`, and the `launchd` `.plist` files to the correct location:
+
+```
+sudo cp piv-agent /usr/local/bin/
+cp deploy/launchd/com.github.smlx.piv-agent.plist ~/Library/LaunchAgents/
+```
+
+From what I can tell `.plist` files only support absolute file paths, even for user agents.
+So edit `~/Library/LaunchAgents/com.github.smlx.piv-agent.plist` and update the path to `$HOME/.gnupg/S.gpg-agent`.
+
+If you plan to use `gpg`, install it via `brew install gnupg`.
+If not, you still need a `pinentry`, so `brew install pinentry`.
+
+If `~/.gnupg` doesn't already exist, create it.
+
+```
+mkdir ~/.gnupg
+chmod 700 ~/.gnupg
+```
+
+Then enable the service:
+
+```
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.github.smlx.piv-agent.plist
+launchctl enable gui/$UID/com.github.smlx.piv-agent
+```
+
+A socket should appear in `~/.gnupg/S.gpg-agent`.
+
+Disable `ssh-agent` to avoid `SSH_AUTH_SOCK` environment variable conflict.
+
+```
+launchctl disable gui/$UID/com.openssh.ssh-agent
+```
+
+Set `launchd` user path to include `/usr/local/bin/` for `pinentry`.
+
+```
+sudo launchctl config user path $PATH
+```
+
+Reboot and log back in.
 
 ### Socket activation
 
-`piv-agent` relies on [socket activation](https://0pointer.de/blog/projects/socket-activated-containers.html), and is currently only tested with `systemd`.
+`piv-agent` relies on [socket activation](https://0pointer.de/blog/projects/socket-activated-containers.html), and is currently tested with `systemd` on Linux, and `launchd` on macOS.
 It doesn't listen to any sockets directly, and instead requires the init system to pass file descriptors to the `piv-agent` process after it is running.
 This requirement makes it possible to exit the process when not in use.
 
-`ssh-agent` and `gpg-agent` functionality are enabled by default in the systemd and launchd configuration files.
-On Linux, index of the sockets listed in `piv-agent.socket` are indicated by the arguments to `--agent-types`.
+`ssh-agent` and `gpg-agent` functionality are enabled by default in the `systemd` and `launchd` configuration files.
+
+On Linux, the index of the sockets listed in `piv-agent.socket` are indicated by the arguments to `--agent-types`.