foreman_hooks 0.3.13 → 0.3.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 40ce82d00a918185af3f0e75063311cdca9c7ecb
-  data.tar.gz: ba63e860d91d252f31fc231a6ca16ca9f63129ca
+  metadata.gz: 2f2bdeb9f5b1cfff753640427f732d376599f824
+  data.tar.gz: d181ec7e648ff2c7631c2d39c69628bcd2f4e362
 SHA512:
-  metadata.gz: 6740120f31efa77b71e218bade83661697dc9aba205444f2bc04f48864d13f0b159fe74f77c76cb44c5c46228bb890f0db4997bb49969a75d9dc983c60dded52
-  data.tar.gz: 2a94de8cf7102c8a20c4b6ec79734a4856736ada300160dcf6793254a399cc56c9dd435a50d0256c0e39c2627e3d08a993274617c37b130c5123938ea106f0cd
+  metadata.gz: a10e596c30229296c2b8e90f5c6023f227cec98763b45ca956247131027722c26eaa3716636853322d41ae96e91732c9afae5f0fafe0a353cccc8ccb32ece938
+  data.tar.gz: 1a9c5966288d7d7f2e02277bf31e6d32cecc00cb128a697adb1c1eb09ce54e9ecb1e323eaf9abf71cacee9faa336bd338781f16a9d7198aa849dee759526b9b6

data/README.md

@@ -17,7 +17,8 @@ Please see the Foreman wiki for appropriate instructions:
 The gem name is "foreman_hooks".
 
 RPM users can install the "tfm-rubygem-foreman_hooks" or
-"rubygem-foreman_hooks" packages.
+"rubygem-foreman_hooks" packages. Debian/Ubuntu users can install the
+"ruby-foreman-hooks" package.
 
 # Usage
 
@@ -31,7 +32,11 @@ Examples:
     ~foreman/config/hooks/host/managed/create/50_register_system.sh
     ~foreman/config/hooks/host/managed/destroy/15_cleanup_database.sh
     ~foreman/config/hooks/smart_proxy/after_create/01_email_operations.sh
-    ~foreman/config/hooks/audited/adapters/active_record/audit/after_create/01_syslog.sh
+    ~foreman/config/hooks/audited/audit/after_create/01_syslog.sh
+
+After adding or removing hooks, restart the Foreman server to update the list
+of known hooks (usually `apache2` or `httpd` when using Passenger, or
+`touch ~foreman/tmp/restart.txt`).
 
 ## Objects / Models
 
@@ -147,6 +152,54 @@ to rollback its action - in this case the first argument will change as
 appropriate, so must be obeyed by the script (e.g. a "create" hook will be
 called with "destroy" if it has to be rolled back later).
 
+## Logging
+
+Entries are logged at application startup and during execution of hooks, but
+most will be at 'debug' level and may use the 'sql' logger. Enable this in
+Foreman's `/etc/foreman/settings.yaml`:
+
+```yaml
+:logging:
+  :level: debug
+:loggers:
+  :sql:
+    :enabled: true
+```
+
+See [Foreman manual: Debugging](https://theforeman.org/manuals/latest/index.html#7.2Debugging)
+for full details.
+
+Enabling debugging and searching the Foreman log file (`/var/log/foreman/production.log`)
+for the word "hook" will find all relevant log entries.
+
+### Hook discovery and setup
+
+Expect to see these entries when the server starts:
+
+* `Found hook to Host::Managed#create, filename 01_example` - for each
+  executable hook script in the correct location
+* `Finished discovering 3 hooks for Host::Managed#create` - for each unique
+  event with hook scripts
+* `Extending Host::Managed with foreman_hooks orchestration hooking support` -
+  if any orchestration (create/update/destroy) hooks exist for that object
+* `Extending Host::Managed with foreman_hooks Rails hooking support` - if any
+  Rails events hooks exist for that object
+* `Created hook method after_create on Host::Managed` - for each type of Rails
+  event that has hooks
+
+### Running hooks
+
+Expect to see these entries logged when a hooked action occurs:
+
+* `Observed after_create hook on test.example.com` when a registered Rails
+  event occurs, hook will then execute immediately
+* `Queuing 3 hooks for Host::Managed#create` when an orchestration action is
+  being set up (hook will be executed later during orchestration)
+* `Queuing hook 01_example for Host::Managed#create at priority 01` for each
+  hook registered when setting up an orchestration action
+* `Running hook: /example/config/hooks/host/managed/create/01_example create test.example.com`
+  as the hook (orchestration or Rails event) is executed
+
 ## Transactions
 
 Most hooks are triggered during database transaction. This can cause
@@ -169,6 +222,7 @@ tools when writing scripts.
 
 # More resources
 
+* [foreman\_hooks issue tracker](https://github.com/theforeman/foreman_hooks/issues)
 * [Extending Foreman quickly with hook scripts](http://m0dlx.com/blog/Extending_Foreman_quickly_with_hook_scripts.html)
 * [AWS VPC Buildout With Foreman Hooks for RDNS Creation](http://www.brian2.net/posts/foreman_hooks_aws_vpc/)
 * [Foreman <-> FreeIPA Integration Guide](https://bitbin.de/blog/2013/11/foreman-freeipa-integration-guide/)
@@ -176,7 +230,7 @@ tools when writing scripts.
 
 # Copyright
 
-Copyright (c) 2012-2013 Red Hat Inc.
+Copyright (c) 2012-2017 Dominic Cleal
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by

data/examples/python/functions.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+#######
+# To allow this module to be imported by other triggers
+# execute the commands below:
+# $ mkdir -p /usr/share/foreman-community/hooks
+# $ touch /usr/share/foreman-community/hooks/__init__.py
+# $ cp functions.py /usr/share/foreman-community/hooks/
+########
+import json
+import sys
+import tempfile
+
+HOOK_TEMP_DIR = "/usr/share/foreman/tmp"
+
+# HOOK_EVENT = update, create, before_destroy etc.
+# HOOK_OBJECT = to_s representation of the object, e.g. host's fqdn
+HOOK_EVENT, HOOK_OBJECT = (sys.argv[1], sys.argv[2])
+
+
+def get_json_hook():
+    '''
+        Create JSON object to be imported by hook/trigger
+        Saves the data received via stdin to file.
+        It does not require to save to a file, but it may be useful
+        to troubleshooting.
+    '''
+
+    with tempfile.NamedTemporaryFile(
+            dir=HOOK_TEMP_DIR,
+            # set to False for troubleshooting
+            delete=True,
+            prefix="foreman_hooks.") as hook:
+
+        json_hook = sys.stdin.read()
+        hook.file.write(json_hook)
+        hook.file.flush()
+    return json.loads(json_hook)

data/examples/python/host/managed/create/10-logger.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python
+import sys
+import tempfile
+import subprocess
+
+sys.path.append('/usr/share/foreman-community/hooks')
+
+from functions import \
+  (HOOK_EVENT, HOOK_OBJECT, HOOK_TEMP_DIR, get_json_hook)
+
+PREFIX = "created_by_hook-{}".format(sys.argv[0].split('/')[-1])
+
+HOOK_JSON = get_json_hook()
+
+cmd = ['logger']
+
+# read the information received
+if HOOK_JSON.get('host'):
+    hostname = HOOK_JSON.get('host').get('name', None)
+    if hostname:
+        cmd.append('System:{0}'.format(hostname))
+
+    mac_address = HOOK_JSON.get('host').get('mac', None)
+    if mac_address:
+        cmd.append('MAC:{0}'.format(mac_address))
+
+    operating_system = HOOK_JSON.get('host').get('operatingsystem_name', None)
+    if operating_system:
+        cmd.append('OS:{0}'.format(operating_system))
+
+# execute logger command
+subprocess.call(cmd)
+
+# for troubleshooting purposes, you can save the received data to a file
+# to parse the information to be used on the trigger.
+# To accomplish it, set the variable dumpdata to True
+dumpdata = False
+if dumpdata:
+    with tempfile.NamedTemporaryFile(dir=HOOK_TEMP_DIR,
+                                     delete=False,
+                                     prefix=PREFIX) as fd:
+        fd.file.write("HOOK_OBJECT: %s\n" % HOOK_OBJECT)
+        fd.file.write("HOOK_EVENT:  %s\n" % HOOK_EVENT)
+        fd.file.write("HOOK_JSON:   %s\n" % HOOK_JSON)
+
+        # local variables
+        fd.file.write("hostname:    %s\n" % hostname)
+        fd.file.write("mac_address: %s\n" % mac_address)
+        fd.file.write("os:          %s\n" % operating_system)
+        fd.file.flush()
+
+sys.exit(0)

data/lib/foreman_hooks.rb

@@ -1,6 +1,7 @@
 module ForemanHooks
   require 'foreman_hooks/engine'
   require 'foreman_hooks/util'
+  require 'foreman_hooks/as_dependencies_hook'
   require 'foreman_hooks/callback_hooks'
   require 'foreman_hooks/orchestration_hook'
 
@@ -83,17 +84,3 @@ module ForemanHooks
     def logger; Rails.logger; end
   end
 end
-
-module ActiveSupport::Dependencies
-  class << self
-    def load_missing_constant_with_hooks(from_mod, constant_name)
-      ret = load_missing_constant_without_hooks(from_mod, constant_name)
-      ForemanHooks.hooks.each do |klass,events|
-        ForemanHooks.attach_hook(ret, events) if ret.name == klass
-      end
-      ret
-    end
-
-    alias_method_chain :load_missing_constant, :hooks
-  end
-end

data/lib/foreman_hooks/as_dependencies_hook.rb

@@ -0,0 +1,13 @@
+module ForemanHooks
+  module ASDependenciesHook
+    def load_missing_constant(from_mod, constant_name)
+      super(from_mod, constant_name).tap do |ret|
+        ForemanHooks.hooks.each do |klass,events|
+          ForemanHooks.attach_hook(ret, events) if ret.name == klass
+        end
+      end
+    end
+  end
+
+  ActiveSupport::Dependencies.singleton_class.send(:prepend, ASDependenciesHook)
+end

data/lib/foreman_hooks/engine.rb

@@ -2,6 +2,8 @@ require 'foreman_hooks'
 
 module ForemanHooks
   class Engine < ::Rails::Engine
+    engine_name 'foreman_hooks'
+
     config.to_prepare do
       ForemanHooks.hooks.each do |klass,events|
         begin

data/lib/foreman_hooks/orchestration_hook.rb

@@ -27,7 +27,7 @@ module ForemanHooks::OrchestrationHook
     end
 
     return unless hooks = ForemanHooks.find_hooks(self.class, event)
-    logger.debug "Queueing #{hooks.size} hooks for #{self.class.to_s}##{event}"
+    logger.debug "Queuing #{hooks.size} hooks for #{self.class.to_s}##{event}"
 
     counter = 0
     hooks.each do |filename|

data/lib/foreman_hooks/util.rb

@@ -20,7 +20,8 @@ module ForemanHooks::Util
     # APIv2 has some pretty good templates.  We could extend them later in special cases.
     # Wrap them in a root node for pre-1.4 compatibility
     view_path = ActionController::Base.view_paths.collect(&:to_path)
-    json = Rabl.render(self, "api/v2/#{render_hook_type.tableize}/show", :view_path => view_path, :format => :json)
+    json = Rabl.render(self, "api/v2/#{render_hook_type.tableize}/show",
+                       view_path: view_path, format: :json, scope: RablScope.new)
     %Q|{"#{render_hook_type}":#{json}}|
   rescue => e
     logger.warn "Unable to render #{self} (#{self.class}) using RABL: #{e.message}"
@@ -29,6 +30,11 @@ module ForemanHooks::Util
   end
 
   def exec_hook(*args)
+    unless File.executable?(args.first)
+      logger.warn("Hook #{args.first} no longer exists or isn't executable, so skipping execution of the hook. The server should be restarted after adding or removing hooks.")
+      return true
+    end
+
     logger.debug "Running hook: #{args.join(' ')}"
     success, output = if defined? Bundler && Bundler.responds_to(:with_clean_env)
                         Bundler.with_clean_env { exec_hook_int(render_hook_json, *args) }
@@ -60,4 +66,17 @@ module ForemanHooks::Util
     logger.debug "Hook output: #{output}" if output && !output.empty?
     [status.success?, output]
   end
+
+  class RablScope
+    def initialize
+      # Used by api/v2/hosts/main.json.yaml to include parameter lists
+      @all_parameters = true
+      @parameters = true
+    end
+
+    def params
+      # Used by app/views/api/v2/common/show_hidden.json.rabl to show hidden parameter values (#17653)
+      { 'show_hidden' => true, 'show_hidden_parameters' => true }
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: foreman_hooks
 version: !ruby/object:Gem::Version
-  version: 0.3.13
+  version: 0.3.14
 platform: ruby
 authors:
 - Dominic Cleal
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-16 00:00:00.000000000 Z
+date: 2017-05-17 00:00:00.000000000 Z
 dependencies: []
 description: Plugin engine for Foreman that enables running custom hook scripts on
   Foreman events
@@ -24,10 +24,13 @@ files:
 - README.md
 - Rakefile
 - TODO
-- examples/hook_functions.sh
-- examples/log.sh
+- examples/bash/hook_functions.sh
+- examples/bash/log.sh
+- examples/python/functions.py
+- examples/python/host/managed/create/10-logger.py
 - extra/foreman-debug.sh
 - lib/foreman_hooks.rb
+- lib/foreman_hooks/as_dependencies_hook.rb
 - lib/foreman_hooks/callback_hooks.rb
 - lib/foreman_hooks/engine.rb
 - lib/foreman_hooks/orchestration_hook.rb
@@ -55,7 +58,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.8
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 4
 summary: Run custom hook scripts on Foreman events