YAML Config Plugin

Relevant source files

The following files were used as context for generating this wiki page:

• plugin/yaml/yaml.go
• plugin/yaml/README.md
• plugin/yaml/main.go
• plugin/yaml/yaml_test.go
• e2e/yaml_test.go
• cmd/sshpiperd/internal/plugin/chain.go
• libplugin/plugin.proto

The YAML Config Plugin for sshpiperd is a routing module that enables the configuration of SSH proxy pipes using a single or multiple YAML files. It allows administrators to define mapping rules between downstream clients and upstream servers based on criteria such as usernames, regex matches, and authentication methods.

This plugin acts as a gRPC-based provider for sshpiperd, handling authentication callbacks—including password, public key, and SSH user certificates—to determine how a connection should be proxied. It supports advanced features like dynamic username expansion using regex capture groups and integration with HashiCorp Vault for sensitive key material.
Sources: plugin/yaml/README.md:1-5, plugin/yaml/main.go:13-18

Architecture and Data Flow

The plugin operates by loading YAML configurations and matching incoming connection metadata against defined pipes. Each pipe consists of a from section (matching criteria) and a to section (upstream destination).

Configuration Loading Flow

The plugin uses file globs to locate configuration files, verifies their permissions (defaulting to 0400), and unmarshals them into internal structures.

Matching Logic

When a connection is initiated, the plugin iterates through the loaded pipes top-to-bottom. The first pipe where the from criteria match the downstream authentication is selected.

Configuration Structure

The configuration follows a specific hierarchy defined in the piperConfig struct.

YAML Schema Components

Component	Description
version	The version of the config format (e.g., "1.0").
pipes	A list of pipe definitions, each containing a from and a to block.
from	Defines matching criteria: username, groupname, and username_regex_match.
to	Defines destination: host, username, private_key, known_hosts, and ignore_hostkey.
Sources: plugin/yaml/yaml.go:17-45, plugin/yaml/yaml.go:81-86

Data Structures

The plugin utilizes a listOrString type to allow configuration fields to accept either a single string or a list of strings, providing flexibility in defining file paths or inline data.

// plugin/yaml/yaml.go:47-50
type listOrString struct {
	List []string
	Str  string
}

Sources: plugin/yaml/yaml.go:47-50, plugin/yaml/yaml_test.go:57-79

Authentication Support

The plugin supports multiple authentication workflows for mapping downstream clients to upstreams.

Username and Regex Matching

• Static Match: Direct comparison of from.username.
• Regex Match: If username_regex_match is true, from.username is treated as a regular expression.
• Template Expansion: Capture groups from the from.username regex can be used in to.username using the $1, $2 syntax.
  Sources: plugin/yaml/README.md:12-16, plugin/yaml/README.md:46-61

Key and Certificate Management

The plugin can source authorized_keys, known_hosts, and private_keys from three locations:

1. Filesystem: standard file paths (e.g., authorized_keys).
2. Inline Data: Base64 encoded strings (e.g., authorized_keys_data).
3. Vault: Secret paths in HashiCorp Vault (e.g., authorized_keys_vault).

Multi-Source Loading Logic

When multiple sources are provided for keys (e.g., file and data), the plugin merges them. For private keys, the file-based configuration takes precedence over inline data.

Placeholders and Variables

The plugin supports "magic placeholders" in file paths for dynamic routing. These are expanded at runtime:

• $DOWNSTREAM_USER: The username provided by the client.
• $UPSTREAM_USER: The username used to connect to the target server.
• $ENV_VAR: Any system environment variables.
  Sources: plugin/yaml/README.md:25-29, plugin/yaml/yaml.go:179-188

Plugin Options

When starting the plugin via sshpiperd, the following flags are available:

Flag	Env Var	Default	Description
--config	SSHPIPERD_YAML_CONFIG	Required	Path to YAML config file(s), supports globs.
--no-check-perm	SSHPIPERD_YAML_NOCHECKPERM	false	Disables the 0400 permission check on config files.
Sources: plugin/yaml/main.go:20-33, plugin/yaml/README.md:34-40

Implementation Details

ListPipe Callback

The plugin implements the listPipe function (via the skel package) to interface with sshpiperd. It converts YAML structures into gRPC-compatible responses.

// cmd/sshpiperd/internal/plugin/chain.go:19-22
type ChainPlugins struct {
	pluginsCallback []*GrpcPluginConfig
	plugins         []*GrpcPlugin
}

Note: sshpiperd can chain multiple plugins together. The YAML plugin typically acts as the primary router in this chain.
Sources: cmd/sshpiperd/internal/plugin/chain.go:19-35, plugin/yaml/main.go:35-38

CA-Based Routing

The plugin enables routing the same downstream username to different upstream hosts based on the Issuing CA of the presented SSH User Certificate. This is achieved by defining multiple pipes for the same username but with different trusted_user_ca_keys.
Sources: plugin/yaml/README.md:104-123, e2e/yaml_test.go:49-65

Conclusion

The YAML Config Plugin provides a declarative way to manage SSH routing. By supporting regex, template expansion, and multiple secret backends (Files, Inline, Vault), it allows for complex proxy configurations while maintaining a simple, file-based administration model. Its integration with sshpiperd's gRPC plugin system ensures it can handle diverse authentication methods seamlessly.
Sources: plugin/yaml/README.md:1-5, plugin/yaml/yaml.go:88-109