cow-shell(1) [debian man page]
cow-shell(1) cowdancer cow-shell(1) NAME
cow-shell - Start a copy-on-write session and invoke a shell. SYNOPSIS
cow-shell [commandline] DESCRIPTION
cow-shell Executes specified command with cowdancer or a shell if no command-line option is given. Inside the cowdancer session, files under the current directory are protected in a way so that a write operation to an i-node which existed at the point of running cow-shell is not modified. Useful for managing hard-linked source-trees and scratch-filesystems. EXAMPLES
cp -al cowdancer/ cowdancer.new && cd cowdancer.new && cow-shell Create a hardlinked tree, and cd into the newly created tree. After invoking cow-shell inside that tree, a write operation against a file that is hardlinked with the original tree will be copied to a new file before write. cp -al cowdancer/ cowdancer.new && cd cowdancer.new && cow-shell debuild Tries to run dpkg-buildpackage on the new tree, to avoid damage to the original tree. Configure debuild to ignore .ilist files, through -i or -I option. FILES
.ilist Generated dynamically in the current directory. The file contains the list of i-node numbers that should be protected from write operation. /usr/lib/cowdancer/libcowdancer.so The shared library used internally that overrides some functions that potentially write to files. This library implements the COW feature and is preloaded with LD_PRELOAD. /bin/cp Used for copying. Requires GNU option -a to be functional. ENVIRONMENT
COWDANCER_ILISTFILE The path to the current .ilist file. COWDANCER_IGNORE Used internally to work around infinite loops. It will be unset. LD_PRELOAD Utilized to preload libcowdancer.so COWDANCER_DEBUG Debugging option. Enables debug messages. cowdancer will give verbose debug messages in standard error output. COWDANCER_SO Debugging option. Specifies a different path for libcowdancer.so. COWDANCER_REUSE=yes Enables reuse of cowdancer .ilist file found for consecutive runs of cow-shell. RETURN VALUE
The functions that are overridden with cowdancer will give an errno value of ENOMEM when there is a problem. System isn't really out of memory, but this error code is chosen because this error is usually handled gracefully by applications. RESTRICTIONS
Can only support directories that are scanned by cow-shell command. The operation is not semantically correct when files are originally hardlinked, hardlinks are always broken. Does not support anything when LD_PRELOAD trick does not work. Does not work unless hardlinks are supported on the filesystem. Not very user-friendly. Leaves .ilist file around. AUTHOR
Junichi Uekawa (dancer@debian.org) Upstream page is available at http://www.netfort.gr.jp/~dancer/software/cowdancer.html SEE ALSO
cowdancer-ilistcreate (1) cowdancer 2006 Jan 25 cow-shell(1)
Check Out this Related Man Page
cowbuilder(8) cowdancer cowbuilder(8) NAME
cowbuilder - a pbuilder wrapper for cowdancer. SYNOPSIS
cowbuilder [commands] [options] DESCRIPTION
cowbuilder Executes the specified pbuilder operation with cowdancer COMMANDS
Most commands invoke pbuilder with the specified commands, see pbuilder manual for details. --create Create the base.cow image. The directory for base.cow should be empty, or this command will fail. --update Update the base.cow image. --build .dsc-file Build a package given a .dsc file --login Start a session within the base.cow. --execute Execute a command within the base.cow. --dumpconfig dump configuration information. OPTIONS
Most options are the same as pbuilder, except for the following which are handled specially --buildplace The place where COW operation takes place. --basepath has a very different meaning to basetgz option of pbuilder, since there is no tgz. This option specifies the directory in which the COW master data is stored, the default being /var/cache/pbuilder/base.cow --configfile [configuration file to load] Additional configuration file to read after all other configuration files have been read. --no-cowdancer-update Do not use cowdancer on cowbuilder --update. Please use this option when cowdancer is interfering with upgrade process, or cowdancer itself is being upgraded within chroot. --debian-etch-workaround Work around on Debian etch compatibility. cow-shell will search for all files in chroot, but will work. CONFIGURATION FILES
cowbuilder reads the following configuration files per default. /usr/share/pbuilder/pbuilderrc Application default, not to be changed. /etc/pbuilderrc System-wide default. ~/.pbuilderrc User default anything specified with --configfile option Additional configuration at runtime. CONFIGURATION FILE OPTIONS
The possible configuration options are as follows. Others are ignored. DISTRIBUTION=distribution BUILDRESULT=directory BUILDPLACE=directory BASEPATH=path MIRRORSITE=http://mirror NO_COWDANCER_UPDATE=1 See --no-cowdancer-update DEBIAN_ETCH_WORKAROUND=1 See --debian-etch-workaround EXAMPLES
cowbuilder --create Create a base.cow image. # cowbuilder --create --hookdir /usr/share/doc/pbuilder/examples/workaround/ --distribution etch --debootstrap debootstrap --basepath /var/cache/pbuilder/base-test.cow bash: /root/.pbuilderrc: No such file or directory W: /home/dancer/.pbuilderrc does not exist -> Running in no-targz mode Distribution is etch. Building the build environment -> running debootstrap /usr/sbin/debootstrap I: Retrieving Release . . cowbuilder --update Update the base.cow image. # cowbuilder --update bash: /root/.pbuilderrc: No such file or directory -> Copying COW directory -> Invoking pbuilder W: /home/dancer/.pbuilderrc does not exist -> Running in no-targz mode -> copying local configuration -> mounting /proc filesystem -> mounting /dev/pts filesystem -> policy-rc.d already exists Refreshing the base.tgz -> upgrading packages . . cowbuilder --build test_0.1.dsc Build the package specified in dsc file, with the base.cow image. pdebuild --pbuilder cowbuilder Run cowbuilder --build against the current directory. The current directory should be an extracted Debian source package directory. Edit /etc/pbuilderrc to have PDEBUILD_PBUILDER=cowbuilder to make this the default behavior for pdebuild. cowbuilder --login --bindmounts /home/dancer Start a cow-shell session inside base.cow, with /home/dancer being bind-mounted to within chroot. Note that cowbuilder will not cow-protect what is inside /home/ # cowbuilder --login --bindmount ${HOME} bash: /root/.pbuilderrc: No such file or directory -> Copying COW directory -> Invoking pbuilder W: /home/dancer/.pbuilderrc does not exist -> Running in no-targz mode -> copying local configuration -> mounting /proc filesystem -> mounting /dev/pts filesystem -> Mounting /home/dancer -> policy-rc.d already exists -> entering the shell # cowbuilder --create --distribution sid --basepath /var/cache/pbuilder/base-test.cow Create a base.cow image with the path /var/cache/pbuilder/base-test.cow and distribution sid. AUTHOR
Junichi Uekawa (dancer@debian.org) SEE ALSO
/usr/share/doc/pbuilder/pbuilder-doc.html, pbuilder (8), pdebuild (1) cowdancer 2007 Jun 17 cowbuilder(8)