bolt 2.1.0 → 2.2.0

data/lib/bolt/config/transport/base.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/util'
+
+module Bolt
+  class Config
+    module Transport
+      class Base
+        attr_reader :input
+
+        def initialize(data = {}, boltdir = nil)
+          assert_hash_or_config(data)
+          @input    = data
+          @resolved = !Bolt::Util.references?(input)
+          @config   = resolved? ? Bolt::Util.deep_merge(defaults, filter(input)) : defaults
+          @boltdir  = boltdir
+
+          validate if resolved?
+        end
+
+        # Accessor methods
+        # These are mostly all wrappers for same-named Hash methods, but they all
+        # require that the config options be fully-resolved before accessing data
+        def [](key)
+          resolved_config[key]
+        end
+
+        def to_h
+          resolved_config
+        end
+
+        def fetch(*args)
+          resolved_config.fetch(*args)
+        end
+
+        def include?(args)
+          resolved_config.include?(args)
+        end
+
+        def dig(*keys)
+          resolved_config.dig(*keys)
+        end
+
+        private def resolved_config
+          unless resolved?
+            raise Bolt::Error.new(
+              "Unable to access transport config, #{self.class} has unresolved config: #{input.inspect}",
+              'bolt/unresolved-transport-config'
+            )
+          end
+
+          @config
+        end
+
+        # Merges the original input data with the provided data, which is either a hash
+        # or transport config object. Accepts multiple inputs.
+        def merge(*data)
+          merged = data.compact.inject(@input) do |acc, layer|
+            assert_hash_or_config(layer)
+            layer_data = layer.is_a?(self.class) ? layer.input : layer
+            Bolt::Util.deep_merge(acc, layer_data)
+          end
+
+          self.class.new(merged, @boltdir)
+        end
+
+        # Resolve any references in the input data, then remerge it with the defaults
+        # and validate all values
+        def resolve(plugins)
+          @input    = plugins.resolve_references(input)
+          @config   = Bolt::Util.deep_merge(defaults, filter(input))
+          @resolved = true
+
+          validate
+        end
+
+        def resolved?
+          @resolved
+        end
+
+        def self.options
+          unless defined? self::OPTIONS
+            raise NotImplementedError,
+                  "Constant OPTIONS must be implemented by the transport config class"
+          end
+          self::OPTIONS
+        end
+
+        private def defaults
+          unless defined? self.class::DEFAULTS
+            raise NotImplementedError,
+                  "Constant DEFAULTS must be implemented by the transport config class"
+          end
+          self.class::DEFAULTS
+        end
+
+        private def filter(unfiltered)
+          unfiltered.slice(*self.class.options.keys)
+        end
+
+        private def assert_hash_or_config(data)
+          return if data.is_a?(Hash) || data.is_a?(self.class)
+          raise Bolt::ValidationError,
+                "Transport config must be a Hash or #{self.class}, received #{data.class} #{data.inspect}"
+        end
+
+        private def normalize_interpreters(interpreters)
+          Bolt::Util.walk_keys(interpreters) do |key|
+            key.chars[0] == '.' ? key : '.' + key
+          end
+        end
+
+        # Validation defaults to just asserting the option types
+        private def validate
+          assert_type
+        end
+
+        # Validates that each option is the correct type. Types are loaded from the OPTIONS hash.
+        private def assert_type
+          @config.each_pair do |opt, val|
+            next unless (type = self.class.options.dig(opt, :type))
+
+            # Options that accept a Boolean value are indicated by the type TrueClass, so we
+            # need some special handling here to check if the value is either true or false.
+            if type == TrueClass
+              unless [true, false].include?(val)
+                raise Bolt::ValidationError,
+                      "#{opt} must be a Boolean true or false, received #{val.class} #{val.inspect}"
+              end
+            else
+              unless val.nil? || val.is_a?(type)
+                raise Bolt::ValidationError,
+                      "#{opt} must be a #{type}, received #{val.class} #{val.inspect}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/config/transport/docker.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class Docker < Base
+        OPTIONS = {
+          "host"          => { type: String,
+                               desc: "Host name." },
+          "interpreters"  => { type: Hash,
+                               desc: "A map of an extension name to the absolute path of an executable, "\
+                                    "enabling you to override the shebang defined in a task executable. The "\
+                                    "extension can optionally be specified with the `.` character (`.py` and "\
+                                    "`py` both map to a task executable `task.py`) and the extension is case "\
+                                    "sensitive. When a target's name is `localhost`, Ruby tasks run with the "\
+                                    "Bolt Ruby interpreter by default." },
+          "service-url"   => { type: String,
+                               desc: "URL of the Docker host used for API requests." },
+          "shell-command" => { type: String,
+                               desc: "A shell command to wrap any Docker exec commands in, such as `bash -lc`." },
+          "tmpdir"        => { type: String,
+                               desc: "The directory to upload and execute temporary files on the target." },
+          "tty"           => { type: TrueClass,
+                               desc: "Whether to enable tty on exec commands." }
+        }.freeze
+
+        DEFAULTS = {}.freeze
+
+        private def validate
+          super
+
+          if @config['interpreters']
+            @config['interpreters'] = normalize_interpreters(@config['interpreters'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/config/transport/local.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class Local < Base
+        OPTIONS = {
+          "interpreters"    => { type: Hash,
+                                 desc: "A map of an extension name to the absolute path of an executable, "\
+                                      "enabling you to override the shebang defined in a task executable. The "\
+                                      "extension can optionally be specified with the `.` character (`.py` and "\
+                                      "`py` both map to a task executable `task.py`) and the extension is case "\
+                                      "sensitive. When a target's name is `localhost`, Ruby tasks run with the "\
+                                      "Bolt Ruby interpreter by default." },
+          "run-as"          => { type: String,
+                                 desc: "A different user to run commands as after login." },
+          "run-as-command"  => { type: Array,
+                                 desc: "The command to elevate permissions. Bolt appends the user and command "\
+                                      "strings to the configured `run-as-command` before running it on the target. "\
+                                      "This command must not require an interactive password prompt, and the "\
+                                      "`sudo-password` option is ignored when `run-as-command` is specified. The "\
+                                      "`run-as-command` must be specified as an array." },
+          "sudo-executable" => { type: String,
+                                 desc: "The executable to use when escalating to the configured `run-as` user. This "\
+                                      "is useful when you want to escalate using the configured `sudo-password`, "\
+                                      "since `run-as-command` does not use `sudo-password` or support prompting. "\
+                                      "The command executed on the target is `<sudo-executable> -S -u <user> -p "\
+                                      "custom_bolt_prompt <command>`. **This option is experimental.**" },
+          "sudo-password"   => { type: String,
+                                 desc: "Password to use when changing users via `run-as`." },
+          "tmpdir"          => { type: String,
+                                 desc: "The directory to copy and execute temporary files." }
+        }.freeze
+
+        WINDOWS_OPTIONS = {
+          "interpreters" => { type: Hash,
+                              desc: "A map of an extension name to the absolute path of an executable, "\
+                                    "enabling you to override the shebang defined in a task executable. The "\
+                                    "extension can optionally be specified with the `.` character (`.py` and "\
+                                    "`py` both map to a task executable `task.py`) and the extension is case "\
+                                    "sensitive. When a target's name is `localhost`, Ruby tasks run with the "\
+                                    "Bolt Ruby interpreter by default." },
+          "tmpdir"       => { type: String,
+                              desc: "The directory to copy and execute temporary files." }
+        }.freeze
+
+        DEFAULTS = {}.freeze
+
+        def self.options
+          Bolt::Util.windows? ? WINDOWS_OPTIONS : OPTIONS
+        end
+
+        private def validate
+          super
+
+          if @config['interpreters']
+            @config['interpreters'] = normalize_interpreters(@config['interpreters'])
+          end
+
+          if (run_as_cmd = @config['run-as-command'])
+            unless run_as_cmd.all? { |n| n.is_a?(String) }
+              raise Bolt::ValidationError,
+                    "run-as-command must be an Array of Strings, received #{run_as_cmd.class} #{run_as_cmd.inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/config/transport/orch.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class Orch < Base
+        OPTIONS = {
+          "cacert"            => { type: String,
+                                   desc: "The path to the CA certificate." },
+          "host"              => { type: String,
+                                   desc: "Host name." },
+          "job-poll-interval" => { type: Integer,
+                                   desc: "Set interval to poll orchestrator for job status." },
+          "job-poll-timeout"  => { type: Integer,
+                                   desc: "Set time to wait for orchestrator job status." },
+          "service-url"       => { type: String,
+                                   desc: "The URL of the orchestrator API." },
+          "task-environment"  => { type: String,
+                                   desc: "The environment the orchestrator loads task code from." },
+          "token-file"        => { type: String,
+                                   desc: "The path to the token file." }
+        }.freeze
+
+        DEFAULTS = {
+          "task-environment" => "production"
+        }.freeze
+
+        private def validate
+          super
+
+          if @config['cacert']
+            @config['cacert'] = File.expand_path(@config['cacert'], @boltdir)
+            Bolt::Util.validate_file('cacert', @config['cacert'])
+          end
+
+          if @config['token-file']
+            @config['token-file'] = File.expand_path(@config['token-file'], @boltdir)
+            Bolt::Util.validate_file('token-file', @config['token-file'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/config/transport/remote.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class Remote < Base
+        OPTIONS = {
+          "run-on" => { type: String,
+                        desc: "The proxy target that the task executes on." }
+        }.freeze
+
+        DEFAULTS = {
+          "run-on" => "localhost"
+        }.freeze
+
+        private def filter(unfiltered)
+          unfiltered
+        end
+      end
+    end
+  end
+end

data/lib/bolt/config/transport/ssh.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class SSH < Base
+        OPTIONS = {
+          "connect-timeout"    => { type: Integer,
+                                    desc: "How long to wait when establishing connections." },
+          "disconnect-timeout" => { type: Integer,
+                                    desc: "How long to wait before force-closing a connection." },
+          "host"               => { type: String,
+                                    desc: "Host name." },
+          "host-key-check"     => { type: TrueClass,
+                                    desc: "Whether to perform host key validation when connecting." },
+          "interpreters"       => { type: Hash,
+                                    desc: "A map of an extension name to the absolute path of an executable, "\
+                                          "enabling you to override the shebang defined in a task executable. The "\
+                                          "extension can optionally be specified with the `.` character (`.py` and "\
+                                          "`py` both map to a task executable `task.py`) and the extension is case "\
+                                          "sensitive. When a target's name is `localhost`, Ruby tasks run with the "\
+                                          "Bolt Ruby interpreter by default." },
+          "load-config"        => { type: TrueClass,
+                                    desc: "Whether to load system SSH configuration." },
+          "password"           => { type: String,
+                                    desc: "Login password." },
+          "port"               => { type: Integer,
+                                    desc: "Connection port." },
+          "private-key"        => { desc: "Either the path to the private key file to use for authentication, or a "\
+                                          "hash with the key `key-data` and the contents of the private key." },
+          "proxyjump"          => { type: String,
+                                    desc: "A jump host to proxy connections through, and an optional user to "\
+                                          "connect with." },
+          "run-as"             => { type: String,
+                                    desc: "A different user to run commands as after login." },
+          "run-as-command"     => { type: Array,
+                                    desc: "The command to elevate permissions. Bolt appends the user and command "\
+                                          "strings to the configured `run-as-command` before running it on the "\
+                                          "target. This command must not require an interactive password prompt, "\
+                                          "and the `sudo-password` option is ignored when `run-as-command` is "\
+                                          "specified. The `run-as-command` must be specified as an array." },
+          "script-dir"         => { type: String,
+                                    desc: "The subdirectory of the tmpdir to use in place of a randomized "\
+                                          "subdirectory for uploading and executing temporary files on the "\
+                                          "target. It's expected that this directory already exists as a subdir "\
+                                          "of tmpdir, which is either configured or defaults to `/tmp`." },
+          "sudo-executable"    => { type: String,
+                                    desc: "The executable to use when escalating to the configured `run-as` "\
+                                          "user. This is useful when you want to escalate using the configured "\
+                                          "`sudo-password`, since `run-as-command` does not use `sudo-password` "\
+                                          "or support prompting. The command executed on the target is "\
+                                          "`<sudo-executable> -S -u <user> -p custom_bolt_prompt <command>`. "\
+                                          "**This option is experimental.**" },
+          "sudo-password"      => { type: String,
+                                    desc: "Password to use when changing users via `run-as`." },
+          "tmpdir"             => { type: String,
+                                    desc: "The directory to upload and execute temporary files on the target." },
+          "tty"                => { type: TrueClass,
+                                    desc: "Request a pseudo tty for the session. This option is generally "\
+                                          "only used in conjunction with the `run-as` option when the sudoers "\
+                                          "policy requires a `tty`." },
+          "user"               => { type: String,
+                                    desc: "Login user." }
+        }.freeze
+
+        DEFAULTS = {
+          "connect-timeout"    => 10,
+          "tty"                => false,
+          "load-config"        => true,
+          "disconnect-timeout" => 5
+        }.freeze
+
+        private def validate
+          super
+
+          if (key_opt = @config['private-key'])
+            unless key_opt.instance_of?(String) || (key_opt.instance_of?(Hash) && key_opt.include?('key-data'))
+              raise Bolt::ValidationError,
+                    "private-key option must be a path to a private key file or a Hash containing the 'key-data', "\
+                    "received #{key_opt.class} #{key_opt}"
+            end
+
+            if key_opt.instance_of?(String)
+              @config['private-key'] = File.expand_path(key_opt, @boltdir)
+            end
+          end
+
+          if @config['interpreters']
+            @config['interpreters'] = normalize_interpreters(@config['interpreters'])
+          end
+
+          if (run_as_cmd = @config['run-as-command'])
+            unless run_as_cmd.all? { |n| n.is_a?(String) }
+              raise Bolt::ValidationError,
+                    "run-as-command must be an Array of Strings, received #{run_as_cmd.class} #{run_as_cmd.inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/config/transport/winrm.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class WinRM < Base
+        OPTIONS = {
+          "cacert"          => { type: String,
+                                 desc: "The path to the CA certificate." },
+          "connect-timeout" => { type: Integer,
+                                 desc: "How long Bolt should wait when establishing connections." },
+          "extensions"      => { type: Array,
+                                 desc: "List of file extensions that are accepted for scripts or tasks. "\
+                                      "Scripts with these file extensions rely on the target's file type "\
+                                      "association to run. For example, if Python is installed on the system, "\
+                                      "a `.py` script runs with `python.exe`. The extensions `.ps1`, `.rb`, and "\
+                                      "`.pp` are always allowed and run via hard-coded executables." },
+          "file-protocol"   => { type: String,
+                                 desc: "Which file transfer protocol to use. Either `winrm` or `smb`. Using `smb` is "\
+                                      "recommended for large file transfers." },
+          "host"            => { type: String,
+                                 desc: "Host name." },
+          "interpreters"    => { type: Hash,
+                                 desc: "A map of an extension name to the absolute path of an executable, "\
+                                      "enabling you to override the shebang defined in a task executable. The "\
+                                      "extension can optionally be specified with the `.` character (`.py` and "\
+                                      "`py` both map to a task executable `task.py`) and the extension is case "\
+                                      "sensitive. When a target's name is `localhost`, Ruby tasks run with the "\
+                                      "Bolt Ruby interpreter by default." },
+          "password"        => { type: String,
+                                 desc: "Login password. **Required unless using Kerberos.**" },
+          "port"            => { type: Integer,
+                                 desc: "Connection port." },
+          "realm"           => { type: String,
+                                 desc: "Kerberos realm (Active Directory domain) to authenticate against." },
+          "smb-port"        => { type: Integer,
+                                 desc: "With file-protocol set to smb, this is the port to establish a "\
+                                      "connection on." },
+          "ssl"             => { type: TrueClass,
+                                 desc: "When true, Bolt uses secure https connections for WinRM." },
+          "ssl-verify"      => { type: TrueClass,
+                                 desc: "When true, verifies the targets certificate matches the cacert." },
+          "tmpdir"          => { type: String,
+                                 desc: "The directory to upload and execute temporary files on the target." },
+          "user"            => { type: String,
+                                 desc: "Login user. **Required unless using Kerberos.**" }
+        }.freeze
+
+        DEFAULTS = {
+          "connect-timeout" => 10,
+          "ssl"             => true,
+          "ssl-verify"      => true,
+          "file-protocol"   => "winrm"
+        }.freeze
+
+        private def validate
+          super
+
+          if @config['ssl']
+            if @config['file-protocol'] == 'smb'
+              raise Bolt::ValidationError, "SMB file transfers are not allowed with SSL enabled"
+            end
+
+            if @config['cacert']
+              @config['cacert'] = File.expand_path(@config['cacert'], @boltdir)
+              Bolt::Util.validate_file('cacert', @config['cacert'])
+            end
+          end
+
+          if @config['interpreters']
+            @config['interpreters'] = normalize_interpreters(@config['interpreters'])
+          end
+        end
+      end
+    end
+  end
+end