shells 0.1.23 → 0.2.0

data/lib/shells/pf_shell_wrapper.rb

@@ -0,0 +1,270 @@
+module Shells
+
+  ##
+  # A wrapper class around a base shell to execute pfSense PHP commands within.
+  class PfShellWrapper
+
+    ##
+    # The pfSense shell itself.
+    PF_SHELL = '/usr/local/sbin/pfSsh.php'
+
+    ##
+    # The prompt in the pfSense shell.
+    PF_PROMPT = 'pfSense shell:'
+
+
+    attr_accessor :config_parsed
+    private :config_parsed, :config_parsed=
+
+    attr_accessor :shell
+    private :shell, :shell=
+
+    ##
+    # Gets the output from the pfSense PHP shell session.
+    attr_accessor :output
+
+    ##
+    # Creates the wrapper, executing the pfSense shell.
+    #
+    # The provided code block is yielded this wrapper for execution.
+    def initialize(base_shell, &block)
+      raise ArgumentError, 'a code block is required' unless block_given?
+      raise ArgumentError, 'the base shell must be a valid shell' unless base_shell.is_a?(::Shells::ShellBase)
+
+      self.shell = base_shell
+
+      wrapper = self
+      code_block = block
+      self.output = ''
+      self.config_parsed = false
+
+      shell.instance_eval do
+        merge_local_buffer do
+          begin
+            temporary_prompt(PF_PROMPT) do
+              debug 'Initializing the pfSense PHP shell...'
+              queue_input PF_SHELL + line_ending
+              wait_for_prompt 999, 10, true
+
+              debug ' > initialized'
+              begin
+                code_block.call wrapper
+              ensure
+                debug 'Exiting the pfSense PHP shell...'
+                if wait_for_prompt(5, 5, false)
+                  # only queue the exit command if we are still in the pfSense shell.
+                  queue_input 'exit' + line_ending
+                end
+              end
+            end
+          ensure
+            # wait for the normal shell to return.
+            wait_for_prompt 10, 10, true
+            debug ' > exited'
+            wrapper.output = output
+          end
+        end
+      end
+    end
+
+    ##
+    # Executes a series of commands on the pfSense shell.
+    def exec(*commands)
+      ret = ''
+      commands.each { |cmd| ret += shell.exec(cmd) }
+      ret + shell.exec('exec')
+    end
+
+    ##
+    # Reloads the pfSense configuration on the device.
+    def parse_config
+      exec 'parse_config(true);'
+      self.config_parsed = true
+    end
+
+    ##
+    # Determines if the configuration has been parsed during this session.
+    def config_parsed?
+      config_parsed
+    end
+
+    ##
+    # Gets a configuration section from the pfSense device.
+    def get_config_section(section_name)
+      parse_config unless config_parsed?
+      JSON.parse exec("echo json_encode($config[#{section_name.to_s.inspect}]);").strip
+    end
+
+    ##
+    # Sets a configuration section to the pfSense device.
+    #
+    # Returns the number of changes made to the configuration.
+    def set_config_section(section_name, values, message = '')
+      current_values = get_config_section(section_name)
+      changes = generate_config_changes("$config[#{section_name.to_s.inspect}]", current_values, values)
+      if changes&.any?
+        if message.to_s.strip == ''
+          message = "Updating #{section_name} section."
+        end
+        changes << "write_config(#{message.inspect});"
+
+        exec(*changes)
+
+        (changes.size - 1)
+      else
+        0
+      end
+    end
+
+    ##
+    # Apply the firewall configuration.
+    #
+    # You need to apply the firewall configuration after you make changes to aliases, NAT rules, or filter rules.
+    def apply_filter_config
+      exec(
+          'require_once("shaper.inc");',
+          'require_once("filter.inc");',
+          'filter_configure_sync();'
+      )
+    end
+
+    ##
+    # Applies the user configuration for the specified user.
+    def apply_user_config(user_id)
+      user_id = user_id.to_i
+      exec(
+          'require_once("auth.inc");',
+          "$user_entry = $config[\"system\"][\"user\"][#{user_id}];",
+          '$user_groups = array();',
+          'foreach ($config["system"]["group"] as $gidx => $group) {',
+          '  if (is_array($group["member"])) {',
+          "    if (in_array(#{user_id}, $group[\"member\"])) { $user_groups[] = $group[\"name\"]; }",
+          '  }',
+          '}',
+          # Intentionally run set_groups before and after to ensure group membership gets fully applied.
+          'local_user_set_groups($user_entry, $user_groups);',
+          'local_user_set($user_entry);',
+          'local_user_set_groups($user_entry, $user_groups);'
+      )
+    end
+
+    ##
+    # Enabled public key authentication for the current pfSense user.
+    #
+    # Once this has been done you should be able to connect without using a password.
+    def enable_cert_auth(public_key = '~/.ssh/id_rsa.pub')
+      cert_regex = /^ssh-[rd]sa (?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)? \S*$/m
+
+      # get our cert unless the user provided a full cert for us.
+      unless public_key =~ cert_regex
+        public_key = File.expand_path(public_key)
+        if File.exist?(public_key)
+          public_key = File.read(public_key).to_s.strip
+        else
+          raise Shells::PfSenseCommon::PublicKeyNotFound
+        end
+        raise Shells::PfSenseCommon::PublicKeyInvalid unless public_key =~ cert_regex
+      end
+
+      cfg = get_config_section 'system'
+      user_id = nil
+      user_name = options[:user].downcase
+      cfg['user'].each_with_index do |user,index|
+        if user['name'].downcase == user_name
+          user_id = index
+
+          authkeys = Base64.decode64(user['authorizedkeys'].to_s).gsub("\r\n", "\n").strip
+          unless authkeys == '' || authkeys =~ cert_regex
+            warn "Existing authorized keys for user #{options[:user]} are invalid and are being reset."
+            authkeys = ''
+          end
+
+          if authkeys == ''
+            user['authorizedkeys'] = Base64.strict_encode64(public_key)
+          else
+            authkeys = authkeys.split("\n")
+            unless authkeys.include?(public_key)
+              authkeys << public_key unless authkeys.include?(public_key)
+              user['authorizedkeys'] = Base64.strict_encode64(authkeys.join("\n"))
+            end
+          end
+
+          break
+        end
+      end
+
+
+      raise Shells::PfSenseCommon::UserNotFound unless user_id
+
+      set_config_section 'system', cfg, "Enable certificate authentication for #{options[:user]}."
+
+      apply_user_config user_id
+    end
+
+
+    ##
+    # Exits the shell session immediately and requests a reboot of the pfSense device.
+    def reboot
+      raise Shells::NotRunning unless running?
+      raise Shells::PfSenseCommon::RestartNow
+    end
+
+    ##
+    # Exits the shell session immediately.
+    def quit
+      raise Shells::NotRunning unless running?
+      raise Shells::ShellBase::QuitNow
+    end
+
+    private
+
+    def generate_config_changes(prefix, old_value, new_value)
+      old_value = fix_config_arrays(old_value)
+      new_value = fix_config_arrays(new_value)
+
+      if new_value.is_a?(Hash)
+        changes = []
+
+        unless old_value.is_a?(Hash)
+          # make sure the value is an array now.
+          changes << "#{prefix} = array();"
+          # and change the old_value to be an empty hash so we can work with it.
+          old_value = {}
+        end
+
+        # now iterate the hashes and process the child elements.
+        new_value.each do |k, new_v|
+          old_v = old_value[k]
+          changes += generate_config_changes("#{prefix}[#{k.inspect}]", old_v, new_v)
+        end
+
+        changes
+      else
+        if new_value != old_value
+          if new_value.nil?
+            [ "unset #{prefix};" ]
+          else
+            [ "#{prefix} = #{new_value.inspect};" ]
+          end
+        else
+          [ ]
+        end
+      end
+    end
+
+    def fix_config_arrays(value)
+      if value.is_a?(Array)
+        value.each_with_index
+            .map{|v,i| [i,v]}.to_h                      # convert to hash
+            .inject({}){ |m,(k,v)| m[k.to_s] = v; m }   # stringify keys
+      elsif value.is_a?(Hash)
+        value.inject({}) { |m,(k,v)| m[k.to_s] = v; m } # stringify keys
+      else
+        value
+      end
+    end
+
+  end
+
+
+end

data/lib/shells/serial_bash_shell.rb

@@ -0,0 +1,65 @@
+require 'shells/serial_shell'
+require 'shells/bash_common'
+
+module Shells
+  ##
+  # Executes a serial session with a device.
+  #
+  # The default setup of this class should work well with any bash-like shell.
+  #
+  # Valid options:
+  # +path+::
+  #     The path to the serial device (e.g. - COM3 or /dev/tty2)
+  #     This is a required option.
+  # +speed+::
+  #     The bitrate for the connection.
+  #     The default is 115200.
+  # +data_bits+::
+  #     The number of data bits for the connection.
+  #     The default is 8.
+  # +parity+::
+  #     The parity for the connection.
+  #     The default is :none.
+  # +prompt+::
+  #     The prompt used to determine when processes finish execution.
+  # +quit+::
+  #     If set, this defines the command to execute when quitting the session.
+  #     The default is "exit" which will probably work most of the time.
+  # +retrieve_exit_code+::
+  #     If set to a non-false value, then the default behavior will be to retrieve the exit code from the shell after
+  #     executing a command.  If set to a false or nil value, the default behavior will be to ignore the exit code
+  #     from the shell.  When retrieved, the exit code is stored in the +last_exit_code+ property.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +on_non_zero_exit_code+::
+  #     If set to :ignore (the default) then non-zero exit codes will not cause errors.  You will still be able to check
+  #     the +last_exit_code+ property to determine if the command was successful.
+  #     If set to :raise then non-zero exit codes will cause a Shells::NonZeroExitCode to be raised when a command exits
+  #     with a non-zero return value.
+  #     This option only comes into play when +retrieve_exit_code+ is set to a non-false value.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +silence_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for any feedback from the shell.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +command_timeout+ this value resets every time we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +command_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for the command to finish.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +silence_timeout+ this value does not reset when we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  #
+  #   Shells::SerialBashShell.new(
+  #       path: '/dev/ttyusb3',
+  #       speed: 9600
+  #   ) do |shell|
+  #     shell.exec('cd /usr/local/bin')
+  #     user_bin_files = shell.exec('ls -A1').split("\n")
+  #     @app_is_installed = user_bin_files.include?('my_app')
+  #   end
+  #
+  class SerialBashShell < SerialShell
+
+    include Shells::BashCommon
+
+  end
+end

data/lib/shells/{pf_sense_serial_session.rb → serial_pf_sense_shell.rb}

@@ -1,4 +1,4 @@
-require 'shells/serial_session'
+require 'shells/serial_bash_shell'
 require 'shells/pf_sense_common'
 
 module Shells
@@ -30,23 +30,25 @@ module Shells
   #     Unlike +silence_timeout+ this value does not reset when we receive feedback.
   #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
   #
-  #   Shells::PfSenseSerialSession.new(
+  #   Shells::SerialPfSenseShell.new(
   #       path: 'COM3'
   #   ) do |shell|
-  #     cfg = shell.get_config_section("aliases")
-  #     cfg["alias"] ||= []
-  #     cfg["alias"] << {
-  #         :name => "MY_NETWORK",
-  #         :type => "network",
-  #         :address => "192.168.1.0/24",
-  #         :descr => "My home network",
-  #         :details => "Created #{Time.now.to_s}"
-  #     }
-  #     shell.set_config_section("aliases", cfg, "Add home network")
-  #     shell.apply_filter_config
+  #     shell.pf_shell do |shell|
+  #       cfg = shell.get_config_section("aliases")
+  #       cfg["alias"] ||= []
+  #       cfg["alias"] << {
+  #           :name => "MY_NETWORK",
+  #           :type => "network",
+  #           :address => "192.168.1.0/24",
+  #           :descr => "My home network",
+  #           :details => "Created #{Time.now.to_s}"
+  #       }
+  #       shell.set_config_section("aliases", cfg, "Add home network")
+  #       shell.apply_filter_config
+  #     end
   #   end
   #
-  class PfSenseSerialSession < SerialSession
+  class SerialPfSenseShell < SerialShell
 
     include PfSenseCommon
 

data/lib/shells/{serial_session.rb → serial_shell.rb}

@@ -1,18 +1,10 @@
 require 'rubyserial'
 require 'shells/shell_base'
-require 'shells/bash_common'
 
 module Shells
   ##
   # Executes a serial session with a device.
   #
-  # The default setup of this class should work well with any bash-like shell.
-  # In particular, the +exec_prompt+ method sets the "PS1" environment variable, which should set the prompt the shell
-  # uses, and the +get_exit_code+ methods retrieves the value of the "$?" variable which should contain the exit code
-  # from the last action.  Because there is a possibility that your shell does not utilize those methods, the
-  # +override_set_prompt+ and +override_get_exit_code+ options are available to change the behavior.
-  #
-  #
   # Valid options:
   # +path+::
   #     The path to the serial device (e.g. - COM3 or /dev/tty2)
@@ -28,11 +20,6 @@ module Shells
   #     The default is :none.
   # +prompt+::
   #     The prompt used to determine when processes finish execution.
-  #     Defaults to '~~#', but if that doesn't work for some reason because it is valid output from one or more
-  #     commands, you can change it to something else.  It must be unique and cannot contain certain characters.
-  #     The characters you should avoid are !, $, \, /, ", and ' because no attempt is made to escape them and the
-  #     resulting prompt can very easily become something else entirely.  If they are provided, they will be
-  #     replaced to protect the shell from getting stuck.
   # +quit+::
   #     If set, this defines the command to execute when quitting the session.
   #     The default is "exit" which will probably work most of the time.
@@ -58,21 +45,8 @@ module Shells
   #     If set to 0 (or less) there is no timeout.
   #     Unlike +silence_timeout+ this value does not reset when we receive feedback.
   #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
-  # +override_set_prompt+::
-  #     If provided, this must be set to either a command string that will set the prompt, or a Proc that accepts
-  #     the shell as an argument.
-  #     If set to a string, the string is sent to the shell and we wait up to two seconds for the prompt to appear.
-  #     If that fails, we resend the string and wait one more time before failing.
-  #     If set to a Proc, the Proc is called.  If the Proc returns a false value, we fail.  If the Proc returns
-  #     a non-false value, we consider it successful.
-  # +override_get_exit_code+::
-  #     If provided, this must be set to either a command string that will retrieve the exit code, or a Proc that
-  #     accepts the shell as an argument.
-  #     If set to a string, the string is sent to the shell and the output is parsed as an integer and used as the exit
-  #     code.
-  #     If set to a Proc, the Proc is called and the return value of the proc is used as the exit code.
   #
-  #   Shells::SerialSession.new(
+  #   Shells::SerialShell.new(
   #       path: '/dev/ttyusb3',
   #       speed: 9600
   #   ) do |shell|
@@ -81,9 +55,30 @@ module Shells
   #     @app_is_installed = user_bin_files.include?('my_app')
   #   end
   #
-  class SerialSession < Shells::ShellBase
+  class SerialShell < Shells::ShellBase
+
+    attr_accessor :serport
+    private :serport, :serport=
+
+    attr_accessor :ser_stdout_recv
+    private :ser_stdout_recv, :ser_stdout_recv=
+
+    attr_accessor :output_reader
+    private :output_reader, :output_reader=
+
+    add_hook :on_before_run do |sh|
+      sh.instance_eval do
+        self.serport = nil
+        self.output_reader = nil
+      end
+    end
 
-    include BashCommon
+    add_hook :on_after_run do |sh|
+      sh.instance_eval do
+        self.serport = nil
+        self.output_reader = nil
+      end
+    end
 
     ##
     # Sets the line ending for the instance.
@@ -109,75 +104,68 @@ module Shells
       raise InvalidOption, 'Missing path.' if options[:path].to_s.strip == ''
     end
 
-    def exec_shell(&block) #:nodoc:
-
+    def connect #:nodoc:
       debug 'Opening serial port...'
-      @serport = Serial.new options[:path], options[:speed], options[:data_bits], options[:parity]
-
-      begin
-        # start buffering
-        buffer_input
-
-        # yield to the block
-        block.call
+      self.serport = Serial.new(options[:path], options[:speed], options[:data_bits], options[:parity])
+      debug 'Starting output reading thread...'
+      self.output_reader = Thread.start(self) do |shell|
+        while true
+          shell.instance_eval do
+            data = ''
+            while (byte = serport&.getbyte)
+              data << byte.chr
+            end
+            if data != ''
+              # add to the output buffer.
+              debug "Received: (#{data.size} bytes) #{(data.size > 32 ? (data[0..30] + '...') : data).inspect}"
+              ser_stdout_recv&.call data
+            end
+          end
+          Thread.pass
+        end
+      end
 
-      ensure
-        # send the quit message.
-        send_data options[:quit] + line_ending
+    end
 
-        debug 'Closing serial port...'
-        @serport.close
-        @serport = nil
-      end
+    def disconnect #:nodoc:
+      output_reader&.exit
+      serport.close
     end
 
-    def exec_prompt(&block) #:nodoc:
-      cmd = options[:override_set_prompt] || "PS1=\"#{options[:prompt]}\""
-      if cmd.respond_to?(:call)
-        raise Shells::FailedToSetPrompt unless cmd.call(self)
-      else
-        # set the prompt, wait up to 2 seconds for a response, then try one more time.
-        begin
-          exec cmd, command_timeout: 2, retrieve_exit_code: false, command_is_echoed: false
-        rescue Shells::CommandTimeout
-          begin
-            exec cmd, command_timeout: 2, retrieve_exit_code: false, command_is_echoed: false
-          rescue Shells::CommandTimeout
-            raise Shells::FailedToSetPrompt
-          end
-        end
-      end
+    def setup
+      # send a newline to the shell to (hopefully) redraw a menu.
+      debug 'Refreshing...'
+      queue_input line_ending
 
-      # yield to the block
-      block.call
+      debug 'Calling setup_prompt...'
+      setup_prompt
+      debug ' > prompt setup'
     end
 
     def send_data(data) #:nodoc:
-      @serport.write data
+      serport.write data
       debug "Sent: (#{data.size} bytes) #{(data.size > 32 ? (data[0..30] + '...') : data).inspect}"
     end
 
-    def loop(&block) #:nodoc:
+    def active?
+      return false if serport.nil?
+      return false if serport.closed?
+      true
+    end
+
+    def io_loop(&block) #:nodoc:
       while true
-        while true
-          data = ''
-          while (byte = @serport.getbyte)
-            data << byte.chr
-          end
-          break if data == ""
-          debug "Received: (#{data.size} bytes) #{(data.size > 32 ? (data[0..30] + '...') : data).inspect}"
-          @_stdout_recv.call data
-        end
-        break unless block&.call
+        break unless block.call
+        Thread.pass
       end
     end
 
     def stdout_received(&block) #:nodoc:
-      @_stdout_recv = block
+      sync { self.ser_stdout_recv = block }
     end
 
     def stderr_received(&block) #:nodoc:
-      @_stderr_recv = block
+      nil # no stderr to report.
     end
 
   end