1COWPOKE(1)                  General Commands Manual                 COWPOKE(1)
2
3
4

NAME

6       cowpoke - Build a Debian source package in a remote cowbuilder instance
7

SYNOPSIS

9       cowpoke [options] packagename.dsc
10
11

DESCRIPTION

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
16
17

OPTIONS

19       The following options are available:
20
21
22       --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
28
29       --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
38              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
48
49       --buildd=host
50              Specify the remote host to build on.
51
52
53       --buildd-user=name
54              Specify the remote user to build as.
55
56
57       --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
63              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
68
69       --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
74
75       --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
79
80       --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
86
87       --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
93              E.g., --create-opts "--othermirror" --create-opts  "deb  http://
94              ..."
95
96              This option will override any CREATE_OPTS specified for a chroot
97              in the cowpoke configuration files.
98
99
100       --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
106              This option will override any UPDATE_OPTS specified for a chroot
107              in the cowpoke configuration files.
108
109
110       --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
116              This  option will override any BUILD_OPTS specified for a chroot
117              in the cowpoke configuration files.
118
119
120       --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
125
126       --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
131
132       --help Display a brief summary of the  available  options  and  current
133              configuration.
134
135
136       --version
137              Display the current version information.
138
139
140

CONFIGURATION OPTIONS

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
148
149   Global defaults
150       These apply to every arch and dist in a single cowpoke invocation.
151
152
153       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
158       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
165       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
173       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
179
180       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
185       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
191
192       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
202
203       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
214
215
216       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
225
226                      youruser ALL = NOPASSWD: /usr/sbin/cowbuilder
227
228              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
233
234       DEBOOTSTRAP
235              The utility to use when creating a new build root.  Alternatives
236              are debootstrap or cdebootstrap.
237
238
239       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
246
247
248   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
252
253       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
266
267       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
273
274       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
285
286       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
295              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
301              Bash arrays are initialised using the following form:
302
303                  OPTS=(  "arg1"  "arg 2" "--option" "value" "--opt=val" "etc.
304              etc." )
305
306
307       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
313
314       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
322
323       arch_dist_SIGN_KEYID
324              An optional arch and  dist  specific  override  for  the  global
325              SIGN_KEYID option.
326
327
328       arch_dist_UPLOAD_QUEUE
329              An  optional  arch  and  dist  specific  override for the global
330              UPLOAD_QUEUE option.
331
332
333

CONFIGURATION FILES

335       /etc/cowpoke.conf
336              Global configuration options.  Will override hardcoded defaults.
337
338       ~/.cowpoke
339              Per-user configuration options.  Will override any  global  con‐
340              figuration.
341
342       .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
347              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
352
353

COWBUILDER CONFIGURATION

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
365       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
375       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
382       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
390
391

NOTES

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
403

SEE ALSO

405       cowbuilder(1), pbuilder(1), ssh-agent(1), sudoers(5)
406
407

AUTHOR

409       cowpoke was written by Ron <ron@debian.org>.
410
411
412
413
414                                April 28, 2008                      COWPOKE(1)
Impressum