.\" Man page generated from reStructuredText.
.
.TH "CH-TUG" "1" "2020-08-22 18:37 Coordinated Universal Time" "0.18" "Charliecloud"
.SH NAME
ch-tug \- Pull and flatten image from repository to local filesystem
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-tug [OPTIONS] IMAGE_REF
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This script is experimental. Please report the bugs you find so we can fix
them!
.UNINDENT
.UNINDENT
.sp
Pull the image described by \fBIMAGE_REF\fP from a repository by HTTPS and
flatten it to a local filesystem. The resulting image directory can be used by
\fBch\-run(1)\fP or feed into other processing.
.sp
This script does a fair amount of validation and fixing of the layer tarballs
before flattening in order to support unprivileged use despite image problems
we frequently see in the wild. For example, device files are ignored, and file
and directory permissions are increased to a minimum of \fBrwx\-\-\-\-\-\-\fP and
\fBrw\-\-\-\-\-\-\-\fP respectively. Note, however, that symlinks pointing outside
the image are permitted, because they are not resolved until runtime within a
container.
.sp
Typically this script is not used directly. Most tasks instead use the
underlying code during image build with \fBch\-grow(1)\fP\&.
.sp
Other arguments:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fB\-h\fP, \fB\-\-help\fP
Print help and exit.
.TP
.B \fB\-\-dependencies\fP
Report any dependency problems and exit. If all is well, there is no
output and the exit code is zero; in case of problems, the exit code is
non\-zero.
.TP
.B \fB\-\-dl\-cache DIR\fP
Use \fBDIR\fP to store downloaded layers and metadata. If not specified
but environment variable \fBCH_GROW_STORAGE\fP is, then use
\fB$CH_GROW_STORAGE/dlcache\fP; the default is
\fB/var/tmp/$USER/ch\-grow/dlcache\fP\&.
.TP
.B \fB\-\-no\-cache\fP
Always download files, even if they already exist in \fB\-\-dl\-cache\fP\&.
.TP
.B \fB\-\-image\-subdir DIR\fP
Subdirectory of \fB\-\-unpack\-dir\fP to hold the flattened image. Can be
the empty string, in which case \fB\-\-unpack\-dir\fP is used directly. The
default is \fBIMAGE_REF\fP with slashes replaced by percent signs.
.TP
.B \fB\-\-parse\-ref\-only\fP
Parse \fBIMAGE_REF\fP, print a parse report, and exit successfully.
.TP
.B \fB\-\-unpack\-dir DIR\fP
Directory containing flattened images. If not specified but environment
variable \fBCH_GROW_STORAGE\fP is, then use
\fB$CH_GROW_STORAGE/img\fP; the default is
\fB/var/tmp/$USER/ch\-grow/img\fP\&.
.TP
.B \fB\-v\fP, \fB\-\-verbose\fP
Print extra chatter; can be repeated.
.TP
.B \fB\-\-version\fP
Print version number and exit.
.UNINDENT
.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
Download the classic Docker “hello\-world” image and flatten it into
\fB/var/tmp/$USER/ch\-grow/img/hello\-world\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-tug hello\-world
pulling image: hello\-world
manifest: downloading
layer 1/1: 1b930d0: downloading
layer 1/1: 1b930d0: listing
validating tarball members
resolving whiteouts
flattening image
creating new image: /var/tmp/charlie/ch\-grow/img/hello\-world
layer 1/1: 1b930d0: extracting
done
$ ls /var/tmp/$USER/ch\-grow/img/hello\-world
hello
$ ls /var/tmp/$USER/ch\-grow/dlcache
1b930d010525941c1d56ec53b97bd057a67ae1865eebf042686d2a2d18271ced.tar.gz
hello\-world.manifest.json
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Download the image “charliecloud/whiteout:2020\-01\-10” and flatten it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-tug charliecloud/whiteout:2020\-01\-10
pulling image: charliecloud/whiteout:2020\-01\-10
manifest: downloading
layer 1/86: e7c96db: downloading
layer 2/86: 4816f76: downloading
[...]
layer 85/86: 59b7abe: extracting
layer 86/86: e756ca6: extracting
done
$ ls /var/tmp/$USER/ch\-grow/img
charliecloud%whiteout:2020\-01\-10
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Download the “hello\-world” image and flatten it into \fB/tmp/foo\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-tug \-\-unpack\-dir=/tmp \-\-image\-subdir=foo hello\-world
[...]
$ ls /tmp/foo
hello
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Same as above:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-tug \-\-unpack\-dir=/tmp/foo \-\-image\-subdir=\(aq\(aq hello\-world
[...]
$ ls /tmp/foo
hello
.ft P
.fi
.UNINDENT
.UNINDENT
.SH REPORTING BUGS
.sp
If Charliecloud was obtained from your Linux distribution, use your
distribution’s bug reporting procedures.
.sp
Otherwise, report bugs to: <\fI\%https://github.com/hpc/charliecloud/issues\fP>
.SH SEE ALSO
.sp
charliecloud(1)
.sp
Full documentation at: <\fI\%https://hpc.github.io/charliecloud\fP>
.SH COPYRIGHT
2014–2020, Triad National Security, LLC
.\" Generated by docutils manpage writer.
.