Bug 856266 - Multiple typos and other issues
Multiple typos and other issues
Status: CLOSED CURRENTRELEASE
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: doc-Identity_Management_Guide (Show other bugs)
6.5
Unspecified Unspecified
unspecified Severity medium
: rc
: ---
Assigned To: Deon Ballard
ecs-bugs
: Documentation
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-09-11 11:11 EDT by Nikolai Kondrashov
Modified: 2014-05-09 23:42 EDT (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2014-05-09 23:42:29 EDT
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)

  None (edit)
Description Nikolai Kondrashov 2012-09-11 11:11:15 EDT
I was going through the Indentity Management Guide for the first time and noticed multiple typos and several other issues. I was reading it at https://access.redhat.com/knowledge/docs/en-US/Red_Hat_Enterprise_Linux/6/html-single/Identity_Management_Guide/index.html

Here is the list. The hash character starts original text.

# As said, an IPA server is a controller for a lot of associated services. While a number of those services are support, most of them are not required.
support->supported

# It is recommended that a separate DNS domain be allocated for the IPA server. While not required (clients from other domains can still be enrolled in the IPA domain), this is a convenience for overall DNS management.
Is it really "DNS domain ... for the IPA server"? Shouldn't it be "DNS domain ... for the IPA *domain*" instead?

# If the IPA server is configured to host its own DNS server, any previous existing DNS ignored.
"existing DNS" what?

# To make sure that these ports are available, try iptables to list the available ports or nc, telnet, or nmap to connect to a port or run a port scan.
Iptables won't list available ports. You can interpret iptables configuration and assume that ports are open, but it's not always easy.
The best advice is to use nc as the client and the server for both TCP and UDP.
Nmap is a good way but it seems it wouldn't scan Dogtag port by default.

# To open a port:
#
# [root@server ~]# iptables -A INPUT -p tcp --dport 389 -j ACCEPT
#
# The iptables man page has more information on opening and closing ports on a system. 
This command doesn't guarantee that the port would be "opened" in all configurations.

# If a server is being installed on a virtual machine, that server should not run an NTP server.
A short explanation would be nice here.

# To disable NTP for IPA, use the --no-ntp option. 
The --no-ntp option to what?

# if a request determines that a specific IPA user does not exist, it marks this as a negative cache
I'd suggest "it caches this as a negative response" instead. There is no such thing as a "negative cache".

# The port numbers and directory locations used by IPA are all defined automatically, as defined in Section 2.2.4.4, “System Ports” and .
"and ." what?

# These example illustrate some common options when installing the server.
example->examples

# To use DNS always requires the --setup-dns.
Maybe "To enable DNS always use the --setup-dns option."

# To user forwarders, use the --forwarder option
user->use

# DNS entries are required for required domain services:
The "are" should probably be removed.

# If the initial IPA server was created without DNS enabled, then each DNS entry, including both TCP and UPD entries for some services, should be added manually.
UPD->UDP

# [root@ipaserver ~]# yum update *
The star should be quoted, like this: "yum update '*'", or: "yum update \*".
Otherwise the shell will expand it into current directory entries.

# It is not necessary to update all servers and replicas at precisely the same
# time; the IPA servers will still work with each other and replicate data
# successfully. The older IPA servers will simply lack the new features.
This contradicts this:

"The replica must be the same version as the original master server. If the
master server is running on Red Hat Enterprise Linux 6.3, IPA version 2.2.x,
then the replica must also run on Red Hat Enterprise Linux 6.3 and use the IPA
2.2.x packages."

The reader will be left unsure whether it will work or not and will have to
seek information from other sources.

This note alleviates that slightly:

"Schema changes are replicated between servers. So once one master server is
updated, all servers and replicas will have the updated schema, even if their
packages are not yet updated. This ensures that any new entries which use the
new schema can still be replicated among all the servers in the IPA domain."

However, it is still unclear whether schema is updated or not during replica
creation.

# Configures SSSD or LDAP/KRB5, including NSS and PAM configuration files.
Configures->Configure

# Configures an OpenSSH server and client, as well as enabling the host to create DNS SSHFP records.
Should probably be: "Configure an OpenSSH server and client, enabling the host to create DNS SSHFP records."

# ipa command parentEntryName chidlEntryName --childOptions=childValues
chidlEntryName->childEntryName

# If each cluster member contains a subject alternative name which includes the names of all the other cluster members will satisfy any client connection requirements.
Maybe "If each cluster member contains a subject alternative name which includes the names of all the other cluster members, *this* will satisfy any client connection requirements."

# If an attribute does not exist in the DNS zone entry, than the dnszone-mod command adds the attribute.
than->then

# The regular expression can match any port of the string.
port->part

# Wrapping the pattern in ^ and $ means that it must be an exact match.
It doesn't mean an "exact match", it means that the whole string should match.
Such pattern could still match several strings, like this one: "^user[0-9]$".
Maybe it's better to say "Wrapping the pattern in ^ and $ means that it must match the string as a whole."
Comment 2 Najmuddin Chirammal 2012-10-02 06:59:14 EDT
From : Configuring_Automount-Configuring_autofs_on_Linux

------------
This must be run from a machine with the ipa-admintools package installed so that the  ipa command is available.
On the IPA server, obtain a keytab for the NFS service principal.
# ipa-getkeytab -s ipaserver.example.com -p nfs/ipaclient.example.com@EXAMPLE -k /tmp/krb5.keytab
------------

ipa-getkeytab is provided by ipa-clients package itself, we dont need to install ipa-admintools for that.. it'd be great if the example can be changed to run on the client side itself (rather than creating it on the server and copying to client(s)).
Comment 3 Petr Spacek 2012-10-15 06:57:47 EDT
(In reply to comment #0)
> Here is the list. The hash character starts original text.
> 
> # It is recommended that a separate DNS domain be allocated for the IPA
> server. While not required (clients from other domains can still be enrolled
> in the IPA domain), this is a convenience for overall DNS management.
> Is it really "DNS domain ... for the IPA server"? Shouldn't it be "DNS
> domain ... for the IPA *domain*" instead?

I would recommend something like "It is recommended that a separate DNS domain be allocated for the IPA deployment."



> # If the IPA server is configured to host its own DNS server, any previous
> existing DNS ignored.
> "existing DNS" what?

# TIP:
# If the IPA server is configured to host its own DNS server, any previous existing DNS ignored. A records and PTR records do not need to match for the IPA server machine, and the machine can have any configured IP address. 

I find whole "tip" confusing. I would say something like:
If the IPA server is configured to host its own DNS server, all DNS queries from IPA server will be processed by its own DNS server. DNS records in IPA will take precedence before any DNS records configured in other DNS servers.

All clients and replicas should be configured to use IPA-managed DNS server in that case.



# 2.4.3.3. Using DNS
# IPA can be configured to manage its own DNS, use an existing DNS, or not use DNS services at all (which is the default)

*This statement is incorrect.* "use an existing DNS" is the default option.

Please add following warning: Many services depend on correct DNS records. Please test your DNS environment thoroughly when not using IPA-managed DNS server. Mutual correspondence between A and PTR records is very important.



> # To use DNS always requires the --setup-dns.
> Maybe "To enable DNS always use the --setup-dns option."
I would recommend "To install IPA-managed DNS always use the --setup-dns option."



> # [root@ipaserver ~]# yum update *
> The star should be quoted, like this: "yum update '*'", or: "yum update \*".
> Otherwise the shell will expand it into current directory entries.
Please use
yum update
without a star. It will update all packages and it is less confusing.
Comment 4 Deon Ballard 2014-05-09 23:42:29 EDT
Mass closure of bugs modified in 2013. All of these are in the currently-published docs.

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