Module: Bolt::Config::Transport::Options

Included in:

Base

Defined in:

lib/bolt/config/transport/options.rb

Constant Summary

LOGIN_SHELLS =

%w[sh bash zsh dash ksh powershell].freeze

TRANSPORT_OPTIONS =

Definitions used to validate config options. github.com/puppetlabs/bolt/blob/main/schemas/README.md

{
  "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
  },
  "task-agent" => {
    type: String,
    description: "Which Choria agent to use for task execution. Defaults to 'bolt_tasks' " \
                 "(downloads task files from a Puppet Server). Set to 'shell' for tasks " \
                 "not available on the Puppet Server.",
    _plugin: true,
    _example: "shell"
  },
  "collective" => {
    type: String,
    description: "The Choria collective to target. Overrides the main_collective from the Choria " \
                 "client configuration file.",
    _plugin: true,
    _example: "production"
  },
  "command-timeout" => {
    type: Integer,
    description: "How long to wait in seconds for commands and scripts to complete when using the " \
                 "Choria transport.",
    minimum: 1,
    _plugin: true,
    _default: 60,
    _example: 120
  },
  "config-file" => {
    type: String,
    description: "The path to the Choria or MCollective client configuration file.",
    _plugin: true,
    _example: "/etc/choria/client.conf"
  },
  "broker-timeout" => {
    type: Integer,
    description: "How long to wait in seconds for the initial TCP connection to a Choria broker. " \
                 "If the connection cannot be made within this time, the operation fails.",
    minimum: 1,
    _plugin: true,
    _default: 30,
    _example: 60
  },
  "rpc-timeout" => {
    type: Integer,
    description: "How long to wait in seconds for nodes to respond to an RPC request. " \
                 "Used for lightweight operations like agent discovery, shell.start, and " \
                 "shell.list polling. Distinct from command-timeout and task-timeout which " \
                 "govern the overall duration of commands and tasks.",
    minimum: 1,
    _plugin: true,
    _default: 30,
    _example: 60
  },
  "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]
  },
  "mcollective-certname" => {
    type: String,
    description: "Override the MCollective certname used for Choria client identity. " \
                 "The choria-mcorpc-support library identifies non-root clients as " \
                 "'<username>.mcollective'. Set this when authenticating with a certificate " \
                 "whose CN differs from that default (e.g. the host's Puppet cert).",
    _plugin: true,
    _example: "primary.example.com"
  },
  "brokers" => {
    type: [String, Array],
    description: "One or more Choria broker addresses in host or host:port format. " \
                 "Port defaults to 4222 if omitted. Do not use the nats:// prefix. " \
                 "Overrides the middleware hosts from the Choria client configuration file. " \
                 "Can be a single string or an array.",
    items: {
      type: String
    },
    _plugin: true,
    _example: ["broker1:4222", "broker2:4222"]
  },
  "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"
  },
  "puppet-environment" => {
    type: String,
    description: "The Puppet environment to use when constructing task file URIs for the Choria " \
                 "bolt_tasks agent.",
    _plugin: true,
    _default: "production",
    _example: "staging"
  },
  "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
  },
  "ssl-ca" => {
    type: String,
    description: "The path to the CA certificate for Choria TLS connections. Overrides the CA " \
                 "from the Choria client configuration file.",
    _plugin: true,
    _example: "/etc/choria/ssl/ca.pem"
  },
  "ssl-cert" => {
    type: String,
    description: "The path to the client certificate for Choria TLS connections. Overrides the " \
                 "certificate from the Choria client configuration file.",
    _plugin: true,
    _example: "/etc/choria/ssl/client.pem"
  },
  "ssl-key" => {
    type: String,
    description: "The path to the client private key for Choria TLS connections. Overrides the " \
                 "key from the Choria client configuration file.",
    _plugin: true,
    _example: "/etc/choria/ssl/client-key.pem"
  },
  "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"
  },
  "task-timeout" => {
    type: Integer,
    description: "How long to wait in seconds for tasks to complete when using the Choria transport.",
    minimum: 1,
    _plugin: true,
    _default: 300,
    _example: 300
  },
  "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