FreeBSD Manual Pages
keychain(1) https://github.com/danielrobbins/keychain keychain(1) NAME keychain - Manager for ssh-agent, gpg-agent and private keys. Compatible with POSIX systems. SYNOPSIS keychain [ -hklQqV ] [ --clear --confhost --confallhosts --debug --ex- tended --gpg2 --help --ignore-missing --list --noask --nocolor --nogui --noinherit --nolock --quick --quiet --ssh-allow-forwarded --ssh-allow-gpg --ssh-rm --ssh-spawn-gpg --systemd --version ] [ --ssh-agent-socket path ] [ --dir dirname ] [ --host name ] [ --lockwait seconds ] [ --stop which ] [ --timeout minutes ] [ --wipe which ] [ keys... ] INTRODUCTION Keychain helps you to manage SSH and GPG keys in a convenient and secure manner. It acts as a frontend to "ssh-agent" and "ssh-add", but allows you to easily have one long-running "ssh-agent" process per system, rather than the norm of one "ssh-agent" per login session. This dramatically reduces the number of times you need to enter your passphrase. With "keychain", you only need to enter a passphrase once every time your local machine is rebooted. Keychain also makes it easy for remote cron jobs to securely "hook in" to a long running "ssh-agent" process, al- lowing your scripts to take advantage of key-based logins. Keychain also supports GnuPG 2.1 and later, and will automatically start gpg-agent if any GPG keys are referenced on the command-line, and will en- sure these credentials are cached in memory and available for use. Official project home: <https://github.com/danielrobbins/keychain>. COMPATIBILITY Keychain supports most UNIX-like operating systems and intentionally limits its scope to modern, widely deployed implementations of OpenSSH and GnuPG. * Minimum OpenSSH version: 7.3 OpenSSH 7.3 (released 2016-08-01) introduced the "-G" (config dump) op- tion used by Keychain to expand "host:" extended keys and the "--con- fallhosts" feature. Because this option is central to modern key dis- covery, Keychain officially targets OpenSSH 7.3 or newer. Earlier ver- sions (>=6.5) may appear to work for basic usage (loading explicitly named keys) but are not part of the supported test matrix. Key types supported under the 7.3+ baseline include RSA, ECDSA and Ed25519 (Ed25519 first appeared in OpenSSH 6.5). DSA keys have been disabled by default upstream since OpenSSH 7.0; Keychain will still list or load them if they are explicitly enabled and present, but they are considered legacy. Features leveraged from OpenSSH: ssh -V (implementation detection) ssh -nG host (configuration expansion for host: extended keys) ssh-agent -s (Bourne-compatible environment output; always forced) ssh-agent -t (default key lifetime when spawning) ssh-agent -a path (explicit socket path when requested) ssh-add -l/-L (list fingerprints / public keys) ssh-add -d/-D (remove one / remove all keys) ssh-add -c (confirmation mode) ssh-add -t (per-key lifetime override) ssh-keygen -l -f (fingerprint extraction, handles SHA256 & legacy MD5) Forwarded agent sockets (optionally adopted with --ssh-allow-forwarded) * GnuPG / gpg-agent GnuPG 2.1 or later is required for gpg-agent integration. Keychain uses "gpg-connect-agent" "GETINFO socket_name" and "GETINFO ssh_socket_name" to detect, adopt or (optionally) spawn gpg-agent when acting as an SSH agent via "--ssh-allow-gpg" or "--ssh-spawn-gpg". Earlier GnuPG ver- sions (2.0.x) lacked reliable SSH key storage support and are not sup- ported. * Shells The Keychain script itself requires a POSIX / Bourne-compatible shell. It generates pidfiles for Bourne ("...-sh"), csh/tcsh ("...-csh") and fish ("...-fish") shells. Internally Keychain now always consumes the canonical Bourne output of ssh-agent (forced with "-s") and derives the other shell formats. Bash, ksh and zsh consume the Bourne pidfiles. Keychain is officially supported on Git Bash (MSYS2) for Windows, in- cluding proper handling of Windows-style paths and usernames containing spaces. The csh/tcsh and fish pidfiles remain supported for backward compati- bility. They are candidates for deprecation: a warning about planned removal will be announced at least two minor releases before any change. * Spaces in HOME and paths Keychain 2.9.7+ properly handles home directories and private key paths containing spaces. All path variables in pidfiles (SSH_AUTH_SOCK) are quoted to ensure correct parsing by shells. The implementation uses a robust approach that evaluates ssh-agent output in a subshell to ex- tract environment variables directly, rather than fragile string pars- ing. This ensures compatibility even if ssh-agent output format changes. File ownership detection uses POSIX-defined ls output format with logic to correctly parse usernames containing spaces. * Legacy / Other SSH implementations SunSSH (found on older Oracle Solaris releases) may still function; code paths for SunSSH detection are retained but are not actively tested. They are scheduled for review and possible removal after three future minor releases unless community feedback requests retention. The historical commercial ssh.com implementation and its agent are no longer targets. If detected, behavior may fall back to simpler key loading; advanced features (confirmation, modern fingerprint parsing, host expansion) are not guaranteed. Reporting such usage via GitHub Is- sues will help shape any future support decisions. * Systemd user environment On systems with systemd --user, Keychain can inject "SSH_AUTH_SOCK" (and optionally "SSH_AGENT_PID") via "--systemd" for wider session availability. Summary: A supported environment is OpenSSH >= 7.3 plus (optionally) GnuPG >= 2.1, running under any modern UNIX-like OS with a POSIX shell. Earlier versions or unlisted SSH implementations may work for basic scenarios but are outside official scope. LIFECYCLE Typically, you configure keychain to run when you first log in to a system. If you are using Bourne shell or bash, you will create a ~/.profile or ~/.bash_profile file and include the following line in it: eval "$(keychain --eval id_rsa)" Keychain will start ssh-agent if one isn't already running. Keychain then checks to make sure your private keys (in this example, "id_rsa") are loaded into the agent. If they are not, you are prompted for any passphrase necessary to decrypt them, so that they are cached in memory and available for use. In addition to printing some user-friendly output to your terminal, key- chain will also output important ssh-agent environment variables, which the "$( )" (you can also use "` `") captures, and the "eval" evaluates, setting these variables in your current shell. These ssh-agent environment variables are also written to ~/.key- chain/${HOSTNAME}-sh, so that subsequent logins and non-interactive shells such as cron jobs can source the file to access the running ssh-agent and make passwordless ssh connections using the cached private keys -- even when you are logged out. These files are collectively called pidfiles. The key files specified on the command-line will be searched for in the ~/.ssh/ directory, and keychain will expect to find the private key file with the same name, as well as a ".pub" public key. Keychain will also see if any GPG keys are specified, and if so, prompt for any passphrases to cache these keys into "gpg-agent". Typically, private SSH key files are specified by filename only, without path, although it is possible to specify an absolute or relative path to the private key file as well. Private key files can be symlinks to the ac- tual key as long as your system has the "readlink" command available. More advanced features are available for specifying keys as well -- see the --extended and --confallhosts options for more information. In addition, for GPG keys specified, similar steps will be taken to ensure that gpg-agent has the GPG key cached in memory and ready for use. STREAMLINING AND SIMPLIFICATION Keychain 2.9.0 has been streamlined, and with this maintenance several com- mand-line options have been retired as they are not completely necessary. This simplifies the use of the tool by making it more intuitive to use. The files created in ~/.keychain have also been cleaned up. This section details all the important changes. PIDFILE CHANGES "Pidfile" is the nickname for files created in ~/.keychain which can then be sourced by your scripts to access a running agent. When using gpg-agent for GPG keys, keychain will no longer create a ~/.key- chain/${HOSTNAME}-sh-gpg pidfile. This file is no longer needed as the canonical GPG socket inside ~/.gnupg/ will be used to detect the running gpg-agent, which is the modern convention. GnuPG 2.1 and later have stopped using environment variables to find the agent, so we follow this upstream change. IMPROVED DEBUGGING A new --debug option is now available which will print additional informa- tion related to keychain's decisions regarding why and how an agent was found -- or not. NEW (AND DEPRECATED) OPTIONS This section provides an overview of new and deprecated command-line op- tions. For full details on each option, see the respective option defini- tion under "OPTIONS". Keychain 2.9.2 The "--confhost" option has been deprecated. Instead of "--confhost host- name", use "--extended host:hostname". This extended format allows multiple keys of multiple types (SSH, GPG and SSH-from-hostname) to be specified on the command-line together. This is also fully compatible with "--confall- hosts", and keychain now de-duplicates the list of keys to be loaded. Keychain 2.9.1 The short-lived "--ssh-wipe" and "--gpg-wipe" options that appeared only in version 2.9.0 were replaced with "--wipe which" to work similarly to the "--stop" option, and allows you to specify "ssh", "gpg" or "all". Keychain 2.9.0 The "--agents" option is now deprecated. Keychain will always ensure an ssh-agent or equivalent is running, or if "--ssh-spawn-gpg" is used, poten- tially a gpg-agent for the purpose of storing SSH keys if no running ssh-agent is available. To simply use a gpg-agent if one is already run- ning, falling back to launching ssh-agent if no agent is available, use the "--ssh-allow-gpg" option. Specifying a GPG key on the command-line will instruct keychain to enable gpg-agent functionality automatically. This eliminates an option that you need to specify ("--agents ssh,gpg") when invoking keychain, and for many will avoid spawning a GPG agent you may not be using. Specifying the "--agents" option will now display a warning that it's dep- recated, but keychain will not abort. The "--inherit" option, which took one of four arguments, has been depre- cated. Keychain's default behavior remains that of preferring to use an ssh-agent or equivalent referenced by its pidfile, falling back to finding an ssh-agent in its environment. By default, keychain will not use a gpg-agent socket for SSH keys unless at least "--ssh-allow-gpg" is speci- fied. Similarly, the use of any forwarded SSH agent connection is disabled by default and can be enabled via "--ssh-allow-forwarded". Again, see the full documentation for each option in the "OPTIONS" section. You can still influence keychain's behavior via the still-present "--noin- herit" option which will prevent all detection of existing SSH agents via the environment. The "--clear" option is still available, but isn't intended to be a "stand- alone" option, meaning that it is used to perform an initial clearing of cached keys before loading any specified keys when Keychain is run. To perform the sole action of wiping all cached keys, use the "--wipe" action. To remove an individual cached SSH private key or keys, use the "--ssh-rm" keyfile option. The "--stop" option will now only stop any running ssh-agent processes, and still supports three possible options: "mine", "others" and "all". It no longer stops gpg-agent processes, which tend to get auto-respawned by GPG tools, so killing gpg-agent typically doesn't make a lot of sense. BETTER GNUPG INTEGRATION Keychain can now use an existing gpg-agent that has been started in your environment to store ssh keys, rather than spawning its own ssh-agent, by using the "--ssh-allow-gpg" option. If you would like keychain to spawn gpg-agent instead of ssh-agent, and use it to store SSH keys, specify the "--ssh-spawn-gpg" option. Without either option, keychain will not use an SSH_AUTH_SOCK that is pro- vided by gpg-agent, and will spawn an official ssh-agent process. In addition, behind the scenes, keychain now uses the gpg-connect-agent ex- ecutable to restart the agent, get official PID and socket information, etc. Please note that while gpg-agent provides full compatibility with ssh-agent, its password prompt is handled by pinentry and its store may en- crypt your in-memory keys. For this reason, consider this new feature ex- perimental, and use GitHub issues to report back any anomalies or suggested improvements for gpg-agent integration. DISPLAY CHANGES When keychain uses gpg-agent for either GnuPG or SSH support, then keychain will display the GnuPG socket file in its output, rather than the PID. Since the socket file has the ~/.gnupg path in it, this communicates to you that gpg-agent, not ssh-agent, is active. If you see an integer PID, this means that ssh-agent is being used. STREAMLINED STARTUP By default, keychain will always ensure that an ssh-agent should be started. It will only start a gpg-agent if a GPG key is referenced on the command-line. Modern versions of gpg-agent also support the caching of SSH keys, allowing it to be a drop-in replacement for ssh-agent. With keychain 2.9.0, a new "--ssh-spawn-gpg" option has been added, which when specified will give keychain permission to spawn a gpg-agent in place of ssh-agent. CODE OPTIMIZATION With keychain 2.9.0, there has been significant code cleanup, reducing the size of the script from 1500 lines to about 1100 lines. In addition, the script is now fully compliant with ShellCheck <https://shellcheck.net>, which will be hugely helpful to ensure continued POSIX shell compatibility moving forward. AGENT DETECTION AND STARTUP ALGORITHM This section documents the official algorithm used for detecting and if necessary starting ssh-agent, to facilitate understanding as well as devel- oper maintenance of the codebase. DEFINITIONS There are several important definition related to the algorithm: 1. The agent, "ssh-agent", which is a long-running daemon. This can also in some cases be "gpg-agent", depending on command-line options. 2. The inherited agent, which is the agent or forwarded agent that was not started by keychain, but is detected in the environment or by other means. 3. The adopted agent, which is an inherited agent whose information has been persisted by being written to the pidfiles (see below). 4. The environment variables "SSH_AUTH_SOCK", which points to the socket file used to communicate with ssh-agent, and optionally "SSH_AGENT_PID", which indicates its process ID if running locally (although gpg-agent does not define "SSH_AGENT_PID", even if running locally.) 5. The file ~/.keychain/${HOSTNAME}-sh and related files, which are collec- tively referred to as "pidfiles". Pidfiles are used to persistently store "SSH_AUTH_SOCK" and "SSH_AGENT_PID" environment variables for use by other scripts, as well as by keychain itself, formatted so that they can be "sourced" by shells of various types. 6. Relevant command-line options affecting behavior, which include --noin- herit, --ssh-allow-gpg, --ssh-spawn-gpg, and --ssh-allow-forwarded. ALGORITHM OVERVIEW When the keychain script is run, it will first attempt to find a running ssh-agent. Phase 1: pidfile: To do this, it will first look for an existing pidfile. If one exists, it will be inspected and used to find a running agent, in alignment with specified command-line options. If this process is success- ful, a "keychain-spawned" agent is found and this process is complete. Oth- erwise, we continue to the next step. Phase 2: environment: If keychain's pidfile did not yield a running agent, keychain looks at environment variables defined in the current environment. This step will be skipped if the --noinherit option is specified. If an agent is found that is in alignment with specified command-line options, it is considered "inherited" by keychain, and the process is complete. Other- wise, we continue to the next step. Phase 3: spawn agent: In the absence of finding a keychain-spawned or ex- isting agent that can be adopted, keychain will spawn a new ssh-agent, or a new gpg-agent if --ssh-spawn-gpg is specified and gpg-agent is available. Final Phase: update pidfile: In addition, the pidfiles will be updated to reflect the keychain-spawned or "inherited" agent. An "inherited" agent, once written to the pidfile, is now considered to be "adopted". Pidfile update exception: If the --ssh-allow-forwarded option was speci- fied, and a forwarded SSH socket was found -- which is identified as a valid SSH socket defined in a "SSH_AUTH_SOCK" variable, which has no asso- ciated or valid "SSH_AGENT_PID" also defined in the environment and is also determined to not be the socket of any running gpg-agent -- then this agent will simply be used, but not persisted in any pidfile. This is because this SSH-supplied socket will disappear when the underlying SSH connection ter- minates, and thus it cannot be relied on to be available persistently. THE QUICK SHORT-CIRCUIT When the --quick option is specified, a special algorithm will run prior to the main agent-detection algorithm listed above. A pidfile, if it exists, will be evaluated as per Phase 1 of the main algorithm. If a valid running agent is found, it will be queried for valid keys. If at least one valid key is loaded into the agent, the quick start is considered successful, and keychain will skip the regular agent startup algorithm, and will use this found agent. SUMMARY AND RATIONALE The keychain ssh-agent detection and startup algorithm is somewhat sophis- ticated for a reason. There is an intention behind its behavior. The algorithm has been specifically designed to prefer an agent spawned by keychain, or previously adopted, if that agent is currently available. This is by design, because other system software could spawn ssh-agent and/or gpg-agent processes, and we want keychain to not coerced into using these new agents which may suddenly appear in the environment unexpectedly when new desktop sessions start and in other circumstances. If keychain is too "suggestible", it will lose track of the agent which currently holds valid keys, which can result in unnecessary prompting for passphrases, and gen- eral confusion. OPTIONS --absolute This option can be used with the --dir option, if you would like to specify a non-default directory to store pidfiles (defaults to ~/.key- chain). When this option is used, the script does not automatically ap- pend /.keychain to the path, allowing you to use any arbitrary direc- tory name for the storing of pidfiles. Please note that Keychain 2.9.3 adds some extra security checks related to directory and file permis- sions -- you must have exclusive ownership of any directory that key- chain uses to store pidfiles, or keychain will abort. --clear When specified, this option adds an initial step prior to adding any keys to the agents of wiping all existing cached keys/passphrases. This is intended to be used alongside keychain --eval to ensure that only the specified keys are loaded, and that keychain should assume that you are an intruder until proven otherwise and force all interac- tive logins to specify valid passphrases. This option increases secu- rity and still allows your cron jobs to use your ssh keys when you're logged out. --confallhosts In addition to any keys specified on the command-line, this option will tell keychain to scour ~/.ssh/config for all private keys referenced in all "IdentityFile" lines, and load all keys for all hosts. --confirm Keys are subject to interactive confirmation by the SSH_ASKPASS program before being used for authentication. See the -c option for ssh-add(1). --debug Keychain 2.9.0 introduces the --debug option, which will output addi- tional information related to how Keychain makes its agent-selection process. Specifically, it will output when an SSH_AUTH_SOCK is rejected because it is being supplied by gpg-agent -- and this is not allowed due to no --ssh-allow-gpg option, or when it is rejected because it ap- pears to be from a forwarded SSH connection, and --ssh-allow-forwarded was not supplied. --dir dirname This option allows you to use another directory besides $HOME/.keychain for the storing of pidfiles. Please note that Keychain 2.9.3 adds some extra security checks related to directory and file permissions -- you must have exclusive ownership of any directory that keychain uses to store pidfiles, or the script will abort. Also see the --absolute op- tion. --env filename After parsing options, keychain will load additional environment set- tings from "filename". By default, if "--env" is not given, then key- chain will attempt to load from ~/.keychain/[hostname]-env or alterna- tively ~/.keychain/env. The purpose of this file is to override set- tings such as PATH, in case ssh is stored in a non-standard place. --eval Keychain will print lines to be evaluated in the shell on stdout. It respects the SHELL environment variable to determine if Bourne shell or C shell output is expected. --extended This enables extended command-line key processing with more features, and is a replacement for the old "--confhost" option. When specified, each key specified on the command-line must have a prefix to explicitly categorize it. SSH keys must have a prefix of "sshk:" immediately fol- lowed by the path or key name (the part after the "sshk:" is processed just like a SSH key is without the "--extended" option). GPG keys must be in the format "gpgk:" immediately followed by the 8 or 16-character fingerprint. If "host:<hostname>" is specified, then Keychain will ex- tract the SSH configuration for the specified hostname, grab all iden- tityfile options (private keys) specified, and these keys will be in- cluded in the set of keys to be loaded by keychain. This allows multi- ple keys of multiple types, including SSH-keys-by-host, to be specified together, which wasn't possible with "--confhost". --gpg2 This option changes the default gpg calls to use gpg2 instead to sup- port distributions such as Ubuntu which has both gpg and gpg2 -h --help Show help that looks remarkably like this man-page. As of 2.6.10, help is sent to stdout so it can be easily piped to a pager. --host name Set alternate hostname for creation of pidfiles --ignore-missing Don't warn if some keys on the command-line can't be found. This is useful for situations where you have a shared .bash_profile, but your keys might not be available on every machine where keychain is run. -l --list List signatures of all active SSH keys, and exit, similar to "ssh-add -l". -L --list-fp List fingerprints of all active SSH keys, and exit, similar to "ssh-add -L". --lockwait seconds How long to wait for the lock to become available. Defaults to 5 sec- onds. Specify a value of zero or more. If the lock cannot be acquired within the specified number of seconds, then this keychain process will forcefully acquire the lock. --noask This option tells keychain do everything it normally does (ensure ssh-agent is running, set up the ~/.keychain/[hostname]-{c}sh files) except that it will not prompt you to add any of the keys you specified if they haven't yet been added to ssh-agent. --nocolor Disable color highlighting for non ANSI-compatible terms. --nogui Don't honor SSH_ASKPASS, if it is set. This will cause ssh-add to prompt on the terminal instead of using a graphical program. --noinherit Don't inherit any agent processes, overriding the default behavior of inheriting all non-forwarded ssh-agent and any existing gpg-agent processes. Also see "AGENT DETECTION AND STARTUP ALGORITHM". --nolock Don't attempt to use a lockfile while manipulating files, pids and keys. --query Keychain will print lines in KEY=value format representing the values which are set by the agents. -Q --quick If an ssh-agent process is running then use it. Don't verify the list of keys, other than making sure it's non-empty. This option avoids locking when possible so that multiple terminals can be opened simulta- neously without waiting on each other. See the "THE QUICK SHORT-CIR- CUIT" section for more information regarding how this fits into the overall startup algorithm. -q --quiet Only print messages in case of warning, error or required interactiv- ity. As of version 2.6.10, this also suppresses "Identities added" mes- sages for ssh-agent. -k --stop which Kill currently running ssh-agent processes and exit. Note that previous versions of keychain (2.8.5 and earlier) allowed killing of gpg-agent as well. This functionality was removed as ssh-agent and gpg-agent have a bit different design philosophies and you almost always only have at most one gpg-agent running at a time. Use "killall gpg-agent" if you really want to kill gpg-agent. However, since this option also removes pidfiles, it will remove any gpg-agent processes adopted by keychain that were being used to store ssh keys. The following values are valid for "which" which controls which ssh-agents to target: all Kill all ssh-agent processes and quit keychain immediately. Prior to keychain-2.5.0, this was the behavior of the bare "--stop" option. others Kill agent processes other than the ones keychain is provid- ing. Prior to keychain-2.5.0, keychain would do this automat- ically. The new behavior requires that you specify it explic- itly if you want it. mine Kill keychain's agent processes, leaving other agents alone. --ssh-agent-socket path Use this option to specify the path to the socket file that you would like ssh-agent to create and use as its official socket. By default, ssh-agent will create its own socket file, typically in /tmp. --ssh-allow-forwarded By default, keychain will not use a forwarded ssh-agent connection, which is a ssh-agent socket created by SSH that has no associated local process. To permit keychain to use a forwarded ssh-agent connection, specify this option. If a SSH-forwarded socket is used, it will not be persisted in the pidfiles, as it is not likely to be available outside of the currently-active SSH session. --ssh-allow-gpg Would you like to have keychain use an already-running gpg-agent to store your SSH keys, rather than spawning a new ssh-agent? This option does just that. When this option is specified, keychain will accept an SSH_AUTH_SOCK environment variable in its environment, even if it was created by gpg-agent. Modern versions of gpg-agent are also able to store SSH keys. By default, keychain has a special check to avoid using a gpg-agent that has set the SSH_AUTH_SOCK environment variable, and will instead spawn its own ssh-agent. With this option enabled, this restriction is turned off. Please note that this option does not actu- ally instruct keychain to spawn a gpg-agent for storing SSH keys if no agent is available -- if you want that, see the --ssh-spawn-gpg option, below. ALSO NOTE: When a gpg-agent is adopted for ssh-agent duties in this way, the ~/.keychain/${HOSTNAME}-sh pidfile will be updated to refer- ence the gpg-agent socket, so it will be seamlessly used by future cron jobs needing an ssh-agent, as well as by future invocations of key- chain, as long as the --ssh-allow-gpg or --ssh-spawn-gpg (which implies --ssh-allow-gpg) are specified. --ssh-spawn-gpg This is the option to use if you're really on-board with using gpg-agent as a replacement for ssh-agent. Not only will keychain use a running gpg-agent if found as per the --ssh-allow-gpg, but if it needs to spawn a new ssh-agent, it will go ahead and spawn a gpg-agent in its place, and use it instead. Also see notes for the --ssh-allow-gpg op- tion, as this option also implies --ssh-allow-gpg. --ssh-rm -r keys Only perform the single action of removing the specified cached keys from the running ssh-agent, and then exit. --systemd Inject environment variables into the systemd --user session. --timeout minutes Allows a timeout to be set for identities added to ssh-agent. When this option is used with a keychain invocation that starts ssh-agent itself, then keychain uses the appropriate ssh-agent option to set the default timeout for ssh-agent. The --timeout option also gets passed to ssh-add invocations, so any keys added to a running ssh-agent will be individually configured to have the timeout specified, overriding any ssh-agent default. Most users can simply use the timeout setting they desire and get the result they want -- with all identities having the specified timeout, whether added by keychain or not. More advanced users can use one invo- cation of keychain to set the default timeout, and optionally set dif- ferent timeouts for keys added by using a subsequent invocation of key- chain. -V --version Show version information. --wipe which Only perform the single action of wiping all agent's cached keys. Spec- ify 'ssh', 'gpg' or 'all' for SSH keys, GPG keys and all agents respec- tively. Also see the "--ssh-rm" action and the "--clear" option. EXAMPLES This snippet should work in most shells to load two ssh keys and one gpg key: eval `keychain --eval id_rsa id_dsa 0123ABCD` For the fish shell, use the following format: if status --is-interactive keychain --eval --quiet -Q id_rsa | source end If you have trouble with that in csh: setenv SHELL /bin/csh eval `keychain --eval id_rsa id_dsa 0123ABCD` This is equivalent for Bourne shells (including bash and zsh) but doesn't use keychain's --eval feature: keychain id_rsa id_dsa 0123ABCD [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n` [ -f $HOME/.keychain/$HOSTNAME-sh ] && \ . $HOME/.keychain/$HOSTNAME-sh This is equivalent for C shell (including tcsh): keychain id_rsa id_dsa 0123ABCD host=`uname -n` if (-f $HOME/.keychain/$host-csh) then source $HOME/.keychain/$host-csh endif Likewise, the following commands can be used in fish: keychain id_rsa id_dsa 0123ABCD test -z "$hostname"; and set hostname (uname -n) if test -f "$HOME/.keychain/$hostname-fish" source $HOME/.keychain/$hostname-fish end To load keychain variables from a script (for example from cron) and abort unless id_dsa is available: # Load keychain variables and check for id_dsa [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n` . $HOME/.keychain/$HOSTNAME-sh 2>/dev/null ssh-add -l 2>/dev/null | grep -q id_dsa || exit 1 SEE ALSO ssh-agent(1), gpg-agent(1), ssh-add(1), ssh(1) NOTES Keychain was created and is currently maintained by Daniel Robbins. To re- port a bug or request an enhancement, use the issue tracker at <https://github.com/danielrobbins/keychain>. Keychain includes bash completion support for command-line options, SSH keys, GPG keys, and extended mode prefixes ("sshk:", "gpgk:", "host:"). The completion script is included in the source tarball at "completions/key- chain.bash". For installation instructions, see the README file or run "make install-completions". The former Funtoo Linux wiki page is preserved only as an historical refer- ence: <https://www.funtoo.org/Funtoo:Keychain>. 2.9.8 2025-11-02 keychain(1)
NAME | SYNOPSIS | INTRODUCTION | COMPATIBILITY | LIFECYCLE | STREAMLINING AND SIMPLIFICATION | AGENT DETECTION AND STARTUP ALGORITHM | OPTIONS | EXAMPLES | SEE ALSO | NOTES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=keychain&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>