Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fussybeaver/bollard/llms.txt

Use this file to discover all available pages before exploring further.

Bollard uses Rustls to establish mutually-authenticated TLS connections to remote Docker daemons. Both the server certificate authority chain and the client certificate/key are configured through environment variables or passed directly to the connection constructor.
SSL/TLS support requires exactly one crypto-provider feature flag. Enabling more than one will cause a compile-time error. See the feature flags section below for the full list.

​
Docker::connect_with_ssl_defaults

Reads the target host from DOCKER_HOST (falling back to tcp://localhost:2375) and locates certificates in the directory pointed to by DOCKER_CERT_PATH. The expected files are:
FilePurpose
key.pemClient private key
cert.pemClient certificate
ca.pemCertificate authority chain used to verify the server
use bollard::Docker;

#[cfg(feature = "ssl")]
let docker = Docker::connect_with_ssl_defaults().unwrap();

​
Function signature

pub fn connect_with_ssl_defaults() -> Result<Docker, Error>

​
Address resolution

  1. DOCKER_HOST environment variable (e.g. tcp://docker.example.com:2376).
  2. Falls back to "tcp://localhost:2375" if unset.

​
Certificate resolution (default_cert_path)

The helper DockerClientCertResolver::default_cert_path() determines the certificate directory using this precedence:
  1. DOCKER_CERT_PATH environment variable.
  2. DOCKER_CONFIG environment variable.
  3. ~/.docker (home directory fallback).

​
Docker::connect_with_ssl

Pass all parameters explicitly — useful when certificates are stored outside the default location, or when you need to connect to multiple daemons with different credentials. 
use bollard::{API_DEFAULT_VERSION, Docker};
use std::path::Path;

#[cfg(feature = "ssl")]
let docker = Docker::connect_with_ssl(
    "tcp://docker.example.com:2376",
    Path::new("/certs/key.pem"),
    Path::new("/certs/cert.pem"),
    Path::new("/certs/ca.pem"),
    120,
    API_DEFAULT_VERSION,
).unwrap();

​
Function signature

pub fn connect_with_ssl(
    addr: &str,
    ssl_key: &Path,
    ssl_cert: &Path,
    ssl_ca: &Path,
    timeout: u64,
    client_version: &ClientVersion,
) -> Result<Docker, Error>
ParameterTypeDescription
addr&strTarget URL — tcp:// or https:// scheme accepted.
ssl_key&PathPath to the PEM-encoded private key (key.pem).
ssl_cert&PathPath to the PEM-encoded client certificate (cert.pem).
ssl_ca&PathPath to the PEM-encoded CA chain (ca.pem).
timeoutu64Read/write timeout in seconds.
client_version&ClientVersionDocker API version to request.

​
Environment Variables

VariableDescription
DOCKER_HOSTURL of the Docker daemon, e.g. tcp://docker.example.com:2376.
DOCKER_CERT_PATHDirectory containing key.pem, cert.pem, and ca.pem.
DOCKER_CONFIGFallback directory for certificates when DOCKER_CERT_PATH is not set.
DOCKER_TLS_VERIFYWhen set (any non-empty value), connect_with_host will automatically use SSL for tcp:// addresses.

​
Feature Flags

Choose exactly one crypto provider. Enabling multiple providers will produce a compile error.

ssl (recommended)

Rustls backed by the ring cryptography library. This is the recommended option for most applications.
bollard = { version = "*", features = ["ssl"] }

aws-lc-rs (FIPS)

Rustls backed by aws-lc-rs. Use this when FIPS 140-3 compliance is required.
bollard = { version = "*", features = ["aws-lc-rs"] }

ssl_providerless

Rustls without a bundled crypto provider. You must call CryptoProvider::install_default() before creating any connection. Intended for advanced use cases that supply their own provider.
bollard = { version = "*", features = ["ssl_providerless"] }

webpki

Replaces OS-native root certificates with Mozilla’s WebPKI root store. Can be combined with any of the above provider features.
bollard = { version = "*", features = ["ssl", "webpki"] }
When using ssl_providerless you must install a CryptoProvider before calling any connection method, otherwise the library will panic:
rustls::crypto::ring::default_provider()
    .install_default()
    .expect("Failed to install ring crypto provider");

​
Complete Example

1

Generate TLS certificates (server side)

Use Docker’s built-in dockerd TLS generation or cert-manager to create your CA, server, and client certificate/key pairs. Place ca.pem, cert.pem, and key.pem in a known directory.
2

Add Bollard to Cargo.toml

[dependencies]
bollard = { version = "*", features = ["ssl"] }
tokio = { version = "1", features = ["full"] }
3

Connect using environment variables

export DOCKER_HOST=tcp://docker.example.com:2376
export DOCKER_CERT_PATH=/home/user/.docker/certs

use bollard::Docker;

#[tokio::main]
async fn main() {
    let docker = Docker::connect_with_ssl_defaults()
        .expect("Failed to connect with SSL");

    let version = docker.version().await.unwrap();
    println!("Connected securely to Docker {:?}", version.version);
}
4

Or supply certificate paths explicitly

use bollard::{API_DEFAULT_VERSION, Docker};
use std::path::Path;

#[tokio::main]
async fn main() {
    let docker = Docker::connect_with_ssl(
        "tcp://docker.example.com:2376",
        Path::new("/certs/key.pem"),
        Path::new("/certs/cert.pem"),
        Path::new("/certs/ca.pem"),
        120,
        API_DEFAULT_VERSION,
    )
    .expect("Failed to connect with SSL");

    let version = docker.version().await.unwrap();
    println!("Connected securely to Docker {:?}", version.version);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us