4.13.1.2 WebStatus Configuration Parameters

HTTP Connection

The most common way to run a WebStatus is on a regular TCP port. To do this, just pass in the TCP port number when you create the WebStatus instance; this is called the http_port argument:

     from buildbot.status.html import WebStatus
     c['status'].append(http_port=WebStatus(http_port=8080))

The http_port argument is actually a “strports specification” for the port that the web server should listen on. This can be a simple port number, or a string like http_port="tcp:8080:interface=127.0.0.1" (to limit connections to the loopback interface, and therefore to clients running on the same host)¹.

If instead (or in addition) you provide the distrib_port argument, a twisted.web distributed server will be started either on a TCP port (if distrib_port is like "tcp:12345") or more likely on a UNIX socket (if distrib_port is like "unix:/path/to/socket").

The public_html option gives the path to a regular directory of HTML files that will be displayed alongside the various built-in URLs buildbot supplies. This is most often used to supply CSS files (/buildbot.css) and a top-level navigational file (/index.html), but can also serve any other files required - even build results!

Authorization

The buildbot web status is, by default, read-only. It displays lots of information, but users are not allowed to affect the operation of the buildmaster. However, there are a number of supported activities that can be enabled, and Buildbot can also perform rudimentary username/password authentication. The actions are:

forceBuild

force a particular builder to begin building, optionally with a specific revision, branch, etc.

forceAllBuilds

force all builders to start building

pingBuilder

"ping" a builder's buildslaves to check that they are alive

gracefulShutdown

gracefully shut down a slave when it is finished with its current build

stopBuild

stop a running build

stopAllBuilds

stop all running builds

cancelPendingBuild

cancel a build that has not yet started

stopChange

cancel builds that include a given change number

cleanShutdown

shut down the master gracefully, without interrupting builds

For each of these actions, you can configure buildbot to never allow the action, always allow the action, allow the action to any authenticated user, or check with a function of your creation to determine whether the action is OK.

This is all configured with the Authz class:

     from buildbot.status.html import WebStatus
     from buildbot.status.web.authz import Authz
     authz = Authz(
         forceBuild=True,
         stopBuild=True)
     c['status'].append(http_port=WebStatus(http_port=8080, authz=authz))

Each of the actions listed above is an option to Authz. You can specify False (the default) to prohibit that action or True to enable it.

Authentication

If you do not wish to allow strangers to perform actions, but do want developers to have such access, you will need to add some authentication support. Pass an instance of status.web.auth.IAuth as a auth keyword argument to Authz, and specify the action as "auth".

     from buildbot.status.html import WebStatus
     from buildbot.status.web.authz import Authz
     from buildbot.status.web.auth import BasicAuth
     users = [('bob', 'secret-pass'), ('jill', 'super-pass')]
     authz = Authz(auth=BasicAuth(users),
         forceBuild='auth', # only authenticated users
         pingBuilder=True, # but anyone can do this
     )
     c['status'].append(WebStatus(http_port=8080, authz=authz))
     # or
     from buildbot.status.web.auth import HTPasswdAuth
     auth = (HTPasswdAuth('/path/to/htpasswd'))

The class BasicAuth implements a basic authentication mechanism using a list of user/password tuples provided from the configuration file. The class HTPasswdAuth implements an authentication against an .htpasswd file.

If you need still-more flexibility, pass a function for the authentication action. That function will be called with an authenticated username and some action-specific arguments, and should return true if the action is authorized.

     def canForceBuild(username, builder_status):
         if builder_status.getName() == 'smoketest':
             return True # any authenticated user can run smoketest
         elif username == 'releng':
             return True # releng can force whatever they want
         else:
             return False # otherwise, no way.
     
     authz = Authz(auth=BasicAuth(users),
         forceBuild=canForceBuild)

The forceBuild and pingBuilder actions both supply a BuilderStatus object. The stopBuild action supplies a BuildStatus object. The cancelPendingBuild action supplies a BuildRequest. The remainder do not supply any extra arguments.

Logging configuration

The WebStatus uses a separate log file (http.log) to avoid clutter buildbot's default log (twistd.log) with request/response messages. This log is also, by default, rotated in the same way as the twistd.log file, but you can also customize the rotation logic with the following parameters if you need a different behaviour.

rotateLength

An integer defining the file size at which log files are rotated.

maxRotatedFiles

The maximum number of old log files to keep.

URL-decorating options

These arguments adds an URL link to various places in the WebStatus, such as revisions, repositories, projects and, optionally, ticket/bug references in change comments.

revlink

The revlink is used to create links from revision IDs in the web status to a web-view of your source control system. The parametr's value must be a format string, a dict mapping a string (repository name) to format strings, or a callable.

The format string should use '%s' to insert the revision id in the url. For example, for Buildbot on github: revlink='http://github.com/buildbot/buildbot/tree/%s' (The revision ID will be URL encoded before inserted in the replacement string)

The callable takes the revision id and repository argument, and should return an URL to the revision.

Note that SourceStamps that are not created from version-control changes (e.g., those created by a Nightly or Periodic scheduler) will have an empty repository string, as the respository is not known.

changecommentlink

The changecommentlink argument can be used to create links to ticket-ids from change comments (i.e. #123).

The argument can either be a tuple of three strings, a dictionary mapping strings (project names) to tuples or a callable taking a changetext (a jinja2.Markup instance) and a project name, returning a the same change text with additional links/html tags added to it.

If the tuple is used, it should contain three strings where the first element is a regex that searches for strings (with match groups), the second is a replace-string that, when substituted with \1 etc, yields the URL and the third is the title attribute of the link. (The <a href="" title=""></a> is added by the system.) So, for Trac tickets (#42, etc): changecommentlink(r"#(\d+)", r"http://buildbot.net/trac/ticket/\1", r"Ticket \g<0>") .

projects

A dictionary from strings to strings, mapping project names to URLs, or a callable taking a project name and returning an URL.

repositories

Same as the projects arg above, a dict or callable mapping project names to URLs.

Display-Specific Options

The order_console_by_time option affects the rendering of the console; see the description of the console above.

The numbuilds option determines the number of builds that most status displays will show. It can usually be overriden in the URL, e.g., ?numbuilds=13.

The num_events option gives the default number of events that the waterfall will display. The num_events_max gives the maximum number of events displayed, even if the web browser requests more.