'\" t
.\"     Title: pybit-client
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 04/06/2018
.\"    Manual: pybit-client
.\"    Source: November 2012
.\"  Language: English
.\"
.TH "PYBIT\-CLIENT" "1" "04/06/2018" "November 2012" "pybit\-client"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pybit-client \- buildd client script to perform build jobs using pybit queues\&.
.SH "SYNOPSIS"
.HP \w'\fBpybit\-client\fR\ 'u
\fBpybit\-client\fR [\fIoptions\fR]
.SH "DESCRIPTION"
.PP
pybit\-client receives messages from the controller to create a specific package build using the specified version control system\&. The client feeds status messages back to the controller\&.
.SH "USAGE"
.PP
pybit\-client runs as a single\-instance daemon by default\&. The standard daemon control interface is supported:
.sp
.if n \{\
.RS 4
.\}
.nf
invoke\-rc\&.d pybit\-client stop
invoke\-rc\&.d pybit\-client start
update\-rc\&.d pybit\-client disable
update\-rc\&.d pybit\-client enable
.fi
.if n \{\
.RE
.\}
.SH "DAEMON CONFIGURATION"
.PP
Certain values are set using
\fIdebconf\fR
at package installation but values can also be set in
/etc/pybit/client/client\&.conf
and the relevant debconf settings can be updated using
\fIdpkg\-reconfigure pybit\-client\fR\&. The configuration file is in JSON format\&.
.PP
\fIclientid\fR
\- The clientid string for this client (must not be empty and needs to be unique for each client using any one RabbitMQ server)\&.
.PP
\fIhost_arch\fR
\- The native architecture of this client, e\&.g\&. i386\&.
.sp
.if n \{\
.RS 4
.\}
.nf
dpkg\-architecture \-qDEB_BUILD_ARCH
.fi
.if n \{\
.RE
.\}
.PP
\fIuse_lvm\fR
\- Whether lvm snapshots are in use (default is true)\&.
.PP
\fIdistribution\fR
\- The distribution in use\&. e\&.g\&. Debian\&.
.sp
.if n \{\
.RS 4
.\}
.nf
dpkg\-vendor \-\-query vendor
.fi
.if n \{\
.RE
.\}
.PP
\fIpkg_format\fR
\- Tag used by each build client to screen out unsupported binary build formats, e\&.g\&. Debian clients will check for deb and RPM clients would check for rpm\&.
.PP
\fIbuildroot\fR
\- The buildd location on the client filesystem\&. Default:
/home/buildd/pybit
.PP
\fIhost\fR
\- The location of the RabbitMQ server which sends the build messages\&. This can be omitted during initial setup and testing but needs to be specified and the client restarted or no builds will be started\&.
.PP
\fIport\fR
\- Override the standard port of 5672 for the RabbitMQ server\&.
.PP
\fIsuites\fR
\-
\fINEW in 0\&.4\&.1\fR
JSON list of the suites which this client can support \- names must match the Distribution: specified in the changelog of relevant packages and must also match an alias for a configured schroot chroot\&.
.sp
.if n \{\
.RS 4
.\}
.nf
 "suites": [ "unstable" ],
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
 "suites": [ "unstable", "squeeze\-backports" ],
.fi
.if n \{\
.RE
.\}
.PP
The
\fIsuite\fR
field used in 0\&.4\&.0 has been removed \- clients will not start unless at least one suite is specified in the
\fIsuites\fR
list\&. See also
/usr/share/pybitclient/client\&.conf
.PP
\fIuserid\fR
\- If the RabbitMQ server uses authentication, override the default username of
\fIguest\fR\&.
.PP
\fIpassword\fR
\- If the RabbitMQ server uses authentication, override the default password of
\fIguest\fR\&.
.PP
\fIvhost\fR
\- If the RabbitMQ server uses a specific VHost, override the default of
\fI/\fR\&.
.PP
\fIdput\fR
\- options passed down to dput \- see dput (1)\&. The default is
\fI\-U\fR
to stop dput writing \&.upload files\&.
.PP
\fIdput_dest\fR
\- The codename of the location to upload the built packages (must not be empty as the default for dput is typically to upload to ftp\-master\&.debian\&.org)\&.
.PP
\fIpoll_time\fR
\- frequency with which this client checks the queues for new messages\&. Measured in seconds\&. Default: 60 seconds\&.
.PP
\fIdebsignkey\fR
\- keyID to be used to sign the \&.changes files from this buildd\&. If empty or omitted, changes files will never be signed\&.
\fIThe specified key MUST NOT use a passphrase\&.\fR
The key must be usable by the user running
\fBpybit\-client\fR
\- check with
.sp
.if n \{\
.RS 4
.\}
.nf
gpg \-\-list\-secret\-keys
    
.fi
.if n \{\
.RE
.\}
.PP
\fIdry_run\fR
\- initially, clients are setup in dry run mode which means that commands are echoed to the terminal instead of being executed, to allow testing of new setups\&. To enable builds on the client, edit
/etc/pybit/client/client\&.conf
to change the value for dry_run to false\&.
.SH "SCHROOT CONFIGURATION"
.PP
The detailed process of creating chroots suitable for schroot is covered in the sbuild documentation (schroot\&.conf (5)) and amounts to using a tool like debootstrap to create a Debian build environment in a subdirectory (which may or may not be also the mountpoint of an LVM snapshot) and then configuring that chroot to have the relevant apt sources and pre\-installed packages (e\&.g\&. build\-essential and dpkg\-dev)\&.
.PP
Note: when creating a chroot for schroot, remember to use the
\fB\-\-variant=buildd\fR
option to
debootstrap
and install
fakeroot
inside the chroot\&.
.SS "Install pbuilder"
.PP
The pybit debianclient uses
/usr/lib/pbuilder/pbuilder\-satisfydepends\-classic
for the dependency resolution test, so the pbuilder package needs to be installed inside each build chroot\&.
.SS "Naming the chroots"
.PP
The pybit client will expect to be able to use a chroot (or an alias for a chroot) which matches the suite specified in the build request\&. If using version control hooks, this suite is likely to come from the Distribution field of the output of
\fIdpkg\-parsechangelog\fR\&. Ensure that any client has a suitable chroot listed in the output of
\fIschroot \-l\fR\&.
.PP
\fBpybit\-client\fR
only listens to queues which match the listed
\fIsuites\fR
in
/etc/pybit/client/client\&.conf\&.
.PP
The syntax for the suites configuration value changed in version 0\&.4\&.1 to support multiple suites within a JSON list:
.sp
.if n \{\
.RS 4
.\}
.nf
 "suites": [ "unstable", "squeeze\-backports" ],
.fi
.if n \{\
.RE
.\}
.PP
Clients running 0\&.4\&.0 need to have the configuration file updated for 0\&.4\&.1 or the client will fail to start as it will be unable to bind to the necessary queues\&.
.SS "Client backends"
.PP
The principal backend for this version of pybit is SVN \- the git and apt backends are not complete\&. The apt backend, in particular, is not intended for use building any packages which would be uploaded to a public repository as it disables Apt authentication by default for easier configuration of local repositories of build dependencies\&.
.PP
The test script relies on a example buildd data file \- this file can quickly become out of date, check the pybit wiki for more examples\&. https://github\&.com/nicholasdavidson/pybit/wiki/Debian\-clients
.PP
Enabled backends need to be symlinked into
/var/lib/pybit\-client\&.d
.SS "Testing the chroots"
.PP
There is a test script (/usr/share/pybitclient/buildd\-test\&.py) which can be used alongside a test schroot to run through the buildd commands and then do the upload\&. (What happens to that upload is dependent on the next step, it just sits in an incoming directory initially\&.)
.SS "Configuring the upload handler"
.PP
Set up dput by editing
/etc/pybit/client/dput\&.cf
to provide a usable upload configuration\&. The format of this file is the same as ~/\&.dput\&.cf and is passed to dput using the \-c option internally\&. See dput\&.cf (5)
.SH "OPTIONS"
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
show this help message and exit
.RE
.PP
\fB\-\-conf_file\fR=\fICONF_FILE\fR
.RS 4
Configuration file from which settings can be read\&. Defaults to
configs/client\&.conf
from the current working directory or falls back to
/etc/pybit/client/client\&.conf\&.
.RE
.PP
\fB\-\-arch\fR=\fIARCH\fR
.RS 4
Architecture to use, defaults to i386
.RE
.PP
\fB\-d\fR
.RS 4
Run this client as a daemon \- default option used by
/etc/init\&.d/pybit\-client\&.
.RE
.PP
\fB\-\-distribution\fR=\fIPYBIT_CLIENT_DIST\fR
.RS 4
Distribution to use, defaults to Debian
.RE
.PP
\fB\-\-pkg_format\fR=\fIPYBIT_CLIENT_FORMAT\fR
.RS 4
Package type to use, defaults to deb
.RE
.PP
\fB\-\-suite\fR=\fIPYBIT_CLIENT_SUITE\fR
.RS 4
Suite to use, defaults to development
.RE
.PP
\fB\-\-host\fR=\fIPYBIT_CLIENT_HOST\fR
.RS 4
host to connect to, defaults to localhost\&.
.RE
.PP
\fB\-\-vhost\fR=\fIPYBIT_CLIENT_VHOST\fR
.RS 4
vhost to connect to, defaults to localhost\&.
.RE
.PP
\fB\-\-userid\fR=\fIPYBIT_CLIENT_USERID\fR
.RS 4
user id to use for AMQP server, defaults to guest\&.
.RE
.PP
\fB\-\-port\fR=\fIPYBIT_CLIENT_PORT\fR
.RS 4
port to use for AMQP server, defaults to 5672
.RE
.PP
\fB\-\-password\fR=\fIPYBIT_CLIENT_PASSWORD\fR
.RS 4
password to use for AMQP server, defaults to guest
.RE
.PP
\fB\-\-insist\fR=\fIPYBIT_CLIENT_INSIST\fR
.RS 4
insist to use for AMQP server, defaults to 5672
.RE
.PP
\fB\-\-clientid\fR=\fIPYBIT_CLIENT_INSIST\fR
.RS 4
id to use for build\-client control queue, defaults to 1 but is unique per amqp server\&.
.RE
.SH "SETTING UP THE PYBIT SERVER TO WORK WITH CLIENTS"
.PP
The clients are only one part of pybit\&. pybit\-web provides the server which will provide jobs for the clients\&. See pybit\-web (1)\&.
.SH "AUTHOR"
.PP
This manual page was written by Neil Williams
<codehelp@debian\&.org>