Support for logging to database via grml-live-db. Changed logic of ZERO_LOGFILE to...

[grml-live.git] / docs / grml-live-db.txt

diff --git a/docs/grml-live-db.txt b/docs/grml-live-db.txt
new file mode 100644 (file)
index 0000000..a52e74e
--- /dev/null
+++ b/docs/grml-live-db.txt
@@ -0,0 +1,104 @@
+grml-live-db(8)
+===============
+
+Name
+----
+grml-live-db - log package build information of grml-live to database
+
+Synopsis
+--------
+dpkg-to-db  [ options ] || db-to-fai /path/to/grml-live.db <build-id> |
+
+Introduction
+------------
+
+The grml-live-db Debian package provides a simple way to put build information
+of grml-live into a database. By default you have to do nothing but install
+grml-live-db and during each invocation of grml-live you'll get an additional
+entry in the sqlite3 database /var/log/grml-live.db. If you want to customize
+the database logging check out the following sections in this manpage.
+
+Provided scripts
+----------------
+
+/usr/share/grml-live-db/scripts/dpkg-to-db adds grml-live build information
+(output of 'dpkg --list') and (optionally) a logfile into a sqlite3 database.
+This script is used by default if grml-live-db is installed (no configuration
+needed by default).
+
+/usr/share/grml-live-db/scripts/db-to-fai converts output of grml-live's sqlite
+database for use within FAI. This script is useful if you want to reproduce a
+certain build with specific package versions. Please note that you need the
+according Debian mirrors providing all the specific package versions of course.
+
+Options
+-------
+
+dpkg-to-db supports the following options:
+
+  --help
+
+Brief help message.
+
+  --db <database>
+
+Use specified database file.
+
+  --logfile <logfile>
+
+Logfile thath should be added to the database entry.
+
+  --flavour <flavour>
+
+Name of the grml-live flavour that was being built.
+
+db-to-fai does not support any options but needs to be invoked
+with path to the grml-live database and the build id.
+
+Configuration and using custom database wrapper scripts
+-------------------------------------------------------
+
+The following configuration variables are available and can be adjusted:
+
+  DPKG_DATABASE=/var/log/grml-live.db
+
+Path to the database file that should be used for storing the build information.
+This database is ysed within dpkg-to-db by default.
+
+  DPKG_DBSCRIPT=/usr/share/grml-live-db/scripts/dpkg-to-db
+
+The database wrapper script that's used for storing the build information.
+If you do not want to log to the sqlite3 database but instead use your own
+abstraction layer just point this variable to your favourite script.
+
+  DPKG_DBOPTIONS="-d $DPKG_DATABASE --logfile $LOGFILE --flavour $GRML_NAME < $DPKG_LIST"
+
+If the database script ($DPKG_DBSCRIPT) requires any command line options
+specifiy it through this variable.
+
+Usage Examples
+--------------
+
+How dpkg-to-db is being used inside grml-live:
+
+  /usr/share/grml-live-db/scripts/dpkg-to-db -d /var/log/grml-live.db --logfile /var/log/grml-live.log --flavour $GRML_NAME < /var/log/fai/$HOSTNAME/last/dpkg.list
+
+Manually insert data to database:
+
+  # /usr/share/grml-live-db/scripts/dpkg-to-db -d ./grml-live.db --logfile /tmp/logfile --flavour grml-full < ./dpkg.list
+
+  # dpkg -l | ./dpkg-to-db --db ./grml-live.db --logfile /tmp/logfile --flavour grml-full
+
+Retrieve build information of a specific build for use within FAI:
+
+  # /usr/share/grml-live-db/scripts/db-to-fai /var/log/grml-live.db 6 > /etc/grml/fai/config/package_config/REPRODUCE
+
+Describe schema of database:
+
+  # echo '.schema' | sqlite3 /var/log/grml-live.db
+
+Query database:
+
+  # echo 'SELECT package,version,status,build.flavour,build.identifier FROM packages, build WHERE build.identifier = "grml-full-20091213012517" AND packages.build = build.id ; ' | sqlite3 /var/log/grml-live.db
+
+  # echo 'SELECT package,version,status,build.flavour,build.identifier FROM packages, build WHERE build.id = 7 AND packages.build = build.id ; ' | sqlite3 /var/log/grml-live.db