### Install QEMU for Multi-Platform Builds

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Run this command to install QEMU user static binaries, which are required for emulating different CPU architectures during multi-platform builds.

```bash
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
```

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

### Kubernetes StatefulSet Example

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/MANIFEST.txt

This example demonstrates how to configure a Kubernetes StatefulSet for the docker-ssh-agent.

```yaml
# Kubernetes StatefulSet example
# ... YAML configuration ...
```

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

### Example of Register-NativeMethod Usage

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/windows-powershell-module.md

Example of how to register the 'CreateProfile' method from 'userenv.dll'. This prepares the method for compilation into a .NET type.

```powershell
Register-NativeMethod "userenv.dll" "int CreateProfile([MarshalAs(UnmanagedType.LPWStr)] string pszUserSid, [MarshalAs(UnmanagedType.LPWStr)] string pszUserName, [Out][MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszProfilePath, uint cchProfilePath)"
```

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

### Docker Run with Known Hosts (Usage Example)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/scripts-reference.md

Example of running the jenkins/ssh-agent Docker image with both an SSH public key and known hosts entries provided via environment variables.

```bash
docker run \
  -e "JENKINS_AGENT_SSH_PUBKEY=ssh-rsa AAAA..." \
  -e "JENKINS_AGENT_SSH_KNOWNHOST_0=github.com ssh-rsa BBBB..." \
  -e "JENKINS_AGENT_SSH_KNOWNHOST_1=gitlab.com ssh-rsa CCCC..." \
  jenkins/ssh-agent
```

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

### JDK Download URL Script Usage Examples

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/scripts-reference.md

Demonstrates how to use the `jdk-download-url.sh` script with environment variables or command-line arguments to specify the Java version, OS, and architecture.

```shell
export JAVA_VERSION=17.0.19_10
export OS=alpine
./jdk-download-url.sh
```

```shell
./jdk-download-url.sh 17.0.19_10 alpine
```

```shell
./jdk-download-url.sh 17.0.19_10 linux x64
```

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

### New-UserWithProfile

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/windows-powershell-module.md

Creates a Windows user account and initializes its user profile directory structure using net.exe for user creation and the CreateProfile API for profile setup.

```APIDOC
## New-UserWithProfile

### Description
Creates a Windows user account and initializes its user profile directory structure using net.exe for user creation and the CreateProfile API for profile setup.

### Parameters
#### Parameters
- **UserName** (string) - Required - Windows username to create
- **Description** (string) - Optional - Default: '' - Full name/description for user
```

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

### Docker Run Example

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/INDEX.md

Example of how to run the Jenkins Docker SSH Agent container. It maps the SSH port, mounts a volume for workspace, and sets the public key for authentication.

```bash
docker run -d \
  --name jenkins-agent \
  --publish 2200:22 \
  -v jenkins-workspace:/home/jenkins/agent \
  -e "JENKINS_AGENT_SSH_PUBKEY=ssh-rsa AAAA..." \
  jenkins/ssh-agent:debian-jdk21
```

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

### Test Execution with Make

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/INDEX.md

Commands to manage test execution using Make. Includes setup, running all tests, and running specific variant tests.

```bash
make prepare-test     # Setup test environment
make test            # Run all tests
make test-alpine_*   # Run specific variant tests
```

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

### Function Signature Example

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/README.md

Illustrates the format for function signatures used in this project, including parameter types and return types.

```bash
function_name(param1: type, param2: type) → return_type
```

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

### Groovy Configuration Example for Jenkins

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/MANIFEST.txt

This is an example of Groovy configuration used for integrating with the Jenkins SSH Build Agents Plugin.

```groovy
// Groovy configuration example (Jenkins SSH Build Agents Plugin)
// ... Groovy script ...
```

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

### Docker Compose Example for Jenkins SSH Agent

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/configuration.md

This example demonstrates how to configure the Jenkins SSH Agent service using Docker Compose. It specifies the image, environment variables, port mapping, volume mounts, and resource limits/reservations.

```yaml
services:
  jenkins-agent:
    image: jenkins/ssh-agent:debian-jdk21
    environment:
      JENKINS_AGENT_SSH_PUBKEY: "ssh-rsa AAAA..."
    ports:
      - "2200:22"
    volumes:
      - jenkins-workspace:/home/jenkins/agent
      - jenkins-metadata:/home/jenkins/.jenkins
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1024M
        reservations:
          cpus: '0.5'
          memory: 512M
```

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

### Example Usage of Add-NativeMethods and P/Invoke

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/windows-powershell-module.md

Demonstrates registering a method, compiling it into a .NET type named 'UserEnvCP', and then calling the compiled method. Ensure the necessary parameters like SID, username, and path are provided.

```powershell
Register-NativeMethod "userenv.dll" "int CreateProfile(...)"
Add-NativeMethods -typeName UserEnvCP
[UserEnvCP]::CreateProfile($sid, $username, $path, $pathLen)
```

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

### Build All Linux Images

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Builds all Linux targets using docker buildx bake. This command requires a cross-platform BuildKit setup (QEMU) and is push-only, not loading images into the local daemon.

```bash
docker buildx bake --file docker-bake.hcl linux
```

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

### Docker Bake Configuration (HCL2)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/README.md

Example of HCL2 syntax for Docker Bake, defining a target for an Alpine-based JDK 21 image.

```hcl
# Example docker-bake.hcl syntax
target "alpine_jdk21" {
  dockerfile = "alpine/Dockerfile"
}
```

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

### Clone and Setup BATS Testing Framework

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Clones the bats-core testing framework (v1.13.0) and creates a .git/submodule entry. This operation is idempotent and will skip if the framework is already cloned.

```bash
make bats
```

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

### Basic Docker Compose Setup

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

A basic Docker Compose file to run a Jenkins SSH agent. It configures the image, ports, SSH public key, and persistent volumes for workspace and metadata. Use this for a standard agent setup.

```yaml
version: '3.8'

services:
  jenkins-agent:
    image: jenkins/ssh-agent:debian-jdk21
    ports:
      - "2200:22"
    environment:
      JENKINS_AGENT_SSH_PUBKEY: 'ssh-rsa AAAA...'
    volumes:
      - agent-workspace:/home/jenkins/agent
      - agent-metadata:/home/jenkins/.jenkins
    restart: unless-stopped

volumes:
  agent-workspace:
  agent-metadata:
```

```bash
docker compose up -d
docker compose logs -f jenkins-agent
docker compose down
```

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

### Start SSH Agent Container (Windows)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Starts the jenkins/ssh-agent Docker container on Windows, using PowerShell syntax for commands. It publishes port 22 and configures the SSH public key.

```powershell
docker run -d `
  --name jenkins-agent `
  --publish 2200:22 `
  -e "JENKINS_AGENT_SSH_PUBKEY=ssh-rsa AAAA..." `
  jenkins/ssh-agent:nanoserver-ltsc2022-jdk21
```

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

### Verify Java Installation

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Check the installed Java Development Kit (JDK) version within the container. This command is executed remotely via SSH.

```bash
ssh jenkins@localhost "java -version"
```

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

### Check Git and Git LFS Installation

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Verify the installed versions of Git and Git Large File Storage (LFS) within the container. Both commands are executed remotely via SSH.

```bash
ssh jenkins@localhost "git --version"
ssh jenkins@localhost "git-lfs version"
```

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

### Create New User with Profile

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/exported-symbols.md

Creates a new local Windows user account, adds it to the Administrators group, creates a user profile directory, and initializes the user's registry hive. This function automates the setup for a new user.

```powershell
function New-UserWithProfile {
    [CmdletBinding()]
    [Alias()]
    [OutputType([int])]
    Param(
        [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=0)]
        [string]$UserName,
        
        [Parameter(Mandatory=$false, ValueFromPipelineByPropertyName=$true, Position=1)]
        [string]$Description = ''
    )
}
```

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

### Build and Run Docker Compose Services (Windows)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/windows-powershell-module.md

Commands to build Docker images and start services defined in a Docker Compose file on Windows. Use 'up -d' to run services in detached mode.

```powershell
docker compose --file=build-windows.yaml build
```

```powershell
docker compose --file=build-windows.yaml up -d
```

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

### Run Agent on Custom Network

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Starts the SSH agent container and attaches it to the `jenkins-net` network. This enables communication with other containers on the same network.

```bash
docker run -d \
  --name jenkins-agent \
  --network jenkins-net \
  -e "JENKINS_AGENT_SSH_PUBKEY=ssh-rsa AAAA..." \
  jenkins/ssh-agent:debian-jdk21
```

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

### Build Custom SSH Agent Image

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Builds a custom Docker image for the SSH agent using a provided Dockerfile. This example demonstrates overriding build arguments for user, UID, and home directory.

```bash
docker build \
  --build-arg user=buildbot \
  --build-arg uid=1500 \
  --build-arg JENKINS_AGENT_HOME=/opt/buildbot \
  -t custom-ssh-agent:jdk21 \
  -f debian/Dockerfile .
```

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

### Download and Extract JDK Script

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/scripts-reference.md

This script downloads a specified Java Development Kit version from Adoptium, extracts it, and renames the directory. It requires `curl` and `tar` to be installed and handles OS parameter variations.

```shell
#!/bin/bash

# Script to download and extract JDK from Adoptium API

# Default OS
OS="standard"

# Check for required tools
command -v curl >/dev/null 2>&1 || { echo >&2 "Error: curl is required but not installed. Aborting."; exit 1; }
command -v tar >/dev/null 2>&1 || { echo >&2 "Error: tar is required but not installed. Aborting."; exit 1; }

# Process OS argument
if [ "$#" -eq 1 ]; then
  OS="$1"
elif [ "$#" -gt 1 ]; then
  echo >&2 "Usage: $0 [OS]"
  exit 1
fi

# Validate OS parameter
case "$OS" in
  "standard" | "alpine" | "windows")
    ;; # Valid OS
  *)
    echo >&2 "Error: Invalid OS parameter '$OS'. Valid options are 'standard', 'alpine', or 'windows'."
    exit 1
    ;; 
esac

# Retrieve download URL
DOWNLOAD_URL=$(./jdk-download-url.sh "${JAVA_VERSION}" "${OS}")

if [ -z "$DOWNLOAD_URL" ]; then
  echo >&2 "Error: Failed to retrieve download URL."
  exit 1
fi

# Download JDK
echo "Downloading JDK from: $DOWNLOAD_URL"
curl -L "$DOWNLOAD_URL" -o /tmp/jdk.tar.gz

if [ $? -ne 0 ]; then
  echo >&2 "Error: Download failed."
  exit 1
fi

# Extract JDK
echo "Extracting JDK to /opt/"
tar -xzf /tmp/jdk.tar.gz -C /opt/

if [ $? -ne 0 ]; then
  echo >&2 "Error: Extraction failed."
  exit 1
fi

# Get the extracted directory name
EXTRACTED_DIR=$(tar -tzf /tmp/jdk.tar.gz | head -1 | cut -f1 -d"/")

# Rename directory
if [ -n "$EXTRACTED_DIR" ]; then
  echo "Renaming extracted directory to /opt/jdk-${JAVA_VERSION}"
  mv "/opt/${EXTRACTED_DIR}" "/opt/jdk-${JAVA_VERSION}"
  if [ $? -ne 0 ]; then
    echo >&2 "Error: Directory rename failed."
    exit 1
  fi
else
  echo >&2 "Error: Could not determine extracted directory name."
  exit 1
fi

# Cleanup
rm /tmp/jdk.tar.gz

echo "JDK ${JAVA_VERSION} downloaded and extracted successfully."
exit 0

```

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

### GitHub Actions Workflow for Building Release Images

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Example GitHub Actions workflow that triggers on tag pushes and uses `docker buildx bake` to build and push release images. It dynamically sets the version from the Git tag.

```yaml
on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: docker/setup-buildx-action@v2
      - run: docker buildx bake --set '*.args.ON_TAG=true' --set '*.args.VERSION=${{ github.ref_name }}' linux --push
```

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

### Run Docker SSH Agent with Default Volumes (Linux)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/configuration.md

Example of running the Docker SSH Agent with default volume mounts for workspace and metadata. The JENKINS_AGENT_SSH_PUBKEY environment variable is required for agent authentication.

```bash
docker run \
  -v jenkins-agent-workspace:/home/jenkins/agent \
  -v jenkins-agent-metadata:/home/jenkins/.jenkins \
  -e "JENKINS_AGENT_SSH_PUBKEY=..." \
  jenkins/ssh-agent
```

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

### Run SSH Agent with Environment Variables

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Starts the SSH agent container and sets several environment variables. These variables can be accessed within the SSH session for build context.

```bash
docker run -d \
  --publish 2200:22 \
  -e "JENKINS_AGENT_SSH_PUBKEY=ssh-rsa AAAA..." \
  -e "BUILD_NUM_EXECUTORS=4" \
  -e "JENKINS_NODE_LABELS=docker linux" \
  -e "CI=true" \
  jenkins/ssh-agent:debian-jdk21
```

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

### Build Specific Docker Image

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/README.md

Construct a specific Docker image by specifying the operating system and JDK version. For example, to build the JDK 17 image on Alpine Linux, use 'make build-alpine_jdk17'.

```bash
make build-<OS>_<JDK_VERSION>
```

```bash
make build-alpine_jdk17
```

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

### New-TestContainer

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/windows-powershell-module.md

Creates and starts a new Docker container for testing. It can optionally pull the specified image if it's not already present and maps the SSH port. The function returns an object containing details about the created container.

```APIDOC
## New-TestContainer

### Description
Creates and starts a new Docker container for testing. It can optionally pull the specified image if it's not already present and maps the SSH port. The function returns an object containing details about the created container.

### Method
Cmdlet

### Parameters
#### Path Parameters
- **ImageName** (string) - Required - Docker image name/tag
- **SshPort** (int) - Optional - Container SSH port (default: 22)

### Returns
Container object with:
- Id: Container ID
- IP: Container IP address
- Port: Mapped SSH port on host
```

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

### Valid SSH Public Key Formats

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/configuration.md

Examples of valid SSH public key formats supported by the Jenkins SSH agent. Ensure keys start with 'ssh-' and are in single-line format.

```text
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7...
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTY...
```

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

### Custom Entrypoint for SSH Host Key Persistence

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/dockerfile-reference.md

This bash script demonstrates how to persist SSH host keys across container restarts. It copies keys from a volume, generates missing ones, and then copies them back to the volume after starting the SSH daemon.

```bash
#!/bin/bash
mkdir -p /mnt/agent/host_keys/
cp -u /mnt/agent/host_keys/ssh_host*_key* /etc/ssh/
ssh-keygen -A
cp -u /etc/ssh/ssh_host*_key* /mnt/agent/host_keys/
exec setup-sshd "$@"
```

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

### Run Docker SSH Agent with Custom Volume Path (Linux)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/configuration.md

Example of running the Docker SSH Agent with a custom volume path for the agent. This allows flexibility in where the agent's files are stored. The JENKINS_AGENT_SSH_PUBKEY environment variable is required for agent authentication.

```bash
docker run \
  -v jenkins-agent:/opt/buildbot/agent \
  -e "JENKINS_AGENT_SSH_PUBKEY=..." \
  jenkins/ssh-agent:alpine-jdk21
```

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

### Choose Minimal Base Image

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Select the appropriate base image (alpine, debian, nanoserver) based on your needs for footprint, startup time, and included build tools. Alpine offers the smallest footprint.

```bash
docker run jenkins/ssh-agent:alpine-jdk21
```

```bash
docker run jenkins/ssh-agent:debian-jdk21
```

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

### Initialize Docker Buildx for Jenkins CI

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Initializes the Docker buildx builder and sets up QEMU for multi-platform builds, specifically tailored for Jenkins CI infrastructure. It handles different configurations based on the presence of /etc/buildkitd.toml.

```bash
make docker-init
```

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

### Show Detailed Image Build Information

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/README.md

Display detailed information about the images that will be built, including tags, platforms, and Dockerfiles.

```bash
make show
```

```json
{
  "group": {
    "default": {
      "targets": [
        "alpine_jdk17",
        "alpine_jdk11",
        "debian_jdk11",
        "debian_jdk17",
      ]
    }
  },
  "target": {
    "alpine_jdk11": {
      "context": ".",
      "dockerfile": "alpine/Dockerfile",
      "tags": [
        "docker.io/jenkins/ssh-agent:alpine-jdk11",
        "docker.io/jenkins/ssh-agent:latest-alpine-jdk11"
      ],
      "platforms": [
        "linux/amd64"
      ],
      "output": [
        "type=docker"
      ]
    },
    "[...]"
  }
}
```

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

### Initial Build

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/scripts-reference.md

Execute the script for an initial build without any specific parameters.

```powershell
.\build.ps1
```

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

### Start SSH Agent Container (Linux)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Starts the jenkins/ssh-agent Docker container in detached mode, publishing port 22, and setting the SSH public key. Use this for basic Linux environments.

```bash
docker run -d \
  --name jenkins-agent \
  --publish 2200:22 \
  -e "JENKINS_AGENT_SSH_PUBKEY=ssh-rsa AAAA..." \
  jenkins/ssh-agent:debian-jdk21
```

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

### Prepare Test Environment

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Prepares the environment for running tests by cloning the BATS testing framework, initializing git submodules, and creating a target/ directory.

```bash
make prepare-test
```

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

### Validate SSH Public Key Format

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/INDEX.md

This script snippet checks if the JENKINS_AGENT_SSH_PUBKEY environment variable starts with 'ssh-'. If it does, it proceeds to write the key.

```bash
if [[ ${JENKINS_AGENT_SSH_PUBKEY} == ssh-* ]]; then
  write_key "${JENKINS_AGENT_SSH_PUBKEY}"
fi
```

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

### Display Detailed Build Configuration

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Outputs a JSON representation of all build targets, including tags, platforms, and Dockerfiles. This is useful for understanding the complete build configuration.

```json
{
  "group": {
    "default": {
      "targets": ["alpine_jdk17", "alpine_jdk21", ...]
    }
  },
  "target": {
    "alpine_jdk21": {
      "context": ".",
      "dockerfile": "alpine/Dockerfile",
      "tags": ["docker.io/jenkins/ssh-agent:alpine-jdk21", ...],
      "platforms": ["linux/amd64", "linux/arm64"],
      "output": ["type=docker"]
    }
  }
}
```

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

### Connect to SSH Agent on Custom Port

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Connects to the SSH agent container using the custom port (2222 in this example) that was published during container startup.

```bash
ssh -p 2222 jenkins@localhost
```

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

### Test SSH Connectivity to Agent

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/INDEX.md

Verify SSH connectivity to the running agent on localhost:2200 and check the versions of Java and Git installed within the container.

```bash
ssh -p 2200 jenkins@localhost "java -version && git --version"
```

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

### Create Docker Buildx Builder with Container Driver

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Create and use a new Docker Buildx builder instance that utilizes the container driver. This is a prerequisite for multi-platform builds.

```bash
docker buildx create --use --bootstrap --driver docker-container
```

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

### List Available Targets for Current Architecture

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Lists all available build targets for the current architecture, with each target on a new line. This helps in identifying which images can be built locally.

```text
alpine_jdk17
alpine_jdk21
debian_jdk17
debian_jdk21
```

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

### Connect to SSH Agent (Linux)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Connects to the running jenkins/ssh-agent container using SSH on the published port. Ensure the agent is started before attempting to connect.

```bash
ssh -p 2200 jenkins@localhost
```

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

### JDK Download URL Script (Bash)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/MANIFEST.txt

This Bash script, jdk-download-url.sh, acts as a wrapper for the Adoptium API to download JDKs.

```bash
# jdk-download-url.sh - Adoptium API wrapper
# ... script content ...
```

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

### Docker Run with Custom SSHD Arguments

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/scripts-reference.md

Example of running the Jenkins SSH Agent container and passing custom arguments to the sshd daemon, such as specifying a different port.

```bash
docker run jenkins/ssh-agent -p 2222 -v
```

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

### New-UserWithProfile

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/exported-symbols.md

Creates a new local Windows user account with a profile. This function also adds the user to the Administrators group, creates their profile directory, and initializes their registry hive.

```APIDOC
## New-UserWithProfile

### Description
Creates a new local Windows user account with a profile. This function also adds the user to the Administrators group, creates their profile directory, and initializes their registry hive.

### Method
PowerShell Function

### Parameters
#### Parameters
- **UserName** (string) - Mandatory - Windows username to create
- **Description** (string) - Optional, default: '' - User description/full name

### Return Type
int (not used)

### Side Effects
- Creates local user account
- Adds user to Administrators group
- Creates user profile directory
- Initializes registry hive
```

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

### Run Jenkins Controller on Custom Network

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Starts a Jenkins controller container on the `jenkins-net` network. This allows the SSH agent container to connect to the controller using its hostname.

```bash
docker run -d \
  --name jenkins-controller \
  --network jenkins-net \
  jenkins/jenkins:lts
```

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

### Create User with Profile Function

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/windows-powershell-module.md

Creates a Windows user account and initializes its user profile directory structure. This function combines user creation via `net.exe` with profile creation via the `CreateProfile` API and profile initialization.

```powershell
function New-UserWithProfile {
    [CmdletBinding()]
    [Alias()]
    [OutputType([int])]
    Param(
        [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=0)]
        [string]$UserName,
        
        [Parameter(Mandatory=$false, ValueFromPipelineByPropertyName=$true, Position=1)]
        [string]$Description = ''
    )
    
    # User creation via net.exe
    # Profile creation via CreateProfile API
    # Profile initialization via NTUSER.DAT copy
}
```

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

### Build and Test Windows Images

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Commands to build Windows Docker images and then execute the test harness using a PowerShell script.

```powershell
build.ps1
build.ps1 test
```

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

### Windows PowerShell Setup SSHD Functions

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/MANIFEST.txt

This section details the functions within the setup-sshd.ps1 script for Windows PowerShell. These functions manage SSH configurations and user profiles.

```powershell
# setup-sshd.ps1 (Windows PowerShell)
# 4 functions

# Function to register native methods for P/Invoke
function Register-NativeMethod {
    param(
        [string]$DllPath,
        [string]$FunctionName,
        [array]$Arguments
    )
    # ... implementation details ...
}

# Function to add native methods for compilation
function Add-NativeMethods {
    param(
        [string]$SourcePath,
        [string]$OutputPath
    )
    # ... implementation details ...
}

# Function to create a new user with a profile
function New-UserWithProfile {
    param(
        [string]$UserName,
        [string]$Password,
        [string]$ProfilePath
    )
    # ... implementation details ...
}

# Function to manage SSH daemon configuration
function Setup-Sshd {
    param(
        [string]$SshdConfigPath,
        [string]$HostKeyPath
    )
    # ... implementation details ...
}
```

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

### Build All Docker Images

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/README.md

Build all available Docker images, including those not supported by your current architecture.

```bash
make every-build
```

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

### Dockerfile Excerpt for Windows Container Build

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/windows-powershell-module.md

Shows how to copy, import, and use the PowerShell module within a Dockerfile to create a user with a profile in a Windows container.

```dockerfile
COPY CreateProfile.psm1 C:/

# Create user and user directory
RUN Import-Module -Force C:/CreateProfile.psm1 ; \
    New-UserWithProfile -UserName $env:JENKINS_AGENT_USER -Description 'Jenkins Agent User' ; \
    Remove-Item -Force C:/CreateProfile.psm1
```

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

### Get SSH Directory Path (PowerShell)

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/scripts-reference.md

Returns the full path to the .ssh directory for the Jenkins agent user. This is a helper function for managing SSH configuration files.

```powershell
function Get-SSHDir {
    return Join-Path "C:/Users/$env:JENKINS_AGENT_USER" '.ssh'
}
```

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

### Jenkins Declarative Pipeline Agent Configuration

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/configuration.md

Example of how to configure an agent in a Jenkins Declarative Pipeline to use a Docker SSH agent. Ensure the label matches your agent configuration.

```groovy
// In Jenkins Declarative Pipeline:
agent {
  label 'docker-ssh-agent'
}
```

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

### Build Docker Image for Multiple Platforms

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Build a Docker image for specified platforms (e.g., amd64 and arm64). The `--platform` flag is essential for cross-platform compatibility.

```bash
docker buildx build --platform linux/amd64,linux/arm64 .
```

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

### Build Docker Images for Current Architecture

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/README.md

Build all Docker images that are supported by your current system architecture.

```bash
make build
```

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

### Docker Run with SSH Public Key as Command Argument

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/scripts-reference.md

Example of running the Jenkins SSH Agent container, passing the SSH public key as a direct command-line argument.

```bash
docker run jenkins/ssh-agent "ssh-rsa AAAA..."
```

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

### Initialize User Profile by Copying NTUSER.DAT

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/windows-powershell-module.md

Ensures that a user's registry hive (NTUSER.DAT) is initialized for their profile. If the hive is missing after profile creation, it copies the default hive from 'C:\Users\Default' to the new profile path.

```powershell
$profilePath = $sb.ToString()
if(-not (Test-Path (Join-Path $profilePath "NTUSER.DAT"))) {
    Copy-Item "C:\Users\Default\NTUSER.DAT" $profilePath
}
```

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

### Customize Build Arguments with docker buildx bake --set

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Illustrates how to set specific build arguments for a target ('debian_21') using the --set flag with docker buildx bake.

```bash
docker buildx bake \
  --set 'debian_21.args.JAVA_VERSION=21.0.11_10' \
  --set 'debian_21.args.user=myuser' \
  debian_21
```

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

### Custom Dockerfile for Jenkins Agent

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Extend the base jenkins/ssh-agent image by installing additional packages (Python, pip, Maven) and custom tools. This Dockerfile sets up a more feature-rich agent environment.

```dockerfile
FROM jenkins/ssh-agent:debian-jdk21

USER root

# Install additional packages
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 \
    python3-pip \
    maven \
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
RUN pip3 install pytest requests

# Create custom build tools directory
RUN mkdir -p /opt/custom-tools
COPY ./tools/ /opt/custom-tools/

# Update PATH
ENV PATH="/opt/custom-tools/bin:${PATH}"

USER jenkins
```

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

### Define and Use Build Argument in Dockerfile

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/build-system.md

Shows how to declare a build argument in a Dockerfile, with a default value, and how it can be overridden.

```dockerfile
ARG JAVA_VERSION=17.0.19_10
# Can be overridden, defaults to 17 if not provided
```

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

### Extend Jenkins SSH Agent Docker Image

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/README.md

A Dockerfile example showing how to extend the base jenkins/ssh-agent image. This allows adding custom files or configurations, such as SSH keys, to the agent image.

```Dockerfile
FROM jenkins/ssh-agent:debian-jdk17 as ssh-agent
# [...]
COPY --chown=jenkins mykey "${JENKINS_AGENT_HOME}"/.ssh/mykey
# [...]
```

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

### Dynamic Configuration with ARG in Dockerfile

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Use build arguments (ARG) to dynamically configure versions of software like Maven and Gradle during the Docker image build process. This allows for flexible image creation without modifying the Dockerfile content directly.

```dockerfile
FROM jenkins/ssh-agent:debian-jdk21

ARG MAVEN_VERSION=3.8.1
ARG GRADLE_VERSION=7.0

RUN apt-get update && apt-get install -y --no-install-recommends \
    curl unzip \
    && rm -rf /var/lib/apt/lists/*

RUN curl -fsSL "https://archive.apache.org/dist/maven/maven-3/${MAVEN_VERSION}/apache-maven-${MAVEN_VERSION}-bin.zip" \
    -o /tmp/maven.zip && unzip /tmp/maven.zip -d /opt/ && rm /tmp/maven.zip

ENV PATH="/opt/apache-maven-${MAVEN_VERSION}/bin:${PATH}"
```

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

### Docker Build Targets

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/exported-symbols.md

Lists various build targets, representing matrix combinations for different operating systems, JDK versions, and Windows server core versions.

```text
alpine_17, alpine_21, alpine_25
debian_17, debian_21, debian_25
nanoserver-ltsc2019_17, nanoserver-ltsc2019_21, nanoserver-ltsc2019_25
nanoserver-ltsc2022_17, nanoserver-ltsc2022_21, nanoserver-ltsc2022_25
windowsservercore-ltsc2019_17, windowsservercore-ltsc2019_21, ...
windowsservercore-ltsc2022_17, windowsservercore-ltsc2022_21, ...
```

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

### Docker Run with Additional Command Execution

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/scripts-reference.md

Example of running the Jenkins SSH Agent container and executing additional commands after the SSH server is set up, such as running a custom script or keeping the container alive.

```bash
docker run jenkins/ssh-agent bash -c "echo 'custom' && /bin/sleep 99999"
```

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

### Build and Test with Debug Output

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/scripts-reference.md

Build images and run tests with verbose debug output by specifying the 'test' command and the TestsDebug parameter.

```powershell
.\build.ps1 test -TestsDebug 'verbose'
```

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

### Test Specific Docker Image

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/README.md

Test a particular Docker image by specifying the operating system and JDK version. For example, to test the JDK 17 image on Alpine Linux, use 'make test-alpine_jdk17'.

```bash
make test-<OS>_<JDK_VERSION>
```

```bash
make test-alpine_jdk17
```

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

### Make Build Commands

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/INDEX.md

Use these make commands to build, test, and publish the Docker SSH Agent image. Specify variants for targeted builds or tests.

```bash
make build                           # Build for current architecture
make build-alpine_jdk21             # Build specific variant
make test                           # Run full test suite
make test-debian_jdk21              # Test specific variant
make publish                        # Push to registry
make list                           # List available targets
make show                           # Show build configuration
```

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

### Troubleshoot Permission Denied

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Address 'Permission denied' errors by verifying SSH key format, file permissions within the container, and ensuring the public key is correctly configured.

```bash
docker exec jenkins-agent cat /home/jenkins/.ssh/authorized_keys
```

```bash
docker exec jenkins-agent ls -la /home/jenkins/.ssh/
```

```bash
ssh-keyscan -p 2200 localhost > /tmp/host_key.txt
```

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

### Build All Images

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/exported-symbols.md

Builds all Docker images for the current architecture using docker buildx bake. Ensure docker-ssh-agent is cloned locally.

```bash
docker buildx bake --file docker-bake.hcl [targets] --set '*.platform=linux/$(ARCH)'
```

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

### Run SSH Agent with Custom Port

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

Starts the SSH agent container and maps host port 2222 to the container's port 22. This is useful if port 22 is already in use on the host.

```bash
docker run -d \
  --publish 2222:22 \
  -e "JENKINS_AGENT_SSH_PUBKEY=ssh-rsa AAAA..." \
  jenkins/ssh-agent
```

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

### Build Docker Images with Docker Compose

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/README.md

Use this command to build Docker images and store the result in a docker compose file. It pipes the output of `docker buildx bake` through `yq` to format it as a services definition for docker compose.

```bash
$ docker buildx bake --progress=plain --file=docker-bake.hcl windows --print `
    | yq --prettyPrint '.target[] | del(.output) | {(. | key): {"image": .tags[0], "build": .}}' | yq '{"services": .}' `
    | Out-File -FilePath build-windows.yaml
```

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

### Build Docker Image with Custom Settings

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/INDEX.md

Build a Docker image for the SSH agent with custom build arguments for user, UID, and Java version. This allows for tailored image creation.

```bash
docker build \
  --build-arg user=jenkins \
  --build-arg uid=1000 \
  --build-arg JAVA_VERSION=21.0.11_10 \
  -t my-ssh-agent:jdk21 \
  -f debian/Dockerfile .
```

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

### Initialize SSH Host Keys

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/README.md

This script initializes SSH host keys within a mounted agent volume and ensures they are copied to the correct locations for SSH server operation.

```bash
mkdir -p /mnt/agent/host_keys/

cp -u /mnt/agent/host_keys/ssh_host*_key* /etc/ssh/

ssh-keygen -A

cp -u /etc/ssh/ssh_host*_key* /mnt/agent/host_keys/
```

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

### Define New-TestContainer Function

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/windows-powershell-module.md

Defines the New-TestContainer function which pulls a Docker image, creates and starts a container, maps the SSH port, and returns a container object. It accepts the image name and an optional SSH port.

```powershell
function New-TestContainer {
    [CmdletBinding()]
    Param(
        [Parameter(Mandatory=$true)]
        [string]$ImageName,
        
        [Parameter(Mandatory=$false)]
        [int]$SshPort = 22
    )
    
    # Pulls image if needed
    # Creates and starts container
    # Maps SSH port
    # Returns container object
}
```

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

### Custom User and Home Directory Build Argument

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/INDEX.md

This bash command demonstrates how to customize the user, user ID, and home directory for the agent within the Docker container during the build process.

```bash
docker build \
  --build-arg user=buildbot \
  --build-arg uid=1500 \
  --build-arg JENKINS_AGENT_HOME=/opt/buildbot \
  -f debian/Dockerfile .
```

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

### Windows Directory Structure

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/configuration.md

Details the directory layout for the Jenkins agent on a Windows system. Covers user home, SSH configuration, build workspaces, Java installations, and essential tools like OpenSSH, PowerShell, and Git.

```bash
C:\Users\jenkins\                       # JENKINS_AGENT_USER home
    ├── .ssh\                               # SSH directory
    │   └── authorized_keys                 # Public keys
    ├── Work\                               # JENKINS_AGENT_WORK
    │   └── (build workspace)
    └── AppData\Local\Temp\                 # Temporary files

C:\openjdk-21\                          # JAVA_HOME
    ├── bin\                                # Java executables
    ├── lib\                                # Java libraries
    └── (jdk modules)

C:\jdk-21 → C:\openjdk-21              # Symlink for backward compat

C:\Program Files\OpenSSH-Win64\         # Win32-OpenSSH
    ├── ssh.exe
    └── sshd.exe

C:\Program Files\Powershell\            # PowerShell (pwsh.exe)

C:\Program Files\MinGit\                # MinGit installation
    └── cmd\                                # Git commands

C:\mingit\mingw64\bin\                  # Git LFS
    └── git-lfs.exe

C:\ProgramData\ssh\                     # SSH service directory
    ├── sshd_config                         # Modified configuration
    └── logs\
        └── sshd.log                        # SSH service logs
```

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

### Run Pester Test Suite on Windows

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/INDEX.md

Execute the Pester test suite on a Windows environment using a specific image type. This checks container creation, SSH service startup, user account setup, and Java/Git availability.

```powershell
.\build.ps1 test -ImageType 'nanoserver-ltsc2022'
```

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

### Docker Compose with Host Key Persistence

Source: https://github.com/jenkinsci/docker-ssh-agent/blob/master/_autodocs/usage-patterns.md

This Docker Compose setup includes volume mounting for SSH keys (`/etc/ssh`). This ensures that SSH host keys persist across container recreations, which is useful for maintaining consistent SSH configurations.

```yaml
version: '3.8'

services:
  jenkins-agent:
    image: jenkins/ssh-agent:debian-jdk21
    ports:
      - "2200:22"
    environment:
      JENKINS_AGENT_SSH_PUBKEY: 'ssh-rsa AAAA...'
    volumes:
      - agent-workspace:/home/jenkins/agent
      - agent-ssh-keys:/etc/ssh
    restart: unless-stopped

volumes:
  agent-workspace:
  agent-ssh-keys:
```