This service will be undergoing maintenance at 00:00 UTC, 2017-10-23 It is expected to last about 30 minutes
Bug 1288691 - MIscellaneous errors in Security Guide
MIscellaneous errors in Security Guide
Status: CLOSED CURRENTRELEASE
Product: Red Hat Enterprise Linux 7
Classification: Red Hat
Component: doc-Security_Guide (Show other bugs)
7.3
Unspecified Unspecified
high Severity low
: rc
: ---
Assigned To: Robert Krátký
ecs-bugs
: Documentation
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2015-12-04 22:32 EST by Kwan Lowe
Modified: 2016-01-07 07:26 EST (History)
1 user (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2016-01-07 07:26:08 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)
text file of the above (4.54 KB, text/plain)
2015-12-04 22:32 EST, Kwan Lowe
no flags Details

  None (edit)
Description Kwan Lowe 2015-12-04 22:32:57 EST
Created attachment 1102489 [details]
text file of the above

Description of problem:
Miscellaneous errors in Security guide

Version-Release number of selected component (if applicable):


How reproducible:
NA

Steps to Reproduce:
1.
2.
3.

Actual results:


Expected results:


Additional info:
Sorry for bundling all these into one large report. If there's a more efficient way please do let me know.

Document URL: 
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html-single/Security_Guide/index.html

Section Number and Name: 
Multiple

Describe the issue: 
Miscellaneous errors (typos, clarity, etc.)

Suggestions for improvement: 
Please see below

Additional information: 


Bugzilla - Security Admin Guide

4.4.4.1
Missing leading / on path

OLD:
usr/share/doc/kernel-doc-version/Documentation/networking/ip-sysctl.txt - This 

NEW:
/usr/share/doc/kernel-doc-version/Documentation/networking/ip-sysctl.txt - This 


4.5.3.1.1
Typo/Spelling

OLD:
...and Lockdown Whitlist tabs are only visible after being selected from the View drop-down menu.

NEW:
and Lockdown Whitelist tabs are only visible after being selected from the View drop-down menu.


4.5.3.4.1
Run-on sentence

OLD:
Prints yes with exit status 0, if enabled, prints no with exit status 1 otherwise.

NEW:
Prints yes with exit status 0, if enabled. Prints no with exit status 1 otherwise.




4.5.3.4.2
Suggestion: Style - favor parentheses over commas for clarifying clause

OLD:
To reload the firewall without interrupting user connections, that is to say, without losing state information, enter the following command as root:

NEW:
To reload the firewall without interrupting user connections (that is to say, without losing state information) enter the following command as root:


4.5.3.4.3
Suggestion: Word choice for clause
These are admittedly stylistic suggestions.The phrase "for example" should be followed by a comma but adding one would make an unwieldy sentence.  (http://www.myenglishteacher.net/forexample.html). This is true for all the examples in the section.

OLD:
To add an interface to a zone, for example to add em1 to the public zone, enter the following command as root:

NEW:
To add an interface to a zone (for example, to add em1 to the public zone) enter the following command as root:





4.5.3.4.5
As above -- just a stylistic suggestion.
Remove extraneous comma

OLD:
To add an interface to a zone by editing the ifcfg-em1 configuration file, for example to add em1 to the work zone, as root use an editor to add the following line to ifcfg-em1:

NEW:
To add an interface to a zone by editing the ifcfg-em1 configuration file (for example, to add em1 to the work zone), as root append the following line to ifcfg-em1:



OLD:
Reload the firewall, by entering the following command as root:

NEW:
Reload the firewall by entering the following command as root:


4.5.3.5
Run-on

OLD:
Do not edit the files in the /usr/lib/firewalld/ directory, they are for the default settings. 

NEW:
Do not edit the files in the /usr/lib/firewalld/ directory as they are for the default settings. 




4.5.3.6.1
Unclear sentence, run-on, verb. 

OLD:
To add a custom rule to the chain “IN_public_allow”, issuing a command as root in the following format:

NEW:
To add a custom rule to the chain “IN_public_allow”, issue the following command as root:


4.5.3.6.3
The example command is not working as expected. If I understand correctly, the --direct option should query the underlying iptables.

If I run the example (firewall-cmd --direct --get-rules ipv4 filter IN_public_allow) nothing is returned. If I understand the documentation correcty, it should return output at least similar to that from:  iptables --table filter --list IN_public_allow

Example:

[root@vm-centos7-001 ~]# firewall-cmd --direct --get-rules ipv4 filter IN_public_allow
[root@vm-centos7-001 ~]# iptables --table filter --list IN_public_allow
Chain IN_public_allow (1 references)
target     prot opt source               destination         
ACCEPT     tcp  --  anywhere             anywhere             tcp dpt:ssh ctstate NEW

I'm not certain if this is a documentation bug or one with the firewall-cmd.





4.5.3.7.1
This is a bit of a nit-pick, but since the examples are partially BNF, using full BNF might be appropriate.  Also, the "seconds" is not absolutely correct as timeout can be specified in seconds, minutes or hours (s,m,h). For clarity, it might be better to give a specific example with an explanation. 

OLD:
firewall-cmd [--zone=zone] --add-rich-rule='rule' [--timeout=seconds]

NEW:
firewall-cmd [--zone=<zone>] --add-rich-rule='rule' [--timeout=<timeval>]

OLD:
This will return whether a rich language rule rule has been added for the zone zone. Prints yes with exit status 0, if enabled, prints no with exit status 1 otherwise. If the zone is omitted, the default zone will be used.

NEW:
This will return whether a rich language rule rule has been added for the zone zone. Prints yes with exit status 0, if enabled. Prints no with exit status 1 otherwise. If the zone is omitted, the default zone will be used.


4.5.3.7.3
Wording

OLD:
If the rule family is provided, it can be either ipv4 or ipv6, it limits the rule to IPv4 or IPv6. 

NEW:
If the rule family is provided, either ipv4 or ipv6, it limits the rule to IPv4 or IPv6.
Comment 1 Robert Krátký 2016-01-05 07:18:19 EST
(In reply to Kwan Lowe from comment #0)

Kwan, thank you for taking the time to report these issues. I corrected the mistakes, improved legibility, and added a number of other fixes as well. Some comments below:

> 4.5.3.6.3
> The example command is not working as expected. If I understand correctly,
> the --direct option should query the underlying iptables.
> 
> If I run the example (firewall-cmd --direct --get-rules ipv4 filter
> IN_public_allow) nothing is returned. If I understand the documentation
> correcty, it should return output at least similar to that from:  iptables
> --table filter --list IN_public_allow
> 
> Example:
> 
> [root@vm-centos7-001 ~]# firewall-cmd --direct --get-rules ipv4 filter
> IN_public_allow
> [root@vm-centos7-001 ~]# iptables --table filter --list IN_public_allow
> Chain IN_public_allow (1 references)
> target     prot opt source               destination         
> ACCEPT     tcp  --  anywhere             anywhere             tcp dpt:ssh
> ctstate NEW
> 
> I'm not certain if this is a documentation bug or one with the firewall-cmd.

This was a mistake in the documentation. I added an explanation:

"Note that this command (the --get-rules option) only lists rules previously added using the --add-rule option. It does not list existing iptables rules added by other means."

> 4.5.3.7.1
> This is a bit of a nit-pick, but since the examples are partially BNF, using
> full BNF might be appropriate.  Also, the "seconds" is not absolutely
> correct as timeout can be specified in seconds, minutes or hours (s,m,h).
> For clarity, it might be better to give a specific example with an
> explanation. 
> 
> OLD:
> firewall-cmd [--zone=zone] --add-rich-rule='rule' [--timeout=seconds]
> 
> NEW:
> firewall-cmd [--zone=<zone>] --add-rich-rule='rule' [--timeout=<timeval>]

The documentation uses DocBook as its source format, which (mostly) follows EBNF -- therefore, angle brackets ('<>') are not used. Instead, cursive is used to denote a replaceable value.
Comment 2 Robert Krátký 2016-01-07 07:26:08 EST
The updated guide is live on the portal.

Note You need to log in before you can comment on or make changes to this bug.