[Piuparts-commits] rev 280 - in trunk: . debian

Holger Levsen holger at alioth.debian.org
Wed Mar 18 02:37:05 UTC 2009


Author: holger
Date: 2009-03-18 02:37:05 +0000 (Wed, 18 Mar 2009)
New Revision: 280

Added:
   trunk/README.txt
   trunk/debian/compat
   trunk/debian/piuparts.docs
Removed:
   trunk/README
   trunk/custom-scripts.txt
   trunk/how-to-use-piuparts.txt
Modified:
   trunk/Makefile
   trunk/TODO
   trunk/debian/changelog
   trunk/debian/rules
Log:
unversioned and add build-dependencies for debhelper and asciidoc.
* Merge README, how-to-use-piuparts.txt and custom-scripts.txt into 
README.txt and build pdf and html versions of it.

Modified: trunk/Makefile
===================================================================
--- trunk/Makefile	2009-03-18 02:01:57 UTC (rev 279)
+++ trunk/Makefile	2009-03-18 02:37:05 UTC (rev 280)
@@ -16,10 +16,13 @@
 
 ignore = -I fdmount -N
 
-all: piuparts.1 install-conf install-py
+all: piuparts-doc install-conf install-py
 
-piuparts.1: piuparts.docbook
+piuparts-doc:
 	docbook2x-man --encoding=utf-8 piuparts.docbook
+	asciidoc -a toc -a toclevels=3 README.txt
+	a2x -a toc -a toclevels=3 -f pdf README.txt
+	rm README.xml
 
 install-conf:
 	install -d $(etcdir)/piuparts
@@ -56,4 +59,4 @@
 	python unittests.py
 
 clean:
-	rm -rf piuparts.1 piuparts
+	rm -rf piuparts.1 piuparts README.pdf README.html 

Deleted: trunk/README

Copied: trunk/README.txt (from rev 244, trunk/README)
===================================================================
--- trunk/README.txt	                        (rev 0)
+++ trunk/README.txt	2009-03-18 02:37:05 UTC (rev 280)
@@ -0,0 +1,471 @@
+piuparts README
+---------------
+
+Author: Lars Wirzenius 
+Email: <liw at iki.fi>
+
+
+Introduction
+~~~~~~~~~~~~
+
+                This is a tool for testing that .deb packages can be
+                installed, upgraded, and removed without problems. The
+                name, a variant of something suggested by Tollef Fog
+                Heen, is short for "package installation, upgrading, and
+                removal testing suite".
+                
+                See the manual page for more information about using
+                the program.
+                
+                You need at least Python 2.3 and debootstrap. The
+                version of debootstrap in the Debian 3.1 release
+                (codename sarge) is too old.
+                
+                piuparts is licensed under the GNU General Public
+                License, version 2.
+                
+
+Distrubuted testing
+~~~~~~~~~~~~~~~~~~~
+
+                As part of the quality assurance effort of Debian, I run
+                piuparts on the Debian package archive. This requires a
+                lot of processing power, and so the work is distributed
+                over several hosts.
+
+                There is one central machine, the master, and any number
+                of slave machines. Each slave machine connects to the
+                master, via ssh, and runs the piuparts-master program to
+                report results of packages it has tested already, and to
+                get more work.
+                
+                To set this up for yourself, the following steps should
+                suffice:
+                
+                 1. Pick a machine to run the master. It cannot be a chroot,
+                    but a etch system is good enough.
+                 2. Install piuparts on it.
+                 3. Create an account for the master.
+                 4. Configure /etc/piuparts/piuparts-master.conf 
+                    appropriately.
+                 
+                 5. Pick one or more slaves to run the slave. You can use
+                    the machine running the master also as a slave. Etch is
+		    fine, it can even be in a chroot.
+                 6. Install piuparts on it.
+                 7. Configure /etc/piuparts/piuparts-slave.conf
+                    appropriately.
+                 8. Create an account for the slave. This must be different
+                    from the master account.
+                 9. Create an ssh keypair for the slave. No passphrase.
+                10. Add the slave's public key to the master's 
+                    .ssh/authorized_keys
+		11. Configure sudo on the slave machine to allow the slave
+		    account run /usr/sbin/piuparts as root without password
+		    (otherwise you'll be typing in a password all the time).
+
+                12. Run /usr/share/piuparts/piuparts-slave.py on the slave
+		    accounts. Packages that are installed want to use
+		    /dev/tty, so you can't do this from cron. Also, you'll
+		    want to keep an eye on what is happening, to catch
+		    runaway processes and stuff.
+
+                13. The logs go into the master account, into
+                    subdirectories.
+
+                Please note that running piuparts this way is somewhat
+                risky, to say the least. There are security implications
+                that you want to consider. It's best to do it on
+                machines that you don't mind wiping clean at a moment's
+                notice, and preferably so that they don't have direct
+                network access.
+
+
+Distributed piuparts testing protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                
+                The slave machine and the piuparts-master program
+                communicate using a simplistic line based protocol. Ssh
+                takes care of authentication, so there is nothing in the
+                protocol for that. The protocol is transaction based:
+                the slave gives a command, the master program responds.
+                Commands and responses can be simple (a single line) or
+                long (a status line plus additional data lines). Simple
+                commands and responses are of the following format:
+                
+                    keyword arg1 arg2 arg3 ... argN
+                    
+                The keyword is a command or status code ("ok"), and it
+                and the arguments are separated by spaces. An argument
+                may not contain a space.
+                
+                A long command or response is deduced from the context:
+                certain commands always include additional data, and
+                certain commands always get a long response, if
+                successful (error responses are always simple). The
+                first line of a long command or response is the same as
+                for a simple one, the additional lines are prefixed with
+                a space, and followed by a line containing only a
+                period.
+                
+                A sample session (">>" indicates what the slave sends,
+                "<<" what the master responds with):
+                
+                    << hello
+                    >> pass liwc 1.2.3-4
+                    >>  The piuparts
+                    >>  log file comes
+                    >>  here
+                    >> .
+                    << ok
+                    >> reserve
+                    << ok vorbisgain 2.3-4
+                
+                Here the slave first reports a successful test of
+                package liwc, version 1.2.3-4, and sends the piuparts
+                log file for it. Then it reserves a new package to test
+                and the master gives it vorbisgain, version 2.3-4.
+                
+                The communication always starts with the master saying
+                "hello". The slave shall not speak until the master has
+                spoken.
+                
+                Commands and responses in this protocol:
+                
+                    Command: reserve
+                    Success: ok <packagename> <packageversion>
+                    Failure: error
+                    
+                        Slave asks master to reserve a package (a
+                        particular version of it) for the slave to test.
+                        The slave may reserve any number of packages to
+                        test. If the transaction fails, there are no
+                        more packages to test, and the slave should
+                        disconnect, wait some time and try again.
+                    
+                    Command: unreserve <packagename> <packageversion>
+                    Success: ok
+                    
+                        Slave informs master it cannot test the desired
+                        version of a package (perhaps it went away from
+                        the mirror?).
+                
+                    Command: pass <packagename> <packageversion>
+                              log file contents
+                             .
+                    Success: ok
+                    
+                        Slave reports that it has tested a particular
+                        version of a package and that the package passed
+                        all tests. Master records this and stores the
+                        log file somewhere suitable.
+                        
+                    Command: fail <packagename> <packageversion>
+                              log file contents
+                             .
+                    Success: ok
+                    
+                        Same as "pass", but package failed one or more tests.
+                        
+                    Command: untestable <packagename> <packageversion>
+                              log file contents
+                             .
+                    Success: ok
+                    
+                        Slave reports that a particular package is
+                        untestable, possibly because it insists on
+                        interacting with the user.
+                        
+                In all cases, if the master cannot respond with "ok"
+                (e.g., because of a disk error storing a log file), it
+                aborts and the connection fails. The slave may only
+                assume the command has succeeded if the master responds
+                with "ok".
+                
+                The master may likewise abort, without an error message,
+                if the slave sends garbage, or sends too much data.
+
+
+Master configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+                piuparts-master uses the configuration file
+                /etc/piuparts/piuparts-master.conf. The syntax is defined
+                by the Python ConfigParser class, and is, briefly, like
+                this:
+                
+                    [master]
+                    foo = bar
+                    
+		where "master" is the name of a section.  By default,
+		piuparts-master.py uses the "master" section in the master
+		configuration file, but you can tell it to use another
+		section by giving the name of that section as an argument.
+		"foo" is the name of a configuration item, and "bar" is the
+		value.  If a section other than "master" is used, all the
+		piuparts logs for that section are kept in a subdirectory by
+		the name of the section.
+                
+                The following configuration items are defined for the master:
+                
+                * "log-file" is the name of a file to where the master should
+                  write its log messages. In the default configuration file
+                  it is "/dev/null", that is, log messages are not put in a
+                  file.
+
+                * "packages-url" is a URL to the Packages.bz2 file for your
+                  mirror. It is usually best to use the Packages.bz2 for
+                  sid (unstable), unless you know what you're doing. For
+                  example, you might use
+                  
+                      http://ftp.debian.org/debian/dists/sid/main/
+                      binary-i386/Packages.bz2
+          
+                  (all on one line, of course), but you really do want
+                  to replace "ftp.debian.org" with the name of your local
+                  mirror.
+
+                Both configuration items must be in the configuration file,
+                or master will refuse to run.
+
+
+Slave configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+                piuparts-slave uses the configuration file
+                /etc/piuparts/piuparts-slave.conf. It has the same
+                general syntax as the master's configuration file. The
+		default section is called "slave" (again, you can use a
+		different section by specifying it on the command-line) and
+		the configuration items are as follows:
+                
+                * "idle-sleep" is the length of time the slave should wait
+                  before querying the master again if the master didn't have
+                  any new packages to test. In seconds, so a value of 300
+                  would mean five minutes, and that seems to be a good
+                  value when there are fairly few slaves per master.
+                  
+                * "master-host" is the host where the master exists. The
+                  slave will give this host to ssh.
+                  
+                * "master-user" is the username of the master. The slave will
+                  log in using this username.
+                
+                * "master-directory" is the directory where the master keeps
+                  its files. Can be relative to the master's home directory.
+                  
+                * "master-command" is the command to run on master-host to
+                  start the master. When the master has been installed from
+                  the Debian package, the command is 
+		  "python /usr/share/piuparts/piuparts-master.py".  If you
+		  want to use a section in the master configuration file
+		  other than "master", append the section name to this
+		  command.  For example, if the master configuration file has
+		  a "sid-ia64" section that you want to use, the command
+		  should be
+		  "python /usr/share/piuparts/piuparts-master.py sid-ia64".
+                  
+                * "mirror" tells the slave which mirror it is to use. The
+                  slave gives this to piuparts when it runs it.
+                  
+                * "piuparts-cmd" is the command the slave uses to start
+                  piuparts. It should include "sudo" if necessary so that
+                  piuparts runs with sufficient priviledges to do its testing
+                  (and that means root priviledges).
+                  
+                * "distro" is the distribution the slave should tell piuparts
+                  to use for basic install/purge testing.
+                  
+                * "chroot-tgz" is the name of the file the slave should
+                  use for the tarball to keep the chroot for the basic
+                  install/purge testing. If the tarball doesn't exist, the
+                  slave creates it.
+
+                * "upgrade-test-distros" is the space delimited list of
+                  distributions the slave should use for testing upgrades
+                  between distributions (i.e., Debian versions). Currently,
+		  "etch lenny sid" is a good choice.  Make this empty if you
+		  do not want to run upgrade tests.
+
+                * "upgrade-test-chroot-tgz" is the name of the file the slave
+                  should use for the tarball to keep the chroot for the
+                  first distribution in upgrade-test-distros. If the file
+                  does not exist, the slave creates it.
+
+                * "max-reserved" is the maximum number of packages the
+                  slave will reserve at once. It should be large enough
+                  that the host that runs master is not unduly stressed by
+                  frequent ssh logins and running master (both of which
+                  take quite a bit of CPU cycles), yet at the same time it
+                  should not be so large that one slave grabs so many
+                  packages all other slaves just sit idle. The number
+                  obviously depends on the speed of the slave. A good
+                  value seems to be enough to let the slave test packages
+                  for about an hour before reporting results and reserving
+                  more. For a contemporary AMD64 machine with a reasonably
+                  fast disk subsystem the value 50 seems to work fine.
+
+		* "keep-sources-list" controls whether the slave runs
+		  piuparts with the "--keep-sources-list" option.  This
+		  option does not apply to upgrade tests.  The value should
+		  be "yes" or "no", with the default being "no".  Use this
+		  option for dists that you need a custom sources.list for,
+		  such as "stable-proposed-updates".
+
+                * "debug" tells the slave whether to log debug level
+                  messages. The value should be "yes" or "no", with the
+                  default being "no".
+
+                Some of the configuration items are not required, but it
+                is best to set them all to be sure what the configuration
+                actually is.
+
+How to use piuparts in 5 minutes
+--------------------------------
+
+* Basic Usage
+~~~~~~~~~~~~~
+
+Testing your packages with piuparts is as easy as typing at the console prompt:
+
+    # piuparts sm_0.6-1_i386.deb
+
+Note that in order to work, piuparts has to be executed as user root, so you 
+need to be logged as root or use sudo.
+
+This will create a sid chroot with debootstrap, where it'll test your package.
+
+If you want to test your package in another release, for example, lenny, you can
+do so with:
+
+    # piuparts sm_0.6-1_i386.deb -d lenny
+
+By default, this will read the first mirror from your /etc/apt/sources.list 
+file. If you want to specify a different mirror you can do it with the option 
+-m:
+
+    # piuparts sm_0.6-1_i386.deb -m http://ftp.de.debian.org/debian
+
+
+* Some tips
+~~~~~~~~~~~
+
+If you use piuparts on a regular basis, waiting for it to create a chroot every 
+time takes too much time, even if you are using a local mirror or a caching tool 
+such as approx. 
+
+Piuparts has the option of using a tarball as the contents of the initial chroot, 
+instead of building a new one with debootstrap. A easy way to use this option 
+is use a tarball created with pbuilder. If you are not a pbuilder user, you can 
+create this tarball with the command (again, as root):
+
+    # puilder create
+ 
+then you only have to remember to update this tarball with:
+
+    #  pbuilder update.
+
+To run piuparts using this tarball:
+
+    # piuparts -p sm_0.6-1_i386.deb
+
+If you want to use your own pre-made tarball:
+
+    # piuparts --basetgz=/path/to/my/tarball.tgz sm_0.6-1_i386.deb
+
+Piuparts also has the option of using a tarball as the contents of the initial
+chroot, instead of building a new one with pbuilder. You can save a tarball
+for later use with the -s (--save) piuparts option. Some people like this, 
+others prefer to only have to maintain one tarball. Read the piuparts manpage 
+about the -p, -b and -s options
+
+
+* Piuparts tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, piuparts does two tests:
+1 - Installation and purging test.
+2 - Installation, upgrade and purging tests.
+
+The first test installs the package in a minimal chroot, removes it and purges
+it. The second test installs the current version in the archive of the given 
+packages, then upgrades to the new version (deb files given to piuparts in the
+input), removes and purges.
+
+If you only want to perfom the first test, you can use the option: 
+--no-upgrade-test  
+
+
+* Analyzing piuparts results
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When piuparts finishes all the tests satisfactorily, you will get these lines
+as final output:
+
+    0m39.5s INFO: PASS: All tests.
+    0m39.5s INFO: piuparts run ends.
+
+Anyway, it is a good idea to read the whole log in order to discover possible 
+problems that did not stop the piuparts execution.
+
+If you do not get those lines, piuparts has failed during a test. The latest 
+lines should give you a pointer to the problem with your package.
+
+Custom scripts with piuparts
+------------------------------
+
+You can specify several custom scripts to be run inside piuparts.
+You have to store them in a directory and give it as argument to
+piuparts: --scriptsdir=/dir/with/the/scripts
+
+The scripts can be run:
+
+    Before *installing* your package. The name of the script must
+    start with:
+    pre_install_
+
+    After *installing* your package and its deps. In the case of the 
+    upgrade test, it is after install and upgrade. The name of the 
+    script must start with:
+    post_install_
+
+    After *removing* your package, The name of the script must start with:
+    post_remove_
+
+    After *purging* your package, The name of the script must start with:
+    post_purge_
+
+    Before *upgrading* your package, once the current version in the archive
+    has been installed (this is done in the second test, "Installation, 
+    upgrade and purging test"). The name of the script must start with:
+    pre_upgrade_
+
+    Before upgrading the chroot to another distro and after upgrading:
+    pre_distupgrade_
+    post_distupgrade_
+
+You can run several scripts in every step, they are run in alphabetical 
+order.
+
+The scripts are run *inside* the piuparts chroot and only can be shell 
+scripts, if you want to run Python or Perl scripts, you have to install 
+Python or Perl. The chroot where piuparts is run is minized and does not 
+include Perl.
+
+
+It would be interesting to declare some piuparts variables like the name
+of the current testing packages, and be able to use this variable in the 
+custom scripts. But this option is not available yet.
+
+Example script:
+
+'$cat post_install_number.sh'
+----
+#!/bin/bash
+
+number=`dpkg -l | wc -l`
+echo "There are $number packages installed."
+exit 0
+----
+
+


Property changes on: trunk/README.txt
___________________________________________________________________
Name: svn:mergeinfo
   + 

Modified: trunk/TODO
===================================================================
--- trunk/TODO	2009-03-18 02:01:57 UTC (rev 279)
+++ trunk/TODO	2009-03-18 02:37:05 UTC (rev 280)
@@ -6,15 +6,13 @@
 - document sections for piuparts-slave in README. 
 - the templates used by update-reports.py should be taken from /etc/piuparts/templates/
   and not be included in the python source
-- merge how-to-use-piuparts.txt custom-scripts.txt README and piuparts.docbook
-  into one asciidoc document.
 - the sections in the index page generated by piuparts-report.py are hardcoded atm..
   (fix by merging configfiles, also sections should have 
    desctription="Debian sid, consisting of main contrib non-free, testing installation and removal in sid"
-- use debhelper to build the package
 - rename packages.txt into $section_done_today.txt and include sections
 - create $section_packages.txt with into about all packages 
 - better header (link to FAQ, point out to read the bottom first..) for piuparts-logs
+- debug is on, even though its off in the config
 
 nice for 0.36
 

Deleted: trunk/custom-scripts.txt

Modified: trunk/debian/changelog
===================================================================
--- trunk/debian/changelog	2009-03-18 02:01:57 UTC (rev 279)
+++ trunk/debian/changelog	2009-03-18 02:37:05 UTC (rev 280)
@@ -36,8 +36,10 @@
     - improve look.
   * Makefile: add "~$date" to versionstring if building an unreleased version.
   * debian/control: depend on python (>>2.4), make dependency to python-debian
-    unversioned and add one for debhelper.
+    unversioned and add build-dependencies for debhelper and asciidoc.
   * Rewrite debian/rules using debhelper.
+  * Merge README, how-to-use-piuparts.txt and custom-scripts.txt into 
+    README.txt and build pdf and html versions of it.
 
  -- Holger Levsen <holger at debian.org>  Tue, 10 Mar 2009 15:23:59 +0100
 

Added: trunk/debian/compat
===================================================================
--- trunk/debian/compat	                        (rev 0)
+++ trunk/debian/compat	2009-03-18 02:37:05 UTC (rev 280)
@@ -0,0 +1 @@
+5

Added: trunk/debian/piuparts.docs
===================================================================
--- trunk/debian/piuparts.docs	                        (rev 0)
+++ trunk/debian/piuparts.docs	2009-03-18 02:37:05 UTC (rev 280)
@@ -0,0 +1,3 @@
+README.txt
+README.html
+README.pdf

Modified: trunk/debian/rules
===================================================================
--- trunk/debian/rules	2009-03-18 02:01:57 UTC (rev 279)
+++ trunk/debian/rules	2009-03-18 02:37:05 UTC (rev 280)
@@ -3,7 +3,6 @@
 # Uncomment this to turn on verbose mode. 
 #export DH_VERBOSE=1
 
-
 build:
 
 clean:

Deleted: trunk/how-to-use-piuparts.txt




More information about the Piuparts-commits mailing list