openbolt 5.0.0.rc1

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

@@ -0,0 +1,431 @@
+# frozen_string_literal: true
+
+module Bolt
+  class Config
+    module Transport
+      module Options
+        LOGIN_SHELLS = %w[sh bash zsh dash ksh powershell].freeze
+
+        # Definitions used to validate config options.
+        # https://github.com/puppetlabs/bolt/blob/main/schemas/README.md
+        TRANSPORT_OPTIONS = {
+          "basic-auth-only" => {
+            type: [TrueClass, FalseClass],
+            description: "Whether to force basic authentication. This option is only available when using SSL.",
+            _plugin: true,
+            _default: false,
+            _example: true
+          },
+          "batch-mode" => {
+            type: [TrueClass, FalseClass],
+            description: "Whether to disable password querying. When set to `false`, SSH will fall back to "\
+                         "prompting for a password if key authentication fails. This might cause Bolt to hang. "\
+                         "To prevent Bolt from hanging, you can configure `ssh-command` to use an SSH utility "\
+                         "such as sshpass that supports providing a password non-interactively. For more "\
+                         "information, see [Providing a password non-interactively using "\
+                         "`native-ssh`](troubleshooting.md#providing-a-password-non-interactively-using-native-ssh).",
+            _plugin: true,
+            _default: true,
+            _example: false
+          },
+          "bundled-ruby" => {
+            description: "Whether to use the Ruby bundled with Bolt packages for local targets.",
+            type: [TrueClass, FalseClass],
+            _plugin: false,
+            _example: true,
+            _default: true
+          },
+          "cacert" => {
+            type: String,
+            description: "The path to the CA certificate.",
+            _plugin: true,
+            _example: "~/.puppetlabs/puppet/cert.pem"
+          },
+          "cleanup" => {
+            type: [TrueClass, FalseClass],
+            description: "Whether to clean up temporary files created on targets. When running commands on a target, "\
+                         "Bolt might create temporary files. After completing the command, these files are "\
+                         "automatically deleted. This value can be set to 'false' if you wish to leave these "\
+                         "temporary files on the target.",
+            _plugin: true,
+            _default: true,
+            _example: false
+          },
+          "connect-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds when establishing connections. Set this value higher if you "\
+                         "frequently encounter connection timeout errors when running Bolt.",
+            minimum: 1,
+            _plugin: true,
+            _default: 10,
+            _example: 15
+          },
+          "copy-command" => {
+            type: [Array, String],
+            description: "The command to use when copying files using native SSH. Bolt runs `<copy-command> <src> "\
+                         "<dest>`. This option is used when you need support for features or algorithms that are not "\
+                         "supported by the net-ssh Ruby library. **This option is experimental.** You can read more "\
+                         "about this option in [Native SSH transport](experimental_features.md#native-ssh-transport).",
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _default: %w[scp -r],
+            _example: %w[scp -r -F ~/ssh-config/myconf]
+          },
+          "disconnect-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds before force-closing a connection.",
+            minimum: 1,
+            _plugin: true,
+            _default: 5,
+            _example: 10
+          },
+          "encryption-algorithms" => {
+            type: Array,
+            description: "A list of encryption algorithms to use when establishing a connection "\
+                         "to a target. Supported algorithms are defined by the Ruby net-ssh library and can be "\
+                         "viewed [here](https://github.com/net-ssh/net-ssh#supported-algorithms). All supported, "\
+                         "non-deprecated algorithms are available by default when this option is not used. To "\
+                         "reference all default algorithms using this option, add 'defaults' to the list of "\
+                         "supported algorithms.",
+            uniqueItems: true,
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _example: %w[defaults idea-cbc]
+          },
+          "extensions" => {
+            type: Array,
+            description: "A list of file extensions that are accepted for scripts or tasks on "\
+                         "Windows. 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.",
+            uniqueItems: true,
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _example: [".sh"]
+          },
+          "file-protocol" => {
+            type: String,
+            description: "Which file transfer protocol to use. Either `winrm` or `smb`. Using `smb` is "\
+                         "recommended for large file transfers.",
+            enum: %w[smb winrm],
+            _plugin: true,
+            _default: "winrm",
+            _example: "smb"
+          },
+          "host" => {
+            type: String,
+            description: "The target's hostname.",
+            _plugin: true,
+            _example: "docker_host_production"
+          },
+          "host-key-algorithms" => {
+            type: Array,
+            description: "A list of host key algorithms to use when establishing a connection "\
+                         "to a target. Supported algorithms are defined by the Ruby net-ssh library and can be "\
+                         "viewed [here](https://github.com/net-ssh/net-ssh#supported-algorithms). All supported, "\
+                         "non-deprecated algorithms are available by default when this option is not used. To "\
+                         "reference all default algorithms using this option, add 'defaults' to the list of "\
+                         "supported algorithms.",
+            uniqueItems: true,
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _example: %w[defaults ssh-dss]
+          },
+          "host-key-check" => {
+            type: [TrueClass, FalseClass],
+            description: "Whether to perform host key validation when connecting.",
+            _plugin: true,
+            _example: false
+          },
+          "interpreters" => {
+            type: Hash,
+            description: "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.",
+            additionalProperties: {
+              type: [String, Array],
+              _plugin: false
+            },
+            propertyNames: {
+              pattern: "^.?[a-zA-Z0-9]+$"
+            },
+            _plugin: true,
+            _example: { "rb" => ["/usr/bin/ruby", "-r", "puppet"],
+                        ".py" => "/usr/bin/python3" }
+          },
+          "job-poll-interval" => {
+            type: Integer,
+            description: "The interval, in seconds, to poll orchestrator for job status.",
+            minimum: 1,
+            _plugin: true,
+            _example: 2
+          },
+          "job-poll-timeout" => {
+            type: Integer,
+            description: "The time, in seconds, to wait for orchestrator job status.",
+            minimum: 1,
+            _plugin: true,
+            _example: 2000
+          },
+          "kex-algorithms" => {
+            type: Array,
+            description: "A list of key exchange algorithms to use when establishing a connection "\
+                         "to a target. Supported algorithms are defined by the Ruby net-ssh library and can be "\
+                         "viewed [here](https://github.com/net-ssh/net-ssh#supported-algorithms). All supported, "\
+                         "non-deprecated algorithms are available by default when this option is not used. To "\
+                         "reference all default algorithms using this option, add 'defaults' to the list of "\
+                         "supported algorithms.",
+            uniqueItems: true,
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _example: %w[defaults diffie-hellman-group1-sha1]
+          },
+          "load-config" => {
+            type: [TrueClass, FalseClass],
+            description: "Whether to load system SSH configuration from '~/.ssh/config' and '/etc/ssh_config'.",
+            _plugin: true,
+            _default: true,
+            _example: false
+          },
+          "login-shell" => {
+            type: String,
+            description: "Which login shell Bolt should expect on the target. Supported shells are " \
+                         "#{LOGIN_SHELLS.join(', ')}. **This option is experimental.**",
+            enum: LOGIN_SHELLS,
+            _plugin: true,
+            _default: "bash",
+            _example: "powershell"
+          },
+          "mac-algorithms" => {
+            type: Array,
+            description: "List of message authentication code algorithms to use when establishing a connection "\
+                         "to a target. Supported algorithms are defined by the Ruby net-ssh library and can be "\
+                         "viewed [here](https://github.com/net-ssh/net-ssh#supported-algorithms). All supported, "\
+                         "non-deprecated algorithms are available by default when this option is not used. To "\
+                         "reference all default algorithms using this option, add 'defaults' to the list of "\
+                         "supported algorithms.",
+            uniqueItems: true,
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _example: %w[defaults hmac-md5]
+          },
+          "native-ssh" => {
+            type: [TrueClass, FalseClass],
+            description: "This enables the native SSH transport, which shells out to SSH instead of using the "\
+                         "net-ssh Ruby library",
+            _default: false,
+            _example: true
+          },
+          "password" => {
+            type: String,
+            description: "The password to use to login.",
+            _plugin: true,
+            _example: "hunter2!"
+          },
+          "port" => {
+            type: Integer,
+            description: "The port to use when connecting to the target.",
+            minimum: 0,
+            _plugin: true,
+            _example: 22
+          },
+          "private-key" => {
+            type: [Hash, String],
+            description: "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. Note that "\
+            "the key cannot be encrypted if using the `key-data` hash.",
+            required: ["key-data"],
+            properties: {
+              "key-data" => {
+                description: "The contents of the private key.",
+                type: String
+              }
+            },
+            _plugin: true,
+            _example: "~/.ssh/id_rsa"
+          },
+          "proxyjump" => {
+            type: String,
+            description: "A jump host to proxy connections through, and an optional user to connect with.",
+            format: "uri",
+            _plugin: true,
+            _example: "jump.example.com"
+          },
+          "read-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds when making requests to the Orchestrator.",
+            minimum: 1,
+            _plugin: true,
+            _example: 15
+          },
+          "realm" => {
+            type: String,
+            description: "The Kerberos realm (Active Directory domain) to authenticate against.",
+            _plugin: true,
+            _example: "BOLT.PRODUCTION"
+          },
+          "remote" => {
+            type: String,
+            description: "The LXD remote host to use.",
+            _default: "local",
+            _plugin: false,
+            _example: 'myremote'
+          },
+          "run-as" => {
+            type: String,
+            description: "The user to run commands as after login. The run-as user must be different than the "\
+                         "login user.",
+            _plugin: true,
+            _example: "root"
+          },
+          "run-as-command" => {
+            type: Array,
+            description: "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 "\
+                         " aninteractive 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.",
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _example: ["sudo", "-nkSEu"]
+          },
+          "run-on" => {
+            type: String,
+            description: "The proxy target that the task executes on.",
+            format: "uri",
+            _plugin: true,
+            _default: "localhost",
+            _example: "proxy_target"
+          },
+          "script-dir" => {
+            type: String,
+            description: "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`.",
+            _plugin: true,
+            _example: "bolt_scripts"
+          },
+          "service-url" => {
+            type: String,
+            description: "The URL of the host used for API requests.",
+            format: "uri",
+            _plugin: true,
+            _example: "https://api.example.com:8143"
+          },
+          "shell-command" => {
+            type: String,
+            description: "A shell command to wrap any exec commands in, such as `bash -lc`.",
+            _plugin: true,
+            _example: "bash -lc"
+          },
+          "smb-port" => {
+            type: Integer,
+            description: "The port to use when connecting to the target when file-protocol is set to 'smb'.",
+            minimum: 0,
+            _plugin: true,
+            _example: 445
+          },
+          "ssh-command" => {
+            type: [Array, String],
+            description: "The command and options to use when SSHing. This option is used when you need support for "\
+                         "features or algorithms that are not supported by the net-ssh Ruby library. **This option "\
+                         "is experimental.** You can read more about this  option in [Native SSH "\
+                         "transport](experimental_features.md#native-ssh-transport).",
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _default: 'ssh',
+            _example: %w[ssh -o Ciphers=chacha20-poly1305@openssh.com]
+          },
+          "ssl" => {
+            type: [TrueClass, FalseClass],
+            description: "Whether to use secure https connections for WinRM.",
+            _plugin: true,
+            _default: true,
+            _example: false
+          },
+          "ssl-verify" => {
+            type: [TrueClass, FalseClass],
+            description: "Whether to verify that the target's certificate matches the cacert.",
+            _plugin: true,
+            _default: true,
+            _example: false
+          },
+          "sudo-executable" => {
+            type: String,
+            description: "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.**",
+            _plugin: true,
+            _example: "dzdo"
+          },
+          "sudo-password" => {
+            type: String,
+            description: "The password to use when changing users via `run-as`.",
+            _plugin: true,
+            _example: "p@$$w0rd!"
+          },
+          "task-environment" => {
+            type: String,
+            description: "The environment the orchestrator loads task code from.",
+            _plugin: true,
+            _default: "production",
+            _example: "development"
+          },
+          "tmpdir" => {
+            type: String,
+            description: "The directory to upload and execute temporary files on the target.",
+            _plugin: true,
+            _example: "/tmp/bolt"
+          },
+          "token-file" => {
+            type: String,
+            description: "The path to the token file.",
+            _plugin: true,
+            _example: "~/.puppetlabs/puppet/token.pem"
+          },
+          "tty" => {
+            type: [TrueClass, FalseClass],
+            description: "Whether to enable tty on exec commands.",
+            _plugin: true,
+            _example: true
+          },
+          "user" => {
+            type: String,
+            description: "The user name to login as.",
+            _plugin: true,
+            _example: "bolt"
+          }
+        }.freeze
+
+        RUN_AS_OPTIONS = %w[
+          run-as
+          run-as-command
+          sudo-executable
+          sudo-password
+        ].freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative '../../../bolt/error'
+require_relative '../../../bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class Orch < Base
+        OPTIONS = %w[
+          cacert
+          host
+          job-poll-interval
+          job-poll-timeout
+          read-timeout
+          service-url
+          task-environment
+          token-file
+        ].freeze
+
+        DEFAULTS = {
+          "task-environment" => "production"
+        }.freeze
+
+        private def validate
+          super
+
+          if @config['cacert']
+            @config['cacert'] = File.expand_path(@config['cacert'], @project)
+            Bolt::Util.validate_file('cacert', @config['cacert'])
+          end
+
+          if @config['token-file']
+            @config['token-file'] = File.expand_path(@config['token-file'], @project)
+            Bolt::Util.validate_file('token-file', @config['token-file'])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../../../bolt/error'
+require_relative '../../../bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class Podman < Base
+        OPTIONS = %w[
+          cleanup
+          host
+          interpreters
+          shell-command
+          tmpdir
+          tty
+        ].concat(RUN_AS_OPTIONS).sort.freeze
+
+        DEFAULTS = {
+          'cleanup' => true
+        }.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/remote.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../../../bolt/error'
+require_relative '../../../bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class Remote < Base
+        OPTIONS = %w[
+          run-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,138 @@
+# frozen_string_literal: true
+
+require_relative '../../../bolt/error'
+require_relative '../../../bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class SSH < Base
+        # Options available when using the net-ssh-based transport
+        OPTIONS = %w[
+          cleanup
+          connect-timeout
+          disconnect-timeout
+          encryption-algorithms
+          extensions
+          host
+          host-key-algorithms
+          host-key-check
+          interpreters
+          kex-algorithms
+          load-config
+          login-shell
+          mac-algorithms
+          password
+          port
+          private-key
+          proxyjump
+          script-dir
+          tmpdir
+          tty
+          user
+        ].concat(RUN_AS_OPTIONS).sort.freeze
+
+        # Options available when using the native ssh transport
+        NATIVE_OPTIONS = %w[
+          batch-mode
+          cleanup
+          copy-command
+          host
+          host-key-check
+          interpreters
+          native-ssh
+          port
+          private-key
+          script-dir
+          ssh-command
+          tmpdir
+          user
+        ].concat(RUN_AS_OPTIONS).sort.freeze
+
+        DEFAULTS = {
+          "batch-mode"         => true,
+          "cleanup"            => true,
+          "connect-timeout"    => 10,
+          "disconnect-timeout" => 5,
+          "load-config"        => true,
+          "login-shell"        => 'bash',
+          "tty"                => false
+        }.freeze
+
+        # The set of options available for the ssh and native ssh transports overlap, so we
+        # need to check which transport is used before fully initializing, otherwise options
+        # may not be filtered correctly.
+        def initialize(data = {}, project = nil)
+          assert_hash_or_config(data)
+          @native = true if data['native-ssh']
+          super(data, project)
+        end
+
+        # This method is used to filter CLI options in the Config class. This
+        # should include `ssh-command` so that we can later warn if the option
+        # is present without `native-ssh`
+        def self.options
+          %w[ssh-command native-ssh].concat(OPTIONS)
+        end
+
+        def self.schema
+          {
+            type:       Hash,
+            properties: self::TRANSPORT_OPTIONS.slice(*(self::OPTIONS + self::NATIVE_OPTIONS)),
+            _plugin:    true
+          }
+        end
+
+        private def filter(unfiltered)
+          # Because we filter before merging config together it's impossible to
+          # know whether both ssh-command *and* native-ssh will be specified
+          # unless they are both in the filter. However, we can't add
+          # ssh-command to OPTIONS since that's used for documenting available
+          # options. This makes it so that ssh-command is preserved so we can
+          # warn once all config is resolved if native-ssh isn't set.
+          @native ? unfiltered.slice(*NATIVE_OPTIONS) : unfiltered.slice(*self.class.options)
+        end
+
+        private def validate
+          super
+
+          if (key_opt = @config['private-key'])
+            if key_opt.instance_of?(String)
+              @config['private-key'] = File.expand_path(key_opt, @project)
+
+              # We have an explicit test for this to only warn if using net-ssh transport
+              Bolt::Util.validate_file('ssh key', @config['private-key']) if @config['native-ssh']
+            end
+
+            if key_opt.instance_of?(Hash) && @config['native-ssh']
+              raise Bolt::ValidationError, 'private-key must be a filepath when using native-ssh'
+            end
+          end
+
+          if @config['interpreters']
+            @config['interpreters'] = normalize_interpreters(@config['interpreters'])
+          end
+
+          if @config['login-shell'] == 'powershell'
+            %w[tty run-as].each do |key|
+              if @config[key]
+                raise Bolt::ValidationError,
+                      "#{key} is not supported when using PowerShell"
+              end
+            end
+          end
+
+          if @config['native-ssh'] && !@config['load-config']
+            msg = 'Cannot use native SSH transport with load-config set to false'
+            raise Bolt::ValidationError, msg
+          end
+
+          if !@config['batch-mode'] && !@config['ssh-command']
+            raise Bolt::ValidationError,
+                  'Must set ssh-command when batch-mode is set to false'
+          end
+        end
+      end
+    end
+  end
+end