From owner-freebsd-doc@FreeBSD.ORG Mon Feb 13 05:39:13 2012 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 12839106566B for ; Mon, 13 Feb 2012 05:39:13 +0000 (UTC) (envelope-from kaduk@mit.edu) Received: from dmz-mailsec-scanner-1.mit.edu (DMZ-MAILSEC-SCANNER-1.MIT.EDU [18.9.25.12]) by mx1.freebsd.org (Postfix) with ESMTP id A0A1E8FC1F for ; Mon, 13 Feb 2012 05:39:12 +0000 (UTC) X-AuditID: 1209190c-b7fad6d000000920-cd-4f38a1ffa30c Received: from mailhub-auth-1.mit.edu ( [18.9.21.35]) by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP id D2.D3.02336.FF1A83F4; Mon, 13 Feb 2012 00:39:11 -0500 (EST) Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id q1D5dBcH016156; Mon, 13 Feb 2012 00:39:11 -0500 Received: from multics.mit.edu (MULTICS.MIT.EDU [18.187.1.73]) (authenticated bits=56) (User authenticated as kaduk@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id q1D5d84O011911 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Mon, 13 Feb 2012 00:39:11 -0500 (EST) Received: (from kaduk@localhost) by multics.mit.edu (8.12.9.20060308) id q1D5d8B6025435; Mon, 13 Feb 2012 00:39:08 -0500 (EST) Date: Mon, 13 Feb 2012 00:39:08 -0500 (EST) From: Benjamin Kaduk To: Eitan Adler In-Reply-To: Message-ID: References: User-Agent: Alpine 1.10 (GSO 962 2008-03-14) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFvrBIsWRmVeSWpSXmKPExsUixCmqrPt/oYW/we/DVhanznSxWiw60c7k wOQxbfNBNo8Zn+azBDBFcdmkpOZklqUW6dslcGW8vDGDrWCvXcWNXf2sDYyHDLoYOTkkBEwk Tiz9wwhhi0lcuLeerYuRi0NIYB+jxMl9/YwQzgZGic87VrNDOAeYJE6f7WSFcBoYJRZuPcIC 0s8ioC1x6P4qJhCbTUBFYuabjWwgtoiAmsS7191gO5gFpCUa1m8GqxEW0JCY8mwe0CAODk6B QIkVi8NBwrwC9hJ/3p5mBAkLCQRIXHpnDxIWFdCRWL1/CgtEiaDEyZlPWCAmWkr8W/uLdQKj 4CwkqVlIUgsYmVYxyqbkVunmJmbmFKcm6xYnJ+blpRbpGurlZpbopaaUbmIEB6okzw7GNweV DjEKcDAq8fAGFFv4C7EmlhVX5h5ilORgUhLljV4AFOJLyk+pzEgszogvKs1JLT7EKMHBrCTC qxcDlONNSaysSi3Kh0lJc7AoifOqaL3zExJITyxJzU5NLUgtgsnKcHAoSfD6AyNSSLAoNT21 Ii0zpwQhzcTBCTKcB2g4K0gNb3FBYm5xZjpE/hSjLsfErvUXGIVY8vLzUqXEeXNBigRAijJK 8+DmwBLMK0ZxoLeEeRtAqniAyQlu0iugJUxAS6TPmYAsKUlESEk1MJYxKpndeRmveGFpTsrs J11362rc/Hfv481m5rKMnHdZ9qM8+9uTfed+MxpO+519UsLue+TGY4FWKaWpATcjvY/bxs+9 xTv1Q0mmjsOpu9Y2Vdb7ajONI27l3rTJDTJeXTFDcPkijUuuDRP+h0Smd7v8kl/5Ikr8RfST hjQ1zmo9fl2dn+8eKLEUZyQaajEXFScCAJZCXTALAwAA Cc: freebsd-doc@freebsd.org Subject: Re: CfR: config chapter changes X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 13 Feb 2012 05:39:13 -0000 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 @@ % The cron 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, cron 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. % % % User crontabs allow individual users to schedule tasks without the % - need for root privileges. Commands in a user's crontab run with the % - permissions of the user who owns the crontab. % + need for root privileges. Commands in a user's crontab run with the % + permissions of the user who owns the crontab. Are these just whitespace changes? % % The root user can have a user crontab just like % - any other user. This one is different from % - /etc/crontab (the system crontab). Because of the % - system crontab, there is usually no need to create a user crontab % - for root. % + any other user. root's crontab is % + distinct from /etc/crontab (the system crontab). % + Because of the system crontab, there is usually no need to % + create a user crontab for root. % Fine. % % Let us take a look at the /etc/crontab file % @@ -547,11 +546,9 @@ % day of the week. All these fields must be numeric values, and follow % the twenty-four hour clock. The who field is special, % and only exists in the /etc/crontab file. % - This field specifies which user the command should be run as. % - When a user installs his or her crontab file, they % - will not have this option. Finally, the command option is listed. % - This is the last field, so naturally it should designate the command % - to be executed. % + The command will be run as the user named in this % + field. Finally, the last field is the command to be % + executed. 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. % % % % @@ -584,13 +581,13 @@ % Installing a Crontab % % % - You must not use the procedure described here to % - edit/install the system crontab. Simply use your favorite % - editor: the cron utility will notice that the file % - has changed and immediately begin using the updated version. % - See % - % - this FAQ entry for more information. % + Do not use the procedure described here to % + edit and install the system crontab. Simply use your favorite % + editor: the cron utility will notice that the file % + has changed and immediately begin using the updated version. % + See % + this FAQ entry We should be able to make this line shorter, right? % + for more information. % % % To install a freshly written user [snip some minor/formatting changes] % @@ -2390,15 +2386,35 @@ % of the Handbook. % % % - Swap on a New Hard Drive % + Swap on a New or Existing Hard Drive % + % + 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 % + . % + discusses partition layouts and swap partition size considerations. 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. % + % + Use &man.swapon.8; to add a swap partition to the system. For example: % + % + &prompt.root; swapon/dev/ada1s1p2 % + % + % + 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 % + swapon. % + % + 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... % + To automatically add this swap partition on boot, % + add an entry to /etc/fstab for the % + partition: % + % + /dev/ada1s1p1 none swap sw 0 0 % % - 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 % - of the Handbook for some suggestions on how to best % - arrange your swap. % + &man.fstab.5; explains the entries in % + /etc/fstab. 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? % % % [snip more minor stuff] -Ben Kaduk