2 title: "MCollective » Configure » Servers"
7 <!-- TODO Got to change this middleware link as soon as enough of the deploy docs come up. -->
8 [middleware]: /mcollective/deploy/middleware/activemq.html
9 [filters]: /mcollective/reference/ui/filters.html
10 [plugin_directory]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki
11 [facter_plugin]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki/FactsFacter
12 [ohai_plugin]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki/FactsOhai
13 [chef_classfile]: /mcollective/reference/integration/chef.html#class-filters
14 [fact]: #facts-identity-and-classes
15 [connector_plugin]: #connector-settings
16 [subcollectives]: /mcollective/reference/basic/subcollectives.html
17 [registration]: /mcollective/reference/plugins/registration.html
18 [puppetdb]: /puppetdb/
19 [security_plugin]: #security-plugin-settings
20 [auditing]: /mcollective/simplerpc/auditing.html
21 [authorization]: /mcollective/simplerpc/authorization.html
22 [actionpolicy]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki/AuthorizationActionPolicy
23 [security_aes]: /mcollective/reference/plugins/security_aes.html
24 [security_overview]: /mcollective/security.html
25 [ssl_plugin]: /mcollective/reference/plugins/security_ssl.html
26 [activemq_tls_verified]: /mcollective/reference/integration/activemq_ssl.html#ca-verified-tls
27 [activemq_connector]: /mcollective/reference/plugins/connector_activemq.html
28 [rabbitmq_connector]: /mcollective/reference/plugins/connector_rabbitmq.html
29 [stdlib]: http://forge.puppetlabs.com/puppetlabs/stdlib
31 {% capture badbool %}**Note:** Use these exact values only; do not use "true" or "false."{% endcapture %}
33 {% capture pluginname %}**Note:** Capitalization of plugin names doesn't matter; MCollective normalizes it before loading the plugin.{% endcapture %}
35 {% capture path_separator %}system path separator (colon \[`:`\] on \*nix, semicolon \[`;`\] on Windows){% endcapture %}
39 This document describes MCollective server configuration in MCollective 2.0.0 and higher. Older versions may lack certain fetaures.
45 The following is an example MCollective server config file showing all of the major groups of settings. All of the setting names styled as links can be clicked, and will take you down the page to a full description of that setting.
47 [See below the example for a full description of the config file location and format.](#the-server-config-files)
49 <pre><code># /etc/mcollective/server.cfg
51 # <a href="#connector-settings">Connector settings (required):</a>
52 # -----------------------------
54 <a href="#connector">connector</a> = activemq
55 <a href="#directaddressing">direct_addressing</a> = 1
57 # <a href="#activemq-connector-settings">ActiveMQ connector settings:</a>
58 plugin.activemq.pool.size = 1
59 plugin.activemq.pool.1.host = middleware.example.net
60 plugin.activemq.pool.1.port = 61614
61 plugin.activemq.pool.1.user = mcollective
62 plugin.activemq.pool.1.password = secret
63 plugin.activemq.pool.1.ssl = 1
64 plugin.activemq.pool.1.ssl.ca = /var/lib/puppet/ssl/certs/ca.pem
65 plugin.activemq.pool.1.ssl.cert = /var/lib/puppet/ssl/certs/web01.example.com.pem
66 plugin.activemq.pool.1.ssl.key = /var/lib/puppet/ssl/private_keys/web01.example.com.pem
67 plugin.activemq.pool.1.ssl.fallback = 0
69 # <a href="#rabbitmq-connector-settings">RabbitMQ connector settings:</a>
70 plugin.rabbitmq.vhost = /mcollective
71 plugin.rabbitmq.pool.size = 1
72 plugin.rabbitmq.pool.1.host = middleware.example.net
73 # ... etc., similar to activemq settings
75 # <a href="#security-plugin-settings">Security plugin settings (required):</a>
76 # -----------------------------------
78 <a href="#securityprovider">securityprovider</a> = ssl
80 # <a href="#ssl-plugin-settings">SSL plugin settings:</a>
81 plugin.ssl_client_cert_dir = /etc/mcollective.d/clients
82 plugin.ssl_server_private = /etc/mcollective.d/server_private.pem
83 plugin.ssl_server_public = /etc/mcollective.d/server_public.pem
85 # <a href="#psk-plugin-settings">PSK plugin settings:</a>
86 plugin.psk = j9q8kx7fnuied9e
88 # <a href="#facts-identity-and-classes">Facts, identity, and classes (recommended):</a>
89 # ------------------------------------------
91 <a href="#factsource">factsource</a> = yaml
92 <a href="#pluginyaml">plugin.yaml</a> = /etc/mcollective/facts.yaml
93 <a href="#factcachetime">fact_cache_time</a> = 300
95 <a href="#identity">identity</a> = web01.example.com
97 <a href="#classesfile">classesfile</a> = /var/lib/puppet/state/classes.txt
99 # <a href="#subcollectives">Subcollectives (optional):</a>
100 # -------------------------
102 <a href="#collectives">collectives</a> = mcollective,uk_collective
103 <a href="#maincollective">main_collective</a> = mcollective
105 # <a href="#node-registration">Registration (optional):</a>
106 # -----------------------
108 <a href="#registerinterval">registerinterval</a> = 300
109 <a href="#registration">registration</a> = agentlist
110 <a href="#registrationcollective">registration_collective</a> = mcollective
112 # <a href="#auditing">Auditing (optional):</a>
113 # -------------------
115 <a href="#rpcaudit">rpcaudit</a> = 1
116 <a href="#rpcauditprovider">rpcauditprovider</a> = logfile
117 <a href="#pluginrpcauditlogfile">plugin.rpcaudit.logfile</a> = /var/log/mcollective-audit.log
119 # <a href="#authorization">Authorization (optional):</a>
120 # ------------------------
122 <a href="#rpcauthorization">rpcauthorization</a> = 1
123 <a href="#rpcauthprovider">rpcauthprovider</a> = action_policy
125 # <a href="#logging">Logging:</a>
128 <a href="#loggertype">logger_type</a> = file
129 <a href="#loglevel">loglevel</a> = info
130 <a href="#keeplogs">keeplogs</a> = 5
131 <a href="#maxlogsize">max_log_size</a> = 2097152
132 <a href="#logfacility">logfacility</a> = user
134 # <a href="#platform-defaults">Platform defaults:</a>
137 <a href="#daemonize">daemonize</a> = 1
138 <a href="#libdir">libdir</a> = /usr/libexec/mcollective
139 <a href="#sslcipher">ssl_cipher</a> = aes-256-cbc
144 ([↑ Back to top](#content))
151 The Server Config File(s)
156 MCollective servers are configured with the `/etc/mcollective/server.cfg` file. It contains MCollective's core settings, as well as settings for the various plugins.
158 > **Warning:** This file contains sensitive credentials, and should only be readable by the root user, or whatever user the MCollective daemon runs as.
162 Each line consists of a setting, an equals sign, and a value:
167 The spaces on either side of the equals sign are optional. Lines starting with a `#` are comments.
169 > **Note on Boolean Values:** MCollective's config code does not have consistent handling of boolean values. Many of the core settings will accept values of `1/0` and `y/n`, but will fail to handle `true/false`; additionally, each plugin can handle boolean values differently, and some of them do not properly handle the `y/n` values accepted by the core settings.
171 > Nearly all known plugins and core settings accept `1` and `0`. Until further notice, you should always use these for all boolean settings, as no other values are universally safe.
173 ### Plugin Config Directory (Optional)
175 Many of MCollective's settings are named with the format `plugin.<NAME>.<SETTING_NAME>`. These settings can optionally be put in separate files, in the `/etc/mcollective/plugin.d/` directory.
177 To move a plugin setting to an external file, put it in `/etc/mcollective/plugin.d/<NAME>.cfg`, and use only the `<SETTING_NAME>` segment of the setting. So this:
179 # /etc/mcollective/server.cfg
180 plugin.puppet.splay = true
184 # /etc/mcollective/plugin.d/puppet.cfg
187 Note that this doesn't work for settings like `plugin.psk`, since they have no `<SETTING_NAME>` segment; a setting must have at least three segments to go in a plugin.cfg file.
191 You should manage your MCollective servers' config files with config management software (such as Puppet). While most settings in a deployment are the same, several should be different for each server, and managing these differences manually is impractical.
193 If your deployment is fairly simple and there is little division of responsibility (e.g. having one group in charge of MCollective core and another group in charge of several agent plugins), then you can manage the config file with a simple template.
195 If your deployment is large or complex, or you expect it to become so, you should manage MCollective settings as individual resources, as this is the only practical way to divide responsibilities within a single file.
197 Below is an example of how to do this using the `file_line` type from the [puppetlabs/stdlib module][stdlib]:
200 # /etc/puppet/modules/mcollective/manifests/setting.pp
201 define mcollective::setting ($setting = $title, $target = '/etc/mcollective/server.cfg', $value) {
202 validate_re($target, '\/(plugin\.d\/[a-z]+|server)\.cfg\Z')
203 $regex_escaped_setting = regsubst($setting, '\.', '\\.', 'G') # assume dots are the only regex-unsafe chars in a setting name.
205 file_line {"mco_setting_${title}":
207 line => "${setting} = ${value}",
208 match => "^ *${regex_escaped_setting} *=.*$",
212 # /etc/puppet/modules/mcollective_core/manifests/server/connector.pp
214 # Connector settings:
215 mcollective::setting {
220 'plugin.activemq.pool.size':
222 'plugin.activemq.pool.1.host':
223 value => $activemq_server;
224 'plugin.activemq.pool.1.port':
226 'plugin.activemq.pool.1.user':
227 value => $activemq_user;
228 'plugin.activemq.pool.1.password':
229 value => $activemq_password;
230 'plugin.activemq.pool.1.ssl':
232 'plugin.activemq.pool.1.ssl.fallback':
238 ([↑ Back to top](#content))
244 ### Connector Settings
247 <pre><code><a href="#connector">connector</a> = activemq
248 <a href="#directaddressing">direct_addressing</a> = 1
250 # <a href="#activemq-connector-settings">ActiveMQ connector settings:</a>
251 plugin.activemq.pool.size = 1
252 plugin.activemq.pool.1.host = middleware.example.net
253 plugin.activemq.pool.1.port = 61614
254 plugin.activemq.pool.1.user = mcollective
255 plugin.activemq.pool.1.password = secret
256 plugin.activemq.pool.1.ssl = 1
257 plugin.activemq.pool.1.ssl.ca = /var/lib/puppet/ssl/certs/ca.pem
258 plugin.activemq.pool.1.ssl.cert = /var/lib/puppet/ssl/certs/web01.example.com.pem
259 plugin.activemq.pool.1.ssl.key = /var/lib/puppet/ssl/private_keys/web01.example.com.pem
260 plugin.activemq.pool.1.ssl.fallback = 0
262 # <a href="#rabbitmq-connector-settings">RabbitMQ connector settings:</a>
263 plugin.rabbitmq.vhost = /mcollective
264 plugin.rabbitmq.pool.size = 1
265 plugin.rabbitmq.pool.1.host = middleware.example.net
266 plugin.rabbitmq.pool.1.port = 61613
267 # ... etc., similar to activemq settings
272 MCollective always requires a connector plugin. The connector plugin is determined by the [middleware][] you chose for your deployment. Each connector plugin will have additional settings it requires.
274 > #### Shared Configuration
276 > * All servers and clients must use the same connector plugin, and its settings must be configured compatibly.
277 > * You must use the right connector plugin for your [choice of middleware][middleware].
278 > * The hostname and port must match what the middleware is using. The username and password must be valid login accounts on the middleware. If you are using [CA-verified TLS][activemq_tls_verified], the certificate must be signed by the same CA the middleware is using.
282 Which connector plugin to use. This is determined by your [choice of middleware][middleware].
284 - _Default:_ `activemq`
285 - _Allowed values:_ `activemq`, `rabbitmq`, or the name of a third-party connector plugin. {{ pluginname }}
288 #### `direct_addressing`
290 Whether your middleware supports direct point-to-point messages. **This should usually be turned on,** although it is off by default. The built-in `activemq` and `rabbitmq` connectors both support direct addressing, as does the external `redis` connector. (The older `stomp` connector, however, does not.)
293 - _Allowed values:_ `1`, `0`, `y`, `n` --- {{ badbool }}
295 #### ActiveMQ Connector Settings
297 ActiveMQ is the main middleware we recommend for MCollective. The ActiveMQ connector can use multiple servers as a failover pool; if you have only one server, just use a pool size of `1`.
299 > **Note:** This is only a summary of the most commonly used ActiveMQ settings; there are about ten more settings that can be used to tune the connector's performance. [See the ActiveMQ connector documentation][activemq_connector] for more complete details.
301 - **`plugin.activemq.pool.size`** --- How many ActiveMQ servers to attempt to use. _Default:_ (nothing)
302 - **`plugin.activemq.pool.1.host`** --- The hostname of the first ActiveMQ server. (Note that additional servers use the same settings as the first, incrementing the number.) _Default:_ (nothing)
303 - **`plugin.activemq.pool.1.port`** --- The Stomp port of the first ActiveMQ server. _Default:_ `61613` or `6163`, depending on the MCollective version.
304 - **`plugin.activemq.pool.1.user`** --- The ActiveMQ user account to connect as. If the `STOMP_USER` environment variable is set, MCollective will use its value instead of this setting.
305 - **`plugin.activemq.pool.1.password`** --- The password for the user account being used. If the `STOMP_PASSWORD` environment variable is set, MCollective will use its value instead of this setting.
306 - **`plugin.activemq.pool.1.ssl`** --- Whether to use TLS when connecting to ActiveMQ. _Default:_ `0`; _allowed:_ `1/0`, `true/false`, `yes/no`
307 - **`plugin.activemq.pool.1.ssl.fallback`** --- _(When `ssl == 1`)_ Whether to allow unverified TLS if the ca/cert/key settings aren't set. _Default:_ `0`; _allowed:_ `1/0`, `true/false`, `yes/no`
308 - **`plugin.activemq.pool.1.ssl.ca`** --- _(When `ssl == 1`)_ The CA certificate to use when verifying ActiveMQ's certificate. Must be the path to a `.pem` file. _Default:_ (nothing)
309 - **`plugin.activemq.pool.1.ssl.cert`** --- _(When `ssl == 1`)_ The certificate to present when connecting to ActiveMQ. Must be the path to a `.pem` file. _Default:_ (nothing)
310 - **`plugin.activemq.pool.1.ssl.key`** --- _(When `ssl == 1`)_ The private key corresponding to this node's certificate. Must be the path to a `.pem` file. _Default:_ (nothing)
312 #### RabbitMQ Connector Settings
314 The RabbitMQ connector uses very similar settings to the ActiveMQ connector, with the same `.pool.1.host` style of setting names.
316 [See the RabbitMQ connector documentation][rabbitmq_connector] for more complete details.
319 ([↑ Back to top](#content))
322 ### Security Plugin Settings
324 <pre><code><a href="#securityprovider">securityprovider</a> = ssl
326 # <a href="#ssl-plugin-settings">SSL plugin settings:</a>
327 plugin.ssl_client_cert_dir = /etc/mcollective.d/clients
328 plugin.ssl_server_private = /etc/mcollective.d/server_private.pem
329 plugin.ssl_server_public = /etc/mcollective.d/server_public.pem
331 # <a href="#psk-plugin-settings">PSK plugin settings:</a>
332 plugin.psk = j9q8kx7fnuied9e
336 MCollective always requires a security plugin. (Although they're called security plugins, they actually handle more, including message serialization.) Each security plugin will have additional settings it requires.
338 > #### Shared Configuration
340 > All servers and clients must use the same security plugin, and its settings must be configured compatibly.
342 It's possible to write new security plugins, but most people use one of the three included in MCollective:
344 - **SSL:** The best choice for most users. Provides very good security when combined with TLS on the connector plugin (see above).
345 - **PSK:** Poor security, but easy to configure; fine for proof-of-concept deployments.
346 - **AES:** Complex to configure, and carries a noticable performance cost in large networks. Only suitable for certain use cases, like where TLS on the middleware is impossible.
348 For a full-system look at how security works in MCollective, see [Security Overview][security_overview].
351 #### `securityprovider`
353 Which security plugin to use.
356 - _Allowed values:_ `ssl`, `psk`, `aes_security`, or the name of a third-party security plugin. {{ pluginname }}
358 #### SSL Plugin Settings
360 > **Note:** This security plugin requires you to manage and distribute SSL credentials. [See the SSL security plugin page][ssl_plugin] for full details. In summary:
362 > * All servers share **one** "server" keypair. They must all have a copy of the public key and private key.
363 > * Every admin user must have a copy of the server public key.
364 > * Every admin user has their own "client" keypair.
365 > * Every server must have a copy of **every** authorized client public key.
367 All of these settings have **no default,** and must be set for the SSL plugin to work.
369 - **`plugin.ssl_server_private`** --- The path to the server private key file, which must be in `.pem` format.
370 - **`plugin.ssl_server_public`** --- The path to the server public key file, which must be in `.pem` format.
371 - **`plugin.ssl_client_cert_dir`** --- A directory containing every authorized client public key.
374 #### PSK Plugin Settings
376 > **Note:** The only credential used by this plugin is a single shared password, which all servers and admin users have a copy of.
378 - **`plugin.psk`** --- The shared passphrase. If the `MCOLLECTIVE_PSK` environment variable is set, MCollective will use its value instead of this setting.
381 ([↑ Back to top](#content))
384 Facts, Identity, and Classes
387 <pre><code><a href="#factsource">factsource</a> = yaml
388 <a href="#pluginyaml">plugin.yaml</a> = /etc/mcollective/facts.yaml
389 <a href="#factcachetime">fact_cache_time</a> = 300
391 <a href="#identity">identity</a> = web01.example.com
393 <a href="#classesfile">classesfile</a> = /var/lib/puppet/state/classes.txt
397 MCollective clients use filters to discover nodes and limit commands. (See [Discovery Filters][filters] for more details.) These filters can use a variety of per-server metadata, including **facts, identity,** and **classes.**
399 * **Facts:** A collection of key/value data about a server's hardware and software. (E.g. `memorytotal = 8.00 GB`, `kernel = Darwin`, etc.)
400 * **Identity:** The name of the node.
401 * **Classes:** The Puppet classes (or Chef cookbooks, etc.) applied to this node. Classes are useful as metadata because they describe what _roles_ a server fills at your site.
403 None of these settings are mandatory, but MCollective is less useful without them.
407 The node's name or identity. This **should** be unique for each node, but does not **need** to be.
409 - _Default:_ The value of Ruby's `Socket.gethostname` method, which is usually the server's FQDN.
410 - _Sample value:_ `web01.example.com`
411 - _Allowed values:_ Any string containing only alphanumeric characters, hyphens, and dots --- i.e. matching the regular expression `/\A[\w\.\-]+\Z/`
415 A file with a list of classes applied by your configuration management system. This should be a plain text file containing one class name per line.
417 Puppet automatically writes a class file, which can be found by running `sudo puppet apply --configprint classfile`. [Chef can be made to write a class file][chef_classfile].
419 - _Default:_ `/var/lib/puppet/state/classes.txt`
424 Which fact plugin to use.
426 MCollective includes a fact plugin called `yaml`. Most users should use this default, set [the `plugin.yaml` setting (see below)](#pluginyaml), and arrange to fill the file it relies on.
428 Other fact plugins (including [Facter][facter_plugin] and [Ohai][ohai_plugin] ones) are available in the [plugin directory][plugin_directory]. These may require settings of their own.
431 - _Allowed values:_ The name of any installed fact plugin, with the `_facts` suffix trimmed off. {{ pluginname }}
435 _When `factsource == yaml`_
437 The fact file(s) to load for [the default `yaml` fact plugin](#factsource).
439 - _Default:_ (nothing)
440 - _Sample value:_ `/etc/mcollective/facts.yaml`
441 - _Valid values:_ A single path, or a list of paths separated by the {{ path_separator }}.
445 The default `yaml` fact plugin reads cached facts from a file, which should be a simple YAML hash. If multiple files are specified, they will be merged. (Later files override prior ones if there are conflicting values.)
447 **The user is responsible for populating the fact file;** by default it is empty, and MCollective has no facts.
449 If you are using Puppet and Facter, you can populate it by putting something like the following in your puppet master's `/etc/puppet/manifests/site.pp`, outside any node definition:
452 # /etc/puppet/manifests/site.pp
453 file{"/etc/mcollective/facts.yaml":
457 loglevel => debug, # reduce noise in Puppet reports
458 content => inline_template("<%= scope.to_hash.reject { |k,v| k.to_s =~ /(uptime_seconds|timestamp|free)/ }.to_yaml %>"), # exclude rapidly changing facts
462 #### `fact_cache_time`
464 How long (in seconds) to cache fact results before refreshing from source. This can be ignored unless you're using a non-default `factsource`.
468 ([↑ Back to top](#content))
476 <pre><code><a href="#collectives">collectives</a> = mcollective,uk_collective
477 <a href="#maincollective">main_collective</a> = mcollective
481 Subcollectives provide an alternate way of dividing up the servers in a deployment. They are mostly useful because the middleware can be made aware of them, which enables traffic flow and access restrictions. In multi-datacenter deployments, this can save bandwidth costs and give some extra security.
483 * [See the Subcollectives and Partitioning page][subcollectives] for more details and an example of site partitioning.
485 Subcollective membership is managed **on the server side,** by each server's config file. A given server can join any number of collectives, and will respond to commands from any of them.
487 > #### Shared Configuration
489 > If you are using any additional collectives (besides the default `mcollective` collective), your middleware must be configured to permit traffic on those collectives. See the middleware deployment guide for your specific middleware to see how to do this:
491 > * ActiveMQ: [Subcollective topic/queue names](/mcollective/deploy/middleware/activemq.html#topic-and-queue-names) --- [Multi-subcollective authorization example](/mcollective/deploy/middleware/activemq.html#detailed-restrictions-with-multiple-subcollectives)
496 A comma-separated list (spaces OK) of [subcollectives][] this server should join.
498 - _Default:_ `mcollective`
499 - _Sample value:_ `mcollective,uk_collective`
501 #### `main_collective`
503 The main collective for this server. Currently, this is only used as the default value for the [`registration_collective`](#registrationcollective) setting.
505 - _Default:_ (the first value of [the `collectives` setting](#collectives), usually `mcollective`)
508 ([↑ Back to top](#content))
511 ### Node Registration
513 <pre><code><a href="#registerinterval">registerinterval</a> = 300
514 <a href="#registration">registration</a> = agentlist
515 <a href="#registrationcollective">registration_collective</a> = mcollective
519 By default, registration is disabled, due to [`registerinterval`](#registerinterval) being set to 0.
521 Optionally, MCollective servers can [send periodic heartbeat messages][registration] containing some inventory information. This can provide a central inventory at sites that don't already use something like [PuppetDB][], and can also be used as a simple passive monitoring system.
523 The default registration plugin, `agentlist`, sends a standard SimpleRPC command over the MCollective middleware, to be processed by some server with an agent called `registration` installed. You would need to ensure that the `registration` agent is extremely performant (due to the volume of message it will receive) and installed on a limited number of servers. If your [middleware][] supports detailed permissions, you must also ensure that it allows servers to send commands to the registration agent ([ActiveMQ instructions](/mcollective/deploy/middleware/activemq.html#detailed-restrictions)).
525 Some registration plugins (e.g. `redis`) can insert data directly into the inventory instead of sending an RPC message. This is a flexible system, and the user is in charge of deciding what to build with it, if anything. If all you need is a searchable inventory, [PuppetDB][] is probably closer to your needs.
527 #### `registerinterval`
529 How long (in seconds) to wait between registration messages. Setting this to 0 disables registration.
535 The [registration plugin][registration] to use.
537 This plugin must be installed on the server sending the message, and will dictate what the message contains. The default `agentlist` plugin will only send a list of the installed agents. See [Registration Plugins][registration] for more details.
539 - _Default:_ `agentlist`
540 - _Allowed values:_ The name of any installed registration plugin. {{ pluginname }}
542 #### `registration_collective`
544 Which subcollective to send registration messages to, when using a SimpleRPC-based registration plugin.
546 - _Default:_ (the value of [`main_collective`](#maincollective), usually `mcollective`)
549 ([↑ Back to top](#content))
554 <pre><code><a href="#rpcaudit">rpcaudit</a> = 1
555 <a href="#rpcauditprovider">rpcauditprovider</a> = logfile
556 <a href="#pluginrpcauditlogfile">plugin.rpcaudit.logfile</a> = /var/log/mcollective-audit.log
560 Optionally, MCollective can log the SimpleRPC agent commands it receives from admin users, recording both the command itself and some identifying information about the user who issued it. The caller ID of a command is determined by the [security plugin][security_plugin] being used.
562 MCollective ships with a local logging audit plugin, called `Logfile`, which saves audit info to a local file (different from the daemon log file). Log lines look like this:
564 2010-12-28T17:09:03.889113+0000: reqid=319719cc475f57fda3f734136a31e19b: reqtime=1293556143 caller=cert=nagios@monitor1 agent=nrpe action=runcommand data={:process_results=>true, :command=>"check_mailq"}
566 Tthere are central loggers available from [the plugin directory][plugin_directory], and you can also write your own audit plugins; see [Writing Auditing Plugins][auditing] for more information.
571 Whether to enable [SimpleRPC auditing][Auditing] for all SimpleRPC agent commands.
574 - _Allowed values:_ `1`, `0`, `y`, `n` --- {{ badbool }}
576 #### `rpcauditprovider`
578 The name of the audit plugin to use whenever SimpleRPC commands are received.
580 - _Default:_ (nothing)
581 - _Sample value:_ `logfile`
582 - _Allowed values:_ The name of any installed audit plugin. {{ pluginname }}
585 #### `plugin.rpcaudit.logfile`
587 _When `rpcauditprovider == logfile`_
589 The file to write to when using the `logfile` audit plugin. **Note:** this file is not automatically rotated.
591 - _Default:_ `/var/log/mcollective-audit.log`
594 ([↑ Back to top](#content))
599 <pre><code><a href="#rpcauthorization">rpcauthorization</a> = 1
600 <a href="#rpcauthprovider">rpcauthprovider</a> = action_policy
604 Optionally, MCollective can refuse to execute agent commands unless they meet some requirement. The exact requirement is defined by an [authorization plugin][authorization].
606 See [SimpleRPC Authorization][authorization] for more details, including how to enable authorization for only certain agents.
608 The [actionpolicy][] plugin, which is provided in the [plugin directory][plugin_directory], is fairly popular and seems to meet many users' needs, when combined with a [security plugin][security_plugin] that provides a verified caller ID (such as the SSL plugin). [See its documentation][actionpolicy] for details.
610 #### `rpcauthorization`
612 Whether to enable [SimpleRPC authorization][Authorization] globally.
615 - _Allowed values:_ `1`, `0`, `y`, `n` --- {{ badbool }}
617 #### `rpcauthprovider`
619 The plugin to use when globally managing authorization. See [SimpleRPC Authorization][authorization] for more details.
621 - _Default:_ (nothing)
622 - _Sample value:_ `action_policy`
623 - _Allowed values:_ The name of any installed authorization plugin. This uses different capitalization/formatting rules from the other plugin settings: if the name of the plugin (in the code) has any interior capital letters (e.g. `ActionPolicy`), you should use a lowercase value for the setting but insert an underscore before the place where the interior capital letter(s) would have gone (e.g. `action_policy`). If the name contains no interior capital letters, simply use a lowercase value with no other changes.
626 ([↑ Back to top](#content))
634 <pre><code><a href="#loggertype">logger_type</a> = file
635 <a href="#loglevel">loglevel</a> = info
636 <a href="#logfile">logfile</a> = /var/log/mcollective.log
637 <a href="#keeplogs">keeplogs</a> = 5
638 <a href="#maxlogsize">max_log_size</a> = 2097152
639 <a href="#logfacility">logfacility</a> = user
643 The MCollective server daemon can log to its own log file (which it will automatically rotate), or to the syslog. It can also log directly to the console, if you are running it in the foreground instead of daemonized.
645 Some of the settings below only apply if you are using log files, and some only apply if you are using syslog.
649 How the MCollective server daemon should log. You generally want to use a file or syslog.
652 - _Allowed values:_ `file`, `syslog`, `console`
656 How verbosely to log.
659 - _Allowed values:_ In increasing order of verbosity: `fatal`, `error` , `warn`, `info`, `debug`
663 _When `logger_type == file`_
665 Where the log file should be stored.
667 - _Default:_ (nothing; the package's default config file usually sets a platform-appropriate value)
668 - _Sample value:_ `/var/log/mcollective.log`
672 _When `logger_type == file`_
674 The number of log files to keep when rotating.
680 _When `logger_type == file`_
682 Max size in bytes for log files before rotation happens.
684 - _Default:_ `2097152`
688 _When `logger_type == syslog`_
690 The syslog facility to use.
695 ([↑ Back to top](#content))
698 ### Platform Defaults
700 <pre><code><a href="#daemonize">daemonize</a> = 1
701 <a href="#libdir">libdir</a> = /usr/libexec/mcollective
702 <a href="#sslcipher">ssl_cipher</a> = aes-256-cbc
706 These settings generally shouldn't be changed by the user, but their values may vary by platform. The package you used to install MCollective should have created a config file with platform-appropriate values for these settings.
710 Whether to fork and run the MCollective server daemon in the background.
712 This depends on your platform's init system. For example, newer Ubuntu releases require this to be false, while RHEL-derived systems require it to be true.
714 - _Default:_ `0` <!-- Actually nil but acts like false -->
715 - _Allowed values:_ `1`, `0`, `y`, `n` --- {{ badbool }}
719 Where to look for plugins. Should be a single path or a list of paths separated by the {{ path_separator }}.
721 By default, this setting is blank, but the package you installed MCollective with should supply a default server.cfg file with a platform-appropriate value for this setting. **If server.cfg has no value for this setting, MCollective will not work.**
723 - _Default:_ (nothing; the package's default config file usually sets a platform-appropriate value)
724 - _Sample value:_ `/usr/libexec/mcollective:/opt/mcollective`
728 The cipher to use for encryption. This is currently only relevant if you are using the [AES security plugin][security_aes].
730 This setting should be a standard OpenSSL cipher string. See `man enc` for a list.
732 - _Default:_ `aes-256-cbc`