From jhawk@bbnplanet.com Fri Oct 4 01:18:40 1996
Received: from MIT.EDU (SOUTH-STATION-ANNEX.MIT.EDU [18.72.1.2]) by rt-11.MIT.EDU (8.7.5/8.7.3) with SMTP id BAA18598 for <bugs@RT-11.MIT.EDU>; Fri, 4 Oct 1996 01:18:39 -0400
Received: from all-purpose-gunk.near.net by MIT.EDU with SMTP
id AA11861; Fri, 4 Oct 96 01:18:38 EDT
Received: (from jhawk@localhost) by all-purpose-gunk.near.net (8.8.0/8.8.0) id BAA10654; Fri, 4 Oct 1996 01:18:37 -0400 (EDT)
Message-Id: <199610040518.BAA10654@all-purpose-gunk.near.net>
Date: Fri, 4 Oct 1996 01:18:37 -0400 (EDT)
From: John Hawkinson <jhawk@bbnplanet.com>
To: krb5-bugs@MIT.EDU
Subject: Comments on "Kerberos V5 Installation Guide"
Here are some comments on doc/install.texinfo.
Some are bugfixes, others are simply my own impression.
} @section Why Should I use Kerberos?
}
} Since Kerberos negotiates authenticated, and optionally encrypted,
} communications between two points anywhere on the internet, it provides
Capitalize "Internet".
This section really needs to include a "Why should I use Kerberos over SSH"
section. Politics is important, especially if a release is imminent :-).
...
} @section Ports for the KDC and Admin Services
...
} files, and the @code{kdc.conf} file on each KDC. Because the kadmin
} port was recently assigned, @value{COMPANY} recommands that you specify
} it explicitly in your @code{krb5.conf} and @code{kdc.conf} files.
That doesn't make any sense to me. What does how recently
a port number was assigned have to do with anything?
Explain or remove this.
} @section Slave KDCs
}
} Slave KDCs provide an additional source of Kerberos ticket-granting
} services in the event of inaccessibility of the master KDC. The number
} of slave KDCs you need and the decision of where to place them, both
} physically and logically, depend on the specifics of your network.
s/depend/depends/
} If your network is split such that a network outage is likely to cause
} some segment or segments of the network to become cut off or isolated,
} have a slave KDC accessible to each segment.
Replace "some segment...isolated" with "a network partition".
} If you have a large and/or complex network, @value{COMPANY} will be
} happy to work with you to determine the optimal number and placement of
} your slave KDCs.
Never use "and/or" in technical writing. Just "or" is fine.
} @section Hostnames for the Master and Slave KDCs
}
} @value{COMPANY} recommends that your KDCs have a predefined set of
} cnames, such as @code{@value{KDCSERVER}} for the master KDC and
s/cnames/CNAMEs/
} @section Database Propagation
}
} The Kerberos database resides on the master KDC, and must be propagated
} regularly (usually by a cron job) to the slave KDCs. In deciding how
} frequently the propagation should happen, you will need to balance the
} amount of time the propagation takes against the maximum reasonable
} amount of time a user should have to wait for a password change to take
} effect. @value{COMPANY} recommends that this be no longer than an hour.
It's not at all clear what value is being discussed as "an hour" -- the
duration of propagation or the or the frequency of propagation.
Please clarify.
Jumping into build.texinfo:
} @subsection Building Within a Single Tree
}
} If you don't want separate build trees for each architecture, then
} use the following abbreviated procedure.
}
} @enumerate
} @item
} @code{cd /u1/krb5/src}
} @item
} @code{./configure}
The currrent release would unpack into /u1/krb5/krb5-beta7. The instructions
need to be amended to use this instead for this and the next 2 sections.
} @subsection Building Using @samp{lndir}
...
} You must give an absolute pathname to @samp{lndir} because it has a bug that
} makes it fail for relative pathnames. Note that this version differs
} from the latest version as distributed and installed by the XConsortium
} with X11R6.
"This version"? Excuse me? No one on the planet with a handy-dandy sipb locker
uses the crufty version of lndir. Everyone else has the the X11 version if any.
Since you don't bother to mention where to get the non-X11 version, it's
silly to assume the default is that folks have it. Or are you
referring to src/uytil/lndir? I guess that's possible but it seems
odd since that version seems to be an X-consortium-produced program, too.
This confusion should be remedied.
} @subsection The DejaGnu Tests
...
} Most of the tests are setup to run as a non-privledged user. There are
} two series of tests (@samp{rlogind} and @samp{telnetd}) which require
} the ability to @samp{rlogin} as root to the local machine. Admittedly,
} this does require the use of a @file{.rhosts} file or some other
} authenticated means. @footnote{If you are fortunate enough to have a
Strike "other" in "other authenticated means" :-).
} @item --with-krb4
}
} This option enables Kerberos V4 backwards compatibility using the
} builtin Kerberos V4 library.
}
} @item --with-krb4=KRB4DIR
}
} This option enables Kerberos V4 backwards compatibility. The directory
} specified by @code{KRB4DIR} specifies where the V4 header files should
} be found (@file{/KRB4DIR/include}) as well as where the V4 Kerberos
} library should be found (@file{/KRB4DIR/lib}).
Sentence #1 of "--with-krb4=" could stand a bit of clarification on
the difference between it and the default.
Popping back to install.texinfo:
} @section Installing KDCs
}
} The Key Distribution Centers (KDCs) issue Kerberos tickets. Each KDC
} contains a copy of the Kerberos database. The master KDC contains the
} master copy of the database, which it propagates to the slave KDCs at
} regular intervals. All database changes (such as password changes) are
} made on the master KDC.
}
} Slave KDCs provide Kerberos ticket-granting services, but not database
} access.
Huh? They don't provide writable database access but otherwise the database
access is certainly provided!
} @subsubsection Edit the Configuration Files
}
} Modify the configuration files, @code{/etc/krb5.conf}
} (@pxref{krb5.conf}) and @code{@value{ROOTDIR}/lib/krb5kdc/kdc.conf}
} (@pxref{kdc.conf}) to reflect the correct information (such as the
} hostnames and realm name) for your realm. @value{COMPANY} recommends
} that you keep @code{krb5.conf} in @code{/etc}. The @code{krb5.conf}
} file may contain a pointer to @code{kdc.conf}, which you need to change
} if you want to move @code{kdc.conf} to another location.
s/if you want to move/if you move/
} @subsubsection Create the Database
}
} the sample keys that appear in this manual. One example of a key which
} would be good if it did not appear in this manual is ``MITiys4K5!'',
} which represents the sentence ``@value{COMPANY} is your source for
} Kerberos 5!'' (It's the first letter of each word, substituting the
Inconsistant use of @value{COMPANY}. The password should use it.
It's highly questionable to me that this in fact a good key, since it is
rather non-random and is based on facts that would be well-known to a cracker.
Sure, it's cute, but is it good? I don't think so.
} @subsubsection Start the Kerberos Daemons on the Master KDC
} @noindent
} Each daemon will fork and run in the background. Assuming you want
} these daemons to start up automatically at boot time, you can add them
} to the KDC's @code{/etc/rc} or @code{/etc/inittab} file. You need to
} have a stash file in order to do this.
/etc/inittab? I don't think anyone really wants to do that. Same for
/etc/rc on modern OSes. Either /etc/rc.local or /etc/rc.d/*SOMETHING*
} @subsubsection Set Up the Slave KDCs for Database Propagation
} @group
} kerberos 88/udp kdc # Kerberos authentication (udp)
} kerberos 88/tcp kdc # Kerberos authentication (tcp)
} krb5_prop 754/tcp # Kerberos slave propagation
} kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp)
} kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp)
} eklogin 2105/tcp # Kerberos encrypted rlogin
} @end group
} @end smallexample
Umm, some reason the # comments aren't lined up?
Responsible-Changed-From-To: krb5-unassigned->bjaspan
Responsible-Changed-By: bjaspan
Responsible-Changed-When: Fri Nov 1 17:04:07 1996
Responsible-Changed-Why:
Responsible-Changed-From-To: bjaspan->krb5-unassigned
Responsible-Changed-By: bjaspan
Responsible-Changed-When: Mon Nov 4 16:52:10 1996
Responsible-Changed-Why:
I fixed the kadm5-specific problems that jhawk listed. The rest are
for the build system documentation, which probably should still be
fixed.
State-Changed-From-To: open-closed
State-Changed-By: bjaspan
State-Changed-When: Tue Nov 19 13:42:32 1996
State-Changed-Why:
Files:
doc/ChangeLog
doc/install.texinfo
doc/build.texinfo
Received: from MIT.EDU (SOUTH-STATION-ANNEX.MIT.EDU [18.72.1.2]) by rt-11.MIT.EDU (8.7.5/8.7.3) with SMTP id BAA18598 for <bugs@RT-11.MIT.EDU>; Fri, 4 Oct 1996 01:18:39 -0400
Received: from all-purpose-gunk.near.net by MIT.EDU with SMTP
id AA11861; Fri, 4 Oct 96 01:18:38 EDT
Received: (from jhawk@localhost) by all-purpose-gunk.near.net (8.8.0/8.8.0) id BAA10654; Fri, 4 Oct 1996 01:18:37 -0400 (EDT)
Message-Id: <199610040518.BAA10654@all-purpose-gunk.near.net>
Date: Fri, 4 Oct 1996 01:18:37 -0400 (EDT)
From: John Hawkinson <jhawk@bbnplanet.com>
To: krb5-bugs@MIT.EDU
Subject: Comments on "Kerberos V5 Installation Guide"
Show quoted text
>Number: 55
>Category: krb5-doc
>Synopsis: Comments on "Kerberos V5 Installation Guide"
>Confidential: no
>Severity: non-critical
>Priority: high
>Responsible: krb5-unassigned
>State: closed
>Class: doc-bug
>Submitter-Id: unknown
>Arrival-Date: Fri Oct e 01:19:01 EDT 1996
>Last-Modified: Tue Nov 19 13:42:47 EST 1996
>Originator: John Hawkinson
>Organization:
BBN Planet>Category: krb5-doc
>Synopsis: Comments on "Kerberos V5 Installation Guide"
>Confidential: no
>Severity: non-critical
>Priority: high
>Responsible: krb5-unassigned
>State: closed
>Class: doc-bug
>Submitter-Id: unknown
>Arrival-Date: Fri Oct e 01:19:01 EDT 1996
>Last-Modified: Tue Nov 19 13:42:47 EST 1996
>Originator: John Hawkinson
>Organization:
Show quoted text
>Release: beta-7
>Environment:
My poor deluded brain>Environment:
Show quoted text
>Description:
Here are some comments on doc/install.texinfo.
Some are bugfixes, others are simply my own impression.
Show quoted text
>How-To-Repeat:
>Fix:
>Fix:
} @section Why Should I use Kerberos?
}
} Since Kerberos negotiates authenticated, and optionally encrypted,
} communications between two points anywhere on the internet, it provides
Capitalize "Internet".
This section really needs to include a "Why should I use Kerberos over SSH"
section. Politics is important, especially if a release is imminent :-).
...
} @section Ports for the KDC and Admin Services
...
} files, and the @code{kdc.conf} file on each KDC. Because the kadmin
} port was recently assigned, @value{COMPANY} recommands that you specify
} it explicitly in your @code{krb5.conf} and @code{kdc.conf} files.
That doesn't make any sense to me. What does how recently
a port number was assigned have to do with anything?
Explain or remove this.
} @section Slave KDCs
}
} Slave KDCs provide an additional source of Kerberos ticket-granting
} services in the event of inaccessibility of the master KDC. The number
} of slave KDCs you need and the decision of where to place them, both
} physically and logically, depend on the specifics of your network.
s/depend/depends/
} If your network is split such that a network outage is likely to cause
} some segment or segments of the network to become cut off or isolated,
} have a slave KDC accessible to each segment.
Replace "some segment...isolated" with "a network partition".
} If you have a large and/or complex network, @value{COMPANY} will be
} happy to work with you to determine the optimal number and placement of
} your slave KDCs.
Never use "and/or" in technical writing. Just "or" is fine.
} @section Hostnames for the Master and Slave KDCs
}
} @value{COMPANY} recommends that your KDCs have a predefined set of
} cnames, such as @code{@value{KDCSERVER}} for the master KDC and
s/cnames/CNAMEs/
} @section Database Propagation
}
} The Kerberos database resides on the master KDC, and must be propagated
} regularly (usually by a cron job) to the slave KDCs. In deciding how
} frequently the propagation should happen, you will need to balance the
} amount of time the propagation takes against the maximum reasonable
} amount of time a user should have to wait for a password change to take
} effect. @value{COMPANY} recommends that this be no longer than an hour.
It's not at all clear what value is being discussed as "an hour" -- the
duration of propagation or the or the frequency of propagation.
Please clarify.
Jumping into build.texinfo:
} @subsection Building Within a Single Tree
}
} If you don't want separate build trees for each architecture, then
} use the following abbreviated procedure.
}
} @enumerate
} @item
} @code{cd /u1/krb5/src}
} @item
} @code{./configure}
The currrent release would unpack into /u1/krb5/krb5-beta7. The instructions
need to be amended to use this instead for this and the next 2 sections.
} @subsection Building Using @samp{lndir}
...
} You must give an absolute pathname to @samp{lndir} because it has a bug that
} makes it fail for relative pathnames. Note that this version differs
} from the latest version as distributed and installed by the XConsortium
} with X11R6.
"This version"? Excuse me? No one on the planet with a handy-dandy sipb locker
uses the crufty version of lndir. Everyone else has the the X11 version if any.
Since you don't bother to mention where to get the non-X11 version, it's
silly to assume the default is that folks have it. Or are you
referring to src/uytil/lndir? I guess that's possible but it seems
odd since that version seems to be an X-consortium-produced program, too.
This confusion should be remedied.
} @subsection The DejaGnu Tests
...
} Most of the tests are setup to run as a non-privledged user. There are
} two series of tests (@samp{rlogind} and @samp{telnetd}) which require
} the ability to @samp{rlogin} as root to the local machine. Admittedly,
} this does require the use of a @file{.rhosts} file or some other
} authenticated means. @footnote{If you are fortunate enough to have a
Strike "other" in "other authenticated means" :-).
} @item --with-krb4
}
} This option enables Kerberos V4 backwards compatibility using the
} builtin Kerberos V4 library.
}
} @item --with-krb4=KRB4DIR
}
} This option enables Kerberos V4 backwards compatibility. The directory
} specified by @code{KRB4DIR} specifies where the V4 header files should
} be found (@file{/KRB4DIR/include}) as well as where the V4 Kerberos
} library should be found (@file{/KRB4DIR/lib}).
Sentence #1 of "--with-krb4=" could stand a bit of clarification on
the difference between it and the default.
Popping back to install.texinfo:
} @section Installing KDCs
}
} The Key Distribution Centers (KDCs) issue Kerberos tickets. Each KDC
} contains a copy of the Kerberos database. The master KDC contains the
} master copy of the database, which it propagates to the slave KDCs at
} regular intervals. All database changes (such as password changes) are
} made on the master KDC.
}
} Slave KDCs provide Kerberos ticket-granting services, but not database
} access.
Huh? They don't provide writable database access but otherwise the database
access is certainly provided!
} @subsubsection Edit the Configuration Files
}
} Modify the configuration files, @code{/etc/krb5.conf}
} (@pxref{krb5.conf}) and @code{@value{ROOTDIR}/lib/krb5kdc/kdc.conf}
} (@pxref{kdc.conf}) to reflect the correct information (such as the
} hostnames and realm name) for your realm. @value{COMPANY} recommends
} that you keep @code{krb5.conf} in @code{/etc}. The @code{krb5.conf}
} file may contain a pointer to @code{kdc.conf}, which you need to change
} if you want to move @code{kdc.conf} to another location.
s/if you want to move/if you move/
} @subsubsection Create the Database
}
} the sample keys that appear in this manual. One example of a key which
} would be good if it did not appear in this manual is ``MITiys4K5!'',
} which represents the sentence ``@value{COMPANY} is your source for
} Kerberos 5!'' (It's the first letter of each word, substituting the
Inconsistant use of @value{COMPANY}. The password should use it.
It's highly questionable to me that this in fact a good key, since it is
rather non-random and is based on facts that would be well-known to a cracker.
Sure, it's cute, but is it good? I don't think so.
} @subsubsection Start the Kerberos Daemons on the Master KDC
} @noindent
} Each daemon will fork and run in the background. Assuming you want
} these daemons to start up automatically at boot time, you can add them
} to the KDC's @code{/etc/rc} or @code{/etc/inittab} file. You need to
} have a stash file in order to do this.
/etc/inittab? I don't think anyone really wants to do that. Same for
/etc/rc on modern OSes. Either /etc/rc.local or /etc/rc.d/*SOMETHING*
} @subsubsection Set Up the Slave KDCs for Database Propagation
} @group
} kerberos 88/udp kdc # Kerberos authentication (udp)
} kerberos 88/tcp kdc # Kerberos authentication (tcp)
} krb5_prop 754/tcp # Kerberos slave propagation
} kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp)
} kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp)
} eklogin 2105/tcp # Kerberos encrypted rlogin
} @end group
} @end smallexample
Umm, some reason the # comments aren't lined up?
Show quoted text
>Audit-Trail:
Responsible-Changed-From-To: krb5-unassigned->bjaspan
Responsible-Changed-By: bjaspan
Responsible-Changed-When: Fri Nov 1 17:04:07 1996
Responsible-Changed-Why:
Responsible-Changed-From-To: bjaspan->krb5-unassigned
Responsible-Changed-By: bjaspan
Responsible-Changed-When: Mon Nov 4 16:52:10 1996
Responsible-Changed-Why:
I fixed the kadm5-specific problems that jhawk listed. The rest are
for the build system documentation, which probably should still be
fixed.
State-Changed-From-To: open-closed
State-Changed-By: bjaspan
State-Changed-When: Tue Nov 19 13:42:32 1996
State-Changed-Why:
Files:
doc/ChangeLog
doc/install.texinfo
doc/build.texinfo
Show quoted text
>Unformatted: