<commit_before>``ezjail-remote`` is a 'remote control' and convenience wrapper for the ``ezjail-admin`` command of the most excellent `ezjail <http://erdgeist.org/arts/software/ezjail/>`_ tool (which in turn is itself a convenience wrapper for `jails <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/jails.html>`_, `FreeBSD <http://www.freebsd.org>`_'s leight-weight virtualization solution).

Its main features are:

 * more sophisticated support for flavours, i.e. interactive configuration and/or templating as opposed to ezjail's hardcoded flavours
 * you can ssh into jails created by ``ezjail-remote`` immediately upon creation (no more manual mucking about with sshd config or uploading your public key!)
 * unlike ``ezjail-admin``, ``ezjail-remote`` is not invoked on the jail host, but on your local machine.

Usage
=====

ezjail-remote uses the `fabric <http://docs.fabfile.org>`_ library to remotely run its tasks. Basically it provides a so-called *fabfile* that contains all of the commands of ``ezjail-admin`` (version 3.1 as of this writing).

This means that its usage differs slightly from that of ``ezjail-admin``. In particular, you provide the hostname of the jail server via the ``-H`` switch and the parameters for the command (such as the name of the jail etc) separated with a colon, like so::

  ezjail-remote -H host(s) <COMMAND>:param1,param2,param3

or::

  ezjail-remote -H host(s) <COMMAND>:param1=foo,param3=bar

See the `full documentation of what fabric has to offer here <http://docs.fabfile.org/en/1.2.0/usage/fab.html#command-line-options>`_.

In particualar, you can...

 * run ``ezjail-remote --help`` to see a list of the available *options*
 * run ``ezjail-remote -l`` to see a list of the available *commands*
 * run ``ezjail-remote -d COMMAND`` to see a detailed description of a command

As a side effect of using fabric, you can run ezjail-admin commands against multiple jailhosts at the same time.

Commands
========

In its simplest form, ezjail remote offers the exact same commands as ezjail-admin, namely ``[archive|config|console|create|delete|install|list|restore|start|stop|update]``. In addition to that it provides enhanced versions of ``create`` and ``destroy`` (the latter a more thorough variant of the ``delete`` command.)

create
------

creates a new jail instance on the given host, creates an admin user with sudo privileges and enables ssh access via public key.

after setting up the jail it attempts to execute a method named ``setup`` from ``ezjailremote.flavours.<name-of-flavour>``, passing on all parameters, including any additional, arbitrary keyword arguments.

parameters
**********

name
  name of the new jail, *required*

IP
  the IP address, *required*

admin
  name of the admin user for the jail, defaults to the current user. the user will be created and added to ``wheel`` (which in turn will be allowed to sudo without password).

keyfile
  public key to install for the admin user, defaults to ``~/.ssh/identity.pub``.

flavour
  the name of the local flavour, defaults to ``basic``.


destroy
-------

stops, removes and deletes the given jail instance (but not before asking you one last time, explicitely). however, once you confirm, the jail is irrevocably *gone*.

parameters
**********

name
  name of the new jail, *required*

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

Simply use easy_install::

  easy_install ezjail-remote

Development
===========

To develop ezjail-remote itself, check out a copy of this repository and then::

  virtualenv . --no-site-package
  ./bin/python setup.py develop

TODO:

 * document flavour development
 * use a base class for flavours
 * list them (with their docstr) with ezjail-remote list-flavours
 * allow chaining/nesting/stacking of flavours (i.e. always include basic)<commit_msg>explain the resoning behind the remote concept.<commit_after>``ezjail-remote`` is a 'remote control' and convenience wrapper for the ``ezjail-admin`` command of the most excellent `ezjail <http://erdgeist.org/arts/software/ezjail/>`_ tool (which in turn is itself a convenience wrapper for `jails <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/jails.html>`_, `FreeBSD <http://www.freebsd.org>`_'s leight-weight virtualization solution).

Its main features are:

 * more sophisticated support for flavours, i.e. interactive configuration and/or templating as opposed to ezjail's hardcoded flavours
 * you can ssh into jails created by ``ezjail-remote`` immediately upon creation (no more manual mucking about with sshd config or uploading your public key!)
 * unlike ``ezjail-admin``, ``ezjail-remote`` is not installed on the jail host, but on your local machine. This means *it doesn't introduce any further dependencies on the jail host whatsoever* (ezjail itself purposefully limits itself to ``sh``).

Usage
=====

ezjail-remote uses the `fabric <http://docs.fabfile.org>`_ library to remotely run its tasks. Basically it provides a so-called *fabfile* that contains all of the commands of ``ezjail-admin`` (version 3.1 as of this writing).

This means that its usage differs slightly from that of ``ezjail-admin``. In particular, you provide the hostname of the jail server via the ``-H`` switch and the parameters for the command (such as the name of the jail etc) separated with a colon, like so::

  ezjail-remote -H host(s) <COMMAND>:param1,param2,param3

or::

  ezjail-remote -H host(s) <COMMAND>:param1=foo,param3=bar

See the `full documentation of what fabric has to offer here <http://docs.fabfile.org/en/1.2.0/usage/fab.html#command-line-options>`_.

In particualar, you can...

 * run ``ezjail-remote --help`` to see a list of the available *options*
 * run ``ezjail-remote -l`` to see a list of the available *commands*
 * run ``ezjail-remote -d COMMAND`` to see a detailed description of a command

As a side effect of using fabric, you can run ezjail-admin commands against multiple jailhosts at the same time.

Commands
========

In its simplest form, ezjail remote offers the exact same commands as ezjail-admin, namely ``[archive|config|console|create|delete|install|list|restore|start|stop|update]``. In addition to that it provides enhanced versions of ``create`` and ``destroy`` (the latter a more thorough variant of the ``delete`` command.)

create
------

creates a new jail instance on the given host, creates an admin user with sudo privileges and enables ssh access via public key.

after setting up the jail it attempts to execute a method named ``setup`` from ``ezjailremote.flavours.<name-of-flavour>``, passing on all parameters, including any additional, arbitrary keyword arguments.

parameters
**********

name
  name of the new jail, *required*

IP
  the IP address, *required*

admin
  name of the admin user for the jail, defaults to the current user. the user will be created and added to ``wheel`` (which in turn will be allowed to sudo without password).

keyfile
  public key to install for the admin user, defaults to ``~/.ssh/identity.pub``.

flavour
  the name of the local flavour, defaults to ``basic``.


destroy
-------

stops, removes and deletes the given jail instance (but not before asking you one last time, explicitely). however, once you confirm, the jail is irrevocably *gone*.

parameters
**********

name
  name of the new jail, *required*

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

Simply use easy_install::

  easy_install ezjail-remote

Development
===========

To develop ezjail-remote itself, check out a copy of this repository and then::

  virtualenv . --no-site-package
  ./bin/python setup.py develop

TODO:

 * document flavour development
 * use a base class for flavours
 * list them (with their docstr) with ezjail-remote list-flavours
 * allow chaining/nesting/stacking of flavours (i.e. always include basic)
{'fraction_non_alphanumeric': 0.10483767483639163, 'fraction_numerical': 0.003849608623123316, 'mean_word_length': 4.4389392882065595, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4836294', 'n_tokens_mistral': 2288, 'n_tokens_neox': 2183, 'n_words': 1005}