openssh bugs - Oct 2020 - [Bug 3223] New: Issues in openssh manpages

https://bugzilla.mindrot.org/show_bug.cgi?id=3223

            Bug ID: 3223
           Summary: Issues in openssh manpages
           Product: Portable OpenSSH
           Version: 8.4p1
          Hardware: All
                OS: All
            Status: NEW
          Severity: trivial
          Priority: P5
         Component: Documentation
          Assignee: unassigned-bugs at mindrot.org
          Reporter: debian at helgefjell.de

Dear openssh maintainer,
the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including openssh) as
well for a large variety of target languages.

During their work translators notice different possible issues in the
original (english) man pages. Sometimes this is a straightforward
typo, sometimes a hard to read sentence, sometimes this is a
convention not held up and sometimes we simply do not understand the
original.

We use several distributions as sources and update regularly (at
least every 2 month). This means we are fairly recent (some
distributions like archlinux also update frequently) but might miss
the latest upstream version once in a while, so the error might be
already fixed. We apologize and ask you to close the issue immediately
if this should be the case, but given the huge volume of projects and
the very limited number of volunteers we are not able to double check
each and every issue.

Secondly we translators see the manpages in the neutral po format,
i.e. converted and harmonized, but not the original source (be it man,
groff, xml or other). So we cannot provide a true patch (where
possible), but only an approximation which you need to convert into
your source format.

Finally the issues I'm reporting have accumulated over time and are
not always discovered by me, so sometimes my description of the
problem my be a bit limited - do not hesitate to ask so we can clarify
them.

I'm now reporting the errors for your project. If future reports
should use another channel, please let me know.

Man page: sftp.1
Issue: Broken wrapping, everything before "Display" belongs to the
command

"E<.Op Fl hi> E<.Op Ar path> E<.Xc> Display usage
information for the "
"filesystem holding the current directory (or E<.Ar path> if
specified).  If "
"the E<.Fl h> flag is specified, the capacity information will be
displayed "
"using \"human-readable\" suffixes.  The E<.Fl i> flag
requests display
of "
"inode information in addition to capacity information.  This command
is only "
"supported on servers that implement the E<.Dq statvfs at
openssh.com>
extension."
--
Man page: sftp.1
Issue: Broken wrapping, everything before "Retrieve" belongs to the
command

"E<.Op Fl afPpr> E<.Ar remote-path> E<.Op Ar local-path>
E<.Xc>
Retrieve the "
"E<.Ar remote-path> and store it on the local machine.  If the local
path "
"name is not specified, it is given the same name it has on the remote
"
"machine.  E<.Ar remote-path> may contain E<.Xr glob 7>
characters and
may "
"match multiple files.  If it does and E<.Ar local-path> is
specified,
then "
"E<.Ar local-path> must specify a directory."
--
Man page: sftp.1
Issue: Broken wrapping, everything before "Create" belongs to the
command

"E<.Op Fl s> E<.Ar oldpath> E<.Ar newpath> E<.Xc>
Create a link from
E<.Ar "
"oldpath> to E<.Ar newpath>.  If the E<.Fl s> flag is
specified the
created "
"link is a symbolic link, otherwise it is a hard link."
--
Man page: sftp.1
Issue: Broken wrapping, everything before "Display" belongs to the
command

"E<.Op Fl 1afhlnrSt> E<.Op Ar path> E<.Xc> Display a
remote directory
listing "
"of either E<.Ar path> or the current directory if E<.Ar path>
is not "
"specified.  E<.Ar path> may contain E<.Xr glob 7> characters
and may
match "
"multiple files."
--
Man page: sftp.1
Issue: Is this missing a dash?

"OpenSSH secure file transfer"
--
Man page: ssh-agent.1
Issue: eg ? e.g.

"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 E<.Cm ssh-agent xterm &>.  The second is that the agent
prints the
needed "
"shell commands (either E<.Xr sh 1> or E<.Xr csh 1> syntax can
be
generated) "
"which can be evaluated in the calling shell, eg E<.Cm eval `ssh-agent
-s`> "
"for Bourne-type shells such as E<.Xr sh 1> or E<.Xr ksh 1> and
E<.Cm
eval "
"`ssh-agent -c`> for E<.Xr csh 1> and derivatives."
--
Man page: ssh-agent.1
Issue: ssh-agent. ? E<.Nm>

"In Debian, E<.Nm> is installed with the set-group-id bit set, to
prevent E<."
"Xr ptrace 2> attacks retrieving private key material.  This has the
side-"
"effect of causing the run-time linker to remove certain environment "
"variables which might have security implications for set-id programs,
"
"including E<.Ev LD_PRELOAD>, E<.Ev LD_LIBRARY_PATH>, and
E<.Ev
TMPDIR>.  If "
"you need to set any of these environment variables, you will need to
do so "
"in the program executed by ssh-agent."
--
Man page: ssh-agent.1
Issue: ssh(1) does not have a section caveats

"Connections to E<.Nm> may be forwarded from further remote hosts
using
the "
"E<.Fl A> option to E<.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."
--
Man page: ssh-keygen.1
Issue: private keys ? prvivate key?

"Requests changing the comment in the private and public key files. 
The "
"program will prompt for the file containing the private keys, for the
"
"passphrase if the key has one, and for the new comment."
--
Man page: ssh-keygen.1
Issue: safety ? security?

"Test DH group exchange candidate primes (generated using the E<.Fl
G>
"
"option) for safety."
--
Man page: ssh-keygen.1
Issue: 2011). ? 2011),

"For example: E<.Dq +52w1d> (valid from now to 52 weeks and one day
from "
"now), E<.Dq -4w:+4w> (valid from four weeks ago to four weeks from
now), E<."
"Dq 20100101123000:20110101123000> (valid from 12:30 PM, January 1st,
2010 to "
"12:30 PM, January 1st, 2011), E<.Dq -1d:20110101> (valid from
yesterday to "
"midnight, January 1st, 2011).  E<.Dq -1m:forever> (valid from one
minute ago "
"and never expiring)."
--
Man page: ssh-keygen.1
Issue: By default, the validity of certificates starts with the E<.Ux>
Epoch and is unlimited.

"Finally, certificates may be defined with a validity lifetime.  The
E<.Fl V> "
"option allows specification of certificate start and end times.  A "
"certificate that is presented at a time outside this range will not be
"
"considered valid.  By default, certificates are valid from E<.Ux>
Epoch to "
"the distant future."
--
Man page: ssh-keygen.1
Issue: See ? see

"The principals field is a pattern-list (See PATTERNS in E<.Xr
ssh_config "
"5>)  consisting of one or more comma-separated USER at DOMAIN identity
patterns "
"that are accepted for signing.  When verifying, the identity presented
via "
"the E<.Fl I> option must match a principals pattern in order for the
"
"corresponding key to be considered acceptable for verification."

-- 
You are receiving this mail because:
You are watching the assignee of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=3223

Darren Tucker <dtucker at dtucker.net> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |dtucker at dtucker.net

--- Comment #1 from Darren Tucker <dtucker at dtucker.net> ---
(In reply to Helge Kreutzmann from comment #0)
[...]
> Man page: sftp.1
> Issue: Broken wrapping, everything before "Display" belongs to
the
> command
This does not exist upstream.  The formatted version of the upstream
man page looks like

```
     df [-hi] [path]
             Display usage information for the 
```

The same applies to the following three items.
> Man page: sftp.1
> Issue: Is this missing a dash?
No.
> "OpenSSH secure file transfer"
> --
> Man page: ssh-agent.1
> Issue: eg ? e.g.
> 
> "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 E<.Cm ssh-agent xterm &>.
This text does not exist in OpenSSH's man page:

```
     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 ssh-agent program.  The agent starts a command
under
     which its environment variables are exported, for example
ssh-agent xterm
     &.  When the command terminates, so does the agent.
```
> --
> Man page: ssh-agent.1
> Issue: ssh-agent. ? E<.Nm>
> 
> "In Debian, E<.Nm> is installed with the set-group-id bit set,
to
> prevent E<."
This text also does not exist in the upstream text and looks like a
Debian modification.
> Man page: ssh-agent.1
> Issue: ssh(1) does not have a section caveats
err, OK.  So?
> Man page: ssh-keygen.1
> Issue: private keys ? prvivate key?
Definitely no.
> Man page: ssh-keygen.1
> Issue: safety ? security?
> 
> "Test DH group exchange candidate primes (generated using the E<.Fl
> G> "
> "option) for safety."
No.  Safe primes are a specific concept:
https://en.wikipedia.org/wiki/Safe_and_Sophie_Germain_primes
> --
> Man page: ssh-keygen.1
> Issue: 2011). ? 2011),
Yes.
> Man page: ssh-keygen.1
> Issue: By default, the validity of certificates starts with the
> E<.Ux> Epoch and is unlimited.
the capitalization?  probably yes.
> --
> Man page: ssh-keygen.1
> Issue: See ? see
Yes.

-- 
You are receiving this mail because:
You are watching someone on the CC list of the bug.
You are watching the assignee of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=3223

--- Comment #2 from Darren Tucker <dtucker at dtucker.net> ---
Created attachment 3452
  --> https://bugzilla.mindrot.org/attachment.cgi?id=3452&action=edit
fix identified man page nits

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
You are watching someone on the CC list of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=3223

Darren Tucker <dtucker at dtucker.net> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Blocks|                            |3217


Referenced Bugs:

https://bugzilla.mindrot.org/show_bug.cgi?id=3217
[Bug 3217] Tracking bug for 8.5 release
-- 
You are receiving this mail because:
You are watching the assignee of the bug.
You are watching someone on the CC list of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=3223

--- Comment #3 from Darren Tucker <dtucker at dtucker.net> ---
(In reply to Darren Tucker from comment #1)
> > Man page: ssh-keygen.1
> > Issue: By default, the validity of certificates starts with the
> > E<.Ux> Epoch and is unlimited.
> 
> the capitalization?  probably yes.
Our man page expert prefers the existing text including the
capitalization "from UNIX Epoch to the distant future." so I'm
removing
that part.

-- 
You are receiving this mail because:
You are watching someone on the CC list of the bug.
You are watching the assignee of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=3223

Darren Tucker <dtucker at dtucker.net> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Resolution|---                         |FIXED
             Status|NEW                         |RESOLVED

--- Comment #4 from Darren Tucker <dtucker at dtucker.net> ---
I've committed the changes, thanks for the report.

The changes will be visible soon on
https://man.openbsd.org/ssh-keygen.1 and
https://github.com/openssh/openssh-portable/blob/master/ssh-keygen.1

-- 
You are receiving this mail because:
You are watching someone on the CC list of the bug.
You are watching the assignee of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=3223

Damien Miller <djm at mindrot.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|RESOLVED                    |CLOSED

--- Comment #5 from Damien Miller <djm at mindrot.org> ---
close bugs that were resolved in OpenSSH 8.5 release cycle

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
You are watching someone on the CC list of the bug.