dwight is a utility for managing and deploying chrooted environments with external dependencies. dwight reads a configuration file that specifies how to establish the environment, and then allows you to run commands and interact with the environment.
Chrooted environments are constructed from a base image (currently only squashfs images are supported). External dependencies can then be added on to specified paths at construction time (these paths must exist in the base image as empty directories, as this is done via mount).
dwight can be installed via pip:
pip install dwight-chroot
To run dwight you'll need a configuration file. A configuration file should at least contain the location of the base image. Here is a minimal configuration file:
ROOT_IMAGE = "/path/to/image.squashfs"
Now just run:
dwight -c /path/to/config_file.py shell
This will drop you into a shell in your chrooted environment.
Dwight receives its configuration from files specified with the -c flag. Multiple files can be specified for this option.
Dwight configuration files are simple Python files that contain settings in the form of underscore-separated uppercase strings (like THIS_ONE). variables not matching that criterion will be silently ignored (enabling you to use them for temporary variables etc.).
When Dwight loads configuration, it first looks for ~/.dwightrc and loads it. If it doesn't exist an empty one will be created. Afterwards each configuration file from command line is loaded in turn, and the end result is the aggregation of all the config files.
PLEASE NOTE that when a configuration file is processed it has access to the parameters set by previous configuration files, so it can choose whether to override them or extend them. This is important, for instance, when using the INCLUDES option -- assigning to it will drop previous entries, so prefer using the += operator instead.
The path to the root image for the chroot. This can also be a URL to an image file over http.
To bind paths or resources to your chroot environment, use the INCLUDES varaible in your configuration file:
INCLUDES += [
Include("/path/in/chroot", "/local/path"),
]
INCLUDES is a list of Include declarations. Each has a first argument which is the destination inside the chroot, and a second argument which is the resource to be Includeed.
Severl types of resources can be included, as describe below.
Local paths get included as bind-mounts. If the path specified is a relative path, it is taken relative to the current working directory (useful for home dir mounting, for example)
Git and Mercurial repositories can be included. They are designated by using resource paths starting with git://, ssh+git://, http+hg:// or https+hg://. They also take additional optional parameters, for example:
Include("/path", "git://server/git/repository", branch="development") # cloning a specific branch
Include("/path", "git://server/git/repository", tag="rc1") # clone a specific tag
Include("/path", "git://server/git/repository", commit="4ff7a0565964eb428e5b45479922f164a5ee941b") # specific commit
You can include whole images saved as squashfs files. This can be done from a local path:
Include("/mount", "/path/to/image.squashfs")
Or from http/https:
Include("/mount", "http://server/files/image.squashfs")
You can control the environment variables set up by dwight using the ENVIRON variable in your configuration file:
ENVIRON = {
"PATH" : "$PATH:another/extra/path/here"
}
The working directory for the command to run. By default this is the working directory in which dwight was run.
You can control the uid/gids of the chrooted command.
If the uid value is an integer, it will be used as the user to execute commands.
If the uid is None, Dwight will attempt to fetch the uid from the SUDO_UID environment variable. If the variable does not exist, the command will run as root
The variable GIDS holds a list of group ids used when executing commands
If the value is None, Dwight will fetch the list of group id's belonging to the user invoking dwight, using SUDO_UID to determine the current user or using uid 0 if SUDO_UID does not exist
This optional variable controls the amount of loop devices to ensure before chrooting. If it is set, and no hard limit is configured for number of loop devices, dwight will ensure this number of loop devices exists in /dev.
The maximum size, in bytes, that the cache directory can occupy. Note that the total size of the cache directory may still exceed this value some times, like in cases where all the space is needed for current includes.
- Currently including a single git/hg repository multiple times with different commits/branches/tags will cause separate copies of the repository in the cache
The tests included in dwight are intended to be run in a dedicated environment set up by vagrant. To get started, install vagrant, and then run vagrant up from the project directory to start the environment.
To run the tests, ssh into the client vm and run via nosetests like so:
$ vagrant ssh client
vagrant@client:~$ sudo nosetests -w src/tests
Special credit and thanks go to Yotam Rubin, who came up with the idea and drove this project forward.
Dwight is distributed under the BSD 3-clause license. (See LICENSE)