diff options
Diffstat (limited to '')
| -rw-r--r-- | scripts/cowpoke.1 | 388 |
1 files changed, 388 insertions, 0 deletions
diff --git a/scripts/cowpoke.1 b/scripts/cowpoke.1 new file mode 100644 index 0000000..7d5177b --- /dev/null +++ b/scripts/cowpoke.1 @@ -0,0 +1,388 @@ +.\" 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>. + |