stow/oh-my-zsh/.oh-my-zsh/plugins/ssh-agent/README.md

   1 # ssh-agent plugin
   2
   3 This plugin starts automatically `ssh-agent` to set up and load whichever
   4 credentials you want for ssh connections.
   5
   6 To enable it, add `ssh-agent` to your plugins:
   7
   8 ```zsh
   9 plugins=(... ssh-agent)
  10 ```
  11
  12 ## Settings
  13
  14 **IMPORTANT: put these settings _before_ the line that sources oh-my-zsh**
  15
  16 ### `agent-forwarding`
  17
  18 To enable **agent forwarding support** add the following to your zshrc file:
  19
  20 ```zsh
  21 zstyle :omz:plugins:ssh-agent agent-forwarding yes
  22 ```
  23
  24 ### `helper`
  25
  26 To set an **external helper** to ask for the passwords and possibly store
  27 them in the system keychain use the `helper` style. For example:
  28
  29 ```zsh
  30 zstyle :omz:plugins:ssh-agent helper ksshaskpass
  31 ```
  32
  33 ### `identities`
  34
  35 To **load multiple identities** use the `identities` style (**this has no effect
  36 if the `lazy` setting is enabled**). For example:
  37
  38 ```zsh
  39 zstyle :omz:plugins:ssh-agent identities id_rsa id_rsa2 id_github
  40 ```
  41
  42 **NOTE:** the identities may be an absolute path if they are somewhere other than
  43 `~/.ssh`. For example:
  44
  45 ```zsh
  46 zstyle :omz:plugins:ssh-agent identities ~/.config/ssh/id_rsa ~/.config/ssh/id_rsa2 ~/.config/ssh/id_github
  47 # which can be simplified to
  48 zstyle :omz:plugins:ssh-agent identities ~/.config/ssh/{id_rsa,id_rsa2,id_github}
  49 ```
  50
  51 ### `lazy`
  52
  53 To **NOT load any identities on start** use the `lazy` setting. This is particularly
  54 useful when combined with the `AddKeysToAgent` setting (available since OpenSSH 7.2),
  55 since it allows to enter the password only on first use. _NOTE: you can know your
  56 OpenSSH version with `ssh -V`._
  57
  58 ```zsh
  59 zstyle :omz:plugins:ssh-agent lazy yes
  60 ```
  61
  62 You can enable `AddKeysToAgent` by passing `-o AddKeysToAgent=yes` to the `ssh` command,
  63 or by adding `AddKeysToAgent yes` to your `~/.ssh/config` file [1].
  64 See the [OpenSSH 7.2 Release Notes](http://www.openssh.com/txt/release-7.2).
  65
  66 ### `lifetime`
  67
  68 To **set the maximum lifetime of the identities**, use the `lifetime` style.
  69 The lifetime may be specified in seconds or as described in sshd_config(5)
  70 (see _TIME FORMATS_). If left unspecified, the default lifetime is forever.
  71
  72 ```zsh
  73 zstyle :omz:plugins:ssh-agent lifetime 4h
  74 ```
  75
  76 ### `quiet`
  77
  78 To silence the plugin, use the following setting:
  79
  80 ```zsh
  81 zstyle :omz:plugins:ssh-agent quiet yes
  82 ```
  83
  84 ### `ssh-add-args`
  85
  86 To **pass arguments to the `ssh-add` command** that adds the identities on startup,
  87 use the `ssh-add-args` setting. You can pass multiple arguments separated by spaces:
  88
  89 ```zsh
  90 zstyle :omz:plugins:ssh-agent ssh-add-args -K -c -a /run/user/1000/ssh-auth
  91 ```
  92
  93 These will then be passed the the `ssh-add` call as if written directly. The example
  94 above will turn into:
  95
  96 ```zsh
  97 ssh-add -K -c -a /run/user/1000/ssh-auth <identities>
  98 ```
  99
 100 For valid `ssh-add` arguments run `ssh-add --help` or `man ssh-add`.
 101
 102 ## Credits
 103
 104 Based on code from Joseph M. Reagle: https://www.cygwin.com/ml/cygwin/2001-06/msg00537.html
 105
 106 Agent-forwarding support based on ideas from Florent Thoumie and Jonas Pfenniger