cowpoke


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  sepa-
              rated 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 sepa-
              rated 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
              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 cow-
              builder 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 sepa-
              rated 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

       UPLOAD_QUEUE
              If this option is set, it is expected to contain a 'host' speci-
              fication  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  pack-
              ages  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 sudo-
              ers  will enable invoking cowbuilder without an additional pass-
              word entry required:


                      youruser ALL = NOPASSWD: /usr/sbin/cowbuilder

              Alternatively you could use SSH with a forwarded key,  or  what-
              ever  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 ver-
              sions  of  the  package that were built previously may be found.
              If any such older packages exist, debdiff will be used  to  com-
              pare  the  new package with the previous version after the build
              is complete, and the result will be included in the  build  log.



CONFIGURATION FILES
       /etc/cowpoke.conf
              Global configuration options.  Will override hardcoded defaults.

       ~/.cowpoke
              Per-user configuration options.  Will override any  global  con-
              figuration.

       .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 over-
              ride all configuration files.



COWBUILDER CONFIGURATION
       There is nothing particularly special  required  to  configure  a  cow-
       builder  instance  for  use  with  cowpoke.   Simply create them in the
       flavour you require with `cowbuilder --create` according  to  the  cow-
       builder  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  INCOM-
       ING_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 subse-
       quent 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-
       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  uncommit-
       ted 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)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.