Package: ploy-ezjail
OverviewThe ploy_ezjail plugin provides integration ofezjailwithployto manageFreeBSDjails.Installationploy_ezjail is best installed with easy_install, pip or with zc.recipe.egg in a buildout.MastersTo use ploy_ezjail you need a host running FreeBSD on which you want to manage jails.You declare a master with[ez-master:masterid]wheremasteridis the name you want to use for this master.
Now you can either add options like for aplainploy instance, or you can use theinstanceoption to refer to another instance from your config like this:[ez-master:master1]
host = myhost.example.com

[plain-instance:foohost]
host = foohost.example.com

[ez-master:master2]
instance = foohostThe latter is most useful in conjunction with other ploy backend plugins, as it allows you to easily switch between provisioners, i.e. to have anez-masterprovisioned on VirtualBox during development and on aplaininstance in production.Optionsdebug-commandsIf set toyes, the commands executed on the host are echoed locally.instanceThe instance to use as host for this master.
If empty, the local machine is used without an ssh connection.ezjail-adminPath to theezjail-adminscript on the host.
Defaults to/usr/local/bin/ezjail-admin.sudoUsesudoto run commands on the host.ezjail-use-one-prefixUseoneprefix forstartandstopcommands.
This is useful whenezjail_enable="NO"is set in/etc/rc.conf.OptionalInstancesAt the moment all jails will be created using ZFS (the-czfsoption ofezjail-admin), so the host needs to be setup accordingly.OptionsipThe ip address to use for the jail.This can either be a single IPv4 address:ip = 10.0.0.3or any number of IPv4 and IPv6 addresses attached to different devices:ip = lo1|10.0.0.3,vtnet0|2a03:b0c0:3:d0::3a4d:c002The latter format isezjail’sown.Requiredezjail-flavourTheflavourto use for this jail. This is explained in theezjail docs.ezjail-nameThenameto use for the jail. By default the id of the instance is used.mountsAdditional mount points for the jail.
You can specify one mount point per line.
The format is:src=SRC dst=DST [ro=true] [create=true]Thesrcis the path on the host,dstis the path inside the jail.Ifrois set totrue, then the mount is read only.Whencreateis enabled, then thesrcpath is created withmkdir-p.
Thedstpath is always created inside the jail withmkdir-p.You can referenceZFS sectionsinsidesrcwith{zfs[name]}wherenameis theez-zfssection name.
You can use the name of the jail instance with{name}}in bothsrcanddst.
Examples:src=/foo dst=/foo
src={zfs[backup]} dst=/bak
src={zfs[data]}/{name} dst=/mnt/data create=true
src={zfs[static]} dst=/mnt/static ro=trueno-terminateIf set toyes, the jail can’t be terminated via ploy until the setting is changed tonoor removed entirely.startup_scriptPath to a local script (relative to the location of the configuration file) which will be run inside the jail right after creation and first start of the jail.rc_requireString that indicates which other jails this jail requires to start up, effectively allowing you to define the startup order of jails.
Seercorder(8)for more details.
This value is written upon each startup of the jail not just when it is created initially, so to have changes take effect, it’s sufficient to restart it.Optionalrc_provideString that indicates what this jail provides.ezjailitself always sets its jails to providestandard_ezjailto whichploy_ezjailadds the name of the jail.
IOW if you simply want to build a startup order using the names of the jails, you will not need to set this value.
If you want this jail to provide any additional values, set them here.
This value is written upon each startup of the jail not just when it is created initially, so to have changes take effect, it’s sufficient to restart it.Optionalrc_beforeString that indicates before which other jails this jail should start up, effectively allowing you to define the startup order of jails.
Seercorder(8)for more details.
This value is written upon each startup of the jail not just when it is created initially, so to have changes take effect, it’s sufficient to restart it.Optionaljail_*Allows to set jail specific setting. For examplejail_devfs_ruleset="5"to use devfs ruleset number 5 for this jail.
Seeman ezjail“Per-Jail options” (skip theJAILNAMEpart from the option names).OptionalZFS sectionsYou can specify ZFS filesystems via[ez-zfs:name]sections.
This is used in mounts of jails to get the mountpoint and verify that the path exists and is it’s own ZFS filesystem.
You can also create new ZFS filesystems with thecreateoption.OptionscreateIf set toyes, the filesystem is created when first used.pathSpecifies the path of this filesystem.
This is not the mountpoint, but the ZFS path.
You can reference other ZFS sections with{zfs[name][path]}.
Thenameis the name of the referenced ZFS section.
The[path]at the end is mandatory, as otherwise you would get the mountpoint of the referenced ZFS section.
Examples:[ez-zfs:data]
path = tank/data

[ez-zfs:shared]
path = {zfs[data][path]}/shared

[ez-zfs:jails]
path = {zfs[data][path]}/jails

[ez-zfs:backup]
create = true
path = tank/backupChangelog2.0.0 - 2022-08-17Dropped support for Python 3.6.
[fschulze]Added support for Python 3.10.
[fschulze]Addrc_beforeoption.
[fschulze]Add support for jail specific settings.
[fschulze]Addezjail-use-one-prefixoption.
[fschulze]Renamedflavouroption toezjail-flavour.
The old one still works, but will be deprecated in the future.
[fschulze]2.0.0b4 - 2021-07-16Fix Python 3.x encoding errors when reporting errors from ezjail commands.
[fschulze]Use full instance name for logging ininit_ssh_keyfor easier debugging
in case of multiple masters.
[fschulze]2.0.0b3 - 2020-05-13Fix ZFS sections for Python 3.
[fschulze]2.0.0b2 - 2019-06-09Some Python 3.x encoding related fixes.
[fschulze]Drop Python 3.4 support.
[fschulze]2.0.0b1 - 2018-02-07Support for ploy 2.0.0.
[fschulze]1.5.1 - 2018-02-03Fix startup script for FreeBSD 11.x by replacing dots in it’s name with
underscores.
[fschulze]1.5.0 - 2017-12-17Addget_fingerprintsto support host keys with all key types.
[fschulze]Fix jail hoststatuscommand for various cases.
[fschulze]Output stdout in addition to stderr on various errors. This let’s one see
additional debug info when jails don’t start.
[fschulze]1.4.0 - 2015-10-16Allow setting the jail name viaezjail-nameinstead of using the instance
id as the default.
[fschulze]1.3.0 - 2015-09-03Improved error handling with useful error messages instead of tracebacks.
[fschulze]Allow setting startup order of jails.
[tomster]1.2.0 - 2015-03-05Use newExecutorhelper from ploy 1.2.0 which handles ssh agent forwarding.
[fschulze]Enable “local mode” where if theinstanceoption is empty all commands
are executed locally.
[fschulze]1.1.0 - 2014-10-27Print status of all jails when requesting status of master.
[fschulze]Check jail status before trying to connect.
[fschulze]Use new helper in ploy 1.0.2 to setup proxycommand.
[fschulze]1.0.0 - 2014-07-19Added documentation.
[fschulze]1.0b9 - 2014-07-08Packaging and test fixes.
[fschulze]1.0b8 - 2014-07-04Python 3 compatibility.
[fschulze]Renamed mr.awsome to ploy and mr.awsome.ezjail to ploy_ezjail.
[fschulze]1.0b7 - 2014-06-16Provide default values forproxyhostandproxycommandoptions.
[fschulze]Merge config of ez-master with the instance it’s using.
[fschulze]1.0b6 - 2014-06-11Pass changes of proxy instance config on to the proxied instance config.
[fschulze]1.0b5 - 2014-06-10Forcefully destroy jail. Together with ezjail 3.4.1 this solves the issue
that sometimes the ZFS filesystem wasn’t removed and the jail couldn’t be
started without manual intervention.
[fschulze]1.0b4 - 2014-05-22Clear out massagers after copying the config for the proxy instance to
prevent conflicts when the proxy instance is created.
[fschulze]1.0b3 - 2014-05-21Fixes to make[instance:...]using an ez-master work.
[fschulze]1.0b2 - 2014-05-15Addedinstanceoption to ez-master section to use another instance as
the jail host.
[fschulze, tomster]Moved setuptools-git from setup.py to .travis.yml, it’s only needed for
releases and testing.
[fschulze]1.0b1 - 2014-03-24Initial release
[fschulze]