@@ -116,7 +116,14 @@ The `puppetfile` section of the configuration file configures how to retrieve mo
 
 ## Transport configuration options
 
-Transport configuration options can be set in both the configuration file and inventory file.
+Transport configuration options can be set in the inventory file. Options at
+the inventory's top level will apply to all targets.
+
+### The transport option
+
+<% @transport_option[:options].each do |option, desc| -%>
+| `<%= option %>` | <%= desc %> | <%= @transport_option[:defaults][option].to_s %> |
+<% end %>
 
 <% @transports[:options].each do |transport, options| %>
 ### <%= transport %>
# Bolt configuration options

## Global configuration options

Global configuration options can be set in the configuration file.

| Option | Description | Default |
| ------ | ----------- | ------- |
<% @global[:options].each do |option, desc| -%>
| `<%= option %>` | <%= desc %> | <%= @global[:defaults][option].to_s || "" %> |
<% end %>

## Log file configuration options

You can configure how the results of plan runs are captured in a log file. Different log files can be configured by specifying the log file's location using either `console` or a path to the log file, such as `~/.puppetlabs/bolt/debug.log`.

| Option | Description | Default |
| ------ | ----------- | ------- |
<% @log[:options].each do |option, desc| -%>
| `<%= option %>` | <%= desc %> | <%= @log[:defaults][option].to_s %> |
<% end %>

### Example configuration

Setting log configuration in the configuration file:

```yaml
log:
  console:
    level: error
  ~/.puppetlabs/bolt/debug.log:
    level: debug
```

## Plugin hooks configuration options

The `plugin_hooks` section allows you to configure which plugins a specific hook should use for a specific target. This section is a hash where keys are hook names, and values specify and configure the plugin that that hook should use. There are two possible plugins: the `install_agent` plugin runs the `puppet_agent::install` task, and the `task` plugin runs your own custom task.

For now, the only configurable plugin hook is `puppet_library`.

The default is to use the `puppet_agent` plugin with the agent service stopped:

```yaml
plugin_hooks:
  puppet_library:
    plugin: puppet_agent
    stop_service: true
```

The `puppet_agent::install` task will error if it's not run as root. To ensure this plugin to succeeds on non-root targets set `_run_as: true` for the `puppet_agent` plugin.

```yaml
plugin_hooks:
  puppet_library:
    plugin: puppet_agent
    _run_as: root
```

You can use the `bootstrap` task to connect all targets to a PE master instead:

```yaml
plugin_hooks:
  puppet_library:
    plugin: task
    _run_as: root
    task: 'bootstrap'
    parameters:
      master: 'puppet.example.com'
      cacert_content: <CERT>
```

You can also configure `plugin_hooks` using [`_plugin` references](https://puppet.com/docs/bolt/latest/using_plugins.html):

```yaml
plugin_hooks:
  puppet_library:
    plugin: puppet_agent
    version:
      _plugin: prompt
      message: "Which version of Puppet do you want to install?"
```

## Project configuration options

> **Note:** Project configuration is experimental

Use `<PROJECT_NAME>/bolt-project.yaml` to configure your [Bolt
project](experimental_features.md#bolt-projects). You can define the following settings:

| Option | Description | Default |
| ------ | ----------- | ------- |
<% @project[:options].each do |option, desc| -%>
| `<%= option %>` | <%= desc %> | <%= @project[:defaults][option].to_s %> |
<% end %>

## Apply options

Apply options are a subset of [Puppet configuration settings](https://puppet.com/docs/puppet/latest/configuration.html) which are set when Bolt applies Puppet code on remote targets. Users can define values for the following Puppet settings:

| Option | Description | Default |
| ------ | ----------- | ------- |
<% @apply[:options].each do |option, desc| -%>
| `<%= option %>` | <%= desc %> | <%= @apply[:defaults][option].to_s %> |
<% end %>


## Puppetfile configuration options

The `puppetfile` section of the configuration file configures how to retrieve modules when running `bolt puppetfile install`.

| Option | Description |
| ------ | ----------- |
<% @puppetfile[:options].each do |option, desc| -%>
| `<%= option %>` | <%= desc %> |
<% end %>

## Transport configuration options

Transport configuration options can be set in both the configuration file and inventory file.

<% @transports[:options].each do |transport, options| %>
### <%= transport %>

<% if transport == 'ssh' %>
| Option | Description | External SSH | Type | Default |
| ------ | ----------- | :----------: | ---- | ------- |
<% options.each do |option, data| -%>
  | `<%= option %>` | <%= data[:desc] %> | <%= data[:external] == true ? 'Yes' : '' %> | <%= data[:type] == TrueClass ? 'Boolean' : data[:type] %> | <%= @transports[:defaults][transport][option].to_s || "" %> |
<% end %>
<% else %>
| Option | Description | Type | Default |
| ------ | ----------- | ---- | ------- |
<% options.each do |option, data| -%>
| `<%= option %>` | <%= data[:desc] %> | <%= data[:type] == TrueClass ? 'Boolean' : data[:type] %> | <%= @transports[:defaults][transport][option].to_s || "" %> |
<% end %>
<%end%>

<% if transport == 'ssh' %>
#### OpenSSH

In addition to the SSH transport options, some additional SSH options are read from OpenSSH configuration files, including `~/.ssh/config`, `/etc/ssh_config`, and `/etc/ssh/ssh_config`. Not all OpenSSH configuration values have equivalents in Bolt.

These are the options configurable in OpenSSH files:

| Option | Description |
| ------ | ----------- |
| `Ciphers` | Ciphers allowed in order of preference. Multiple ciphers must be comma-separated. |
| `Compression` | Whether to use compression. |
| `CompressionLevel` | Compression level to use if compression is enabled. |
| `GlobalKnownHostsFile` | Path to global host key database. |
| `HostKeyAlgorithms` | Host key algorithms that the client wants to use in order of preference. |
| `HostKeyAlias` | Use alias instead of real hostname when looking up or saving the host key in the host key database file. |
| `HostName` | Host name to log. |
| `IdentityFile` | File in which user's identity key is stored. |
| `Port` | SSH port. |
| `StrictHostKeyChecking` | Prevents SSH from automatically adding host keys to the known hosts file, and refuses to connect to a host whose host key has changed. |
| `User` | Login user. |
| `UserKnownHostsFile` | Path to local user's host key database. |

> **Note:** For OpenSSH configuration options with direct equivalents in Bolt, such as user and port, the settings in Bolt config take precedence.

To illustrate, consider this example:

```yaml
targets:
  - name: host1.example.net
    config:
      transport: ssh
      ssh:
        host-key-check: true
        port: 22
        private-key: ~/.ssh/id_rsa-example
```

```
Host *.example.net
  UserKnownHostsFile=~/.ssh/known_hosts
  User root
  Port 444
```

In this example, the SSH connection is configured to use the user and known hosts file defined in OpenSSH config and the port defined in Bolt's config.

> **Note:** The `host-key-check` option must be set in Bolt config because the `StrictHostKeyChecking` OpenSSH configuration value is ignored.

When using the SSH transport, Bolt also interacts with the ssh-agent for SSH key management. The most common interaction is to handle password protected private keys. When a private key is password protected it must be added to the ssh-agent in order to be used to authenticate Bolt SSH connections.
<% end %>
<% end %>

Definitely work for another ticket, but I think we need to look at creating separate ref pages for each config/inventory file. This is quickly getting confusing.  