reshuffle the text to read better;

input from naddy, djmc, and dtucker

1 files changed, 76 insertions, 82 deletions

diff --git a/usr.bin/ssh/ssh-agent.1 b/usr.bin/ssh/ssh-agent.1
index 9129d36ff6f..2a1268af747 100644
--- a/usr.bin/ssh/ssh-agent.1
+++ b/usr.bin/ssh/ssh-agent.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ssh-agent.1,v 1.67 2019/11/19 16:02:32 jmc Exp $
+.\" $OpenBSD: ssh-agent.1,v 1.68 2019/11/28 12:23:25 jmc Exp $
 .\"
 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
@@ -34,7 +34,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 19 2019 $
+.Dd $Mdocdate: November 28 2019 $
 .Dt SSH-AGENT 1
 .Os
 .Sh NAME
@@ -54,37 +54,12 @@
 .Fl k
 .Sh DESCRIPTION
 .Nm
-is a program to hold private keys used for public key authentication
-(RSA, DSA, ECDSA, Ed25519).
-.Nm
-is usually started in the beginning of an X-session or a login session, and
-all other windows or programs are started as clients to the ssh-agent
-program.
+is a program to hold private keys used for public key authentication.
 Through use of environment variables the agent can be located
 and automatically used for authentication when logging in to other
 machines using
 .Xr ssh 1 .
 .Pp
-The agent initially does not have any private keys.
-Keys are added using
-.Xr ssh 1
-(see
-.Cm AddKeysToAgent
-in
-.Xr ssh_config 5
-for details)
-or
-.Xr ssh-add 1 .
-Multiple identities may be stored in
-.Nm
-concurrently and
-.Xr ssh 1
-will automatically use them if present.
-.Xr ssh-add 1
-is also used to remove keys from
-.Nm
-and to query the keys that are held in one.
-.Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl a Ar bind_address
@@ -125,17 +100,17 @@ environment variable).
 .It Fl P Ar provider_whitelist
 Specify a pattern-list of acceptable paths for PKCS#11 and security key shared
 libraries that may be used with the
-.Fl s
-or
 .Fl S
+or
+.Fl s
 options to
 .Xr ssh-add 1 .
-The default is to allow loading libraries from
-.Dq /usr/lib/*,/usr/local/lib/* .
 Libraries that do not match the whitelist will be refused.
 See PATTERNS in
 .Xr ssh_config 5
 for a description of pattern-list syntax.
+The default whitelist is
+.Dq /usr/lib/*,/usr/local/lib/* .
 .It Fl s
 Generate Bourne shell commands on
 .Dv stdout .
@@ -150,64 +125,82 @@ A lifetime specified for an identity with
 .Xr ssh-add 1
 overrides this value.
 Without this option the default maximum lifetime is forever.
+.It Ar command Op Ar arg ...
+If a command (and optional arguments) is given,
+this is executed as a subprocess of the agent.
+The agent exits automatically when the command given on the command
+line terminates.
 .El
 .Pp
-If a command line is given, this is executed as a subprocess of the agent.
-When the command dies, so does the agent.
-.Pp
-The idea is that the agent is run in the user's local PC, laptop, or
-terminal.
-Authentication data need not be stored on any other
-machine, and authentication passphrases never go over the network.
-However, the connection to the agent is forwarded over SSH
-remote logins, and the user can thus use the privileges given by the
-identities anywhere in the network in a secure way.
-.Pp
-There are two main ways to get an agent set up:
-The first is that the agent starts a new subcommand into which some environment
-variables are exported, eg
+There are two main ways to get an agent set up.
+The first is at the start of an X session,
+where all other windows or programs are started as children of the
+.Nm
+program.
+The agent starts a command under which its environment
+variables are exported, for example
 .Cm ssh-agent xterm & .
-The second is that the agent prints the needed shell commands (either
-.Xr sh 1
-or
-.Xr csh 1
-syntax can be generated) which can be evaluated in the calling shell, eg
-.Cm eval `ssh-agent -s`
-for Bourne-type shells such as
-.Xr sh 1
-or
-.Xr ksh 1
-and
-.Cm eval `ssh-agent -c`
-for
-.Xr csh 1
-and derivatives.
+When the command terminates, so does the agent.
 .Pp
-Later
+The second method is used for a login session.
+When
+.Nm
+is started,
+it prints the shell commands required to set its environment variables,
+which in turn can be evaluated in the calling shell, for example
+.Cm eval `ssh-agent -s` .
+.Pp
+In both cases,
 .Xr ssh 1
-looks at these variables and uses them to establish a connection to the agent.
+looks at these environment variables and uses them to establish a connection to the agent.
 .Pp
-The agent will never send a private key over its request channel.
-Instead, operations that require a private key will be performed
-by the agent, and the result will be returned to the requester.
-This way, private keys are not exposed to clients using the agent.
+The agent initially does not have any private keys.
+Keys are added using
+.Xr ssh-add 1
+or by
+.Xr ssh 1
+when
+.Cm AddKeysToAgent
+is set in
+.Xr ssh_config 5 .
+Multiple identities may be stored in
+.Nm
+concurrently and
+.Xr ssh 1
+will automatically use them if present.
+.Xr ssh-add 1
+is also used to remove keys from
+.Nm
+and to query the keys that are held in one.
 .Pp
-A
+Connections to
+.Nm
+may be forwarded from further remote hosts using the
+.Fl A
+option to
+.Xr ssh 1
+(but see the caveats documented therein),
+avoiding the need for authentication data to be stored on other machines.
+Authentication passphrases and private keys never go over the network:
+the connection to the agent is forwarded over SSH remote connections
+and the result is returned to the requester,
+allowing the user access to their identities anywhere in the network
+in a secure fashion.
+.Sh ENVIRONMENT
+.Bl -tag -width "SSH_AGENT_PID"
+.It Ev SSH_AGENT_PID
+When
+.Nm
+starts, it stores the name of the agent's process ID (PID) in this variable.
+.It Ev SSH_AUTH_SOCK
+When
+.Nm
+starts, it creates a
 .Ux Ns -domain
-socket is created and the name of this socket is stored in the
-.Ev SSH_AUTH_SOCK
-environment
-variable.
-The socket is made accessible only to the current user.
-This method is easily abused by root or another instance of the same
-user.
-.Pp
-The
-.Ev SSH_AGENT_PID
-environment variable holds the agent's process ID.
-.Pp
-The agent exits automatically when the command given on the command
-line terminates.
+socket and stores its pathname in this variable.
+It is accessible only to the current user,
+but is easily abused by root or another instance of the same user.
+.El
 .Sh FILES
 .Bl -tag -width Ds
 .It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
@@ -220,6 +213,7 @@ The sockets should get automatically removed when the agent exits.
 .Xr ssh 1 ,
 .Xr ssh-add 1 ,
 .Xr ssh-keygen 1 ,
+.Xr ssh_config 5 ,
 .Xr sshd 8
 .Sh AUTHORS
 .An -nosplit