Date: Mon, 13 Feb 2012 00:39:08 -0500 (EST) From: Benjamin Kaduk <kaduk@MIT.EDU> To: Eitan Adler <lists@eitanadler.com> Cc: freebsd-doc@freebsd.org Subject: Re: CfR: config chapter changes Message-ID: <alpine.GSO.1.10.1202120028440.882@multics.mit.edu> In-Reply-To: <CAF6rxgnvyoibFt7ijm6GpWoeF-eAOLu3SgvhEGCBDUAV4grybw@mail.gmail.com> References: <CAF6rxgnvyoibFt7ijm6GpWoeF-eAOLu3SgvhEGCBDUAV4grybw@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, 10 Feb 2012, Eitan Adler wrote: > I started working on editing the config chapter. The following is the work of > Niclas Zeising, wblock, myself, and others in the #bsddocs channel. > > I'm looking for additional review of the following patch: > http://people.freebsd.org/~eadler/files/yoda-can-has-a-donught.diff Inline patches are easier to review. % Index: chapter.sgml % =================================================================== % RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml,v % retrieving revision 1.250 % diff -u -r1.250 chapter.sgml % --- chapter.sgml 31 Jan 2012 14:14:59 -0000 1.250 % +++ chapter.sgml 10 Feb 2012 01:15:29 -0000 % @@ -475,22 +475,21 @@ % <para>The <command>cron</command> utility uses two different % types of configuration files, the system crontab and user crontabs. The % only difference between these two formats is the sixth field. In the % - system crontab, the sixth field is the name of a user for the command % - to run as. This gives the system crontab the ability to run commands % - as any user. In a user crontab, the sixth field is the command to run, % + system crontab, <command>cron</command> will run the command as this user. % + In a user crontab, the sixth field is the command to run, I can't see how this could possibly be correct. A command line in a crontab requires a command to run, which would be a seventh field in the system crontab. But this is not mentioned at all, here! % and all commands run as the user who created the crontab; this is an % important security feature.</para> % % <note> % <para>User crontabs allow individual users to schedule tasks without the % - need for <username>root</username> privileges. Commands in a user's crontab run with the % - permissions of the user who owns the crontab.</para> % + need for <username>root</username> privileges. Commands in a user's crontab run with the % + permissions of the user who owns the crontab.</para> Are these just whitespace changes? % % <para>The <username>root</username> user can have a user crontab just like % - any other user. This one is different from % - <filename>/etc/crontab</filename> (the system crontab). Because of the % - system crontab, there is usually no need to create a user crontab % - for <username>root</username>.</para> % + any other user. <username>root</username>'s crontab is % + distinct from <filename>/etc/crontab</filename> (the system crontab). % + Because of the system crontab, there is usually no need to % + create a user crontab for <username>root</username>.</para> % </note> Fine. % % <para>Let us take a look at the <filename>/etc/crontab</filename> file % @@ -547,11 +546,9 @@ % day of the week. All these fields must be numeric values, and follow % the twenty-four hour clock. The <literal>who</literal> field is special, % and only exists in the <filename>/etc/crontab</filename> file. % - This field specifies which user the command should be run as. % - When a user installs his or her <filename>crontab</filename> file, they % - will not have this option. Finally, the <literal>command</literal> option is listed. % - This is the last field, so naturally it should designate the command % - to be executed.</para> % + The command will be run as the user named in this % + field. Finally, the last field is the command to be % + executed.</para> This feels a bit odd; most of the sentences here have "the [nth] field" as the subject of the sentence, so switching to having the command be the subject seems out-of-place. I think I would keep the first sentence as-is, but dropping the "When a user..." sentence is probably okay. "Finally, the last field" feels a bit redundant. % </callout> % % <callout arearefs="co-main"> % @@ -584,13 +581,13 @@ % <title>Installing a Crontab</title> % % <important> % - <para>You must not use the procedure described here to % - edit/install the system crontab. Simply use your favorite % - editor: the <command>cron</command> utility will notice that the file % - has changed and immediately begin using the updated version. % - See % - <ulink url="&url.books.faq;/admin.html#ROOT-NOT-FOUND-CRON-ERRORS"> % - this FAQ entry </ulink> for more information.</para> % + <para>Do not use the procedure described here to % + edit and install the system crontab. Simply use your favorite % + editor: the <command>cron</command> utility will notice that the file % + has changed and immediately begin using the updated version. % + See % + <ulink url="&url.books.faq;/admin.html#ROOT-NOT-FOUND-CRON-ERRORS">this FAQ entry</ulink> We should be able to make this line shorter, right? % + for more information.</para> % </important> % % <para>To install a freshly written user [snip some minor/formatting changes] % @@ -2390,15 +2386,35 @@ % <xref linkend="swap-encrypting"> of the Handbook.</para> % % <sect2 id="new-drive-swap"> % - <title>Swap on a New Hard Drive</title> % + <title>Swap on a New or Existing Hard Drive</title> % + % + <para>The best way to add swap space, and the way that gives the best % + performance, is to add a new swap partition on an existing or new hard % + drive. Setting up partitions and hard drives is explained in % + <xref linkend="disks-adding">. <xref linkend="configtuning-initial"> % + discusses partition layouts and swap partition size considerations.</para> The old text was sort of advocating for using a new drive for swap, but it seems to have not actually mentioned (at least in the context that is quoted) perhaps the best reason for doing so: having a dedicated spindle for swap avoids extra seeks from competition with normal i/o. It would seem that if we are going to claim there is a "best" way, it should involve a dedicated drive. % + % + <para>Use &man.swapon.8; to add a swap partition to the system. For example:</para> % + % + <screen>&prompt.root; <userinput>swapon<replaceable>/dev/ada1s1p2</replaceable></userinput></screen> % + % + <warning> % + <para>It is possible to use any partition not currently mounted, even % + if it already contains data. Using &man.swapon.8; on a partition that % + contains data will overwrite and destroy that data. % + Make sure that the partition to be added as swap % + is really the intended partition before running % + <command>swapon</command>.</para> % + </warning> % + Hmm, I thought that that there would be a check for the swap partition type, but glancing through the kernel code (vm/swap_pager.c) makes it seem like swap can be enabled in a great many places... % + <para>To automatically add this swap partition on boot, % + add an entry to <filename>/etc/fstab</filename> for the % + partition:</para> % + % + <programlisting><replaceable>/dev/ada1s1p1</replaceable> none swap sw 0 0</programlisting> % % - <para>The best way to add swap, of course, is to use this as an % - excuse to add another hard drive. You can always use another % - hard drive, after all. If you can do this, go reread the % - discussion of swap space % - in <xref linkend="configtuning-initial"> % - of the Handbook for some suggestions on how to best % - arrange your swap.</para> % + <para>&man.fstab.5; explains the entries in % + <filename>/etc/fstab</filename>.</para> I kind of feel like "explains the entries" is too concise. Are we looking for the meaning of the entries, or their format, or something else? % </sect2> % % <sect2 id="nfs-swap"> [snip more minor stuff] -Ben Kaduk
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.GSO.1.10.1202120028440.882>