---
name: "cowbuilder"
section: "8"
platform: "linux"
package: "cowbuilder"
version: "0.90"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/cowbuilder"
---

# cowbuilder(8)

a pbuilder wrapper for cowdancer.

## NAME

cowbuilder - a pbuilder wrapper for cowdancer.

## SYNOPSIS

**cowbuilder create \[***options***\]**

**cowbuilder update \[***options***\]**

**cowbuilder build \[***options***\]** *.dsc-file*

**cowbuilder login \[***options***\]**

**cowbuilder execute \[***options***\] --** *script \[***script options***\]*

**cowbuilder dumpconfig**

## 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**, **up**, **u**

  Update the base.cow image.

- **build**, **b**

  Build a package given a .dsc file

- **login**, **l**

  Start a session within the base.cow.

- **execute**, **e**

  Execute a command within the base.cow.

- **dumpconfig**

  Dump configuration information, used for debugging.

## 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**

  This has a very different meaning to the **--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**

  Workaround for Debian Etch. cow-shell will search for all files in the 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
  I: Running in no-targz mode
  Distribution is etch.
  Building the build environment
  I: 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
  I: Copying COW directory
  I: Invoking pbuilder
  W: /home/dancer/.pbuilderrc does not exist
  I: Running in no-targz mode
  I: copying local configuration
  I: mounting /proc filesystem
  I: mounting /dev/pts filesystem
  I: policy-rc.d already exists
  Refreshing the base.tgz
  I: 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
  I: Copying COW directory
  I: Invoking pbuilder
  W: /home/dancer/.pbuilderrc does not exist
  I: Running in no-targz mode
  I: copying local configuration
  I: mounting /proc filesystem
  I: mounting /dev/pts filesystem
  I: Mounting /home/dancer
  I: policy-rc.d already exists
  I: 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)](/pbuilder/8.md),  [**pdebuild**(1)](/pdebuild/1.md)