- FreeBSD in a chroot
finch - FreeBSD in a chroot
finch <cmd> [args] finch --help
chroot - Chroot into Finch FreeBSD (`chroot /path/to/finch`). start - Mount Finch and start it's rc.d services. stop - Stop Finch's rc.d services and unmount "finch/dev". restart - Same as `finch stop` followed by `finch start`. status - Report on Finch service status (enabled/disabled). export - Map a new command into Finch exports (`finch export <cmd>`). -export - Remove a command from Finch exports (`finch -export <cmd>`). <export> - Run a command listed in Finch exports (`finch <export>`). update - Update the Finch scripts (this program) to the latest version. refresh - Refresh /finch/etc/ files (resolv.conf, localtime & passwd). bootstrap - Run the curl-based online installation script `finch-bootstrap`. realpath - The real path to Finch ("$finch_realpath", "/path/to/finch"). --version - Print the current version of Finch and exit. -h,--help - Display this message and exit.
Finch is FreeBSD running inside a
chroot. Finch is best used as a way to extend the functionality of restricted USB-based FreeBSD distributions, usually FREENAS and NAS4FREE. For added convenience, Finch also includes the
qjail jails management tool. Since FreeBSD jails are such a popular request.
Recommended system configuration:
Restricted FreeBSD host <--> Finch <--> qjail <--> your jails
Chroot into the Finch environment by typing
finch chroot. All other operations may be performed by
issuing relevant subcommand.
finch --help for more information. Or visit the website at
STARTING / STOPPING
You may manually start or stop Finch at any time simply by issuing the relevant finch subcommand
finch start or
finch stop. See
finch --help for more information. However the boot-time mechanisms for running Finch are platform-specific.
On FreeNAS and NAS4Free hosts, the Finch POSTINIT and SHUTDOWN scripts must be entered into the relevant web-based configuration pages. Which will tell FreeNAS / NAS4Free to automatically start and stop Finch at bootup and shutdown.
For other platforms such as FreeBSD-GENERIC where the traditional rc.d mechanism is properly supported, the Finch service can be started / stopped in the normal manner with it's rc.d script. The necessary rc.conf statements are automatically added to the system's /etc/rc.conf file for you during installation. To prevent conflicts between multiple installed instances, the Finch rc.d script is given a unique name: /etc/rc.d/finch-path.to.finch.
To execute the
finch command, your user account must be a member of group
wheel. This is
because on FreeBSD the
chroot command requires root user level access privileges. Therefore, to
run Finch commands also requires at least administrator level permissions.
Finch will auto-configure sudo for all
wheel users without a password, by ensuring the sudo entry
%wheel ALL=(ALL) NOPASSWD: ALL) is included in your host's sudoers file. This auto-configuration
is considered necessary as to use Finch effectively requires a frequent invocation of the
command. The necessary configuration is handled automatically.
It is also highly recommended to configure the default user login shell to the
automatically adds it's login profile to
/etc/profile, which is automatically sourced by the
The Finch login profile adds further convenience whilst invoking commands through sudo or from the
Finch exports list. This Finch login profile is not exclusively only for bash. It may be sourced
by any POSIX.2 compatible shell, (bourne-style shell), for example FreeBSD's
/bin/sh. In which
case, please consult the shell's documentation for loading /etc/profile.
The Finch exports feature provides a way to auto-chroot for certain frequently-used commands. If not present on the host environment, the command is searched for and executed within the Finch chroot environment instead. Of course whilst inside the chroot, the root tree and filesystem are not accessible. This is worth remembering.
Updating Finch administrative scripts is trivial, and can be done at any time with
finch update. Upgrading the version of FreeBSD located inside Finch's chroot is a more delicate and involved
process. Full instructions are up on the website at http://dreamcat4.github.io/finch/upgrading.
$finch_realpath/usr/sbin/finch --> /usr/sbin/finch For additional instances, manually symlink finch2,3 into /usr/sbin/
STARTUP / SHUTDOWN
$finch_realpath/etc/finch/postinit $finch_realpath/etc/finch/shutdown - OR - $finch_realpath/etc/rc.d/finch --> /etc/rc.d/finch-path.to.finch
$finch_realpath/etc/finch/ $finch_realpath/var/db/finch/ $finch_realpath/var/log/finch/ $finch_realpath/var/distfiles/finch/
For the most up-to-date documentation please visit the project homepage at http://dreamcat4.github.io/finch.
Can be reported at http://dreamcat4.github.io/finch/support.
Dreamcat4, firstname.lastname@example.org (C 2014). FreeBSD License.
- April 2014