From owner-freebsd-doc@FreeBSD.ORG Tue Sep 30 17:36:41 2003 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id E445116A4BF for ; Tue, 30 Sep 2003 17:36:40 -0700 (PDT) Received: from sixshooter.v6.thrupoint.net (sixshooter.v6.thrupoint.net [65.242.152.6]) by mx1.FreeBSD.org (Postfix) with ESMTP id D2F374400B for ; Tue, 30 Sep 2003 17:36:38 -0700 (PDT) (envelope-from jpb@sixshooter.v6.thrupoint.net) Received: from sixshooter.v6.thrupoint.net (localhost.v6.thrupoint.net [127.0.0.1]) by sixshooter.v6.thrupoint.net (Postfix) with ESMTP id E9D004E36 for ; Tue, 30 Sep 2003 20:36:37 -0400 (EDT) Received: (from jpb@localhost)h910abLG084837 for FreeBSD-doc@FreeBSD.org; Tue, 30 Sep 2003 20:36:37 -0400 (EDT) Date: Tue, 30 Sep 2003 20:36:37 -0400 From: Jim Brown To: FreeBSD-doc@FreeBSD.org Message-ID: <20031001003637.GB84749@sixshooter.v6.thrupoint.net> Mail-Followup-To: FreeBSD-doc@FreeBSD.org References: <20030930180215.7438ba73.trhodes@FreeBSD.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20030930180215.7438ba73.trhodes@FreeBSD.org> User-Agent: Mutt/1.4.1i Subject: Re: Quick review requested X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 01 Oct 2003 00:36:41 -0000 * Tom Rhodes [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. > > > + > + Configure Additional Network Services > + > + 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. "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. > + > + Selecting the Networking option will bring forth a menu > + similar to the one below: s/bring forth/display/ seems a bit better to me. > + > +
> + Network Configuration Upper-level > + > + > + > + > + > + > +
> + > + The first option, Interfaces, was previously covered during > + the Network Device Configuration section; thus we can bypass > + this option. You are in the first person here. > + > + Selecting the option adds > + support for the BSD auto mount utility. > + This is usually used in conjunction with the > + NFS protocol (see below) > + for automatically mounting remote file systems. > + No special configuration > + is required here. > + > + Next in line is the AMD flags > + option. When selected, a menu will pop up for you > + to enter specific AMD flags. > + The menu already contains a set of default options: > + > + -a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map > + > + The -a option specifies the default mount > + location which is listed here as /.amd_mnt. > + The -l option specifies the default > + log file; however, when &man.syslogd.8; is I would use syslog 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 /host is used to mount an exported > + file system from a remote hostname, while > + /net is used to mount an exported file > + system from an IP address. The > + /etc/amd.map defines the default options > + for AMD exports. > + > + The Anon FTP 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: "The Anon FTP option permits anonymous ..." or something similar. > + FTP 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. > + > + The 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. > + > + The option can be used to configure or > + completely disable the &man.inetd.8; daemon as discussed above. > + > + The is used to configure the system's > + default MTA or mail server. Selecting this > + option will bring forth the following menu: > + > +
> + Select a default MTA > + > + > + > + > + > + > +
> + > + Here the user is given a choice as to which > + MTA, or Mail Transfer Agent to install > + and set as the default. An MTA is nothing > + more than a mail server which delivers email to users on the > + system or the Internet. > + > + Selecting Sendmail will install > + the popular Sendmail server which > + is the &os; default. The option > + will set Sendmail to be the default > + MTA, but disables its ability to receive > + incoming email from the Internet. The other options here, > + Postfix and > + Exim act similar to > + Sendmail, as in they both deliver "as in they both" doesn't work for me. Perhaps: "Sendmail. They both deliver ..." > + email; however, selecting either of these is more of a user > + preference than anything else. > + > + After selecting an MTA, 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 NFS client. > + > + The NFS client will > + set the machine to work as a client for an > + NFS server. An NFS server > + exports remotely mounted file systems to other machines on the local > + network via the NFS protocol. If this is > + a stand alone machine, this option can remain unselected. The > + system may require more configuration later, see > + for more > + information about client and server configuration. > + > + Below that option is the > + NFS server option, > + permitting a user to set the system up as an > + NFS server. This adds the required > + information to start up the RPC remote > + procedure call services. RPC is used to > + coordinate connections between hosts and programs. > + > + Next in line is the option, > + which deals with time synchronization. When selected, a menu > + like the one below shows up: > + > +
> + Ntpdate Configuration > + > + > + > + > + > + > +
> + > + 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. > + > + Our next option is the > + PCNFSD selection. This > + option will install the > + net/pcnfsd package from > + the ports collection. This is a useful utility which provides > + NFS authentication services for systems which > + are unable to provide their own. For instance, Microsoft's > + DOS operating system. > + > + Now we must scroll down a bit to see the other options: > + > +
> + Network Configuration Lower-level > + > + > + > + > + > + > +
> + > + The &man.rpcbind.8;, &man.rpc.statd.8;, and > + &man.rpc.lockd.8; utilities are all used for Remote Procedure > + Calls (RPC). The rpcbind.8 > + utility handles the communication between NFS > + servers, their clients, and is required for > + NFS servers to operate correctly. The > + rpc.statd daemon interacts with the > + rpc.statd daemon on other hosts to provide > + status monitoring. The reported status is usually held in the > + /var/db/statd.status file. The final > + option listed here is the rpc.lockd option, > + which, when selected, will provide for file locking. This is > + usually used with rpc.statd 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 NFS servers and clients > + to operate correctly. > + > + As we progress down the list the next item here is > + , 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 > + connectionless 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 Enter key. You will then be presented > + with yet another menu, this time asking for the flags you wish > + to be passed on to routed. The default is > + -q and it should already appear on the > + screen. > + > + Next in line is the option which, > + when selected, will have the &man.rwhod.8; daemon start up > + during system initialization. The rwhod > + utility broadcasts system messages across the network > + periodically, or collects them when in consumer > + mode. This utility is great for monitoring the status of > + machines on the network, but can be highly annoying when in > + producer mode as it will broadcast messages > + every three minutes or so. > + > + Next to the last option in the list we have the Usually seen as: The next to last option in the list we have the ... > + &man.sshd.8; daemon. This is the secure shell server for > + OpenSSH and it is highly recommended > + over the standard telnet and > + FTP servers. The sshd > + server is used to create a secure connection from one host to > + another by using encryption connections. s/encryption/encrypted/ seems better to me. > + > + Finally there is the TCP Extensions > + option. This enables the TCP Extensions > + as defined by RFC 1323 and > + RFC 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. > + > + Now that we have configured the network services, we can > + scroll up to the very top item which is > + and continue on to the next configuration section. > + > + > + > > Configure X Server 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 ===