Agent
=====

The (ssh agent) module provides procedures for interacting with SSH authentication agent instances.

Starting/stopping SSH agents
----------------------------

 -- Scheme Procedure: ssh-agent-start
     Start an OpenSSH agent. Return a list with SSH agent information of the following form:

          '((SSH_AUTH_SOCK . <agent-socket-file-path>)
            (SSH_AGENT_PID . <agent-pid>))

 -- Scheme Procedure: ssh-agent-stop
     Kill the current agent (given by the SSH_AGENT_PID environment variable).

Getting information about SSH agents
------------------------------------

 -- Scheme Procedure: ssh-agent-info
     [#:user=(getenv "USER")]
     [#:path=(or (getenv "TMPDIR") "/tmp")]

     The procedure tries to find information about all running SSH authentication agent instances by searching the specified PATH for a given USER.

     The agent subdirectory pattern is used as specified in the ssh-agent man page: ssh-XXXXXXXXXX/agent.<ppid>

     Returns an associative list of the following form:

          '(((SSH_AUTH_SOCK . <agent-socket-file-path-1>)
             (SSH_AGENT_PID . <agent-pid-1>))
            ((SSH_AUTH_SOCK . <agent-socket-file-path-2>)
             (SSH_AGENT_PID . <agent-pid-2>))
            ...)

     One might use the procedure to configure the environment in a REPL to use SSH userauth-agent! procedure later:

          (define s (make-session #:host "localhost"))
          (connect! s)
          (ssh-agent-sock-set! (assoc-ref (car (ssh-agent-info)) 'SSH_AUTH_SOCK))
          (userauth-agent! s)
          (with-ssh (make-node s) (version))

Managing SSH agent environment variables
----------------------------------------

 -- Scheme Procedure: ssh-agent-sock-get
     Get the SSH__AGENT__SOCK environment variable value.

 -- Scheme Procedure: ssh-agent-sock-set! sock-file
     Set the value of SSH__AGENT__SOCK environment variable to the SOCK-FILE.