scout_agent 3.0.0

data/lib/scout_agent/api.rb

@@ -0,0 +1,241 @@
+#!/usr/bin/env ruby -wKU
+
+require "pathname"  # all paths are Pathname objects
+
+begin
+  require "json"    # the agent communicates in JSON
+rescue LoadError    # library not found
+  begin
+    require "rubygems"
+    require "json"
+  rescue LoadError  # library not found
+    abort "Please install the 'json' gem to use this API."
+  end
+end
+
+module ScoutAgent
+  # 
+  # This module contains methods used to communicate with the agent
+  # programmatically.  These methods can be used to send data to the agent or
+  # to make requests that the agent perform certain actions for you.
+  # 
+  module API
+    #
+    # You should not need to consruct instances of this class directly as the
+    # API will handle those details for you.  However, you can use the methods
+    # of these instances, returned by many API methods, to examine the success
+    # or failure of your requests.
+    # 
+    class Command
+      def initialize(name, args, input, options)  # :nodoc:
+        @name          = name
+        @args          = args
+        @input         = input
+        @background    = options[:background]
+        @exit_status   = nil
+        @error_message = nil
+        @finished      = false
+        
+        @background ? run_in_background : run
+      end
+      
+      # Returns the exit status of the agent command as an Integer.
+      attr_reader  :exit_status
+      # This is the error code, if the request was not a success?().
+      alias_method :error_code,  :exit_status
+      # 
+      # Returns the error message from the agent as a Sting.  This is only set
+      # if the request was not a success?().
+      # 
+      attr_reader  :error_message
+      
+      # Returns +true+ if your request to the agent completed successfully.
+      def success?
+        exit_status and exit_status.zero?
+      end
+      
+      # 
+      # Returns +true+ if you chose to run the request in the background and it
+      # is now complete.  You can periodically poll this method to see if a
+      # background request has completed yet.
+      # 
+      # *Warning*:  none of the other methods should be trusted until this
+      # method returns +true+.
+      # 
+      def finished?
+        @finished
+      end
+      
+      private
+      
+      def run
+        command        = [API.path_to_agent, @name, *Array(@args)].
+                         map { |s| "'#{API.shell_escape(s)}'" }.join(" ")
+        begin
+          response     = open("| #{command} 2>&1", "r+") do |agent|
+            agent.puts @input.to_json if @input
+            agent.close_write
+            agent.read
+          end
+        rescue Exception => error  # we cannot shell out to the agent
+          @exit_status   = ($? && $?.exitstatus) || -1
+          @error_message = "#{error.message} (#{error.class})"
+          @finished      = true
+          return
+        end
+        @exit_status   = $?.exitstatus
+        @error_message = response unless success?
+        @finished      = true
+      end
+      
+      def run_in_background
+        Thread.new { run }
+      end
+    end
+    
+    class QueueCommand < Command  # :nodoc:
+      def initialize(mission_id_or_report_type, fields, options)
+        validate(mission_id_or_report_type, fields)
+        super(:queue, [mission_id_or_report_type], fields, options)
+      end
+      
+      private
+      
+      def validate(mission_id_or_report_type, fields)
+        unless mission_id_or_report_type.to_s =~
+               /\A(?:report|hint|alert|error|\d*[1-9])\z/
+          raise ArgumentError, "Invalid mission ID or report type"
+        end
+        
+        if %w[report hint alert error].include? mission_id_or_report_type.to_s
+          unless fields.is_a? Hash
+            raise ArgumentError, "Reports must receive a fields Hash"
+          end
+          plugin_id = fields[:plugin_id] || fields["plugin_id"]
+          unless plugin_id
+            raise ArgumentError, "A :plugin_id is a required field for reports"
+          end
+          unless plugin_id.to_s =~ /\A\d*[1-9]\z/
+            raise ArgumentError, "The :plugin_id must be a positive Integer"
+          end
+        end
+      end
+    end
+    
+    module_function
+    
+    # 
+    # This convience method will escape a single _word_ for use in a shell
+    # command.  This is handy for anyone wanting to construct their own commands
+    # manually.  You will not need this method if you stick to the higher level
+    # interface methods provided by this API.
+    # 
+    def shell_escape(str)
+      String(str).gsub(/(?=[^a-zA-Z0-9_.\/\-\x7F-\xFF\n])/n, '\\').
+                  gsub(/\n/,                                 "'\n'").
+                  sub(/^$/,                                  "''")
+    end
+    
+    # 
+    # This method returns the path to the agent executable as a Pathname object.
+    # This is convience for those who wish to manually communicate with the
+    # agent and not needed if you stick to the higher level interface.
+    # 
+    def path_to_agent
+      Pathname.new( File.join( File.dirname(__FILE__),
+                               *%w[.. .. bin scout_agent] ) )
+    end
+    
+    #
+    # Use this method to queue a +message+ for a mission to receive on it's next
+    # run.
+    # 
+    # By default, this method will not return until the request to the agent is
+    # complete.  It then returns a Command object, which can be used to examine
+    # how the request went.  For example:
+    # 
+    #   response = ScoutAgent::API.queue_for_mission(42, {"message" => "here"})
+    #   if response.success?
+    #     puts "Message queued."
+    #   else
+    #     warn "Error:  #{response.error_message} (#{response.error_code})"
+    #   end
+    # 
+    # If you don't wish to wait, you can request that the send take place in the
+    # background.  You can still use the command objects to check the status of
+    # these requests, but you must first wait for them to be finished?().  Do
+    # not trust any other methods, like success?(), until finished?() returns
+    # +true+.
+    # 
+    #   in_progress = ScoutAgent::API.queue_for_mission( ...,
+    #                                                    :background => true )
+    #   # the above returns immediately, so we need to wait for it to finish
+    #   until in_progress.finished?
+    #     # do important work that can't wait here
+    #   end
+    #   if in_progress.success?
+    #     # ...
+    #   else
+    #     # ...
+    #   end
+    # 
+    # Of course, you are free to ignore the returned Command, say if performance
+    # is more critical than getting a +message+ through.
+    # 
+    def queue_for_mission(mission_id, message, options = { })
+      QueueCommand.new(mission_id, message, options)
+    end
+    
+    # 
+    # This method queues a report that will be sent straight to the Scout server
+    # during the next checkin.  The passed +fields+ must be a Hash and must
+    # contain a <tt>:plugin_id</tt> key/value pair that tells the server which
+    # plugin this report belongs to.  The returned object and background
+    # processing rules are the same as those described in queue_for_mission().
+    # 
+    def queue_report(fields, options = { })
+      QueueCommand.new(:report, fields, options)
+    end
+    
+    # 
+    # This method queues a hint that will be sent straight to the Scout server
+    # during the next checkin.  The passed +fields+ should follow the rules
+    # outlined in queue_report().  The returned object and background processing
+    # rules are the same as those described in queue_for_mission().
+    # 
+    def queue_hint(fields, options = { })
+      QueueCommand.new(:hint, fields, options)
+    end
+    
+    # 
+    # This method queues an alert that will be sent straight to the Scout server
+    # during the next checkin.  The passed +fields+ should follow the rules
+    # outlined in queue_report().  The returned object and background processing
+    # rules are the same as those described in queue_for_mission().
+    # 
+    def queue_alert(fields, options = { })
+      QueueCommand.new(:alert, fields, options)
+    end
+    
+    # 
+    # This method queues an error that will be sent straight to the Scout server
+    # during the next checkin.  The passed +fields+ should follow the rules
+    # outlined in queue_report().  The returned object and background processing
+    # rules are the same as those described in queue_for_mission().
+    # 
+    def queue_error(fields, options = { })
+      QueueCommand.new(:error, fields, options)
+    end
+    
+    # 
+    # This method requests that the agent take a snapshot of the current
+    # environment, by running any commands the server has sent down.  A
+    # timestamped result of these executions will be pushed up to the server
+    # during the next checkin.  The returned object and background processing
+    # rules are the same as those described in queue_for_mission().
+    # 
+    def take_snapshot(options = { })
+      Command.new(:snapshot, nil, nil, options)
+    end
+  end
+end

data/lib/scout_agent/assignment.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  class Assignment
+    { :plan         => :file_and_switches,
+      :choose_user  => false,
+      :choose_group => false }.each do |name, default|
+      instance_eval <<-END_CONFIG
+      def #{name}(setting = nil)
+        @#{name} ||= #{default.inspect}  # default
+        @#{name} =   setting if setting  # writer
+        @#{name}                         # reader
+      end
+      END_CONFIG
+    end
+    
+    def initialize(switches, other_args)
+      @switches   = switches
+      @other_args = other_args
+      @user       = nil
+      @group      = nil
+    end
+    
+    include Tracked
+    
+    attr_reader :switches, :other_args, :user, :group
+    
+    def prepare_and_execute
+      read_the_plan
+      choose_identity
+      execute
+    end
+    
+    private
+    
+    def read_the_plan
+      if self.class.plan.to_s.include? "file"
+        begin
+          Plan.update_from_config_file        # load our config file
+        rescue Errno::ENOENT                  # missing config
+          abort_with_missing_config
+        end
+      end
+      if not @switches.empty? and self.class.plan.to_s.include? "switches"
+        Plan.update_from_switches(@switches)  # override with switches
+      end
+    end
+    
+    def choose_identity
+      [ %w[user  getpwnam],
+        %w[group getgrnam] ].each do |type, interface|
+        if self.class.send("choose_#{type}")
+          match = nil
+          Array(Plan.send("#{type}_choices")).each do |name|
+            begin
+              match = Etc.send(interface, name)
+              break
+            rescue ArgumentError  # not found
+              # try the next choice
+            end
+          end
+          if match
+            instance_variable_set("@#{type}", match)
+          else
+            abort_with_not_found(type)
+          end
+        end
+      end
+    end
+    
+    def test_server_connection(quiet = false)
+      unless quiet
+        print "Testing server connection:  "
+        $stdout.flush
+      end
+      if Server.new.get_plan
+        puts "success." unless quiet
+        true
+      else
+        puts "failed." unless quiet
+        false
+      end
+    end
+    
+    def abort_with_missing_config
+      abort <<-END_MISSING_CONFIG.trim
+      Unable to load configuration file.  Please make sure you
+      have setup the daemon with this command:
+  
+          sudo #{$PROGRAM_NAME} identify
+      
+      END_MISSING_CONFIG
+    end
+    
+    def abort_with_not_found(type)
+      choices = Plan.send("#{type}_choices")
+      config  = "\n\n    config.#{type}_choices = %w[#{choices.join(" ")}]\n\n"
+      abort <<-END_NOT_FOUND.word_wrap + config
+      I was unable to find a #{type} from the choice#{'s' if choices.size != 1}
+      #{choices.to_word_list("or")}.  Please edit the following line in
+      #{Plan.config_file} to insert a valid group for your system:
+      END_NOT_FOUND
+    end
+  end
+end

data/lib/scout_agent/assignment/configuration.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  class Assignment
+    class Configuration < Assignment
+      def execute
+        puts "Configuration"
+        puts "============="
+        puts 
+        settings = [:agent_key] + Plan.defaults.map { |name, _| name }
+        size     = settings.map { |name| name.to_s.size }.max
+        settings.each do |name|
+          value = case v = Plan.send(name)
+                  when Pathname
+                    if name.to_s =~ /\Aos_/
+                      v.relative_path_from(Plan.prefix_path).to_s.inspect
+                    else
+                      v.to_s.inspect
+                    end
+                  when Array
+                    "%w[#{v.join(' ')}]"
+                  else
+                    v.inspect
+                  end
+          puts "config.%-#{size}s = %s" % [name, value]
+        end
+      end
+    end
+  end
+end

data/lib/scout_agent/assignment/identify.rb

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby -wKU
+
+module ScoutAgent
+  class Assignment
+    class Identify < Assignment
+      plan         :switches_only
+      choose_group true
+      
+      def execute
+        puts "Identifying Your Agent"
+        puts "======================"
+        puts
+        
+        %w[config_file db_dir log_dir].each do |path|
+          full = dir = Plan.send(path)
+          loop do
+            dir = dir.dirname
+            break if dir.exist?
+          end
+          unless dir.writable?
+            abort_with_insufficient_permissions(full)
+          end
+        end
+        
+        unless Plan.config_file.exist?
+          print <<-END_KEY_DESCRIPTION.trim.to_question
+          I need your Agent Key displayed in the Agent Settings tab
+          to communicate with the server.  It looks like:
+
+              a7349498-bec3-4ddf-963c-149a666433a4
+
+          Enter the Agent Key:
+          END_KEY_DESCRIPTION
+          Plan.agent_key = gets.to_s.strip
+          puts
+          if test_server_connection
+            puts
+          else
+            puts
+            abort_with_bad_key
+          end
+        end
+        
+        puts "Saving identification..."
+        if Plan.write_default_config_file
+          puts "Identification file '#{Plan.config_file}' created."
+        else
+          if Plan.config_file.exist?
+            puts "Identification file '#{Plan.config_file}' exists.  Skipped."
+          else
+            abort_with_insufficient_permissions(Plan.config_file)
+          end
+        end
+        %w[db_dir log_dir].each do |path|
+          dir = Plan.send(path)
+          if dir.exist?
+            puts "Directory '#{dir}' exists.  Skipped."
+          elsif Plan.send("build_#{path}", group.gid)
+            puts "Directory '#{dir}' created."
+          else
+            abort_with_insufficient_permissions(dir)
+          end
+          if path == "db_dir"
+            %w[statuses queue snapshots].each do |name|
+              db = Database.path(name)
+              if db.exist?
+                puts "Database '#{db}' exists.  Skipped."
+              elsif Plan.prepare_global_database(name)
+                puts "Database '#{db}' created."
+              else
+                abort_with_insufficient_permissions(db)
+              end
+            end
+          end
+        end
+        puts "Done."
+        puts
+        
+        puts <<-END_START_INSTRUCTIONS.trim
+        You are now identified.  You can start the agent with:
+        
+            sudo #{$PROGRAM_NAME} start
+        
+        END_START_INSTRUCTIONS
+      end
+      
+      private
+      
+      def abort_with_insufficient_permissions(path)
+        abort <<-END_PRIVILEGES.trim
+        I don't have enough privileges to create '#{path}'.
+        Try running this program again with super user privileges:
+        
+            sudo #{$PROGRAM_NAME} identify
+        
+        END_PRIVILEGES
+      end
+      
+      def abort_with_bad_key
+        abort <<-END_BAD_KEY.trim
+        Could not contact server.  The key may be incorrect.
+        For more help, please visit:
+
+            http://scoutapp.com/help
+        
+        END_BAD_KEY
+      end
+    end
+  end
+end