website/simplerpc/auditing.md

   1 ---
   2 layout: default
   3 title: SimpleRPC Auditing
   4 toc: false
   5 ---
   6 [SimpleRPCIntroduction]: index.html
   7 [AuditCentralRPCLog]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki/AuditCentralRPC
   8
   9 # {{page.title}}
  10
  11 As part of the [SimpleRPC][SimpleRPCIntroduction] framework we've added an auditing system that you can use to log all requests received into a file or even send it over mcollective to a central auditing system.  What actually happens with audit data is pluggable and you can provide your own plugins to do what you need.
  12
  13 The clients will include the _uid_ of the process running the client library in the requests and the audit function will have access to that on the requests.
  14
  15 ## Configuration
  16 To enable logging you should set an option to enable it and also one to configure which plugin to use:
  17
  18 {% highlight ini %}
  19 rpcaudit = 1
  20 rpcauditprovider = Logfile
  21 {% endhighlight %}
  22
  23 This sets it up to use _MCollective::Audit::Logfile_ plugin for logging evens.
  24
  25 The client will embed a caller id - the Unix UID of the program running it or SSL cert - in requests which you can find in the _request_ object.
  26
  27 ## Logfile plugin
  28
  29 Auditing is implemented using plugins that you should install in the normal plugin directory under _mcollective/audit/_.  We have a sample Logfile plugin that you can see below:
  30
  31 {% highlight ruby %}
  32 module MCollective
  33     module RPC
  34         class Logfile<Audit
  35             require 'pp'
  36
  37             def audit_request(request, connection)
  38                 logfile = Config.instance.pluginconf["rpcaudit.logfile"] || "/var/log/mcollective-audit.log"
  39
  40                 now = Time.now
  41                 now_tz = tz = now.utc? ? "Z" : now.strftime("%z")
  42                 now_iso8601 = "%s.%06d%s" % [now.strftime("%Y-%m-%dT%H:%M:%S"), now.tv_usec, now_tz]
  43
  44                 File.open(logfile, "w") do |f|
  45                     f.puts("#{now_iso8601}: reqid=#{request.uniqid}: reqtime=#{request.time} caller=#{request.caller}@#{request.sender} agent=#{request.agent} action=#{request.action} data=#{request.data.pretty_print_inspect}")
  46                 end
  47             end
  48         end
  49     end
  50 end
  51 {% endhighlight %}
  52
  53 As you can see you only need to provide one method called _audit_request_, you will get the request in the form of an _MCollective::RPC::Request_ object as well as the connection to the middleware should you wish to send logs to a central host.
  54
  55 The Logfile plugin takes a configuration option:
  56
  57 {% highlight ini %}
  58 plugin.rpcaudit.logfile = /var/log/mcollective-audit.log
  59 {% endhighlight %}
  60
  61 We do not do log rotation of this file so you should do that yourself if you enable this plugin.
  62
  63 This log lines like:
  64
  65 {% highlight ruby %}
  66 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"}
  67 {% endhighlight %}
  68
  69 Other plugins can be found on the community site like [a centralized logging plugin][AuditCentralRPCLog].