1 files changed, 58 insertions, 2 deletions
diff --git a/plugins/ssh-agent/README.md b/plugins/ssh-agent/README.md
index 0b96d9bb5..1d6914ec6 100644
--- a/plugins/ssh-agent/README.md
+++ b/plugins/ssh-agent/README.md
@@ -9,7 +9,7 @@ To enable it, add `ssh-agent` to your plugins:
 plugins=(... ssh-agent)
 ```
 
-## Instructions
+## Settings
 
 **IMPORTANT: put these settings _before_ the line that sources oh-my-zsh**
 
@@ -19,12 +19,41 @@ To enable **agent forwarding support** add the following to your zshrc file:
 zstyle :omz:plugins:ssh-agent agent-forwarding on
 ```
 
-To **load multiple identities** use the `identities` style, For example:
+----
+
+To **NOT load any identities on start** use the `lazy` setting. This is particularly
+useful when combined with the `AddKeysToAgent` setting (available since OpenSSH 7.2),
+since it allows to enter the password only on first use. _NOTE: you can know your
+OpenSSH version with `ssh -V`._
+
+```zsh
+zstyle :omz:plugins:ssh-agent lazy yes
+```
+
+You can enable `AddKeysToAgent` by passing `-o AddKeysToAgent=yes` to the `ssh` command,
+or by adding `AddKeysToAgent yes` to your `~/.ssh/config` file [1].
+See the [OpenSSH 7.2 Release Notes](http://www.openssh.com/txt/release-7.2).
+
+----
+
+To **load multiple identities** use the `identities` style (**this has no effect
+if the `lazy` setting is enabled**). For example:
 
 ```zsh
 zstyle :omz:plugins:ssh-agent identities id_rsa id_rsa2 id_github
 ```
 
+**NOTE:** the identities may be an absolute path if they are somewhere other than
+`~/.ssh`. For example:
+
+```zsh
+zstyle :omz:plugins:ssh-agent identities ~/.config/ssh/id_rsa ~/.config/ssh/id_rsa2 ~/.config/ssh/id_github
+# which can be simplified to
+zstyle :omz:plugins:ssh-agent identities ~/.config/ssh/{id_rsa,id_rsa2,id_github}
+```
+
+----
+
 To **set the maximum lifetime of the identities**, use the `lifetime` style.
 The lifetime may be specified in seconds or as described in sshd_config(5)
 (see _TIME FORMATS_). If left unspecified, the default lifetime is forever.
@@ -33,6 +62,33 @@ The lifetime may be specified in seconds or as described in sshd_config(5)
 zstyle :omz:plugins:ssh-agent lifetime 4h
 ```
 
+----
+
+To **pass arguments to the `ssh-add` command** that adds the identities on startup,
+use the `ssh-add-args` setting. You can pass multiple arguments separated by spaces:
+
+```zsh
+zstyle :omz:plugins:ssh-agent ssh-add-args -K -c -a /run/user/1000/ssh-auth
+```
+
+These will then be passed the the `ssh-add` call as if written directly. The example
+above will turn into:
+
+```zsh
+ssh-add -K -c -a /run/user/1000/ssh-auth <identities>
+```
+
+For valid `ssh-add` arguments run `ssh-add --help` or `man ssh-add`.
+
+----
+
+To set an **external helper** to ask for the passwords and possibly store
+them in the system keychain use the `helper` style. For example:
+
+```zsh
+zstyle :omz:plugins:ssh-agent helper ksshaskpass
+```
+
 ## Credits
 
 Based on code from Joseph M. Reagle: https://www.cygwin.com/ml/cygwin/2001-06/msg00537.html