Metadata-Version: 1.1
Name: pychroot
Version: 0.9.13
Summary: a python library and cli tool that simplify chroot handling
Home-page: https://github.com/pkgcore/pychroot
Author: Tim Harder
Author-email: radhermit@gmail.com
License: BSD
Description: |pypi| |test| |coverage|
        
        ========
        pychroot
        ========
        
        pychroot is a python library and cli tool that simplify chroot handling.
        Specifically, the library provides a **Chroot** context manager that enables
        more pythonic methods for running code in chroots while the **pychroot**
        utility works much like an extended chroot command in the terminal.
        
        Usage
        =====
        
        In its simplest form, the library can be used similar to the following::
        
            from pychroot import Chroot
        
            with Chroot('/path/to/chroot'):
                code that will be run
                inside the chroot
        
        By default, this will bind mount the host's /dev, /proc, and /sys filesystems
        into the chroot as well as the /etc/resolv.conf file (so DNS resolution works
        as expected in the chroot).
        
        A simple chroot equivalent is also installed as **pychroot**. It can be used in
        a similar fashion to chroot; however, it also performs the bind mounts
        previously mentioned so the environment is usable. In addition, pychroot
        supports specifying custom bind mounts, for example::
        
            pychroot -R /home/user ~/chroot
        
        will recursively bind mount the user's home directory at the same location
        inside the chroot directory in addition to the standard bind mounts. See
        pychroot's help output for more options.
        
        When running on a system with a recent kernel (Linux 3.8 and on) and user
        namespaces enabled pychroot can be run by a regular user. Note that currently
        pychroot just maps the current user to root in the chroot environment. This
        means that recursively chown-ing the chroot directory to the user running
        pychroot should essentially allow that user to act as root in the pychroot
        environment.
        
        Implementation details
        ======================
        
        Namespaces are used by the context manager to isolate the chroot instance from
        the host system and to simplify the teardown phase for the environments. By
        default, new mount, UTS, IPC, and pid namespaces are used.  In addition, if
        running as non-root, both user and network namespaces will be enabled as well
        so that the chrooting and mounting process will work without elevated
        permissions.
        
        One quirk of note is that currently local variables are not propagated back
        from the chroot context to the main context due to the usage of separate
        processes running the contexts. This means that something similar to the
        following won't work::
        
            from pychroot import Chroot
        
            with Chroot('/path/to/chroot'):
                answer = 42
            print(answer)
        
        In this case, a NameError exception will be raised unless the variable *answer*
        was previously defined. This will probably be fixed to some extent in a future
        release.
        
        Requirements
        ============
        
        Python versions 2.7, 3.3, 3.4 are supported. Note however, that pychroot is
        quite Linux specific due to the use of namespaces via the `snakeoil`_ library
        which also require proper kernel support. Specifically, the following kernel
        config options are required to be enabled for full namespace support::
        
            CONFIG_NAMESPACES=y
            CONFIG_UTS_NS=y
            CONFIG_IPC_NS=y
            CONFIG_USER_NS=y
            CONFIG_PID_NS=y
            CONFIG_NET_NS=y
        
        Installing
        ==========
        
        In a virtualenv or elsewhere via pip::
        
            pip install pychroot
        
        From the repo manually::
        
            python setup.py install
        
        Bugs
        ====
        
        Please create an issue in the `issue tracker`_.
        
        Tests
        =====
        
        Tests are handled via pytest, run via::
        
            py.test
        
        which is also integrated into setup.py, run via::
        
            python setup.py test
        
        Also, tests for all supported python versions can be run together or
        individually via::
        
            tox
        
        Note that mock_ is required for testing with anything less than python 3.3.
        
        
        .. _`issue tracker`: https://github.com/pkgcore/pychroot/issues
        .. _`snakeoil`: https://github.com/pkgcore/snakeoil
        .. _mock: https://pypi.python.org/pypi/mock
        
        .. |pypi| image:: https://img.shields.io/pypi/v/pychroot.svg
            :target: https://pypi.python.org/pypi/pychroot
        .. |test| image:: https://travis-ci.org/pkgcore/pychroot.svg?branch=master
            :target: https://travis-ci.org/pkgcore/pychroot
        .. |coverage| image:: https://coveralls.io/repos/pkgcore/pychroot/badge.png?branch=master
            :target: https://coveralls.io/r/pkgcore/pychroot?branch=master
        
        
        Release Notes
        =============
        
        pychroot 0.9.13 (2015-12-13)
        ----------------------------
        
        - Add --no-mounts option to disable the default mounts for the command line
          tool. This makes pychroot act similar to chroot.
        
        - Make pychroot pip-installable without requiring snakeoil to be manually
          installed first.
        
        - Add lots of additional content to the pychroot utility man page.
        
        pychroot 0.9.12 (2015-08-10)
        ----------------------------
        
        - The main module was renamed from chroot to pychroot mostly for consistency to
          match the project name and cli tool installed alongside it.
        
        - Add a man page for the pychroot cli tool.
        
        - Add user namespace support so you can chroot as a regular user. Note that
          this also requires using a network namespace for which we only setup a
          loopback interface (if iproute2 is installed in the chroot) so external
          network access won't work by default in this situation.
        
        - Add an option to skip changing to the newroot directory after chrooting. This
          is similar to the option for chroot(1) but also allows skipping the directory
          change when the new root isn't '/'. In other words, you can use a chroot
          environment against the host's rootfs.
        
        - Use $SHELL from the environment for the pychroot script to mirror chroot's
          behavior.
        
        - Move WithParentSkip, the main parent/child execution splitting context
          manager allowing this all to work, to snakeoil.contextlib and rename it
          SplitExec. It was moved in order to develop other context managers around it
          in snakeoil and elsewhere more easily.
        
        - Fix additional argument parsing for the pychroot script. Now commands like::
        
            pychroot ~/chroot /bin/bash -c "ls -R /"
        
          will work as expected (i.e. how they normally work with chroot).
        
        - Allow mount propagation from the host mount namespace to the chroot's but not
          vice versa. Previously systems that set the rootfs mount as shared, e.g.
          running something like::
        
            mount --make-rshared /
        
          would leak mounts from the chroot mount namespace back into the host's
          namespace. Now the chroot mount namespace is recursively slaved from the
          host's so mount events will propagate down from host to chroot, but not back
          up from chroot to host.
        
        - Add support for setting the chroot's host and domain names for all versions
          of python. Previously we only supported setting the hostname for py33 and up.
          To set the domain name, pass an FQDN instead of a singular hostname. This
          also adds a "--hostname" option to the pychroot script that enables the same
          support for it.
        
        pychroot 0.9.11 (2015-07-05)
        ----------------------------
        
        - Fix pychroot script when no custom mountpoints as specified.
        
        pychroot 0.9.10 (2015-04-09)
        ----------------------------
        
        - Add support for custom bind mounts to the pychroot script. Now users are able
          to do things like::
        
            pychroot -R /home/user ~/chroot
        
          which will recursively bind mount their home directory into the chroot in
          addition to the standard set of bind mounts.
        
        - Use "source[:dest]" as keys for mountpoints. This enables support for
          mounting the same source onto multiple destinations. For example, with
          pychroot it's now possible to run::
        
            pychroot -B tmpfs:/dev/shm -B tmpfs:/tmp
        
        pychroot 0.9.9 (2015-04-03)
        ---------------------------
        
        - Install chroot(1) workalike as pychroot. This allows users to be lazier when
          doing basic chrooting since pychroot handles mounting and unmounting standard
          bind mounts automatically.
        
Platform: Posix
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
