hosts.equiv.5: Fix format, clarify IdM needs, and provide examples.

Arjun,

As promised. Does this look good to you?

Michael,

In some recent work with a Red Hat customer I had the opportunity to discuss the fine nuances of the ruserok() function and related API which are used to implement rlogin and rsh.

It came to my attention after working with QE on some automated internal testing that there were no good examples in the hosts.equiv manual page showing how the format was supposed to work for this file and for ~/.rhosts, worse the "format" line showed that there should be spaces between arguments when that would clearly lead to incorrect behaviour. In addition some things that the format allows you to write are just wrong like "-host -user" which makes no sense since the host is already rejected, and should be written as "host -user" instead. I added notes in the example to make it clear that "-host -user" is invalid.

I fixed three things:

(a) The format line.
- Either +, or [-]hostname, or +@netgrp or -@netgrp.
- Either +, or [-]username, or +@netgrp or -@netgrp.
- You must specify something in the hostname portion so remove optional brackets.

(b) Clarify language around credentials
- If the host is not trusted you must provide credentials to the login system and that could be anything really and it depends on your configuration e.g. PAM or whatever IdM you have.

(c) Provide real-world examples
- Provide several real world examples and some corner case examples for how you would write something. Hopefully others can add examples as they see fit.

Patch applies to trunk.

Signed-off-by Carlos O'Donell <[email protected]>

man5/hosts.equiv.5 +110 -4

index 89d0b4a..c8e85ac 100644
@@ -22,7 +22,7 @@ supplying a password.
 .PP
 The file uses the following format:
 .TP
-\fI[ + | \- ]\fP \fI[hostname]\fP \fI[username]\fP
+\fI+|[\-]hostname|+@netgroup|\-@netgroup\fP \fI[+|[\-]username|+@netgroup|\-@netgroup]\fP
 .PP
 The
 .I hostname

@@ -37,9 +37,9 @@ If the plus sign is used alone, it allows any host to access your system.
 You can explicitly deny access to a host by preceding the
 .I hostname
 by a minus (\-) sign.
-Users from that host must always supply a password.
-For security reasons you should always use the FQDN of the hostname and
-not the short hostname.
+Users from that host must always supply additional credentials,
+including possibly a password. For security reasons you should always
+use the FQDN of the hostname and not the short hostname.
 .PP
 The
 .I username

@@ -81,6 +81,112 @@ character which means "any host" only when the word
 is added to the auth component line in your PAM file for
 the particular service
 .RB "(e.g., " rlogin ).
+.SH EXAMPLE
+Here are some example
+.I /etc/host.equiv
+or
+.I ~/.rhosts
+files:
+.TP
+Allow any user to login from any host:
+.LP
+.RS 4
+.TP
++
+.PD
+.RE
+.TP
+Allow any user from host with a matching local account to login:
+.LP
+.RS 4
+.TP
+host
+.PD
+.RE
+.PP
+Note: The use of
+.B +host
+is never a valid syntax, including attempting to specify that any user from the host is allowed.
+.TP
+Allow any user from host to login:
+.LP
+.RS 4
+.TP
+host +
+.PD
+.RE
+.PP
+Note: This is distinct from the previous example since it does not require a matching local account.
+.TP
+Allow user from host to login:
+.LP
+.RS 4
+.TP
+host user
+.PD
+.RE
+.TP
+Allow all users with matching local accounts from host to login except for baduser:
+.LP
+.RS 4
+.PD 0
+.TP
+host -baduser
+.TP
+host
+.PD
+.RE
+.TP
+Deny all users from host:
+.LP
+.RS 4
+.TP
+-host
+.PD
+.RE
+.PP
+Note: The use of
+.B -host -user
+is never a valid syntax, including attempting to specify that a particular user from the host is not trusted.
+.TP
+Allow all users with matching local accounts in all hosts in the netgroup:
+.LP
+.RS 4
+.TP
++@netgroup
+.PD
+.RE
+.TP
+Disallow all users in all hosts in the netgroup:
+.LP
+.RS 4
+.TP
+-@netgroup
+.PD
+.RE
+.TP
+Allow all users in netgroup to login from host:
+.LP
+.RS 4
+.TP
+host +@netgroup
+.PD
+.RE
+.TP
+Allow all users with matching local accounts in all hosts in the netgroup except baduser:
+.LP
+.RS 4
+.PD 0
+.TP
++@netgroup -baduser
+.TP
++@netgroup
+.PD
+.RE
+.TP
+Note: The deny statements must always preceed the allow statements because the file is processed one line at a time.
+
+
 .SH SEE ALSO
 .BR rhosts (5),
 .BR rlogind (8),

Quoted 3 lines · Carlos O'Donell

Arjun,

As promised. Does this look good to you?

Just a note: I'm hoping for a response from Arjun before I commit this.

Quoted 6 lines · Michael Kerrisk (man-pages)

Quoted 3 lines · Carlos O'Donell

Arjun,

As promised. Does this look good to you?

Just a note: I'm hoping for a response from Arjun before I commit this.

Hope is not a plan :-)

I do not feel that a response from Arjun is required, and if I missed any cases that Arjun considers should be described in more detail we can add those later.

Please apply.

Quoted 1 line

Just a note: I'm hoping for a response from Arjun before I commit this.

Hope is not a plan :-)

Quoted 2 lines

Quoted 1 line

Just a note: I'm hoping for a response from Arjun before I commit this.

Hope is not a plan :-)

I see that I got here a little late. This looks good, but I have one nitpick:

Review

Quoted 5 lines

(quoted diff) +5 -0

+Allow user from host to login:
+.LP
+.RS 4
+.TP
+host user

It might make sense to repeat here that such an entry will allow the specified user on the remote host to login as *any* user on the local host.

i.e., something like:

Quoted 17 lines · Arjun Shankar

Quoted 2 lines

Quoted 1 line

Just a note: I'm hoping for a response from Arjun before I commit this.

Hope is not a plan :-)

I see that I got here a little late. This looks good, but I have one nitpick:

Review

Quoted 5 lines

(quoted diff) +5 -0

+Allow user from host to login:
+.LP
+.RS 4
+.TP
+host user

It might make sense to repeat here that such an entry will allow the specified user on the remote host to login as *any* user on the local host.

i.e., something like:

Review

Quoted 2 lines

(quoted diff) +1 -1

-Allow user from host to login:
+Allow user from host to login as any non-root user:

Good point.

Signed-off-by Carlos O'Donell <[email protected]>

man5/hosts.equiv.5 +1 -1

index b6ecb94..9ee0e6e 100644
@@ -116,7 +116,7 @@ Allow
 .I user
 from
 .I host
-to login:
+to login as any non-root user:
 
     host user
 

Quoted 2 lines

Quoted 1 line

Just a note: I'm hoping for a response from Arjun before I commit this.

Hope is not a plan :-)

I see that I got here a little late. This looks good, but I have one nitpick:

Review

Quoted 5 lines

(quoted diff) +5 -0

+Allow user from host to login:
+.LP
+.RS 4
+.TP
+host user

It might make sense to repeat here that such an entry will allow the specified user on the remote host to login as *any* user on the local host.

i.e., something like:

Carlos: when you have a moment, please review the current draft in Git and let me know if my edits injected any errors.

Quoted 2 lines · Michael Kerrisk (man-pages)

Carlos: when you have a moment, please review the current draft in Git and let me know if my edits injected any errors.

I don't see a draft branch nor changes to master?

Hi Carlos,

Quoted 5 lines · Carlos O'Donell

Quoted 2 lines · Michael Kerrisk (man-pages)

Carlos: when you have a moment, please review the current draft in Git and let me know if my edits injected any errors.

I don't see a draft branch nor changes to master?

Where are you looking? I can see hem at
http://git.kernel.org/cgit/docs/man-pages/man-pages.git

Quoted 11 lines · Michael Kerrisk (man-pages)

Hi Carlos,

Quoted 5 lines · Carlos O'Donell

Quoted 2 lines · Michael Kerrisk (man-pages)

Carlos: when you have a moment, please review the current draft in Git and let me know if my edits injected any errors.

I don't see a draft branch nor changes to master?

Where are you looking? I can see hem at
http://git.kernel.org/cgit/docs/man-pages/man-pages.git

I see the changes now.

You missed the second hunk of my patch which adds the same text to the +@netgroup example.

With that fixed it's OK.

Arjun,

As promised. Does this look good to you?

Michael,

In some recent work with a Red Hat customer I had the opportunity to discuss the fine nuances of the ruserok() function and related API which are used to implement rlogin and rsh.

It came to my attention after working with QE on some automated internal testing that there were no good examples in the hosts.equiv manual page showing how the format was supposed to work for this file and for ~/.rhosts, worse the "format" line showed that there should be spaces between arguments when that would clearly lead to incorrect behaviour. In addition some things that the format allows you to write are just wrong like "-host -user" which makes no sense since the host is already rejected, and should be written as "host -user" instead. I added notes in the example to make it clear that "-host -user" is invalid.

I fixed three things:

(a) The format line.
- Either +, or [-]hostname, or +@netgrp or -@netgrp.
- Either +, or [-]username, or +@netgrp or -@netgrp.
- You must specify something in the hostname portion so remove optional brackets.

(b) Clarify language around credentials
- If the host is not trusted you must provide credentials to the login system and that could be anything really and it depends on your configuration e.g. PAM or whatever IdM you have.

(c) Provide real-world examples
- Provide several real world examples and some corner case examples for how you would write something. Hopefully others can add examples as they see fit.

Patch applies to trunk.

Signed-off-by Carlos O'Donell <[email protected]>

man5/hosts.equiv.5 +98 -4

index 89d0b4a..c8e85ac 100644
@@ -22,7 +22,7 @@ supplying a password.
 .PP
 The file uses the following format:
 .TP
-\fI[ + | \- ]\fP \fI[hostname]\fP \fI[username]\fP
+\fI+|[\-]hostname|+@netgroup|\-@netgroup\fP \fI[+|[\-]username|+@netgroup|\-@netgroup]\fP
 .PP
 The
 .I hostname

@@ -37,9 +37,9 @@ If the plus sign is used alone, it allows any host to access your system.
 You can explicitly deny access to a host by preceding the
 .I hostname
 by a minus (\-) sign.
-Users from that host must always supply a password.
-For security reasons you should always use the FQDN of the hostname and
-not the short hostname.
+Users from that host must always supply additional credentials,
+including possibly a password. For security reasons you should always
+use the FQDN of the hostname and not the short hostname.
 .PP
 The
 .I username

@@ -81,6 +81,112 @@ character which means "any host" only when the word
 is added to the auth component line in your PAM file for
 the particular service
 .RB "(e.g., " rlogin ).
+.SH EXAMPLE
+Here are some example
+.I /etc/host.equiv
+or
+.I ~/.rhosts
+files:
+.TP
+Allow any user to login from any host:
+.LP
+.RS 4
+.TP
++
+.PD
+.RE
+.TP
+Allow any user from host with a matching local account to login:
+.LP
+.RS 4
+.TP
+host
+.PD
+.RE
+.PP
+Note: The use of
+.B +host
+is never a valid syntax, including attempting to specify that any user from the host is allowed.
+.TP
+Allow any user from host to login:
+.LP
+.RS 4
+.TP
+host +
+.PD
+.RE
+.PP
+Note: This is distinct from the previous example since it does not require a matching local account.
+.TP
+Allow user from host to login:
+.LP
+.RS 4
+.TP
+host user
+.PD
+.RE
+.TP
+Allow all users with matching local accounts from host to login except for baduser:
+.LP
+.RS 4
+.PD 0
+.TP
+host -baduser
+.TP
+host
+.PD
+.RE
+.TP
+Deny all users from host:
+.LP
+.RS 4
+.TP
+-host
+.PD
+.RE
+.PP
+Note: The use of
+.B -host -user
+is never a valid syntax, including attempting to specify that a particular user from the host is not trusted.
+.TP
+Allow all users with matching local accounts in all hosts in the netgroup:
+.LP
+.RS 4
+.TP
++@netgroup
+.PD
+.RE
+.TP
+Disallow all users in all hosts in the netgroup:
+.LP
+.RS 4
+.TP
+-@netgroup
+.PD
+.RE
+.TP
+Allow all users in netgroup to login from host:
+.LP
+.RS 4
+.TP
+host +@netgroup
+.PD
+.RE
+.TP
+Allow all users with matching local accounts in all hosts in the netgroup except baduser:
+.LP

Hi Carlos,

I've applied this patch, making a number of formatting changes along the way. You might want to review the (rendered) result.

One other comment bewlow

Quoted 167 lines · Carlos O'Donell

Arjun,

As promised. Does this look good to you?

Michael,

In some recent work with a Red Hat customer I had the opportunity to discuss the fine nuances of the ruserok() function and related API which are used to implement rlogin and rsh.

It came to my attention after working with QE on some automated internal testing that there were no good examples in the hosts.equiv manual page showing how the format was supposed to work for this file and for ~/.rhosts, worse the "format" line showed that there should be spaces between arguments when that would clearly lead to incorrect behaviour. In addition some things that the format allows you to write are just wrong like "-host -user" which makes no sense since the host is already rejected, and should be written as "host -user" instead. I added notes in the example to make it clear that "-host -user" is invalid.

I fixed three things:

(a) The format line.
- Either +, or [-]hostname, or +@netgrp or -@netgrp.
- Either +, or [-]username, or +@netgrp or -@netgrp.
- You must specify something in the hostname portion so remove optional brackets.

(b) Clarify language around credentials
- If the host is not trusted you must provide credentials to the login system and that could be anything really and it depends on your configuration e.g. PAM or whatever IdM you have.

(c) Provide real-world examples
- Provide several real world examples and some corner case examples for how you would write something. Hopefully others can add examples as they see fit.

Patch applies to trunk.

Signed-off-by Carlos O'Donell <[email protected]>

man5/hosts.equiv.5 +98 -4

index 89d0b4a..c8e85ac 100644
@@ -22,7 +22,7 @@ supplying a password.
 .PP
 The file uses the following format:
 .TP
-\fI[ + | \- ]\fP \fI[hostname]\fP \fI[username]\fP
+\fI+|[\-]hostname|+@netgroup|\-@netgroup\fP \fI[+|[\-]username|+@netgroup|\-@netgroup]\fP
 .PP
 The
 .I hostname

@@ -37,9 +37,9 @@ If the plus sign is used alone, it allows any host to access your system.
 You can explicitly deny access to a host by preceding the
 .I hostname
 by a minus (\-) sign.
-Users from that host must always supply a password.
-For security reasons you should always use the FQDN of the hostname and
-not the short hostname.
+Users from that host must always supply additional credentials,
+including possibly a password. For security reasons you should always
+use the FQDN of the hostname and not the short hostname.
 .PP
 The
 .I username

@@ -81,6 +81,112 @@ character which means "any host" only when the word
 is added to the auth component line in your PAM file for
 the particular service
 .RB "(e.g., " rlogin ).
+.SH EXAMPLE
+Here are some example
+.I /etc/host.equiv
+or
+.I ~/.rhosts
+files:
+.TP
+Allow any user to login from any host:
+.LP
+.RS 4
+.TP
++
+.PD
+.RE
+.TP
+Allow any user from host with a matching local account to login:
+.LP
+.RS 4
+.TP
+host
+.PD
+.RE
+.PP
+Note: The use of
+.B +host
+is never a valid syntax, including attempting to specify that any user from the host is allowed.
+.TP
+Allow any user from host to login:
+.LP
+.RS 4
+.TP
+host +
+.PD
+.RE
+.PP
+Note: This is distinct from the previous example since it does not require a matching local account.
+.TP
+Allow user from host to login:
+.LP
+.RS 4
+.TP
+host user
+.PD
+.RE
+.TP
+Allow all users with matching local accounts from host to login except for baduser:
+.LP
+.RS 4
+.PD 0
+.TP
+host -baduser
+.TP
+host
+.PD
+.RE
+.TP
+Deny all users from host:
+.LP
+.RS 4
+.TP
+-host
+.PD
+.RE
+.PP
+Note: The use of
+.B -host -user
+is never a valid syntax, including attempting to specify that a particular user from the host is not trusted.
+.TP
+Allow all users with matching local accounts in all hosts in the netgroup:
+.LP
+.RS 4
+.TP
++@netgroup
+.PD
+.RE
+.TP
+Disallow all users in all hosts in the netgroup:
+.LP
+.RS 4
+.TP
+-@netgroup
+.PD
+.RE
+.TP
+Allow all users in netgroup to login from host:
+.LP
+.RS 4
+.TP
+host +@netgroup
+.PD
+.RE
+.TP
+Allow all users with matching local accounts in all hosts in the netgroup except baduser:
+.LP

man5/hosts.equiv.5 character which means "any host" only when the word · line 187

Quoted 10 lines

man5/hosts.equiv.5 +10 -0

+.RS 4
+.PD 0
+.TP
++@netgroup -baduser
+.TP
++@netgroup
+.PD
+.RE
+.TP
+Note: The deny statements must always preceed the allow statements because the file is processed one line at a time.

This last explanation feels incomplete. Should it not be something like:

The deny statements must always precede the allow statements because the file is processed sequentially until the first matching rule is found.

?

man5/hosts.equiv.5 character which means "any host" only when the word · line 192

Quoted 5 lines

man5/hosts.equiv.5 +2 -0

+
+
 .SH SEE ALSO
 .BR rhosts (5),
 .BR rlogind (8),

Cheers,

Michael

Hi Carlos,

In this earlier reply, I should have highlighted that there is one open question I have about you patch, at the end of the mail below. Could you take a look please.

Cheers,

Michael

Quoted 201 lines · Michael Kerrisk (man-pages)

Hi Carlos,

I've applied this patch, making a number of formatting changes along the way. You might want to review the (rendered) result.

One other comment bewlow

Quoted 167 lines · Carlos O'Donell

Arjun,

As promised. Does this look good to you?

Michael,

In some recent work with a Red Hat customer I had the opportunity to discuss the fine nuances of the ruserok() function and related API which are used to implement rlogin and rsh.

It came to my attention after working with QE on some automated internal testing that there were no good examples in the hosts.equiv manual page showing how the format was supposed to work for this file and for ~/.rhosts, worse the "format" line showed that there should be spaces between arguments when that would clearly lead to incorrect behaviour. In addition some things that the format allows you to write are just wrong like "-host -user" which makes no sense since the host is already rejected, and should be written as "host -user" instead. I added notes in the example to make it clear that "-host -user" is invalid.

I fixed three things:

(a) The format line.
- Either +, or [-]hostname, or +@netgrp or -@netgrp.
- Either +, or [-]username, or +@netgrp or -@netgrp.
- You must specify something in the hostname portion so remove optional brackets.

(b) Clarify language around credentials
- If the host is not trusted you must provide credentials to the login system and that could be anything really and it depends on your configuration e.g. PAM or whatever IdM you have.

(c) Provide real-world examples
- Provide several real world examples and some corner case examples for how you would write something. Hopefully others can add examples as they see fit.

Patch applies to trunk.

Signed-off-by Carlos O'Donell <[email protected]>

man5/hosts.equiv.5 +98 -4

index 89d0b4a..c8e85ac 100644
@@ -22,7 +22,7 @@ supplying a password.
 .PP
 The file uses the following format:
 .TP
-\fI[ + | \- ]\fP \fI[hostname]\fP \fI[username]\fP
+\fI+|[\-]hostname|+@netgroup|\-@netgroup\fP \fI[+|[\-]username|+@netgroup|\-@netgroup]\fP
 .PP
 The
 .I hostname

@@ -37,9 +37,9 @@ If the plus sign is used alone, it allows any host to access your system.
 You can explicitly deny access to a host by preceding the
 .I hostname
 by a minus (\-) sign.
-Users from that host must always supply a password.
-For security reasons you should always use the FQDN of the hostname and
-not the short hostname.
+Users from that host must always supply additional credentials,
+including possibly a password. For security reasons you should always
+use the FQDN of the hostname and not the short hostname.
 .PP
 The
 .I username

@@ -81,6 +81,112 @@ character which means "any host" only when the word
 is added to the auth component line in your PAM file for
 the particular service
 .RB "(e.g., " rlogin ).
+.SH EXAMPLE
+Here are some example
+.I /etc/host.equiv
+or
+.I ~/.rhosts
+files:
+.TP
+Allow any user to login from any host:
+.LP
+.RS 4
+.TP
++
+.PD
+.RE
+.TP
+Allow any user from host with a matching local account to login:
+.LP
+.RS 4
+.TP
+host
+.PD
+.RE
+.PP
+Note: The use of
+.B +host
+is never a valid syntax, including attempting to specify that any user from the host is allowed.
+.TP
+Allow any user from host to login:
+.LP
+.RS 4
+.TP
+host +
+.PD
+.RE
+.PP
+Note: This is distinct from the previous example since it does not require a matching local account.
+.TP
+Allow user from host to login:
+.LP
+.RS 4
+.TP
+host user
+.PD
+.RE
+.TP
+Allow all users with matching local accounts from host to login except for baduser:
+.LP
+.RS 4
+.PD 0
+.TP
+host -baduser
+.TP
+host
+.PD
+.RE
+.TP
+Deny all users from host:
+.LP
+.RS 4
+.TP
+-host
+.PD
+.RE
+.PP
+Note: The use of
+.B -host -user
+is never a valid syntax, including attempting to specify that a particular user from the host is not trusted.
+.TP
+Allow all users with matching local accounts in all hosts in the netgroup:
+.LP
+.RS 4
+.TP
++@netgroup
+.PD
+.RE
+.TP
+Disallow all users in all hosts in the netgroup:
+.LP
+.RS 4
+.TP
+-@netgroup
+.PD
+.RE
+.TP
+Allow all users in netgroup to login from host:
+.LP
+.RS 4
+.TP
+host +@netgroup
+.PD
+.RE
+.TP
+Allow all users with matching local accounts in all hosts in the netgroup except baduser:
+.LP

man5/hosts.equiv.5 character which means "any host" only when the word · line 187

Quoted 10 lines

man5/hosts.equiv.5 +10 -0

+.RS 4
+.PD 0
+.TP
++@netgroup -baduser
+.TP
++@netgroup
+.PD
+.RE
+.TP
+Note: The deny statements must always preceed the allow statements because the file is processed one line at a time.

This last explanation feels incomplete. Should it not be something like:

The deny statements must always precede the allow statements because the file is processed sequentially until the first matching rule is found.

?

man5/hosts.equiv.5 character which means "any host" only when the word · line 192

Quoted 5 lines

man5/hosts.equiv.5 +2 -0

+
+
 .SH SEE ALSO
 .BR rhosts (5),
 .BR rlogind (8),

Cheers,

Quoted 4 lines

Michael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Hi Carlos,

In this earlier reply, I should have highlighted that there is one open question I have about you patch, at the end of the mail below. Could you take a look please.

Quoted 15 lines

man5/hosts.equiv.5 character which means "any host" only when the word · line 187

Quoted 12 lines

man5/hosts.equiv.5 +12 -0

+Allow all users with matching local accounts in all hosts in the netgroup except baduser:
+.LP
+.RS 4
+.PD 0
+.TP
++@netgroup -baduser
+.TP
++@netgroup
+.PD
+.RE
+.TP
+Note: The deny statements must always preceed the allow statements because the file is processed one line at a time.

This last explanation feels incomplete. Should it not be something like:

Quoted 3 lines

The deny statements must always precede the allow statements because the file is processed sequentially until the first matching rule is found.

Quoted 5 lines · Michael Kerrisk (man-pages)

Hi Carlos,

In this earlier reply, I should have highlighted that there is one open question I have about you patch, at the end of the mail below. Could you take a look please.

Certainly.

Quoted 15 lines

Quoted 15 lines

Review

Quoted 12 lines

(quoted diff) +12 -0

+Allow all users with matching local accounts in all hosts in the netgroup except baduser:
+.LP
+.RS 4
+.PD 0
+.TP
++@netgroup -baduser
+.TP
++@netgroup
+.PD
+.RE
+.TP
+Note: The deny statements must always preceed the allow statements because the file is processed one line at a time.

This last explanation feels incomplete. Should it not be something like:

Quoted 3 lines

Quoted 3 lines

The deny statements must always precede the allow statements because the file is processed sequentially until the first matching rule is found.

Your text is certainly correct and clearer. The processing does stop at the first match.