path: root/scripts/cowpoke.1

.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH COWPOKE 1 "April 28, 2008"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
cowpoke \- Build a Debian source package in a remote cowbuilder instance
.SH SYNOPSIS
.B cowpoke
.RI [ options ] " packagename.dsc"

.SH DESCRIPTION
Uploads a Debian source package to a \fBcowbuilder\fR host and builds it,
optionally also signing and uploading the result to an incoming queue.


.SH OPTIONS
The following options are available:

.TP
.BI \-\-arch= architecture
Specify the Debian architecture(s) to build for.  A space separated list of
architectures may be used to build for all of them in a single pass.  Valid
arch names are those returned by \fBdpkg-architecture\fP(1) for
\fBDEB_BUILD_ARCH\fP.

.TP
.BI \-\-dist= distribution
Specify the Debian distribution(s) to build for.  A space separated list of
distributions may be used to build for all of them in a single pass.  Either
codenames (such as \fBsid\fP, or \fBsqueeze\fP) or distribution names (such as
\fBunstable\fP, or \fBexperimental\fP) 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 \fBBASE_DIST\fP option in a configuration file.
This permits the maintenance and use of specially configured build chroots,
which can source package dependencies from the backports archives or a local
repository, or have other unusual configuration options set, without polluting
the chroots you use for clean package builds intended for upload to the main
repositories.  See the description of \fBBASE_DIST\fP below.

.TP
.BI \-\-buildd= host
Specify the remote host to build on.

.TP
.BI \-\-buildd\-user= name
Specify the remote user to build as.

.TP
.B \-\-create
Create the remote \fBcowbuilder\fR root if it does not already exist.  If this option
is not passed it is an error for the specified \fB\-\-dist\fP or \fB\-\-arch\fP
to not have an existing \fBcowbuilder\fR root in the expected location.

The \fB\-\-buildd\-user\fP must have permission to create the \fBRESULT_DIR\fP
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.

.TP
.BR \-\-return= [ \fIpath ]
Copy results of the build to \fIpath\fP.  If \fIpath\fP is not specified, then return
them to the current directory. The given \fIpath\fP must exist, it will not be created.

.TP
.B \-\-no\-return
Do not copy results of the build to \fBRETURN_DIR\fP (overriding a path set for
it in the configuration files).

.TP
.BI \-\-dpkg\-opts= "'opt1 opt2 ...'"
Specify additional options to be passed to \fBdpkg-buildpackage\fP(1).  Multiple
options are delimited with spaces.  This will override any options specified in
\fBDEBBUILDOPTS\fP in the build host's \fIpbuilderrc\fP.

.TP
.BI \-\-create\-opts= "'cowbuilder option'"
Specify additional arguments to be passed verbatim to \fBcowbuilder\fR when a
chroot is first created (using the \fB\-\-create\fP option above). If multiple
arguments need to be passed, this option should be specified separately for
each of them.

E.g., \fB\-\-create\-opts "\-\-othermirror" \-\-create\-opts "deb http:// ..."\fP

This option will override any \fBCREATE_OPTS\fP specified for a chroot in the
cowpoke configuration files.

.TP
.BI \-\-update\-opts= "'cowbuilder option'"
Specify additional arguments to be passed verbatim to \fBcowbuilder\fR 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 \fBUPDATE_OPTS\fP specified for a chroot in the
cowpoke configuration files.

.TP
.BI \-\-build\-opts= "'cowbuilder option'"
Specify additional arguments to be passed verbatim to \fBcowbuilder\fR when
a package build is performed.  If multiple arguments need to be passed, this
option should be specified separately for each of them.

This option will override any \fBBUILD_OPTS\fP specified for a chroot in the
cowpoke configuration files.

.TP
.BI \-\-sign= keyid
Specify the key to sign packages with.  This will override any \fBSIGN_KEYID\fP
specified for a chroot in the cowpoke configuration files.

.TP
.BI \-\-upload= queue
Specify the dput queue to upload signed packages to.  This will override any
\fBUPLOAD_QUEUE\fP specified for a chroot in the cowpoke configuration files.

.TP
.B \-\-help
Display a brief summary of the available options and current configuration.

.TP
.B \-\-version
Display the current version information.


.SH CONFIGURATION OPTIONS
When \fBcowpoke\fP 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 \fBBUILDD_USER\fR's
home directory.  Since the paths are typically quoted when used, tilde expansion
will \fBnot\fP be performed on them.

.SS Global defaults
These apply to every \fIarch\fP and \fIdist\fP in a single cowpoke invocation.

.TP
.B BUILDD_HOST
The network address or fqdn of the build machine where \fBcowbuilder\fR is configured.
This may be overridden by the \fB\-\-buildd\fP command line option.
.TP
.B BUILDD_USER
The unprivileged user name for operations on the build machine.  This defaults
to the local name of the user executing \fBcowpoke\fP (or to a username that is
specified in your SSH configuration for \fBBUILDD_HOST\fR), and may be overridden by the
\fB\-\-buildd\-user\fP command line option.
.TP
.B BUILDD_ARCH
The Debian architecture(s) to build for.  This must match the \fBDEB_BUILD_ARCH\fP
of the build chroot being used.  It defaults to the local machine architecture where
\fBcowpoke\fP is executed, and may be overridden by the \fB\-\-arch\fP command line
option.  A (quoted) space separated list of architectures may be used here to build
for all of them in a single pass.
.TP
.B BUILDD_DIST
The Debian distribution(s) to build for.  A (quoted) space separated list of
distributions may be used to build for all of them in a single pass.  This may
be overridden by the \fB\-\-dist\fP command line option.

.TP
.B INCOMING_DIR
The directory path on the build machine where the source package will initially
be placed.  This must be writable by the \fBBUILDD_USER\fP.
.TP
.B PBUILDER_BASE
The filesystem root for all pbuilder CoW and result files.  \fIArch\fP and \fIdist\fP
specific subdirectories will normally be created under this.  The apt cache
and temporary build directory will also be located under this path.

.TP
.B SIGN_KEYID
If this option is set, it is expected to contain the gpg key ID to pass to
\fBdebsign\fP(1) 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 \fIarch\fP and \fIdist\fP specific basis using
the
.IB arch _ dist _SIGN_KEYID
option described below, or per-invocation with the \fB\-\-sign\fP command line
option.

.TP
.B UPLOAD_QUEUE
If this option is set, it is expected to contain a 'host' specification for
\fBdput\fP(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 packages
will be made.  If \fBSIGN_KEYID\fP is not set, this option will be ignored entirely.
It may be overridden on an \fIarch\fP and \fIdist\fP specific basis using the
.IB arch _ dist _UPLOAD_QUEUE
option described below, or per-invocation with the \fB\-\-upload\fP command line
option.


.TP
.B BUILDD_ROOTCMD
The command to use to gain root privileges on the remote build machine.  If
unset the default is \fBsudo\fP(8).  This is only required to invoke \fBcowbuilder\fR
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 \fBcowbuilder\fR without an additional password entry
required:
.TP
.B " "
.RS 1.5i
youruser ALL = NOPASSWD: /usr/sbin/cowbuilder
.RE
.TP
.B " "
Alternatively you could use SSH with a forwarded key, or whatever other
mechanism suits your local access policy.  Using \fBsu \-c\fR isn't really
suitable here due to its quoting requirements being somewhat different to
the rest.

.TP
.B DEBOOTSTRAP
The utility to use when creating a new build root.  Alternatives are
.BR debootstrap " or " cdebootstrap .

.TP
.B 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 \fB\-\-return\fR or \fB\-\-no-return\fR.


.SS Arch and dist specific options
These are variables of the form: $arch_$dist\fB_VAR\fR which apply only for a
particular target arch/dist build.

.TP
.IB 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, \fBdebdiff\fP 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 \fBBUILDD_USER\fP for sanity checking with \fBlintian\fP(1) and
\fBdebdiff\fP(1), and for upload with \fBdput\fP(1).  If this option is not
specified for some arch and dist combination then it will default to
.I $PBUILDER_BASE/$arch/$dist/result

.TP
.IB arch _ dist _BASE_PATH
The directory where the CoW master files are to be found (or created if the
\fB\-\-create\fP command line option was passed).  If this option is not specified
for some arch or dist then it will default to
.I $PBUILDER_BASE/$arch/$dist/base.cow

.TP
.IB arch _ dist _BASE_DIST
The code name to pass as the \fB\-\-distribution\fP option for cowbuilder instead
of \fIdist\fP.  This is necessary when \fIdist\fP 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 \fBcowpoke\fP. If this
option is not specified for an arch and dist combination then it will default to
.IR dist .

.TP
.IB arch _ dist _CREATE_OPTS
A bash array containing additional options to pass verbatim to \fBcowbuilder\fP
when this chroot is created for the first time (using the \fB\-\-create\fP option).
This is useful when options like \fB\-\-othermirror\fP 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 \fB\-\-create\-opts\fP
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." )

.TP
.IB arch _ dist _UPDATE_OPTS
A bash array containing additional options to pass verbatim to \fBcowbuilder\fP
each time the base of this chroot is updated.  It behaves similarly to the
\fBCREATE_OPTS\fP option above, except for acting when the chroot is updated.

.TP
.IB arch _ dist _BUILD_OPTS
A bash array containing additional options to pass verbatim to \fBcowbuilder\fP
each time a package build is performed in this chroot.  This is useful when you
want to use some option like \fB\-\-twice\fP which cowpoke does not directly
need to care about.  It otherwise behaves similarly to \fBUPDATE_OPTS\fP above
except that it acts during the build phase of \fBcowbuilder\fP.

.TP
.IB arch _ dist _SIGN_KEYID
An optional arch and dist specific override for the global \fBSIGN_KEYID\fP
option.

.TP
.IB arch _ dist _UPLOAD_QUEUE
An optional arch and dist specific override for the global \fBUPLOAD_QUEUE\fP
option.


.SH CONFIGURATION FILES
.TP
.I /etc/cowpoke.conf
Global configuration options.  Will override hardcoded defaults.
.TP
.I ~/.cowpoke
Per\-user configuration options.  Will override any global configuration.
.TP
.I .cowpoke
Per\-project configuration options.  Will override any per-user or global
configuration if \fBcowpoke\fP is called from the directory where they exist.

If the environment variable \fBCOWPOKE_CONF\fP is set, it specifies an additional
configuration file which will override all of those above.  Options specified
explicitly on the command line override all configuration files.


.SH COWBUILDER CONFIGURATION
There is nothing particularly special required to configure a \fBcowbuilder\fR instance
for use with \fBcowpoke\fP.  Simply create them in the flavour you require with
`\fBcowbuilder \-\-create\fP` according to the \fBcowbuilder\fR documentation, then
configure \fBcowpoke\fP with the user, arch, and path information required to
access it, on the machines you wish to invoke it from (or alternatively configure
\fBcowpoke\fP with the path, arch and distribution information and pass the
\fB\-\-create\fP option to it on the first invocation).  The build host running
\fBcowbuilder\fR does not require \fBcowpoke\fP installed locally.

The build machine should have the \fBlintian\fP and \fBdevscripts\fR packages
installed for post-build sanity checking.  Upon completion, the build log and
the results of automated checks will be recorded in the \fBINCOMING_DIR\fP.
If you wish to upload signed packages the build machine will also need
\fBdput\fP(1) installed and configured to use the '\fIhost\fP' alias specified
by \fBUPLOAD_QUEUE\fP.  If \fBrsync\fP(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 \fIorig.tar.*\fP when building subsequent Debian
revisions).

The user executing \fBcowpoke\fP must have SSH access to the build machine as
the \fBBUILDD_USER\fP.  That user must be able to invoke \fBcowbuilder\fR as root by
using the \fBBUILDD_ROOTCMD\fP.  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 \fBcowpoke\fP.

When \fBcowpoke\fP is invoked, it will first attempt to update the \fBcowbuilder\fR
image if that has not already been done on the same day.  This is checked by
the presence or absence of a \fIcowbuilder-$arch-$dist-update-log-$date\fP file
in the \fBINCOMING_DIR\fP.  You may move, remove, or touch this file if you wish
the image to be updated more or less often than that.  Its contents log the
output of \fBcowbuilder\fR during the update (or creation) of the build root.


.SH NOTES
Since \fBcowbuilder\fP creates a chroot, and to do that you need root, \fBcowpoke\fP
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.  \fBcowbuilder\fR 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 \fBcowpoke\fP to keep all
that on a machine that isn't your bleeding edge dev box with your last few hours
of uncommitted work.

.SH SEE ALSO
.BR cowbuilder (1),
.BR pbuilder (1),
.BR ssh-agent (1),
.BR sudoers (5)

.SH AUTHOR
.B cowpoke
was written by Ron <\fIron@debian.org\fP>.