Provided by: devscripts_2.14.1ubuntu0.1_amd64 
NAME
cowpoke - Build a Debian source package in a remote cowbuilder instance
SYNOPSIS
cowpoke [options] packagename.dsc
DESCRIPTION
Uploads a Debian source package to a cowbuilder host and builds it, optionally also signing and uploading
the result to an incoming queue.
OPTIONS
The following options are available:
--arch=architecture
Specify the Debian architecture(s) to build for. A space separated list of architectures may be
used to build for all of them in a single pass. Valid arch names are those returned by dpkg-
architecture(1) for DEB_BUILD_ARCH.
--dist=distribution
Specify the Debian distribution(s) to build for. A space separated list of distributions may be
used to build for all of them in a single pass. Either codenames (such as sid, or squeeze) or
distribution names (such as unstable, or experimental) may be used, but you should usually stick
to using one or the other consistently as this name may be used in file paths and to locate old
packages for comparison reporting.
--buildd=host
Specify the remote host to build on.
--buildd-user=name
Specify the remote user to build as.
--create
Create the remote cowbuilder root if it does not already exist. If this option is not passed it
is an error for the specified --dist or --arch to not have an existing cowbuilder root in the
expected location.
--return=[path]
Copy results of the build to path. If path is not specified, then return them to the current
directory. The given path must exist, it will not be created.
--no-return
Do not copy results of the build to RETURN_DIR (overriding a path set for it in the configuration
files).
--dpkg-opts='opt1 opt2 ...'
Specify additional options to be passed to dpkg-buildpackage(1). Multiple options are delimited
with spaces. This will override any options specified in DEBBUILDOPTS in the build host's
pbuilderrc.
--help Display a brief summary of the available options and current configuration.
--version
Display the current version information.
CONFIGURATION OPTIONS
When cowpoke is run the following configuration options are read from global, per-user, and per-project
configuration files if present. File paths may be absolute or relative, the latter being relative to the
BUILDD_USER's home directory. Since the paths are typically quoted when used, tilde expansion will not
be performed on them.
Global defaults
These apply to every arch and dist in a single cowpoke invocation.
BUILDD_HOST
The network address or fqdn of the build machine where cowbuilder is configured. This may be
overridden by the --buildd command line option.
BUILDD_USER
The unprivileged user name for operations on the build machine. This defaults to the local name
of the user executing cowpoke (or to a username that is specified in your SSH configuration for
BUILDD_HOST), and may be overridden by the --buildd-user command line option.
BUILDD_ARCH
The Debian architecture(s) to build for. This must match the DEB_BUILD_ARCH of the build chroot
being used. It defaults to the local machine architecture where cowpoke is executed, and may be
overridden by the --arch command line option. A (quoted) space separated list of architectures
may be used here to build for all of them in a single pass.
BUILDD_DIST
The Debian distribution(s) to build for. A (quoted) space separated list of distributions may be
used to build for all of them in a single pass. This may be overridden by the --dist command line
option.
INCOMING_DIR
The directory path on the build machine where the source package will initially be placed. This
must be writable by the BUILDD_USER.
PBUILDER_BASE
The filesystem root for all pbuilder COW and result files. Arch and dist specific subdirectories
will normally be created under this. The apt cache and temporary build directory will also be
located under this path.
SIGN_KEYID
If this option is set, it is expected to contain the gpg key id to pass to debsign(1) if the
packages are to be remotely signed. You will be prompted to confirm whether you wish to sign the
packages after all builds are complete. If this option is unset or an empty string, no attempt to
sign packages will be made.
UPLOAD_QUEUE
If this option is set, it is expected to contain a 'host' specification for dput(1) which will be
used to upload them after they are signed. You will be prompted to confirm whether you wish to
upload the packages after they are signed. If this option is unset or an empty string, no attempt
to upload packages will be made. If SIGN_KEYID is not set, this option will be ignored entirely.
BUILDD_ROOTCMD
The command to use to gain root privileges on the remote build machine. If unset the default is
sudo(8). This is only required to invoke cowbuilder and allow it to enter its chroot, so you may
restrict this user to only being able to run that command with escalated privileges. Something
like this in sudoers will enable invoking cowbuilder without an additional password entry
required:
youruser ALL = NOPASSWD: /usr/sbin/cowbuilder
Alternatively you could use SSH with a forwarded key, or whatever other mechanism suits your local
access policy. Using su -c isn't really suitable here due to its quoting requirements being
somewhat different to the rest.
DEBOOTSTRAP
The utility to use when creating a new build root. Alternatives are debootstrap or cdebootstrap.
RETURN_DIR
If set, package files resulting from the build will be copied to the path (local or remote) that
this is set to, after the build completes. The path must exist, it will not be created. This
option is unset by default and can be overridden with --return or --no-return.
Arch and dist specific options
These are variables of the form: $arch_$dist_VAR which apply only for a particular target arch/dist
build.
arch_dist_RESULT_DIR
The directory path on the build machine where the resulting packages (source and binary) will be
found, and where older versions of the package that were built previously may be found. If any
such older packages exist, debdiff will be used to compare the new package with the previous
version after the build is complete, and the result will be included in the build log. Files in
it must be readable by the BUILDD_USER for sanity checking with lintian(1) and debdiff(1), and for
upload with dput(1). If this option is not specified for some arch and dist combination then it
will default to $PBUILDER_BASE/$arch/$dist/result
arch_dist_BASE_PATH
The directory where the COW master files are to be found (or created if the --create command line
option was passed). If this option is not specified for some arch or dist then it will default to
$PBUILDER_BASE/$arch/$dist/base.cow
CONFIGURATION FILES
/etc/cowpoke.conf
Global configuration options. Will override hardcoded defaults.
~/.cowpoke
Per-user configuration options. Will override any global configuration.
.cowpoke
Per-project configuration options. Will override any per-user or global configuration if cowpoke
is called from the directory where they exist.
If the environment variable COWPOKE_CONF is set, it specifies an additional configuration file
which will override all of those above. Options specified explicitly on the command line override
all configuration files.
COWBUILDER CONFIGURATION
There is nothing particularly special required to configure a cowbuilder instance for use with cowpoke.
Simply create them in the flavour you require with `cowbuilder --create` according to the cowbuilder
documentation, then configure cowpoke with the user, arch, and path information required to access it, on
the machines you wish to invoke it from (or alternatively configure cowpoke with the path, arch and
distribution information and pass the --create option to it on the first invocation). The build host
running cowbuilder does not require cowpoke installed locally.
The build machine should have the lintian and devscripts packages installed for post-build sanity
checking. Upon completion, the build log and the results of automated checks will be recorded in the
INCOMING_DIR. If you wish to upload signed packages the build machine will also need dput(1) installed
and configured to use the 'host' alias specified by UPLOAD_QUEUE. If rsync(1) is available on both the
local and build machine, then it will be used to transfer the source package (this may save on some
transfers of the orig.tar.* when building subsequent Debian revisions).
The user executing cowpoke must have SSH access to the build machine as the BUILDD_USER. That user must
be able to invoke cowbuilder as root by using the BUILDD_ROOTCMD. Signing keys are not required to be
installed on the build machine (and will be ignored there if they are). If the package is signed, keys
will be expected on the machine that executes cowpoke.
When cowpoke is invoked, it will first attempt to update the cowbuilder image if that has not already
been done on the same day. This is checked by the presence or absence of a cowbuilder-$arch-$dist-
update-log-$date file in the INCOMING_DIR. You may move, remove, or touch this file if you wish the
image to be updated more or less often than that. Its contents log the output of cowbuilder during the
update (or creation) of the build root.
NOTES
Since cowbuilder creates a chroot, and to do that you need root, cowpoke also requires some degree of
root access. So all the horrible things that can go wrong with that may well one day rain down upon you.
cowbuilder has been known to accidentally wipe out bind-mounted filesystems outside the chroot, and worse
than that can easily happen. So be careful, keep good backups of things you don't want to lose on your
build machine, and use cowpoke to keep all that on a machine that isn't your bleeding edge dev box with
your last few hours of uncommitted work.
SEE ALSO
cowbuilder(1), pbuilder(1), ssh-agent(1), sudoers(5)
AUTHOR
cowpoke was written by Ron <ron@debian.org>.
April 28, 2008 COWPOKE(1)