Package: openssh-client
Version: 1:9.9p1-3
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff:<stdin>:1030: warning: [page 8, 6.5i]: cannot break line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages openssh-client depends on:
ii adduser 3.137
ii libc6 2.40-6
ii libedit2 3.1-20250104-1
ii libfido2-1 1.15.0-1+b1
ii libgssapi-krb5-2 1.21.3-4
ii libselinux1 3.7-3.1
ii libssl3t64 3.4.0-2
ii passwd 1:4.16.0-7
ii zlib1g 1:1.3.dfsg+really1.3.1-1+b1
Versions of packages openssh-client recommends:
ii xauth 1:1.1.2-1.1
Versions of packages openssh-client suggests:
pn keychain <none>
pn libpam-ssh <none>
pn monkeysphere <none>
pn ssh-askpass <none>
-- no debconf information
Input file is ssh_config.5
Output from "mandoc -T lint ssh_config.5": (shortened list)
6 new sentence, new line
1 no blank before trailing delimiter: Pa /etc/ssh/ssh_config.
1 referenced manual not found: Xr ssh-askpass 1
1 referenced manual not found: Xr sshd 8 (4 times)
1 referenced manual not found: Xr sshd_config 5 (6 times)
1 referenced manual not found: Xr tap 4
1 referenced manual not found: Xr tun 4 (3 times)
-.-.
Output from "test-groff -mandoc -t -ww -z ssh_config.5": (shortened list)
1 cannot break line
-.-.
Change '-' (\-) to '\(en' (en-dash) for a (numeric) range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
ssh_config.5:2275:would match any host in the 192.168.0.[0-9] network range:
-.-.
Add a (no-break, "\ " or "\~") space between a number and a unit,
as these are not one entity.
1774:.Sq 1G
1776:.Sq 4G ,
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
1671:ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
1699:option - whichever is specified first will prevent later instances of the
1748:.Qq ssh -Q PubkeyAcceptedAlgorithms .
1932:.Pa - .
2457:.An -nosplit
-.-.
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URL (web address)
1030 .Dq
gss-group14-sha256-,gss-group16-sha512-,gss-nistp256-sha256-,gss-curve25519-sha256-,gss-gex-sha1-,gss-group14-sha1-
.
-.-.
Add a "\&" after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
230:situations (e.g. when the network is automatically configured using DHCP)
402:allows a single dot (i.e. hostname.subdomain).
552:guarantee to remove all resources associated with the session, e.g. shell
687:connection i.e. it is not possible to forward multiple displays or agents.
2168:(i.e. not
2368:The type of the server host key, e.g.
2407:shell commands (e.g. quotes), it is the user's responsibility to ensure
that
-.-.
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
230:situations (e.g. when the network is automatically configured using DHCP)
402:allows a single dot (i.e. hostname.subdomain).
552:guarantee to remove all resources associated with the session, e.g. shell
687:connection i.e. it is not possible to forward multiple displays or agents.
973:connecting to the server. The default is unset, which means that the default
980:Specifies whether key exchange based on GSSAPI may be used. When using
988:ssh connection. With a compatible server, this will delegate the renewed
1003:connecting to the server. The default is unset, which means that the
1010:the name of the host being connected to. If
1018:key exchange. Possible values are
2168:(i.e. not
2407:shell commands (e.g. quotes), it is the user's responsibility to ensure
that
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Use '\:' for splitting the string for the output, "\<newline>" in the source.
Line 1030, length 121
.Dq
gss-group14-sha256-,gss-group16-sha512-,gss-nistp256-sha256-,gss-curve25519-sha256-,gss-gex-sha1-,gss-group14-sha1-
.
-.-.
Use \(en (en-dash) for a dash at the beginning (en) of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
ssh_config.5:1699:option - whichever is specified first will prevent later
instances of the
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
Not considered in a patch, too many lines.
[List of affected lines removed]
-.-
Use a no-break space between a number and a (SI) unit
1556:The default is to obscure keystrokes using a 20ms packet interval.
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:1030: warning: [page 8, 6.5i]: cannot break line
--- ssh_config.5 2025-02-15 19:53:15.370578389 +0000
+++ ssh_config.5.new 2025-02-16 01:49:41.156839680 +0000
@@ -92,7 +92,7 @@ which are not the default in
.Pa /etc/ssh/ssh_config.d/*.conf
files are included at the start of the system-wide configuration file, so
options set there will override those in
-.Pa /etc/ssh/ssh_config.
+.Pa /etc/ssh/ssh_config .
.Pp
The file contains keyword-argument pairs, one per line.
Lines starting with
@@ -227,7 +227,7 @@ supplied list of networks in CIDR format
This may be convenient for varying the effective configuration on devices that
roam between networks.
Note that network address is not a trustworthy criteria in many
-situations (e.g. when the network is automatically configured using DHCP)
+situations (e.g.\& when the network is automatically configured using DHCP)
and so caution should be applied if using it to control security-sensitive
configuration.
.Pp
@@ -399,7 +399,7 @@ host.
Specifies the maximum number of dot characters in a hostname before
canonicalization is disabled.
The default, 1,
-allows a single dot (i.e. hostname.subdomain).
+allows a single dot (i.e.\& hostname.subdomain).
.It Cm CanonicalizePermittedCNAMEs
Specifies rules to determine whether CNAMEs should be followed when
canonicalizing hostnames.
@@ -443,7 +443,7 @@ If the specified list begins with a
character, then the specified algorithms will be appended to the default set
instead of replacing them.
If the specified list begins with a
-.Sq -
+.Sq \-
character, then the specified algorithms (including wildcards) will be removed
from the default set instead of replacing them.
.Pp
@@ -549,7 +549,7 @@ Open X11 forwarding sessions.
.El
.Pp
Note that in all the above cases, terminating an inactive session does not
-guarantee to remove all resources associated with the session, e.g. shell
+guarantee to remove all resources associated with the session, e.g.\& shell
processes or X11 clients relating to the session may continue to execute.
.Pp
Moreover, terminating an inactive channel or session does not necessarily
@@ -583,7 +583,7 @@ If the specified list begins with a
character, then the specified ciphers will be appended to the default set
instead of replacing them.
If the specified list begins with a
-.Sq -
+.Sq \-
character, then the specified ciphers (including wildcards) will be removed
from the default set instead of replacing them.
If the specified list begins with a
@@ -613,7 +613,7 @@ aes128-...@openssh.com,aes256-gcm@openss
.Ed
.Pp
The list of available ciphers may also be obtained using
-.Qq ssh -Q cipher .
+.Qq ssh \-Q cipher .
.It Cm ClearAllForwardings
Specifies that all local, remote, and dynamic port forwardings
specified in the configuration files or on the command line be
@@ -684,7 +684,7 @@ X11 and
.Xr ssh-agent 1
forwarding is supported over these multiplexed connections, however the
display and agent forwarded will be the one belonging to the master
-connection i.e. it is not possible to forward multiple displays or agents.
+connection i.e.\& it is not possible to forward multiple displays or agents.
.Pp
Two additional options allow for opportunistic multiplexing: try to use a
master connection but fall back to creating a new one if one does not already
@@ -733,7 +733,7 @@ If set to
or 0,
then the master connection will remain in the background indefinitely
(until killed or closed via a mechanism such as the
-.Qq ssh -O exit ) .
+.Qq ssh \-O exit ) .
If set to a time in seconds, or a time in any of the formats documented in
.Xr sshd_config 5 ,
then the backgrounded master connection will automatically terminate
@@ -845,7 +845,7 @@ configuration option being set to
.Dq yes .
The recommended way to start X11 programs at a remote site is with
something like
-.Ic ssh -f host xterm ,
+.Ic ssh \-f host xterm ,
which is the same as
.Ic ssh host xterm
if the
@@ -970,22 +970,25 @@ The default is
.Cm no .
.It Cm GSSAPIClientIdentity
If set, specifies the GSSAPI client identity that ssh should use when
-connecting to the server. The default is unset, which means that the default
-identity will be used.
+connecting to the server.
+The default is unset,
+which means
+that the default identity will be used.
.It Cm GSSAPIDelegateCredentials
Forward (delegate) credentials to the server.
The default is
.Cm no .
.It Cm GSSAPIKeyExchange
-Specifies whether key exchange based on GSSAPI may be used. When using
-GSSAPI key exchange the server need not have a host key.
+Specifies whether key exchange based on GSSAPI may be used.
+When using GSSAPI key exchange the server need not have a host key.
The default is
.Dq no .
.It Cm GSSAPIRenewalForcesRekey
If set to
.Dq yes
then renewal of the client's GSSAPI credentials will force the rekeying of the
-ssh connection. With a compatible server, this will delegate the renewed
+ssh connection.
+With a compatible server, this will delegate the renewed
credentials to a session on the server.
.Pp
Checks are made to ensure that credentials are only propagated when the new
@@ -1000,14 +1003,16 @@ For this to work
needs to be enabled in the server and also used by the client.
.It Cm GSSAPIServerIdentity
If set, specifies the GSSAPI server identity that ssh should expect when
-connecting to the server. The default is unset, which means that the
-expected GSSAPI server identity will be determined from the target
-hostname.
+connecting to the server.
+The default is unset,
+which means that the expected GSSAPI server identity will be determined
+from the target hostname.
.It Cm GSSAPITrustDns
Set to
.Dq yes
to indicate that the DNS is trusted to securely canonicalize
-the name of the host being connected to. If
+the name of the host being connected to.
+If
.Dq no ,
the hostname entered on the
command line will be passed untouched to the GSSAPI library.
@@ -1015,7 +1020,8 @@ The default is
.Dq no .
.It Cm GSSAPIKexAlgorithms
The list of key exchange algorithms that are offered for GSSAPI
-key exchange. Possible values are
+key exchange.
+Possible values are
.Bd -literal -offset 3n
gss-gex-sha1-,
gss-group1-sha1-,
@@ -1027,7 +1033,8 @@ gss-curve25519-sha256-
.Ed
.Pp
The default is
-.Dq
gss-group14-sha256-,gss-group16-sha512-,gss-nistp256-sha256-,gss-curve25519-sha256-,gss-gex-sha1-,gss-group14-sha1-
.
+.Dq gss-group14-sha256-,\:gss-group16-sha512-,\:gss-nistp256-sha256-,\
+\:gss-curve25519-sha256-,\:gss-gex-sha1-,\:gss-group14-sha1- .
This option only applies to connections using GSSAPI.
.It Cm HashKnownHosts
Indicates that
@@ -1057,7 +1064,7 @@ Alternately if the specified list begins
character, then the specified signature algorithms will be appended
to the default set instead of replacing them.
If the specified list begins with a
-.Sq -
+.Sq \-
character, then the specified signature algorithms (including wildcards)
will be removed from the default set instead of replacing them.
If the specified list begins with a
@@ -1103,7 +1110,7 @@ Alternately if the specified list begins
character, then the specified signature algorithms will be appended to
the default set instead of replacing them.
If the specified list begins with a
-.Sq -
+.Sq \-
character, then the specified signature algorithms (including wildcards)
will be removed from the default set instead of replacing them.
If the specified list begins with a
@@ -1131,7 +1138,7 @@ If hostkeys are known for the destinatio
to prefer their algorithms.
.Pp
The list of available signature algorithms may also be obtained using
-.Qq ssh -Q HostKeyAlgorithms .
+.Qq ssh \-Q HostKeyAlgorithms .
.It Cm HostKeyAlias
Specifies an alias that should be used instead of the
real host name when looking up or saving the host key
@@ -1176,7 +1183,7 @@ This option is intended for situations w
offers many different identities.
.It Cm IdentityAgent
Specifies the
-.Ux Ns -domain
+.Ux Ns \-domain
socket used to communicate with the authentication agent.
.Pp
This option overrides the
@@ -1226,7 +1233,7 @@ If no certificates have been explicitly
.Xr ssh 1
will try to load certificate information from the filename obtained by
appending
-.Pa -cert.pub
+.Pa \-cert.pub
to the path of a specified
.Cm IdentityFile .
.Pp
@@ -1364,7 +1371,7 @@ If the specified list begins with a
character, then the specified algorithms will be appended to the default set
instead of replacing them.
If the specified list begins with a
-.Sq -
+.Sq \-
character, then the specified algorithms (including wildcards) will be removed
from the default set instead of replacing them.
If the specified list begins with a
@@ -1385,7 +1392,7 @@ diffie-hellman-group14-sha256
.Ed
.Pp
The list of supported key exchange algorithms may also be obtained using
-.Qq ssh -Q kex .
+.Qq ssh \-Q kex .
.It Cm KnownHostsCommand
Specifies a command to use to obtain a list of host keys, in addition to
those listed in
@@ -1501,7 +1508,7 @@ If the specified list begins with a
character, then the specified algorithms will be appended to the default set
instead of replacing them.
If the specified list begins with a
-.Sq -
+.Sq \-
character, then the specified algorithms (including wildcards) will be removed
from the default set instead of replacing them.
If the specified list begins with a
@@ -1510,7 +1517,7 @@ character, then the specified algorithms
default set.
.Pp
The algorithms that contain
-.Qq -etm
+.Qq \-etm
calculate the MAC after encryption (encrypt-then-mac).
These are considered safer and their use recommended.
.Pp
@@ -1524,7 +1531,7 @@ hmac-sha2-256,hmac-sha2-512,hmac-sha1
.Ed
.Pp
The list of available MAC algorithms may also be obtained using
-.Qq ssh -Q mac .
+.Qq ssh \-Q mac .
.It Cm NoHostAuthenticationForLocalhost
Disable host authentication for localhost (loopback addresses).
The argument to this keyword must be
@@ -1553,7 +1560,7 @@ or an interval specifier of the form
(e.g.\&
.Cm interval:80
for 80 milliseconds).
-The default is to obscure keystrokes using a 20ms packet interval.
+The default is to obscure keystrokes using a 20\~ms packet interval.
Note that smaller intervals will result in higher fake keystroke packet rates.
.It Cm PasswordAuthentication
Specifies whether to use password authentication.
@@ -1650,7 +1657,7 @@ and should read from its standard input
It should eventually connect an
.Xr sshd 8
server running on some machine, or execute
-.Ic sshd -i
+.Ic sshd \-i
somewhere.
Host key management will be done using the
.Cm Hostname
@@ -1668,7 +1675,7 @@ and its proxy support.
For example, the following directive would connect via an HTTP proxy at
192.0.2.0:
.Bd -literal -offset 3n
-ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
+ProxyCommand /usr/bin/nc \-X connect \-x 192.0.2.0:8080 %h %p
.Ed
.It Cm ProxyJump
Specifies one or more jump proxies as either
@@ -1696,7 +1703,7 @@ disables this option entirely.
.Pp
Note that this option will compete with the
.Cm ProxyCommand
-option - whichever is specified first will prevent later instances of the
+option \(en whichever is specified first will prevent later instances of the
other from taking effect.
.Pp
Note also that the configuration for the destination host (either supplied
@@ -1720,7 +1727,7 @@ If the specified list begins with a
character, then the algorithms after it will be appended to the default
instead of replacing it.
If the specified list begins with a
-.Sq -
+.Sq \-
character, then the specified algorithms (including wildcards) will be removed
from the default set instead of replacing them.
If the specified list begins with a
@@ -1745,7 +1752,7 @@ rsa-sha2-512,rsa-sha2-256
.Ed
.Pp
The list of available signature algorithms may also be obtained using
-.Qq ssh -Q PubkeyAcceptedAlgorithms .
+.Qq ssh \-Q PubkeyAcceptedAlgorithms .
.It Cm PubkeyAuthentication
Specifies whether to try public key authentication.
The argument to this keyword must be
@@ -1771,9 +1778,9 @@ or
.Sq G
to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
The default is between
-.Sq 1G
+.Sq 1\~GB
and
-.Sq 4G ,
+.Sq 4\~GB ,
depending on the cipher.
The optional second value is specified in seconds and may use any of the
units documented in the TIME FORMATS section of
@@ -1929,7 +1936,7 @@ for more information on patterns.
It is possible to clear previously set
.Cm SendEnv
variable names by prefixing patterns with
-.Pa - .
+.Pa \- .
The default is not to send any environment variables.
.It Cm ServerAliveCountMax
Sets the number of server alive messages (see below) which may be
@@ -2165,7 +2172,7 @@ Additional hostkeys are only accepted if
host was already trusted or explicitly accepted by the user, the host was
authenticated via
.Cm UserKnownHostsFile
-(i.e. not
+(i.e.\& not
.Cm GlobalKnownHostsFile )
and the host was authenticated using a plain key and not a certificate.
.Pp
@@ -2272,7 +2279,7 @@ the following pattern could be used:
.Dl Host *.co.uk
.Pp
The following pattern
-would match any host in the 192.168.0.[0-9] network range:
+would match any host in the 192.168.0.[0\(en9] network range:
.Pp
.Dl Host 192.168.0.?
.Pp
@@ -2365,7 +2372,7 @@ tunnel forwarding was requested, or
.Qq NONE
otherwise.
.It %t
-The type of the server host key, e.g.
+The type of the server host key, e.g.\&
.Cm ssh-ed25519 .
.It %u
The local username.
@@ -2404,7 +2411,7 @@ Note that some of these directives build
Because
.Xr ssh 1
performs no filtering or escaping of characters that have special meaning in
-shell commands (e.g. quotes), it is the user's responsibility to ensure that
+shell commands (e.g.\& quotes), it is the user's responsibility to ensure that
the arguments passed to
.Xr ssh 1
do not contain such characters and that tokens are appropriately quoted
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
