[Open Source] docker-tar: A small tool for directly downloading Docker tar images from DockerHub

Introduction#

docker-tar is a tool for pulling images from Docker repositories and automatically packaging them into Tar files.
Github: docker-tar

Features#

No Docker environment required: All functionalities are included in the binary, ready to use out of the box.
Multi-OS support: Provides relevant binaries that can be used on operating systems such as Linux, Windows, MacOS, Solaris, OpenBSD, etc. More supported operating systems can be found in the Release.
Multi-architecture support: Provides relevant binaries that support processor architectures such as amd64/x64, i386/x86, arm, arm64, mips, ppc64, etc. You can run this tool on a PC or even a router. More supported architectures can be found in the Release.
Image mode download: Tar files downloaded from image sites do not require tagging and can maintain consistency with the input image name.
Login download: Supports Docker repositories and image sites that require authentication.
Select image architecture: Supports selecting Docker images with multiple architectures for download.
Closer to Docker CLI download results: The tar image files downloaded by this tool are identical to those saved using docker pull and docker save.
Lab mode: Provides a lab mode to resolve DNS pollution and SNI blocking, helping you directly connect to certain inaccessible Docker repository sites.

Command Line Usage Instructions#

-action action
        pull: Pull the image tar file.
        list: List the processor architecture images that can be pulled.
  -arch architecture
        Specify the architecture of the image to pull (default is "amd64").
  -image name
        Information about the image to download.
        Defaults to latest if no version is specified.
        Uses DockerHub's Docker repository by default.
        nginx
        home-assistant/home-assistant:stable
        ghcr.io/home-assistant/home-assistant:stable
  -output filename
        The filename of the output tar image. If this option is not specified, a random filename will be generated.
   -username username
        Username is required when logging into Docker repositories/image sites.
  -password password
        Password is required when logging into Docker repositories/image sites.
  -mirror string
        Use an image site to download the image.
        This method will not modify the name specified by -image.
  -lab
        Lab mode, when enabled, will use default parameters to avoid DNS pollution and SNI blocking. It can be used in both pull and list modes.
        Generally, the default settings are sufficient.
  -dns-servers ip list
        This option takes effect when lab mode is enabled.
        The tool has a built-in list, and the input will override the built-in list.
        DNS server configuration options must be resolved IP addresses, separated by commas.
  -dns-timeout int
         This option takes effect when lab mode is enabled. 
         Configuration for the timeout of DNS hijacking filtering. (default value 2s)
  -network network
        This option takes effect when lab mode is enabled.
        ip4: Download images using only IPv4.
        ip6: Download images using only IPv6.
        ip: Download images using both IPv4 and IPv6 (default value "ip").

Usage Examples#

List Supported Architectures for Target Image#

Query the supported architectures for nginx.

docker-tar -action list -image nginx

Output:

Available Architecture:
amd64
armv5
armv7
arm64v8
386
mips64le
ppc64le
s390x

Download Image (Direct Download)#

This method requires configuring the HTTPS_PROXY environment variable.
Download the nginx image for the armv7 architecture.

docker-tar -action pull -image nginx -arch armv7 -output nginx.tar

Output:

Pulling from  nginx:latest
[1/7]3d83c6df5858: Downloading  100% |██████████████████████████████████████████████████| (24/24 MB, 1.9 MB/s)
[2/7]9260be83662e: Downloading  100% |██████████████████████████████████████████████████| (37/37 MB, 2.0 MB/s)
[3/7]3058d76256fc: Downloading  100% |██████████████████████████████████████████████████| (628/628 B, 986 kB/s)
[4/7]7888ef92f48d: Downloading  100% |██████████████████████████████████████████████████| (956/956 B, 994 kB/s)
[5/7]5c27d4148f08: Downloading  100% |██████████████████████████████████████████████████| (404/404 B, 400 kB/s)
[6/7]9c733a7e6553: Downloading  100% |█████████████████████████████████████████████████| (1.2/1.2 kB, 1.5 MB/s)
[7/7]931fb3c7333d: Downloading  100% |█████████████████████████████████████████████████| (1.4/1.4 kB, 2.5 MB/s)
Output File:  nginx.tar

Download Image (Through Image Site)#

Download the nginx image for the armv7 architecture.

docker-tar -action pull -image nginx -arch armv7 -output nginx.tar -mirror docker.xuanyuan.me

Output:

Pulling from  nginx:latest
[1/7]9c733a7e6553: Downloading  100% |█████████████████████████████████████████████████| (1.2/1.2 kB, 1.0 MB/s)
[2/7]931fb3c7333d: Downloading  100% |█████████████████████████████████████████████████| (1.4/1.4 kB, 2.8 MB/s)
[3/7]3d83c6df5858: Downloading  100% |███████████████████████████████████████████████████| (24/24 MB, 3.6 MB/s)
[4/7]9260be83662e: Downloading  100% |███████████████████████████████████████████████████| (37/37 MB, 5.2 MB/s)
[5/7]3058d76256fc: Downloading  100% |███████████████████████████████████████████████████| (628/628 B, 68 kB/s)
[6/7]7888ef92f48d: Downloading  100% |██████████████████████████████████████████████████| (956/956 B, 107 kB/s)
[7/7]5c27d4148f08: Downloading  100% |███████████████████████████████████████████████████| (404/404 B, 35 kB/s)
Output File:  nginx.tar

Download Image (Using Lab Mode for Direct Download)#

Download the nginx image for the armv7 architecture.

docker-tar -action pull -image nginx -arch armv7 -output nginx.tar -lab

Output:

Pulling from  nginx:latest
[1/7]3d83c6df5858: Downloading  100% |███████████████████████████████████████████████████| (24/24 MB, 6.9 MB/s)
[2/7]9260be83662e: Downloading  100% |████████████████████████████████████████████████████| (37/37 MB, 12 MB/s)
[3/7]3058d76256fc: Downloading  100% |██████████████████████████████████████████████████| (628/628 B, 489 kB/s)
[4/7]7888ef92f48d: Downloading  100% |██████████████████████████████████████████████████| (956/956 B, 671 kB/s)
[5/7]5c27d4148f08: Downloading  100% |██████████████████████████████████████████████████| (404/404 B, 353 kB/s)
[6/7]9c733a7e6553: Downloading  100% |█████████████████████████████████████████████████| (1.2/1.2 kB, 1.1 MB/s)
[7/7]931fb3c7333d: Downloading  100% |█████████████████████████████████████████████████| (1.4/1.4 kB, 2.8 MB/s)
Output File:  nginx.tar

TODO#

Multi-layer concurrent downloads
Support for segmented downloads, implementing segmented downloads for responses that support Range.
Compatibility with Docker API (ContentType).
Code structure and naming adjustments.
More user-friendly error output.

Compatibility Status (Currently Tested)#

DockerHub
DockerHub image sites
ghcr.io
ghcr.io image sites
quay.io (currently not adapted for application/vnd.docker.distribution.manifest.v1+prettyjws)
quay.io image sites (currently not adapted for application/vnd.docker.distribution.manifest.v1+prettyjws)

Some Possibly Useful Information#

Request Phase	Supported ContentType	Others
Get Token	Only processes response body, ignores type	Access Token: Bearer, Username and password (if needed): Basic
Get all architecture image manifest index	application/vnd.oci.image.index.v1+json	Response of non-this type will terminate directly
Get specified architecture image manifest	application/vnd.oci.image.manifest.v1+json	Compatible types are also acceptable
Get image configuration	application/vnd.oci.image.config.v1+json	Compatible types are also acceptable
Download Layer	application/vnd.oci.image.layer.v1.tar application/vnd.oci.image.layer.v1.tar+gzip application/vnd.oci.image.layer.v1.tar+zstd application/vnd.oci.image.layer.nondistributable.v1.tar application/vnd.oci.image.layer.nondistributable.v1.tar+gzip application/vnd.oci.image.layer.nondistributable.v1.tar+zstd application/vnd.docker.image.rootfs.diff.tar application/vnd.docker.image.rootfs.diff.tar.gzip application/vnd.docker.image.rootfs.diff.tar.zstd	Encrypted images are not supported