Manpage fixups. Follow-up to #517.

1 files changed, 52 insertions, 31 deletions

diff --git a/src/iperf3.1 b/src/iperf3.1
index 48d58e2..a95aad6 100644
--- a/src/iperf3.1
+++ b/src/iperf3.1
@@ -86,13 +86,17 @@ write a file with the process ID, most useful when running as a daemon.
 .BR -1 ", " --one-off
 handle one client connection, then exit.
 .TP
-.BR --rsa-private-key-path " \fIfile\fR" " (if built with OpenSSL support) 
-path to the RSA private key used to decrypt authentication credentials (not 
-password protected) 
+.BR --rsa-private-key-path " \fIfile\fR"
+path to the RSA private key (not password-protected) used to decrypt 
+authentication credentials from the client (if built with OpenSSL
+support).
 .TP          
-.BR --authorized-users-path " \fIfile\fR" " (if built with OpenSSL support)
-path to the configuration file containing authorized users credendientals to run 
-iperf tests. File is a comma separated list of usernames and password hashes.
+.BR --authorized-users-path " \fIfile\fR"
+path to the configuration file containing authorized users credentials to run 
+iperf tests (if built with OpenSSL support).
+The file is a comma separated list of usernames and password hashes;
+more information on the structure of the file can be found in the
+EXAMPLES section.
 .SH "CLIENT SPECIFIC OPTIONS"
 .TP
 .BR -c ", " --client " \fIhost\fR"
@@ -230,44 +234,61 @@ If the client is run with \fB--json\fR, the server output is included
 in a JSON object; otherwise it is appended at the bottom of the
 human-readable output.
 .TP
-.BR --username " \fIusername\fR" " (if built with OpenSSL support)               
-username assigned by server adminitrators to access to the iperf service.
+.BR --username " \fIusername\fR" 
+username to use for authentication to the iperf server (if built with
+OpenSSL support).
+The password will be prompted for interactively when the test is run.
 .TP
-.BR --rsa-public-key-path " \fIfile\fR" " (if built with OpenSSL support)    
+.BR --rsa-public-key-path " \fIfile\fR" 
 path to the RSA public key used to encrypt authentication credentials
+(if built with OpenSSL support)
 
 .SH EXAMPLES
-.TP
-.BR "Authentication - RSA Keypair"
-Authentication feature requires a pair of public and private RSA keys. The 
-public key is used to encrypt the authentication token containing the 
-user credentials, the private key is used to decrypt the authentication token.
-An example of linux command to generate correct keypair follows:
+.SS "Authentication - RSA Keypair"
+The authentication feature of requires an RSA public keypair.
+The public key is used to encrypt the authentication token containing the 
+user credentials, while the private key is used to decrypt the authentication token.
+An example of a set of UNIX/Linux commands to generate correct keypair follows:
 .sp 1 
-.in +.5i $> openssl genrsa -des3 -out private.pem 2048
+.in +.5i
+> openssl genrsa -des3 -out private.pem 2048
 .sp 0
-$> openssl rsa -in private.pem -outform PEM -pubout -out public.pem
+> openssl rsa -in private.pem -outform PEM -pubout -out public.pem
 .sp 0
-$> openssl rsa -in private.pem -out private_not_protected.pem -outform PEM  
-.TP
-.BR "Authentication - Authorized users configuration file"
-A simple plaintext file can be provided to iperf3 server in order to specify 
-the authorized user credentials allowd to use iperf3 server. File can contain 
-commented lines (starting with # char) and is a simple list of comma separated
-pair of username password hash. Password hash is a sha256 hash of string 
-"{$user}$password":
+> openssl rsa -in private.pem -out private_not_protected.pem -outform PEM  
+.in -.5i
+.sp 1
+After these commands, the public key will be contained in the file
+public.pem and the private key will be contained in the file
+private_not_protected.pem.
+.SS "Authentication - Authorized users configuration file"
+A simple plaintext file must be provided to the iperf3 server in order to specify 
+the authorized user credentials.
+The file is a simple list of comma-separated pairs of a username and a
+corresponding password hash.
+The password hash is a SHA256 hash of the string "{$user}$password".
+The file can also contain commented lines (starting with the \fC#\fR
+character).
+An example of commands to generate the password hash on a UNIX/Linux system
+is given below:
 .sp 1 
-.in +.5i $> S_USER=mario S_PASSWD=rossi
+.in +.5i
+> S_USER=mario S_PASSWD=rossi
 .sp 0
-$> echo -n "{$S_USER}$S_PASSWD" | sha256sum | awk '{ print $1 }'
+> echo -n "{$S_USER}$S_PASSWD" | sha256sum | awk '{ print $1 }'
+.in -.5i
+.sp 1
+An example of a password file (with an entry corresponding to the
+above username and password) is given below:
 .sp 0
-$> cat credentials.csv
+.in +.5i
+> cat credentials.csv
 .sp 0
 # file format: username,sha256
 .sp 0
-mario,44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c0....
-.sp 0
-$>
+mario,bf7a49a846d44b454a5d11e7acfaf13d138bbe0b7483aa3e050879700572709b
+.in -.5i
+.sp 1
 
 .SH AUTHORS
 A list of the contributors to iperf3 can be found within the