Date: Wed, 20 Feb 2002 09:05:56 +0000 From: Ceri <setantae@submonkey.net> To: Tom Rhodes <darklogik@pittgoth.com> Cc: freebsd-doc@freebsd.org Subject: Re: docs/35098: [PATCH] Handbook NFS stuff Message-ID: <20020220090556.GA2535@rhadamanth> In-Reply-To: <200202200350.g1K3o2D95303@freefall.freebsd.org> References: <200202200350.g1K3o2D95303@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Feb 19, 2002 at 07:50:02PM -0800, Tom Rhodes wrote:
>
> Please review this, it has alot of your ideas, but a few of my own
> tossed in here. I did cover more ground than listed, and have yet
> to touch the amd part, well, more than the first paragraph hehe
This is a large patch, so I am going to be as terse as possible with my
comments; sorry to stick my oar in, if Michael and yourself would rather
sort this out between yourselves that's cool too.
> + the Network File System also known as <acronym>NFS</acronym>.
...System, also...
OR
...System (<acronym>NFS</acronym> for short). <!--this one's yucky-->
> + <acronym>NFS</acronym> allows your system to share directories and files on
> + with others over the network.
That doesn't make sense.
> + <para>Some of the benefits for using <acronym>NFS</acronym> are:</para>
..benefits of using..
> - <title>How It Works</title>
> + <title>How <acronym>NFS</acronym> Works</title>
Don't think we need acronym there ??
> + <para><acronym>NFS</acronym> consists of at least two parts; a client and
> + a server. The client remotely accesses the data that is stored locally
> + on the server machine. In order for this to function properly a few
> + processes have to be configured and running:</para>
i) indentation is cack here;
ii) the words remotely and locally here are potentially confusing.
> - <entry>The NFS Daemon which services requests from NFS
> - clients.</entry>
> + <entry>The <acronym>NFS</acronym> daemon which serves requests from
> + the <acronym>NFS</acronym> clients.</entry>
I prefer the original "services requests" to "serves requests", which doesn't
seem to make sense.
> - <entry>The NFS Mount Daemon which actually carries out
> + <entry>The <acronym>NFS</acronym> mount daemon which actually carries out
> requests that &man.nfsd.8; passes on to it.</entry>
I know this isn't your copy, but :
"actually carries out requests" seems redundant, viz.
The NFS mount daemon which actually carries out requests that nfsd
passes on to it (as opposed to silently discarding them like all
the other processes do).
> + <entry> The <command>portmapper</command> daemon
> + allows <acronym>NFS</acronym> clients to find out which port the
> + <acronym>NFS</acronym> server is using.</entry>
i) indentation is all cack again
ii) s/find out/discover/
iii) {setantae@rhadamanth}-{~} $ portmapper
portmapper: Command not found.
Not a <command> at all, then.
> + <para>The client can also run a daemon, known as
> + <application>nfsiod</application>. The <application>nfsiod</application>
> + daemon services the requests from a <acronym>NFS</acronym> server. This,
> + is optional, and improves performance, but not really required for normal
> + and correct operation. See the &man.nfsiod.8; man page for more information.
..performance, but is not...
> - <para>On the NFS server make sure you have:</para>
> + <para>On the <acronym>NFS</acronym> server, make sure that the following options
> + in the <filename>/etc/rc.conf</filename> file:</para>
Doesn't make sense.
make sure that the following options are configured in the <fil... ??
> + <para><command>mountd</command> runs automatically whenever the
> + <acronym>NFS</acronym> server is enabled. The <option>-u</option> and
> + <option>-t</option> flags tell <command>nfsd</command> to
I'm going to complain about indentation again...
> - <para>Like <command>nfsd</command>, the <option>-n 4</option> tells
> + <para>Like with <command>nfsd</command>, the <option>-n 4</option> tells
> <command>nfsiod</command> to start 4 copies of itself.</para>
s/Like/As/
> + <para>The <acronym>NFS</acronym> configuration requires that a file
> + called <filename>/etc/exports</filename> exsists. The exports file
> + specifies which file systems on your server will be exported
> + or <quote>shared</quote> and with what clients they will
> + exported too. Each line in the file specifies a file system to be
> + exported. There are many options that can be used in this
i) indentation, indentation, indentation
ii) |ispell ? s/exsists/exists/ ?
ii) I prefer this :
<para><acronym>NFS</acronym> configuration requires that a file
named <filename>/etc/exports</filename> exist. The exports file
specifies which filesystems on the server will be shared (or
<firstterm>exported</firstterm>), and with which clients. Each
line in <filename>/etc/exports</filename> specifies a filesystem
to be exported and the options with which this will be done. There
are many such option that can be used in this...
Assuming of course, that <firstterm> is valid in the Handbook.
Otherwise, maybe <quote>.
> - <secondary>exporting filesystems</secondary>
> + <secondary>examples of exporting filesystems</secondary>
I don't feel that's necessary in an <indexterm>.
> + <para>In the following examples, an idea of how to export filesystems
> + is displayed, although the settings may be different depending on
> + environment and network setup.
If we're using "you/your" (as we are above), I'd prefer "..depending on your
environment and..." here.
> - <programlisting>/cdrom -ro moe larry curly</programlisting>
> + <programlisting>/cdrom -ro example1 example2 example3</programlisting>
s/example/host/g ?
> + private network but do not have a <acronym>DNS</acronym> server configured. The
> + <option>-alldirs</option> flag allows for all of the directories below
> the specified file system to be exported as well.</para>
Don't think that both of "all of" and "as well" are necessary.
> + <para>The following line exports <filename>/a</filename> so that two
> + machines with different domain names may access the server. The
> + <option>-maproot=0</option> flag allows the <username>root</username>
indentation :)
> + user on the remote system to write data on the exported file system as
> + <username>root</username>. Without the -maproot=0 flag, even if
-maproot=0 isn't an option anymore ?
> + someone has <username>root</username> access on the remote system they will not
> + be able to modify files on the exported file system.</para>
>
> - <programlisting>/a -maproot=0 host.domain.com box.example.com</programlisting>
> + <programlisting>/a -maproot=0 host.example.com box.example2.com</programlisting>
example2.com isn't a documentation friendly domain.
example.org instead ?
> - <para>In <filename>/etc/exports</filename>, each line represents
> + <para>In the <filename>/etc/exports</filename> file, each line represents
> the export information for one filesystem to one host. A
> - remote host can only be specified once for each local
> - filesystem, and you can only have one default entry per local
> + remote host can only be specified once per
> + filesystem, and may only have one default entry for each
> filesystem. For example, let's assume that
> <filename>/usr</filename> is a single filesystem. The
> - following <filename>/etc/exports</filename> is invalid:</para>
> + following <filename>/etc/exports</filename> would be invalid:</para>
I've been responsible for some rather spectacular NFS abortions in my time,
and I still don't understand the above paragraph.
What's a default entry ?
I don't like from here until the end of the section at all :
> - <para>You must restart
> - <command>mountd</command> whenever you modify
> - <filename>/etc/exports</filename> to make changes take
> - effect. This can be accomplished by sending the hangup signal
> + <para>You must restart <command>mountd</command> whenever you modify
> + <filename>/etc/exports</filename> to make the changes current.
> + This can be accomplished by either sending the hangup signal
The "or" that goes with this "either" is too far away.
> + <para>Or, a simple reboot should make FreeBSD set everything up
> + for you. Although, a reboot is not nessissary
> + the following commands, run as <username>root</username> of course,
> + could start everything up also.</para>
i) s/nessissary/necessary/
ii) It doesn't scan at all.
iii) A reboot _will_ work, if everything is set up correctly.
> name will be <literal>client</literal>. If you just want to
> - temporarily mount a remote file system or just want to test out
> - your configuration you can run a command like this as root on the
> + temporarily mount a remote file system or just want to test the
> + configuration, just run a command like this as <username>root</username> on the
> client:</para>
That sentence contains the word "just" at least three times.
Just use "just" just once ;)
> <para>This will mount the <filename>/home</filename> directory
> on the server at <filename>/mnt</filename> on the client. If
> - everything is setup correctly you should be able to go into
> - /mnt on the client and see all the files that are on the
> + everything is setup correctly you should be able to enter
I'll get in here before Gary does ;)
s/setup/set up/
> <para>If you want to automatically mount a remote file system
> + <para>The &man.fstab.5; manual page will show many more options that are available.</para>
> </sect2>
The &man.fstab.5; manual page lists all available options.
> + <para>There are many practical uses for <acronym>NFS</acronym>. Some of the
> + more common ones are listed below:</para>
> +
> + <note><para>The following practicle <acronym>NFS</acronym> examples require
You already said they were practical.
s/practicle//
> + the proper <acronym>NFS</acronym> configuration before actual use.</para>
NFS to be correctly configured...
> - <para>Have several machines on a network and share a CDROM or
> - floppy drive among them. This is cheaper and often more
> - convenient.</para>
> + <para>Setup several machines on a network to share a CDROM or
> + floppy drive among them. This is cheaper and often more convenient.</para>
s/Setup/Set up/
> - <para>With so many machines on a network, it gets old having your
> - personal files strewn all over the place. You can have a
> - central NFS server that houses all user home directories and
> - shares them with the rest of the machines on the LAN, so no
> - matter where you log in you will have the same home
> - directory.</para>
> + <para>With so many machines on a network, you can have a
> + central <acronym>NFS</acronym> server store the user home directories and
> + export them with the rest of the machines on the network, this way
> + users can have the same home directory, regardless of which workstation
> + they log in to.</para>
With how many machines ?
And it won't work if I've got N-1 machines ?
(picky in the extreme, I know)
> - <para>&man.amd.8;, which is also known as the automatic mounter
> + <para>&man.amd.8;, also known as the automatic mounter
&man.amd.8; (the automatic mounter daemon) ...
> - to static mounts.</para>
> + to perminant mounts.</para>
eh ?
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020220090556.GA2535>