Basic docs for save_failed_tree plugin

docs/source/index.rst

@@ -31,6 +31,7 @@ Contents
     server_bootstrap
     server_howto
     using_the_koji_build_system
+    plugins
     writing_a_plugin
     writing_koji_code
     content_generators

docs/source/plugins.rst

@@ -0,0 +1,56 @@
+=======
+Plugins
+=======
+
+Following plugins are available in default koji installation.
+
+Runroot
+=======
+
+Plugin for running any command in buildroot.
+
+Save Failed Tree Plugin
+=======================
+
+In some cases developers want to investigate exact environment in which their
+build failed. Reconstructing this environment via mock needn't end with
+exactly same structure (due to builder settings, etc.). In such case this
+plugin can be used to retrieve tarball with complete mock tree.
+
+.. warning::
+  For security reasons, currently all ``/tmp/krb5cc*`` and ``/etc/*.keytab``
+  files are removed from tarball. If we found some other dangerous pieces,
+  they can be added to this blacklist.
+
+Special task method is created for achieving this which is called
+``SaveFailedTree``. This task can be created via CLI:
+``koji save-failed-tree <taskID>``. Additional options are:
+
+.. option:: --full
+
+   directs koji to create tarball with complete tree.
+
+.. option:: --nowait
+
+   exit immediately after creating task
+
+.. option:: --quiet
+
+   don't print any information to output
+
+After task finishes, one can find the tarball on relevant task web page (URL
+will be printed to stdout until ``--quiet`` is used.
+
+Currently plugin allow to save trees only for ``buildArch`` tasks and anybody
+is allowed to create this type of task (and download tarball).
+
+.. warning::
+  Don't forget that this type of task can generate huge amount of data, so use
+  it wisely.
+
+TODO
+----
+ * Make allowed task types configurable on hub
+ * Restricted access (original owner, special permission, ...)
+ * Separate volume/directory on hub
+ * garbage collector + policy for retaining generated tarballs