<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="pybit-client">
  <refmeta>
    <refentrytitle>pybit-client</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">November 2012</refmiscinfo>
    <refmiscinfo class="manual">pybit-client</refmiscinfo>
  </refmeta>
  <refnamediv id="name">
    <refname>pybit-client</refname>
    <refpurpose>buildd client script to perform build jobs using pybit queues.</refpurpose>
  </refnamediv>
  <!-- body begins here -->
  <refsynopsisdiv id="synopsis">
    <cmdsynopsis>
      <command>pybit-client</command>
      <arg choice="opt">
        <replaceable>options</replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1 id="description">
    <title>DESCRIPTION</title>
    <para>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.
</para>
  </refsect1>
  <refsect1 id="usage">
    <title>Usage</title>
    <para>pybit-client runs as a single-instance daemon by default. The standard
    daemon control interface is supported:
</para>
    <programlisting>
invoke-rc.d pybit-client stop
invoke-rc.d pybit-client start
update-rc.d pybit-client disable
update-rc.d pybit-client enable
</programlisting>
  </refsect1>
  <refsect1 id="configuration">
    <title>Daemon Configuration</title>
    <para>
Certain values are set using <emphasis>debconf</emphasis> at package installation but values can also be
set in <filename>/etc/pybit/client/client.conf</filename> and the relevant debconf settings can be
updated using <emphasis>dpkg-reconfigure pybit-client</emphasis>. The configuration file is in JSON
format.
</para>
    <para><emphasis>clientid</emphasis> -
The clientid string for this client (must not be empty and needs to be unique for each client using any one RabbitMQ server).
</para>
    <para><emphasis>host_arch</emphasis> -
The native architecture of this client, e.g. i386.
</para>
    <programlisting>
dpkg-architecture -qDEB_BUILD_ARCH
</programlisting>
    <para><emphasis>use_lvm</emphasis> -
Whether lvm snapshots are in use (default is true).
</para>
    <para><emphasis>distribution</emphasis> -
The distribution in use. e.g. Debian.
</para>
    <programlisting>
dpkg-vendor --query vendor
</programlisting>
    <para><emphasis>pkg_format</emphasis> -
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.
</para>
    <para><emphasis>buildroot</emphasis> -
The buildd location on the client filesystem. Default: <filename>/home/buildd/pybit</filename>
</para>
    <para><emphasis>host</emphasis> -
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.
</para>
    <para><emphasis>port</emphasis> -
Override the standard port of 5672 for the RabbitMQ server.
</para>
    <para><emphasis>suites</emphasis> - <emphasis>NEW in 0.4.1</emphasis>
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.
</para>
<programlisting>
 "suites": [ "unstable" ],
</programlisting>
<programlisting>
 "suites": [ "unstable", "squeeze-backports" ],
</programlisting>
    <para>The <emphasis>suite</emphasis> field used in 0.4.0 has been
removed - clients will not start unless at least one suite is specified
in the <emphasis>suites</emphasis> list. See also <filename>/usr/share/pybitclient/client.conf</filename>
</para>
    <para><emphasis>userid</emphasis> -
If the RabbitMQ server uses authentication, override the default username of <emphasis>guest</emphasis>.
</para>
    <para><emphasis>password</emphasis> -
If the RabbitMQ server uses authentication, override the default password of <emphasis>guest</emphasis>.
</para>
    <para><emphasis>vhost</emphasis> -
If the RabbitMQ server uses a specific VHost, override the default of <emphasis>/</emphasis>.
</para>
    <para><emphasis>dput</emphasis> -
options passed down to dput - see dput (1). The default is
<emphasis>-U</emphasis> to stop dput writing .upload files.
</para>
    <para><emphasis>dput_dest</emphasis> -
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).
</para>
    <para><emphasis>poll_time</emphasis> - frequency with which this client checks
the queues for new messages. Measured in seconds. Default: 60 seconds.
</para>
    <para><emphasis>debsignkey</emphasis> - keyID to be used to sign the .changes files from
    this buildd. If empty or omitted, changes files will never be signed.
    <emphasis>The specified key MUST NOT use a passphrase.</emphasis> The key must be
    usable by the user running <command>pybit-client</command> - check with
    <programlisting>
gpg --list-secret-keys
    </programlisting>
    </para>
    <para><emphasis>dry_run</emphasis> - 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 <filename>/etc/pybit/client/client.conf</filename>
to change the value for dry_run to false.
</para>
  </refsect1>
  <refsect1 id="schroot">
    <title>schroot configuration</title>
    <para>
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).
</para>
<para>
Note: when creating a chroot for schroot, remember to use the
<option>--variant=buildd</option> option to <filename>debootstrap</filename>
and install <filename>fakeroot</filename> inside the chroot.
</para>
    <refsect2 id="pbuilder">
      <title>Install pbuilder</title>
      <para>
The pybit debianclient uses <filename>/usr/lib/pbuilder/pbuilder-satisfydepends-classic</filename>
for the dependency resolution test, so the pbuilder package needs to be
installed inside each build chroot.
</para>
    </refsect2>
    <refsect2 id="naming">
      <title>Naming the chroots</title>
      <para>
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 <emphasis>dpkg-parsechangelog</emphasis>. Ensure that
any client has a suitable chroot listed in the output of <emphasis>schroot -l</emphasis>.
</para>
<para>
<command>pybit-client</command> only listens to queues which match the listed
<emphasis>suites</emphasis> in <filename>/etc/pybit/client/client.conf</filename>.
</para>
<para>The syntax for the suites configuration value changed in version 0.4.1
to support multiple suites within a JSON list:
</para>
<programlisting>
 "suites": [ "unstable", "squeeze-backports" ],
</programlisting>
<para>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.
</para>
    </refsect2>
    <refsect2 id="backends">
        <title>Client backends</title>
        <para>
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.
        </para>
<para>
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
</para>
        <para>
Enabled backends need to be symlinked into <code>/var/lib/pybit-client.d</code>
        </para>
    </refsect2>
    <refsect2 id="testing">
      <title>Testing the chroots</title>
      <para>
There is a test script (<filename>/usr/share/pybitclient/buildd-test.py</filename>)
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.)
</para>
    </refsect2>
    <refsect2 id="upload">
      <title>Configuring the upload handler</title>
      <para>
Set up dput by editing <filename>/etc/pybit/client/dput.cf</filename> 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)
</para>
    </refsect2>
  </refsect1>
  <refsect1 id="options">
    <title>OPTIONS</title>
    <variablelist remap="TP">
      <varlistentry>
        <term><option>-h</option>, <option>--help</option></term>
        <listitem>
          <para>show this help message and exit</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--conf_file</option>=<emphasis remap="I">CONF_FILE</emphasis></term>
        <listitem>
          <para>Configuration file from which settings can be read. Defaults to <filename>configs/client.conf</filename>
  from the current working directory or falls back to <filename>/etc/pybit/client/client.conf</filename>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--arch</option>=<emphasis remap="I">ARCH</emphasis></term>
        <listitem>
          <para>Architecture to use, defaults to i386</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-d</option>
        </term>
        <listitem>
          <para>Run this client as a daemon - default option used by <filename>/etc/init.d/pybit-client</filename>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--distribution</option>=<emphasis remap="I">PYBIT_CLIENT_DIST</emphasis></term>
        <listitem>
          <para>Distribution to use, defaults to Debian</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--pkg_format</option>=<emphasis remap="I">PYBIT_CLIENT_FORMAT</emphasis></term>
        <listitem>
          <para>Package type to use, defaults to deb</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--suite</option>=<emphasis remap="I">PYBIT_CLIENT_SUITE</emphasis></term>
        <listitem>
          <para>Suite to use, defaults to development</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--host</option>=<emphasis remap="I">PYBIT_CLIENT_HOST</emphasis></term>
        <listitem>
          <para>host to connect to, defaults to localhost.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--vhost</option>=<emphasis remap="I">PYBIT_CLIENT_VHOST</emphasis></term>
        <listitem>
          <para>vhost to connect to, defaults to localhost.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--userid</option>=<emphasis remap="I">PYBIT_CLIENT_USERID</emphasis></term>
        <listitem>
          <para>user id to use for AMQP server, defaults to guest.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--port</option>=<emphasis remap="I">PYBIT_CLIENT_PORT</emphasis></term>
        <listitem>
          <para>port to use for AMQP server, defaults to 5672</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--password</option>=<emphasis remap="I">PYBIT_CLIENT_PASSWORD</emphasis></term>
        <listitem>
          <para>password to use for AMQP server, defaults to guest</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--insist</option>=<emphasis remap="I">PYBIT_CLIENT_INSIST</emphasis></term>
        <listitem>
          <para>insist to use for AMQP server, defaults to 5672</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--clientid</option>=<emphasis remap="I">PYBIT_CLIENT_INSIST</emphasis></term>
        <listitem>
          <para>id to use for build-client control queue, defaults to
1 but is unique per amqp server.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1 id="server">
      <title>Setting up the pybit server to work with clients</title>
      <para>The clients are only one part of pybit. pybit-web provides
      the server which will provide jobs for the clients. See pybit-web (1).
      </para>
  </refsect1>
  <refsect1>
    <title>Author</title>
    <para>This  manual  page  was  written by Neil Williams
      <email>codehelp@debian.org</email>
    </para>
  </refsect1>
</refentry>