ploy-ezjail 2.0.0
Plugin for ploy to provision FreeBSD jails using ezjail.
License: BSD 3-Clause License
Requires Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*

Overview
========

The ploy_ezjail plugin provides integration of `ezjail`_ with `ploy`_ to manage `FreeBSD`_ jails.

.. _ezjail: http://erdgeist.org/arts/software/ezjail/
.. _ploy: https://github.com/ployground/
.. _FreeBSD: http://www.freebsd.org


Installation
============

ploy_ezjail is best installed with easy_install, pip or with zc.recipe.egg in a buildout.


Masters
=======

To use ploy_ezjail you need a host running FreeBSD on which you want to manage jails.

You declare a master with ``[ez-master:masterid]`` where ``masterid`` is the name you want to use for this master.
Now you can either add options like for a ``plain`` ploy instance, or you can use the ``instance`` option 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 = foohost

The latter is most useful in conjunction with other ploy backend plugins, as it allows you to easily switch between provisioners, i.e. to have an ``ez-master`` provisioned on VirtualBox during development and on a ``plain`` instance in production.


Options
-------

``debug-commands``
  If set to ``yes``, the commands executed on the host are echoed locally.

``instance``
  The instance to use as host for this master.
  If empty, the local machine is used without an ssh connection.

``ezjail-admin``
  Path to the ``ezjail-admin`` script on the host.
  Defaults to ``/usr/local/bin/ezjail-admin``.

``sudo``
  Use ``sudo`` to run commands on the host.

``ezjail-use-one-prefix``
  Use ``one`` prefix for ``start`` and ``stop`` commands.
  This is useful when ``ezjail_enable="NO"`` is set in ``/etc/rc.conf``.
  **Optional**


Instances
=========

At the moment all jails will be created using ZFS (the ``-c zfs`` option of ``ezjail-admin``), so the host needs to be setup accordingly.


Options
-------

``ip``
  The ip address to use for the jail.

  This can either be a single IPv4 address::

      ip = 10.0.0.3

  or any number of IPv4 and IPv6 addresses attached to different devices::

      ip = lo1|10.0.0.3,vtnet0|2a03:b0c0:3:d0::3a4d:c002

  The latter format is `ezjail's <http://erdgeist.org/arts/software/ezjail/>`_ own.
  **Required**

``ezjail-flavour``
  The **flavour** to use for this jail. This is explained in the `ezjail docs <http://erdgeist.org/arts/software/ezjail/>`_.

``ezjail-name``
  The **name** to use for the jail. By default the id of the instance is used.

``mounts``
  Additional mount points for the jail.
  You can specify one mount point per line.
  The format is::

      src=SRC dst=DST [ro=true] [create=true]

  The ``src`` is the path on the host, ``dst`` is the path inside the jail.

  If ``ro`` is set to ``true``, then the mount is read only.

  When ``create`` is enabled, then the ``src`` path is created with ``mkdir -p``.
  The ``dst`` path is always created inside the jail with ``mkdir -p``.

  You can reference `ZFS sections`_ inside ``src`` with ``{zfs[name]}`` where ``name`` is the ``ez-zfs`` section name.
  You can use the name of the jail instance with ``{name}}`` in both ``src`` and ``dst``.
  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=true

``no-terminate``
  If set to ``yes``, the jail can't be terminated via ploy until the setting is changed to ``no`` or removed entirely.

``startup_script``
  Path 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_require``
  String that indicates which other jails this jail requires to start up, effectively allowing you to define the startup order of jails.
  See ``rcorder(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.
  **Optional**

``rc_provide``
  String that indicates what this jail provides.
  ``ezjail`` itself always sets its jails to provide ``standard_ezjail`` to which ``ploy_ezjail`` adds 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.
  **Optional**

``rc_before``
  String that indicates before which other jails this jail should start up, effectively allowing you to define the startup order of jails.
  See ``rcorder(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.
  **Optional**

``jail_*``
  Allows to set jail specific setting. For example ``jail_devfs_ruleset="5"`` to use devfs ruleset number 5 for this jail.
  See ``man ezjail`` "Per-Jail options" (skip the ``JAILNAME`` part from the option names).
  **Optional**


ZFS sections
============

You 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 the ``create`` option.


Options
-------

``create``
  If set to ``yes``, the filesystem is created when first used.

``path``
  Specifies the path of this filesystem.
  This is not the mountpoint, but the ZFS path.
  You can reference other ZFS sections with ``{zfs[name][path]}``.
  The ``name`` is 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/backup


Changelog
=========

2.0.0 - 2022-08-17
------------------

* Dropped support for Python 3.6.
  [fschulze]

* Added support for Python 3.10.
  [fschulze]

* Add ``rc_before`` option.
  [fschulze]

* Add support for jail specific settings.
  [fschulze]

* Add ``ezjail-use-one-prefix`` option.
  [fschulze]

* Renamed ``flavour`` option to ``ezjail-flavour``.
  The old one still works, but will be deprecated in the future.
  [fschulze]


2.0.0b4 - 2021-07-16
--------------------

* Fix Python 3.x encoding errors when reporting errors from ezjail commands.
  [fschulze]

* Use full instance name for logging in ``init_ssh_key`` for easier debugging
  in case of multiple masters.
  [fschulze]


2.0.0b3 - 2020-05-13
--------------------

* Fix ZFS sections for Python 3.
  [fschulze]


2.0.0b2 - 2019-06-09
--------------------

* Some Python 3.x encoding related fixes.
  [fschulze]

* Drop Python 3.4 support.
  [fschulze]


2.0.0b1 - 2018-02-07
--------------------

* Support for ploy 2.0.0.
  [fschulze]


1.5.1 - 2018-02-03
------------------

* Fix startup script for FreeBSD 11.x by replacing dots in it's name with
  underscores.
  [fschulze]


1.5.0 - 2017-12-17
------------------

* Add ``get_fingerprints`` to support host keys with all key types.
  [fschulze]

* Fix jail host ``status`` command 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-16
------------------

* Allow setting the jail name via ``ezjail-name`` instead of using the instance
  id as the default.
  [fschulze]


1.3.0 - 2015-09-03
------------------

* Improved error handling with useful error messages instead of tracebacks.
  [fschulze]

* Allow setting startup order of jails.
  [tomster]


1.2.0 - 2015-03-05
------------------

* Use new ``Executor`` helper from ploy 1.2.0 which handles ssh agent forwarding.
  [fschulze]

* Enable "local mode" where if the ``instance`` option is empty all commands
  are executed locally.
  [fschulze]


1.1.0 - 2014-10-27
------------------

* Print 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-19
------------------

* Added documentation.
  [fschulze]


1.0b9 - 2014-07-08
------------------

* Packaging and test fixes.
  [fschulze]


1.0b8 - 2014-07-04
------------------

* Python 3 compatibility.
  [fschulze]

* Renamed mr.awsome to ploy and mr.awsome.ezjail to ploy_ezjail.
  [fschulze]


1.0b7 - 2014-06-16
------------------

* Provide default values for ``proxyhost`` and ``proxycommand`` options.
  [fschulze]

* Merge config of ez-master with the instance it's using.
  [fschulze]


1.0b6 - 2014-06-11
------------------

* Pass changes of proxy instance config on to the proxied instance config.
  [fschulze]


1.0b5 - 2014-06-10
------------------

* Forcefully 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-22
------------------

* Clear out massagers after copying the config for the proxy instance to
  prevent conflicts when the proxy instance is created.
  [fschulze]


1.0b3 - 2014-05-21
------------------

* Fixes to make ``[instance:...]`` using an ez-master work.
  [fschulze]


1.0b2 - 2014-05-15
------------------

* Added ``instance`` option 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-24
------------------

* Initial release
  [fschulze]