website/reference/basic/configuration.md

   1 ---
   2 layout: default
   3 title: Configuration Guide
   4 ---
   5
   6 [SSLSecurity]: /mcollective/reference/plugins/security_ssl.html
   7 [AESSecurity]: /mcollective/reference/plugins/security_aes.html
   8 [Registration]: /mcollective/reference/plugins/registration.html
   9 [Auditing]: /mcollective/simplerpc/auditing.html
  10 [Authorization]: /mcollective/simplerpc/authorization.html
  11 [Subcollectives]: /mcollective/reference/basic/subcollectives.html
  12 [server_config]: /mcollective/configure/server.html
  13
  14 > **Note:** There is a new [Server Configuration Reference][server_config] page with a more complete overview of MCollective's server daemon settings. A similar client configuration page is forthcoming.
  15
  16 This guide tells you about the major configuration options in the daemon and client config files.  There are options not mentioned
  17 here typically ones specific to a certain plugin.
  18
  19 ## Configuration Files
  20 There are 2 configuration files, one for the client and one for the server, these default to */etc/mcollective/server.cfg* and */etc/mcollective/client.cfg*.
  21
  22 Configuration is a simple *key = val* style configuration file.
  23
  24 ## Common Options
  25
  26 |Key|Sample|Description|
  27 |---|------|-----------|
  28 |collectives|mcollective,subcollective|A list of [Subcollectives] to join - 1.1.3 and newer only|
  29 |main_collective|mcollective|The main collective to target - 1.1.3 and newer only|
  30 |logfile|/var/log/mcollective.log|Where to log|
  31 |loglevel|debug|Can be info, warn, debug, fatal, error|
  32 |identity|dev1.your.com|Identifier for this node, does not need to be unique, defaults to hostname if unset and must match _/\w\.\-/_ if set|
  33 |keeplogs|5|The amount of logs to keep|
  34 |max_log_size|2097152|Max size in bytes for log files before rotation happens|
  35 |libdir|/usr/libexec/mcollective:/site/mcollective|Where to look for plugins|
  36 |connector|activemq|Which _connector_ plugin to use for communication|
  37 |securityprovider|Psk|Which security model to use, see [SSL Security Plugin][SSLSecurity] and [AES Security Plugin][AESSecurity] for details on others|
  38 |rpchelptemplate|/etc/mcollective/rpc-help.erb|The path to the erb template used for generating help|
  39 |helptemplatedir|/etc/mcollective|The path that contains all the erb templates for generating help|
  40 |logger_type|file|Valid logger types, currently file, syslog or console|
  41 |ssl_cipher|aes-256-cbc|This sets the cipher in use by the SSL code, see _man enc_ for a list supported by OpenSSL|
  42 |direct_addressing|n|Enable or disable directed requests|
  43 |direct_addressing_threshold|10|When direct requests are enabled, send direct messages for less than or equal to this many hosts|
  44 |ttl|60|Sets the default TTL for requests - 1.3.2 and newer only|
  45 |logfacility|When using the syslog logger sets the facility, defaults to user|
  46 |default_discovery_method|The default method to use for discovery - _mc_ by default|
  47 |default_discovery_options|Options to pass to the discovery plugin, empty by default|
  48
  49 ## Server Configuration
  50 The server configuration file should be root only readable
  51
  52 |Key|Sample|Description|
  53 |---|------|-----------|
  54 |daemonize|1|Runs the server in the background|
  55 |factsource|Facter|Which fact plugin to use|
  56 |registration|Agentlist|[Registration] plugin to use|
  57 |registerinterval|120|How many seconds to sleep between registration messages, setting this to zero disables registration|
  58 |registration_collective|development|Which sub-collective to send registration messages to|
  59 |classesfile|/var/lib/puppet/classes.txt|Where to find a list of classes configured by your configuration management system|
  60 |rpcaudit|1|Enables [SimpleRPC Auditing][Auditing]|
  61 |rpcauditprovider|Logfile|Enables auditing using _MCollective::Audit::Logfile_|
  62 |rpcauthorization|1|Enables [SimpleRPC Authorization][Authorization] globally|
  63 |rpcauthprovider|action_policy|Use the _MCollective::Util::ActionPolicy_ plugin to manage authorization|
  64 |rpclimitmethod|The method used for --limit-results.  Can be either _first_ or _random_|
  65 |fact_cache_time|300|How long to cache fact results for before refreshing from source|
  66
  67 The last example sets a option for the _discovery_ plugin, you can also set this in _/etc/mcollective/plugin.d/discovery.cfg_, in that case
  68 you'd just set _timeout=10_ in the file.
  69
  70 ## Client Configuration
  71 The client configuration file should be readable by everyone, it's not advised to put PSK's or client SSL certs in a world readable file, see below how to do that per user.
  72
  73 |Key|Sample|Description|
  74 |---|------|-----------|
  75 |color|0|Disables the use of color in RPC results|
  76
  77 ## Plugin Configuration
  78 You can add free form config options for plugins, they take the general form like:
  79
  80 {% highlight ini %}
  81     plugin.pluginname.option = value
  82 {% endhighlight %}
  83
  84 Each plugin's documentation should tell you what options are availble.
  85
  86 Common plugin options are:
  87
  88 |Key|Sample|Description|
  89 |---|------|-----------|
  90 |plugin.yaml|/etc/mcollective/facts.yaml:/other/facts.yaml|Where the yaml fact source finds facts from, multiples get merged|
  91 |plugin.psk|123456789|The pre-shared key to use for the Psk security provider|
  92 |plugin.psk.callertype|group|What to base the callerid on for the PSK plugin, uid, gid, user, group or identity|
  93
  94 ## Client Setup
  95 It's recommended that you do not set host, user, password and Psk in the client configuration file since these files are generally world readable unlike the server one that should be root readable only.  I just set mine to *unset* so it's clear to someone who looks at the config file that it's not going to work without the settings below.
  96
  97 You can also put client configuration in _~/.mcollective_ as an alternative to the method below, but you will need a full client.cfg then in that location.
  98
  99 You can set various Environment variables per user to supply these values:
 100
 101 {% highlight bash %}
 102 export STOMP_USER=user
 103 export STOMP_PASSWORD=password
 104 export MCOLLECTIVE_PSK=123456789
 105 {% endhighlight %}
 106
 107 You an set options that will always apply using the _MCOLLECTIVE_EXTRA_OPTS_ as below:
 108
 109 {% highlight bash %}
 110 export MCOLLECTIVE_EXTRA_OPTS="--dt 5 --timeout 3 --config /home/you/mcollective.cfg"
 111 {% endhighlight %}
 112
 113 The client library will use these and so you can give each user who use the admin utilities their own username and rights.