Add a fix to the LDAP article to allow users logging in when /bin/bash is set in the user profile of the LDAP server

[bcr]

Summary

This patch contains a fix that is described in the FreeBSD forums by the user melco:
https://forums.freebsd.org/threads/ldap-authentication-fails-for-users-not-in-etc-passwd.27276/#post-236877

The problem is that if you have correctly set up your LDAP client to authenticate against an LDAP server (on Linux), but the user profile on the server contains /bin/bash, that user can not log in. You need to tell the client that on FreeBSD, bash is installed in /usr/local/bin/bash.
I had this exact same problem on my systems and a few users on the forums as well, so I think this warrants inclusion in the article.

On a wider scale, we might think about integrating the article in the handbook (at least the client part), but that is a topic for another day and another review...

Test Plan

1. Read the fix on the forums (link above)
2. Apply the patch
3. Review thoroughly (sprinkle english grammar, typo fixes, and better sentences on it)

[wblock]

article.xml

453 ↗

(On Diff #7280)

The first two sentences can be combined to avoid some of the if/then pauses.

Users whose shell is not in <filename>/etc/shells</filename> will not be able to log in.

"Especially true" is a little weird. Maybe "particularly important" instead?

454 ↗

(On Diff #7280)

"users shell" should be possessive, but we can avoid that by just saying "user shell".

455 ↗

(On Diff #7280)

<application>bash</application> is not included with a default installation of &os;.
When installed from a package or port, it is located at <filename>/usr/local/bin/bash</filename>.

459 ↗

(On Diff #7280)

Verify that the path to the shell on the server is set correctly:

465 ↗

(On Diff #7280)

Avoid if/then, avoid informal "you", avoid "the following", passive->active (will be->is):

There are two choices when the output shows <literal>/bin/bash</literal> in the last column.
The first is to change the user's entry on the LDAP server to <filename>/usr/local/bin/bash</filename>.
The second option is to create a symlink on the LDAP client so <application>bash</application> is found
at the correct location:

477 ↗

(On Diff #7280)

Try to avoid starting sentences with a pause like this. It makes them halting to read. It can be said later in the sentence, or even avoided completely:

Make sure that <filename>/etc/shells</filename> contains entries for both
<literal>/usr/local/bin/bash</literal> and <literal>/bin/bash</literal>.

480 ↗

(On Diff #7280)

The "after that" just adds a pause, but is not really needed.

The user will then be able to log into the system with <application>bash</application> as their shell.</para>

[wblock]

See https://wiki.freebsd.org/CodeReview#Create_a_Revision_via_Web_Interface about including context in the diff.

Also, it helps to run that from the doc/ directory, so the pathname tells which article or book is being patched.

Thanks!

[bcr]

Address the valuable comments by Warren, thanks for that. The only issue I have now is that one sentence does start with a lowercase bash because of the application tags.

[wblock]

"bash" is not a normal word here. It is a proper name or reserved word, something special, and the markup will make that clear when rendered. There are grammar rules that say a sentence must always begin with an uppercase letter*. The filename here is lowercase. The name of the application is capitalized, inconsistently with the filename. So this is easy to fix: in <application> tags, it's always just "Bash". In <filename> or <command>, it will be either /usr/local/bin/bash or just bash.

• However, those rules usually add "unless it changes the meaning of the word". So if the word is a case-sensitive command, function, or variable name, do not change the case. Or a name that has been specified as capitalized strangely, like iPad or eBay.

en_US.ISO8859-1/articles/ldap-auth/article.xml

454 ↗

(On Diff #7288)

As per my full comment:
<application>Bash</application>

455 ↗

(On Diff #7288)

As per my full comment:
<application>Bash</application>

468 ↗

(On Diff #7288)

As per my full comment:
<application>Bash</application>

476 ↗

(On Diff #7288)

As per my full comment:
<application>Bash</application>

[bcr]

Capitalize Bash within <application> tags.

[wblock]

en_US.ISO8859-1/articles/ldap-auth/article.xml

453 ↗

(On Diff #7293)

This sentence somehow sounds wrong with "It" instead of "This". I'd say it was because "it" is nonspecific, but "this" is not specific either.

467 ↗

(On Diff #7293)

"on the LDAP client" is a little vague. The reader might ask whether this is a client computer, or a client application running on a server.

476 ↗

(On Diff #7293)

This looked a little weird before, still does. I think "log into" should be "log in to".

[bcr]

Address comments. New patch follows...

en_US.ISO8859-1/articles/ldap-auth/article.xml

453 ↗

(On Diff #7293)

It sounds better with "this" (or is it. "This sounds better with "this"). ;-)
Specifics aside, I think it is clear from context with the previous sentence that "this" refers to the problem of not being able to log in.

467 ↗

(On Diff #7293)

I rewrote it to LDAP client computer, to make it clear where it is (not the server). Since this whole section is about client config, it should be clear. The previous section is about the server setup, so the distinction is there by the sectioning, although we mention the server here when describing the problem.

476 ↗

(On Diff #7293)

I changed it to separate words to make it consistent with the beginning of the patch.

[bcr]

Address Warren's comments.

[wblock]

Looks good. Please check with igor (phabricator makes indentation very difficult to see). And build-test. Thanks!

[bcr]

Great, thank you Warren!