### Full Workflow: Create and Start LXC Container

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

A complete function to create and start an LXC container, including building the command arguments, executing creation, and starting the container. Handles errors at each step.

```go
func createAndStartContainer(name, template string, envVars []string) error {
    // Build lxc-create command
    args := []string{"env"}
    args = append(args, envVars...)
    args = append(args, "lxc-create", "-n", name, "-t", template)
    
    // Execute
    if err := RunCommand(args...); err != nil {
        return fmt.Errorf("failed to create: %w", err)
    }
    
    // Start the container
    if err := RunCommand("lxc-start", "-d", "-n", name); err != nil {
        return fmt.Errorf("failed to start: %w", err)
    }
    
    return nil
}
```

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

### Configure Shell Provisioner

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

Example of configuring a shell provisioner to update package lists, install curl, and download a script.

```hcl
provisioner "shell" {
  inline = [
    "apt-get update",
    "apt-get install -y curl",
    "curl -fsSL https://example.com/install.sh | bash"
  ]
}
```

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

### Command Wrapper Example

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/00-index.md

Demonstrates how to wrap original commands for remote execution using a template. The example shows an `lxc-create` command being prefixed with `ssh remote`.

```template
Original command: lxc-create -n ubuntu -t ubuntu
Wrapper template: ssh remote {{.Command}}
Result: ssh remote lxc-create -n ubuntu -t ubuntu
```

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

### LXC Attach Provisioning Example

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

Illustrates how provisioners execute commands using `lxc-attach` and transfer files directly to the container's root filesystem.

```go
// Provisioners run commands like:
// lxc-attach -n packer-ubuntu -- /bin/sh -c "apt-get update"
// and upload files to the container rootfs
```

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

### Basic LXC Packer Builder Example

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/docs/builders/lxc.mdx

This example demonstrates how to configure multiple LXC builders for different Ubuntu and Debian releases, as well as a CentOS 7 image. It specifies the builder type, name, configuration file path, template name, and template environment variables or parameters.

```json
{
  "builders": [
    {
      "type": "lxc",
      "name": "lxc-trusty",
      "config_file": "/tmp/lxc/config",
      "template_name": "ubuntu",
      "template_environment_vars": ["SUITE=trusty"]
    },
    {
      "type": "lxc",
      "name": "lxc-xenial",
      "config_file": "/tmp/lxc/config",
      "template_name": "ubuntu",
      "template_environment_vars": ["SUITE=xenial"]
    },
    {
      "type": "lxc",
      "name": "lxc-jessie",
      "config_file": "/tmp/lxc/config",
      "template_name": "debian",
      "template_environment_vars": ["SUITE=jessie"]
    },
    {
      "type": "lxc",
      "name": "lxc-centos-7-x64",
      "config_file": "/tmp/lxc/config",
      "template_name": "centos",
      "template_parameters": ["-R", "7", "-a", "x86_64"]
    }
  ]
}
```

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

### LXC Export Step Example

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

Illustrates the expected output files after the LXC export step, including the compressed root filesystem and configuration file.

```go
// Container: /var/lib/lxc/packer-ubuntu//
// Output directory: output-ubuntu/
// Creates:
//   output-ubuntu/rootfs.tar.gz (compressed filesystem)
//   output-ubuntu/lxc-config (configuration file)

```

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

### Install LXC Plugin using packer plugins install

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/docs/README.md

Use the `packer plugins install` command to manage the installation of the LXC plugin.

```sh
$ packer plugins install github.com/hashicorp/lxc
```

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

### Configure File Provisioner

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

Example of configuring a file provisioner to upload local configuration files to the container.

```hcl
provisioner "file" {
  source = "local/config/"
  destination = "/etc/myapp/"
}
```

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

### External Setup Script for Provisioning

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

An external bash script used as a shell provisioner in Packer. It installs development tools, creates a user, configures sudo, and sets up the SSH directory.

```bash
#!/bin/bash
set -e

# Install development tools
apt-get install -y vim nano git

# Create application user
useradd -m -s /bin/bash appuser

# Configure sudo
echo "appuser ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/appuser

# Set up SSH directory
mkdir -p /home/appuser/.ssh
chmod 700 /home/appuser/.ssh
chown -R appuser:appuser /home/appuser/.ssh

echo "Setup completed"
```

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

### Start Command Execution in LXC Container

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

Starts a command asynchronously in a running LXC container. Use this when the command needs to run in the background and its output is captured.

```go
comm := &LxcAttachCommunicator{
    ContainerName: "packer-ubuntu",
    RootFs: "/var/lib/lxc/packer-ubuntu/rootfs",
    AttachOptions: []string{},
    CmdWrapper: func(cmd string) (string, error) { return cmd, nil },
}

cmd := &packersdk.RemoteCmd{
    Command: "apt-get update",
    Stdout: os.Stdout,
    Stderr: os.Stderr,
}

err := comm.Start(context.Background(), cmd)
if err != nil {
    log.Fatalf("Failed to start command: %v", err)
}

// Command runs in background, check cmd.ExitStatus() later
```

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

### Extract Tar Archive Example

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

Example command to extract the created rootfs.tar.gz archive to a specified directory.

```bash
tar -xzf rootfs.tar.gz -C /target/
```

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

### LXC Builder Run Method Example

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/03-builder.md

Demonstrates how to instantiate and run the LXC builder. Ensure the builder is configured via `Prepare()` before calling `Run()`. The `artifact.Files()` will contain the generated `rootfs.tar.gz` and `lxc-config`.

```go
builder := &Builder{}
builder.Prepare(cfg) // Configure the builder

artifact, err := builder.Run(context.Background(), ui, hook)
if err != nil {
    log.Fatalf("Build failed: %v", err)
}

// artifact.Files() contains ["rootfs.tar.gz", "lxc-config"]
// artifact.String() returns "VM files in directory: output-ubuntu"
```

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

### Start

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

Starts execution of a command in the running container asynchronously. The command runs in the background, and the method returns immediately. Output is captured through pipes connected to the provided stdout/stderr.

```APIDOC
## Start

### Description
Starts execution of a command in the running container asynchronously. The command runs in the background, and the method returns immediately. Output is captured through pipes connected to the provided stdout/stderr.

### Method
`error`

### Parameters
- `ctx` (context.Context) — Go context for cancellation (used in Packer)
- `cmd` (*packersdk.RemoteCmd) — Remote command to execute
  - `cmd.Command` (string) — The command string to execute
  - `cmd.Stdin` (io.Reader) — Standard input stream (or nil)
  - `cmd.Stdout` (io.Writer) — Standard output stream
  - `cmd.Stderr` (io.Writer) — Standard error stream

### Return
- `error` — Error if command execution cannot be started, nil on success

### Behavior
- Constructs an `lxc-attach` command using the container name and attach options
- Wraps the command using `CmdWrapper` for remote execution if configured
- Starts the command in a goroutine to avoid blocking
- Sets the exit status via `cmd.SetExited(exitStatus)` when the command completes

### Exit Code Handling:
- On success: exit code 0
- On error: attempts to extract the real exit status using `syscall.WaitStatus`
- Falls back to exit code 1 if the real exit code cannot be determined

### Example:
```go
comm := &LxcAttachCommunicator{
    ContainerName: "packer-ubuntu",
    RootFs: "/var/lib/lxc/packer-ubuntu/rootfs",
    AttachOptions: []string{},
    CmdWrapper: func(cmd string) (string, error) { return cmd, nil },
}

cmd := &packersdk.RemoteCmd{
    Command: "apt-get update",
    Stdout: os.Stdout,
    Stderr: os.Stderr,
}

err := comm.Start(context.Background(), cmd)
if err != nil {
    log.Fatalf("Failed to start command: %v", err)
}

// Command runs in background, check cmd.ExitStatus() later
```
```

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

### Install Packer Plugin Lxc with packer init

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/README.md

Use this snippet to declare the Lxc plugin in your Packer configuration. Run `packer init` to automatically install it.

```hcl
packer {
  required_plugins {
    lxc = {
      version = ">= 1.0.0"
      source  = "github.com/hashicorp/lxc"
    }
  }
}
```

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

### Install LXC Plugin with Packer Configuration

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/docs/README.md

Add this block to your Packer configuration to declare the LXC plugin as a requirement. Run `packer init` to install.

```hcl
packer {
  required_plugins {
    lxc = {
      source  = "github.com/hashicorp/lxc"
      version = "~> 1"
    }
  }
}
```

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

### Configure Ansible-Local Provisioner

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

Example of configuring an ansible-local provisioner to run a playbook within the container.

```hcl
provisioner "ansible-local" {
  playbook_file = "playbook.yml"
}
```

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

### Creating and Using a Custom Artifact

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/04-artifact.md

Provides a Go example of creating a custom Artifact struct, initializing it with output directory, files, and generated data, and then accessing its methods like String(), BuilderId(), Files(), and Destroy().

```go
func createArtifact(outputDir string, files []string, generatedData map[string]interface{}) *Artifact {
    return &Artifact{
        dir: outputDir,
        f: files,
        StateData: map[string]interface{}{
            "generated_data": generatedData,
        },
    }
}

// Usage
artifact := createArtifact(
    "output-ubuntu",
    []string{"output-ubuntu/rootfs.tar.gz", "output-ubuntu/lxc-config"},
    map[string]interface{}{"provisioner": "ansible"},
)

fmt.Println(artifact.String())      // "VM files in directory: output-ubuntu"
fmt.Println(artifact.BuilderId())   // "ustream.lxc"
fmt.Println(artifact.Files())       // List of files

// Cleanup when done
artifact.Destroy()
```

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

### Container with File Provisioner (HCL2)

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Configure a container with file provisioners using HCL2. This example uploads a configuration file and a directory of scripts into the container.

```hcl
source "lxc" "with_config" {
  config_file              = "/etc/lxc/default.conf"
  template_name            = "ubuntu"
  template_environment_vars = ["SUITE=focal"]
  container_name           = "packer-ubuntu-config"
  output_directory         = "output/ubuntu-config"
}

build {
  sources = ["source.lxc.with_config"]
  
  provisioner "file" {
    source      = "config/app.conf"
    destination = "/etc/app/app.conf"
  }
  
  provisioner "file" {
    source      = "scripts/"
    destination = "/opt/scripts"
  }
  
  provisioner "shell" {
    inline = [
      "chmod +x /opt/scripts/*.sh",
      "chown -R root:root /opt/scripts"
    ]
  }
}
```

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

### Alpine Linux Minimal Container (HCL2)

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Create a minimal Alpine Linux container using HCL2 configuration. This example includes shell provisioners for package installation.

```hcl
source "lxc" "alpine" {
  config_file              = "/etc/lxc/default.conf"
  template_name            = "alpine"
  template_environment_vars = ["ARCH=x86_64"]
  container_name           = "packer-alpine"
  output_directory         = "output/alpine"
  init_timeout             = "45s"
}

build {
  sources = ["source.lxc.alpine"]
  
  provisioner "shell" {
    inline = [
      "apk update",
      "apk add curl wget",
      "apk add python3"
    ]
  }
}
```

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

### Directory Structure for File Provisioner

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Illustrates the directory structure required for the file provisioner example, showing the location of the Packer template, configuration files, and scripts.

```text
├── packer.hcl
├── config/
│   └── app.conf
└── scripts/
    ├── setup.sh
    ├── install.sh
    └── configure.sh
```

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

### Get Artifact Files

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/04-artifact.md

Retrieves the list of output files created by the build, including the container image and configuration.

```go
artifact := &Artifact{
    dir: "output-ubuntu",
    f: []string{"output-ubuntu/rootfs.tar.gz", "output-ubuntu/lxc-config"},
}
files := artifact.Files()
// files == []string{"output-ubuntu/rootfs.tar.gz", "output-ubuntu/lxc-config"}
```

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

### Execute

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

Constructs an exec.Cmd that executes a command in the container using `lxc-attach`. The command is wrapped but not started. This is a lower-level method used internally by Start() and CheckInit().

```APIDOC
## Execute

### Description
Constructs an exec.Cmd that executes a command in the container using `lxc-attach`. The command is wrapped but not started. This is a lower-level method used internally by Start() and CheckInit().

### Method
`(*exec.Cmd, error)`

### Parameters
- `commandString` (string) — The command to execute inside the container

### Return
- `*exec.Cmd` — Go exec command object ready to run
- `error` — Error if command construction fails

### Command Construction:
- Builds: `lxc-attach [options] --name <container> -- /bin/sh -c "<command>"`
- Applies `AttachOptions` to the lxc-attach invocation
- Wraps the final command string using `CmdWrapper`

### Example:
```go
localCmd, err := comm.Execute("dpkg -l")
if err != nil {
    log.Fatalf("Failed to construct command: %v", err)
}

// Command is ready but not yet started
pr, _ := localCmd.StdoutPipe()
localCmd.Start()

output, _ := ioutil.ReadAll(pr)
```
```

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

### Prepare

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/03-builder.md

Validates and prepares the builder configuration before the build starts. It internally calls `Config.Prepare()` to validate all configuration options and apply defaults.

```APIDOC
## Prepare(raws ...interface{})

### Description
Validates and prepares the builder configuration. This is called once by Packer before the build starts. Internally calls `Config.Prepare()` to validate all configuration options and apply defaults.

### Signature
```go
func (b *Builder) Prepare(raws ...interface{}) ([]string, []string, error)
```

### Parameters
- `raws` — Raw configuration data, typically a `map[string]interface{}` containing the decoded HCL2 block

### Return
- First return value ([]string) — Provisioner names that this builder supports (currently empty)
- Second return value ([]string) — User variable names (currently empty)
- Error — Validation error, or nil on success

### Behavior
- Creates or validates the internal `Config` object
- Returns any errors from `Config.Prepare()` validation

### Example
```go
builder := &Builder{}
cfg := map[string]interface{}{
    "config_file": "/tmp/lxc/config",
    "template_name": "ubuntu",
    "template_environment_vars": []interface{}{"SUITE=focal"},
}
warnings, users, err := builder.Prepare(cfg)
if err != nil {
    log.Fatalf("Build preparation failed: %v", err)
}
```
```

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

### Create LXC Container Step

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

This step creates and starts an LXC container using specified templates and configurations. It handles container cleanup if `packer_force` is true.

```go
type stepLxcCreate struct{}
```

```bash
env <env_vars> lxc-create <create_options> -n <name> -t <template> -- <parameters>
```

```bash
touch <rootfs>/tmp/.tmpfs
```

```bash
lxc-start <start_options> -d -n <name>
```

```go
// For template_name="ubuntu" with template_environment_vars=["SUITE=focal"]
// Creates: /var/lib/lxc/packer-ubuntu/
// With environment: SUITE=focal passed to lxc-template
```

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

### Prepare Builder Configuration

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/03-builder.md

Validates and prepares the builder configuration before the build starts. It internally calls Config.Prepare() for detailed validation and default application.

```go
builder := &Builder{}
cfg := map[string]interface{}{
    "config_file": "/tmp/lxc/config",
    "template_name": "ubuntu",
    "template_environment_vars": []interface{}{"SUITE=focal"},
}
warnings, users, err := builder.Prepare(cfg)
if err != nil {
    log.Fatalf("Build preparation failed: %v", err)
}
```

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

### Build and Run LXC Container Creation Commands

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

Constructs and executes a series of commands using RunCommand for LXC container creation, including environment setup and specific creation parameters.

```Go
// Environment setup
commands[0] = append(commands[0], "env")
commands[0] = append(commands[0], config.EnvVars...)
commands[0] = append(commands[0], "lxc-create")
commands[0] = append(commands[0], config.CreateOptions...)
commands[0] = append(commands[0], []string{"-", "n", name, "-", "t", config.Name, "--"}...) 
commands[0] = append(commands[0], config.Parameters...)

// Container creation
for _, command := range commands {
    err := RunCommand(command...)
    if err != nil {
        // Handle error
    }
}
```

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

### Get Human-Readable Artifact String

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/04-artifact.md

Provides a human-readable string representation of the artifact, useful for displaying build results.

```go
artifact := &Artifact{dir: "output-ubuntu"}
str := artifact.String()
// str == "VM files in directory: output-ubuntu"
```

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

### Build Unprivileged Ubuntu Container

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Configures a build for an unprivileged Ubuntu container, including a shell provisioner for package installation.

```hcl
build {
  sources = ["source.lxc.unprivileged"]
  
  provisioner "shell" {
    inline = ["apt-get update && apt-get install -y curl"]
  }
}
```

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

### Ansible Playbook Example

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

A sample Ansible playbook to configure a container, including updating packages and copying application files. This playbook is designed to run within the LXC container provisioned by Packer.

```yaml
---
- name: Configure container
  hosts: localhost
  gather_facts: yes
  
  tasks:
    - name: Update package cache
      apt:
        update_cache: yes
        cache_valid_time: 3600
      when: ansible_os_family == 'Debian'
    
    - name: Install packages
      apt:
        name:
          - curl
          - wget
          - git
          - python3-pip
        state: present
      when: ansible_os_family == 'Debian'
    
    - name: Create application directory
      file:
        path: /opt/app
        state: directory
        mode: '0755'
    
    - name: Copy application files
      copy:
        src: ./files/app/
        dest: /opt/app/

```

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

### Build Ubuntu Jammy Image with Shell Provisioner

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Configures a build for an Ubuntu Jammy image using a shell provisioner to update packages and install curl.

```hcl
build {
  name = "ubuntu-jammy"
  sources = ["source.lxc.ubuntu_jammy"]
  
  provisioner "shell" {
    inline = ["apt-get update && apt-get install -y curl"]
  }
}
```

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

### Production Build with Multiple Provisioners

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Configures a production build for an LXC container with multiple provisioners for system updates, security hardening, application setup, and cleanup.

```hcl
build {
  sources = ["source.lxc.production"]
  
  # System updates
  provisioner "shell" {
    inline = [
      "apt-get update",
      "apt-get upgrade -y",
      "apt-get install -y build-essential git curl wget vim"
    ]
  }
  
  # Security hardening
  provisioner "file" {
    source      = "config/sshd_config"
    destination = "/etc/ssh/sshd_config"
  }
  
  # Application setup
  provisioner "shell" {
    script = "scripts/setup-app.sh"
  }
  
  # Cleanup
  provisioner "shell" {
    inline = [
      "apt-get clean",
      "apt-get autoclean",
      "apt-get autoremove",
      "rm -rf /tmp/*",
      "rm -rf /var/tmp/*"
    ]
  }
}
```

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

### Container with Shell Provisioners (HCL2)

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Configure a container with multiple shell provisioners using HCL2. This includes inline commands for package installation and running an external script.

```hcl
source "lxc" "provisioned" {
  config_file              = "/etc/lxc/default.conf"
  template_name            = "ubuntu"
  template_environment_vars = ["SUITE=focal"]
  container_name           = "packer-ubuntu-provisioned"
  output_directory         = "output/ubuntu-provisioned"
}

build {
  sources = ["source.lxc.provisioned"]
  
  provisioner "shell" {
    inline = [
      "apt-get update",
      "apt-get install -y build-essential",
      "apt-get install -y git curl wget",
      "apt-get clean"
    ]
  }
  
  provisioner "shell" {
    script = "scripts/setup.sh"
  }
  
  provisioner "shell" {
    inline = ["echo 'Build completed successfully'"]
  }
}
```

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

### Build Ubuntu Focal Image with Shell Provisioner

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Configures a build for an Ubuntu Focal image using a shell provisioner to update packages and install curl.

```hcl
build {
  name = "ubuntu-focal"
  sources = ["source.lxc.ubuntu_focal"]
  
  provisioner "shell" {
    inline = ["apt-get update && apt-get install -y curl"]
  }
}
```

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

### Execute Command Construction for LXC Container

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

Constructs an `exec.Cmd` for executing a command within an LXC container using `lxc-attach`. The command is prepared but not yet started.

```go
localCmd, err := comm.Execute("dpkg -l")
if err != nil {
    log.Fatalf("Failed to construct command: %v", err)
}

// Command is ready but not yet started
pr, _ := localCmd.StdoutPipe()
localCmd.Start()

output, _ := ioutil.ReadAll(pr)
```

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

### Customized LXC Builder Configuration

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/00-index.md

An example of a more customized LXC builder configuration, including options for container naming, output directory, timeouts, and specific creation/attach options.

```hcl
source "lxc" "custom" {
  config_file              = "/etc/lxc/default.conf"
  template_name            = "ubuntu"
  template_environment_vars = ["SUITE=focal"]
  container_name           = "my-container"
  output_directory         = "output/my-image"
  init_timeout             = "30s"
  create_options           = ["-f", "/custom.conf"]
  attach_options           = ["--clear-env"]
}
```

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

### Build CentOS 7 Image with Shell Provisioner

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Configures a build for a CentOS 7 image using a shell provisioner to update packages and install curl.

```hcl
build {
  name = "centos7"
  sources = ["source.lxc.centos7"]
  
  provisioner "shell" {
    inline = ["yum update -y && yum install -y curl"]
  }
}
```

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

### Custom LXC Configuration File

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

An example of a custom LXC configuration file that can be used with the Packer LXC builder to define advanced container settings.

```lxc
lxc.arch = x86_64
lxc.include = /usr/share/lxc/config/common.conf.d/

# Network
lxc.network.type = veth
lxc.network.link = virbr0
lxc.network.flags = up

# Root filesystem
lxc.rootfs.path = dir:/var/lib/lxc/packer-ubuntu-custom/rootfs

# Resource limits
lxc.cgroup.memory.limit_in_bytes = 2G
lxc.cgroup.cpuset.cpus = 0,1

# Security
lxc.cap.drop = sys_module sys_time

```

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

### State Bag Usage in Packer LXC Plugin

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/00-index.md

Illustrates how to set and get values from the state bag, which is used to pass data between build steps in the multi-step framework. It also shows how to store errors in the state bag.

```go
state.Put("key", value)
state.Get("key").(Type)
state.Put("error", err)
```

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

### Build Steps

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/00-index.md

Documentation for build steps including stepPrepareOutputDir, stepLxcCreate, StepWaitInit, StepProvision, and stepExport, outlining the step-by-step workflow.

```APIDOC
## Build Steps

### Description
Documentation for build steps including stepPrepareOutputDir, stepLxcCreate, StepWaitInit, StepProvision, and stepExport, outlining the step-by-step workflow.

### Steps

- **stepPrepareOutputDir**: create output directory
- **stepLxcCreate**: create and start container
- **StepWaitInit**: wait for runlevel
- **StepProvision**: run provisioners
- **stepExport**: create tar.gz
```

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

### Execute Command with Multiple Arguments

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

Demonstrates using RunCommand to execute 'lxc-create' with several arguments, capturing and logging any execution errors.

```Go
err = RunCommand("lxc-create", "-n", "mycontainer", "-t", "ubuntu")
if err != nil {
    log.Fatalf("Container creation failed: %v", err)
}
```

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

### Prepare Configuration with Go

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/02-configuration.md

Parses raw configuration data, applies defaults, and validates fields. Use this to programmatically configure the LXC builder.

```go
config := &Config{}
err := config.Prepare(map[string]interface{}{
    "config_file": "/tmp/lxc/config",
    "template_name": "ubuntu",
    "template_environment_vars": []string{"SUITE=focal"},
})
if err != nil {
    log.Fatalf("Config validation failed: %v", err)
}
```

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

### Prepare Output Directory Step

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

This step ensures the output directory is ready for the build, creating it or removing an existing one if `packer_force` is enabled.

```go
type stepPrepareOutputDir struct{}
```

```go
// Output directory is created at /workspace/output-ubuntu
// If /workspace/output-ubuntu exists and packer_force=true, it's deleted first
```

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

### Get Generic Artifact ID

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/04-artifact.md

Returns a generic artifact identifier. For LXC, this is always 'VM'.

```go
artifact := &Artifact{}
id := artifact.Id()
// id == "VM"
```

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

### LXC Upload, Execute, and Download Workflow

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

This snippet shows a complete workflow for uploading a script to an LXC container, executing it, and implicitly handling its completion. Ensure the container name and root filesystem path are correctly specified.

```go
comm := &LxcAttachCommunicator{
    ContainerName: "packer-ubuntu",
    RootFs: "/var/lib/lxc/packer-ubuntu/rootfs",
    CmdWrapper: func(cmd string) (string, error) { return cmd, nil },
}

// Upload a script
scriptFile, _ := os.Open("setup.sh")
deferr scriptFile.Close()
scriptInfo, _ := scriptFile.Stat()
comm.Upload("/tmp/setup.sh", scriptFile, &scriptInfo)

// Execute the script
cmd := &packersdk.RemoteCmd{
    Command: "bash /tmp/setup.sh",
    Stdout: os.Stdout,
    Stderr: os.Stderr,
}
comm.Start(context.Background(), cmd)

// Wait for completion and check exit code
// (Packer handles this automatically)
```

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

### Get Builder ID

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/04-artifact.md

Returns the unique identifier for the builder. Used by Packer to route artifacts to post-processors.

```go
artifact := &Artifact{}
id := artifact.BuilderId()
// id == "ustream.lxc"
```

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

### Logging and Running LXC Create Command

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

Logs the container creation process and executes the lxc-create command. Includes error logging if creation fails.

```go
log.Printf("Creating container: %s", containerName)
err := RunCommand("lxc-create", "-n", containerName, "-t", template)
if err != nil {
    log.Printf("Creation failed: %v", err)
}
```

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

### Get Builder Configuration Specification

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/03-builder.md

Retrieves the HCL2 specification for the builder's configuration block, used for validation.

```go
builder := &Builder{}
spec := builder.ConfigSpec()
// Used internally by Packer to validate HCL2 configuration
```

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

### LXC Builder Build Step Order

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

Visual representation of the sequential build steps for the LXC builder, showing dependencies.

```text
┌─────────────────────────────────┐
│ Step 1: Prepare Output Dir       │  Create/clean output directory
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│ Step 2: LXC Create              │  Create and start container
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│ Step 3: Wait Init               │  Poll until runlevel reached
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│ Step 4: Provision               │  Run provisioners
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│ Step 5: Export                  │  Create tar.gz archive
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│ Build Complete / Failed         │  Return artifact or error
└─────────────────────────────────┘
```

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

### Build Production Image with Variables

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Command to build the production image, specifying distribution and suite variables.

```bash
packer build \
  -var distribution=centos \
  -var suite=7 \
  production.hcl
```

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

### Get Builder State Data

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/04-artifact.md

Retrieves builder state data for a given key, allowing post-processors to access build-generated information.

```go
artifact := &Artifact{
    StateData: map[string]interface{}{
        "generated_data": map[string]interface{}{
            "ansible_user": "ubuntu",
            "build_date": "2025-05-23",
        },
    },
}
data := artifact.State("generated_data")
// data == map[string]interface{}{ "ansible_user": "ubuntu", "build_date": "2025-05-23"}
```

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

### Execute Shell Command with Pipes

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

Demonstrates using ShellCommand to execute a command involving pipes and grep, capturing and logging any execution errors.

```Go
cmd := ShellCommand("echo test | grep test")
err := cmd.Run()
if err != nil {
    log.Fatalf("Command failed: %v", err)
}
```

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

### Identity Command Wrapper Function

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/08-types.md

A function type that wraps command strings. This example shows an identity wrapper that returns the command unchanged.

```go
func(cmd string) (string, error) {
    return cmd, nil
}
```

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

### Communicator API

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/00-index.md

Reference for the Communicator API, including Start(), Execute(), CheckInit(), Upload(), Download(), and UploadDir() methods for file transfer and command execution.

```APIDOC
## Communicator API

### Description
Reference for the Communicator API, including Start(), Execute(), CheckInit(), Upload(), Download(), and UploadDir() methods for file transfer and command execution.

### Methods

#### Start
- **Signature**: `(ctx, cmd)
- **Purpose**: Execute command asynchronously.

#### Execute
- **Signature**: `(cmd)
- **Purpose**: Construct exec.Cmd.

#### CheckInit
- **Signature**: `()
- **Purpose**: Get container runlevel.

#### Upload
- **Signature**: `(dst, reader, info)
- **Purpose**: Upload file to container.

#### UploadDir
- **Signature**: `(dst, src, exclude)
- **Purpose**: Upload directory.

#### Download
- **Signature**: `(src, writer)
- **Purpose**: Download file from container.
```

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

### Version Variables

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/08-types.md

Exposes build-time version information for the plugin, including the main version and prerelease status.

```go
var (
    Version = "1.0.2"
    VersionPrerelease = "dev"
    PluginVersion = version.InitializePluginVersion(Version, VersionPrerelease)
)
```

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

### Stop Container and Create Tar Archive

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

Uses RunCommand to execute sequential commands for stopping an LXC container, creating a tar archive of its rootfs, and setting execute permissions on a config file.

```Go
commands := [][]string{
    {"lxc-stop", "--name", name},
    {"tar", "-C", containerDir, "--numeric-owner", "-czf", outputPath, "./rootfs"},
    {"chmod", "+x", configFilePath},
}

for _, command := range commands {
    err := RunCommand(command...)
    if err != nil {
        return multistep.ActionHalt
    }
}
```

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

### Configuration Options

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/README.md

Key configuration options for the LXC builder.

```APIDOC
## Configuration Options

### Required Options

*   **`config_file`** (string) - Path to the LXC configuration file.
*   **`template_name`** (string) - Name of the template to use for the container.
*   **`template_environment_vars`** (map[string]string) - Environment variables to pass to the template.

### Optional Options

*   **`output_directory`** (string) - Directory to store the exported artifact.
*   **`container_name`** (string) - Custom name for the LXC container.
*   **`init_timeout`** (string) - Timeout for container initialization.
*   **`target_runlevel`** (string) - Target runlevel for the container.
```

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

### Production-Ready LXC Source Configuration

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Defines a production-ready LXC source using variables for configuration file, output directory, distribution, and suite. Includes init timeout and target runlevel.

```hcl
source "lxc" "production" {
  config_file              = var.lxc_config
  template_name            = var.distribution
  template_environment_vars = ["SUITE=${var.suite}"]
  container_name           = "packer-${var.distribution}-${var.suite}"
  output_directory         = "${var.output_dir}/${var.distribution}-${var.suite}"
  init_timeout             = "30s"
  target_runlevel          = 3
}
```

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

### Build Command

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Command to build the container using a Packer template file.

```bash
packer build template.hcl
```

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

### Step Interface Definition

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

Defines the standard interface for all build steps, including methods for execution and cleanup.

```go
type Step interface {
    Run(ctx.Context, multistep.StateBag) multistep.StepAction
    Cleanup(state multistep.StateBag)
}
```

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

### CheckInit

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

Checks the container's runlevel by executing `/sbin/runlevel` inside the container. Used by the build process to determine if the container has completed its initialization. Returns the raw runlevel output.

```APIDOC
## CheckInit

### Description
Checks the container's runlevel by executing `/sbin/runlevel` inside the container. Used by the build process to determine if the container has completed its initialization. Returns the raw runlevel output.

### Method
`(string, error)`

### Return
- `string` — Output of `/sbin/runlevel`, typically in format `"N M"` where N is previous runlevel and M is current runlevel
- `error` — Error if the check fails (command execution error, parsing error, etc.)

### Output Format:
- Typical output: `"S 3"` or `"1 5"`
- Whitespace-trimmed before returning

### Behavior:
- Executes `/sbin/runlevel` via `lxc-attach`
- Captures stdout
- Waits for command completion
- Returns trimmed output

### Example:
```go
runlevel, err := comm.CheckInit()
if err != nil {
    log.Fatalf("Failed to check runlevel: %v", err)
}

// Parse runlevel output
parts := strings.Split(runlevel, " ")
if len(parts) >= 2 {
    currentRunlevel := parts[1]
    log.Printf("Current runlevel: %s", currentRunlevel)
}
```
```

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

### Packer LXC Plugin Build Workflow Steps

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/README.md

The build process for the Packer LXC plugin involves several sequential steps, from preparing the output directory to exporting the container.

```text
1. Prepare Output Directory
2. Create LXC Container
3. Wait for Container Init
4. Run Provisioners
5. Export to tar.gz
```

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

### Download a file from an LXC container

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

Use this method to download a file from a specified path inside the container to a host writer. The source path should be relative to the container's rootfs.

```go
output, err := os.Create("downloaded-file")
if err != nil {
    log.Fatalf("Failed to create output file: %v", err)
}
defer output.Close()

err = comm.Download("etc/hostname", output)
if err != nil {
    log.Fatalf("Download failed: %v", err)
}
```

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

### Basic Ubuntu Container Configuration in HCL2

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/02-configuration.md

A minimal HCL2 configuration for creating a basic Ubuntu LXC container, specifying the config file, template name, and environment variables.

```hcl
source "lxc" "ubuntu" {
  config_file              = "/tmp/lxc/config"
  template_name            = "ubuntu"
  template_environment_vars = ["SUITE=focal"]
}
```

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

### Make LXC Config Executable

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/07-build-steps.md

Command to make the LXC configuration file executable. This is optional and useful for script-like usage.

```bash
chmod +x <config_file>
```

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

### DownloadDir(src string, dst string, exclude []string) error

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

Placeholder method for downloading a directory from the container. Currently not implemented.

```APIDOC
## DownloadDir(src string, dst string, exclude []string) error

### Description
Placeholder method for downloading a directory from the container. Currently not implemented.

### Return
- `error` - Always returns error: `"DownloadDir is not implemented for lxc"`

### Status
This feature is not supported in the current implementation.
```

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

### Execute Command Directly (No Shell)

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

Executes a command and its arguments directly, capturing and logging stdout/stderr. Returns an error if the command fails or returns a non-zero exit code.

```Go
err := RunCommand(args...)
if err != nil {
    log.Fatalf("Failed to list containers: %v", err)
}
```

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

### Accessing Artifact Data in Post-Processor

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/04-artifact.md

Demonstrates how to access artifact files, generated data, builder ID, and artifact ID within a Packer post-processor using the Packer interface.

```go
// In a post-processor
artifact := ... // from Packer

// Get the output files
files := artifact.Files()
for _, file := range files {
    // Process each file
}

// Get generated data
genData := artifact.State("generated_data")

// Get artifact metadata
builderId := artifact.BuilderId()
id := artifact.Id()
```

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

### stepPrepareOutputDir Type Definition

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/08-types.md

Defines the internal struct for preparing the output directory in the build process.

```go
type stepPrepareOutputDir struct{}
```

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

### Basic Ubuntu Container (JSON)

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Create a minimal Ubuntu Focal container using JSON configuration. This snippet defines the builders block for Packer.

```json
{
  "builders": [
    {
      "type": "lxc",
      "name": "ubuntu_focal",
      "config_file": "/etc/lxc/default.conf",
      "template_name": "ubuntu",
      "template_environment_vars": ["SUITE=focal"],
      "container_name": "packer-ubuntu-focal",
      "output_directory": "output/ubuntu-focal"
    }
  ]
}
```

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

### Create Shell Command Executor

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

Creates an os/exec.Cmd object to run a command string using the system's shell (/bin/sh -c). This enables shell features like pipes and redirects but carries a risk of shell injection.

```Go
return exec.Command("/bin/sh", "-c", command)
```

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

### Build and Wrap LXC Attach Command

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

Constructs an lxc-attach command with specified options and wraps it for remote execution using CmdWrapper.

```go
attachCommand := []string{"lxc-attach"}
attachCommand = append(attachCommand, c.AttachOptions...)
attachCommand = append(attachCommand, []string{"--name", "%s", "--", "/bin/sh -c \"%s\""}...) 

command, err := c.CmdWrapper(
    fmt.Sprintf(strings.Join(attachCommand, " "), c.ContainerName, commandString))

localCmd := ShellCommand(command)
err := localCmd.Start()
```

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

### Plugin Entry Point Registration

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/01-overview.md

This Go code snippet shows how the LXC builder is registered with the Packer plugin system in the main entry point of the plugin.

```go
func main() {
    pps := plugin.NewSet()
    pps.RegisterBuilder(plugin.DEFAULT_NAME, new(lxc.Builder))
    pps.SetVersion(version.PluginVersion)
    err := pps.Run()
}
```

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

### Register LXC Builder

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/00-index.md

Registers the LXC builder with the plugin set. This is the main entry point for the plugin.

```go
pps := plugin.NewSet()
pps.RegisterBuilder(plugin.DEFAULT_NAME, new(lxc.Builder))
```

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

### Build Specific Image with Packer

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/09-usage-examples.md

Command to build only the 'ubuntu-focal' image from the template.hcl file.

```bash
packer build -only=ubuntu-focal template.hcl
```

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

### Upload a directory to an LXC container

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

Use this method to recursively copy a source directory from the host to a destination directory inside the container. The 'exclude' parameter is currently not implemented.

```go
err := comm.UploadDir("/opt/config", "/tmp/src/config", nil)
if err != nil {
    log.Fatalf("Directory upload failed: %v", err)
}
```

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

### Command Utilities

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/00-index.md

Reference for command execution helpers, including the CommandWrapper type and ShellCommand(), RunCommand() functions.

```APIDOC
## Command Utilities

### Description
Reference for command execution helpers, including the CommandWrapper type and ShellCommand(), RunCommand() functions.

### Types

#### CommandWrapper
- **Purpose**: Command wrapping function.

### Functions

#### ShellCommand
- **Purpose**: Command execution helper.

#### RunCommand
- **Purpose**: Command execution helper.
```

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

### Upload a file to an LXC container

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/05-communicator.md

Use this method to upload a file from a host reader to a specified destination path within the container. Ensure the file is opened and deferred closed, and file information is passed if available.

```go
file, err := os.Open("provisioner.sh")
if err != nil {
    log.Fatalf("Failed to open file: %v", err)
}
defer file.Close()

fi, _ := file.Stat()

err = comm.Upload("/opt/provisioner.sh", file, &fi)
if err != nil {
    log.Fatalf("Upload failed: %v", err)
}
```

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

### Define Logging Command Wrapper

Source: https://github.com/hashicorp/packer-plugin-lxc/blob/main/_autodocs/06-command.md

A CommandWrapper that logs the command string before returning it, useful for debugging execution.

```Go
loggingWrapper := func(cmd string) (string, error) {
    log.Printf("Executing: %s", cmd)
    return cmd, nil
}
```