[Buildbot-commits] buildbot/docs buildbot.texinfo,1.12,1.13

Wed Aug 10 04:52:43 UTC 2005

Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv5477/docs

Modified Files:
	buildbot.texinfo 
Log Message:
Revision: arch at buildbot.sf.net--2004/buildbot--dev--0--patch-270
Creator:  Brian Warner <warner at monolith.lothar.com>

add docs for 'try', some placeholder tests

	* docs/buildbot.texinfo (try): add docs on the
	as-yet-unimplemented Try scheduler

	* buildbot/test/test_buildreq.py: move Scheduling tests out to ..
	* buildbot/test/test_scheduler.py: .. here
	(Scheduling.testTryJobdir): add placeholder test for 'try'


Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13

--- buildbot.texinfo	3 Aug 2005 23:47:28 -0000	1.12
+++ buildbot.texinfo	10 Aug 2005 04:52:41 -0000	1.13
@@ -3628,9 +3628,10 @@
 
 For this command to work, several pieces must be in place:
 
+
 @heading TryScheduler
 
-The buildmaster must have a @code{scheduler.TryScheduler} instance in
+The buildmaster must have a @code{scheduler.Try} instance in
 the config file's @code{c['schedulers']} list. This lets the
 administrator control who may initiate these ``trial'' builds, which
 branches are eligible for trial builds, and which Builders should be
@@ -3638,42 +3639,105 @@
 
 The @code{TryScheduler} has various means to accept build requests:
 all of them enforce more security than the usual buildmaster ports do.
-The source code patch that is provided with the trial build could be
-used to compromise the buildslave accounts: the usual force-build
-control channels can waste buildslave time but do not allow arbitrary
-commands to be executed (since the code must be checked out from the
-VC repository). The @code{TryScheduler} requires a bit more
-configuration to insure that it cannot be abused in this way. There
-are currently two ways to set this up:
+Any source code being built can be used to compromise the buildslave
+accounts, but in general that code must be checked out from the VC
+repository first, so only people with commit privileges can get
+control of the buildslaves. The usual force-build control channels can
+waste buildslave time but do not allow arbitrary commands to be
+executed by people who don't have those commit privileges. However,
+the source code patch that is provided with the trial build does not
+have to go through the VC system first, so it is important to make
+sure these builds cannot be abused by a non-committer to acquire as
+much control over the buildslaves as a committer has. Ideally, only
+developers who have commit access to the VC repository would be able
+to start trial builds, but unfortunately the buildmaster does not, in
+general, have access to VC system's user list.
 
- at table @emph
- at item ssh
-create a command queue maildir in the buildmaster's space, admin sets
-the ownership/permissions to only grant write access to trusted
-developers. 'buildbot try' formats an rfc822-style message
-(sourcestamp goes in a header, patch goes in the body) and adds it to
-the queuedir. The config file entries used by 'buildbot try' either
-specify a local queuedir (for which write and mv are used) or a remote
-one (using scp and ssh). +: quite secure. -: requires fiddling outside
-the buildmaster config.
+As a result, the @code{TryScheduler} requires a bit more
+configuration. There are currently two ways to set this up:
+
+ at table @strong
+ at item jobdir (ssh)
+
+This approach creates a command queue directory, called the
+``jobdir'', in the buildmaster's working directory. The buildmaster
+admin sets the ownership and permissions of this directory to only
+grant write access to the desired set of developers, all of whom must
+have accounts on the machine. The @code{buildbot try} command creates
+a special file containing the source stamp information and drops it in
+the jobdir, just like a standard maildir. When the buildmaster notices
+the new file, it unpacks the information inside and starts the builds.
+
+The config file entries used by 'buildbot try' either specify a local
+queuedir (for which write and mv are used) or a remote one (using scp
+and ssh).
+
+The advantage of this scheme is that it is quite secure, the
+disadvantage is that it requires fiddling outside the buildmaster
+config (to set the permissions on the jobdir correctly). If the
+buildmaster machine happens to also house the VC repository, then it
+can be fairly easy to keep the VC userlist in sync with the
+trial-build userlist. If they are on different machines, this will be
+much more of a hassle. It may also involve granting developer accounts
+on a machine that would not otherwise require them.
 
 To implement this, the buildslave invokes 'ssh -l username host
 buildbot tryserver ARGS', passing the patch contents over stdin. The
 arguments must include the inlet directory and the revision
 information.
 
- at item PB
-each developer gets a username/passwd pair, known to the buildmaster.
-'buildbot try' connects to the slaveport and identifies itself as that
-user, then sends a PB command to force the build (with the
-sourcestamp+diff as arguments). +: don't need a special group or
-filesystem fiddling. -: depending upon the Cred mechanics used, the
-password may be passed in plaintext or plaintext-equivalent. -: the
-username/passwd list must be maintained by the buildmaster admin,
-really you want it to remain equivalent to the VC system's list.
+ at item user+password (PB)
+
+In this approach, each developer gets a username/password pair, which
+are all listed in the buildmaster's configuration file. When the
+developer runs @code{buildbot try}, their machine connects to the
+buildmaster via PB and authenticates themselves using that username
+and password, then sends a PB command to start the trial build.
+
+The advantage of this scheme is that the entire configuration is
+performed inside the buildmaster's config file. The disadvantages are
+that it is less secure (while the ``cred'' authentication system does
+not expose the password in plaintext over the wire, it does not offer
+most of the other security properties that SSH does. In addition, the
+buildmaster admin is responsible for maintaining the username/password
+list, adding and deleting entries as developers come and go.
 
 @end table
 
+
+For example, to set up the ``jobdir'' style of trial build, using a
+command queue directory of @file{MASTERDIR/jobdir} (and assuming that
+all your project developers were members of the @code{developers} unix
+group), you would first create that directory (with @command{mkdir
+MASTERDIR/jobdir; chgrp developers MASTERDIR/jobdir; chmod g+rwx,o-rwx
+MASTERDIR/jobdir}), and then use the following scheduler in the
+buildmaster's config file:
+
+ at example
+from buildbot.scheduler import Try_Jobdir
+s = Try_Jobdir("try1", ["full-linux", "full-netbsd", "full-OSX"],
+               jobdir="jobdir")
+c['schedulers'] = [s]
+ at end example
+
+Note that you must create the jobdir before telling the buildmaster to
+use this configuration, otherwise you will get an error. Also remember
+that the buildmaster must be able to read and write to the jobdir as
+well. Be sure to watch the @xref{Logfiles} as you start using the
+jobdir, to make sure the buildmaster is happy with it.
+
+To use the username/password form of authentication, create a
+ at code{Try_Userpass} instance instead. It takes the same
+ at code{builderNames} argument as the @code{Try_Jobdir} form:
+
+ at example
+from buildbot.scheduler import Try_Userpass
+s = Try_Userpass("try2", ["full-linux", "full-netbsd", "full-OSX"],
+                 userpass=[("alice","pw1"), ("bob", "pw2")] )
+c['schedulers'] = [s]
+ at end example
+
+
 @heading locating the master
 
 The @command{try} command needs to be told how to connect to the



