foreman_hooks 0.3.12 → 0.3.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e36bbbb7ffec26b6250bc5b073bea7b8237539b1
-  data.tar.gz: 31d5746a12a9d454044e11d32c52350f616b2dd4
+SHA256:
+  metadata.gz: ada8bb38440801209fabcb38b2bea702e6364f0e9cdd0bb8e074060b3c46450a
+  data.tar.gz: ca37f997197dde8d000ce21d4ebd0bb938803cb7a3ff46dd2a8ee335634e396a
 SHA512:
-  metadata.gz: 96726288631740a784979242e476053d5fa9b3e2007af35e428b7a12c6fa52bae7b40c98b556c1ebd22c3dcbc9af58d611ea151d86fc28debdb10f5038e28db4
-  data.tar.gz: a7d8dda6643da1d5e38d5fcb750410bc24ad0e775d0a1f86f677fc2b8f0699cadf4b00fe91752807a51568c8ac004d75cf58caee2d6545f209e498cb79b9f25a
+  metadata.gz: 9da94d17eff07e19d3f02014a007f01aa5d33e113417eae10f3fcfb01edb7bb90a6d9e6f5f59ac7a8547b26b4aa1b875c7f02b4cac98c426dd44aaa47519f7dc
+  data.tar.gz: b97ee982a4ac00618bad1a832e48c69981bdbbafaaa806b97f1d891fcbfbb644ee04377696a77fa146eaf3935c41e0b0054eba3dae321352e951b93ae8de475a

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
 
@@ -54,6 +59,11 @@ and to get events for a listed object (e.g. `host/managed`):
 
 ## Orchestration events
 
+_Only supported on these objects:_
+
+* _host/managed_
+* _nic/\*_
+
 Foreman supports orchestration tasks for hosts and NICs (each network
 interface) which happen when the object is created, updated and destroyed.
 These tasks are shown to the user in the UI and if they fail, will
@@ -61,18 +71,38 @@ automatically trigger a rollback of the action. A rollback is performed as
 an opposite action (e.g. for DHCP record creation a rollback action is
 destroy).
 
-To add hooks to these, use these event names:
+The following hooks are executed during `around_save` Rails callback:
 
 * `create`
 * `update`
+
+The following hooks are executed during `on_destroy` Rails callback:
+
 * `destroy`
 
-Orchestration hooks can be given a priority (see below), therefore it is
-possible to order them before or after built-in orchestration steps (before
-DNS record is created for example).
+The following hooks are executed during `after_commit` Rails callback:
+
+* `postcreate`
+* `postupdate`
+
+The major difference between `create` and `postcreate` (or update respectively) is how late the hook is called during save operation. In the former case when a hook fails it starts rollback and operation can be still cancelled. In the latter case object was already saved and there is no way of cancelling the operation, but all referenced data should be properly loaded. The advice is to use the latter hooks as they will likely contain all the required data (e.g. nested parameters).
+
+Orchestration hooks can be given a priority by prefixing the filename with the
+priority number, therefore it is possible to order them before or after
+built-in orchestration steps (before DNS records are created for example).
+Existing common priority levels are:
+
+* _2_: Set up compute instance (create VM)
+* _10_: Create DNS record
+* _10_: Create DHCP reservation
+* _20_: Deploy TFTP configs
+* _50_: Create realm entry
+* _1000_: Power up compute instance
 
 ## Rails events
 
+_Supported on all object types._
+
 For hooks on anything apart from hosts or NICs (which support orchestration,
 as above) then the standard Rails events will be needed. These are the most
 interesting events provided:
@@ -111,6 +141,12 @@ may want to ensure stdin is closed to prevent pipe buffer from filling.
       | ~foreman/config/hooks/host/managed/create/50_register_system.sh \
            create foo.example.com
 
+Some arguments are available as environment variables:
+
+Variable | Description
+-------- | -----------
+FOREMAN_HOOKS_USER | Username of Foreman user
+
 Every hook within the event directory is executed in alphabetical order.  For
 orchestration hooks, an integer prefix in the hook filename will be used as
 the priority value, so influences where it's done in relation to DNS, DHCP, VM
@@ -132,6 +168,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
@@ -154,6 +238,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/)
@@ -161,7 +246,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/extra/foreman-debug.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# This file provides additional debug information for foreman-debug tool and is
+# symlinked as /usr/share/foreman/script/foreman-debug.d/50-foreman_hooks
+
+add_cmd "find /usr/share/foreman/config/hooks/ -type f -executable" "foreman_hooks_list"

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'
 
@@ -67,7 +68,7 @@ module ForemanHooks
     end
 
     def attach_hook(klass, events)
-      if events.keys.detect { |event| ['create', 'update', 'destroy'].include? event }
+      if events.keys.detect { |event| ['create', 'update', 'destroy', 'postcreate', 'postupdate'].include? event }
         unless klass.ancestors.include?(ForemanHooks::OrchestrationHook)
           logger.debug "Extending #{klass} with foreman_hooks orchestration hooking support"
           klass.send(:include, ForemanHooks::OrchestrationHook)
@@ -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,14 @@
+module ForemanHooks
+  module ASDependenciesHook
+    def load_missing_constant(from_mod, constant_name)
+      super(from_mod, constant_name).tap do |ret|
+        return ret unless ret.try(:name)
+        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/callback_hooks.rb

@@ -10,7 +10,11 @@ module ForemanHooks::CallbackHooks
       next unless name
 
       Rails.logger.debug("Created hook method #{event} on #{self}")
-      set_callback name.to_sym, filter.to_sym, "#{event}_hooks".to_sym
+      if "#{event}" == "before_destroy"
+        set_callback name.to_sym, filter.to_sym, "#{event}_hooks".to_sym, prepend: true
+      else
+        set_callback name.to_sym, filter.to_sym, "#{event}_hooks".to_sym
+      end
       define_method("#{event}_hooks") do
         Rails.logger.debug "Observed #{event} hook on #{self}"
         return unless hooks = ForemanHooks.find_hooks(self.class, event)

data/lib/foreman_hooks/engine.rb

@@ -2,8 +2,18 @@ require 'foreman_hooks'
 
 module ForemanHooks
   class Engine < ::Rails::Engine
+    engine_name 'foreman_hooks'
+
     config.to_prepare do
-      ForemanHooks.hooks.each { |klass,events| ForemanHooks.attach_hook(klass.constantize, events) }
+      ForemanHooks.hooks.each do |klass,events|
+        begin
+          klass_const = klass.constantize
+        rescue NameError => e
+          ForemanHooks.logger.error "foreman_hooks: unknown hook object #{klass}, check against `foreman-rake hooks:objects`"
+          next
+        end
+        ForemanHooks.attach_hook(klass_const, events)
+      end
     end
 
     initializer 'foreman_hooks.register_plugin', :before => :finisher_hook do |app|

data/lib/foreman_hooks/orchestration_hook.rb

@@ -12,6 +12,7 @@ module ForemanHooks::OrchestrationHook
   def queue_hooks_validate
     return unless errors.empty?
     queue_hooks(new_record? ? 'create' : 'update')
+    queue_hooks(new_record? ? 'postcreate' : 'postupdate')
   end
 
   def queue_hooks_destroy
@@ -22,20 +23,21 @@ module ForemanHooks::OrchestrationHook
   def queue_hooks(event)
     logger.debug "Observed #{event} hook on #{self}"
     unless is_a? Orchestration
-      logger.warn "#{self.class.to_s} doesn't support orchestration, can't run orchestration hooks: use Rails events instead"
+      logger.error "#{self.class.to_s} doesn't support orchestration, can't run orchestration hooks: use Rails events instead"
+      return
     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|
       basename = File.basename(filename)
       priority = basename =~ /^(\d+)/ ? $1 : 10000 + (counter += 1)
-      logger.debug "Queuing hook #{basename} for #{self.class.to_s}##{event} at priority #{priority}"
-      queue.create(:name   => "Hook: #{basename}", :priority => priority.to_i,
-                   :action => [HookRunner.new(filename, self, event.to_s),
-                               event.to_s == 'destroy' ? :hook_execute_del : :hook_execute_set])
+      logger.debug "Queuing hook #{filename} for #{self.class.to_s}##{event} at priority #{priority}"
+      queue_to_use = (event =~ /^post/) ? post_queue : queue
+      queue_to_use.create(:name => "Hook: #{filename}", :priority => priority.to_i,
+        :action => [HookRunner.new(filename, self, event.to_s), event.to_s == 'destroy' ? :hook_execute_del : :hook_execute_set])
     end
   end
 
@@ -53,7 +55,7 @@ module ForemanHooks::OrchestrationHook
     end
 
     def hook_execute_set
-      @obj.exec_hook(@filename, @event == 'destroy' ? 'create' : @event, *args)
+      @obj.exec_hook(@filename, @event, *args)
     end
 
     def hook_execute_del

data/lib/foreman_hooks/util.rb

@@ -9,18 +9,23 @@ module ForemanHooks::Util
         'host'
       when "Host::Discovered"
         'discovered_host'
-      when "Audited::Adapters::ActiveRecord::Audit"
+      when "Audited::Adapters::ActiveRecord::Audit", "Audited::Audit"
         'audit'
       else
         self.class.name.downcase
     end
   end
 
+  def rabl_path
+    "api/v2/#{render_hook_type.tableize}/show"
+  end
+
   def render_hook_json
     # 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, rabl_path,
+                       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 +34,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) }
@@ -41,6 +51,10 @@ module ForemanHooks::Util
   end
 
   def exec_hook_int(stdin_data, *args)
+    # Set environment vars available in hook scripts
+    # Name of active Foreman user:
+    ENV['FOREMAN_HOOKS_USER'] = User.current.login
+
     args.map!(&:to_s)
     output, status = if Open3.respond_to? :capture2e
       Open3.capture2e(*args.push(:stdin_data => stdin_data))
@@ -60,4 +74,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

data/lib/tasks/hooks.rake

@@ -1,7 +1,15 @@
 namespace :hooks do
   desc 'Print a list of object names that can be hooked'
   task :objects => :environment do
-    puts ActiveRecord::Base.descendants.collect(&:name).collect(&:underscore).sort
+    Rails.application.config.eager_load_namespaces.each(&:eager_load!)
+
+    # Gather the models
+    models = ActiveRecord::Base.descendants.collect(&:name).collect(&:underscore)
+
+    # filter out known models not hookable
+    models.reject! {|e| e.start_with?('habtm')}
+
+    puts models.sort
   end
 
   desc 'Print a list of event names for a given object, e.g. hooks:events[host/managed]'
@@ -12,8 +20,18 @@ namespace :hooks do
               fail("Unknown model #{args[:object]}, run hooks:objects to get a list (#{e.message})")
             end
 
+    # 1. List default ActiveRecord callbacks
     events = ActiveRecord::Callbacks::CALLBACKS.map(&:to_s).reject { |e| e.start_with?('around_') }
-    events.concat(['create', 'destroy', 'update']) if model.included_modules.include?(Orchestration)
+
+    # 2. List Foreman orchestration callbacks
+    events.concat(['create', 'destroy', 'update', 'postcreate', 'postupdate']) if model.included_modules.include?(Orchestration)
+
+    # 3. List custom define_callbacks/define_model_callbacks
+    callbacks = model.methods.map { |m| $1 if m =~ /\A_([a-z]\w+)_callbacks\z/ }.compact
+    # ignore callbacks that are in the AR default list
+    callbacks.delete_if { |c| events.any? { |e| e.end_with?("_#{c}") } }
+    callbacks.each { |c| events.push("before_#{c}", "after_#{c}") }
+
     puts events.sort
   end
 end

metadata

@@ -1,18 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: foreman_hooks
 version: !ruby/object:Gem::Version
-  version: 0.3.12
+  version: 0.3.17
 platform: ruby
 authors:
 - Dominic Cleal
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-05 00:00:00.000000000 Z
+date: 2020-11-18 00:00:00.000000000 Z
 dependencies: []
 description: Plugin engine for Foreman that enables running custom hook scripts on
   Foreman events
-email: dcleal@redhat.com
+email: dominic@cleal.org
 executables: []
 extensions: []
 extra_rdoc_files:
@@ -24,9 +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
@@ -34,9 +38,9 @@ files:
 - lib/tasks/hooks.rake
 - test/test_helper.rb
 - test/unit/host_observer_test.rb
-homepage: http://github.com/theforeman/foreman_hooks
+homepage: https://github.com/theforeman/foreman_hooks
 licenses:
-- GPL-3
+- GPL-3.0
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -44,17 +48,16 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.0.6
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Run custom hook scripts on Foreman events