Sophie

Sophie

distrib > Mageia > 6 > armv5tl > by-pkgid > 821bff9b1c6450f83fd56c64b66aa3f7 > files > 142

buildbot-doc-0.8.12-3.mga6.noarch.rpm

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Global Configuration &mdash; Buildbot 0.8.12 documentation</title>
    
    <link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '0.8.12',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="shortcut icon" href="../_static/buildbot.ico"/>
    <link rel="top" title="Buildbot 0.8.12 documentation" href="../index.html" />
    <link rel="up" title="Configuration" href="configuration.html" />
    <link rel="next" title="Change Sources" href="cfg-changesources.html" />
    <link rel="prev" title="Configuring Buildbot" href="cfg-intro.html" /> 
  </head>
  <body role="document">
    <div class="header-wrapper" role="banner">
      <div class="header">
          <p class="logo"><a href="../index.html">
            <img class="logo" src="../_static/header-text-transparent.png" alt="Logo"/>
          </a></p>
        <div class="headertitle"><a
          href="../index.html">Buildbot 0.8.12 documentation</a></div>
        <div class="rel" role="navigation" aria-label="related navigation">
          <a href="cfg-intro.html" title="Configuring Buildbot"
             accesskey="P">previous</a> |
          <a href="cfg-changesources.html" title="Change Sources"
             accesskey="N">next</a> |
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a>
        </div>
       </div>
    </div>

    <div class="content-wrapper">
      <div class="content">
        <div class="document">
            
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="global-configuration">
<h1>Global Configuration<a class="headerlink" href="#global-configuration" title="Permalink to this headline">¶</a></h1>
<p>The keys in this section affect the operations of the buildmaster globally.</p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#database-specification" id="id8">Database Specification</a></li>
<li><a class="reference internal" href="#multi-master-mode" id="id9">Multi-master mode</a></li>
<li><a class="reference internal" href="#site-definitions" id="id10">Site Definitions</a></li>
<li><a class="reference internal" href="#log-handling" id="id11">Log Handling</a></li>
<li><a class="reference internal" href="#data-lifetime" id="id12">Data Lifetime</a></li>
<li><a class="reference internal" href="#merging-build-requests" id="id13">Merging Build Requests</a></li>
<li><a class="reference internal" href="#prioritizing-builders" id="id14">Prioritizing Builders</a></li>
<li><a class="reference internal" href="#setting-the-pb-port-for-slaves" id="id15">Setting the PB Port for Slaves</a></li>
<li><a class="reference internal" href="#defining-global-properties" id="id16">Defining Global Properties</a></li>
<li><a class="reference internal" href="#debug-options" id="id17">Debug Options</a></li>
<li><a class="reference internal" href="#manhole" id="id18">Manhole</a></li>
<li><a class="reference internal" href="#metrics-options" id="id19">Metrics Options</a></li>
<li><a class="reference internal" href="#users-options" id="id20">Users Options</a></li>
<li><a class="reference internal" href="#input-validation" id="id21">Input Validation</a></li>
<li><a class="reference internal" href="#revision-links" id="id22">Revision Links</a></li>
<li><a class="reference internal" href="#codebase-generator" id="id23">Codebase Generator</a></li>
</ul>
</div>
<span class="target" id="cfg-db"></span><span class="target" id="cfg-db_url"></span><div class="section" id="database-specification">
<span id="cfg-db_poll_interval"></span><span id="id1"></span><h2><a class="toc-backref" href="#id8">Database Specification</a><a class="headerlink" href="#database-specification" title="Permalink to this headline">¶</a></h2>
<p>Buildbot requires a connection to a database to maintain certain state information, such as tracking pending build requests.
In the default configuration Buildbot uses a file-based SQLite database, stored in the <code class="file docutils literal"><span class="pre">state.sqlite</span></code> file of the master's base directory.
Override this configuration with the <a class="reference internal" href="#cfg-db_url" title="db_url"><code class="xref bb bb-cfg docutils literal"><span class="pre">db_url</span></code></a> parameter.</p>
<p>Buildbot accepts a database configuration in a dictionary named <code class="docutils literal"><span class="pre">db</span></code>.
All keys are optional:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;db&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;db_url&#39;</span><span class="p">:</span> <span class="s1">&#39;sqlite:///state.sqlite&#39;</span><span class="p">,</span>
    <span class="s1">&#39;db_poll_interval&#39;</span><span class="p">:</span> <span class="mi">30</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">db_url</span></code> key indicates the database engine to use.
The format of this parameter is completely documented at <a class="reference external" href="http://www.sqlalchemy.org/docs/dialects/">http://www.sqlalchemy.org/docs/dialects/</a>, but is generally of the form:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="s2">&quot;driver://[username:password@]host:port/database[?args]&quot;</span>
</pre></div>
</div>
<p>The optional <code class="docutils literal"><span class="pre">db_poll_interval</span></code> specifies the interval, in seconds, between checks for pending tasks in the database.
This parameter is generally only useful in multi-master mode.
See <a class="reference internal" href="#multi-master-mode"><span class="std std-ref">Multi-master mode</span></a>.</p>
<p>These parameters can be specified directly in the configuration dictionary, as <code class="docutils literal"><span class="pre">c['db_url']</span></code> and <code class="docutils literal"><span class="pre">c['db_poll_interval']</span></code>, although this method is deprecated.</p>
<p>The following sections give additional information for particular database backends:</p>
<div class="section" id="sqlite">
<span id="index-0"></span><h3>SQLite<a class="headerlink" href="#sqlite" title="Permalink to this headline">¶</a></h3>
<p>For sqlite databases, since there is no host and port, relative paths are specified with <code class="docutils literal"><span class="pre">sqlite:///</span></code> and absolute paths with <code class="docutils literal"><span class="pre">sqlite:////</span></code>.
Examples:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;db_url&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;sqlite:///state.sqlite&quot;</span>
</pre></div>
</div>
<p>SQLite requires no special configuration.</p>
<p>If Buildbot produces &quot;database is locked&quot; exceptions, try adding <code class="docutils literal"><span class="pre">serialize_access=1</span></code> to the DB URL as a workaround:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;db_url&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;sqlite:///state.sqlite?serialize_access=1&quot;</span>
</pre></div>
</div>
<p>and please file a bug at <a class="reference external" href="http://trac.buildbot.net">http://trac.buildbot.net</a>.</p>
</div>
<div class="section" id="mysql">
<span id="index-1"></span><h3>MySQL<a class="headerlink" href="#mysql" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;db_url&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;mysql://user:pass@somehost.com/database_name?max_idle=300&quot;</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">max_idle</span></code> argument for MySQL connections is unique to Buildbot, and should be set to something less than the <code class="docutils literal"><span class="pre">wait_timeout</span></code> configured for your server.
This controls the SQLAlchemy <code class="docutils literal"><span class="pre">pool_recycle</span></code> parameter, which defaults to no timeout.
Setting this parameter ensures that connections are closed and re-opened after the configured amount of idle time.
If you see errors such as <code class="docutils literal"><span class="pre">_mysql_exceptions.OperationalError:</span> <span class="pre">(2006,</span> <span class="pre">'MySQL</span> <span class="pre">server</span> <span class="pre">has</span> <span class="pre">gone</span> <span class="pre">away')</span></code>, this means your <code class="docutils literal"><span class="pre">max_idle</span></code> setting is probably too high.
<code class="docutils literal"><span class="pre">show</span> <span class="pre">global</span> <span class="pre">variables</span> <span class="pre">like</span> <span class="pre">'wait_timeout';</span></code> will show what the currently configured <code class="docutils literal"><span class="pre">wait_timeout</span></code> is on your MySQL server.</p>
<p>Buildbot requires <code class="docutils literal"><span class="pre">use_unique=True</span></code> and <code class="docutils literal"><span class="pre">charset=utf8</span></code>, and will add them automatically, so they do not need to be specified in <code class="docutils literal"><span class="pre">db_url</span></code>.</p>
<p>MySQL defaults to the MyISAM storage engine, but this can be overridden with the <code class="docutils literal"><span class="pre">storage_engine</span></code> URL argument.</p>
<p>Note that, because of InnoDB's extremely short key length limitations, it cannot be used to run Buildbot.
See <a class="reference external" href="http://bugs.mysql.com/bug.php?id=4541">http://bugs.mysql.com/bug.php?id=4541</a> for more information.</p>
</div>
<div class="section" id="postgres">
<span id="index-2"></span><h3>Postgres<a class="headerlink" href="#postgres" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;db_url&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;postgresql://username@hostname/dbname&quot;</span>
</pre></div>
</div>
<p>PosgreSQL requires no special configuration.</p>
</div>
</div>
<div class="section" id="multi-master-mode">
<span id="cfg-multiMaster"></span><span id="id2"></span><h2><a class="toc-backref" href="#id9">Multi-master mode</a><a class="headerlink" href="#multi-master-mode" title="Permalink to this headline">¶</a></h2>
<p>Normally buildbot operates using a single master process that uses the configured database to save state.</p>
<p>It is possible to configure buildbot to have multiple master processes that share state in the same database.
This has been well tested using a MySQL database.
There are several benefits of Multi-master mode:</p>
<ul class="simple">
<li>You can have large numbers of build slaves handling the same queue of build requests.
A single master can only handle so many slaves (the number is based on a number of factors including type of builds, number of builds, and master and slave IO and CPU capacity--there is no fixed formula).
By adding another master which shares the queue of build requests, you can attach more slaves to this additional master, and increase your build throughput.</li>
<li>You can shut one master down to do maintenance, and other masters will continue to do builds.</li>
</ul>
<p>State that is shared in the database includes:</p>
<ul class="simple">
<li>List of changes</li>
<li>Scheduler names and internal state</li>
<li>Build requests, including the builder name</li>
</ul>
<p>Because of this shared state, you are strongly encouraged to:</p>
<ul class="simple">
<li>Ensure that each named scheduler runs on only one master.
If the same scheduler runs on multiple masters, it will trigger duplicate builds and may produce other undesirable behaviors.</li>
<li>Ensure builder names are unique for a given build factory implementation.
You can have the same builder name configured on many masters, but if the build factories differ, you will get different results depending on which master claims the build.</li>
</ul>
<p>One suggested configuration is to have one buildbot master configured with just the scheduler and change sources; and then other masters configured with just the builders.</p>
<p>To enable multi-master mode in this configuration, you will need to set the <a class="reference internal" href="#cfg-multiMaster" title="multiMaster"><code class="xref bb bb-cfg docutils literal"><span class="pre">multiMaster</span></code></a> option so that buildbot doesn't warn about missing schedulers or builders.
You will also need to set <a class="reference internal" href="#cfg-db_poll_interval" title="db_poll_interval"><code class="xref bb bb-cfg docutils literal"><span class="pre">db_poll_interval</span></code></a> to specify the interval (in seconds) at which masters should poll the database for tasks.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Enable multiMaster mode; disables warnings about unknown builders and</span>
<span class="c1"># schedulers</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;multiMaster&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span>
<span class="c1"># Check for new build requests every 60 seconds</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;db&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;db_url&#39;</span> <span class="p">:</span> <span class="s1">&#39;mysql://...&#39;</span><span class="p">,</span>
    <span class="s1">&#39;db_poll_interval&#39;</span> <span class="p">:</span> <span class="mi">30</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<span class="target" id="cfg-buildbotURL"></span><span class="target" id="cfg-titleURL"></span></div>
<div class="section" id="site-definitions">
<span id="cfg-title"></span><h2><a class="toc-backref" href="#id10">Site Definitions</a><a class="headerlink" href="#site-definitions" title="Permalink to this headline">¶</a></h2>
<p>Three basic settings describe the buildmaster in status reports:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;title&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;Buildbot&quot;</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;titleURL&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;http://buildbot.sourceforge.net/&quot;</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;buildbotURL&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;http://localhost:8010/&quot;</span>
</pre></div>
</div>
<p><a class="reference internal" href="#cfg-title" title="title"><code class="xref bb bb-cfg docutils literal"><span class="pre">title</span></code></a> is a short string that will appear at the top of this buildbot installation's <code class="xref py py-class docutils literal"><span class="pre">html.WebStatus</span></code> home page (linked to the <a class="reference internal" href="#cfg-titleURL" title="titleURL"><code class="xref bb bb-cfg docutils literal"><span class="pre">titleURL</span></code></a>), and is embedded in the title of the waterfall HTML page.</p>
<p><a class="reference internal" href="#cfg-titleURL" title="titleURL"><code class="xref bb bb-cfg docutils literal"><span class="pre">titleURL</span></code></a> is a URL string that must end with a slash (<code class="docutils literal"><span class="pre">/</span></code>).
HTML status displays will show <code class="docutils literal"><span class="pre">title</span></code> as a link to <a class="reference internal" href="#cfg-titleURL" title="titleURL"><code class="xref bb bb-cfg docutils literal"><span class="pre">titleURL</span></code></a>.
This URL is often used to provide a link from buildbot HTML pages to your project's home page.</p>
<p>The <a class="reference internal" href="#cfg-buildbotURL" title="buildbotURL"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildbotURL</span></code></a> string should point to the location where the buildbot's internal web server is visible.
This URL must end with a slash (<code class="docutils literal"><span class="pre">/</span></code>).
This typically uses the port number set for the web status (<a class="reference internal" href="cfg-statustargets.html#status-WebStatus" title="WebStatus"><code class="xref bb bb-status docutils literal"><span class="pre">WebStatus</span></code></a>): the buildbot needs your help to figure out a suitable externally-visible host URL.</p>
<p>When status notices are sent to users (either by email or over IRC), <a class="reference internal" href="#cfg-buildbotURL" title="buildbotURL"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildbotURL</span></code></a> will be used to create a URL to the specific build or problem that they are being notified about.
It will also be made available to queriers (over IRC) who want to find out where to get more information about this buildbot.</p>
<span class="target" id="cfg-logCompressionLimit"></span><span class="target" id="cfg-logCompressionMethod"></span><span class="target" id="cfg-logMaxSize"></span></div>
<div class="section" id="log-handling">
<span id="cfg-logMaxTailSize"></span><h2><a class="toc-backref" href="#id11">Log Handling</a><a class="headerlink" href="#log-handling" title="Permalink to this headline">¶</a></h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;logCompressionLimit&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">16384</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;logCompressionMethod&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;gz&#39;</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;logMaxSize&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1024</span><span class="o">*</span><span class="mi">1024</span> <span class="c1"># 1M</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;logMaxTailSize&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">32768</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#cfg-logCompressionLimit" title="logCompressionLimit"><code class="xref bb bb-cfg docutils literal"><span class="pre">logCompressionLimit</span></code></a> enables compression of build logs on disk for logs that are bigger than the given size, or disables that completely if set to <code class="docutils literal"><span class="pre">False</span></code>.
The default value is 4096, which should be a reasonable default on most file systems.
This setting has no impact on status plugins, and merely affects the required disk space on the master for build logs.</p>
<p>The <a class="reference internal" href="#cfg-logCompressionMethod" title="logCompressionMethod"><code class="xref bb bb-cfg docutils literal"><span class="pre">logCompressionMethod</span></code></a> controls what type of compression is used for build logs.
The default is 'bz2', and the other valid option is 'gz'.
'bz2' offers better compression at the expense of more CPU time.</p>
<p>The <a class="reference internal" href="#cfg-logMaxSize" title="logMaxSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">logMaxSize</span></code></a> parameter sets an upper limit (in bytes) to how large logs from an individual build step can be.
The default value is None, meaning no upper limit to the log size.
Any output exceeding <a class="reference internal" href="#cfg-logMaxSize" title="logMaxSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">logMaxSize</span></code></a> will be truncated, and a message to this effect will be added to the log's HEADER channel.</p>
<p>If <a class="reference internal" href="#cfg-logMaxSize" title="logMaxSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">logMaxSize</span></code></a> is set, and the output from a step exceeds the maximum, the <a class="reference internal" href="#cfg-logMaxTailSize" title="logMaxTailSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">logMaxTailSize</span></code></a> parameter controls how much of the end of the build log will be kept.
The effect of setting this parameter is that the log will contain the first <a class="reference internal" href="#cfg-logMaxSize" title="logMaxSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">logMaxSize</span></code></a> bytes and the last <a class="reference internal" href="#cfg-logMaxTailSize" title="logMaxTailSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">logMaxTailSize</span></code></a> bytes of output.
Don't set this value too high, as the the tail of the log is kept in memory.</p>
</div>
<div class="section" id="data-lifetime">
<h2><a class="toc-backref" href="#id12">Data Lifetime</a><a class="headerlink" href="#data-lifetime" title="Permalink to this headline">¶</a></h2>
<span class="target" id="cfg-changeHorizon"></span><span class="target" id="cfg-buildHorizon"></span><span class="target" id="cfg-eventHorizon"></span><div class="section" id="horizons">
<span id="cfg-logHorizon"></span><h3>Horizons<a class="headerlink" href="#horizons" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;changeHorizon&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">200</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;buildHorizon&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">100</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;eventHorizon&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">50</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;logHorizon&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">40</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;buildCacheSize&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">15</span>
</pre></div>
</div>
<p>Buildbot stores historical information on disk in the form of &quot;Pickle&quot; files and compressed logfiles.
In a large installation, these can quickly consume disk space, yet in many cases developers never consult this historical information.</p>
<p>The <a class="reference internal" href="#cfg-changeHorizon" title="changeHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">changeHorizon</span></code></a> key determines how many changes the master will keep a record of.
One place these changes are displayed is on the waterfall page.
This parameter defaults to 0, which means keep all changes indefinitely.</p>
<p>The <a class="reference internal" href="#cfg-buildHorizon" title="buildHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildHorizon</span></code></a> specifies the minimum number of builds for each builder which should be kept on disk.
The <a class="reference internal" href="#cfg-eventHorizon" title="eventHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">eventHorizon</span></code></a> specifies the minimum number of events to keep--events mostly describe connections and disconnections of slaves, and are seldom helpful to developers.
The <a class="reference internal" href="#cfg-logHorizon" title="logHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">logHorizon</span></code></a> gives the minimum number of builds for which logs should be maintained; this parameter must be less than or equal to <a class="reference internal" href="#cfg-buildHorizon" title="buildHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildHorizon</span></code></a>.
Builds older than <a class="reference internal" href="#cfg-logHorizon" title="logHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">logHorizon</span></code></a> but not older than <a class="reference internal" href="#cfg-buildHorizon" title="buildHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildHorizon</span></code></a> will maintain their overall status and the status of each step, but the logfiles will be deleted.</p>
<span class="target" id="cfg-caches"></span><span class="target" id="cfg-changeCacheSize"></span></div>
<div class="section" id="caches">
<span id="cfg-buildCacheSize"></span><h3>Caches<a class="headerlink" href="#caches" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;caches&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;Changes&#39;</span> <span class="p">:</span> <span class="mi">100</span><span class="p">,</span>     <span class="c1"># formerly c[&#39;changeCacheSize&#39;]</span>
    <span class="s1">&#39;Builds&#39;</span> <span class="p">:</span> <span class="mi">500</span><span class="p">,</span>      <span class="c1"># formerly c[&#39;buildCacheSize&#39;]</span>
    <span class="s1">&#39;chdicts&#39;</span> <span class="p">:</span> <span class="mi">100</span><span class="p">,</span>
    <span class="s1">&#39;BuildRequests&#39;</span> <span class="p">:</span> <span class="mi">10</span><span class="p">,</span>
    <span class="s1">&#39;SourceStamps&#39;</span> <span class="p">:</span> <span class="mi">20</span><span class="p">,</span>
    <span class="s1">&#39;ssdicts&#39;</span> <span class="p">:</span> <span class="mi">20</span><span class="p">,</span>
    <span class="s1">&#39;objectids&#39;</span> <span class="p">:</span> <span class="mi">10</span><span class="p">,</span>
    <span class="s1">&#39;usdicts&#39;</span> <span class="p">:</span> <span class="mi">100</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#cfg-caches" title="caches"><code class="xref bb bb-cfg docutils literal"><span class="pre">caches</span></code></a> configuration key contains the configuration for Buildbot's in-memory caches.
These caches keep frequently-used objects in memory to avoid unnecessary trips to the database or to pickle files.
Caches are divided by object type, and each has a configurable maximum size.</p>
<p>The default size for each cache is 1, except where noted below.
A value of 1 allows Buildbot to make a number of optimizations without consuming much memory.
Larger, busier installations will likely want to increase these values.</p>
<p>The available caches are:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">Changes</span></code></dt>
<dd><p class="first">the number of change objects to cache in memory.
This should be larger than the number of changes that typically arrive in the span of a few minutes, otherwise your schedulers will be reloading changes from the database every time they run.
For distributed version control systems, like Git or Hg, several thousand changes may arrive at once, so setting this parameter to something like 10000 isn't unreasonable.</p>
<p class="last">This parameter is the same as the deprecated global parameter <a class="reference internal" href="#cfg-changeCacheSize" title="changeCacheSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">changeCacheSize</span></code></a>.
Its default value is 10.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">Builds</span></code></dt>
<dd><p class="first">The <a class="reference internal" href="#cfg-buildCacheSize" title="buildCacheSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildCacheSize</span></code></a> parameter gives the number of builds for each builder which are cached in memory.
This number should be larger than the number of builds required for commonly-used status displays (the waterfall or grid views), so that those displays do not miss the cache on a refresh.</p>
<p class="last">This parameter is the same as the deprecated global parameter <a class="reference internal" href="#cfg-buildCacheSize" title="buildCacheSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildCacheSize</span></code></a>.
Its default value is 15.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">chdicts</span></code></dt>
<dd>The number of rows from the <code class="docutils literal"><span class="pre">changes</span></code> table to cache in memory.
This value should be similar to the value for <code class="docutils literal"><span class="pre">Changes</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">BuildRequests</span></code></dt>
<dd>The number of BuildRequest objects kept in memory.
This number should be higher than the typical number of outstanding build requests.
If the master ordinarily finds jobs for BuildRequests immediately, you may set a lower value.</dd>
<dt><code class="docutils literal"><span class="pre">SourceStamps</span></code></dt>
<dd>the number of SourceStamp objects kept in memory.
This number should generally be similar to the number <code class="docutils literal"><span class="pre">BuildRequesets</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">ssdicts</span></code></dt>
<dd>The number of rows from the <code class="docutils literal"><span class="pre">sourcestamps</span></code> table to cache in memory.
This value should be similar to the value for <code class="docutils literal"><span class="pre">SourceStamps</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">objectids</span></code></dt>
<dd>The number of object IDs - a means to correlate an object in the Buildbot configuration with an identity in the database--to cache.
In this version, object IDs are not looked up often during runtime, so a relatively low value such as 10 is fine.</dd>
<dt><code class="docutils literal"><span class="pre">usdicts</span></code></dt>
<dd><p class="first">The number of rows from the <code class="docutils literal"><span class="pre">users</span></code> table to cache in memory.
Note that for a given user there will be a row for each attribute that user has.</p>
<p class="last">c['buildCacheSize'] = 15</p>
</dd>
</dl>
<span class="target" id="cfg-mergeRequests"></span></div>
</div>
<div class="section" id="merging-build-requests">
<span id="index-3"></span><h2><a class="toc-backref" href="#id13">Merging Build Requests</a><a class="headerlink" href="#merging-build-requests" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;mergeRequests&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
</div>
<p>This is a global default value for builders' <a class="reference internal" href="#cfg-mergeRequests" title="mergeRequests"><code class="xref bb bb-cfg docutils literal"><span class="pre">mergeRequests</span></code></a> parameter, and controls the merging of build requests.</p>
<p>This parameter can be overridden on a per-builder basis.
See <a class="reference internal" href="cfg-builders.html#merging-build-requests"><span class="std std-ref">Merging Build Requests</span></a> for the allowed values for this parameter.</p>
<span class="target" id="index-4"></span></div>
<div class="section" id="prioritizing-builders">
<span id="cfg-prioritizeBuilders"></span><span id="id3"></span><h2><a class="toc-backref" href="#id14">Prioritizing Builders</a><a class="headerlink" href="#prioritizing-builders" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">prioritizeBuilders</span><span class="p">(</span><span class="n">buildmaster</span><span class="p">,</span> <span class="n">builders</span><span class="p">):</span>
    <span class="o">...</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;prioritizeBuilders&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">prioritizeBuilders</span>
</pre></div>
</div>
<p>By default, buildbot will attempt to start builds on builders in order, beginning with the builder with the oldest pending request.
Customize this behavior with the <a class="reference internal" href="#cfg-prioritizeBuilders" title="prioritizeBuilders"><code class="xref bb bb-cfg docutils literal"><span class="pre">prioritizeBuilders</span></code></a> configuration key, which takes a callable.
See <a class="reference internal" href="customization.html#builder-priority-functions"><span class="std std-ref">Builder Priority Functions</span></a> for details on this callable.</p>
<p>This parameter controls the order that the build master can start builds, and is useful in situations where there is resource contention between builders, e.g., for a test database.
It does not affect the order in which a builder processes the build requests in its queue.
For that purpose, see <a class="reference internal" href="cfg-builders.html#prioritizing-builds"><span class="std std-ref">Prioritizing Builds</span></a>.</p>
</div>
<div class="section" id="setting-the-pb-port-for-slaves">
<span id="cfg-protocols"></span><span id="id4"></span><h2><a class="toc-backref" href="#id15">Setting the PB Port for Slaves</a><a class="headerlink" href="#setting-the-pb-port-for-slaves" title="Permalink to this headline">¶</a></h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;protocols&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;pb&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;port&quot;</span><span class="p">:</span> <span class="mi">10000</span><span class="p">}}</span>
</pre></div>
</div>
<p>The buildmaster will listen on a TCP port of your choosing for connections from buildslaves.
It can also use this port for connections from remote Change Sources, status clients, and debug tools.
This port should be visible to the outside world, and you'll need to tell your buildslave admins about your choice.</p>
<p>It does not matter which port you pick, as long it is externally visible; however, you should probably use something larger than 1024, since most operating systems don't allow non-root processes to bind to low-numbered ports.
If your buildmaster is behind a firewall or a NAT box of some sort, you may have to configure your firewall to permit inbound connections to this port.</p>
<p><code class="docutils literal"><span class="pre">c['protocols']['pb']['port']</span></code> is a <em>strports</em> specification string, defined in the <code class="docutils literal"><span class="pre">twisted.application.strports</span></code> module (try <code class="docutils literal"><span class="pre">pydoc</span> <span class="pre">twisted.application.strports</span></code> to get documentation on the format).</p>
<p>This means that you can have the buildmaster listen on a localhost-only port by doing:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;protocols&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;pb&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;port&quot;</span><span class="p">:</span> <span class="s2">&quot;tcp:10000:interface=127.0.0.1&quot;</span><span class="p">}}</span>
</pre></div>
</div>
<p>This might be useful if you only run buildslaves on the same machine, and they are all configured to contact the buildmaster at <code class="docutils literal"><span class="pre">localhost:10000</span></code>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In Buildbot versions &lt;=0.8.8 you might see <code class="docutils literal"><span class="pre">slavePortnum</span></code> option.
This option contains same value as <code class="docutils literal"><span class="pre">c['protocols']['pb']['port']</span></code> but not recomended to use.</p>
</div>
<span class="target" id="index-5"></span></div>
<div class="section" id="defining-global-properties">
<span id="cfg-properties"></span><h2><a class="toc-backref" href="#id16">Defining Global Properties</a><a class="headerlink" href="#defining-global-properties" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#cfg-properties" title="properties"><code class="xref bb bb-cfg docutils literal"><span class="pre">properties</span></code></a> configuration key defines a dictionary of properties that will be available to all builds started by the buildmaster:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;properties&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;Widget-version&#39;</span> <span class="p">:</span> <span class="s1">&#39;1.2&#39;</span><span class="p">,</span>
    <span class="s1">&#39;release-stage&#39;</span> <span class="p">:</span> <span class="s1">&#39;alpha&#39;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="debug-options">
<span id="cfg-debugPassword"></span><span id="id5"></span><h2><a class="toc-backref" href="#id17">Debug Options</a><a class="headerlink" href="#debug-options" title="Permalink to this headline">¶</a></h2>
<p>If you set <a class="reference internal" href="#cfg-debugPassword" title="debugPassword"><code class="xref bb bb-cfg docutils literal"><span class="pre">debugPassword</span></code></a>, then you can connect to the buildmaster with the diagnostic tool launched by <code class="samp docutils literal"><span class="pre">buildbot</span> <span class="pre">debugclient</span> <em><span class="pre">MASTER</span></em><span class="pre">:</span><em><span class="pre">PORT</span></em></code>.
From this tool, you can reload the config file, manually force builds, and inject changes, which may be useful for testing your buildmaster without actually committing changes to your repository (or before you have the Change Sources configured.)</p>
<p>The debug tool uses the same port number as the slaves, <a class="reference internal" href="#cfg-protocols" title="protocols"><code class="xref bb bb-cfg docutils literal"><span class="pre">protocols</span></code></a>, and you may configure its authentication credentials as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;debugPassword&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;debugpassword&quot;</span>
</pre></div>
</div>
<span class="target" id="index-6"></span></div>
<div class="section" id="manhole">
<span id="cfg-manhole"></span><h2><a class="toc-backref" href="#id18">Manhole</a><a class="headerlink" href="#manhole" title="Permalink to this headline">¶</a></h2>
<p>If you set <a class="reference internal" href="#cfg-manhole" title="manhole"><code class="xref bb bb-cfg docutils literal"><span class="pre">manhole</span></code></a> to an instance of one of the classes in <code class="docutils literal"><span class="pre">buildbot.manhole</span></code>, you can telnet or ssh into the buildmaster and get an interactive Python shell, which may be useful for debugging buildbot internals.
It is probably only useful for buildbot developers.
It exposes full access to the buildmaster's account (including the ability to modify and delete files), so it should not be enabled with a weak or easily guessable password.</p>
<p>There are three separate <code class="xref py py-class docutils literal"><span class="pre">Manhole</span></code> classes.
Two of them use SSH, one uses unencrypted telnet.
Two of them use a username+password combination to grant access, one of them uses an SSH-style <code class="file docutils literal"><span class="pre">authorized_keys</span></code> file which contains a list of ssh public keys.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Using any Manhole requires that <code class="docutils literal"><span class="pre">pycrypto</span></code> and <code class="docutils literal"><span class="pre">pyasn1</span></code> be installed.
These are not part of the normal Buildbot dependencies.</p>
</div>
<dl class="docutils">
<dt><cite>manhole.AuthorizedKeysManhole</cite></dt>
<dd>You construct this with the name of a file that contains one SSH public key per line, just like <code class="file docutils literal"><span class="pre">~/.ssh/authorized_keys</span></code>.
If you provide a non-absolute filename, it will be interpreted relative to the buildmaster's base directory.</dd>
<dt><cite>manhole.PasswordManhole</cite></dt>
<dd>This one accepts SSH connections but asks for a username and password when authenticating.
It accepts only one such pair.</dd>
<dt><cite>manhole.TelnetManhole</cite></dt>
<dd>This accepts regular unencrypted telnet connections, and asks for a username/password pair before providing access.
Because this username/password is transmitted in the clear, and because Manhole access to the buildmaster is equivalent to granting full shell privileges to both the buildmaster and all the buildslaves (and to all accounts which then run code produced by the buildslaves), it is  highly recommended that you use one of the SSH manholes instead.</dd>
</dl>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># some examples:</span>
<span class="kn">from</span> <span class="nn">buildbot.plugins</span> <span class="k">import</span> <span class="n">util</span>

<span class="n">c</span><span class="p">[</span><span class="s1">&#39;manhole&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">AuthorizedKeysManhole</span><span class="p">(</span><span class="mi">1234</span><span class="p">,</span> <span class="s2">&quot;authorized_keys&quot;</span><span class="p">)</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;manhole&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">PasswordManhole</span><span class="p">(</span><span class="mi">1234</span><span class="p">,</span> <span class="s2">&quot;alice&quot;</span><span class="p">,</span> <span class="s2">&quot;mysecretpassword&quot;</span><span class="p">)</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;manhole&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">TelnetManhole</span><span class="p">(</span><span class="mi">1234</span><span class="p">,</span> <span class="s2">&quot;bob&quot;</span><span class="p">,</span> <span class="s2">&quot;snoop_my_password_please&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="xref py py-class docutils literal"><span class="pre">Manhole</span></code> instance can be configured to listen on a specific port.
You may wish to have this listening port bind to the loopback interface (sometimes known as <cite>lo0</cite>, <cite>localhost</cite>, or 127.0.0.1) to restrict access to clients which are running on the same host.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">buildbot.plugins</span> <span class="k">import</span> <span class="n">util</span>

<span class="n">c</span><span class="p">[</span><span class="s1">&#39;manhole&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">PasswordManhole</span><span class="p">(</span><span class="s2">&quot;tcp:9999:interface=127.0.0.1&quot;</span><span class="p">,</span> <span class="s2">&quot;admin&quot;</span><span class="p">,</span> <span class="s2">&quot;passwd&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>To have the <code class="xref py py-class docutils literal"><span class="pre">Manhole</span></code> listen on all interfaces, use <code class="docutils literal"><span class="pre">&quot;tcp:9999&quot;</span></code> or simply 9999.
This port specification uses <code class="docutils literal"><span class="pre">twisted.application.strports</span></code>, so you can make it listen on SSL or even UNIX-domain sockets if you want.</p>
<p>Note that using any <code class="xref py py-class docutils literal"><span class="pre">Manhole</span></code> requires that the <a class="reference external" href="http://twistedmatrix.com/trac/wiki/TwistedConch">TwistedConch</a> package be installed.</p>
<p>The buildmaster's SSH server will use a different host key than the normal sshd running on a typical unix host.
This will cause the ssh client to complain about a <cite>host key mismatch</cite>, because it does not realize there are two separate servers running on the same host.
To avoid this, use a clause like the following in your <code class="file docutils literal"><span class="pre">.ssh/config</span></code> file:</p>
<div class="highlight-none"><div class="highlight"><pre><span></span>Host remotehost-buildbot
HostName remotehost
HostKeyAlias remotehost-buildbot
Port 9999
# use &#39;user&#39; if you use PasswordManhole and your name is not &#39;admin&#39;.
# if you use AuthorizedKeysManhole, this probably doesn&#39;t matter.
User admin
</pre></div>
</div>
<div class="section" id="using-manhole">
<h3>Using Manhole<a class="headerlink" href="#using-manhole" title="Permalink to this headline">¶</a></h3>
<p>After you have connected to a manhole instance, you will find yourself at a Python prompt.
You have access to two objects: <code class="docutils literal"><span class="pre">master</span></code> (the BuildMaster) and <code class="docutils literal"><span class="pre">status</span></code> (the master's Status object).
Most interesting objects on the master can be reached from these two objects.</p>
<p>To aid in navigation, the <code class="docutils literal"><span class="pre">show</span></code> method is defined.
It displays the non-method attributes of an object.</p>
<p>A manhole session might look like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">show</span><span class="p">(</span><span class="n">master</span><span class="p">)</span>
<span class="go">data attributes of &lt;buildbot.master.BuildMaster instance at 0x7f7a4ab7df38&gt;</span>
<span class="go">                       basedir : &#39;/home/dustin/code/buildbot/t/buildbot/&#39;...</span>
<span class="go">                     botmaster : &lt;type &#39;instance&#39;&gt;</span>
<span class="go">                buildCacheSize : None</span>
<span class="go">                  buildHorizon : None</span>
<span class="go">                   buildbotURL : http://localhost:8010/</span>
<span class="go">               changeCacheSize : None</span>
<span class="go">                    change_svc : &lt;type &#39;instance&#39;&gt;</span>
<span class="go">                configFileName : master.cfg</span>
<span class="go">                            db : &lt;class &#39;buildbot.db.connector.DBConnector&#39;&gt;</span>
<span class="go">              db_poll_interval : None</span>
<span class="go">                        db_url : sqlite:///state.sqlite</span>
<span class="go">                              ...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">show</span><span class="p">(</span><span class="n">master</span><span class="o">.</span><span class="n">botmaster</span><span class="o">.</span><span class="n">builders</span><span class="p">[</span><span class="s1">&#39;win32&#39;</span><span class="p">])</span>
<span class="go">data attributes of &lt;Builder &#39;&#39;builder&#39;&#39; at 48963528&gt;</span>
<span class="go">                              ...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">win32</span> <span class="o">=</span> <span class="n">_</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">win32</span><span class="o">.</span><span class="n">category</span> <span class="o">=</span> <span class="s1">&#39;w32&#39;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="metrics-options">
<span id="cfg-metrics"></span><h2><a class="toc-backref" href="#id19">Metrics Options</a><a class="headerlink" href="#metrics-options" title="Permalink to this headline">¶</a></h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;metrics&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">log_interval</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">periodic_interval</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
<p><a class="reference internal" href="#cfg-metrics" title="metrics"><code class="xref bb bb-cfg docutils literal"><span class="pre">metrics</span></code></a> can be a dictionary that configures various aspects of the metrics subsystem.
If <a class="reference internal" href="#cfg-metrics" title="metrics"><code class="xref bb bb-cfg docutils literal"><span class="pre">metrics</span></code></a> is <code class="docutils literal"><span class="pre">None</span></code>, then metrics collection, logging and reporting will be disabled.</p>
<p><code class="docutils literal"><span class="pre">log_interval</span></code> determines how often metrics should be logged to twistd.log.
It defaults to 60s.
If set to 0 or <code class="docutils literal"><span class="pre">None</span></code>, then logging of metrics will be disabled.
This value can be changed via a reconfig.</p>
<p><code class="docutils literal"><span class="pre">periodic_interval</span></code> determines how often various non-event based metrics are collected, such as memory usage, uncollectable garbage, reactor delay.
This defaults to 10s.
If set to 0 or <code class="docutils literal"><span class="pre">None</span></code>, then periodic collection of this data is disabled.
This value can also be changed via a reconfig.</p>
<p>Read more about metrics in the <a class="reference internal" href="../developer/metrics.html#metrics"><span class="std std-ref">Metrics</span></a> section in the developer documentation.</p>
</div>
<div class="section" id="users-options">
<span id="cfg-user_managers"></span><span id="id6"></span><h2><a class="toc-backref" href="#id20">Users Options</a><a class="headerlink" href="#users-options" title="Permalink to this headline">¶</a></h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">buildbot.plugins</span> <span class="k">import</span> <span class="n">util</span>

<span class="n">c</span><span class="p">[</span><span class="s1">&#39;user_managers&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;user_managers&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">util</span><span class="o">.</span><span class="n">CommandlineUserManager</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s2">&quot;user&quot;</span><span class="p">,</span>
                                                      <span class="n">passwd</span><span class="o">=</span><span class="s2">&quot;userpw&quot;</span><span class="p">,</span>
                                                      <span class="n">port</span><span class="o">=</span><span class="mi">9990</span><span class="p">))</span>
</pre></div>
</div>
<p><a class="reference internal" href="#cfg-user_managers" title="user_managers"><code class="xref bb bb-cfg docutils literal"><span class="pre">user_managers</span></code></a> contains a list of ways to manually manage User Objects within Buildbot (see <a class="reference internal" href="concepts.html#user-objects"><span class="std std-ref">User Objects</span></a>).
Currently implemented is a commandline tool <cite>buildbot user</cite>, described at length in <a class="reference internal" href="cmdline.html#cmdline-user" title="user"><code class="xref bb bb-cmdline docutils literal"><span class="pre">user</span></code></a>.
In the future, a web client will also be able to manage User Objects and their attributes.</p>
<p>As shown above, to enable the <cite>buildbot user</cite> tool, you must initialize a <cite>CommandlineUserManager</cite> instance in your <cite>master.cfg</cite>.
<cite>CommandlineUserManager</cite> instances require the following arguments:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">username</span></code></dt>
<dd>This is the <cite>username</cite> that will be registered on the PB connection and need to be used when calling <cite>buildbot user</cite>.</dd>
<dt><code class="docutils literal"><span class="pre">passwd</span></code></dt>
<dd>This is the <cite>passwd</cite> that will be registered on the PB connection and need to be used when calling <cite>buildbot user</cite>.</dd>
<dt><code class="docutils literal"><span class="pre">port</span></code></dt>
<dd>The PB connection <cite>port</cite> must be different than <cite>c['protocols']['pb']['port']</cite> and be specified when calling <cite>buildbot user</cite></dd>
</dl>
</div>
<div class="section" id="input-validation">
<span id="cfg-validation"></span><span id="id7"></span><h2><a class="toc-backref" href="#id21">Input Validation</a><a class="headerlink" href="#input-validation" title="Permalink to this headline">¶</a></h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">re</span>
<span class="n">c</span><span class="p">[</span><span class="s1">&#39;validation&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;branch&#39;</span><span class="p">:</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s1">r&#39;^[\w.+/~-]*$&#39;</span><span class="p">),</span>
    <span class="s1">&#39;revision&#39;</span><span class="p">:</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s1">r&#39;^[ \w\.\-\/]*$&#39;</span><span class="p">),</span>
    <span class="s1">&#39;property_name&#39;</span><span class="p">:</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s1">r&#39;^[\w\.\-\/\~:]*$&#39;</span><span class="p">),</span>
    <span class="s1">&#39;property_value&#39;</span><span class="p">:</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s1">r&#39;^[\w\.\-\/\~:]*$&#39;</span><span class="p">),</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This option configures the validation applied to user inputs of various types.
This validation is important since these values are often included in command-line arguments executed on slaves.
Allowing arbitrary input from untrusted users may raise security concerns.</p>
<p>The keys describe the type of input validated; the values are compiled regular expressions against which the input will be matched.
The defaults for each type of input are those given in the example, above.</p>
</div>
<div class="section" id="revision-links">
<span id="cfg-revlink"></span><h2><a class="toc-backref" href="#id22">Revision Links</a><a class="headerlink" href="#revision-links" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#cfg-revlink" title="revlink"><code class="xref bb bb-cfg docutils literal"><span class="pre">revlink</span></code></a> parameter is used to create links from revision IDs in the web status to a web-view of your source control system.
The parameter's value must be a callable.</p>
<p>By default, Buildbot is configured to generate revlinks for a number of open source hosting platforms.</p>
<p>The callable takes the revision id and repository argument, and should return an URL to the revision.
Note that the revision id may not always be in the form you expect, so code defensively.
In particular, a revision of &quot;??&quot; may be supplied when no other information is available.</p>
<p>Note that <code class="xref py py-class docutils literal"><span class="pre">SourceStamp</span></code>s that are not created from version-control changes (e.g., those created by a Nightly or Periodic scheduler) may have an empty repository string, if the repository is not known to the scheduler.</p>
<div class="section" id="revision-link-helpers">
<h3>Revision Link Helpers<a class="headerlink" href="#revision-link-helpers" title="Permalink to this headline">¶</a></h3>
<p>Buildbot provides two helpers for generating revision links.
<code class="xref py py-class docutils literal"><span class="pre">buildbot.revlinks.RevlinkMatcher</span></code> takes a list of regular expressions, and replacement text.
The regular expressions should all have the same number of capture groups.
The replacement text should have sed-style references to that capture groups (i.e. '1' for the first capture group), and a single '%s' reference, for the revision ID.
The repository given is tried against each regular expression in turn.
The results are the substituted into the replacement text, along with the revision ID to obtain the revision link.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">buildbot.plugins</span> <span class="k">import</span> <span class="n">util</span>

<span class="n">c</span><span class="p">[</span><span class="s1">&#39;revlink&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">RevlinkMatch</span><span class="p">([</span><span class="s1">r&#39;git://notmuchmail.org/git/(.*)&#39;</span><span class="p">],</span>
                                 <span class="s1">r&#39;http://git.notmuchmail.org/git/\1/commit/</span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p><code class="xref py py-class docutils literal"><span class="pre">buildbot.revlinks.RevlinkMultiplexer</span></code> takes a list of revision link callables, and tries each in turn, returning the first successful match.</p>
</div>
</div>
<div class="section" id="codebase-generator">
<span id="cfg-codebaseGenerator"></span><h2><a class="toc-backref" href="#id23">Codebase Generator</a><a class="headerlink" href="#codebase-generator" title="Permalink to this headline">¶</a></h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">all_repositories</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">r&#39;https://hg/hg/mailsuite/mailclient&#39;</span><span class="p">:</span> <span class="s1">&#39;mailexe&#39;</span><span class="p">,</span>
    <span class="s1">r&#39;https://hg/hg/mailsuite/mapilib&#39;</span><span class="p">:</span> <span class="s1">&#39;mapilib&#39;</span><span class="p">,</span>
    <span class="s1">r&#39;https://hg/hg/mailsuite/imaplib&#39;</span><span class="p">:</span> <span class="s1">&#39;imaplib&#39;</span><span class="p">,</span>
    <span class="s1">r&#39;https://github.com/mailinc/mailsuite/mailclient&#39;</span><span class="p">:</span> <span class="s1">&#39;mailexe&#39;</span><span class="p">,</span>
    <span class="s1">r&#39;https://github.com/mailinc/mailsuite/mapilib&#39;</span><span class="p">:</span> <span class="s1">&#39;mapilib&#39;</span><span class="p">,</span>
    <span class="s1">r&#39;https://github.com/mailinc/mailsuite/imaplib&#39;</span><span class="p">:</span> <span class="s1">&#39;imaplib&#39;</span><span class="p">,</span>
<span class="p">}</span>

<span class="k">def</span> <span class="nf">codebaseGenerator</span><span class="p">(</span><span class="n">chdict</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">all_repositories</span><span class="p">[</span><span class="n">chdict</span><span class="p">[</span><span class="s1">&#39;repository&#39;</span><span class="p">]]</span>

<span class="n">c</span><span class="p">[</span><span class="s1">&#39;codebaseGenerator&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">codebaseGenerator</span>
</pre></div>
</div>
<p>For any incoming change, the <a class="reference internal" href="concepts.html#attr-codebase"><span class="std std-ref">codebase</span></a> is set to ''.
This codebase value is sufficient if all changes come from the same repository (or clones).
If changes come from different repositories, extra processing will be needed to determine the codebase for the incoming change.
This codebase will then be a logical name for the combination of repository and or branch etc.</p>
<p>The <cite>codebaseGenerator</cite> accepts a change dictionary as produced by the <code class="xref py py-class docutils literal"><span class="pre">buildbot.db.changes.ChangesConnectorComponent</span></code>, with a changeid equal to <cite>None</cite>.</p>
</div>
</div>


          </div>
        </div>
      </div>
        </div>
        <div class="sidebar">
<h3>Table Of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Buildbot Tutorial</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Buildbot Manual</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html">Concepts</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="configuration.html">Configuration</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="cfg-intro.html">Configuring Buildbot</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Global Configuration</a><ul class="simple">
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="cfg-changesources.html">Change Sources</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-schedulers.html">Schedulers</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-buildslaves.html">Buildslaves</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-builders.html">Builder Configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-buildfactories.html">Build Factories</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-properties.html">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-buildsteps.html">Build Steps</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-interlocks.html">Interlocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-statustargets.html">Status Targets</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="customization.html">Customization</a></li>
<li class="toctree-l2"><a class="reference internal" href="new-style-steps.html">New-Style Build Steps</a></li>
<li class="toctree-l2"><a class="reference internal" href="cmdline.html">Command-line Tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="resources.html">Resources</a></li>
<li class="toctree-l2"><a class="reference internal" href="optimization.html">Optimization</a></li>
<li class="toctree-l2"><a class="reference internal" href="plugins.html">Plugin Infrastructure in Buildbot</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../developer/index.html">Buildbot Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="../relnotes/index.html">Release Notes for Buildbot 0.8.12</a></li>
</ul>

          <div role="search">
            <h3 style="margin-top: 1.5em;">Search</h3>
            <form class="search" action="../search.html" method="get">
                <input type="text" name="q" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
            </form>
          </div>
        </div>
        <div class="clearer"></div>
      </div>
    </div>

    <div class="footer-wrapper">
      <div class="footer">
        <div class="left">
          <div role="navigation" aria-label="related navigaton">
            <a href="cfg-intro.html" title="Configuring Buildbot"
              >previous</a> |
            <a href="cfg-changesources.html" title="Change Sources"
              >next</a> |
            <a href="../py-modindex.html" title="Python Module Index"
              >modules</a> |
            <a href="../genindex.html" title="General Index"
              >index</a>
          </div>
          <div role="note" aria-label="source link">
              <br/>
              <a href="../_sources/manual/cfg-global.txt"
                rel="nofollow">Show Source</a>
          </div>
        </div>

        <div class="right">
          
    <div class="footer" role="contentinfo">
        &copy; Copyright Buildbot Team Members.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.1.
    </div>
        </div>
        <div class="clearer"></div>
      </div>
    </div>

  </body>
</html>