1COWPOKE(1) General Commands Manual COWPOKE(1)
2
6 cowpoke - Build a Debian source package in a remote cowbuilder instance
7
9 cowpoke [options] packagename.dsc
10
13 Uploads a Debian source package to a cowbuilder host and builds it,
14 optionally also signing and uploading the result to an incoming queue.
15
19 The following options are available:
20 --arch=architecture
23 Specify the Debian architecture(s) to build for. A space sepa‐
24 rated list of architectures may be used to build for all of them
25 in a single pass. Valid arch names are those returned by dpkg-
26 architecture(1) for DEB_BUILD_ARCH.
27 --dist=distribution
30 Specify the Debian distribution(s) to build for. A space sepa‐
31 rated list of distributions may be used to build for all of them
32 in a single pass. Either codenames (such as sid, or squeeze) or
33 distribution names (such as unstable, or experimental) may be
34 used, but you should usually stick to using one or the other
35 consistently as this name may be used in file paths and to
36 locate old packages for comparison reporting.
37 It is now also possible to use locally defined names with this
39 option, when used in conjunction with the BASE_DIST option in a
40 configuration file. This permits the maintenance and use of
41 specially configured build chroots, which can source package
42 dependencies from the backports archives or a local repository,
43 or have other unusual configuration options set, without pollut‐
44 ing the chroots you use for clean package builds intended for
45 upload to the main repositories. See the description of
46 BASE_DIST below.
47 --buildd=host
50 Specify the remote host to build on.
51 --buildd-user=name
54 Specify the remote user to build as.
55 --create
58 Create the remote cowbuilder root if it does not already exist.
59 If this option is not passed it is an error for the specified
60 --dist or --arch to not have an existing cowbuilder root in the
61 expected location.
62 The --buildd-user must have permission to create the RESULT_DIR
64 on the build host, or an admin with the necessary permission
65 must first create it and give that user (or some group they are
66 in) write access to it, for this option to succeed.
67 --return=[path]
70 Copy results of the build to path. If path is not specified,
71 then return them to the current directory. The given path must
72 exist, it will not be created.
73 --no-return
76 Do not copy results of the build to RETURN_DIR (overriding a
77 path set for it in the configuration files).
78 --dpkg-opts='opt1 opt2 ...'
81 Specify additional options to be passed to dpkg-buildpackage(1).
82 Multiple options are delimited with spaces. This will override
83 any options specified in DEBBUILDOPTS in the build host's
84 pbuilderrc.
85 --create-opts='cowbuilder option'
88 Specify additional arguments to be passed verbatim to cowbuilder
89 when a chroot is first created (using the --create option
90 above). If multiple arguments need to be passed, this option
91 should be specified separately for each of them.
92 E.g., --create-opts "--othermirror" --create-opts "deb http://
94 ..."
95 This option will override any CREATE_OPTS specified for a chroot
97 in the cowpoke configuration files.
98 --update-opts='cowbuilder option'
101 Specify additional arguments to be passed verbatim to cowbuilder
102 if the base of the chroot is updated. If multiple arguments
103 need to be passed, this option should be specified separately
104 for each of them.
105 This option will override any UPDATE_OPTS specified for a chroot
107 in the cowpoke configuration files.
108 --build-opts='cowbuilder option'
111 Specify additional arguments to be passed verbatim to cowbuilder
112 when a package build is performed. If multiple arguments need
113 to be passed, this option should be specified separately for
114 each of them.
115 This option will override any BUILD_OPTS specified for a chroot
117 in the cowpoke configuration files.
118 --sign=keyid
121 Specify the key to sign packages with. This will override any
122 SIGN_KEYID specified for a chroot in the cowpoke configuration
123 files.
124 --upload=queue
127 Specify the dput queue to upload signed packages to. This will
128 override any UPLOAD_QUEUE specified for a chroot in the cowpoke
129 configuration files.
130 --help Display a brief summary of the available options and current
133 configuration.
134 --version
137 Display the current version information.
138
142 When cowpoke is run the following configuration options are read from
143 global, per-user, and per-project configuration files if present. File
144 paths may be absolute or relative, the latter being relative to the
145 BUILDD_USER's home directory. Since the paths are typically quoted
146 when used, tilde expansion will not be performed on them.
147 Global defaults
150 These apply to every arch and dist in a single cowpoke invocation.
151 BUILDD_HOST
154 The network address or fqdn of the build machine where cow‐
155 builder is configured. This may be overridden by the --buildd
156 command line option.
157 BUILDD_USER
159 The unprivileged user name for operations on the build machine.
160 This defaults to the local name of the user executing cowpoke
161 (or to a username that is specified in your SSH configuration
162 for BUILDD_HOST), and may be overridden by the --buildd-user
163 command line option.
164 BUILDD_ARCH
166 The Debian architecture(s) to build for. This must match the
167 DEB_BUILD_ARCH of the build chroot being used. It defaults to
168 the local machine architecture where cowpoke is executed, and
169 may be overridden by the --arch command line option. A (quoted)
170 space separated list of architectures may be used here to build
171 for all of them in a single pass.
172 BUILDD_DIST
174 The Debian distribution(s) to build for. A (quoted) space sepa‐
175 rated list of distributions may be used to build for all of them
176 in a single pass. This may be overridden by the --dist command
177 line option.
178 INCOMING_DIR
181 The directory path on the build machine where the source package
182 will initially be placed. This must be writable by the
183 BUILDD_USER.
184 PBUILDER_BASE
186 The filesystem root for all pbuilder CoW and result files. Arch
187 and dist specific subdirectories will normally be created under
188 this. The apt cache and temporary build directory will also be
189 located under this path.
190 SIGN_KEYID
193 If this option is set, it is expected to contain the gpg key ID
194 to pass to debsign(1) if the packages are to be remotely signed.
195 You will be prompted to confirm whether you wish to sign the
196 packages after all builds are complete. If this option is unset
197 or an empty string, no attempt to sign packages will be made.
198 It may be overridden on an arch and dist specific basis using
199 the arch_dist_SIGN_KEYID option described below, or per-invoca‐
200 tion with the --sign command line option.
201 UPLOAD_QUEUE
204 If this option is set, it is expected to contain a 'host' speci‐
205 fication for dput(1) which will be used to upload them after
206 they are signed. You will be prompted to confirm whether you
207 wish to upload the packages after they are signed. If this
208 option is unset or an empty string, no attempt to upload pack‐
209 ages will be made. If SIGN_KEYID is not set, this option will
210 be ignored entirely. It may be overridden on an arch and dist
211 specific basis using the arch_dist_UPLOAD_QUEUE option described
212 below, or per-invocation with the --upload command line option.
213 BUILDD_ROOTCMD
217 The command to use to gain root privileges on the remote build
218 machine. If unset the default is sudo(8). This is only
219 required to invoke cowbuilder and allow it to enter its chroot,
220 so you may restrict this user to only being able to run that
221 command with escalated privileges. Something like this in sudo‐
222 ers will enable invoking cowbuilder without an additional pass‐
223 word entry required:
224 youruser ALL = NOPASSWD: /usr/sbin/cowbuilder
227 Alternatively you could use SSH with a forwarded key, or what‐
229 ever other mechanism suits your local access policy. Using su
230 -c isn't really suitable here due to its quoting requirements
231 being somewhat different to the rest.
232 DEBOOTSTRAP
235 The utility to use when creating a new build root. Alternatives
236 are debootstrap or cdebootstrap.
237 RETURN_DIR
240 If set, package files resulting from the build will be copied to
241 the path (local or remote) that this is set to, after the build
242 completes. The path must exist, it will not be created. This
243 option is unset by default and can be overridden with --return
244 or --no-return.
245 Arch and dist specific options
249 These are variables of the form: $arch_$dist_VAR which apply only for a
250 particular target arch/dist build.
251 arch_dist_RESULT_DIR
254 The directory path on the build machine where the resulting
255 packages (source and binary) will be found, and where older ver‐
256 sions of the package that were built previously may be found.
257 If any such older packages exist, debdiff will be used to com‐
258 pare the new package with the previous version after the build
259 is complete, and the result will be included in the build log.
260 Files in it must be readable by the BUILDD_USER for sanity
261 checking with lintian(1) and debdiff(1), and for upload with
262 dput(1). If this option is not specified for some arch and dist
263 combination then it will default to
264 $PBUILDER_BASE/$arch/$dist/result
265 arch_dist_BASE_PATH
268 The directory where the CoW master files are to be found (or
269 created if the --create command line option was passed). If
270 this option is not specified for some arch or dist then it will
271 default to $PBUILDER_BASE/$arch/$dist/base.cow
272 arch_dist_BASE_DIST
275 The code name to pass as the --distribution option for cow‐
276 builder instead of dist. This is necessary when dist is a
277 locally significant name assigned to some specially configured
278 build chroot, such as 'wheezy_backports', and not the formal
279 suite name of a distro release known to debootstrap. This
280 option cannot be overridden on the command line, since it would
281 rarely, if ever, make any sense to change it for individual
282 invocations of cowpoke. If this option is not specified for an
283 arch and dist combination then it will default to dist.
284 arch_dist_CREATE_OPTS
287 A bash array containing additional options to pass verbatim to
288 cowbuilder when this chroot is created for the first time (using
289 the --create option). This is useful when options like --other‐
290 mirror are wanted to create specialised chroot configurations
291 such as 'wheezy_backports'. By default this is unset. All val‐
292 ues set in it will be overridden if the --create-opts option is
293 passed on the command line.
294 Each element in this array corresponds to a single argument (in
296 the ARGV sense) that will be passed to cowbuilder. This ensures
297 that arguments which may contain whitespace or have strange
298 quoting requirements or other special characters will not be
299 mangled before they get to cowbuilder.
300 Bash arrays are initialised using the following form:
302 OPTS=( "arg1" "arg 2" "--option" "value" "--opt=val" "etc.
304 etc." )
305 arch_dist_UPDATE_OPTS
308 A bash array containing additional options to pass verbatim to
309 cowbuilder each time the base of this chroot is updated. It
310 behaves similarly to the CREATE_OPTS option above, except for
311 acting when the chroot is updated.
312 arch_dist_BUILD_OPTS
315 A bash array containing additional options to pass verbatim to
316 cowbuilder each time a package build is performed in this
317 chroot. This is useful when you want to use some option like
318 --twice which cowpoke does not directly need to care about. It
319 otherwise behaves similarly to UPDATE_OPTS above except that it
320 acts during the build phase of cowbuilder.
321 arch_dist_SIGN_KEYID
324 An optional arch and dist specific override for the global
325 SIGN_KEYID option.
326 arch_dist_UPLOAD_QUEUE
329 An optional arch and dist specific override for the global
330 UPLOAD_QUEUE option.
331
335 /etc/cowpoke.conf
336 Global configuration options. Will override hardcoded defaults.
337 ~/.cowpoke
339 Per-user configuration options. Will override any global con‐
340 figuration.
341 .cowpoke
343 Per-project configuration options. Will override any per-user
344 or global configuration if cowpoke is called from the directory
345 where they exist.
346 If the environment variable COWPOKE_CONF is set, it specifies an
348 additional configuration file which will override all of those
349 above. Options specified explicitly on the command line over‐
350 ride all configuration files.
351
355 There is nothing particularly special required to configure a cow‐
356 builder instance for use with cowpoke. Simply create them in the
357 flavour you require with `cowbuilder --create` according to the cow‐
358 builder documentation, then configure cowpoke with the user, arch, and
359 path information required to access it, on the machines you wish to
360 invoke it from (or alternatively configure cowpoke with the path, arch
361 and distribution information and pass the --create option to it on the
362 first invocation). The build host running cowbuilder does not require
363 cowpoke installed locally.
364 The build machine should have the lintian and devscripts packages
366 installed for post-build sanity checking. Upon completion, the build
367 log and the results of automated checks will be recorded in the INCOM‐
368 ING_DIR. If you wish to upload signed packages the build machine will
369 also need dput(1) installed and configured to use the 'host' alias
370 specified by UPLOAD_QUEUE. If rsync(1) is available on both the local
371 and build machine, then it will be used to transfer the source package
372 (this may save on some transfers of the orig.tar.* when building subse‐
373 quent Debian revisions).
374 The user executing cowpoke must have SSH access to the build machine as
376 the BUILDD_USER. That user must be able to invoke cowbuilder as root
377 by using the BUILDD_ROOTCMD. Signing keys are not required to be
378 installed on the build machine (and will be ignored there if they are).
379 If the package is signed, keys will be expected on the machine that
380 executes cowpoke.
381 When cowpoke is invoked, it will first attempt to update the cowbuilder
383 image if that has not already been done on the same day. This is
384 checked by the presence or absence of a cowbuilder-$arch-$dist-update-
385 log-$date file in the INCOMING_DIR. You may move, remove, or touch
386 this file if you wish the image to be updated more or less often than
387 that. Its contents log the output of cowbuilder during the update (or
388 creation) of the build root.
389
393 Since cowbuilder creates a chroot, and to do that you need root, cow‐
394 poke also requires some degree of root access. So all the horrible
395 things that can go wrong with that may well one day rain down upon you.
396 cowbuilder has been known to accidentally wipe out bind-mounted
397 filesystems outside the chroot, and worse than that can easily happen.
398 So be careful, keep good backups of things you don't want to lose on
399 your build machine, and use cowpoke to keep all that on a machine that
400 isn't your bleeding edge dev box with your last few hours of uncommit‐
401 ted work.
402
405 cowbuilder(1), pbuilder(1), ssh-agent(1), sudoers(5)
406
409 cowpoke was written by Ron <ron@debian.org>.
410 April 28, 2008 COWPOKE(1)