@c -*-texinfo-*-
@c This file is part of Guile-SSH Reference Manual.
@c Copyright (C) 2020-2021 Artyom V. Poptsov
@c See the file guile-ssh.texi for copying conditions.

@node Agent
@section Agent

@cindex agent

The @code{(ssh agent)} module provides procedures for interacting with SSH
authentication agent instances.

@c -----------------------------------------------------------------------------
@subsection Starting/stopping SSH agents

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

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

@end deffn

@deffn {Scheme Procedure} ssh-agent-stop
Kill the current agent (given by the @code{SSH_AGENT_PID} environment
variable).
@end deffn

@c -----------------------------------------------------------------------------
@subsection Getting information about SSH agents

@deffn {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 @var{path} for a given @var{user}.

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

Returns an associative list of the following form:
@lisp
'(((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>))
  ...)
@end lisp

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

@lisp
(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))
@end lisp

@end deffn

@c -----------------------------------------------------------------------------
@subsection Managing SSH agent environment variables

@deffn {Scheme Procedure} ssh-agent-sock-get
Get the @env{SSH__AGENT__SOCK} environment variable value.
@end deffn

@deffn {Scheme Procedure} ssh-agent-sock-set! sock-file
Set the value of @env{SSH__AGENT__SOCK} environment variable to the
@var{sock-file}.
@end deffn

@c Local Variables:
@c TeX-master: "guile-ssh.texi"
@c End:
