1
Obnam configuration files and settings
2
======================================
4
This chapter discusses Obnam configuration files: where they are, what
5
they contain, and how they are used.
7
Where is my configuration?
8
--------------------------
10
Obnam looks for its configuration files in a number of places:
15
* `~/.config/obnam/*.conf`
17
Note that in `/etc/obnam` and `~/.config/obnam`, all files that have a
18
`.conf` suffix are loaded, in "asciibetical" order, which is like
19
alphabetical, but based on character codes rather than what humans
20
understand, but unlike alphabetical isn't dependent on the language
23
Any files in the list above may or may not exist. If it exists, it is
24
read, and then the next file is read. A setting in one file can be
25
overridden by a later file, if it is set there as well.
26
For example, `/etc/obnam.conf` might set `log-level` to `INFO`,
27
but `~/.obnam.conf` may then set it to `DEBUG`, if a user wants more
30
The Obnam configuration files in `/etc` apply to everyone who runs
31
Obnam on that machine. This is important: they are not just for when
34
If you want to have several Obnam configurations, for example for
35
different backup repositories, you need to name or place the files so
36
they aren't on the list above. For example:
38
* `/etc/obnam/system-backup.profile`
39
* `~/.config/obnam/online.profile`
40
* `~/.config/obnam/usbdrive.profile`
42
You would then need to specify that file for Obnam to use it:
44
obnam --config ~/.config/obnam/usbdrive.profile`
46
If you want to not be affected by any configuration files, except
47
the ones you specify explicitly, you need to also use the
48
`--no-default-config` option:
50
obnam --no-default-config --config ~/.obnam-is-fun.conf
52
Command line options override values from configuration files.
54
Configuration file syntax
55
-------------------------
57
Obnam configuration files use the [INI file] syntax, specifically
58
the variant implemented by the Python [ConfigParser] library.
63
log = /var/log/obnam.log
64
encrypt-with = CAFEBEEF
68
[INI file]: https://en.wikipedia.org/wiki/INI_file
69
[ConfigParser]: http://docs.python.org/2/library/configparser.html
71
Names of configuration variables are the same as the corresponding
72
command line options. If `--foo` is the option, then the variable in
73
the file is `foo`. Any command line option `--foo=bar` can be used in
74
a configuration file as `foo = bar`. There's are exceptions to this
75
(`--no-default-config`, `--config`, `--help`, and a few others), but
76
they're all things you wouldn't put in a configuration file anyway.
78
Every option, or setting, has a type. Mostly this doesn't matter,
79
unless you give it a value that isn't suitable. The two important
80
exceptions to this are:
82
* Boolean or yes/no or on/off settings. For example,
83
`--exclude-caches` is a setting that is either turned on (when the
84
option is used) or off (when it's not used). For every Boolean
85
setting `--foo`, there is an option `--no-foo`. In a configuration
86
files, `foo` is turned on by setting it to `yes` or `true`, and off
87
by setting it to `no` or `false`.
89
* Some settings can be lists of values, such as `--exclude`. You can
90
use `--exclude` as many times as you want, each time a new exclusion
91
pattern is added, rather than replacing the previous patterns.
92
In a configuration file, you would write all the values at once,
93
separated by commas and optional spaces: for example,
94
`exclude = foo, bar, baz`. In a configuration file, the previous
95
list of values is replaced entirely rather than added to.
97
For a more detailed explanation of Obnam configuration file syntax,
98
see the **cliapp**(5) manual page on your system, or [cliapp man page]
101
[cliapp man page]: http://liw.fi/cliapp/cliapp.5.txt
103
Checking what my configuration is
104
---------------------------------
106
Obnam can read configuration files from a number of places, and it can
107
be tricky to figure out what the actual configuration is. The
108
`--dump-config` option helps here.
110
obnam --config ~/.obnam.fun --exclude-caches --dump-config
112
The option will tell Obnam to write out (to the standard output) a
113
configuration file that captures every setting, and reporting the
114
value that it would have if `--dump-config` weren't used.
116
This is a good way to see what the current settings are and also as
117
a starting point if you want to make a configuration file from
120
Finding out all the configuration settings
121
------------------------------------------
123
This manual does not yet have a list of all the settings, and their
124
explanation. Obnam provides built-in help (run `obnam --help`) and a
125
manual page automatically generated from the built-in help
126
(run `man obnam` or see [obnam man page]). Some day, this chapter will
127
include an automatically generated section that explains each setting.
128
Until then, you're free to point fingers at Obnam's author and giggle
131
[obnam man page]: http://obnam.org/obnam.1.txt
added
removed
manual/fr/150-config.mdwn
