### WireGuard Configuration Output Example

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/05-config-document-datasource.md

An example of the rendered WireGuard configuration in wg-quick format.

```ini
[Interface]
PrivateKey = ELKJDSLKJDLjsldkj+sldk/dskldjskldj+skld=
ListenPort = 51820
Address = 10.0.0.1/24
DNS = 1.1.1.1,1.0.0.1
PreUp = iptables -A FORWARD -i %i -j ACCEPT
PostUp = iptables -A FORWARD -o %i -j ACCEPT
PostDown = iptables -D FORWARD -i %i -j ACCEPT
PostDown = iptables -D FORWARD -o %i -j ACCEPT

[Peer]
# Example peer
PublicKey = Lj/ksdjlkjsldkj+sldk/dsjdksljdksl+dskld=
PresharedKey = sreVpk9zmgdSV1zYk6pJ+SqolQwVuRKGYoEFmb4/h1k=
AllowedIPs = 10.0.0.2/32
Endpoint = peer.example.com:51820
PersistentKeepalive = 25
```

--------------------------------

### Install Build Tools

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/10-dependencies.md

Commands to download module dependencies and install the documentation generator tool.

```bash
go mod download
go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@v0.21.0
```

--------------------------------

### Configure Multi-valued Arguments

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/07-configuration.md

Examples of defining sets, lists, and nested blocks for provider resources.

```hcl
# Set (unordered)
addresses = ["10.0.0.1/24", "fd00::1/64"]

# List (ordered)
pre_up = [
  "echo 1 > /proc/sys/net/ipv4/ip_forward",
  "modprobe wireguard"
]

# Blocks (ordered list of maps)
peer {
  public_key  = "..."
  allowed_ips = ["10.0.0.2/32"]
}

peer {
  public_key  = "..."
  allowed_ips = ["10.0.0.3/32"]
}
```

--------------------------------

### Terraform provider usage example

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/02-provider-api.md

Example configuration for the wireguard provider and a resource usage.

```hcl
provider "wireguard" {
  # No configuration options required
}

resource "wireguard_asymmetric_key" "server" {
  # Resource will use Provider() internally
}
```

--------------------------------

### Terraform Plugin Initialization Hierarchy

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/11-module-map.md

Visual representation of the plugin initialization sequence starting from the Terraform CLI.

```text
Terraform CLI
    └── plugin.Serve() [from main.go]
        └── ProviderFunc callback
            └── provider.Provider()
                └── Registers resources and data sources
                    ├── resourceWireguardAsymmetricKey()
                    ├── resourceWireguardPresharedKey()
                    └── dataSourceWireguardConfigDocument()
```

--------------------------------

### Valid Base64 Key Example

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/08-errors.md

A sample string representing a valid base64 encoded key.

```text
ELKJDSLKJDLjsldkj+sldk/dskldjskldj+skld=
```

--------------------------------

### Configure wireguard_preshared_key resource

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/04-preshared-key-resource.md

Example of generating a preshared key and using it within a peer configuration.

```hcl
# Generate a new preshared key
resource "wireguard_preshared_key" "peer2" {
}

output "preshared_key" {
  value     = wireguard_preshared_key.peer2.key
  sensitive = true
}

# Use in peer configuration
data "wireguard_config_document" "peer1" {
  private_key = wireguard_asymmetric_key.peer1.private_key
  
  peer {
    public_key    = wireguard_asymmetric_key.peer2.public_key
    preshared_key = wireguard_preshared_key.peer2.key
    allowed_ips   = ["10.0.0.2/32"]
  }
}
```

--------------------------------

### Config Document Data Source Error Example

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/08-errors.md

Example of an error returned when the wireguard_config_document data source fails to parse a provided private key.

```text
Error: failed to read data source
  on main.tf line 5, in data "wireguard_config_document" "peer1":
   5:   private_key = wireguard_asymmetric_key.peer1.private_key

Error Details:
invalid key: length mismatch
```

--------------------------------

### Example Usage

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/docs/index.md

Example usage of the WireGuard provider.

```terraform
provider "wireguard" {
}

```

--------------------------------

### Define a WireGuard configuration document

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/07-configuration.md

Example usage of the wireguard_config_document data source to define interface settings, wg-quick options, and multiple peer configurations.

```hcl
data "wireguard_config_document" "gateway" {
  private_key  = wireguard_asymmetric_key.gateway.private_key
  listen_port  = 51820
  firewall_mark = "0x4711"

  # wg-quick options
  addresses    = ["10.0.0.1/24", "fd00::1/64"]
  dns          = ["8.8.8.8", "8.8.4.4"]
  mtu          = 1420
  routing_table = "200"

  pre_up = [
    "echo 1 > /proc/sys/net/ipv4/ip_forward"
  ]

  post_up = [
    "iptables -A FORWARD -i %i -j ACCEPT",
    "iptables -A FORWARD -o %i -j ACCEPT",
    "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE"
  ]

  post_down = [
    "iptables -D FORWARD -i %i -j ACCEPT",
    "iptables -D FORWARD -o %i -j ACCEPT",
    "iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE"
  ]

  # Peer configuration
  peer {
    public_key           = wireguard_asymmetric_key.client1.public_key
    preshared_key        = wireguard_preshared_key.client1.key
    allowed_ips          = ["10.0.0.2/32"]
    endpoint             = "203.0.113.5:51820"
    persistent_keepalive = 25
    description          = "Client 1\nProduction VPN endpoint"
  }

  peer {
    public_key  = wireguard_asymmetric_key.client2.public_key
    allowed_ips = ["10.0.0.3/32", "fd00::3/128"]
    description = "Client 2"
  }
}
```

--------------------------------

### Example Usage

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/docs/resources/asymmetric_key.md

Example usage of the wireguard_asymmetric_key resource to generate and output public and private keys.

```terraform
resource "wireguard_asymmetric_key" "example" {
}

output "wg_public_key" {
  description = "Example's public WireGuard key"
  value       = wireguard_asymmetric_key.example.public_key
}

output "wg_private_key" {
  description = "Example's private WireGuard key"
  value       = wireguard_asymmetric_key.example.private_key
  sensitive   = true
}
```

--------------------------------

### Asymmetric Key Resource Error Examples

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/08-errors.md

Common errors encountered when providing invalid private key strings to the wireguard_asymmetric_key resource.

```text
Error: invalid key: length mismatch
  on main.tf line 3, in resource "wireguard_asymmetric_key" "example":
   3:   private_key = "toolshort"

Error: invalid base64 encoding
  on main.tf line 3, in resource "wireguard_asymmetric_key" "example":
   3:   private_key = "!!!invalid!!!"
```

--------------------------------

### Example Usage

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/docs/data-sources/config_document.md

Example of how to use the wireguard_config_document data source to configure a WireGuard peer.

```HCL
data "wireguard_config_document" "peer1" {
  private_key = wireguard_asymmetric_key.peer1.private_key
  listen_port = 1234
  dns = [
    "1.1.1.1",
    "1.0.0.1",
    "2606:4700:4700:0:0:0:0:64",
    "2606:4700:4700:0:0:0:0:6400",
  ]
  routing_table = "123"

  peer {
    public_key    = wireguard_asymmetric_key.peer2.public_key
    preshared_key = wireguard_preshared_key.peer2.key
    allowed_ips = [
      "0.0.0.0/0",
    ]
    persistent_keepalive = 25
  }

  peer {
    public_key = wireguard_asymmetric_key.peer3.public_key
    endpoint   = "example.com:51820"
    allowed_ips = [
      "::/0",
    ]
  }
}

output "peer1" {
  value     = data.wireguard_config_document.peer1.conf
  sensitive = true
}
```

--------------------------------

### Configure Asymmetric Key Resource

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/03-asymmetric-key-resource.md

Examples for auto-generating a key pair or supplying an existing private key in Terraform configuration.

```hcl
# Auto-generate a key pair
resource "wireguard_asymmetric_key" "server" {
}

# Supply an existing private key
resource "wireguard_asymmetric_key" "existing" {
  private_key = "ELKJDSLKJDLjsldkj+sldk/dskldjskldj+skld="
}

output "public_key" {
  value = wireguard_asymmetric_key.server.public_key
}

output "private_key" {
  value     = wireguard_asymmetric_key.server.private_key
  sensitive = true
}
```

--------------------------------

### Example Usage

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/docs/resources/preshared_key.md

Provides a WireGuard key resource. This can be used to create, read, and delete WireGuard preshared keys in terraform state.

```terraform
resource "wireguard_preshared_key" "example" {
}

output "wg_preshared_key" {
  description = "Example's preshared WireGuard key"
  value       = wireguard_preshared_key.example.key
  sensitive   = true
}
```

--------------------------------

### Build for multiple platforms

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/10-dependencies.md

Use these commands to compile the provider for specific operating systems and architectures.

```bash
# Build for multiple platforms
GOOS=linux GOARCH=amd64 go build -o terraform-provider-wireguard_linux_amd64
GOOS=darwin GOARCH=amd64 go build -o terraform-provider-wireguard_darwin_amd64
GOOS=windows GOARCH=amd64 go build -o terraform-provider-wireguard_windows_amd64.exe
```

--------------------------------

### Configure wireguard_asymmetric_key Resource

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/07-configuration.md

Demonstrates generating new keys, importing existing private keys, and binding key lifecycles to other resources.

```hcl
# Generate new key pair
resource "wireguard_asymmetric_key" "example" {
}

# Use existing key
resource "wireguard_asymmetric_key" "imported" {
  private_key = "ELKJDSLKJDLjsldkj+sldk/dskldjskldj+skld="
}

# Tie to another resource
resource "wireguard_asymmetric_key" "bound" {
  bind = aws_instance.vpn.id
}
```

--------------------------------

### Bootstrap the Terraform Plugin

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/11-module-map.md

The main entry point for the provider, responsible for initializing the plugin server.

```go
package main

import (
    "github.com/OJFord/terraform-provider-wireguard/provider"
    "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
    "github.com/hashicorp/terraform-plugin-sdk/v2/plugin"
)

func main() {
    plugin.Serve(&plugin.ServeOpts{
        ProviderFunc: func() *schema.Provider {
            return provider.Provider()
        },
    })
}
```

--------------------------------

### Initialize WireGuard Provider

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/07-configuration.md

The provider requires no arguments for initialization.

```hcl
provider "wireguard" {
  # No configuration options available
}
```

--------------------------------

### Manage Go dependencies

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/10-dependencies.md

Commands for updating, cleaning, and maintaining project dependencies.

```bash
# Update all dependencies
go get -u

# Update specific dependency
go get -u github.com/hashicorp/terraform-plugin-sdk/v2

# Clean up unused dependencies
go mod tidy
```

--------------------------------

### Invalid Asymmetric Key Configuration

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/08-errors.md

Example of a Terraform configuration that triggers a base64 validation error.

```hcl
# terraform configuration
resource "wireguard_asymmetric_key" "bad_key" {
  private_key = "not-a-valid-base64-key-!!!"
}
```

--------------------------------

### Import and use Terraform Plugin SDK

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/10-dependencies.md

Core SDK components used for defining provider schemas and initializing the plugin server.

```go
import "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
import "github.com/hashicorp/terraform-plugin-sdk/v2/plugin"

// From SDK
schema.Provider{}
schema.Resource{}
schema.TypeString
schema.TypeInt
schema.TypeSet
schema.TypeList
plugin.Serve()
```

--------------------------------

### Configure Simple VPN Peer

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/09-examples.md

Sets up a basic peer configuration using asymmetric keys and a preshared key.

```hcl
resource "wireguard_asymmetric_key" "peer1" {
}

resource "wireguard_asymmetric_key" "peer2" {
}

resource "wireguard_preshared_key" "shared" {
}

# Configuration for peer 1
data "wireguard_config_document" "peer1_config" {
  private_key = wireguard_asymmetric_key.peer1.private_key
  listen_port = 51820

  peer {
    public_key    = wireguard_asymmetric_key.peer2.public_key
    preshared_key = wireguard_preshared_key.shared.key
    allowed_ips   = ["10.0.0.2/32"]
    endpoint      = "peer2.example.com:51820"
  }
}

output "peer1_wg_config" {
  value     = data.wireguard_config_document.peer1_config.conf
  sensitive = true
}
```

--------------------------------

### Configure wireguard_preshared_key Resource

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/07-configuration.md

Shows the creation of a preshared key and how to output the sensitive key value.

```hcl
resource "wireguard_preshared_key" "example" {
}

output "psk" {
  value     = wireguard_preshared_key.example.key
  sensitive = true
}
```

--------------------------------

### Project File Structure

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/README.md

Displays the directory layout of the provider source code.

```text
provider/
├── provider.go                           # Main provider factory
├── resource_wireguard_asymmetric_key.go  # Asymmetric key resource
├── resource_wireguard_preshared_key.go   # Preshared key resource
└── data_source_wireguard_config_document.go  # Config document data source
main.go                                  # Plugin entry point
```

--------------------------------

### Define WgQuickConfig structure

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/05-config-document-datasource.md

Contains extended wg-quick options that are not part of the standard WireGuard kernel interface.

```go
type WgQuickConfig struct {
  Addresses    []string
  DNS          []string
  MTU          *int
  RoutingTable *string
  PreUp        []string
  PostUp       []string
  PreDown      []string
  PostDown     []string
}
```

--------------------------------

### Initialize Provider Entry Point

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/README.md

The primary exported function for configuring the Terraform provider.

```go
// File: provider/provider.go
func Provider() *schema.Provider
```

--------------------------------

### Project File Structure

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/MANIFEST.md

Displays the directory layout of the documentation files.

```text
output/
├── README.md                              (start here)
├── INDEX.md                               (navigation guide)
├── MANIFEST.md                            (this file)
├── 01-overview.md                         (project overview)
├── 02-provider-api.md                     (provider factory)
├── 03-asymmetric-key-resource.md          (key pair resource)
├── 04-preshared-key-resource.md           (PSK resource)
├── 05-config-document-datasource.md       (config data source)
├── 06-types.md                            (type definitions)
├── 07-configuration.md                    (configuration reference)
├── 08-errors.md                           (error reference)
├── 09-examples.md                         (usage examples)
├── 10-dependencies.md                     (dependencies)
├── 11-module-map.md                       (module structure)
└── 12-cryptographic-operations.md         (cryptography)
```

--------------------------------

### Define WgPeerConfig structure

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/05-config-document-datasource.md

Represents configuration for a single peer, supporting multiple comment lines.

```go
type WgPeerConfig struct {
  PublicKey           string
  Comments            []string
  PresharedKey        *string
  AllowedIPs          []string
  Endpoint            *string
  PersistentKeepalive *int
}
```

--------------------------------

### Define WgConfig structure

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/05-config-document-datasource.md

Aggregates all interface and peer settings into a single configuration object.

```go
type WgConfig struct {
  PrivateKey   *string
  ListenPort   *int
  FirewallMark *string
  WgQuickConfig
  Peers        []WgPeerConfig
}
```

--------------------------------

### Import and use WireGuard wgctrl library

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/10-dependencies.md

Cryptographic utilities for generating and parsing WireGuard keys.

```go
import "golang.zx2c4.com/wireguard/wgctrl/wgtypes"

// From wgctrl
wgtypes.GeneratePrivateKey()  // Returns Key, error
wgtypes.GenerateKey()         // Returns Key, error
wgtypes.ParseKey(string)      // Returns Key, error
wgtypes.Key                   // Type with methods
key.PublicKey()               // Returns Key
key.String()                  // Returns base64 string
```

--------------------------------

### Visualize Module Dependency Graph

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/11-module-map.md

Represents the call hierarchy from the main entry point through provider resources and data sources.

```text
main.go
└── provider.Provider()
    ├── resourceWireguardAsymmetricKey()
    │   ├── resourceWireguardAsymmetricKeyCreate
    │   ├── resourceWireguardAsymmetricKeyRead
    │   ├── resourceWireguardAsymmetricKeyDelete
    │   └── resourceWireguardAsymmetricKeyImport
    ├── resourceWireguardPresharedKey()
    │   ├── resourceWireguardPresharedKeyCreate
    │   ├── resourceWireguardPresharedKeyRead
    │   ├── resourceWireguardPresharedKeyDelete
    │   └── resourceWireguardPresharedKeyImport
    └── dataSourceWireguardConfigDocument()
        ├── dataSourceWireguardConfigDocumentRead
        ├── wgTemplate (compiled)
        ├── WgConfig (type)
        ├── WgQuickConfig (type)
        └── WgPeerConfig (type)
```

--------------------------------

### Import wireguard_asymmetric_key

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/07-configuration.md

Use this command to import an existing asymmetric key pair into Terraform state using the base64-encoded private key.

```bash
terraform import wireguard_asymmetric_key.NAME "PRIVATE_KEY_BASE64"
```

--------------------------------

### Export Configuration to Local Files

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/09-examples.md

Write generated WireGuard configurations and private keys to the local filesystem with restricted permissions.

```hcl
resource "local_file" "peer1_config" {
  content              = data.wireguard_config_document.peer1_config.conf
  filename             = "${path.module}/peer1.conf"
  file_permission      = "0600"
  sensitive_content    = true
}

resource "local_file" "peer1_private_key" {
  content              = wireguard_asymmetric_key.peer1.private_key
  filename             = "${path.module}/peer1_private.key"
  file_permission      = "0600"
  sensitive_content    = true
}
```

--------------------------------

### Define WgPeerConfig struct

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/06-types.md

Represents the configuration schema for a single WireGuard peer within the data source.

```go
type WgPeerConfig struct {
    PublicKey           string
    Comments            []string
    PresharedKey        *string
    AllowedIPs          []string
    Endpoint            *string
    PersistentKeepalive *int
}
```

--------------------------------

### Enable Go module verification

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/10-dependencies.md

Set the environment variable to ensure module integrity during builds.

```bash
export GOSUMDB=on
```

--------------------------------

### Import Existing Keys

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/README.md

Commands to import existing WireGuard keys into the Terraform state.

```bash
terraform import wireguard_asymmetric_key.example "PRIVATE_KEY_BASE64"
terraform import wireguard_preshared_key.example "PRESHARED_KEY_BASE64"
```

--------------------------------

### Configuration Template Definition

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/05-config-document-datasource.md

The Go text template used to generate the configuration file content.

```text
[Interface]
{{- if .PrivateKey }}
PrivateKey = {{ .PrivateKey }}
{{- end }}
{{- if .ListenPort }}
ListenPort = {{ .ListenPort }}
{{- end }}
{{- range .Addresses }}
Address = {{ . }}
{{- end }}
{{- range .PostUp }}
PostUp = {{ . }}
{{- end }}
{{- range .Peers }}

[Peer]
PublicKey = {{ .PublicKey }}
{{- if .PresharedKey }}
PresharedKey = {{ .PresharedKey }}
{{- end }}
{{- range .AllowedIPs }}
AllowedIPs = {{ . }}
{{- end }}
{{- end }}
```

--------------------------------

### Import wireguard_preshared_key via CLI

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/04-preshared-key-resource.md

Command to import an existing preshared key into Terraform state.

```bash
# Import by preshared key
terraform import wireguard_preshared_key.existing "sreVpk9zmgdSV1zYk6pJ+SqolQwVuRKGYoEFmb4/h1k="
```

--------------------------------

### Define wireguard_preshared_key import operation

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/04-preshared-key-resource.md

Imports an existing preshared key by its base64-encoded value.

```go
func resourceWireguardPresharedKeyImport(d *schema.ResourceData, m interface{}) ([]*schema.ResourceData, error)
```

--------------------------------

### Define Go module dependencies

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/10-dependencies.md

The go.mod file specifies the required Terraform SDK and WireGuard control packages.

```go
module github.com/OJFord/terraform-provider-wireguard

go 1.25.8

require (
    github.com/hashicorp/terraform-plugin-docs v0.21.0
    github.com/hashicorp/terraform-plugin-sdk/v2 v2.40.1
    golang.zx2c4.com/wireguard/wgctrl v0.0.0-20230215201556-9c5414ab4bde
)
```

--------------------------------

### Convert Key to String

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/12-cryptographic-operations.md

Returns the base64-encoded string representation of a key object.

```go
func (k Key) String() string
```

--------------------------------

### Define WgQuickConfig struct

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/06-types.md

Extended configuration fields for wg-quick and user-space applications, embedded within WgConfig.

```go
type WgQuickConfig struct {
    Addresses    []string
    DNS          []string
    MTU          *int
    RoutingTable *string
    PreUp        []string
    PostUp       []string
    PreDown      []string
    PostDown     []string
}
```

--------------------------------

### Generate WireGuard Configuration Document

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/05-config-document-datasource.md

Defines asymmetric keys, a preshared key, and a configuration document for a WireGuard peer.

```hcl
# Create asymmetric keys
resource "wireguard_asymmetric_key" "peer1" {
}

resource "wireguard_asymmetric_key" "peer2" {
}

# Create a preshared key
resource "wireguard_preshared_key" "psk" {
}

# Generate config for peer1
data "wireguard_config_document" "peer1_config" {
  private_key = wireguard_asymmetric_key.peer1.private_key
  listen_port = 51820
  
  addresses = ["10.0.0.1/24"]
  dns       = ["1.1.1.1", "1.0.0.1"]
  mtu       = 1420
  
  post_up = [
    "iptables -A FORWARD -i %i -j ACCEPT",
    "iptables -A FORWARD -o %i -j ACCEPT"
  ]
  post_down = [
    "iptables -D FORWARD -i %i -j ACCEPT",
    "iptables -D FORWARD -o %i -j ACCEPT"
  ]
  
  peer {
    public_key           = wireguard_asymmetric_key.peer2.public_key
    preshared_key        = wireguard_preshared_key.psk.key
    allowed_ips          = ["10.0.0.2/32"]
    endpoint             = "peer2.example.com:51820"
    persistent_keepalive = 25
    description          = "Peer 2\nExample VPN endpoint"
  }
}

output "peer1_config" {
  value     = data.wireguard_config_document.peer1_config.conf
  sensitive = true
}
```

--------------------------------

### Define wireguard_preshared_key create operation

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/04-preshared-key-resource.md

Generates a new random WireGuard preshared key.

```go
func resourceWireguardPresharedKeyCreate(d *schema.ResourceData, m interface{}) error
```

--------------------------------

### Validate Configuration with Terraform Console and Plan

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/08-errors.md

Use terraform console to inspect key values and terraform plan to verify data source outputs before applying changes.

```hcl
# Validate keys before importing
terraform console
> wireguard_asymmetric_key.existing.private_key
"..."  # Should be valid base64

# Validate data source before apply
terraform plan -out=tfplan
# Review the conf output value
```

--------------------------------

### Render WireGuard Configuration

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/README.md

Data source usage for generating a complete wg-quick configuration document.

```hcl
data "wireguard_config_document" "example" {
  private_key = wireguard_asymmetric_key.example.private_key
  listen_port = 51820
  peer { ... }
}
```

--------------------------------

### Import

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/docs/resources/asymmetric_key.md

Import command for an existing wireguard_asymmetric_key resource.

```shell
terraform import wireguard_asymmetric_key.example "EFr5/97eoK32SeMingmUqJpE4TL21nckcl2jQ9ZT82g="
```

--------------------------------

### Import Existing Key Pair

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/03-asymmetric-key-resource.md

Command to import an existing WireGuard key pair into Terraform state using the private key.

```bash
# Import by private key
terraform import wireguard_asymmetric_key.existing "ELKJDSLKJDLjsldkj+sldk/dskldjskldj+skld="
```

--------------------------------

### Define Configuration Data Source Types

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/11-module-map.md

Internal type definitions used for generating WireGuard configuration documents.

```go
type WgPeerConfig struct { ... }      // Line 231-238
type WgQuickConfig struct { ... }     // Line 240-249
type WgConfig struct { ... }          // Line 251-257
```

--------------------------------

### Define wireguard_preshared_key resource schema

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/04-preshared-key-resource.md

Defines the schema and lifecycle handlers for the preshared key resource.

```go
func resourceWireguardPresharedKey() *schema.Resource
```

--------------------------------

### Import

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/docs/resources/preshared_key.md

Import is supported using the following syntax:

```shell
terraform import wireguard_preshared_key.example "sreVpk9zmgdSV1zYk6pJ+SqolQwVuRKGYoEFmb4/h1k="
```

--------------------------------

### Define WireGuard configuration structure

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/06-types.md

Internal configuration hierarchy showing the relationship between WgConfig, WgQuickConfig, and WgPeerConfig.

```text
WgConfig
├── PrivateKey *string
├── ListenPort *int
├── FirewallMark *string
├── WgQuickConfig (embedded)
│   ├── Addresses []string
│   ├── DNS []string
│   ├── MTU *int
│   ├── RoutingTable *string
│   ├── PreUp []string
│   ├── PostUp []string
│   ├── PreDown []string
│   └── PostDown []string
└── Peers []WgPeerConfig
    └── [each peer]
        ├── PublicKey string
        ├── Comments []string
        ├── PresharedKey *string
        ├── AllowedIPs []string
        ├── Endpoint *string
        └── PersistentKeepalive *int
```

--------------------------------

### Generate Preshared Key

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/12-cryptographic-operations.md

Generates a 32-byte random symmetric key for post-quantum resistance.

```go
func GenerateKey() (Key, error)
```

--------------------------------

### Manage Multi-Environment WireGuard Configurations

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/09-examples.md

Use Terraform locals to switch between environment-specific settings like listen ports and DNS servers.

```hcl
variable "environment" {
  default = "dev"
}

locals {
  env_config = {
    dev = {
      listen_port     = 51820
      interface_cidrs = ["10.0.0.1/24"]
      dns_servers     = ["8.8.8.8"]
    }
    prod = {
      listen_port     = 51820
      interface_cidrs = ["10.100.0.1/24"]
      dns_servers     = ["1.1.1.1", "1.0.0.1"]
    }
  }
  current = local.env_config[var.environment]
}

resource "wireguard_asymmetric_key" "env_server" {
}

data "wireguard_config_document" "env_config" {
  private_key = wireguard_asymmetric_key.env_server.private_key
  listen_port = local.current.listen_port
  addresses   = local.current.interface_cidrs
  dns         = local.current.dns_servers
  # ... peer configuration
}
```

--------------------------------

### Generate SHA256 Hash for Preshared Key

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/12-cryptographic-operations.md

Uses the standard library to create a 32-byte SHA256 hash from a base64-encoded key string.

```go
import "crypto/sha256"

hash := sha256.Sum256([]byte(key.String()))
```

--------------------------------

### Parse and Validate Key

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/12-cryptographic-operations.md

Decodes a base64 string and validates that it represents a 32-byte key.

```go
func ParseKey(s string) (Key, error)
```

--------------------------------

### Dependency Tree

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/10-dependencies.md

Visual representation of the project's dependency hierarchy.

```text
terraform-provider-wireguard
├── github.com/hashicorp/terraform-plugin-sdk/v2
│   ├── github.com/hashicorp/go-hclog
│   ├── github.com/hashicorp/hcl/v2
│   │   └── github.com/zclconf/go-cty
│   ├── github.com/hashicorp/terraform-plugin-go
│   │   └── google.golang.org/grpc
│   │       └── google.golang.org/protobuf
│   └── [many others...]
├── golang.zx2c4.com/wireguard/wgctrl
│   └── golang.org/x/crypto
└── github.com/hashicorp/terraform-plugin-docs (build only)
```

--------------------------------

### Validate Asymmetric Key Generation and Matching

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/12-cryptographic-operations.md

Use this configuration to verify that generated private keys can be re-imported and that the resulting public keys match the original.

```hcl
# Generate and verify a key can be parsed
resource "wireguard_asymmetric_key" "test" {
}

# Import the generated key
resource "wireguard_asymmetric_key" "reimported" {
  private_key = wireguard_asymmetric_key.test.private_key
}

# Verify IDs match
locals {
  keys_match = wireguard_asymmetric_key.test.public_key == 
               wireguard_asymmetric_key.reimported.public_key
}

output "keys_match" {
  value = local.keys_match  # Should be true
}
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/08-errors.md

Set the TF_LOG environment variable to DEBUG to capture detailed SDK logging during execution.

```bash
TF_LOG=DEBUG terraform apply
```

--------------------------------

### Generate Asymmetric Private Key

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/12-cryptographic-operations.md

Generates a 32-byte random private key using crypto/rand.

```go
func GeneratePrivateKey() (Key, error)
```

--------------------------------

### Provider()

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/02-provider-api.md

Returns the configured Terraform provider instance with all registered resources and data sources.

```APIDOC
## Provider() Function

### Description
Returns the configured Terraform provider instance with all registered resources and data sources. This function is called by the main entry point via plugin.Serve().

### Signature
`func Provider() *schema.Provider`

### Return Type
`*schema.Provider` - A Terraform plugin SDK v2 schema.Provider containing:
- **DataSourcesMap** - Map of available data sources by name
- **ResourcesMap** - Map of available resources by name

### Registered Components
| Component | Type | Name |
|-----------|------|------|
| Data Source | wireguard_config_document | Configuration document generator |
| Resource | wireguard_asymmetric_key | WireGuard asymmetric key pair |
| Resource | wireguard_preshared_key | WireGuard preshared key |

### Usage Example
```hcl
provider "wireguard" {
  # No configuration options required
}

resource "wireguard_asymmetric_key" "server" {
  # Resource will use Provider() internally
}
```
```

--------------------------------

### Dynamically generate peer configurations

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/09-examples.md

Uses a local map to define peer attributes and a dynamic block within the wireguard_config_document resource to iterate over them.

```hcl
locals {
  peers = {
    peer_a = {
      allowed_ips = ["10.0.0.2/32"]
      endpoint    = "peer-a.example.com:51820"
    }
    peer_b = {
      allowed_ips = ["10.0.0.3/32"]
      endpoint    = "peer-b.example.com:51820"
    }
    peer_c = {
      allowed_ips = ["10.0.0.4/32"]
      endpoint    = "peer-c.example.com:51820"
    }
  }
}

resource "wireguard_asymmetric_key" "peers" {
  for_each = local.peers
}

resource "wireguard_preshared_key" "peers" {
  for_each = local.peers
}

data "wireguard_config_document" "server" {
  private_key = wireguard_asymmetric_key.server.private_key
  listen_port = 51820
  addresses   = ["10.0.0.1/24"]

  dynamic "peer" {
    for_each = local.peers
    content {
      public_key    = wireguard_asymmetric_key.peers[peer.key].public_key
      preshared_key = wireguard_preshared_key.peers[peer.key].key
      allowed_ips   = peer.value.allowed_ips
      endpoint      = peer.value.endpoint
    }
  }
}
```

--------------------------------

### Bind Key Lifecycle to Infrastructure

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/09-examples.md

Associate WireGuard keys with other resources so they are recreated when the target resource is replaced.

```hcl
resource "aws_instance" "vpn_server" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.small"
  # ... other configuration
}

# This key will be recreated if the EC2 instance is replaced
resource "wireguard_asymmetric_key" "server" {
  bind = aws_instance.vpn_server.id
}

resource "wireguard_asymmetric_key" "backup" {
  bind = aws_instance.vpn_server.id
}
```

--------------------------------

### Define WgConfig struct

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/06-types.md

The root configuration object for WireGuard interfaces, including core settings and peer lists.

```go
type WgConfig struct {
    PrivateKey   *string
    ListenPort   *int
    FirewallMark *string
    WgQuickConfig
    Peers        []WgPeerConfig
}
```

--------------------------------

### Define Asymmetric Key Resource Schema

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/03-asymmetric-key-resource.md

The function responsible for defining the resource schema and lifecycle handlers.

```go
func resourceWireguardAsymmetricKey() *schema.Resource
```

--------------------------------

### Define Create Operation Handler

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/03-asymmetric-key-resource.md

The function responsible for generating or parsing keys during the resource creation lifecycle.

```go
func resourceWireguardAsymmetricKeyCreate(d *schema.ResourceData, m interface{}) error
```

--------------------------------

### Define wireguard_preshared_key read operation

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/04-preshared-key-resource.md

No-op read operation as the provider stores all data in Terraform state.

```go
func resourceWireguardPresharedKeyRead(d *schema.ResourceData, m interface{}) error
```

--------------------------------

### Provider function signature

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/02-provider-api.md

The function signature for initializing the Terraform provider instance.

```go
func Provider() *schema.Provider
```

--------------------------------

### wireguard_config_document

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/07-configuration.md

The wireguard_config_document data source provides a way to define interface settings, network options, and peer definitions for WireGuard.

```APIDOC
## Data Source: wireguard_config_document

### Description
Generates a WireGuard configuration document based on provided interface, network, and peer settings.

### Arguments

#### Interface Configuration
- **private_key** (string, sensitive) - Optional - Base64 private key. If not provided, derived from zero key.
- **listen_port** (int) - Optional - UDP listen port (0-65535).
- **firewall_mark** (string) - Optional - 32-bit fwmark (Linux only).

#### wg-quick Options
- **addresses** (set of string) - Optional - Interface IP addresses in CIDR notation.
- **dns** (set of string) - Optional - DNS server IPs or hostnames.
- **mtu** (int) - Optional - Manual MTU override.
- **routing_table** (string) - Optional - Routing table ID or "off".
- **pre_up** (list of string) - Optional - Pre-up commands.
- **post_up** (list of string) - Optional - Post-up commands.
- **pre_down** (list of string) - Optional - Pre-down commands.
- **post_down** (list of string) - Optional - Post-down commands.

#### Peer Configuration
- **peer** (block list) - Optional - Peer configurations.

#### Peer Block Arguments
- **public_key** (string) - Required - Peer's public key in base64.
- **preshared_key** (string, sensitive) - Optional - Optional preshared key.
- **allowed_ips** (list of string) - Optional - Allowed IP ranges.
- **endpoint** (string) - Optional - Peer endpoint (IP:port or hostname:port).
- **persistent_keepalive** (int) - Optional - Keepalive interval in seconds.
- **description** (string) - Optional - Peer description (supports newlines for multi-line comments).
```

--------------------------------

### Audit dependency vulnerabilities

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/10-dependencies.md

Commands to check for known security vulnerabilities in project dependencies.

```bash
go list -m all | go-audit
# or using official Go vulnerability database
govulncheck ./...
```

--------------------------------

### Configure Full VPN Gateway

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/09-examples.md

Defines a complex gateway configuration including IP addresses, DNS, MTU, firewall rules, and multiple peers.

```hcl
resource "wireguard_asymmetric_key" "gateway" {
}

resource "wireguard_asymmetric_key" "client_a" {
}

resource "wireguard_asymmetric_key" "client_b" {
}

resource "wireguard_preshared_key" "client_a_psk" {
}

data "wireguard_config_document" "gateway_config" {
  private_key  = wireguard_asymmetric_key.gateway.private_key
  listen_port  = 51820
  firewall_mark = "0x4711"

  # Interface IP addresses (wg-quick only)
  addresses = [
    "10.0.0.1/24",
    "fd00:dead:beef::1/64"
  ]

  # DNS configuration (wg-quick only)
  dns = [
    "8.8.8.8",      # Google DNS IPv4
    "8.8.4.4",      # Google DNS IPv4
    "2001:4860:4860::8888"  # Google DNS IPv6
  ]

  # MTU configuration
  mtu = 1420

  # Firewall and NAT rules for Linux
  post_up = [
    "iptables -A FORWARD -i %i -j ACCEPT",
    "iptables -A FORWARD -o %i -j ACCEPT",
    "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE",
    "ip6tables -A FORWARD -i %i -j ACCEPT",
    "ip6tables -A FORWARD -o %i -j ACCEPT",
    "ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE"
  ]

  post_down = [
    "iptables -D FORWARD -i %i -j ACCEPT",
    "iptables -D FORWARD -o %i -j ACCEPT",
    "iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE",
    "ip6tables -D FORWARD -i %i -j ACCEPT",
    "ip6tables -D FORWARD -o %i -j ACCEPT",
    "ip6tables -t nat -D POSTROUTING -o eth0 -j MASQUERADE"
  ]

  # First client with preshared key and keepalive
  peer {
    public_key           = wireguard_asymmetric_key.client_a.public_key
    preshared_key        = wireguard_preshared_key.client_a_psk.key
    allowed_ips          = ["10.0.0.2/32", "fd00:dead:beef::2/128"]
    endpoint             = "203.0.113.10:51820"
    persistent_keepalive = 25
    description          = "Client A\nProduction VPN\nLocation: New York"
  }

  # Second client without preshared key
  peer {
    public_key  = wireguard_asymmetric_key.client_b.public_key
    allowed_ips = ["10.0.0.3/32", "fd00:dead:beef::3/128"]
    # No endpoint - client is dynamic, initiates connection
    description = "Client B"
  }
}

output "gateway_config" {
  value     = data.wireguard_config_document.gateway_config.conf
  sensitive = true
}
```

--------------------------------

### Define wireguard_config_document schema

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/05-config-document-datasource.md

This function defines the resource schema for the WireGuard configuration document data source.

```go
func dataSourceWireguardConfigDocument() *schema.Resource
```

--------------------------------

### Peer Configuration Validation

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/08-errors.md

Comparison between an incorrect peer block missing a public key and a correct implementation.

```hcl
# WRONG - missing public_key
peer {
  allowed_ips = ["10.0.0.2/32"]
}

# CORRECT - includes required public_key
peer {
  public_key  = wireguard_asymmetric_key.peer2.public_key
  allowed_ips = ["10.0.0.2/32"]
}
```

--------------------------------

### Configure a 3-peer WireGuard mesh network

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/09-examples.md

Defines asymmetric and preshared keys for three peers and generates individual configuration documents for each node in the mesh.

```hcl
# Create keys for 3 peers
resource "wireguard_asymmetric_key" "mesh_peer_1" {
}

resource "wireguard_asymmetric_key" "mesh_peer_2" {
}

resource "wireguard_asymmetric_key" "mesh_peer_3" {
}

# Create preshared keys between each pair
resource "wireguard_preshared_key" "psk_1_2" {
}

resource "wireguard_preshared_key" "psk_1_3" {
}

resource "wireguard_preshared_key" "psk_2_3" {
}

# Configuration for peer 1
data "wireguard_config_document" "mesh_peer_1" {
  private_key = wireguard_asymmetric_key.mesh_peer_1.private_key
  listen_port = 51820
  addresses   = ["10.255.0.1/24"]

  peer {
    public_key    = wireguard_asymmetric_key.mesh_peer_2.public_key
    preshared_key = wireguard_preshared_key.psk_1_2.key
    allowed_ips   = ["10.255.0.2/32"]
    endpoint      = "peer2.mesh.local:51820"
  }

  peer {
    public_key    = wireguard_asymmetric_key.mesh_peer_3.public_key
    preshared_key = wireguard_preshared_key.psk_1_3.key
    allowed_ips   = ["10.255.0.3/32"]
    endpoint      = "peer3.mesh.local:51820"
  }
}

# Configuration for peer 2
data "wireguard_config_document" "mesh_peer_2" {
  private_key = wireguard_asymmetric_key.mesh_peer_2.private_key
  listen_port = 51820
  addresses   = ["10.255.0.2/24"]

  peer {
    public_key    = wireguard_asymmetric_key.mesh_peer_1.public_key
    preshared_key = wireguard_preshared_key.psk_1_2.key
    allowed_ips   = ["10.255.0.1/32"]
    endpoint      = "peer1.mesh.local:51820"
  }

  peer {
    public_key    = wireguard_asymmetric_key.mesh_peer_3.public_key
    preshared_key = wireguard_preshared_key.psk_2_3.key
    allowed_ips   = ["10.255.0.3/32"]
    endpoint      = "peer3.mesh.local:51820"
  }
}

# Configuration for peer 3
data "wireguard_config_document" "mesh_peer_3" {
  private_key = wireguard_asymmetric_key.mesh_peer_3.private_key
  listen_port = 51820
  addresses   = ["10.255.0.3/24"]

  peer {
    public_key    = wireguard_asymmetric_key.mesh_peer_1.public_key
    preshared_key = wireguard_preshared_key.psk_1_3.key
    allowed_ips   = ["10.255.0.1/32"]
    endpoint      = "peer1.mesh.local:51820"
  }

  peer {
    public_key    = wireguard_asymmetric_key.mesh_peer_2.public_key
    preshared_key = wireguard_preshared_key.psk_2_3.key
    allowed_ips   = ["10.255.0.2/32"]
    endpoint      = "peer2.mesh.local:51820"
  }
}
```

--------------------------------

### Resource Create Operation Hierarchy

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/11-module-map.md

Flow of the resource creation process triggered by Terraform apply.

```text
Terraform apply
    └── plugin (via RPC)
        └── resourceWireguardAsymmetricKeyCreate()
            └── wgtypes.GeneratePrivateKey() or wgtypes.ParseKey()
                └── Returns key material
```

--------------------------------

### Generate Asymmetric Key Pair

Source: https://github.com/ojford/terraform-provider-wireguard/blob/master/_autodocs/README.md

Resource definition for creating a WireGuard public/private key pair.

```hcl
resource "wireguard_asymmetric_key" "example" {
}
```