Linux build docs

systemd.md

@@ -5,38 +5,84 @@ provide a yubikey-agent as a package.
 
 Refer to [the README](README) for a list of distributions providing packages.
 
-First, install Go and the [`piv-go` dependencies](https://github.com/go-piv/piv-go#installation), build `yubikey-agent` and place it in `$PATH`.
+## Dependencies
 
-```text
-$ git clone https://filippo.io/yubikey-agent && cd yubikey-agent
-$ go build && sudo cp yubikey-agent /usr/local/bin/
+First, [install Go](https://golang.org/doc/install) and all [dependencies for`piv-go`](https://github.com/go-piv/piv-go#installation).
+Make sure you have a `pinentry` program that works for you, either in the terminal-based or graphical, in `$PATH`.
+
+### Packages for Ubuntu 20.04
+
+`piv-go` requires `libpcsclite-dev` to build and `yubikey-agent` needs `pcscd` to run.
+
+```sh
+sudo apt install -y pcscd libpcsclite-dev
 ```
 
-Make sure you have a `pinentry` program that works for you (terminal-based or graphical) in `$PATH`.
+### `pcscd.socket`
 
-Use `yubikey-agent -setup` to create a new key on the YubiKey.
+Make sure `pcsdc.socket` is active before using `yubikey-agent`.
 
-```text
-$ yubikey-agent -setup
+```sh
+$ systemctl is-active pcscd.socket
+active
 ```
 
-Then, create a systemd user service at `~/.config/systemd/user/yubikey-agent.service`
-with the contents of [yubikey-agent.service](contrib/systemd/user/yubikey-agent.service).
+If `pcscd.socket` is not active, you need to start it manually:
+
+```sh
+sudo systemctl enable --now pcscd.socket
+```
 
-Depending on your distribution (`systemd <=239` or no user namespace support),
-you might need to edit the `ExecStart=` line and some of the sandboxing
-options.
+## Building
 
-Refresh systemd, make sure that the PC/SC daemon is available, and start the yubikey-agent.
+Build the `yubikey-agent` and place it somewhere on your `$PATH`, such as `/usr/local/bin/`.
 
-```text
-$ systemctl daemon-reload --user
-$ sudo systemctl enable --now pcscd.socket
-$ systemctl --user enable --now yubikey-agent
+```sh
+git clone https://filippo.io/yubikey-agent
+cd yubikey-agent
+go build
+sudo cp yubikey-agent /usr/local/bin/
 ```
 
-Finally, add the following line to your shell profile and restart it.
+## Creating your first key
 
+After all dependencies are installed and `yubikey-agent` is built, you are ready to start.
+Use `yubikey-agent -setup` to create a new key on your YubiKey.
+
+```sh
+yubikey-agent -setup
 ```
+
+## systemd service
+
+Now we will create a systemd user service for `~/.config/systemd/user/yubikey-agent.service`
+with the contents of [yubikey-agent.service](contrib/systemd/user/yubikey-agent.service).
+
+```sh
+mkdir -p ~/.config/systemd/user/
+cp contrib/systemd/user/yubikey-agent.service ~/.config/systemd/user/yubikey-agent.service
+```
+
+**NB:** _Depending on your distribution (`systemd <=239` or no user namespace support), you might need to edit the `ExecStart=` line and some of the sandboxing options._
+
+Refresh the systemd daemon and start the `yubikey-agent` service.
+
+```sh
+systemctl daemon-reload --user
+systemctl --user enable --now yubikey-agent
+```
+
+To integrate `yubikey-agent` with SSH, set `SSH_AUTH_SOCK` to `yubikey-agent`'s socket. 
+Add the following to your shell profile and restart your shell.
+
+```sh
 export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/yubikey-agent/yubikey-agent.sock"
 ```
+
+### Fish shell
+
+If you use Fish shell, then add the following to `~/.config/fish/config.fish`
+
+```sh
+set SSH_AUTH_SOCK "$XDG_RUNTIME_DIR/yubikey-agent/yubikey-agent.sock"
+```