Bug 187142

Summary: [handbook] [patch] The Handbook (chapter 15.4) does not mention /etc/jail.conf
Product: Documentation Reporter: Jack-Benny Persson <jack-benny>
Component: Books & ArticlesAssignee: freebsd-doc (Nobody) <doc>
Status: Closed FIXED    
Severity: Affects Only Me CC: emaste, joeb1
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   
Attachments:
Description Flags
file.diff none

Description Jack-Benny Persson 2014-02-28 13:50:00 UTC 
FreeBSD Handbook chapter 15.4 (Creating and Controlling Jails).
Since FreeBSD 9.1 the /etc/jail.conf file is the recommended way to configure jails. The Handbook does not mention this in it's present form.

Fix: Patch attached with submission follows:
Comment 1 Eitan Adler freebsd_committer freebsd_triage 2017-12-31 08:00:32 UTC 
For bugs matching the following criteria:

Status: In Progress Changed: (is less than) 2014-06-01

Reset to default assignee and clear in-progress tags.

Mail being skipped
Comment 2 Ed Maste freebsd_committer freebsd_triage 2018-02-26 14:39:39 UTC 
Thank you for your submission, and I apologize that nobody has looked at this in four years. I encountered this just now, and will see that this gets in.
Comment 3 Ed Maste freebsd_committer freebsd_triage 2018-02-26 17:00:21 UTC 
I've posted a change based on your patch at https://reviews.freebsd.org/D14524. Given that all supported FreeBSD releases now use jail.conf I think we should just remove documentation of the old configuration.
Comment 4 Jack-Benny Persson 2018-02-26 17:13:45 UTC 
(In reply to Ed Maste from comment #2)
No worries. I'm just glad if it makes it into the handbook, and that it is helpful.
Comment 5 joeb1 2018-02-27 16:02:51 UTC 
I also think removing all the old configuration documentation is the best solution. To this all the ezjail documentation should also be removed because ezjail uses the rc.conf configuration. 

Documenting how to use a port does not belong in the handbook, it belongs in the port's manual. This had been the original policy of the handbook, but as younger personal replaced the original handbook administration this policy was violated with the addition of the ezjail section. 

A second issue is that readers of the jail section of the handbook see the ezjail section and believe that tool is the recommended tool to use just because its in the handbook. This is unfair to the other jail tools which use jail.conf. 

For inspiration on a new jail section check out the jail-primer port.
Comment 6 commit-hook freebsd_committer freebsd_triage 2018-03-06 12:56:29 UTC 
A commit references this bug:

Author: emaste
Date: Tue Mar  6 12:55:32 UTC 2018
New revision: 51462
URL: https://svnweb.freebsd.org/changeset/doc/51462

Log:
  Document jail.conf Jail configuration

  jail.conf is the preferred method of configuring jails in all supported
  FreeBSD versions.  Older rc.conf(5) configuration produces a warning.
  Update the handbook example to match based on the submission in the PR,
  with a few modifications.

  PR:		187142
  Submitted by:	Jack-Benny Persson
  Reviewed by:	bcr, eadler
  Approved by:	bcr, eadler
  Sponsored by:	The FreeBSD Foundation
  Differential Revision:	https://reviews.freebsd.org/D14524

Changes:
  head/en_US.ISO8859-1/books/handbook/jails/chapter.xml
Comment 7 Ed Maste freebsd_committer freebsd_triage 2018-03-06 17:38:16 UTC 
(In reply to joeb1 from comment #5)
That may be the case but is outside of the scope of this PR, and I'm not a doc committer or understand the history well enough. We should probably have this discussion on the freebsd-jail mailing list instead.