← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to docs/configuration/options.rst

  • Committer: Mark Atwood
  • Date: 2011-12-15 23:13:18 UTC
  • mfrom: (2465.3.1 rf3)
  • Revision ID: me@mark.atwood.name-20111215231318-mt2y2q4s5ydp79q3
merge lp:~olafvdspek/drizzle/refactor14

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/configuration/options.rst
1
 
=============
2
 
Configuration
3
 
=============
4
 
 
5
 
--------
6
 
Overview
7
 
--------
8
 
 
9
 
Drizzle can draw its configuration from a number of sources, including the
10
 
command line, from configuration files, and from environment variables.
11
 
 
12
 
Support is planned for pluggable configuration sources.
13
 
 
14
 
----------------
15
 
Loading Sequence
16
 
----------------
17
 
 
18
 
Drizzle first reads the command line options dealing with config file
19
 
location. These options may only be given as command line options.
20
 
Then, the config files are parsed, for all options. After that,
21
 
environment variables are processed, and any value given in them will
22
 
override values input from the config files. Finally, values on the command
23
 
line will be processed and any options given here take final precedence.
24
 
 
25
 
----------------
26
 
Format and Rules
27
 
----------------
28
 
 
29
 
Command line options are of the form `--option-name=value`. There are some
30
 
boolean flags, such as `--help` which do not require (nor can accept) an
31
 
option value.  See :ref:`options` for all options that :program:`drizzled`
32
 
supports.
33
 
 
34
 
Environment variables are the same as the command line options, except that
35
 
the variable name is prefixed with *DRIZZLED_*, in all caps and all `.` and
36
 
`-` are turned into underscores. So the option
37
 
`--innodb.buffer_pool_size=10` could be given in the environment variable
38
 
*DRIZZLED_INNODB_BUFFER_POOL_SIZE*
39
 
 
40
 
The config files contain a set of lines of the form `option-name=value`, one
41
 
per line. Due to a bug in Boost.Program_options Boolean values require an argument,
42
 
e.g. `console.enable=true`.
43
 
 
44
 
Config files support section headers such as `[innodb]` with all options
45
 
occuring subsequently being prefixed by the section header. For instance, if
46
 
one were do give:
47
 
 
48
 
.. code-block:: ini
49
 
 
50
 
  [innodb]
51
 
  buffer_pool_size=10M
52
 
  log_file_size=5M
53
 
 
54
 
It would be the same as:
55
 
 
56
 
.. code-block:: ini
57
 
 
58
 
  innodb.buffer_pool_size=10M
59
 
  innodb.log_file_size
60
 
  
 
1
.. program:: drizzled
 
2
 
 
3
.. _configuration_options:
 
4
 
 
5
Options
 
6
=======
 
7
 
 
8
Options configure Drizzle at startup.  When :program:`drizzled`
 
9
starts, it reads option values from three sources in this order:
 
10
 
 
11
#. Default values
 
12
#. :ref:`config_files`
 
13
#. :ref:`command_line_options`
 
14
 
 
15
Values from :ref:`command_line_options` have the highest precedence;
 
16
they override values from :ref:`config_files` which override the defaul
 
17
values.  The default values alone are sufficient to start :program:`drizzled`,
 
18
but since they provide only the most basic configuration, you will certainly
 
19
want to specify other options.
 
20
 
 
21
To see which options are available, run ``drizzled --help``.  You can also
 
22
see which options a plugin provides by running
 
23
``drizzled --plugin-add PLUGIN --help`` where ``PLUGIN`` is the name of any
 
24
plugin.  For example:
 
25
 
 
26
.. code-block:: none
 
27
 
 
28
   $ drizzled --plugin-add query_log --help
 
29
   sbin/drizzled  Ver 2011.08.25.2411 for pc-linux-gnu on i686 (Source distribution (trunk))
 
30
   Copyright (C) 2010-2011 Drizzle Developers, Copyright (C) 2008 Sun Microsystems
 
31
   This software comes with ABSOLUTELY NO WARRANTY. This is free software,
 
32
   and you are welcome to modify and redistribute it under the GPL license
 
33
   
 
34
   ...
 
35
 
 
36
   Options used by query_log:
 
37
     --query-log.file-enabled                      Enable query logging to file
 
38
     --query-log.file arg (=drizzled-queries.log)  Query log file
 
39
     --query-log.threshold-execution-time arg (=0) Threshold for logging slow 
 
40
                                                   queries, in microseconds
 
41
 
 
42
Options listed by ``--help`` can be used as :ref:`command_line_options`.
 
43
To use them in :ref:`config_files`, strip the leading ``--``.
 
44
 
 
45
.. note::
 
46
 
 
47
   Since Drizzle uses many plugins, the available options vary
 
48
   depending on which plugins are loaded.  If you cannnot find a
 
49
   certain option, ensure that the plugin which provides the option is
 
50
   loaded.
 
51
 
 
52
.. _setting_options:
 
53
 
 
54
Setting Options
 
55
---------------
 
56
 
 
57
Options are read from one or more of the following sources.  Each source
 
58
is optional.
 
59
 
 
60
.. _config_files:
 
61
 
 
62
Config Files
 
63
^^^^^^^^^^^^
 
64
 
 
65
Config files contain these types of lines:
 
66
 
 
67
.. code-block:: ini
 
68
 
 
69
   # comment
 
70
   option-name=value
 
71
   plugin-name.plugin-option-name=value
 
72
   [plugin-name]
 
73
   plugin-option-name=value
 
74
 
 
75
Blank lines are allowed, and spaces before and after ``=`` are allowed.
 
76
 
 
77
The second type of line, ``option-name=value``, specifies
 
78
:ref:`drizzled_options` which add and remove plugins and configure
 
79
the kernel.
 
80
 
 
81
The third type of line, ``plugin-name.plugin-option-name=value``,
 
82
specifies an option specific to a plugin.  Drizzle loads many plugins
 
83
by default, so many options use this type.  If plugins have the
 
84
same ``plugin-option-name``, they are distinguished by different
 
85
``plugin-name.`` prefixes.  For example:
 
86
 
 
87
.. code-block:: ini
 
88
 
 
89
   drizzle-protocol.port=4427
 
90
   mysql-protocol.port=3306
 
91
 
 
92
Those options are not the same.  The first sets the Drizzle network
 
93
protocol port, and the second sets the MySQL network protocol port.
 
94
 
 
95
The fourth type of line, ``[plugin-name]``, is a header that specifies
 
96
a plugin name to prefix to all the option names that follow.  The previous
 
97
example is equivalent to this:
 
98
 
 
99
.. code-block:: ini
 
100
 
 
101
   [drizzle-protocol]
 
102
   port=4427
 
103
 
 
104
   [mysql-protocol]
 
105
   port=3306
 
106
 
 
107
Once a header is declared, it remains in affect until another header
 
108
is declared, and the plugin name is prefixed to every option that follows,
 
109
so you cannot override the header plugin name by specifying a different
 
110
plugin name like this:
 
111
 
 
112
.. code-block:: ini
 
113
 
 
114
   [drizzle-protocol]
 
115
   port=4427
 
116
   mysql-protocol.port=3306  # WRONG
 
117
 
 
118
That config file is wrong and it will cause an error when Drizzle starts like
 
119
"unknown option drizzle-protocol.mysql-protocol.port".
 
120
 
 
121
Since the :ref:`drizzled_options` are not part of a plugin, they cannot
 
122
be specified after any header.  Therefore, you should specify all
 
123
:ref:`drizzled_options` at the start of the config file, or in a separate
 
124
config file by using :ref:`multiple_config_files`.
 
125
 
 
126
.. _command_line_options:
 
127
 
 
128
Command Line Options
 
129
^^^^^^^^^^^^^^^^^^^^
 
130
 
 
131
Command line options have the form ``--option-name=value`` (the ``=`` is
 
132
optional).  This form works for both :ref:`drizzled_options` and all
 
133
plugin options.  For example::
 
134
 
 
135
   drizzled --basedir=/opt/drizzle --innodb.buffer-pool-size=500M
 
136
 
 
137
.. _multiple_config_files:
 
138
 
 
139
Multiple Config Files
 
140
---------------------
 
141
 
 
142
The command line option :option:`--defaults-file` specifies one config file,
 
143
but :option:`--config-dir` specifies a directory which can contain multiple
 
144
config files.  If a file named :file:`drizzled.cnf` exists in the config dir,
 
145
it is read first.
 
146
If the config dir contains a directory called :file:`conf.d`, then *every*
 
147
file in that directory is read as a config file.  (Even hidden files are read,
 
148
including hidden temp files created by your editor while editing config files
 
149
in this directory.)
 
150
 
 
151
A good strategy for configuring Drizzle with multiple config files is to
 
152
put general :ref:`drizzled_options` in :file:`/etc/drizzle/drizzled.cnf`
 
153
(:file:`/etc/drizzle` is the default :option:`--config-dir` value)
 
154
and any options related to a plugin in a separate config file in
 
155
:file:`/etc/drizzle/conf.d/`.  For example:
 
156
 
 
157
.. code-block:: bash
 
158
 
 
159
   $ ls /etc/drizzle/*
 
160
   /etc/drizzle/drizzled.cnf
 
161
 
 
162
   /etc/drizzle/conf.d:
 
163
   auth-file
 
164
 
 
165
.. code-block:: bash
 
166
 
 
167
   $ cat /etc/drizzle/drizzled.cnf
 
168
 
 
169
.. code-block:: ini
 
170
 
 
171
   server-id=42
 
172
   core-file
 
173
 
 
174
.. code-block:: bash
 
175
 
 
176
   $ cat /etc/drizzle/conf.d/auth-file
 
177
 
 
178
.. code-block:: ini
 
179
 
 
180
   # drizzled option to load the auth_file plugin
 
181
   plugin-remove=auth_all
 
182
   plugin-add=auth_file
 
183
   
 
184
   # Options for the plugin itself
 
185
   [auth-file]
 
186
   users=/etc/drizzle/users
 
187
 
 
188
.. _boolean_options:
 
189
 
 
190
Boolean Options
 
191
---------------
 
192
 
 
193
Boolean options do not and cannot take values.
 
194
Most boolean options are disabled by default, so specifying them enables them.
 
195
For example, ``--transaction-log.enable`` enable the transaction log because
 
196
it is disabled by default.  However, some options are *enabled* by default,
 
197
so specifying them disables them.  For example, ``--innodb.disable-checksums``
 
198
disables InnoDB checkum validation because it is enabled by default.
 
199