Skopeo

The proxy uses a SOCK_SEQPACKET socket for control messages and pipe(2) for large data payloads (manifests and blobs).

Message Formats

Request Format (JSON):

{ "method": "MethodName", "args": [arguments] }

Reply Format (JSON):

{ "success": boolean, "value": JSONValue, "pipeid": number, "error_code": string, "error": string }

• success: true if the call succeeded, false otherwise.
• value: The return value of the method (e.g., an image ID or digest).
• pipeid: An integer identifying a pipe for data transfer. This ID must be used with the FinishPipe method.
• error_code: A string indicating the error type (e.g., EPIPE, retryable, other). Introduced in version 0.2.8.
• error: A string describing the error.

Data Transfer Lifecycle

1. The client sends a request via the socket.
2. The server replies with a JSON object containing a pipeid and the value.
3. The server passes the read-end of a pipe via file descriptor (FD) passing.
4. The client reads the data from the passed FD.
5. Crucial: After consuming all data, the client must call FinishPipe with the corresponding pipeid. This allows the server to clean up and report errors (like digest mismatches) that occurred during streaming.

Skopeo uses specific transport prefixes to identify the storage mechanism of an image or repository. When performing operations like copy, inspect, or delete, you must prefix your image references with one of the following:

• containers-storage:docker-reference: An image in a local containers/storage image store (used by Podman, CRI-O, and Buildah). The location and store are defined in /etc/containers/storage.conf.
• dir:path: A local directory containing the manifest, layer tarballs, and signatures as individual files.
• docker://docker-reference: An image in a registry implementing the "Docker Registry HTTP API V2".
• docker-archive:path[:docker-reference]: An image stored in a docker save-formatted file. When creating such a file, docker-reference must not contain a digest.
• docker-daemon:docker-reference: An image stored in the Docker daemon's internal storage. For reading, you can use docker-daemon:algo:digest (an image ID).
• oci:path:tag: An image tag in a directory compliant with the "Open Container Image Layout Specification".

Skopeo uses a transport:details format to reference container images. This allows you to interact with images across different storage backends without needing a container runtime. Common transports include:

• containers-storage:docker-reference: Images in a local containers/storage store (used by Podman, CRI-O, etc.).
• docker://docker-reference: Images in a registry implementing the Docker Registry HTTP API V2.
• dir:path: A local directory containing manifest, layer tarballs, and signatures.
• docker-archive:path[:docker-reference]: Images in a docker save formatted file.
• docker-daemon:docker-reference: Images stored in the Docker daemon's internal storage.
• oci:path:tag: Images in a directory following the OCI Layout Specification.
• oci-archive:path:tag: Images in an OCI-compliant tar archive.

docker://registry.example.com/my-image:latest
containers-storage:localhost/my-image:latest
dir:/tmp/image-layers

When using --src yaml, you can provide a YAML file that defines complex synchronization rules, including specific tags, regex patterns, and semantic version constraints for multiple registries.

YAML Structure

• images: A map of repository names to a list of specific tags or digests.
• images-by-tag-regex: A map of repository names to regex patterns for matching tags.
• images-by-semver: A map of repository names to semantic version constraints.
• credentials: Registry-specific username and password.
• tls-verify: Boolean to enable/disable TLS verification for that registry.
• cert-dir: Path to certificates for that registry.

Example YAML (sync.yml)

registry.example.com:
    images:
        busybox: []
        redis:
            - "1.0"
            - "2.0"
            - "sha256:0000000000000000000000000000000011111111111111111111111111111111"
    images-by-tag-regex:
        nginx: ^1\.13\.[12]-alpine-perl$
    images-by-semver:
        alpine: ">= 3.12.0"
    credentials:
        username: john
        password: this is a secret
    tls-verify: true
    cert-dir: /home/john/certs
quay.io:
    tls-verify: false
    images:
        coreos/etcd:
            - latest

Running the sync

$ skopeo sync --src yaml --dest docker sync.yml my-registry.local.lan/repo/

The skopeo experimental-image-proxy command is an experimental API server that provides a lightweight way to fetch container image content (manifests and blobs) via a custom JSON+fd-passing protocol. It is primarily intended for programs that need to operate on custom storage backends (e.g., the bootc project's ostree-based storage) that Skopeo does not natively handle.

Setup and Execution

To use the proxy, the client process must create a socketpair(2) of type SOCK_SEQPACKET. One end of the socket is passed to the proxy.

By default, the proxy expects the socket to be provided on standard input (file descriptor 0). You can specify a different file descriptor using the --sockfd option.

Note: This command is experimental, its API is subject to change, it is currently hidden from main help outputs, and it is not supported on Windows.

skopeo experimental-image-proxy [--sockfd fd] [options]

Skopeo allows you to encrypt image layers during the copy process using a JWE (JSON Web Encryption) key.

Encryption

Use the --encryption-key flag followed by the jwe: prefix and the path to your public key. You can also target specific layers using --encrypt-layer with 0-indexed or negative indexing (e.g., 0 for the first layer, -1 for the last).

Decryption

Use the --decryption-key flag with the path to your private key. If an image requires multiple keys, you can provide multiple --decryption-key flags.

Key Details

• Partial Encryption: Use --encrypt-layer <index> to encrypt only a specific layer.
• Multiple Keys: Pass --decryption-key multiple times for images requiring multiple keys.

# Encrypt an image
$ skopeo copy --encryption-key jwe:./public.key oci:local_nginx:1.17.8 oci:try-encrypt:encrypted

# Encrypt only the 2nd layer (index 1)
$ skopeo copy --encryption-key jwe:./public.key --encrypt-layer 1 oci:local_nginx:1.17.8 oci:try-encrypt:encrypted

# Decrypt an image
$ skopeo copy --decryption-key ./private.key oci:try-encrypt:encrypted oci:try-decrypt:decrypted

# Decrypt an image requiring multiple keys
$ skopeo copy --decryption-key ./private1.key --decryption-key ./private2.key --decryption-key ./private3.key oci:try-encrypt:encrypted oci:try-decrypt:decrypted