# phpman > man > COWPOKE(1) [COWPOKE(1)](https://www.chedong.com/phpMan.php/man/COWPOKE/1/markdown) General Commands Manual [COWPOKE(1)](https://www.chedong.com/phpMan.php/man/COWPOKE/1/markdown) ## 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 architec‐ tures may be used to build for all of them in a single pass. Valid arch names are those returned by [**dpkg-architecture**(1)](https://www.chedong.com/phpMan.php/man/dpkg-architecture/1/markdown) for **DEB**___**BUILD**___**ARCH**. **--dist=**_distribution_ Specify the Debian distribution(s) to build for. A space separated list of distribu‐ tions 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. It is now also possible to use locally defined names with this option, when used in conjunction with the **BASE**___**DIST** option in a configuration file. This permits the main‐ tenance and use of specially configured build chroots, which can source package depen‐ dencies from the backports archives or a local repository, or have other unusual con‐ figuration options set, without polluting the chroots you use for clean package builds intended for upload to the main repositories. See the description of **BASE**___**DIST** below. **--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 **cow**‐‐ **builder** root in the expected location. The **--buildd-user** must have permission to create the **RESULT**___**DIR** on the build host, or an admin with the necessary permission must first create it and give that user (or some group they are in) write access to it, for this option to succeed. **--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)](https://www.chedong.com/phpMan.php/man/dpkg-buildpackage/1/markdown). Multiple options are delimited with spaces. This will override any options specified in **DEBBUILDOPTS** in the build host's _pbuilderrc_. **--create-opts=**_'cowbuilder_ _option'_ Specify additional arguments to be passed verbatim to **cowbuilder** when a chroot is first created (using the **--create** option above). If multiple arguments need to be passed, this option should be specified separately for each of them. E.g., **--create-opts** **"--othermirror"** **--create-opts** **"deb** **http://** **..."** This option will override any **CREATE**___**OPTS** specified for a chroot in the cowpoke con‐ figuration files. **--update-opts=**_'cowbuilder_ _option'_ Specify additional arguments to be passed verbatim to **cowbuilder** if the base of the chroot is updated. If multiple arguments need to be passed, this option should be specified separately for each of them. This option will override any **UPDATE**___**OPTS** specified for a chroot in the cowpoke con‐ figuration files. **--build-opts=**_'cowbuilder_ _option'_ Specify additional arguments to be passed verbatim to **cowbuilder** when a package build is performed. If multiple arguments need to be passed, this option should be speci‐ fied separately for each of them. This option will override any **BUILD**___**OPTS** specified for a chroot in the cowpoke config‐ uration files. **--sign=**_keyid_ Specify the key to sign packages with. This will override any **SIGN**___**KEYID** specified for a chroot in the cowpoke configuration files. **--upload=**_queue_ Specify the dput queue to upload signed packages to. This will override any **UP**‐‐ **LOAD**___**QUEUE** specified for a chroot in the cowpoke configuration files. **--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 lat‐ ter 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 distribu‐ tions 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)](https://www.chedong.com/phpMan.php/man/debsign/1/markdown) 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. It may be overridden on an _arch_ and _dist_ specific basis using the _arch_dist__**SIGN**___**KEYID** option described below, or per-invocation with the **--sign** command line option. **UPLOAD**___**QUEUE** If this option is set, it is expected to contain a 'host' specification for [**dput**(1)](https://www.chedong.com/phpMan.php/man/dput/1/markdown) which will be used to upload them after they are signed. You will be prompted to con‐ firm 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. It may be overridden on an _arch_ and _dist_ specific basis using the _arch_dist__**UPLOAD**___**QUEUE** option described below, or per- invocation with the **--upload** command line option. **BUILDD**___**ROOTCMD** The command to use to gain root privileges on the remote build machine. If unset the default is [**sudo**(8)](https://www.chedong.com/phpMan.php/man/sudo/8/markdown). 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 bi‐ nary) will be found, and where older versions of the package that were built previ‐ ously 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)](https://www.chedong.com/phpMan.php/man/lintian/1/markdown) and [**debdiff**(1)](https://www.chedong.com/phpMan.php/man/debdiff/1/markdown), and for upload with [**dput**(1)](https://www.chedong.com/phpMan.php/man/dput/1/markdown). 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_ _arch_dist__**BASE**___**DIST** The code name to pass as the **--distribution** option for cowbuilder instead of _dist_. This is necessary when _dist_ is a locally significant name assigned to some specially configured build chroot, such as 'wheezy_backports', and not the formal suite name of a distro release known to debootstrap. This option cannot be overridden on the com‐ mand line, since it would rarely, if ever, make any sense to change it for individual invocations of **cowpoke**. If this option is not specified for an arch and dist combina‐ tion then it will default to _dist_. _arch_dist__**CREATE**___**OPTS** A bash array containing additional options to pass verbatim to **cowbuilder** when this chroot is created for the first time (using the **--create** option). This is useful when options like **--othermirror** are wanted to create specialised chroot configurations such as 'wheezy_backports'. By default this is unset. All values set in it will be over‐ ridden if the **--create-opts** option is passed on the command line. Each element in this array corresponds to a single argument (in the ARGV sense) that will be passed to cowbuilder. This ensures that arguments which may contain white‐ space or have strange quoting requirements or other special characters will not be mangled before they get to cowbuilder. Bash arrays are initialised using the following form: OPTS=( "arg1" "arg 2" "--option" "value" "--opt=val" "etc. etc." ) _arch_dist__**UPDATE**___**OPTS** A bash array containing additional options to pass verbatim to **cowbuilder** each time the base of this chroot is updated. It behaves similarly to the **CREATE**___**OPTS** option above, except for acting when the chroot is updated. _arch_dist__**BUILD**___**OPTS** A bash array containing additional options to pass verbatim to **cowbuilder** each time a package build is performed in this chroot. This is useful when you want to use some option like **--twice** which cowpoke does not directly need to care about. It otherwise behaves similarly to **UPDATE**___**OPTS** above except that it acts during the build phase of **cowbuilder**. _arch_dist__**SIGN**___**KEYID** An optional arch and dist specific override for the global **SIGN**___**KEYID** option. _arch_dist__**UPLOAD**___**QUEUE** An optional arch and dist specific override for the global **UPLOAD**___**QUEUE** option. ## 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 configura‐ tion 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**` ac‐ cording 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 alterna‐ tively configure **cowpoke** with the path, arch and distribution information and pass the **--cre**‐‐ **ate** option to it on the first invocation). The build host running **cowbuilder** does not re‐ quire **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)](https://www.chedong.com/phpMan.php/man/dput/1/markdown) installed and configured to use the '_host_' alias specified by **UPLOAD**___**QUEUE**. If [**rsync**(1)](https://www.chedong.com/phpMan.php/man/rsync/1/markdown) is available on both the local and build machine, then it will be used to trans‐ fer the source package (this may save on some transfers of the _orig.tar.*_ when building sub‐ sequent 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 _cow__‐ _builder-$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 con‐ tents 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 un‐ committed work. ## SEE ALSO [**cowbuilder**(1)](https://www.chedong.com/phpMan.php/man/cowbuilder/1/markdown), [**pbuilder**(1)](https://www.chedong.com/phpMan.php/man/pbuilder/1/markdown), [**ssh-agent**(1)](https://www.chedong.com/phpMan.php/man/ssh-agent/1/markdown), [**sudoers**(5)](https://www.chedong.com/phpMan.php/man/sudoers/5/markdown) ## AUTHOR **cowpoke** was written by Ron <<_ron@debian.org_>>. April 28, 2008 [COWPOKE(1)](https://www.chedong.com/phpMan.php/man/COWPOKE/1/markdown)