bolt 2.15.0 → 2.20.0

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

@@ -2,11 +2,14 @@
 
 require 'bolt/error'
 require 'bolt/util'
+require 'bolt/config/transport/options'
 
 module Bolt
   class Config
     module Transport
       class Base
+        include Bolt::Config::Transport::Options
+
         attr_reader :input
 
         def initialize(data = {}, project = nil)
@@ -96,7 +99,7 @@ module Bolt
         end
 
         private def filter(unfiltered)
-          unfiltered.slice(*self.class.options.keys)
+          unfiltered.slice(*self.class.options)
         end
 
         private def assert_hash_or_config(data)
@@ -116,24 +119,21 @@ module Bolt
           assert_type
         end
 
-        # Validates that each option is the correct type. Types are loaded from the OPTIONS hash.
+        # Validates that each option is the correct type. Types are loaded from the TRANSPORT_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
+            types = Array(TRANSPORT_OPTIONS.dig(opt, :type)).compact
+
+            next if val.nil? || types.empty? || types.include?(val.class)
+
+            # Ruby doesn't have a Boolean class, so add it to the types list if TrueClass or FalseClass
+            # are present.
+            if types.include?(TrueClass) || types.include?(FalseClass)
+              types = types - [TrueClass, FalseClass] + ['Boolean']
             end
+
+            raise Bolt::ValidationError,
+                  "#{opt} must be of type #{types.join(', ')}; received #{val.class} #{val.inspect} "
           end
         end
       end

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

@@ -7,29 +7,15 @@ module Bolt
   class Config
     module Transport
       class Docker < Base
-        # NOTE: All transport configuration options should have a corresponding schema definition
-        #       in schemas/bolt-transport-definitions.json
-        OPTIONS = {
-          "cleanup"       => { type: TrueClass,
-                               desc: "Whether to clean up temporary files created on targets." },
-          "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
+        OPTIONS = %w[
+          cleanup
+          host
+          interpreters
+          service-url
+          shell-command
+          tmpdir
+          tty
+        ].freeze
 
         DEFAULTS = {
           'cleanup' => true

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

@@ -7,51 +7,13 @@ module Bolt
   class Config
     module Transport
       class Local < Base
-        # NOTE: All transport configuration options should have a corresponding schema definition
-        #       in schemas/bolt-transport-definitions.json
-        OPTIONS = {
-          "cleanup"         => { type: TrueClass,
-                                 desc: "Whether to clean up temporary files created on targets." },
-          "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 = %w[
+          cleanup
+          interpreters
+          tmpdir
+        ].freeze
 
-        WINDOWS_OPTIONS = {
-          "cleanup"      => { type: TrueClass,
-                              desc: "Whether to clean up temporary files created on targets." },
-          "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
+        OPTIONS = WINDOWS_OPTIONS.dup.concat(RUN_AS_OPTIONS).sort.freeze
 
         DEFAULTS = {
           'cleanup' => true

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

@@ -0,0 +1,460 @@
+# frozen_string_literal: true
+
+module Bolt
+  class Config
+    module Transport
+      module Options
+        LOGIN_SHELLS = %w[sh bash zsh dash ksh powershell].freeze
+
+        # The following constants define the various configuration options available to Bolt's
+        # transports. Each constant is a hash where keys are the configuration option and values
+        # are the option's definition. These options are used in multiple locations:
+        #
+        #   - Automatic type validation when loading and setting configuration
+        #   - Generating reference documentation for configuration files
+        #   - Generating JSON schemas for configuration files
+        #
+        # Data includes keys defined by JSON Schema Draft 07 as well as some metadata used
+        # by Bolt to generate documentation. The following keys are used:
+        #
+        #   :description    String      A detailed description of the option and what it does. This
+        #                               field is used in both documentation and the JSON schemas,
+        #                               and should provide as much detail as possible, including
+        #                               links to relevant documentation.
+        #
+        #   :type           Class       The expected type of a value. These should be Ruby classes,
+        #                               as this field is used to perform automatic type validation.
+        #                               If an option can accept more than one type, this should be
+        #                               an array of types. Boolean values should set :type to
+        #                               [TrueClass, FalseClass], as Ruby does not have a single
+        #                               Boolean class.
+        #
+        #   :items          Hash        A definition hash for items in an array. Similar to values
+        #                               for top-level options, items can have a :description, :type,
+        #                               or any other key in this list.
+        #
+        #   :uniqueItems    Boolean     Whether or not an array should contain only unique items.
+        #
+        #   :properties     Hash        A hash where keys are sub-options and values are definitions
+        #                               for the sub-option. Similar to values for top-level options,
+        #                               properties can have a :description, :type, or any other key
+        #                               in this list.
+        #
+        #   :additionalProperties       A variation of the :properties key, where the hash is a
+        #                   Hash        definition for any properties not specified in :properties.
+        #                               This can be used to permit arbitrary sub-options, such as
+        #                               logs for the 'log' option.
+        #
+        #   :propertyNames  Hash        A hash that defines the properties that an option's property
+        #                               names must adhere to.
+        #
+        #   :required       Array       An array of properties that are required for options that
+        #                               accept Hash values.
+        #
+        #   :minimum        Integer     The minimum integer value for an option.
+        #
+        #   :enum           Array       An array of values that the option recognizes.
+        #
+        #   :pattern        String      A JSON regex pattern that the option's vaue should match.
+        #
+        #   :format         String      Requires that a string value matches a format defined by the
+        #                               JSON Schema draft.
+        #
+        #   :_plugin        Boolean     Whether the option accepts a plugin reference. This is used
+        #                               when generating the JSON schemas to determine whether or not
+        #                               to include a reference to the _plugin definition. If :_plugin
+        #                               is set to true, the script that generates JSON schemas will
+        #                               automatically recurse through the :items and :properties keys
+        #                               and add plugin references if applicable.
+        #
+        #   :_example       Any         An example value for the option. This is used to generate
+        #                               reference documentation for configuration files.
+        #
+        #   :_default       Any         The documented default value for the option. This is only
+        #                               used to generate reference documentation for configuration
+        #                               files and is not used by Bolt to actually set default values.
+        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
+          },
+          "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 may 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
+            },
+            propertyNames: {
+              pattern: "^.?[a-zA-Z0-9]+$"
+            },
+            _plugin: true,
+            _example: { "rb" => "/usr/bin/ruby" }
+          },
+          "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.",
+            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"
+          },
+          "realm" => {
+            type: String,
+            description: "The Kerberos realm (Active Directory domain) to authenticate against.",
+            _plugin: true,
+            _example: "BOLT.PRODUCTION"
+          },
+          "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"
+          },
+          "shell-command" => {
+            type: String,
+            description: "A shell command to wrap any Docker 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 flags 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