From c405269a35570120ea1efbc5a1346b8e724e52a0 Mon Sep 17 00:00:00 2001 From: Warren Block Date: Sat, 23 Aug 2014 17:54:21 +0000 Subject: [PATCH] Add new sysutils/ezjail section. Reviewed on IRC, -doc, and with individuals through email. Particular thanks to Glen Barber for his experience and patience. --- .../books/handbook/jails/chapter.xml | 640 +++++++++++++++++- 1 file changed, 637 insertions(+), 3 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/jails/chapter.xml b/en_US.ISO8859-1/books/handbook/jails/chapter.xml index f589cfd48b..791befe0d3 100644 --- a/en_US.ISO8859-1/books/handbook/jails/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/jails/chapter.xml @@ -591,9 +591,10 @@ jail_www_devfs_enable="YES" # mount devfs in Simpler solutions exist, such as - sysutils/ezjail, which provides an easier - method of administering &os; jails and is not as sophisticated - as this setup. + ezjail, which provides an easier + method of administering &os; jails but is less versatile than + this setup. ezjail is covered in + more detail in . The goals of the setup described in this section are: @@ -982,4 +983,637 @@ jail_www_devfs_enable="YES" update the configuration files. + + + + Managing Jails with + <application>ezjail</application> + + + + + Warren + Block + Originally contributed by + + + + + Creating and managing multiple jails can quickly become + tedious and error-prone. Dirk Engling's + ezjail automates and greatly + simplifies many jail tasks. A basejail is + created as a template. Additional jails use &man.mount.nullfs.8; + to share many of the basejail directories without using + additional disk space. Each additional jail takes only a few + megabytes of disk space before applications are installed. + Upgrading the copy of the userland in the basejail automatically + upgrades all of the other jails. + + Additional benefits and features are described in detail on + the ezjail web site, . + + + Installing <application>ezjail</application> + + Installing ezjail consists of + adding a loopback interface for use in jails, installing the + port or package, and enabling the service. + + + + To keep jail loopback traffic off the host's loopback + network interface lo0, a second + loopback interface is created by adding an entry to + /etc/rc.conf: + + cloned_interfaces="${cloned_interfaces} lo1" + + The second loopback interface lo1 + will be created when the system starts. It can also be + created manually without a restart: + + &prompt.root; service netif cloneup +Created clone interfaces: lo1. + + Jails can be allowed to use aliases of this secondary + loopback interface without interfering with the + host. + + Inside a jail, access to the loopback address + 127.0.0.1 is + redirected to the first IP address + assigned to the jail. To make the jail loopback + correspond with the new lo1 interface, + that interface must be specified first in the list of + interfaces and IP addresses given when + creating a new jail. + + Give each jail a unique loopback address in the + 127.0.0.0/8 netblock. + + + + Install + sysutils/ezjail: + + &prompt.root; cd /usr/ports/sysutils/ezjail +&prompt.root; make install clean + + + + Enable ezjail by adding + this line to /etc/rc.conf: + + ezjail_enable="YES" + + + + The service will automatically start on system boot. + It can be started immediately for the current + session: + + &prompt.root; service ezjail start + + + + + + Initial Setup + + With ezjail installed, the + basejail directory structure can be created and populated. + This step is only needed once on the jail host + computer. + + In both of these examples, causes the + ports tree to be retrieved with &man.portsnap.8; into the + basejail. That single copy of the ports directory will be + shared by all the jails. Using a separate copy of the ports + directory for jails isolates them from the host. The + ezjail FAQ + explains in more detail: . + + + + + + To Populate the Jail with &os;-RELEASE + + For a basejail based on the &os; RELEASE matching + that of the host computer, use + install. For example, on a host + computer running &os; 10-STABLE, the latest + RELEASE version of &os; -10 will be installed in + the jail): + + &prompt.root; ezjail-admin install -p + + + + To Populate the Jail with + <command>installworld</command> + + The basejail can be installed from binaries + created by buildworld on + the host with + ezjail-admin update. + + In this example, &os; 10-STABLE has been + built from source. The jail directories are created. + Then installworld is + executed, installing the host's + /usr/obj into the + basejail. + + &prompt.root; ezjail-admin update -i -p + + The host's /usr/src is used + by default. A different source directory on the host + can be specified with and a path, + or set with ezjail_sourcetree in + /usr/local/etc/ezjail.conf. + + + + + + + The basejail's ports tree is shared by other jails. + However, downloaded distfiles are stored in the jail that + downloaded them. By default, these files are stored in + /var/ports/distfiles within each + jail. /var/ports inside each jail is + also used as a work directory when building ports. + + + + + Creating and Starting a New Jail + + New jails are created with + ezjail-admin create. In these examples, + the lo1 loopback interface is used as + described above. + + + Create and Start a New Jail + + + Create the jail, specifying a name and the loopback + and network interfaces to use, along with their + IP addresses. In this example, the + jail is named dnsjail. + + &prompt.root; ezjail-admin create dnsjail 'lo1|127.0.1.1,em0|192.168.1.50' + + + Most network services run in jails without + problems. A few network services, most notably + &man.ping.8;, use + raw network sockets. In jails, raw + network sockets are disabled by default for security. + Services that require them will not work. + + Occasionally, a jail genuinely needs raw sockets. + For example, network monitoring applications often use + &man.ping.8; to check the availability of other + computers. When raw network sockets are actually needed + in a jail, they can be enabled by editing the + ezjail + configuration file for the individual jail, + /usr/local/etc/ezjail/jailname. + Modify the parameters + entry: + + export jail_jailname_parameters="allow.raw_sockets=1" + + Do not enable raw network sockets unless services in + the jail actually require them. + + + + + Start the jail: + + &prompt.root; ezjail-admin start dnsjail + + + + Use a console on the jail: + + &prompt.root; ezjail-admin console dnsjail + + + + The jail is operating and additional configuration can be + completed. Typical settings added at this point + include: + + + + Set the + <systemitem class="username">root</systemitem> + Password + + Connect to the jail and set the + root user's + password: + + &prompt.root; ezjail-admin console dnsjail +&prompt.root; passwd +Changing local password for root +New Password: +Retype New Password: + + + + Time Zone Configuration + + The jail's time zone can be set with &man.tzsetup.8;. + To avoid spurious error messages, the &man.adjkerntz.8; + entry in /etc/crontab can be + commented or removed. This job attempts to update the + computer's hardware clock with time zone changes, but + jails are not allowed to access that hardware. + + + + <acronym>DNS</acronym> Servers + + Enter domain name server lines in + /etc/resolv.conf so + DNS works in the jail. + + + + Edit <filename>/etc/hosts</filename> + + Change the address and add the jail name to the + localhost entries in + /etc/hosts. + + + + Configure <filename>/etc/rc.conf</filename> + + Enter configuration settings in + /etc/rc.conf. This is much like + configuring a full computer. The host name and + IP address are not set here. Those + values are already provided by the jail + configuration. + + + + With the jail configured, the applications for which the + jail was created can be installed. + + + Some ports must be built with special options to be used + in a jail. For example, both of the network monitoring + plugin packages + net-mgmt/nagios-plugins and + net-mgmt/monitoring-plugins + have a JAIL option which must be enabled + for them to work correctly inside a jail. + + + + + Updating Jails + + + Updating the Operating System + + Because the basejail's copy of the userland is shared by + the other jails, updating the basejail automatically updates + all of the other jails. Either source or binary updates can + be used. + + To build the world from source on the host, then + install it in the basejail, use: + + &prompt.root; ezjail-admin update -b + + If the world has already been compiled on the host, + install it in the basejail with: + + &prompt.root; ezjail-admin update -i + + Binary updates use &man.freebsd-update.8;. These + updates have the same limitations as if + &man.freebsd-update.8; were being run directly. The most + important one is that only -RELEASE versions of &os; are + available with this method. To update the basejail to the + latest patched release of the version of &os; on the host + computer, use: + + &prompt.root; ezjail-admin update -r + + After updating the basejail, &man.mergemaster.8; can be + run to update each jail's configuration files. + + How to use &man.mergemaster.8; depends on the purpose + and trustworthiness of a jail. If a jail's services or + users are not trusted, then &man.mergemaster.8; should only + be run from within that jail: + + + &man.mergemaster.8; on Untrusted Jail + + Delete the link from the jail's + /usr/src into the basejail and + create a new /usr/src in the jail + as a mountpoint. Mount the host computer's + /usr/src read-only on the jail's + new /usr/src mountpoint: + + &prompt.root; rm /usr/jails/jailname/usr/src +&prompt.root; mkdir /usr/jails/jailname/usr/src +&prompt.root; mount -t nullfs -o ro /usr/src /usr/jails/jailname/usr/src + + Get a console in the jail: + + &prompt.root; ezjail-admin console jailname + + Inside the jail, run mergemaster. + Then exit the jail console: + + &prompt.root; cd /usr/src +&prompt.root; mergemaster -U +&prompt.root; exit + + Finally, unmount the jail's + /usr/src: + + &prompt.root; umount /usr/jails/jailname/usr/src + + + + + &man.mergemaster.8; on Trusted Jail + + If the users and services in a jail are trusted, + &man.mergemaster.8; can be run from the host: + + &prompt.root; mergemaster -U -D /usr/jails/jailname + + + + + Updating Ports + + The ports tree in the basejail is shared by the other + jails. Updating that copy of the ports tree gives the other + jails the updated version also. + + The basejail ports tree is updated with + &man.portsnap.8;: + + &prompt.root; ezjail-admin update -P + + + + + Controlling Jails + + + Stopping and Starting Jails + + ezjail automatically starts + jails when the computer is started. Jails can be manually + stopped and restarted with stop and + start: + + &prompt.root; ezjail-admin stop sambajail +Stopping jails: sambajail. + + By default, jails are started automatically when the + host computer starts. Autostarting can be disabled + with config: + + &prompt.root; ezjail-admin config -r norun seldomjail + + This takes effect the next time the host computer is + started. A jail that is already running will not be + stopped. + + Enabling autostart is very similar: + + &prompt.root; ezjail-admin config -r run oftenjail + + + + Archiving and Restoring Jails + + Use archive to create a + .tar.gz archive of a jail. The file + name is composed from the name of the jail and the current + date. Archive files are written to the archive directory, + /usr/jails/ezjail_archives. A + different archive directory can be chosen by setting + ezjail_archivedir in the configuration + file. + + The archive file can be copied elsewhere as a backup, or + an existing jail can be restored from it with + restore. A new jail can be created from + the archive, providing a convenient way to clone existing + jails. + + Stop and archive a jail named + wwwserver: + + &prompt.root; ezjail-admin stop wwwserver +Stopping jails: wwwserver. +&prompt.root; ezjail-admin archive wwwserver +&prompt.root; ls /usr/jails/ezjail-archives/ +wwwserver-201407271153.13.tar.gz + + Create a new jail named + wwwserver-clone from the archive created + in the previous step. Use the em1 + interface and assign a new IP address to + avoid conflict with the original: + + &prompt.root; ezjail-admin create -a /usr/jails/ezjail_archives/wwwserver-201407271153.13.tar.gz wwwserver-clone 'lo1|127.0.3.1,em1|192.168.1.51' + + + + + Full Example: <application>BIND</application> in a + Jail + + Putting the BIND + DNS server in a jail improves security by + isolating it. This example creates a simple caching-only name + server. + + + + The jail will be called + dns1. + + + + The jail will use IP address + 192.168.1.240 on the host's + re0 interface. + + + + The upstream ISP's DNS servers are + at 10.0.0.62 and + 10.0.0.61. + + + + The basejail has already been created and a ports tree + installed. + + + + + Create a cloned loopback interface by adding a line to + /etc/rc.conf: + + cloned_interfaces="${cloned_interfaces} lo1" + + Immediately create the new loopback interface: + + &prompt.root; service netif cloneup +Created clone interfaces: lo1. + + Create the jail: + + &prompt.root; ezjail-admin create dns1 'lo1|127.0.2.1,re0|192.168.1.240' + + Start the jail, connect to a console running on it, and + perform some basic configuration: + + &prompt.root; ezjail-admin start dns1 +&prompt.root; ezjail-admin console dns1 +&prompt.root; passwd +Changing local password for root +New Password: +Retype New Password: +&prompt.root; tzsetup +&prompt.root; sed -i .bak -e '/adjkerntz/ s/^/#/' /etc/crontab +&prompt.root; sed -i .bak -e 's/127.0.0.1/127.0.2.1/g; s/localhost.my.domain/dns1.my.domain dns1/' /etc/hosts + + Temporarily set the upstream DNS + servers in /etc/resolv.conf so ports + can be downloaded: + + nameserver 10.0.0.62 +nameserver 10.0.0.61 + + Still using the jail console, install + dns/bind99. + + &prompt.root; cd /usr/ports/dns/bind99 +&prompt.root; make -C /usr/ports/dns/bind99 install clean + + Configure the name server by editing + /usr/local/etc/namedb/named.conf. + + Create an Access Control List (ACL) + of addresses and networks that are permitted to send + DNS queries to this name server. This + section is added just before the options + section already in the file: + + ... +// or cause huge amounts of useless Internet traffic. + +acl "trusted" { + 192.168.1.0/24; + localhost; + localnets; +}; + +options { +... + + Use the jail IP address in the + listen-on setting to accept + DNS queries from other computers on the + network: + + listen-on { 192.168.1.240; }; + + A simple caching-only DNS name server + is created by changing the forwarders + section. The original file contains: + + /* + forwarders { + 127.0.0.1; + }; +*/ + + Uncomment the section by removing the + /* and */ lines. + Enter the IP addresses of the upstream + DNS servers. Immediately after the + forwarders section, add references to the + trusted ACL defined + earlier: + + forwarders { + 10.0.0.62; + 10.0.0.61; + }; + + allow-query { any; }; + allow-recursion { trusted; }; + allow-query-cache { trusted; }; + + Enable the service in + /etc/rc.conf: + + named_enable="YES" + + Start and test the name server: + + &prompt.root; service named start +wrote key file "/usr/local/etc/namedb/rndc.key" +Starting named. +&prompt.root; /usr/local/bin/dig @192.168.1.240 freebsd.org + + A response that includes + + ;; Got answer; + + shows that the new DNS server is + working. A long delay followed by a response + including + + ;; connection timed out; no servers could be reached + + shows a problem. Check the configuration settings and + make sure any local firewalls allow the new + DNS access to the upstream + DNS servers. + + The new DNS server can use itself for + local name resolution, just like other local computers. Set + the address of the DNS server in the + client computer's + /etc/resolv.conf: + + nameserver 192.168.1.240 + + A local DHCP server can be configured + to provide this address for a local DNS + server, providing automatic configuration on + DHCP clients. + + +