# Configuration

Obbench configuration is split into two: a benchmark specification
file in YAML, and a user- and site-specific configuration. The former
specifies the benchmarks to run, and the latter where state and
results should be put on the local machine.


## Benchmark specification YAML file

The benchmark specification file uses [YAML][] as the syntax. The top
level object is an "associative array", corresponding to a Perl
hashmap, a Python dict, or more generally a set of key/value pairs.

[YAML]: https://en.wikipedia.org/wiki/YAML

An example:

    EXAMPLE benchmark specification file
    git: /home/liw/obnam/obnam
    obnam_config:
      repository-format: green-albatross
    benchmarks:
      - name: many_files
        description: backup many small files
        steps:
          - live: genbackupdata . --create=10 --file-size=1
            obnam: backup
            reference: 31
          - obnam: restore
            reference: 32
          - obnam: backup

The top level keys are:

key           |type         |description
--------------|-------------|------
`git`         |URL          |location of Obnam git repository
`obnam_config`|dict         |Obnam configuration variables
`benchmarks`  |list of dicts|actual benchmark specifications

There are no default values, so for example the git URL to the Obnam
repository needs to specified every time.

The Obnam configuration variables are as specified by Obnam itself.
Any configuration variables may be used. Note that obbench itself
provides the following settings for Obnam: `quiet`, `repository`,
`root`, and `log`. The benchmark specification should probably not
override those.

The benchmark have the following key/value pairs.

key          |type         |description
-------------|-------------|-----------
`name`       |symbol       |name of the benchmark
`description`|text         |description of the benchmark
`steps`      |list of dicts|list of steps in the benchmark

The steps can use the following keys:

key    |type      |description
-------|----------|-----------
`live` |shell     |modify live data for step
`obnam`|subcommand|Obnam subcommand to run

Every step optionally modifies the live data to be backed up. This is
done by running an arbitrary shell command. Additionally, an Obnam
subcommand can be run on the live data. Currently, the supported
subcommands are `backup` and `restore`. Arbitrary Obnam subcommands
are not supported.

## Local configuration

FIXME. This needs to be implemented and documented.