From owner-freebsd-doc@FreeBSD.ORG Sat May 17 23:40:00 2014 Return-Path: Delivered-To: freebsd-doc@smarthost.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id A3F42B73 for ; Sat, 17 May 2014 23:40:00 +0000 (UTC) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:1900:2254:206c::16:87]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 8048B2279 for ; Sat, 17 May 2014 23:40:00 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.8/8.14.8) with ESMTP id s4HNe03L076425 for ; Sat, 17 May 2014 23:40:00 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.8/8.14.8/Submit) id s4HNe0WC076424; Sat, 17 May 2014 23:40:00 GMT (envelope-from gnats) Resent-Date: Sat, 17 May 2014 23:40:00 GMT Resent-Message-Id: <201405172340.s4HNe0WC076424@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Sevan Janiyan Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 1A07EAB9 for ; Sat, 17 May 2014 23:36:15 +0000 (UTC) Received: from cgiserv.freebsd.org (cgiserv.freebsd.org [IPv6:2001:1900:2254:206a::50:4]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 06DF9224F for ; Sat, 17 May 2014 23:36:15 +0000 (UTC) Received: from cgiserv.freebsd.org ([127.0.1.6]) by cgiserv.freebsd.org (8.14.8/8.14.8) with ESMTP id s4HNaEBZ012106 for ; Sat, 17 May 2014 23:36:14 GMT (envelope-from nobody@cgiserv.freebsd.org) Received: (from nobody@localhost) by cgiserv.freebsd.org (8.14.8/8.14.8/Submit) id s4HNaEXI012105; Sat, 17 May 2014 23:36:14 GMT (envelope-from nobody) Message-Id: <201405172336.s4HNaEXI012105@cgiserv.freebsd.org> Date: Sat, 17 May 2014 23:36:14 GMT From: Sevan Janiyan To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.1 Subject: docs/189901: Update the jail section of the handbook X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 17 May 2014 23:40:00 -0000 >Number: 189901 >Category: docs >Synopsis: Update the jail section of the handbook >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Sat May 17 23:40:00 UTC 2014 >Closed-Date: >Last-Modified: >Originator: Sevan Janiyan >Release: 11.0-CURRENT >Organization: >Environment: FreeBSD 11.0-CURRENT FreeBSD 11.0-CURRENT #0 r266021M >Description: The following changes where made Mention that jails is operating system level virtualisation Describe that it's possible to install perbuilt binaries as well as build from source. Instructions on how to extract distfiles on 8.x & earlier / 9.0 & later Remove reference to jail_www_devfs_ruleset rc.conf, as-is it prevents the jail from starting because a ruleset needs to be defined & as there is no documentation for that in the article, it's easier to remove it, by doing this, the default ruleset is applied. Add instructions on how to keep jails up to date with freebsd-update. >How-To-Repeat: >Fix: Patch attached with submission follows: Index: jails/chapter.xml =================================================================== --- jails/chapter.xml (revision 44837) +++ jails/chapter.xml (working copy) @@ -50,7 +50,9 @@ host system. Jails expand this model by virtualizing access to the file system, the set of users, and the networking subsystem. More fine-grained controls are available for tuning the access - of a jailed environment. + of a jailed environment. + Jails can be considered as a type of operating system-level + virtualization A jail is characterized by four elements: @@ -194,9 +196,75 @@ system, and service jails, dedicated to one application or service, possibly running with privileges. This is only a conceptual division and the process of building a jail - is not affected by it. The &man.jail.8; manual page is quite - clear about the procedure for building a jail: + is not affected by it. + When creating a complete jail there are two + options for the source of the userland, use prebuilt binaries + (such as those supplied on a install media ) or build from + source. + To install the userland from installation media, first + create the root directory for the jail. + + Set the DESTDIR variable to this + location. + + If using sh + + &prompt.root; export DESTDIR=/here/is/the/jail + + If using csh/tcsh + + &prompt.root; setenv DESTDIR /here/is/the/jail + + mount the install media as covered in &man.mdconfig.8; + if using the install ISO + + &prompt.root; mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt + + Extract the binaries from the tar balls on the install media + into the declared destination, realistically, only the base set + needs to be extracted but a complete install can be performed if + preferred. + + To install just base: + + On &os; 9.x and newer + + &prompt.root; tar -xf /mnt/freebsd_install/usr/freebsd_dist/base.txz -C $DESTDIR + + On &os; 8.x + + &prompt.root; /mnt/8.4-RELEASE/base/install.sh + + To install everything but kernel: + + If using sh + + On &os; 9.x and newer + + &prompt.root; for sets in BASE DOC GAMES PORTS; do (tar -xf /mnt/FREEBSD_INSTALL/USR/FREEBSD_DIST/$sets.TXZ -C $DESTDIR + + On &os; 8.x + + &prompt.root; cd /mnt/8.4-RELEASE; for dir in base catpages dict doc games info manpages ports; do (cd $dir ; ./install.s h) ; done + + If using csh/tcsh + + On &os; 9.x and newer + + &prompt.root; foreach sets ( BASE DOC GAMES PORTS ) + tar -xf /mnt/FREEBSD_INSTALL/USR/FREEBSD_DIST/$sets.TXZ -C $DESTDIR + done + + On &os; 8.x + + &prompt.root; foreach dir ( base catpages dict doc games info manpages ports ) + cd /mnt/8.4-RELEASE/$dir; ./install.sh + done + + The &man.jail.8; manual page is quite clear about the + procedure for building a jail from source: + &prompt.root; setenv D /here/is/the/jail &prompt.root; mkdir -p $D &prompt.root; cd /usr/src @@ -299,8 +367,7 @@ jail_www_rootdir="/usr/jail/www" # jail's root directory jail_www_hostname="www.example.org" # jail's hostname jail_www_ip="192.168.0.10" # jail's IP address -jail_www_devfs_enable="YES" # mount devfs in the jail -jail_www_devfs_ruleset="www_ruleset" # devfs ruleset to apply to jail +jail_www_devfs_enable="YES" # mount devfs in the jail The default startup of jails configured in &man.rc.conf.5;, will run the /etc/rc @@ -460,6 +527,24 @@ applications that contribute to &man.jail.8; management. Please refer to its web page for more information. + + + Keeping jails patched and up to date + + Jails should be kept up to date from the host operating + system as attempting to patch userland from within the jail + may likely fail as the default behaviour in FreeBSD is to + disallow the use of &man.chflags.1; in a jail which prevents + the replacement of some files. + It's possible to change this behaviour but it is recommended + to use &man.freebsd-update.8; to maintain jails instead. + Using the option the path of the jail to + be updated can be specified. + + &prompt.root; freebsd-update -b /here/is/the/jail fetch +&prompt.root; freebsd-update -b /here/is/the/jail install + + >Release-Note: >Audit-Trail: >Unformatted: