COWPOKE(1)

💖 COWPOKE(1) 💖

General Commands Manual · COWPOKE(1)

okay bestie sit DOWN because we're about to talk about cowpoke, and she is that girl. no cap.

---

✨ NAME ✨

cowpoke — build a Debian source package in a remote cowbuilder instance 🐄🫶

---

🌸 SYNOPSIS 🌸

cowpoke [options] packagename.dsc

---

🦋 DESCRIPTION 🦋

So what she does is: she uploads a Debian source package to a cowbuilder host and builds it there. and then, if you want, she'll also sign the result and upload it to an incoming queue. lowkey iconic. it's giving "I do your builds so you don't have to." 💅

---

👑 OPTIONS 👑

the following options are available, and yes we're going through every single one, because we respect her:

• --arch=architecture — specify the Debian architecture(s) to build for. you can pass a space separated list of architectures and she'll build for all of them in a single pass, slay. valid arch names are whatever dpkg-architecture(1) returns for DEB_BUILD_ARCH.
• --dist=distribution — specify the Debian distribution(s) to build for. space separated list works here too, builds for all of them in one pass ✨. you can use either codenames (like sid, or squeeze) or distribution names (like unstable, or experimental), but fr fr you should usually just pick one style and stick with it consistently, because this name might get used in file paths and to locate old packages for comparison reporting.

okay and here's the tea: you can now also use locally defined names with this option when you use it together with the BASE_DIST option in a configuration file. this lets you keep and use specially configured build chroots — ones that can source package dependencies from the backports archives or a local repository, or that have other unusual configuration options set — without polluting the chroots you use for clean package builds meant 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 doesn't already exist. if you don't pass this option, it's an error for the specified --dist or --arch to not have an existing cowbuilder root in the expected location. 😭

heads up bestie: for this option to succeed, the --buildd-user must have permission to create the RESULT_DIR on the build host. or an admin with the necessary permission has to create it first and give that user (or some group they're in) write access to it. no permission, no chroot. periodt.

• --return=[path] — copy results of the build to path. if path isn't specified, she returns them to the current directory. and important: the given path must exist, she will not create it. 🙈
• --no-return — do not copy results of the build to RETURN_DIR. this overrides 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. 🔥
• --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 you need to pass multiple arguments, specify this option separately for each one.

E.g.:

--create-opts "--othermirror" --create-opts "deb http://..."

this option will override any CREATE_OPTS specified for a chroot in the cowpoke configuration files.

• --update-opts='cowbuilder option' — specify additional arguments to be passed verbatim to cowbuilder if the base of the chroot is updated. multiple arguments? same deal, specify this option separately for each of them.

this option will override any UPDATE_OPTS specified for a chroot in the cowpoke configuration files.

• --build-opts='cowbuilder option' — specify additional arguments to be passed verbatim to cowbuilder when a package build is performed. again, multiple arguments means specifying this option separately for each one.

this option will override any BUILD_OPTS specified for a chroot in the cowpoke configuration 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 UPLOAD_QUEUE specified for a chroot in the cowpoke configuration files.
• --help — display a brief summary of the available options and current configuration. (bestie behaviour honestly 🫶)
• --version — display the current version information. ⭐

---

…and that's where part 1 ends, don't go anywhere, there's more coming 🌈

🌸 CONFIGURATION OPTIONS 🌸

okay bestie so here's the tea: when cowpoke runs, it goes looking for these config options in your global, per-user, and per-project config files (if they exist). File paths can be absolute or relative — and if they're relative, they're relative to the BUILDD_USER's home directory. And because these paths are usually quoted when you use them, tilde expansion will not happen on them. sad but true. 💅

---

🎀 Global defaults 🎀

these apply to every arch and dist in a single cowpoke invocation. one run, all the vibes.

• BUILDD_HOST — the network address or fqdn of the build machine where cowbuilder is configured. you can override this with the --buildd command line option.
• BUILDD_USER — the unprivileged user name for operations on the build machine. it defaults to the local name of the user executing cowpoke (or to a username that's specified in your SSH configuration for BUILDD_HOST), and you can override it with 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. defaults to the local machine architecture where cowpoke is executed, and can be overridden with the --arch command line option. you can throw a (quoted) space separated list of architectures here to build for all of them in a single pass. efficiency queen. 👑
• BUILDD_DIST — the Debian distribution(s) to build for. a (quoted) space separated list of distributions works here too, building all of them in one pass. overridable with 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 also live under this path.
• SIGN_KEYID — if this is set, it's expected to contain the OpenPGP key ID to pass to debsign(1) if the packages are to be remotely signed. you'll be prompted to confirm whether you want 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, periodt. it can 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 is set, it's expected to contain a 'host' specification for dput(1) which will be used to upload them after they're signed. you'll be prompted to confirm whether you want to upload the packages after they're signed. if this option is unset or an empty string, no attempt to upload packages will be made. and heads up: if SIGN_KEYID is not set, this option will be ignored entirely. it can 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). 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. so like, very specific. very targeted. main character of one build only. ✨

• 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.
• 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 command 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 combination 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 overridden 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 whitespace 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 🌈

here's where cowpoke goes looking for all of the above, in order:

• /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. and options specified explicitly on the command line override all configuration files. the hierarchy is real and it's giving strict. 💖

🐄 COWBUILDER CONFIGURATION 🐄

Okay bestie, here's the tea: there is literally nothing special you gotta do to set up a cowbuilder instance for cowpoke. Like, none. Zero. Nada. ✨

• Just make them in whatever flavour you need with cowbuilder --create, following the cowbuilder documentation like a good little devotee.
• Then configure cowpoke with the user, arch, and path info it needs to reach that instance — on the machines you wanna invoke it from.
• OR, plot twist 🎀: configure cowpoke with the path, arch, and distribution info instead, and just pass the --create option on the very first invocation.

And here's the cute part: the build host running cowbuilder does not need cowpoke installed locally. It's giving independent queen energy. 👑

---

The build machine should have the lintian and devscripts packages installed so you get that post-build sanity checking. Because we love a vibe check. 🧚 When it's all done, the build log and the results of the automated checks get recorded in the INCOMING_DIR.

Wanna upload signed packages? Then the build machine also needs dput(1) installed, configured to use the 'host' alias that UPLOAD_QUEUE specifies. Slay. 💅

And if rsync(1) is available on both the local and build machine, it'll be used to transfer the source package. Lowkey a lifesaver — it can save on some transfers of the orig.tar.* when you're building subsequent Debian revisions. Obsessed. 🌸

---

The user executing cowpoke must have SSH access to the build machine as the BUILDD_USER. And that user must be able to invoke cowbuilder as root by using the BUILDD_ROOTCMD. Root access, bestie, we love a main character with power. 👑

Signing keys? Not required on the build machine — and they'll be ignored there if they are present, sorry not sorry. 🙈 But if the package is signed, keys will be expected on the machine that executes cowpoke. That's the rule, periodt.

---

When cowpoke gets invoked, first thing it does is try to update the cowbuilder image — but only if that hasn't already been done on the same day. 🗓️

How does it know? By the presence or absence of a cowbuilder-$arch-$dist-update-log-$date file in the INCOMING_DIR. It's literally just vibes and file names.

You may move, remove, or touch this file if you want the image updated more or less often than that. Your file, your rules. ✨ And its contents? They log the output of cowbuilder during the update (or creation) of the build root.

---

⚠️ NOTES ⚠️

Okay so, real talk, not to be dramatic but: since cowbuilder creates a chroot, and to do that you need root, cowpoke also requires some degree of root access. Which means 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.

Fr fr, protect your uncommitted work. It's giving fragile. 💀

---

👀 SEE ALSO 👀

• cowbuilder(1)
• pbuilder(1)
• ssh-agent(1)
• sudoers(5)

---

💖 AUTHOR 💖

cowpoke was written by Ron <ron@debian.org>.

---

And that's the whole page, bestie!! 🎀 This was COWPOKE(1), dated April 28, 2008 — go forth and build your packages, and remember: back up your stuff first. 💅✨