Quick review requested
Jim Brown
jpb at sixshooter.v6.thrupoint.net
Wed Oct 1 00:36:41 UTC 2003
* Tom Rhodes <trhodes at FreeBSD.org> [2003-09-30 18:03]:
> Gang,
>
> I'd really appreciate some feedback on the text below. If anyone
> would like the full patch (images, Makefile, etc) please speak up
> and I'll send it.
>
> Whitespace in added text will be fixed before the initial cvs ci,
> so comments on short/long lines are not required.
>
> Thanks!
>
> --
> Tom Rhodes
>
Comments inline- sorry. I don't have my doc stuff set up on this system
so I can't check what it looks like visually.
> --- doc.old/en_US.ISO8859-1/books/handbook/install/chapter.sgml Mon Sep 29 13:40:57 2003
> +++ doc/en_US.ISO8859-1/books/handbook/install/chapter.sgml Mon Sep 29 18:39:26 2003
> @@ -3382,6 +3382,233 @@
> post-installation configuration.</para>
> </sect2>
>
> + <sect2 id="network-services">
> + <title>Configure Additional Network Services</title>
> +
> + <para>Configuring the network services can be a daunting
> + task for new users if they lack any previous network configuration knowledge.
> + Configuring a network
> + is an important aspect of &os;, therefore users should at least
> + have an understanding of various services available to them.</para>
"Configuring the network..." followed by "configuration" followed by "Configuring the network.."
is somewhat repetitive. Can you choose a different word or make it flow
a bit better? Also '... the network ...' followed by '... a netowrk ...' seemed
to clash for me. Might be just too much coffee though.
> +
> + <para>Selecting the <quote>Networking</quote> option will bring forth a menu
> + similar to the one below:</para>
s/bring forth/display/
seems a bit better to me.
> +
> + <figure id="network-configuration">
> + <title>Network Configuration Upper-level</title>
> +
> + <mediaobject>
> + <imageobject>
> + <imagedata fileref="install/net-config-menu1" format="PNG">
> + </imageobject>
> + </mediaobject>
> + </figure>
> +
> + <para>The first option, Interfaces, was previously covered during
> + the Network Device Configuration section; thus we can bypass
> + this option.</para>
You are in the first person here.
> +
> + <para>Selecting the <option>AMD</option> option adds
> + support for the <acronym>BSD</acronym> auto mount utility.
> + This is usually used in conjunction with the
> + <acronym>NFS</acronym> protocol (see below)
> + for automatically mounting remote file systems.
> + No special configuration
> + is required here.</para>
> +
> + <para>Next in line is the <acronym>AMD</acronym> flags
> + option. When selected, a menu will pop up for you
> + to enter specific <acronym>AMD</acronym> flags.
> + The menu already contains a set of default options:</para>
> +
> + <screen>-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map</screen>
> +
> + <para>The <literal>-a</literal> option specifies the default mount
> + location which is listed here as <filename>/.amd_mnt</filename>.
> + The <literal>-l</literal> option specifies the default
> + <filename>log</filename> file; however, when &man.syslogd.8; is
I would use <literal>syslog</literal> here. The option should never look
like 'syslog(8)'. Might confuse a newbie.
> + specified all log activity will be sent to the system log daemon.
> + The <filename>/host</filename> is used to mount an exported
> + file system from a remote hostname, while
> + <filename>/net</filename> is used to mount an exported file
> + system from an <acronym>IP</acronym> address. The
> + <filename>/etc/amd.map</filename> defines the default options
> + for <acronym>AMD</acronym> exports.</para>
> +
> + <para>The Anon <acronym>FTP</acronym> should be
> + self explanatory. Select this option to permit anonymous
If I'm a newbie, I won't know what is self explanatory. I would offer:
"<para>The Anon <acronym>FTP</acronym> option permits anonymous ..."
or something similar.
> + <acronym>FTP</acronym> logins. Be aware of the security risks
> + involved with this option. Another menu will be displayed to
> + explain the security risks and configuration in depth.</para>
> +
> + <para>The <option>Gateway</option> configuration menu will set
> + the machine up to be a gateway as explained previously. This
> + can be used to unset the gateway option if you accidentally
> + selected it during the installation process.</para>
> +
> + <para>The <option>Inetd</option> option can be used to configure or
> + completely disable the &man.inetd.8; daemon as discussed above.</para>
> +
> + <para>The <option>Mail</option> is used to configure the system's
> + default <acronym>MTA</acronym> or mail server. Selecting this
> + option will bring forth the following menu:</para>
> +
> + <figure id="mta-selection">
> + <title>Select a default MTA</title>
> +
> + <mediaobject>
> + <imageobject>
> + <imagedata fileref="install/mta-main" format="PNG">
> + </imageobject>
> + </mediaobject>
> + </figure>
> +
> + <para>Here the user is given a choice as to which
> + <acronym>MTA</acronym>, or Mail Transfer Agent to install
> + and set as the default. An <acronym>MTA</acronym> is nothing
> + more than a mail server which delivers email to users on the
> + system or the Internet.</para>
> +
> + <para>Selecting <application>Sendmail</application> will install
> + the popular <application>Sendmail</application> server which
> + is the &os; default. The <option>Sendmail local</option> option
> + will set <application>Sendmail</application> to be the default
> + <acronym>MTA</acronym>, but disables its ability to receive
> + incoming email from the Internet. The other options here,
> + <application>Postfix</application> and
> + <application>Exim</application> act similar to
> + <application>Sendmail</application>, as in they both deliver
"as in they both" doesn't work for me. Perhaps:
"<application>Sendmail</application>. They both deliver ..."
> + email; however, selecting either of these is more of a user
> + preference than anything else.</para>
> +
> + <para>After selecting an <acronym>MTA</acronym>, or choosing
> + not to select an MTA, we are back at the default menu with
First person. See note at end.
> + the next option being <acronym>NFS</acronym> client.</para>
> +
> + <para>The <acronym>NFS</acronym> client will
> + set the machine to work as a client for an
> + <acronym>NFS</acronym> server. An <acronym>NFS</acronym> server
> + exports remotely mounted file systems to other machines on the local
> + network via the <acronym>NFS</acronym> protocol. If this is
> + a stand alone machine, this option can remain unselected. The
> + system may require more configuration later, see
> + <xref linkend="network-nfs"> for more
> + information about client and server configuration.</para>
> +
> + <para>Below that option is the
> + <acronym>NFS</acronym> server option,
> + permitting a user to set the system up as an
> + <acronym>NFS</acronym> server. This adds the required
> + information to start up the <acronym>RPC</acronym> remote
> + procedure call services. <acronym>RPC</acronym> is used to
> + coordinate connections between hosts and programs.</para>
> +
> + <para>Next in line is the <option>Ntpdate</option> option,
> + which deals with time synchronization. When selected, a menu
> + like the one below shows up:</para>
> +
> + <figure id="Ntpdate-config">
> + <title>Ntpdate Configuration</title>
> +
> + <mediaobject>
> + <imageobject>
> + <imagedata fileref="install/ntp-config" format="PNG">
> + </imageobject>
> + </mediaobject>
> + </figure>
> +
> + <para>From this menu, select the server which is the closest
> + to your location. Selecting a close one will make the time
> + synchronization more accurate as a server further from your
> + location may have more connection latency.</para>
> +
> + <para>Our next option is the
> + <acronym>PCNFSD</acronym> selection. This
> + option will install the
> + <filename role="package">net/pcnfsd</filename> package from
> + the ports collection. This is a useful utility which provides
> + <acronym>NFS</acronym> authentication services for systems which
> + are unable to provide their own. For instance, Microsoft's
> + <acronym>DOS</acronym> operating system.</para>
> +
> + <para>Now we must scroll down a bit to see the other options:</para>
> +
> + <figure id="Network-configuration-cont">
> + <title>Network Configuration Lower-level</title>
> +
> + <mediaobject>
> + <imageobject>
> + <imagedata fileref="install/net-config-menu2" format="PNG">
> + </imageobject>
> + </mediaobject>
> + </figure>
> +
> + <para>The &man.rpcbind.8;, &man.rpc.statd.8;, and
> + &man.rpc.lockd.8; utilities are all used for Remote Procedure
> + Calls (<acronym>RPC</acronym>). The <command>rpcbind.8</command>
> + utility handles the communication between <acronym>NFS</acronym>
> + servers, their clients, and is required for
> + <acronym>NFS</acronym> servers to operate correctly. The
> + <command>rpc.statd</command> daemon interacts with the
> + <command>rpc.statd</command> daemon on other hosts to provide
> + status monitoring. The reported status is usually held in the
> + <filename>/var/db/statd.status</filename> file. The final
> + option listed here is the <command>rpc.lockd</command> option,
> + which, when selected, will provide for file locking. This is
> + usually used with <command>rpc.statd</command> to monitor what
> + hosts are requesting locks and how frequent they request them.
> + While these last two options are marvelous for debugging, they
> + are not required for <acronym>NFS</acronym> servers and clients
> + to operate correctly.</para>
> +
> + <para>As we progress down the list the next item here is
> + <option>Routd</option>, which is the route daemon. The
Is the option really 'Routd' or 'Routed'? I don't have a way to check
this at the moment.
> + &man.routed.8; utility manages the network routing tables,
> + discovers multicast routers, and supplies a copy of the routing
> + tables to any physically connected host on the network upon
> + request. This is mainly used for routing
> + <quote>connectionless</quote> protocols (see &man.icmp.4 and
> + &man.udp.4;). When selected, a menu will be presented
> + requesting the default location of the utility. The default
> + location is already defined for you and can be selected with
> + the <keycap>Enter</keycap> key. You will then be presented
> + with yet another menu, this time asking for the flags you wish
> + to be passed on to <command>routed</command>. The default is
> + <literal>-q</literal> and it should already appear on the
> + screen.</para>
> +
> + <para>Next in line is the <option>Rwhod</option> option which,
> + when selected, will have the &man.rwhod.8; daemon start up
> + during system initialization. The <command>rwhod</command>
> + utility broadcasts system messages across the network
> + periodically, or collects them when in <quote>consumer</quote>
> + mode. This utility is great for monitoring the status of
> + machines on the network, but can be highly annoying when in
> + <quote>producer mode</quote> as it will broadcast messages
> + every three minutes or so.</para>
> +
> + <para>Next to the last option in the list we have the
Usually seen as:
<para>The next to last option in the list we have the ...
> + &man.sshd.8; daemon. This is the secure shell server for
> + <application>OpenSSH</application> and it is highly recommended
> + over the standard <command>telnet</command> and
> + <acronym>FTP</acronym> servers. The <command>sshd</command>
> + server is used to create a secure connection from one host to
> + another by using encryption connections.</para>
s/encryption/encrypted/
seems better to me.
> +
> + <para>Finally there is the <acronym>TCP</acronym> Extensions
> + option. This enables the <acronym>TCP</acronym> Extensions
> + as defined by <acronym>RFC</acronym> 1323 and
> + <acronym>RFC</acronym> 1644. While on many hosts this can
> + speed up connections, but can also cause some connections to
s/but/it/
seems better to me.
> + or be dropped. It is not recommended for servers but may be
s/or//
> + beneficial for stand alone machines.</para>
> +
> + <para>Now that we have configured the network services, we can
> + scroll up to the very top item which is <option>Exit</option>
> + and continue on to the next configuration section.</para>
> +
> + </sect2>
> +
> <sect2 id="x-server">
> <title>Configure X Server</title>
General Note:
The text fluctuates between first, second, and third person- sometimes in
close proximity. You may wish to review this as it causes an unnecessary
shift in perspective for the reader.
Quite a good effort overall.
As always all comments meant with Best Regards,
jpb
===
More information about the freebsd-doc
mailing list