This is the mail archive of the cygwin mailing list for the Cygwin project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Cygwin & openssh(d) & login without password

On Tue, 5 Oct 2004 10:47:57 +0200, Corinna Vinschen <> wrote:
On Oct 5 16:00, David Campbell wrote:
I've read lots of web pages about how to set it up, and I believe I've
followed them, eg (for openssh to

OpenSSH comes with a lot of man pages. Then there's /usr/share/doc/Cygwin/openssh.README.
Then you could have used ssh-host-config and ssh-user-config for the
basic configuration.

BECAUSE in the case of openssh(and others), the "official documentation" is of little use to a new user: information is not gathered, stored, or presented in a orderly, logical, or sensible hierarchical manner, is not meaningfully cross-referenced, and is not reasonably searchable. There's just no usable thread to pull to unravel the mystery, either.

Let's examine the steps a new user might pursue:

1. A new user types 'help' and is presented with shell help. Luckily, there's a mention of 'man -k'(which doesn't work) and 'info'.

2. The user might type 'help openssh' and be told to "try 'man -k openssh' which produces "openssh: nothing appropriate", a nice showstopper. IF enterprising (and unafraid of the command line) enough, one _might_ try 'man openssh', and 'info openssh' and be met with stony silence.

3. One may try 'help ssh' and be told to "try 'man -k ssh' which produces "ssh: nothing appropriate", another showstopper. One _might_ ultimately try 'man ssh' instead and get (sort of) lucky.

4. 'man' and 'info' pages for ssh and sshd don't refer to /usr/share/doc/Cygwin/openssh.README, nor to /usr/share/doc/ssh/ssh-host-config or ssh-user-config. So the new user is confronted with a brightly lit maze of lucidly defined options and configuration information.

5. A search using 'find / -name openssh*' does find appropriate directories, and even the README. However, 'find' is ill-behaved: alone on a command line, it prints a _full recursive tree_ of the current directory. It's counterintuitive, and ill-documented. 'man find' shows no functional examples. 'find --help' lists options, not ordered by likelyhood of use, but _alphabetically_. Only 'info find' shows a useful example. And if the unlucky user forgets to type 'openssh*', they'll miss the README file. Nice.

6. If a user has by some miracle heard of 'locate', a search using 'locate openssh' produces no results unless the user first runs 'updatedb'.

7. So someone in a hurry is likely instead to go out-of band:
7a. Google for "cygwin openssh setup" produces NO useful official documentation in the first 50 results. In fact, the very first result is the . This resource has been maligned in this very cygwin list.
7b. Windows Find "openssh" finds whatever _might_ be there to see.

8. Let's say the user somehow finds openssh.README. Who the HELL decided to put the "If you are installing OpenSSH the first time" at the END of a four-page document? Wading through panicky "important change" notices is rather pure torture, and irrelevant to the new user.

So these little unfindable jewels exist not to be used _by_ new users, but to be shot _at_ new users in ascerbic opprobrium.

To make the docs _easy_ to find would go against the dinosaur mentality of "Back in the day, I had to read all the docs before I could do anything, and now so do you." The major difference being that back in the day, all the docs fit in a 1/4" booklet. Now the task of forcing the user to imagine, compose a search for, search for, find, read, interpret, and correctly apply the hidden, terse, ultimately unhelpful, poorly referenced "official documentation" is simply onerous.

So, let's have no more asking new users why they didn't read the official documentation, then, eh? They have _very good reasons_ for not doing so.

-- Unsubscribe info: Problem reports: Documentation: FAQ:

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]